Allo

Update person

Updates an existing person. Only provided fields will be updated. Set custom attribute values with custom attributes . A key that is not an active custom…

PUT/v2/api/crm/people/{id}

Partial update

This endpoint performs a partial update -- only the fields you include in the request body are modified. Omitted fields are left unchanged.

All fields from the create endpoint are accepted and optional.

custom_attributes is accepted too. Only the keys you send change.

Unlinking a company

Send company_id as an empty string ("") to remove the person's association with their current company.

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 changes 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

This sets lead_source and clears budget. Any other custom attribute is untouched.

{
  "custom_attributes": {
    "lead_source": "Referral",
    "budget": null
  }
}
{
  "data": {
    "id": "per-abc123",
    "name": "John",
    "custom_attributes": {
      "lead_source": "Referral"
    }
  }
}

Authorization

Authorizationstring · headerrequired

Api-Key ak_live_…

Path parameters

idstringrequired

Person ID (e.g., "per-abc123")

Body

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 (replaces all existing numbers)

emailsstring[]

Email addresses (replaces all existing emails)

company_idstring | null

ID of the company to associate with

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 updated
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
404
422
429