Contacts

Search contacts

GET /api/v1/contacts

Query parameters

Param	Description
`search`	Search by name, phone, email, or company
`tag`	Filter by tag name
`source`	Filter by contact source (e.g. `Referral`)
`status`	Filter by status (`hot`, `warm`, `active`, `cold`, `new`)
`limit`	Max results (default 20)
`offset`	Pagination offset

Response

Each contact in the response includes:

Standard fields: id, name, phone, email, company, status, lifecycle_stage, source, is_unsubscribed, etc.
tags — array of { id, name, color } objects
custom_fields — jsonb object with your workspace's custom field values

Example

curl "https://app.salesbyte.in/api/v1/contacts?search=rahul&tag=Hot+Lead" \
  -H "Authorization: Bearer YOUR_API_KEY"

Create or update a contact

POST /api/v1/contacts

Upserts by phone number first, then by email — if a contact with that phone (or email) already exists, it's updated.

Request body

{
  "name": "Rahul Sharma",
  "phone": "+919876543210",
  "email": "rahul@example.com",
  "company": "Sharma Traders",
  "status": "hot",
  "tags": ["Interested", "Mumbai"],
  "custom_fields": {
    "customer_type": "Wholesale",
    "city": "Mumbai"
  }
}

All fields

Field	Type	Description
`phone`	string	Phone number with country code. Either `phone` or `email` is required.
`email`	string	Email address. Either `phone` or `email` is required.
`name`	string	Full name
`company`	string	Company name
`status`	string	`hot` / `warm` / `active` / `cold` / `new`
`lifecycle_stage`	string	`lead` / `prospect` / `negotiation` / `customer` / `churned`
`tags`	string[]	Tag names — created if they don't exist
`address_as`	string	How to greet them (e.g. "Rahul Ji")
`custom_fields`	object	Key-value pairs for your workspace's custom fields. Keys are `field_key` values. On upsert, only keys you send are updated — existing values for other keys are preserved.
`update`	boolean	Set `false` to skip updating if the contact already exists (default: `true`)

Phone is now optional — you can create email-only contacts. If you provide both phone and email, lookup is by phone first, then email.

Get a contact

GET /api/v1/contacts/:id

Returns the full contact record including tags and custom_fields.

Update a contact

PUT /api/v1/contacts/:id

Partial update — only send fields you want to change.

{
  "status": "warm",
  "company": "New Company Name",
  "custom_fields": {
    "customer_type": "Retail"
  }
}

custom_fields is merged — keys not in the payload are preserved. Returns 409 conflict if you change the email to one that already belongs to another active contact.

Archive a contact

DELETE /api/v1/contacts/:id

Soft-deletes the contact (sets is_archived: true). The contact is hidden from the main list but not permanently deleted.

Custom field keys (field_key) are the snake_case identifiers set in your workspace's Custom Fields settings. To see your workspace's fields and their keys, use the GET /api/v1/contacts endpoint and inspect the custom_fields object on any existing contact, or check Settings → Custom fields in the app.

Multi-select fields

Multi-select values are stored as JSON arrays:

{
  "custom_fields": {
    "interests": ["Yoga", "Nutrition", "Fitness"]
  }
}

Country fields

Country values are stored as ISO 3166-1 alpha-2 codes (e.g. "IN", "AE", "US").