Sign in

Create or update a contact

Creates a new contact or updates an existing one based on email address. Returns information about whether the contact was created or updated.

post/api/contacts.upsert

Request body

workspace_idstring required

The ID of the workspace

Example request

{
  "workspace_id": "ws_1234567890",
  "contact": {
    "email": "user@example.com",
    "external_id": "user_12345",
    "timezone": "America/New_York",
    "language": "en-US",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "phone": "+15551234567",
    "address_line_1": "123 Main St",
    "address_line_2": "Apt 4B",
    "country": "US",
    "postcode": "10001",
    "state": "NY",
    "job_title": "Software Engineer",
    "custom_string_1": "Premium tier",
    "custom_number_1": 42,
    "custom_datetime_1": "2023-06-01T09:00:00Z",
    "custom_json_1": {
      "preferences": {
        "theme": "dark",
        "notifications": true
      }
    }
  }
}

Response

Contact upserted successfully

emailstring email

Email address of the contact

action'create' | 'update' | 'error'

The action that was performed: 'create' for new contacts, 'update' for existing contacts, 'error' if validation failed

errorstring nullable

Error message if the operation failed

Example response

{
  "email": "user@example.com",
  "action": "create"
}

Changes