Create/Update Persons

This API endpoint allows you to create or update multiple person records.

The API will attempt to match these records with existing person records within the scope of the provided groups.

If a match is found, the existing person record will be updated with the information provided.

If no match is found, a new person record will be created and scoped to the provided groups.

If no groups are provided, any updated or created person records will be scoped to all groups the logged in user has access to.

If you do not have access to one of the groups you have provided, the endpoint will not attempt to match the person record against records in that group and any newly created persons will not be assigned to the group.

You can provide either a group id via the group_id parameter or a group external reference via the group_external_ref attribute.

If both are provided for any of the person records in ther request body, the request will not be successful.

Matching of the person records is done in the following order:

1. By external reference. A person record will be updated if the provided external_ref in the request body is an exact match.
2. By email address (email_address) or phone number (phone_number).

For a new person record to be successfully created, you must provide either an external reference (external_ref) or any combination of phone number (phone_number) or email address (email_address) AND first name (first_name) or (last_name).

For example:

  curl --location --request POST 'https://api.travtus.com/integration/persons/' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: bearer <token>'
  --data-raw '{
      "email_address": "[email protected]",
      "first_name": "Test"
  }'

would be accepted as it provides an email address AND a first name, but

  curl --location --request POST 'https://api.travtus.com/integration/persons/' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: bearer <token>'
  --data-raw '{
      "email_address": "[email protected]",
      "phone_number": "01234567890"
  }'

would not be accepted, as it fails to provide a value for an attribute from the second group (no first or last name provided).

​

Header

​

Body

​

Response

​

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 for a person

{
   "error": {
    "type": "both_group_identifiers_provided",
    "message": "You have provided both group ids and group external references for a person in your request body. Please only provide one of the two."
  }
}