Allo

Create person

Creates a new person in your CRM. Set custom attribute values with custom attributes . A key that is not an active custom attribute returns 400 CUSTOM…

POST/v2/api/crm/people

Body fields

FieldTypeRequiredDefaultDescription
namestringnoFirst name
last_namestringnoLast name
job_titlestringnoJob title
websitestringnoWebsite URL
addressstringnoAddress
numbersarrayyesPhone numbers in E.164 format. At least one number
emailsarraynoEmail addresses
company_idstringnoAssociated company ID
allow_duplicate_numberbooleannofalseAllow creating the person even if one or more phone numbers are already assigned to another person
custom_attributesobjectnoValues of your custom fields, keyed by field key

At least one of name or last_name is required. A request without numbers, or with an empty list, fails with 400 MISSING_FIELD.

Associations

Pass a company_id to link the person to an existing company. The company must exist or the request returns an error.

Duplicate phone numbers

By default, creating a person with phone numbers that already belong to another person in your team returns a 409 Conflict error. The error response includes the IDs of the existing people so you can update them instead.

To create the person anyway, set allow_duplicate_number to true.

{
  "name": "John",
  "numbers": ["+33612345678"],
  "allow_duplicate_number": true
}

To find the existing person by phone number, use Search people with the phone_number filter.

Custom attributes

custom_attributes sets the values of your custom fields. Create the field first, then use its key here.

Attribute typeAccepted value
TEXTA string
NUMBERA finite JSON number. Strings are rejected. Read back as a decimal, so 180 is returned as 180.0
BOOLEANA JSON boolean
DATEYYYY-MM-DD or an ISO datetime. Stored as a date and returned as YYYY-MM-DD
DROPDOWNAn option key or label, case-insensitive. Always returned as the option key
  • Send null for a key to clear its value.
  • Keys you leave out are not changed. {}, or leaving out custom_attributes, changes nothing.
  • An unknown or archived key returns 400 CUSTOM_ATTRIBUTE_KEY_UNKNOWN. A value of the wrong type returns 400 CUSTOM_ATTRIBUTE_VALUE_INVALID. In both cases param is custom_attributes.<key>.
  • The whole request is validated before anything is written, so a rejected request creates nothing.
  • The response always includes custom_attributes, {} when the person has none. Archived attributes and empty values are left out.
  • Values are also synced to your connected CRMs that create contacts. A value on an attribute that is synced from a CRM can be overwritten by the next CRM sync.

Example

The budget number is read back as a decimal.

{
  "name": "John",
  "numbers": ["+33612345678"],
  "custom_attributes": {
    "lead_source": "Webinar",
    "budget": 5000
  }
}
{
  "data": {
    "id": "per-abc123",
    "name": "John",
    "numbers": ["+33612345678"],
    "custom_attributes": {
      "lead_source": "Webinar",
      "budget": 5000.0
    }
  }
}

Authorization

Authorizationstring · headerrequired

Api-Key ak_live_…

Body

namestring | null

First name

last_namestring | null

Last name

job_titlestring | null

Job title

websitestring | null

Website URL

addressstring | null

Postal address

numbersstring[]required

Phone numbers in E.164 format. At least one number is required.

emailsstring[]

Email addresses

company_idstring | null

ID of the company to associate with

allow_duplicate_numberboolean

When true, allows creating a person even if the phone numbers are already assigned to another person. Defaults to false.

custom_attributesobject | null

Values for the person's custom attributes, keyed by attribute key. TEXT takes a string, NUMBER a finite JSON number (numeric strings are rejected), BOOLEAN a JSON boolean, DATE a YYYY-MM-DD string or ISO datetime, and DROPDOWN an option key or label (case-insensitive). Send null to clear a value; keys you omit are left untouched, and {} or omitting the field changes nothing. An unknown or archived key, or a value of the wrong type, rejects the whole request with CUSTOM_ATTRIBUTE_KEY_UNKNOWN or CUSTOM_ATTRIBUTE_VALUE_INVALID.

Responses

200Person created
dataobject

A person in the CRM

14 fields
idstring

Unique person identifier

namestring | null

First name

last_namestring | null

Last name

job_titlestring | null

Job title

websitestring | null

Website URL

addressstring | null

Postal address

numbersstring[]

Phone numbers in E.164 format

emailsstring[]

Email addresses

companyobject | null

Embedded company reference

2 fields
idstring

Company ID

namestring

Company name

interactionsinteger

Total number of interactions (calls + messages)

last_activity_atstring<date-time> | null

Timestamp of the last activity

created_atstring<date-time>

When the person was created

updated_atstring<date-time>

When the person was last updated

custom_attributesobject

Values of the person's custom attributes, keyed by attribute key. Always present, {} when there are none. Archived attributes and empty values are omitted. NUMBER values are decimals (180 is returned as 180.0), DATE values are YYYY-MM-DD and DROPDOWN values are the option key. Create the attributes first with POST /v2/api/crm/attributes.

400
401
409
422
429