NatiqDocs

Appearance

Open Natiq

Contact lists

Create static audiences and add or remove the contacts in them.

Updated 7 Nov 2026

A contact list is a static audience you fill by hand: a contact is in the list because someone added it. Use lists to group people for a campaign. For an audience that fills itself from rules, use segments.

Endpoints

GET/contact-listsList contact listsGET/contact-lists/{listId}Retrieve a contact listPOST/contact-listsCreate a contact listPUT/contact-lists/{listId}Update a contact listDELETE/contact-lists/{listId}Delete a contact listGET/contact-lists/{listId}/membersList membersPOST/contact-lists/{listId}/members/{contactId}Add a contact to a listDELETE/contact-lists/{listId}/members/{contactId}Remove a contact from a list

The contact list object

A list does not embed its members; read them with List members.

Attributes

  • idinteger
    Unique identifier of the list.
  • namestring
    List name, as shown in the Audience page and when you pick a campaign audience.
  • descriptionstringnullable
    What the list is for.
  • memberCountinteger
    Number of contacts in the list, counted when you read it, so it is never stale. Never null.
The contact list object
json
{
  "id": 7,
  "name": "VIP customers",
  "description": "Gold-plan customers in Amman",
  "memberCount": 128
}

List contact lists

Returns a page of contact lists.

Requires contacts:read Offset paginated

Query parameters

  • pageinteger
    Zero-based page number. Default 0.
  • sizeinteger
    Page size. Default 20; keep it at 100 or below.

Returns

200A page of results.

bash
curl -X GET "https://api.cx.na6iq.com/api/v1/contact-lists?page=0&size=25" \
  -H "Authorization: Bearer $NATIQ_TOKEN"
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/contact-lists?page=0&size=25', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
  },
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
const data = await res.json()
python
import os, requests

res = requests.get(
    "https://api.cx.na6iq.com/api/v1/contact-lists?page=0&size=25",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
)
res.raise_for_status()
data = res.json()
Response200
json
{
  "data": [
    {
      "id": 7,
      "name": "VIP customers",
      "description": "Gold-plan customers in Amman",
      "memberCount": 128
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1
}

Retrieve a contact list

Returns one list with its current memberCount.

Requires contacts:read

Path parameters

  • listIdintegerrequired
    The list’s id.

Returns

200The contact list object.

Errors

  • 404CONTACT_LIST_NOT_FOUNDNo list with this ID in your organisation.
bash
curl -X GET "https://api.cx.na6iq.com/api/v1/contact-lists/42" \
  -H "Authorization: Bearer $NATIQ_TOKEN"
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/contact-lists/42', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
  },
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
const data = await res.json()
python
import os, requests

res = requests.get(
    "https://api.cx.na6iq.com/api/v1/contact-lists/42",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
)
res.raise_for_status()
data = res.json()
Response200
json
{
  "id": 7,
  "name": "VIP customers",
  "description": "Gold-plan customers in Amman",
  "memberCount": 128
}

Create a contact list

Creates an empty list. Add people with Add a contact to a list.

Requires contacts:write

Request body

  • namestringrequired
    List name.
  • descriptionstringnullable
    Optional description.

Returns

201The contact list object.

Errors

  • 400VALIDATION_FAILED`name` is blank — see `error.details`.
  • 409CONSTRAINT_VIOLATION`name` is longer than 255 characters.
bash
curl -X POST "https://api.cx.na6iq.com/api/v1/contact-lists" \
  -H "Authorization: Bearer $NATIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "VIP customers",
  "description": "Gold-plan customers in Amman"
}'
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/contact-lists', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "VIP customers",
    "description": "Gold-plan customers in Amman"
  }),
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
const data = await res.json()
python
import os, requests

res = requests.post(
    "https://api.cx.na6iq.com/api/v1/contact-lists",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
    json={
      "name": "VIP customers",
      "description": "Gold-plan customers in Amman"
    },
)
res.raise_for_status()
data = res.json()
Response201
json
{
  "id": 7,
  "name": "VIP customers",
  "description": "Gold-plan customers in Amman",
  "memberCount": 0
}

Update a contact list

Renames the list or changes its description. It replaces both fields: send the whole record, since an omitted description is cleared. Members are untouched.

Requires contacts:write

Path parameters

  • listIdintegerrequired
    The list’s id.

Request body

  • namestringrequired
    List name.
  • descriptionstringnullable
    Optional description.

Returns

200The contact list object.

Errors

  • 400VALIDATION_FAILED`name` is blank — see `error.details`.
  • 409CONSTRAINT_VIOLATION`name` is longer than 255 characters.
bash
curl -X PUT "https://api.cx.na6iq.com/api/v1/contact-lists/42" \
  -H "Authorization: Bearer $NATIQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "VIP customers — Jordan",
  "description": "Gold-plan customers in Jordan"
}'
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/contact-lists/42', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "VIP customers — Jordan",
    "description": "Gold-plan customers in Jordan"
  }),
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
const data = await res.json()
python
import os, requests

res = requests.put(
    "https://api.cx.na6iq.com/api/v1/contact-lists/42",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
    json={
      "name": "VIP customers — Jordan",
      "description": "Gold-plan customers in Jordan"
    },
)
res.raise_for_status()
data = res.json()
Response200
json
{
  "id": 7,
  "name": "VIP customers — Jordan",
  "description": "Gold-plan customers in Jordan",
  "memberCount": 128
}

Delete a contact list

Deletes the list. The contacts in it are not deleted.

Requires contacts:write

Path parameters

  • listIdintegerrequired
    The list’s id.

Returns

204The list is deleted.

Errors

  • 404CONTACT_LIST_NOT_FOUNDNo list with this ID in your organisation.
bash
curl -X DELETE "https://api.cx.na6iq.com/api/v1/contact-lists/42" \
  -H "Authorization: Bearer $NATIQ_TOKEN"
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/contact-lists/42', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
  },
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
python
import os, requests

res = requests.delete(
    "https://api.cx.na6iq.com/api/v1/contact-lists/42",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
)
res.raise_for_status()

List members

Returns a page of the contacts in the list, as short summaries. Retrieve a full record with Retrieve a contact.

Requires contacts:read Offset paginated

Path parameters

  • listIdintegerrequired
    The list’s id.

Query parameters

  • pageinteger
    Zero-based page number. Default 0.
  • sizeinteger
    Page size. Default 20; keep it at 100 or below.

Returns

200A page of results.

Errors

  • 404CONTACT_LIST_NOT_FOUNDNo list with this ID in your organisation.
bash
curl -X GET "https://api.cx.na6iq.com/api/v1/contact-lists/42/members?page=0&size=25" \
  -H "Authorization: Bearer $NATIQ_TOKEN"
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/contact-lists/42/members?page=0&size=25', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
  },
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
const data = await res.json()
python
import os, requests

res = requests.get(
    "https://api.cx.na6iq.com/api/v1/contact-lists/42/members?page=0&size=25",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
)
res.raise_for_status()
data = res.json()
Response200
json
{
  "data": [
    {
      "id": 1842,
      "displayName": "Layla Haddad",
      "email": "layla@example.com",
      "phone": "+962791234567",
      "status": "customer"
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1
}

Add a contact to a list

Puts one contact in the list. There is no body. Adding a contact that is already in the list is a no-op and still answers 204. To add many contacts, call it once per contact — there is no bulk endpoint.

Requires contacts:write

Path parameters

  • listIdintegerrequired
    The list’s id.
  • contactIdintegerrequired
    The contact’s id.

Returns

204The contact is in the list.

bash
curl -X POST "https://api.cx.na6iq.com/api/v1/contact-lists/42/members/42" \
  -H "Authorization: Bearer $NATIQ_TOKEN"
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/contact-lists/42/members/42', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
  },
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
python
import os, requests

res = requests.post(
    "https://api.cx.na6iq.com/api/v1/contact-lists/42/members/42",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
)
res.raise_for_status()

Remove a contact from a list

Takes the contact out of the list. The contact itself is kept. A contact that is not in the list also answers 204.

Requires contacts:write

Path parameters

  • listIdintegerrequired
    The list’s id.
  • contactIdintegerrequired
    The contact’s id.

Returns

204The contact is out of the list.

bash
curl -X DELETE "https://api.cx.na6iq.com/api/v1/contact-lists/42/members/42" \
  -H "Authorization: Bearer $NATIQ_TOKEN"
js
const res = await fetch('https://api.cx.na6iq.com/api/v1/contact-lists/42/members/42', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.NATIQ_TOKEN}`,
  },
})
if (!res.ok) throw new Error((await res.json().catch(() => ({}))).error?.message ?? `HTTP ${res.status}`)
python
import os, requests

res = requests.delete(
    "https://api.cx.na6iq.com/api/v1/contact-lists/42/members/42",
    headers={"Authorization": f"Bearer {os.environ['NATIQ_TOKEN']}"},
)
res.raise_for_status()