Contacts

Overview

Create, read and update the people your organization talks to. Contacts are keyed per channel — waId for WhatsApp, igId for Instagram — and the same person on two channels is two contact records until you merge them. Bulk loading goes through the import endpoints, which run as background jobs you poll.

10 endpoints. Requires contacts.view or contacts.edit on the token.

Method	Path	What it does
GET	/contacts	List contacts
POST	/contacts	Create a contact
GET	/contacts/{id}	Get contact by ID
PATCH	/contacts/{id}	Update a contact
GET	/contacts/export	Export contacts as CSV
POST	/contacts/import	Queue a contact import
GET	/contacts/import-template	Download contact import template
GET	/contacts/imports	List contact import jobs
GET	/contacts/imports/{id}	Get contact import job
GET	/contacts/imports/{id}/errors	Download import errors as CSV

Endpoints

GET /contacts

List contacts

List or search contacts with pagination, custom fields, and segments. Requires `contacts.view` permission.

Requires the contacts.view permission.

Parameter	In	Type	Required	Description
page	query	integer	optional	Page number Defaults to 1.
limit	query	integer	optional	Items per page Defaults to 50.
search	query	string	optional	Search by name, WhatsApp ID, Instagram ID, or username
channel	query	WHATSAPP · INSTAGRAM	optional	Filter by channel
segmentId	query	string	optional	Filter by segment ID

Example

curl -X GET "https://orqestra.id/api/v2/contacts" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN"

Responds with 200 · 401 · 403. Try it in the playground →

---

POST /contacts

Create a contact

Create a new contact. At least one of `waId` or `igId` is required. Returns 409 if duplicate exists. Requires `contacts.edit` permission.

Requires the contacts.edit permission.

Request body

Field	Type	Required	Description
waId	string	optional	WhatsApp ID (phone number)
igId	string	optional	Instagram user ID
name	string	required	Display name

Example

curl -X POST "https://orqestra.id/api/v2/contacts" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Example"
  }'

Responds with 200 · 400 · 401 · 403 · 409. Try it in the playground →

---

GET /contacts/{id}

Get contact by ID

Get a single contact. Accepts CUID, waId, or igId. Requires `contacts.view` permission.

Requires the contacts.view permission.

Parameter	In	Type	Required	Description
id	path	string	required	Contact CUID, waId, or igId

Example

curl -X GET "https://orqestra.id/api/v2/contacts/$id" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN"

Responds with 200 · 401 · 403 · 404. Try it in the playground →

---

PATCH /contacts/{id}

Update a contact

Update contact fields. Supports updating name, customName, waId, igId, and igUsername. Accepts CUID, waId, or igId as path parameter. Requires `contacts.edit` permission.

Requires the contacts.edit permission.

Parameter	In	Type	Required	Description
id	path	string	required	Contact CUID, waId, or igId

Request body

Field	Type	Required	Description
name	string	optional	Display name
customName	string	optional	Custom name override
waId	string	optional	WhatsApp ID (phone number)
igId	string	optional	Instagram user ID
igUsername	string	optional	Instagram username

Example

curl -X PATCH "https://orqestra.id/api/v2/contacts/$id" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN"

Responds with 200 · 400 · 401 · 403 · 404. Try it in the playground →

---

GET /contacts/export

Export contacts as CSV

Download contacts as CSV. Requires `contacts.view` permission.

Requires the contacts.view permission.

Parameter	In	Type	Required	Description
search	query	string	optional	Search filter
channel	query	WHATSAPP · INSTAGRAM	optional	Filter by channel
segmentId	query	string	optional	Filter by segment ID

Example

curl -X GET "https://orqestra.id/api/v2/contacts/export" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN"

Responds with 200 · 401 · 403. Try it in the playground →

---

POST /contacts/import

Queue a contact import

Upload a CSV file and queue an asynchronous contact import job. Requires `contacts.edit` permission.

Requires the contacts.edit permission.

Example

curl -X POST "https://orqestra.id/api/v2/contacts/import" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN"

Responds with 200 · 400 · 401 · 403. Try it in the playground →

---

GET /contacts/import-template

Download contact import template

Download a starter CSV template for contact imports. Requires `contacts.view` permission.

Requires the contacts.view permission.

Example

curl -X GET "https://orqestra.id/api/v2/contacts/import-template" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN"

Responds with 200 · 401 · 403. Try it in the playground →

---

GET /contacts/imports

List contact import jobs

List recent contact import jobs. Requires `contacts.view` permission.

Requires the contacts.view permission.

Parameter	In	Type	Required	Description
activeOnly	query	boolean	optional	Only return queued or processing jobs
limit	query	integer	optional	Number of jobs to return Defaults to 20.

Example

curl -X GET "https://orqestra.id/api/v2/contacts/imports" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN"

Responds with 200 · 401 · 403. Try it in the playground →

---

GET /contacts/imports/{id}

Get contact import job

Get the current status and counters for a contact import job. Requires `contacts.view` permission.

Requires the contacts.view permission.

Parameter	In	Type	Required	Description
id	path	string	required	Contact import job ID

Example

curl -X GET "https://orqestra.id/api/v2/contacts/imports/$id" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN"

Responds with 200 · 401 · 403 · 404. Try it in the playground →

---

GET /contacts/imports/{id}/errors

Download import errors as CSV

Download the failed-row report for a contact import job. Requires `contacts.view` permission.

Requires the contacts.view permission.

Parameter	In	Type	Required	Description
id	path	string	required	Contact import job ID

Example

curl -X GET "https://orqestra.id/api/v2/contacts/imports/$id/errors" \
  -H "Authorization: Bearer $ORQESTRA_TOKEN"

Responds with 200 · 401 · 403 · 404. Try it in the playground →