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

Authorization · string · default: "none" · required

The authentication token for your request

Body

first_name · string · default: "none"

The first name of the persons you want to retrieve.

last_name · string · default: "none"

The last name of the persons you want to retrieve.

email_address · string · default: "none"

The email adddress of the persons you want to retrieve.

phone_number · string · default: "none"

The phone number of the persons you want to retrieve.

external_ref · string · default: "none"

The external reference of the persons you want to retrieve.

identifier · string · default: "none"

Internal identifier of the persons you want to retrieve.

group_ids · [string] · default: "none"

The list of group ids for filtering the retrieved list.

groups_external_refs · [string] · default: "none"

The list of group external references for filtering the retrieved list.

after-id · string · default: "1"

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

persons · string

A list of the persons that have been retrieved.

Show properties

identifier · string · default: "none"

The internal identifier of the retrieved person.

email_address · string

The email adddress of the retrieved person.

first_name · string

The first name of the retrieved person.

last_name · string

The last name of the retrieved person.

external_ref · string

The external reference of the retrieved person.

This is typically an identifier you may use for person records in your own system.

phone_number · string

The email adddress of the retrieved person.

last_id · integer

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

Missing Authorization header

{
   "error": {
    "type": "missing_authorization",
    "message": "Your request does not include an 'Authorization' header with a bearer token for your account."
  }
}

Status Code - 401

Expired Authorization header bearer token value

{
   "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

Invalid Authorization header bearer token value

{
   "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

Both group ids and external refs provided for the person find operation

{
   "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.

No person records found for the provided parameters

{
   "error": {
    "type": "not_found",
    "message": "There are no person records matching the information provided."
  }
}

Example Request

curl --location --request POST 'https://api.travtus.com/persons/find/' \
--header 'Content-Type: application/json' \
--header 'Authorization: bearer <token>'
--data-raw '{
  "phone_number": "01234567890",
  "groups_external_refs": ["group-1"],
  "after-id": 1
}'

Response

{
  "last_id": 5,
  "persons": [
      {
        "identifier": "internal-id-1",
        "email_address": "[e-mail]",
        "first_name": "Test",
        "last_name": "Person 1",
        "external_ref": "id-1",
        "phone_number": "01234567890"
      },
      {
        "identifier": "internal-id-2",
        "email_address": "[e-mail]",
        "first_name": "Test",
        "last_name": "Person 2",
        "external_ref": "id-2",
        "phone_number": "01234567890"
      }
    ]
}