Persons

get

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.

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

owningOrganizationUuidsstring[]Optional

Filter persons by owning organization uuids (version 4). If not supplied, the owning organization scope of the service account, if applicable, will be used.

Example: ["a3c2a57e-2797-4159-8700-8ad55bf8150e"]

createdAfterstring · date-timeOptional

ISO8601 compatible datetime string

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

ibanstringOptional

Filter persons by IBAN

Example: NL00INGB0000000000

beforestringOptional

Person cursor to fetch results before

Example: a3c2a57e-2797-4159-8700-8ad55bf8150e

lastnumberOptional

The amount of results to fetch before the 'before' cursor

Example: 10

afterstringOptional

Person cursor to fetch results after

Example: a3c2a57e-2797-4159-8700-8ad55bf8150e

firstnumberOptional

The amount of results to fetch after the 'after' cursor

Example: 10

Responses

200Success

application/json

400

Bad request. Response body shows what the problem is.

401

Service account not properly authenticated

403

Service account forbids executing this action

default

application/json

get

/api/v1/persons

HTTPcURLJavaScriptPython

GET /api/v1/persons HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "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": "[email protected]",
        "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"
        },
        "qualityResult": {
          "score": 30,
          "maxScore": 40,
          "percentage": 100,
          "createdAt": "2026-03-19T00:43:44.645Z",
          "gateResults": [
            {
              "identifier": "addressIsValid",
              "category": "emailQuality",
              "score": 8,
              "maxScore": 10,
              "percentage": 80,
              "explanation": "ibanIsInvalid",
              "metadata": {}
            }
          ]
        }
      },
      "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

post

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.

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

uuidstring · uuidOptional

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

owningOrganizationUuidstring · uuidRequired

UUID (v4) of the organization that owns this person

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

recruitingOrganizationUuidstring · uuidRequired

UUID (v4) of the organization that recruited this person

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

academicTitlestringOptionalExample: Dr.

dateOfBirthstringOptional

Date of birth, formatted as ISO8601 date string

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

socialSecurityNumberstringOptional

Social security number as string without any separators.

Example: 12345678901

genderstring · enumOptionalExample: malePossible values:

phoneNumberstringOptional

International phone number

Example: [phone]

mobilePhoneNumberstringOptional

International phone number

Example: [phone]

emailstringOptional

valid email address

Example: [email protected]

languagestringOptional

ISO6391 language code

Example: nl

ibanstringOptional

Valid iBAN

Example: NL13ABNA6371362585

Responses

201

Person was created

application/json

400

Bad request. Response body shows what the problem is.

401

Service account not properly authenticated

403

Service account forbids executing this action

409

Person already exists

post

/api/v1/persons

HTTPcURLJavaScriptPython

POST /api/v1/persons HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 798

{
  "uuid": "82b431f0-f401-4afd-b6db-9d1d751232d9",
  "owningOrganizationUuid": "82b431f0-f401-4afd-b6db-9d1d751232d9",
  "recruitingOrganizationUuid": "82b431f0-f401-4afd-b6db-9d1d751232d9",
  "academicTitle": "Dr.",
  "name": {
    "initials": "P.",
    "firstName": "Peter",
    "lastNamePrefix": "van der",
    "lastName": "Plas"
  },
  "dateOfBirth": "1978-05-01T00:00:00.000Z",
  "socialSecurityNumber": "12345678901",
  "gender": "male",
  "phoneNumber": "[phone]",
  "mobilePhoneNumber": "[phone]",
  "email": "[email protected]",
  "address": {
    "street": "Kerkstraat",
    "houseNumber": "1",
    "houseNumberExtension": "a",
    "zipCode": "3031LS",
    "city": "Arnhem",
    "country": "NL"
  },
  "language": "nl",
  "iban": "NL13ABNA6371362585",
  "optIns": {
    "email": true,
    "mail": true,
    "phone": true,
    "sms": true
  },
  "mandate": {
    "id": "skd-39-ss9dskdk33k2hjsdkfj",
    "createdAt": "2019-01-01T21:00:21+00:00Z"
  }
}

{
  "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": "[email protected]",
  "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"
  },
  "qualityResult": {
    "score": 30,
    "maxScore": 40,
    "percentage": 100,
    "createdAt": "2026-03-19T00:43:44.645Z",
    "gateResults": [
      {
        "identifier": "addressIsValid",
        "category": "emailQuality",
        "score": 8,
        "maxScore": 10,
        "percentage": 80,
        "explanation": "ibanIsInvalid",
        "metadata": {}
      }
    ]
  }
}

get

Fetches the details of a single person.

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

uuidstringRequired

Responses

200Success

application/json

uuidstring · uuidRequired

UUID (v4)

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

personUuidstring · uuidRequiredDeprecated

UUID (v4). Deprecated: use the 'uuid' property instead.

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

academicTitlestring · nullableRequiredExample: Dr.

initialsstring · nullableRequiredExample: B.

firstNamestring · nullableRequiredExample: Beth

lastNamePrefixstring · nullableRequired

lastNamestring · nullableRequiredExample: Cormier

dateOfBirthstring · nullableRequired

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

Example: 1978-05-01

socialSecurityNumberstring · nullableOptional

Social security number as string without any separators.

Example: 12345678901

ibanstring · nullableRequiredExample: NL13ABNA6371362585

phoneNumberstring · nullableRequiredExample: [phone]

mobilePhoneNumberstring · nullableRequiredExample: [phone]

emailstring · nullableRequiredExample: [email protected]

genderstring · enum · nullableRequiredExample: malePossible values:

optInEmailboolean · nullableRequiredExample: true

optInPhoneboolean · nullableRequiredExample: false

optInMailboolean · nullableRequired

optInSmsboolean · nullableRequired

languagestring · nullableRequired

ISO-639-1 language code

Example: nl

createdAtstring · date-timeRequired

ISO8601 compatible datetime string

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

400

Bad request. Response body shows what the problem is.

401

Service account not properly authenticated

403

Service account forbids executing this action

default

application/json

get

/api/v1/persons/{uuid}

HTTPcURLJavaScriptPython

GET /api/v1/persons/{uuid} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "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": "[email protected]",
  "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"
  },
  "qualityResult": {
    "score": 30,
    "maxScore": 40,
    "percentage": 100,
    "createdAt": "2026-03-19T00:43:44.645Z",
    "gateResults": [
      {
        "identifier": "addressIsValid",
        "category": "emailQuality",
        "score": 8,
        "maxScore": 10,
        "percentage": 80,
        "explanation": "ibanIsInvalid",
        "metadata": {}
      }
    ]
  }
}

Update a person's data

put

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.

Authorizations

bearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

uuidstringRequired

Body

application/json

academicTitlestring · nullableOptionalExample: Dr.

dateOfBirthstring · nullableOptional

Date of birth, formatted as ISO8601 date string

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

socialSecurityNumberstring · nullableOptional

Social security number as string without any separators.

Example: 12345678901

genderstring · enum · nullableOptionalExample: malePossible values:

phoneNumberstring · nullableOptional

International phone number

Example: [phone]

mobilePhoneNumberstring · nullableOptional

International phone number

Example: [phone]

emailstring · nullableOptional

valid email address

Example: [email protected]

languagestring · nullableOptional

ISO6391 language code

Example: nl

ibanstring · nullableOptional

Valid iBAN

Example: NL13ABNA6371362585

Responses

200

Person was updated

application/json

uuidstring · uuidRequired

UUID (v4)

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

personUuidstring · uuidRequiredDeprecated

UUID (v4). Deprecated: use the 'uuid' property instead.

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

academicTitlestring · nullableRequiredExample: Dr.

initialsstring · nullableRequiredExample: B.

firstNamestring · nullableRequiredExample: Beth

lastNamePrefixstring · nullableRequired

lastNamestring · nullableRequiredExample: Cormier

dateOfBirthstring · nullableRequired

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

Example: 1978-05-01

socialSecurityNumberstring · nullableOptional

Social security number as string without any separators.

Example: 12345678901

ibanstring · nullableRequiredExample: NL13ABNA6371362585

phoneNumberstring · nullableRequiredExample: [phone]

mobilePhoneNumberstring · nullableRequiredExample: [phone]

emailstring · nullableRequiredExample: [email protected]

genderstring · enum · nullableRequiredExample: malePossible values:

optInEmailboolean · nullableRequiredExample: true

optInPhoneboolean · nullableRequiredExample: false

optInMailboolean · nullableRequired

optInSmsboolean · nullableRequired

languagestring · nullableRequired

ISO-639-1 language code

Example: nl

createdAtstring · date-timeRequired

ISO8601 compatible datetime string

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

400

Bad request. Response body shows what the problem is.

401

Service account not properly authenticated

403

Service account forbids executing this action

404

Person with this Uuid not found

put

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

HTTPcURLJavaScriptPython

PUT /api/v1/persons/{uuid}/actions/update HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 620

{
  "academicTitle": "Dr.",
  "name": {
    "initials": "P.",
    "firstName": "Peter",
    "lastNamePrefix": "van der",
    "lastName": "Plas"
  },
  "dateOfBirth": "1978-05-01T00:00:00.000Z",
  "socialSecurityNumber": "12345678901",
  "gender": "male",
  "phoneNumber": "[phone]",
  "mobilePhoneNumber": "[phone]",
  "email": "[email protected]",
  "address": {
    "street": "Kerkstraat",
    "houseNumber": "1",
    "houseNumberExtension": "a",
    "zipCode": "3031LS",
    "city": "Arnhem",
    "country": "NL"
  },
  "language": "nl",
  "iban": "NL13ABNA6371362585",
  "optIns": {
    "email": true,
    "mail": true,
    "phone": true,
    "sms": true
  },
  "mandate": {
    "id": "skd-39-ss9dskdk33k2hjsdkfj",
    "createdAt": "2019-01-01T21:00:21+00:00Z"
  }
}

{
  "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": "[email protected]",
  "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"
  },
  "qualityResult": {
    "score": 30,
    "maxScore": 40,
    "percentage": 100,
    "createdAt": "2026-03-19T00:43:44.645Z",
    "gateResults": [
      {
        "identifier": "addressIsValid",
        "category": "emailQuality",
        "score": 8,
        "maxScore": 10,
        "percentage": 80,
        "explanation": "ibanIsInvalid",
        "metadata": {}
      }
    ]
  }
}