Persons

The persons you are able to fetch might be filtered, based upon your service account's organization scope, if applicable. Besides those filters, you can apply additional filters by supplying query parameters to the url.

The collection you are paginating is sorted by creation datetime, descending. This means that the first page contains the most recently created persons.

GET/api/v1/persons

Authorization

bearer

Query parameters

Response

200400401403default

Body

application/json

edges*array of PersonEdgeDto (object)

pageInfo*PageInfo (object)

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/persons', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer jwt"
    },
});
const data = await response.json();

Response

200default

{
  "edges": [
    {
      "node": {
        "uuid": "82b431f0-f401-4afd-b6db-9d1d751232d9",
        "academicTitle": "Dr.",
        "initials": "B.",
        "firstName": "Beth",
        "lastNamePrefix": null,
        "lastName": "Cormier",
        "dateOfBirth": "1978-05-01",
        "socialSecurityNumber": "12345678901",
        "iban": "NL13ABNA6371362585",
        "address": {
          "street": "Claudius Prinsenlaan",
          "houseNumber": "12",
          "houseNumberExtension": null,
          "zipCode": "4811DK",
          "city": "Breda",
          "country": "NL"
        },
        "phoneNumber": "[phone]",
        "mobilePhoneNumber": "[phone]",
        "email": "[e-mail]",
        "gender": "male",
        "optInEmail": true,
        "optInPhone": false,
        "optInMail": null,
        "optInSms": null,
        "language": "nl",
        "mandate": {
          "createdAt": "2017-07-21T17:32:28Z"
        },
        "createdAt": "2017-07-21T17:32:28Z",
        "owningOrganization": {
          "uuid": "2fcc7d41-a72a-4f38-94ff-8a0484b8fc4c",
          "name": "Good Cause Charity"
        }
      },
      "cursor": "48094b0e-15b3-430f-ab5a-16ecf12b9171"
    }
  ],
  "pageInfo": {
    "startCursor": "48094b0e-15b3-430f-ab5a-16ecf12b9171",
    "endCursor": "494d74df-6fbc-46a3-811e-1c17230340a1",
    "hasPreviousPage": true,
    "hasNextPage": false
  }
}

Create a person

This endpoint allows you to create a person, if your service account allows you to.

The 'owningOrganizationUuid' and 'recruitingOrganizationUuid' might also be bound to limitations depending on your service account's organization scope and permissions.

We advice you to provide your own 'uuid' value, as you can use this as a mechanism to ensure the person is only created once. When accidentally the person is posted twice, the uuid will ensure it is only saved the first time, and a 409 CONFLICT status will be returned when posted a second time with the same uuid. When you don't supply a uuid, the system will generate one for you, which will be returned in the response body.

This endpoint will return the person created with the data in your request body.

POST/api/v1/persons

Authorization

bearer

Body

application/json

uuidstring (uuid)

UUID (v4). The person's globally unique identifier in the system. If not provided, a new UUID will be generated.

Example: "82b431f0-f401-4afd-b6db-9d1d751232d9"

owningOrganizationUuid*string (uuid)

UUID (v4) of the organization that owns this person

Example: "82b431f0-f401-4afd-b6db-9d1d751232d9"

recruitingOrganizationUuid*string (uuid)

UUID (v4) of the organization that recruited this person

Example: "82b431f0-f401-4afd-b6db-9d1d751232d9"

academicTitlestring

Example: "Dr."

nameNameInput (object)

dateOfBirthstring

Date of birth, formatted as ISO8601 date string

Example: "1978-05-01T00:00:00.000Z"

socialSecurityNumberstring

Social security number as string without any separators.

Example: "12345678901"

genderenum

Example: "male"

malefemaleother

phoneNumberstring

International phone number

Example: "[phone]"

mobilePhoneNumberstring

International phone number

Example: "[phone]"

emailstring

valid email address

Example: "[e-mail]"

addressAddressInput (object)

languagestring

ISO6391 language code

Example: "nl"

ibanstring

Valid iBAN

Example: "NL13ABNA6371362585"

optInsOptInsInput (object)

mandateMandateInput (object)

Response

201400401403409

Person was created

Body

application/json

uuid*string (uuid)

UUID (v4)

Example: "82b431f0-f401-4afd-b6db-9d1d751232d9"

academicTitle*nullable string

Example: "Dr."

initials*nullable string

Example: "B."

firstName*nullable string

Example: "Beth"

lastNamePrefix*nullable string

lastName*nullable string

Example: "Cormier"

dateOfBirth*nullable string

Local date of birth for user, formatted as YYYY-MM-DD

Example: "1978-05-01"

socialSecurityNumbernullable string

Social security number as string without any separators.

Example: "12345678901"

iban*nullable string

Example: "NL13ABNA6371362585"

address*nullable all of

phoneNumber*nullable string

Example: "[phone]"

mobilePhoneNumber*nullable string

Example: "[phone]"

email*nullable string

Example: "[e-mail]"

gender*nullable enum

Example: "male"

malefemaleother

optInEmail*nullable boolean

Example: true

optInPhone*nullable boolean

Example: false

optInMail*nullable boolean

optInSms*nullable boolean

language*nullable string

ISO-639-1 language code

Example: "nl"

mandate*nullable all of

createdAt*string (date-time)

ISO8601 compatible datetime string

Example: "2017-07-21T17:32:28Z"

owningOrganization*all of

Organization recruited for

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/persons', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer jwt",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "owningOrganizationUuid": "82b431f0-f401-4afd-b6db-9d1d751232d9",
      "recruitingOrganizationUuid": "82b431f0-f401-4afd-b6db-9d1d751232d9"
    }),
});
const data = await response.json();

Response

201

{
  "uuid": "82b431f0-f401-4afd-b6db-9d1d751232d9",
  "academicTitle": "Dr.",
  "initials": "B.",
  "firstName": "Beth",
  "lastNamePrefix": null,
  "lastName": "Cormier",
  "dateOfBirth": "1978-05-01",
  "socialSecurityNumber": "12345678901",
  "iban": "NL13ABNA6371362585",
  "address": {
    "street": "Claudius Prinsenlaan",
    "houseNumber": "12",
    "houseNumberExtension": null,
    "zipCode": "4811DK",
    "city": "Breda",
    "country": "NL"
  },
  "phoneNumber": "[phone]",
  "mobilePhoneNumber": "[phone]",
  "email": "[e-mail]",
  "gender": "male",
  "optInEmail": true,
  "optInPhone": false,
  "optInMail": null,
  "optInSms": null,
  "language": "nl",
  "mandate": {
    "createdAt": "2017-07-21T17:32:28Z"
  },
  "createdAt": "2017-07-21T17:32:28Z",
  "owningOrganization": {
    "uuid": "2fcc7d41-a72a-4f38-94ff-8a0484b8fc4c",
    "name": "Good Cause Charity"
  }
}

Update a person's data

This endpoint allows you to update a person.

You only have to provide the fields you want to update. Any fields that you set to null, will be cleared. Any fields that you don't supply will not be updated.

Whether you are allowed to execute this request, depends on your service account's permissions and organization scope.

This endpoint will return the updated person.

PUT/api/v1/persons/{uuid}/actions/update

Authorization

bearer

Path parameters

uuid*string

Body

application/json

academicTitlenullable string

Example: "Dr."

namenullable all of

dateOfBirthnullable string

Date of birth, formatted as ISO8601 date string

Example: "1978-05-01T00:00:00.000Z"

socialSecurityNumbernullable string

Social security number as string without any separators.

Example: "12345678901"

gendernullable enum

Example: "male"

malefemaleother

phoneNumbernullable string

International phone number

Example: "[phone]"

mobilePhoneNumbernullable string

International phone number

Example: "[phone]"

emailnullable string

valid email address

Example: "[e-mail]"

addressnullable all of

languagenullable string

ISO6391 language code

Example: "nl"

ibannullable string

Valid iBAN

Example: "NL13ABNA6371362585"

optInsall of

mandatenullable all of

Response

200400401403404

Person was updated

Body

application/json

uuid*string (uuid)

UUID (v4)

Example: "82b431f0-f401-4afd-b6db-9d1d751232d9"

academicTitle*nullable string

Example: "Dr."

initials*nullable string

Example: "B."

firstName*nullable string

Example: "Beth"

lastNamePrefix*nullable string

lastName*nullable string

Example: "Cormier"

dateOfBirth*nullable string

Local date of birth for user, formatted as YYYY-MM-DD

Example: "1978-05-01"

socialSecurityNumbernullable string

Social security number as string without any separators.

Example: "12345678901"

iban*nullable string

Example: "NL13ABNA6371362585"

address*nullable all of

phoneNumber*nullable string

Example: "[phone]"

mobilePhoneNumber*nullable string

Example: "[phone]"

email*nullable string

Example: "[e-mail]"

gender*nullable enum

Example: "male"

malefemaleother

optInEmail*nullable boolean

Example: true

optInPhone*nullable boolean

Example: false

optInMail*nullable boolean

optInSms*nullable boolean

language*nullable string

ISO-639-1 language code

Example: "nl"

mandate*nullable all of

createdAt*string (date-time)

ISO8601 compatible datetime string

Example: "2017-07-21T17:32:28Z"

owningOrganization*all of

Organization recruited for

Request

JavaScriptCurlPython

const response = await fetch('/api/v1/persons/{uuid}/actions/update', {
    method: 'PUT',
    headers: {
      "Authorization": "Bearer jwt",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "uuid": "82b431f0-f401-4afd-b6db-9d1d751232d9",
  "academicTitle": "Dr.",
  "initials": "B.",
  "firstName": "Beth",
  "lastNamePrefix": null,
  "lastName": "Cormier",
  "dateOfBirth": "1978-05-01",
  "socialSecurityNumber": "12345678901",
  "iban": "NL13ABNA6371362585",
  "address": {
    "street": "Claudius Prinsenlaan",
    "houseNumber": "12",
    "houseNumberExtension": null,
    "zipCode": "4811DK",
    "city": "Breda",
    "country": "NL"
  },
  "phoneNumber": "[phone]",
  "mobilePhoneNumber": "[phone]",
  "email": "[e-mail]",
  "gender": "male",
  "optInEmail": true,
  "optInPhone": false,
  "optInMail": null,
  "optInSms": null,
  "language": "nl",
  "mandate": {
    "createdAt": "2017-07-21T17:32:28Z"
  },
  "createdAt": "2017-07-21T17:32:28Z",
  "owningOrganization": {
    "uuid": "2fcc7d41-a72a-4f38-94ff-8a0484b8fc4c",
    "name": "Good Cause Charity"
  }
}