Sponsees

List

Retrieve a list of matching sponsees.

Request

url: /admin/api/v2/sponsees
method: GET
filters: (how?)
- id: optional, string, exact match
- first_name: optional, string, partial match
- last_name: optional, string, partial match
- reference_number: optional, string, partial match
sorting : (how?)
- birth_date
- first_name
- last_name
- reference_number
- is_sponsored
- is_enabled

Response

sponsees.json

{
  "data": [
    {
      "id": "84E3RRDW",
      "reference_number": "K01-CFH-154",
      "first_name": "Maurenersz",
      "last_name": "Akiru",
      "gender": "F",
      "birth_date": "2013-01-01",
      "age": 11,
      "enrollment_date": "2019-01-15",
      "longitude": null,
      "latitude": null,
      "biography": "I have six siblings and we were left behind with our elderly grandmother.  She was so overwhelmed with caring for us and did not have the means to do it well.  Four of my older siblings, Peris, Joseph, Ignatious and Lucy were able to go to Maai Mahiu Children’s Home soon after mom died.  I was only 3 years old so I went to Mogogosiek Baby Home and was cared for there until I was old enough to move to the children's home with my siblings.",
      "private_notes": null,
      "sponsored_status": "Sponsored",
      "is_enabled": false,
      "payment_option_group": "Standard",
      "sponsor_count": 0,
      "image_url": "https://cdn.givecloud.co/s/files/2-dev/0000/0001/sponsorships/2j92jwimthoeee3gb6qjvclq8ws2ior-home-page-4_300x_cropped_top.png",
      "url": "https://microsoft.givecloud.test/sponsorship/198",
      "custom_fields": [
        {
          "name": "Classroom",
          "slug": "classroom",
          "value": "Grade 1",
          "item": null,
          "is_simple": 1,
          "is_private": false
        }
      ],
      "created_at": "2022-11-18T00:00:00+00:00",
      "updated_at": "2024-01-30T00:00:00+00:00"
      }
    }
  ],
  "links": {
    "first": "https://your-domain.givecloud.co/admin/api/v2/sponsees?page=1",
    "last": "https://your-domain.givecloud.co/admin/api/v2/sponsees?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://your-domain.givecloud.co/admin/api/v2/sponsees?page=1",
        "label": 1,
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://your-domain.givecloud.co/admin/api/v2/sponsees",
    "per_page": 15,
    "to": 3,
    "total": 3
  }
}

Get

Retrieve the first matching sponsee. This returns a 404 if there is no matching sponsee found.

Request

url: /admin/api/v2/sponsees/{id}
method: GET
parameters:
- id: required, string, exact match

Response

sponsee.json

{
  "data": {
    "id": "84E3RRDW",
    "reference_number": "K01-CFH-154",
    "first_name": "Maurenersz",
    "last_name": "Akiru",
    "gender": "F",
    "birth_date": "2013-01-01",
    "age": 11,
    "enrollment_date": "2019-01-15",
    "longitude": null,
    "latitude": null,
    "biography": "I have six siblings and we were left behind with our elderly grandmother.  She was so overwhelmed with caring for us and did not have the means to do it well.  Four of my older siblings, Peris, Joseph, Ignatious and Lucy were able to go to Maai Mahiu Children’s Home soon after mom died.  I was only 3 years old so I went to Mogogosiek Baby Home and was cared for there until I was old enough to move to the children's home with my siblings.",
    "private_notes": null,
    "sponsored_status": "Sponsored",
    "is_enabled": false,
    "payment_option_group": "Standard",
    "sponsor_count": 0,
    "image_url": "https://cdn.givecloud.co/s/files/2-dev/0000/0001/sponsorships/2j92jwimthoeee3gb6qjvclq8ws2ior-home-page-4_300x_cropped_top.png",
    "url": "https://microsoft.givecloud.test/sponsorship/198",
    "custom_fields": [
        {
            "name": "Classroom",
            "slug": "classroom",
            "value": "Grade 1",
            "item": null,
            "is_simple": 1,
            "is_private": false
        }
    ],
    "created_at": "2022-11-18T00:00:00+00:00",
    "updated_at": "2024-01-30T00:00:00+00:00"
  }
}

POST

Creates a new Sponsee. All attributes are optional unless specified.

Request

url: /admin/api/v2/sponsees
method: POST
parameters:
- reference_number: required, unique, string, max: 45 characters
- first_name: required, string
- sponsored_status: required, integer, must be 0, 1 or 2 where 0 is not sponsored, 1 is sponsored and 2 is automatically marked as sponsored when minimum number of sponsors is reached.
- enrollment_date: required, date, format YYYY-mm-dd
- last_name: string
- birth_date: date, format YYYY-mm-dd
- is_enabled: boolean
- gender: string, value of M or F
- payment_option_group: string, must be one of your payment option group
- custom_fields: array
  - key: required when specifying a custom field, snake_case version of your custom field name
  - value: required when specifying a custom field
- image_url: url, must be publicly available

payload.json

  {
  "reference_number": "K01-CFH-154",
  "first_name": "Maurenersz",
  "last_name": "Akiru",
  "gender": "F",
  "birth_date": "2013-01-01",
  "enrollment_date": "2019-01-15",
  "longitude": "45.5019",
  "latitude": "73.5674",
  "biography": "I have six siblings and we were left behind with our elderly grandmother.  Four of my older siblings, Peris, Joseph, Ignatious and Lucy were able to go to Maai Mahiu Children’s Home soon after mom died.  I was only 3 years old so I went to Mogogosiek Baby Home and was cared for there until I was old enough to move to the children's home with my siblings.",
  "private_notes": "",
  "sponsored_status": 2,
  "is_enabled": true,
  "payment_option_group": "Standard",
  "image_url": "https://example.com/publicly-available/images/my-image.jpg",
  "custom_fields" : {
      "classroom": "Grade 1",
      "hobby": "Arts & Crafts"
  }
}

Response

sponsee.json

{
  "data": {
    "id": "84E3RRDW",
    "reference_number": "K01-CFH-154",
    "first_name": "Maurenersz",
    "last_name": "Akiru",
    "gender": "F",
    "birth_date": "2013-01-01",
    "age": 11,
    "enrollment_date": "2019-01-15",
    "longitude": null,
    "latitude": null,
    "biography": "I have six siblings and we were left behind with our elderly grandmother.  Four of my older siblings, Peris, Joseph, Ignatious and Lucy were able to go to Maai Mahiu Children’s Home soon after mom died.  I was only 3 years old so I went to Mogogosiek Baby Home and was cared for there until I was old enough to move to the children's home with my siblings.",
    "private_notes": null,
    "sponsored_status": "Automatically Sponsored (Not Sponsored)",
    "is_enabled": false,
    "payment_option_group": "Standard",
    "sponsor_count": 0,
    "image_url": "https://cdn.givecloud.co/s/files/2-dev/0000/0001/sponsorships/2j92jwimthoeee3gb6qjvclq8ws2ior-home-page-4_300x_cropped_top.png",
    "url": "https://microsoft.givecloud.test/sponsorship/198",
    "custom_fields": [
        {
            "name": "Classroom",
            "slug": "classroom",
            "value": "Grade 1",
            "item": null,
            "is_simple": 1,
            "is_private": false
        }, {
            "name": "Hobby",
            "slug": "Hobby",
            "value": "Arts & Crafts",
            "item": null,
            "is_simple": 1,
            "is_private": false
        }
    ],
    "created_at": "2022-11-18T00:00:00+00:00",
    "updated_at": "2024-01-30T00:00:00+00:00"
  }
}

PUT / PATCH

Updates an existing Sponsee.

Note on custom_fields When using PATCH, custom fields will be updated while when using PUT all custom_fields will be replaced with the supplied payload.

Request

url: /admin/api/v2/sponsees/{id}
method: PUT|PATCH
parameters:
- reference_number: unique, string, max: 45 characters
- first_name: string
- sponsored_status: integer, must be 0, 1 or 2 where 0 is not sponsored, 1 is sponsored and 2 is automatically marked as sponsored when minimum number of sponsors is reached.
- enrollment_date: date, format YYYY-mm-dd
- last_name: string
- birth_date: date, format YYYY-mm-dd
- is_enabled: boolean
- gender: string, value of M or F
- payment_option_group: string, must be one of your payment option group
- custom_fields: array
  - key: required, snake_case version of your custom field name
  - value: required
- image_url: url, must be publicly available

  {
  "reference_number": "K01-CFH-154",
  "first_name": "Maurenersz",
  "last_name": "Akiru",
  "gender": "F",
  "birth_date": "2013-01-01",
  "enrollment_date": "2019-01-15",
  "longitude": "45.5019",
  "latitude": "73.5674",
  "biography": "I have six siblings and we were left behind with our elderly grandmother.  Four of my older siblings, Peris, Joseph, Ignatious and Lucy were able to go to Maai Mahiu Children’s Home soon after mom died.  I was only 3 years old so I went to Mogogosiek Baby Home and was cared for there until I was old enough to move to the children's home with my siblings.",
  "private_notes": "",
  "sponsored_status": 2,
  "is_enabled": true,
  "payment_option_group": "Standard",
  "image_url": "https://example.com/publicly-available/images/my-image.jpg",
  "custom_fields" : { 
    "classroom": "Grade 2"
  }
}

Response

sponsee.json

{
  "data": {
    "id": "84E3RRDW",
    "reference_number": "K01-CFH-154",
    "first_name": "Maurenersz",
    "last_name": "Akiru",
    "gender": "F",
    "birth_date": "2013-01-01",
    "age": 11,
    "enrollment_date": "2019-01-15",
    "longitude": null,
    "latitude": null,
    "biography": "I have six siblings and we were left behind with our elderly grandmother.  Four of my older siblings, Peris, Joseph, Ignatious and Lucy were able to go to Maai Mahiu Children’s Home soon after mom died.  I was only 3 years old so I went to Mogogosiek Baby Home and was cared for there until I was old enough to move to the children's home with my siblings.",
    "private_notes": null,
    "sponsored_status": "Automatically Sponsored (Not Sponsored)",
    "is_enabled": false,
    "payment_option_group": "Standard",
    "sponsor_count": 0,
    "image_url": "https://cdn.givecloud.co/s/files/2-dev/0000/0001/sponsorships/2j92jwimthoeee3gb6qjvclq8ws2ior-home-page-4_300x_cropped_top.png",
    "url": "https://microsoft.givecloud.test/sponsorship/198",
    "custom_fields": [
        {
            "name": "Classroom",
            "slug": "classroom",
            "value": "Grade 2",
            "item": null,
            "is_simple": 1,
            "is_private": false
        }
    ],
    "created_at": "2022-11-18T00:00:00+00:00",
    "updated_at": "2024-01-30T00:00:00+00:00"
  }
}

DELETE

Deletes an existing Sponsee.

Request

url: /admin/api/v2/sponsees/{id}
method: DELETE

Reponse

Will return 204 No Content on success.

Sponsees

Actions available on sponsees (Sponsorship).