Getting started with contact lists

A contact list is a named group of contacts. A campaign sends one WhatsApp message to the contacts of one list, so a list is the first thing you set up. This section lets you see your lists, create them, rename them, archive them and delete them.

This page covers the lists themselves. Adding the people inside a list is covered in Getting started with contacts.

What you want to do	Endpoint
See all your lists	`GET /contact/list`
Create a list	`POST /contact/list`
Rename a list or change the duplicates setting	`PUT /contact/list`
Archive a list, or make it active again	`PUT /contact/list/status`
Delete a list	`DELETE /contact/list`

1. The big picture

Create a list  →  Add contacts to it  →  Use the list in a campaign
                                              ↓
                        Archive it when you no longer need it  →  Delete it (only when it is empty)

Each list belongs to your organization. Other organizations never see your lists.

2. Before you start

You only need your API key. See Authentication if you do not have one yet.

Every request in this section is sent to https://api.chronox.ai/api with the header Authorization: Bearer <API-key>.

INFO

The Master Contact List. Every organization has one built-in list called Master Contact List. Chronox keeps it for you (for example, it records customers who opted out of marketing messages). You can read it, but you cannot rename it, archive it or delete it, and you cannot delete the contacts inside it. You also cannot create a list with that name.

3. See your lists

GET /contact/list

No parameters. You get every list of your organization, including archived ones and the Master Contact List.

{
  "status": true,
  "data": [
    {
      "contact_list_id": 12,
      "contact_list_name": "October customers",
      "contact_list_status_id": 1,
      "contact_list_status_name": "Active",
      "flag_allow_duplicate_contact": false,
      "created_at_timestamp": "2026-01-01T00:00:00.000Z",
      "updated_at_timestamp": null,
      "total_contact": 250
    }
  ]
}

Field	What it means
`contact_list_id`	The number you use in every other request about this list.
`contact_list_status_name`	`Active` or `Archived`.
`flag_allow_duplicate_contact`	`true` if the same phone number may appear more than once in this list. See section 8.
`total_contact`	How many contacts are in the list right now.
`updated_at_timestamp`	`null` until the list is changed for the first time.

If you have no lists, data is an empty array.

4. Create a list

POST /contact/list

{
  "contact_list_name": "October customers",
  "flag_allow_duplicate_contact": false
}

Field	Required	Notes
`contact_list_name`	Yes	Must be different from every other list name in your organization. `Master Contact List` is reserved.
`flag_allow_duplicate_contact`	No	`true` or `false` (also accepts the text `"true"` or `"false"`). If you leave it out, duplicates are not allowed.

You get the new list back. It starts as Active.

{
  "status": true,
  "data": [
    {
      "contact_list_id": 12,
      "contact_list_name": "October customers",
      "contact_list_status_id": 1,
      "contact_list_status_name": "Active",
      "flag_allow_duplicate_contact": false,
      "created_at_timestamp": "2026-01-01T00:00:00.000Z",
      "updated_at_timestamp": null
    }
  ]
}

Note the contact_list_id. You need it to add contacts.

5. Rename a list, or change the duplicates setting

PUT /contact/list

Send the list ID and the name. The name is always required, even if you only want to change the duplicates setting (send the current name).

{
  "contact_list_id": 12,
  "contact_list_name": "October customers (final)",
  "flag_allow_duplicate_contact": true
}

You get the updated list back, in the same shape as section 4.

What to know:

You cannot rename or change an archived list. Make it active first (section 6).

You cannot use a name that another list already has.

You can turn "allow duplicates" on at any time. You can only turn it off if no phone number appears twice in the list. Otherwise you get error 9333: remove the duplicate contacts first.

If nothing actually changes, the call still succeeds and returns the list as it is.

6. Archive a list, or make it active again

PUT /contact/list/status

{
  "contact_list_id": 12,
  "contact_list_status_id": 2
}

contact_list_status_id is the number for Active or Archived. Look the numbers up with Get Statuses (GET /global/get-status) instead of typing them in by hand. Only Active and Archived are allowed for a list; any other status gives error 9317.

You get the list back with its new status. Sending the status the list already has is fine and returns the list unchanged.

An archived list is read-only. You cannot rename it, add contacts to it, edit its contacts or delete its contacts. Make it active again to work with it.

WARNING

You cannot archive a list that is still in use. Chronox blocks it if the list is used by a draft, running or paused campaign, a workflow, or a custom recipient. The error (9331) tells you exactly where it is used:

{
  "status": false,
  "error": {
    "code": 9331,
    "message": "This contact list is currently being used by the following workflows, campaigns or custom recipients. ...",
    "used_in_workflow": false,
    "used_in_campaign": true,
    "used_in_custom_recipient": false,
    "workflows": [],
    "campaigns": [
      {
        "campaign_id": 77,
        "campaign_title": "October Offer",
        "campaign_execution_status_name": "Draft"
      }
    ],
    "custom_recipients": []
  }
}

Remove the list from those campaigns or workflows (or finish them), then try again.

7. Delete a list

DELETE /contact/list?contact_list_id=12

The list ID goes in the address (query), not in a body.

A list can only be deleted when all of these are true:

It is not the Master Contact List.

It has no contacts. Delete them first (see Getting started with contacts). An archived list that is empty can be deleted.

It is not used by a campaign, workflow or custom recipient.

On success:

{
  "status": true,
  "data": {
    "code": 9064,
    "message": "Contact List - 'October customers' deleted successfully."
  }
}

Deleting cannot be undone from the API.

8. What "allow duplicate contacts" means

Setting	What happens when you add a phone number that is already in the list
`false` (default)	The new contact is refused ("Contact already exists").
`true`	The new contact is added, so the same number can appear more than once.

Choose false unless you really need repeated numbers. A campaign sends one message per contact, so with duplicates on, the same person can receive the message more than once. The Master Contact List never allows duplicates.

9. Common errors

Errors come back with HTTP status 200 and "status": false. See Errors for the general format.

Code	What it means	What to do
`9001`	The body is wrong: missing `contact_list_name`, bad ID, or the list was not found.	Check the fields and the list ID.
`9002`	A query value is missing or wrong (for delete).	Send `contact_list_id` in the address.
`9310`	`Master Contact List` is a reserved name.	Choose another name.
`9311`	The Master Contact List cannot be edited.	Use a different list.
`9312`	A list with this name already exists.	Choose another name.
`9317`	Only Active and Archived are allowed.	Use the IDs from Get Statuses.
`9318`	The status of the Master Contact List cannot change.	Nothing to do.
`9330`	The list is archived, so the action is not allowed.	Make the list active first.
`9331`	The list is used by campaigns, workflows or custom recipients, so it cannot be archived.	See the details in the error, remove it from there.
`9332`	Same as above, for delete.	Same as above.
`9308`	The Master Contact List cannot be deleted.	Nothing to do.
`9316`	The list still has contacts.	Delete the contacts first.
`9333`	The list has duplicate phone numbers, so duplicates cannot be turned off.	Remove the duplicates first.

10. Quick checklist

The list name is unique and is not Master Contact List.

You decided whether the list should allow duplicate contacts.

You saved the contact_list_id from the response.

Before archiving: no draft, running or paused campaign uses the list.

Before deleting: the list is empty and not used anywhere.

What this section doesn't cover

Adding, finding, changing and deleting the contacts inside a list: see Getting started with contacts.

Contact tags and custom fields: see the Tags and fields folder.

Sending a message to a list: see Getting started with campaigns.

Getting started

Getting started with contact lists#

1. The big picture#

2. Before you start#

3. See your lists#

4. Create a list#

5. Rename a list, or change the duplicates setting#

6. Archive a list, or make it active again#

7. Delete a list#

8. What "allow duplicate contacts" means#

9. Common errors#

10. Quick checklist#

What this section doesn't cover#