Get a paged list of existing persons, optionally filtered to the given parameters. A param-based alternative to the '/filter' POST endpoint.
Get Persons Filtered and Paged (GET)
Retrieves a paged, optionally filtered list of existing persons using individual query parameters.
A developer calls this endpoint to search for persons matching one or more criteria (for example by display name, relation type, or address), or to retrieve the full set of persons in manageable pages when no filter is needed, such as for building a picker list or syncing records into another system.
This is a param-based alternative to the POST endpoint (POST /api/v1/relations/persons/filter), but offers a narrower set of filter criteria, it does not support filtering on archive date or last-modified date.
Request Fields
Field | Type | Required | Description |
|---|---|---|---|
pageSize | integer, 1 to 1000 | Optional | The number of persons to return per page. Defaults to 100 when not given. |
pageNumber | integer, 1 to 9999 | Optional | The page number to retrieve. Defaults to 1 when not given. |
displayName | string | Optional | Filters on the person's display name. |
reference | string | Optional | Filters on the person's internal identifier (Reference/Code). |
externalIdentifier | string | Optional | Filters on the person's external API identifier. |
relationTypeName | string | Optional | Filters on the relation type assigned to the person. |
phoneNumber | string | Optional | Filters on the person's landline phone number. |
mobileNumber | string | Optional | Filters on the person's mobile phone number. |
primaryEmailAddresses | string | Optional | Filters on the person's primary email address(es). |
addressStreetAndHouseNumber | string | Optional | Filters on the combined street and house number of the person's address, for example "Bredaseweg 12". |
addressPostalCode | string | Optional | Filters on the postal code of the person's address. |
addressCity | string | Optional | Filters on the city of the person's address. |
addressCountryISOCode | string | Optional | Filters on the ISO 3166-1 alpha-2 country code of the person's address. |
Response Fields
Field | Type | Required | Description |
|---|---|---|---|
paging.pageSize | integer, 1 to 1000, nullable | Optional | The page size used to produce this result set. |
paging.pageNumber | integer, 1 to 9999, nullable | Optional | The page number returned in this result set. |
sorting.columnName | string, nullable | Optional | The field the results are sorted by. |
sorting.order | integer (enum), nullable | Optional | The sort direction applied. Allowed values: 0 = Ascending, 1 = Descending. |
persons | array of objects, nullable | Optional | The list of persons matching the filter for this page. See sub-fields below. |
persons.displayName | string, nullable | Optional | The formatted display name of the person. |
persons.reference | string, nullable | Optional | The internal identifier (Reference/Code) of the person. |
persons.externalIdentifier | string, nullable | Optional | The external API identifier of the person, if any. |
persons.relationTypeName | string, nullable | Optional | The relation type assigned to the person. |
persons.phoneNumber | string, nullable | Optional | The person's landline phone number. |
persons.mobileNumber | string, nullable | Optional | The person's mobile phone number. |
persons.primaryEmailAddresses | string, nullable | Optional | The person's primary email address(es) as a single semicolon-separated string, for example "lars@bloxs.com;lars2@bloxs.com". |
persons.addressStreetAndHouseNumber | string, nullable | Optional | The combined street and house number of the person's address, for example "Bredaseweg 12". |
persons.addressPostalCode | string, nullable | Optional | The postal code of the person's address. |
persons.addressCity | string, nullable | Optional | The city of the person's address. |
persons.addressCountryISOCode | string, nullable | Optional | The ISO 3166-1 alpha-2 country code of the person's address. |
persons.archiveDate | string (date-time), nullable | Optional | The date and time from which the person is archived, formatted as ISO 8601. Null if not archived. |
persons.lastModified | string (date-time), nullable | Optional | The date and time the record was last modified, formatted as ISO 8601. |
The requested page size. Defaults to 100 when not given.
The requested page number. Defaults to 1 when not given.
Optional filter on the display name of the person.
Optional filter on the reference of the person.
Optional filter on the external API identifier of the person.
Optional filter on the relation type name of the person.
Optional filter on the phone number of the person.
Optional filter on the mobile number of the person.
Optional filter on the primary e-mail addressess of the person.
Optional filter on the street and house number of the address of the person.
Optional filter on the postal code of the address of the person.
Optional filter on the city of the address of the person.
Optional filter on the country ISO code of the address of the person.
OK
Ascending = 0 Descending = 1