Find Persons
This endpoint allows users to find a list of persons based on multiple person attributes.
You need to provide exact matches in the body of the request for the attributes of the persons you are looking for.
You can provide either a list of group ids through the group_ids parameter or a list of group external references through the groups_external_refs attribute to filter the list of retrieved persons down.
Do not provide both, as this will result in the request failing.
If no group_ids or group_external_refs are specified in the request body, the authenticated user will retrieve person records for all groups they have access to.
Header
The authentication token for your request
Body
The first name of the persons you want to retrieve.
The last name of the persons you want to retrieve.
The email adddress of the persons you want to retrieve.
The phone number of the persons you want to retrieve.
The external reference of the persons you want to retrieve.
Internal identifier of the persons you want to retrieve.
The list of group ids for filtering the retrieved list.
The list of group external references for filtering the retrieved list.
The API returns a maximum of 100 records per call.
You can use this parameter to load the next set of records by passing in the value returned in the response, under last_id.
Response
A list of the persons that have been retrieved.
The last id in the set of results returned for this API call.
You can use this value in the after-id parameter to load the next set of results.
If there are no more results to load, this value will be -1.
Please note that this is unrelated to the external reference or the internal identifier.
Errors
Listed below are common errors that may be returned by the endpoint, along with their corresponding status code.
Status Code - 400
{
"error": {
"type": "missing_authorization",
"message": "Your request does not include an 'Authorization' header with a bearer token for your account."
}
}
Status Code - 401
{
"error": {
"type": "expired_token",
"message": "The bearer token you have provided in the 'Authorization' header has expired. Please obtain a new one."
}
}
Status Code - 401
{
"error": {
"type": "invalid_authorization",
"message": "The bearer token you have provided in the 'Authorization' header is invalid."
}
}
Status Code - 400
Returned if both of the group_ids and groups_external_refs attributes are provided
{
"error": {
"type": "both_group_identifiers_provided",
"message": "You have provided both group ids and group external references for the find persons operation. Please only provide one of the two."
}
}
Status Code - 404
Returned if no person records can be found matching the provided information.
{
"error": {
"type": "not_found",
"message": "There are no person records matching the information provided."
}
}