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

Authorizations

Query parameters

owningOrganizationUuidsstring[]

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-time

ISO8601 compatible datetime string

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

ibanstring

Filter persons by IBAN

Example: NL00INGB0000000000

beforestring

Person cursor to fetch results before

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

lastnumber

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

Example: 10

afterstring

Person cursor to fetch results after

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

firstnumber

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

Example: 10

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/api/v1/persons' \
  --header 'Authorization: Bearer jwt'

200

400

401

403

default

200

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

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

Authorizations

Body

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

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

academicTitlestring

Example: Dr.

nameobject

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

phoneNumberstring

International phone number

Example: [phone]

mobilePhoneNumberstring

International phone number

Example: [phone]

emailstring

valid email address

Example: [e-mail]

addressobject

languagestring

ISO6391 language code

Example: nl

ibanstring

Valid iBAN

Example: NL13ABNA6371362585

optInsobject

mandateobject

genderstring · enum

Example: male

Options: male, female, other

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/api/v1/persons' \
  --header 'Authorization: Bearer jwt' \
  --header 'Content-Type: application/json' \
  --data '{"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","phoneNumber":"[phone]","mobilePhoneNumber":"[phone]","email":"[e-mail]","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"},"gender":"male"}'

201

400

401

403

409

201

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

Person was created

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

Authorizations

Path parameters

uuidstringrequired

Body

academicTitlestring | nullable

Example: Dr.

dateOfBirthstring | nullable

Date of birth, formatted as ISO8601 date string

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

socialSecurityNumberstring | nullable

Social security number as string without any separators.

Example: 12345678901

phoneNumberstring | nullable

International phone number

Example: [phone]

mobilePhoneNumberstring | nullable

International phone number

Example: [phone]

emailstring | nullable

valid email address

Example: [e-mail]

languagestring | nullable

ISO6391 language code

Example: nl

ibanstring | nullable

Valid iBAN

Example: NL13ABNA6371362585

genderstring · enum | nullable

Example: male

Options: male, female, other

nameall of | nullable

addressall of | nullable

optInsall of

mandateall of | nullable

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url '/api/v1/persons/{uuid}/actions/update' \
  --header 'Authorization: Bearer jwt' \
  --header 'Content-Type: application/json' \
  --data '{"academicTitle":"Dr.","dateOfBirth":"1978-05-01T00:00:00.000Z","socialSecurityNumber":"12345678901","phoneNumber":"[phone]","mobilePhoneNumber":"[phone]","email":"[e-mail]","language":"nl","iban":"NL13ABNA6371362585","gender":"male","name":{"initials":"P.","firstName":"Peter","lastNamePrefix":"van der","lastName":"Plas"},"address":{"street":"Kerkstraat","houseNumber":"1","houseNumberExtension":"a","zipCode":"3031LS","city":"Arnhem","country":"NL"},"optIns":{"email":true,"mail":true,"phone":true,"sms":true},"mandate":{"id":"skd-39-ss9dskdk33k2hjsdkfj","createdAt":"2019-01-01T21:00:21+00:00Z"}}'

200

400

401

403

404

200

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

Person was updated