Skip to main content

​
Contacts

Contacts represent people in your CRM. They support the broadest Public API v2 surface.

​
Supported actions

ActionEndpoint
CreatePOST /api/v2/contact
ReadGET /api/v2/contact/{contact_id}
QueryPOST /api/v2/contact/_query
UpdatePATCH /api/v2/contact/{contact_id}
ArchiveDELETE /api/v2/contact/{contact_id}
Create or updatePOST /api/v2/contact/_assert
Relationships/api/v2/contact/{contact_id}/relationship/{api_name}
Emails/api/v2/contact/{contact_id}/attribute/contact_emails
Phone numbers/api/v2/contact/{contact_id}/attribute/contact_phone_numbers

​
Common fields

FieldValue typeNotes
first_namestringWritable
last_namestringWritable
display_namestringComputed/read-only
primary_emailemailUsually derived from contact emails; useful for matching
primary_phone_numberphone_numberUsually derived from contact phone numbers
stagecontact_stagePatchable; may enforce entrance criteria
owner_user_idrecord_referenceOwner user reference
created_at, updated_attimestampSystem fields
Use GET /api/v2/_schema/contact for the complete field list in your workspace.

​
Create-or-update by email

{
  "match": {
    "contact_emails": "sarah.chen@acme.com"
  },
  "attributes": {
    "first_name": "Sarah",
    "last_name": "Chen",
    "stage": "working",
    "title": "CTO"
  }
}
_assert returns 201 with meta.action: "created" when it creates a contact and 200 with meta.action: "updated" when it updates an existing contact.

​
Relationships

Contacts expose typed relationship routes for accounts and opportunities. 
GET  /api/v2/contact/{contact_id}/relationship/accounts
POST /api/v2/contact/{contact_id}/relationship/accounts

GET  /api/v2/contact/{contact_id}/relationship/opportunities
POST /api/v2/contact/{contact_id}/relationship/opportunities
Use generic relationship routes for other declared relationships from schema.

​
Emails and phone numbers

Use sub-resource endpoints for surgical edits to contact emails and phone numbers. This avoids replacing the whole parent record. 
POST   /api/v2/contact/{contact_id}/attribute/contact_emails
PATCH  /api/v2/contact/{contact_id}/attribute/contact_emails/{item_id}
DELETE /api/v2/contact/{contact_id}/attribute/contact_emails/{item_id}

​
Common errors

Error codeUsually means
ambiguous_match_assert or related_record_match found more than one contact
unknown_fieldField is not in contact schema
field_not_updatableRequest tried to write a computed or system field
stage_entrance_criteria_not_metStage move is blocked
sub_resource_not_supportedAttribute sub-resource is not contact emails or phone numbers