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:

By external reference. A person record will be updated if the provided external_ref in the request body is an exact match.
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": "[email protected]",
      "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": "[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).

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

curl --location --request POST 'https://api.travtus.com/persons/multiple/' \
--header 'Content-Type: application/json' \
--header 'Authorization: bearer <token>' \
--data-raw '{
    "persons": [
      {
        "email_address": "[email protected]",
        "first_name": "Test",
        "last_name": "Person 1",
        "external_ref": "id-1",
        "phone_number": "01234567890",
        "group_ids": "['group-1', 'group-2']"
      },
      {
        "email_address": "[email protected]",
        "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']"
      }
    ]
}'

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

Introduction

Webhook

Endpoints

Create/Update Persons

Header

Body

Response

Errors

Introduction

Webhook

Endpoints

​Header

​Body

​Response

​Errors

Header

Body

Response

Errors