Body fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | no | First name | |
last_name | string | no | Last name | |
job_title | string | no | Job title | |
website | string | no | Website URL | |
address | string | no | Address | |
numbers | array | yes | Phone numbers in E.164 format. At least one number | |
emails | array | no | Email addresses | |
company_id | string | no | Associated company ID | |
allow_duplicate_number | boolean | no | false | Allow creating the person even if one or more phone numbers are already assigned to another person |
custom_attributes | object | no | Values 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 type | Accepted value |
|---|---|
TEXT | A string |
NUMBER | A finite JSON number. Strings are rejected. Read back as a decimal, so 180 is returned as 180.0 |
BOOLEAN | A JSON boolean |
DATE | YYYY-MM-DD or an ISO datetime. Stored as a date and returned as YYYY-MM-DD |
DROPDOWN | An option key or label, case-insensitive. Always returned as the option key |
- Send
nullfor a key to clear its value. - Keys you leave out are not changed.
{}, or leaving outcustom_attributes, changes nothing. - An unknown or archived key returns
400 CUSTOM_ATTRIBUTE_KEY_UNKNOWN. A value of the wrong type returns400 CUSTOM_ATTRIBUTE_VALUE_INVALID. In both casesparamiscustom_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
}
}
}