Contacts API

Manage contacts in your EmacronAI CRM workspace. Create contacts from signups, imports, or lead forms. Update them when data changes. Use tags and custom fields for segmentation.

Endpoints

Method	Path	Scope	Description
GET	/api/v1/contacts	contacts:read	List contacts (paginated)
GET	/api/v1/contacts/:id	contacts:read	Get a single contact
POST	/api/v1/contacts	contacts:write	Create a new contact
PATCH	/api/v1/contacts/:id	contacts:write	Update contact fields

GET /api/v1/contacts

Returns a paginated list of contacts. Supports search by name, phone, or email.

Query parameters

Param	Type	Default	Description
page	integer	1	Page number (1-indexed)
limit	integer	25	Results per page (max 100)
search	string	—	Search by name, phone, or email

SDK

const { data, total, has_more } = await oa.contacts.list({
  page:   1,
  limit:  25,
  search: 'Rajesh',
});

POST /api/v1/contacts

Create a new contact. At minimum, name is required. Either phone or email is strongly recommended.

const contact = await oa.contacts.create({
  name:         'Rajesh Kumar',
  phone:        '+919876543210',
  email:        'rajesh@example.com',
  company_name: 'Acme Corp',
  designation:  'CTO',
  city:         'Pune',
  source:       'WhatsApp CTwA',
  tags:         ['enterprise', 'warm-lead'],
  custom_fields: {
    gst_number: '27AAPFU0939F1ZV',
    mrr:        '50000',
  },
});
// returns full Contact object with id, created_at, etc.

PATCH /api/v1/contacts/:id

Partially update a contact. Only send the fields you want to change. Updatable fields: name email phone company_name designation city status.

const updated = await oa.contacts.update('contact_id_here', {
  status: 'qualified',
  city:   'Mumbai',
});

Contact object schema

Field	Type	Description
id	string	Unique contact ID (UUID)
name	string	Full name (required on create)
phone	string	E.164 phone number e.g. +919876543210
email	string	Email address
company_name	string	Company or organisation name
designation	string	Job title or role
city	string	City of residence or work
source	string	Lead source tag e.g. "WhatsApp", "Website"
status	string	Contact status e.g. "active", "unsubscribed"
tags	string[]	Array of tag strings for segmentation
custom_fields	object	Key-value map of custom field data
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last-updated timestamp

Next steps

← Authentication Webhooks →Error codes →Rate limits →