Contacts API

List Contacts


GET /api/v1/contacts

Scope: contacts:read

Query Parameters

Param	Type	Description
`search`	string	Filter by name, email, or company (partial match)
`email`	string	Exact email match
`limit`	number	Max results (default 50, max 100)
`offset`	number	Pagination offset

Response


{
  "contacts": [
    {
      "id": "uuid",
      "email": "john@acme.com",
      "first_name": "John",
      "last_name": "Smith",
      "company": "Acme Corp",
      "title": "VP Sales",
      "phone": "+15551234567",
      "lead_status": "qualified",
      "custom_fields": { "assessment_score": 85 },
      "created_at": "2026-03-26T10:00:00Z"
    }
  ],
  "total": 150,
  "limit": 50,
  "offset": 0
}

Create Contact


POST /api/v1/contacts

Scope: contacts:write

Creates a new contact or updates an existing one (upserts by email). Optionally creates an Account and Opportunity in the same call.

Request Body


{
  "email": "john@acme.com",
  "first_name": "John",
  "last_name": "Smith",
  "phone": "+15551234567",
  "mobile_phone": "+15559876543",
  "company": "Acme Corp",
  "title": "VP Sales",
  "department": "Sales",
  "industry": "Technology",
  "lead_source": "website",
  "lead_status": "qualified",
  "lifecycle_stage": "opportunity",
  "address_city": "Dallas",
  "address_state": "TX",
  "address_country": "US",
  "timezone": "America/Chicago",
  "preferred_contact_method": "email",
  "do_not_call": false,
  "do_not_email": false,
  "do_not_sms": false,
  "custom_fields": {
    "assessment_score": 85,
    "opportunity_type": "AI Transformation"
  },
  "create_account": true,
  "create_opportunity": {
    "name": "Acme Corp — AI Assessment",
    "value": 25000,
    "stage": "qualified",
    "close_date": "2026-04-30",
    "probability": 70,
    "description": "Interested in AI workforce platform"
  }
}

Only email is required. All other fields are optional.

Response (201)


{
  "contact": {
    "id": "uuid",
    "email": "john@acme.com",
    "first_name": "John",
    "last_name": "Smith",
    "company": "Acme Corp",
    "custom_fields": { "assessment_score": 85 }
  },
  "account": {
    "id": "uuid",
    "name": "Acme Corp"
  },
  "opportunity": {
    "id": "uuid",
    "name": "Acme Corp — AI Assessment",
    "stage": "qualified",
    "value": 25000
  }
}

Webhook Event

Triggers contact.created with the contact data.

Update Contact


PATCH /api/v1/contacts/:id

Scope: contacts:write

Request Body

Only include the fields you want to change:


{
  "lead_status": "engaged",
  "custom_fields": { "assessment_score": 92 },
  "phone": "+15559999999"
}

Response


{
  "contact": {
    "id": "uuid",
    "email": "john@acme.com",
    "first_name": "John",
    "last_name": "Smith",
    "company": "Acme Corp",
    "custom_fields": { "assessment_score": 92 }
  }
}