Sponsees

Actions available on sponsees (Sponsorship).


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": "« Previous",
        "active": false
      },
      {
        "url": "https://your-domain.givecloud.co/admin/api/v2/sponsees?page=1",
        "label": 1,
        "active": true
      },
      {
        "url": null,
        "label": "Next »",
        "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.