Create/Update Persons

This endpoint creates or updates multiple person records passed as a list in the request’s body.

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:

Example Request

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

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

Example Request

  curl --location --request POST 'https://api.travtus.com/integration/persons/' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: bearer <token>'
  --data-raw '{
      "email_address": "[e-mail]",
      "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

Authorization · string · default: "none" · required

The authentication token for your request.

Body

persons · [object] · default: "none" · required

A list of person entries to create or update.

Show properties

email_address · string · default: "none"

The email adddress of the person you want to create or update.

first_name · string · default: "none"

The first name of the person you want to create or update.

last_name · string · default: "none"

The last name of the person you want to create or update.

external_ref · string · default: "none"

An external reference for the person you want to create or update.

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

This will be the first attribute that will be used when attempting to match an exisitng person records, if it is set in the request’s body.

phone_number · string · default: "none"

The phone number of the persons you want to create or update.

group_ids · [string] · default: "none"

A list of group ids to be used when creating or updating the person record.

The groups will be used for matching existing person records and for scoping newly created ones.

groups_external_refs · [string] · default: "none"

A list of group external refs to be used when creating or updating the person record.

The groups will be used for matching existing person records and for scoping newly created ones.

Response

success · boolean

True if the person creation was successful, false otherwise.

persons · string

A list of the persons that have been created or updated, along with their internal identifiers

Show properties

identifier · string · default: "none"

The internal identifier of the created or updated person.

email_address · string

The email address of the created or updated person.

first_name · string

The first name of the created or updated person.

last_name · string

The last name of the created or updated person.

external_ref · string

The external reference of the created or updated person.

phone_number · string

The phone number of the created or updated person.

success · boolean

Whether the person record update or creation was successful.

failure_reason · string

The reason for an unsuccesful person record creation or update.

Empty if update or creation of record was successful.

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

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 a person in your request body. Please only provide one of the two."
  }
}

Example Request

curl --location --request POST 'https://api.travtus.com/persons/multiple/' \
--header 'Content-Type: application/json' \
--header 'Authorization: bearer <token>' \
--data-raw '{
    "persons": [
      {
        "email_address": "[e-mail]",
        "first_name": "Test",
        "last_name": "Person 1",
        "external_ref": "id-1",
        "phone_number": "01234567890",
        "group_ids": "['group-1', 'group-2']"
      },
      {
        "email_address": "[e-mail]",
        "first_name": "Test",
        "last_name": "Person 2",
        "external_ref": "id-2",
        "phone_number": "01234567891",
        "group_ids": "['group-1']"
      },
      {
         "first_name": "Test insuficient info",
         "groups_external_refs": "['group-external-ref-1']"
      }
    ]
}'

Response

{
  "persons": [
      {
        "identifier": "internal-id-1",
        "email_address": "[e-mail]",
        "first_name": "Test",
        "last_name": "Person 1",
        "external_ref": "id-1",
        "phone_number": "01234567890",
        "success": true,
        "failure_reason": ""
      },
      {
        "identifier": "internal-id-2",
        "email_address": "[e-mail]",
        "first_name": "Test",
        "last_name": "Person 2",
        "external_ref": "id-2",
        "phone_number": "01234567891",
        "success": true,
        "failure_reason": ""
      },
      {
         "first_name": "Test insuficient info",
         "groups": "['group-1']",
         "success": false,
         "failure_reason": "Insufficient information to create a new person record. Please provide either an external reference or a combination of phone number OR email address AND first name OR last name."
      }
    ]
}