Skip to main content
POST
/
persons
/
find
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
}'

{
  "last_id": 5,
  "persons": [
      {
        "identifier": "internal-id-1",
        "email_address": "[email protected]",
        "first_name": "Test",
        "last_name": "Person 1",
        "external_ref": "id-1",
        "phone_number": "01234567890"
      },
      {
        "identifier": "internal-id-2",
        "email_address": "[email protected]",
        "first_name": "Test",
        "last_name": "Person 2",
        "external_ref": "id-2",
        "phone_number": "01234567890"
      }
    ]
}
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.
​
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.
​
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."
  }
}

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
}'

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