> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.travtus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField header="Authorization" type="string" default="none" required>
  The authentication token for your request
</ParamField>

### Body

<ParamField body="first_name" type="string" default="none">
  The first name of the persons you want to retrieve.
</ParamField>

<ParamField body="last_name" type="string" default="none">
  The last name of the persons you want to retrieve.
</ParamField>

<ParamField body="email_address" type="string" default="none">
  The email adddress of the persons you want to retrieve.
</ParamField>

<ParamField body="phone_number" type="string" default="none">
  The phone number of the persons you want to retrieve.
</ParamField>

<ParamField body="external_ref" type="string" default="none">
  The external reference of the persons you want to retrieve.
</ParamField>

<ParamField body="identifier" type="string" default="none">
  Internal identifier of the persons you want to retrieve.
</ParamField>

<ParamField body="group_ids" type="[string]" default="none">
  The list of group ids for filtering the retrieved list.
</ParamField>

<ParamField body="groups_external_refs" type="[string]" default="none">
  The list of group external references for filtering the retrieved list.
</ParamField>

<ParamField body="after-id" type="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`.
</ParamField>

### Response

<ResponseField name="persons" type="string">
  A list of the persons that have been retrieved.

  <Expandable title="properties">
    <ResponseField name="identifier" type="string" default="none">
      The internal identifier of the retrieved person.
    </ResponseField>

    <ResponseField name="email_address" type="string">
      The email adddress of the retrieved person.
    </ResponseField>

    <ResponseField name="first_name" type="string">
      The first name of the retrieved person.
    </ResponseField>

    <ResponseField name="last_name" type="string">
      The last name of the retrieved person.
    </ResponseField>

    <ResponseField name="external_ref" type="string">
      The external reference of the retrieved person.

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

    <ResponseField name="phone_number" type="string">
      The email adddress of the retrieved person.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="last_id" type="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.
</ResponseField>

### Errors

Listed below are common errors that may be returned by the endpoint, along with their corresponding status code.

Status Code - 400

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

Status Code - 401

```json Expired Authorization header bearer token value theme={null}
{
   "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

```json Invalid Authorization header bearer token value theme={null}
{
   "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

```json Both group ids and external refs provided for the person find operation theme={null}
{
   "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.

```json No person records found for the provided parameters theme={null}
{
   "error": {
    "type": "not_found",
    "message": "There are no person records matching the information provided."
  }
}
```

<RequestExample>
  ```bash Example Request theme={null}
  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
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "last_id": 5,
    "persons": [
        {
          "identifier": "internal-id-1",
          "email_address": "test.person.1@travtus.com",
          "first_name": "Test",
          "last_name": "Person 1",
          "external_ref": "id-1",
          "phone_number": "01234567890"
        },
        {
          "identifier": "internal-id-2",
          "email_address": "test.person.2@travtus.com",
          "first_name": "Test",
          "last_name": "Person 2",
          "external_ref": "id-2",
          "phone_number": "01234567890"
        }
      ]
  }
  ```
</ResponseExample>