Documentation

API Reference
All Docs

Contacts

Your contact database — profiles, notes, tags, lists, and segmentation.

Overview

Contacts is the central database of everyone your bots interact with. A contact is created automatically when someone messages your bot for the first time, or you can create contacts manually, import from CSV, sync from WhatsApp, or capture via voice recording. The database is shared across all bots and sessions in your organization — a contact who talks to Bot A and Bot B has separate conversations but one shared profile. Two APIs serve contacts: the Bot API (per-bot actions at /api/v1/bot-api/actions) and the Account API (org-scoped at /api/v1/account/contacts).

Create a Contact

Create a contact from the dashboard, via the Bot API actions endpoint, or via the Account API. The phone number is the unique identifier — if a contact with the same phone already exists the call updates it instead of duplicating.

curl -X POST https://neuron-api.dlvh.site/api/v1/bot-api/actions \
  -H "Authorization: Bearer nrn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "save_contact",
    "params": {
      "phone": "+2348012345678",
      "name": "Amara Okafor",
      "email": "[email protected]",
      "tags": ["vip", "lagos"]
    }
  }'

Update a Contact

Update any field on an existing contact. The Bot API identifies the contact by phone; the Account API uses the contact's UUID. Tags, notes, and suppression flags can all be set this way.

# Identify by phone
curl -X POST https://neuron-api.dlvh.site/api/v1/bot-api/actions \
  -H "Authorization: Bearer nrn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "update_contact",
    "params": {
      "phone": "+2348012345678",
      "name": "Amara O.",
      "tags": ["vip", "lagos", "premium"]
    }
  }'

Import & Export

Import contacts in bulk or export your entire database. Both operations are Account API only (org-scoped, not per-bot). The import endpoint accepts a JSON array of contact objects — each with phone, name, and optional email, tags, and notes. Existing contacts matched by phone are updated rather than duplicated. The export endpoint returns a CSV download.

Import and export via Account API

# Import contacts
curl -X POST https://neuron-api.dlvh.site/api/v1/account/contacts/import \
  -H "Authorization: Bearer nrn_acc_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone": "+2348012345678", "name": "Amara Okafor", "tags": "vip,lagos" },
      { "phone": "+2349087654321", "name": "Chidi Eze", "email": "[email protected]" }
    ]
  }'

# Export all contacts as CSV
curl https://neuron-api.dlvh.site/api/v1/account/contacts/export \
  -H "Authorization: Bearer nrn_acc_your_token" \
  -o contacts.csv

Syncing from WhatsApp

Pull contacts from your connected WhatsApp sessions into Neuron. Go to Contacts and use the sync feature to import contacts from a specific session. This imports names and phone numbers from the WhatsApp contact list on that device. You can also trigger a sync via the neuron_sync_whatsapp_contacts MCP tool.

Contact Properties

Each contact stores the following fields:

  1. 1

    Phone

    The unique identifier, stored in digits-only format.

  2. 2

    Name

    Display name, auto-populated from the WhatsApp profile when available.

  3. 3

    Email

    Optional, for cross-channel reference.

  4. 4

    Tags

    String labels for categorization (e.g. "vip", "new-lead", "lagos"). Used by flows, broadcasts, and list filters.

  5. 5

    Notes

    Structured note entries with semantic embeddings. Each note records its source (user, bot, audio, import, system, flow) and is searchable via AI-powered semantic search. Notes are append-only — adding a note never overwrites previous ones.

  6. 6

    Do-not-broadcast

    When flagged, the contact is excluded from all broadcasts.

  7. 7

    Do-not-auto-respond

    When flagged, the bot will not auto-respond to this contact (manual and API sends still work).

Voice Contact Capture

Record a voice memo describing a contact — name, phone number, email, notes — and Neuron transcribes the audio, extracts structured contact fields using AI, and saves the contact automatically. Available from the Contacts page and via the neuron_audio_contact MCP tool.

The MCP tool neuron_audio_contact accepts a file path or URL to an audio recording and returns the created contact — useful for hands-free capture from your IDE.

Contact Lists Overview

Contact lists group contacts for broadcasts, campaigns, and flows. Three types exist: Static lists are manually curated — add and remove members by hand or via API. Dynamic lists are rule-based or AI-powered — define criteria (tag filters, conditions) and/or an AI prompt, and Neuron re-evaluates membership on a schedule (manual, daily, weekly, or on-access). Merged lists are a virtual union of two or more lists, deduplicated — they can be a live window (stays in sync) or a materialized snapshot. The system-protected "Do Not Contact" list cannot be deleted.

Create a Contact List

Create a static, dynamic, or merged list. For dynamic lists, provide filter rules and/or an AI prompt. For merged lists, pass the IDs of the source lists. Both the Bot API and Account API support list creation.

curl -X POST https://neuron-api.dlvh.site/api/v1/bot-api/actions \
  -H "Authorization: Bearer nrn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "create_contact_list",
    "params": {
      "name": "Lagos VIPs",
      "description": "High-value contacts in Lagos",
      "type": "static"
    }
  }'

Update a Contact List

Update a list's name, description, or filter criteria. The Bot API uses the actions payload; the Account API accepts a PUT with the list ID or slug in the URL.

curl -X POST https://neuron-api.dlvh.site/api/v1/bot-api/actions \
  -H "Authorization: Bearer nrn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "update_contact_list",
    "params": {
      "listId": "list-uuid",
      "name": "Lagos Premium VIPs",
      "description": "Updated description"
    }
  }'

Delete a Contact List

Delete a list by ID or slug. The contacts themselves are not deleted — only the list grouping is removed. The system-protected "Do Not Contact" list cannot be deleted.

curl -X POST https://neuron-api.dlvh.site/api/v1/bot-api/actions \
  -H "Authorization: Bearer nrn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "delete_contact_list",
    "params": { "listId": "list-uuid" }
  }'

Add Members to a List

Add one or more contacts to a static list. The Bot API accepts phone numbers; the Account API accepts an entries array with contactId or phone per entry.

curl -X POST https://neuron-api.dlvh.site/api/v1/bot-api/actions \
  -H "Authorization: Bearer nrn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "add_to_contact_list",
    "params": {
      "listId": "list-uuid",
      "phones": ["+2348012345678", "+2349087654321"]
    }
  }'

Remove Members from a List

Remove one or more contacts from a static list. The Bot API accepts phone numbers; the Account API accepts an array of contact UUIDs.

curl -X POST https://neuron-api.dlvh.site/api/v1/bot-api/actions \
  -H "Authorization: Bearer nrn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "remove_from_contact_list",
    "params": {
      "listId": "list-uuid",
      "phones": ["+2348012345678"]
    }
  }'

Get List Members

Retrieve all members of a contact list with pagination. Both APIs support this — the Account API also accepts the list slug instead of UUID.

curl -X POST https://neuron-api.dlvh.site/api/v1/bot-api/actions \
  -H "Authorization: Bearer nrn_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "get_contact_list_members",
    "params": { "listId": "list-uuid", "page": 1, "limit": 50 }
  }'