Skip to content
Get an API key
Reference

Contacts

6 endpoints in this family.

List contacts

GET/api/v1/contacts

Returns the people this workspace has talked to, searchable by name, phone number or email.

Query parameters

  • qstring

    Search by name, phone number or email.

  • consentstring

    Only contacts with this broadcast consent: in (recorded), out (withdrawn), unknown (never asked).

    inoutunknown

  • blockedboolean

    true keeps only blocked contacts.

  • channelstring

    Only contacts who have a conversation on this channel type (for example whatsapp).

  • scopestring

    account for the contacts of every client of your account, each with its client (a key that sees every client).

    account

  • limitinteger

    How many to return.

  • cursorstring

    Opaque cursor from the previous page.

Response

A page of contacts.

  • data.itemsContact[]

    The contacts, newest first.

  • data.nextCursorstring

    Pass it as cursor for the next page; null at the end.

  • data.hasMoreboolean

    Whether another page exists.

  • data.totalinteger

    How many match, on the first page only; null after.

curl https://nodium.io/api/v1/contacts \ -H "Authorization: Bearer $NODIUM_KEY"

Response

200 OK
{ "data": { "items": [ {} ], "nextCursor": "…", "hasMore": true, "total": 0 }}

Create a contact

POST/api/v1/contacts

Creates someone before they have written. A contact needs at least one identity — a phone number or an email address — otherwise nothing can ever reach them.

If that identity is already known, the existing contact is returned rather than duplicated.

Body

  • displayNamestring

    Their name, as you want it displayed.

  • phonestring

    Phone number in E.164 form.

  • emailstring

    Email address.

Response

The contact.

Refusals

  • 422no_identityNeither a phone number nor an email address was given.
curl -X POST https://nodium.io/api/v1/contacts \ -H "Authorization: Bearer $NODIUM_KEY" \ -H "Content-Type: application/json" \ -d '{ "phone": "+33612345678" }'

Response

200 OK
{ "data": { "contact": { "id": "…", "displayName": "…", "phone": "…", "email": "…", "externalId": "…", "optInAt": "…", "optOutAt": "…", "blocked": true, "conversationCount": 0, "createdAt": "…", "updatedAt": "…" } }}

Get one contact

GET/api/v1/contacts/{id}

Returns the contact with all their identities and their conversations.

Path parameters

  • idstring

    The contact id.

Response

The contact.

curl https://nodium.io/api/v1/contacts/<id> \ -H "Authorization: Bearer $NODIUM_KEY"

Response

200 OK
{ "data": { "contact": { "id": "…", "displayName": "…", "phone": "…", "email": "…", "externalId": "…", "optInAt": "…", "optOutAt": "…", "blocked": true, "conversationCount": 0, "createdAt": "…", "updatedAt": "…" } }}

Update a contact

PATCH/api/v1/contacts/{id}

Changes the name, the consent (optIn) or the block flag (blocked). Fields you leave out keep their value.

Blocking also blocks at WhatsApp, on every WhatsApp number of the client this contact has a conversation with: the person can no longer write to it. WhatsApp only blocks someone who wrote to the number in the last 24 hours; when it refuses, the contact stays blocked in Nodium (nothing is sent, their messages are discarded) and whatsappBlock says which number refused and why. Unblocking works at any time.

Path parameters

  • idstring

    The contact id.

Body

  • displayNamestring

    Their name.

  • optInboolean

    true records the broadcast consent, false withdraws it.

  • blockedboolean

    true blocks the contact: nothing is sent to them, their messages are discarded.

Response

The contact, updated.

  • data.contactContact
  • data.whatsappBlockobject[]

    Only when blocked was sent: one line per WhatsApp number, channelId, ok and error (WhatsApp's reason when it refused).

curl -X PATCH https://nodium.io/api/v1/contacts/<id> \ -H "Authorization: Bearer $NODIUM_KEY" \ -H "Content-Type: application/json" \ -d '{ "displayName": "…", "optIn": true }'

Response

200 OK
{ "data": { "contact": { "id": "…", "displayName": "…", "phone": "…", "email": "…", "externalId": "…", "optInAt": "…", "optOutAt": "…", "blocked": true, "conversationCount": 0, "createdAt": "…", "updatedAt": "…" }, "whatsappBlock": [ {} ] }}

Export contacts as CSV

GET/api/v1/contacts/export

Returns the contacts of your workspace as a CSV file (UTF-8), with the same filters as GET /contacts. At most 10,000 rows: narrow the filters beyond that. Columns: id, name, phone, email, external_id, consent (in, out or unknown), blocked, conversations, created_at, updated_at.

Query parameters

  • qstring

    Search by name, phone number or email.

  • consentstring

    Only contacts with this broadcast consent.

    inoutunknown

  • blockedboolean

    true keeps only blocked contacts.

  • channelstring

    Only contacts who have a conversation on this channel type.

Response

The CSV file.

curl https://nodium.io/api/v1/contacts/export \ -H "Authorization: Bearer $NODIUM_KEY"

Returns the file itself, not wrapped: its type is in Content-Type.

Erase a person, for good

DEL/api/v1/privacy/contacts/{id}

Irreversible. Deletes the contact, their identities, their messages and their conversations. Meant for a right-to-erasure request.

What is kept is what carries no personal data: counters, and the record that an erasure happened. The call returns a report of what was removed.

Path parameters

  • idstring

    The contact id.

Response

A report: what was erased, and how much of it.

  • data.erasedboolean

    Always true.

  • data.removedobject

    Counts removed: identities, conversations, messages, files (stored media).

  • data.emptiedobject

    Counts kept for deduplication but emptied of their content: providerEvents, eventLog, webhookDeliveries.

curl -X DELETE https://nodium.io/api/v1/privacy/contacts/<id> \ -H "Authorization: Bearer $NODIUM_KEY"

Response

200 OK
{ "data": { "erased": true, "removed": {}, "emptied": {} }}