Guides

Contacts

Keep each project's phonebook in step with your own systems, by number.

Each project has a phonebook: the people it calls, one entry per number, with the details an agent may say about them. It is the phonebook the console shows, and what it holds reaches two places — a campaign started from it in the console, and an inbound call whose agent fills its fields from the phonebook.

Reading it needs contacts:read; changing it needs contacts:write and a live key, because these are real people. A test key reads nobody. A phonebook belongs to its whole project, so a key limited to some agents cannot reach it.

Add someone

Add someone to the phonebook

#!/bin/sh
# Add someone to the phonebook. With a live key: the phonebook holds real people.
curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/contacts" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY" \
  --json '{
  "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
  "phone": "+12025550131",
  "name": "Sara Haddad",
  "attributes": {
    "first_name": "Sara",
    "member_since": "2023"
  },
  "timezone": "America/New_York"
}'

Field	What it is
`phone`	Their number, in international format. One entry per number in a project.
`name`	What the console calls them. The agent never says it — it says what its placeholders take.
`attributes`	What an agent may say about them. Its `{{placeholders}}` take these by name: `first_name` fills `{{first_name}}`. Kept as text — `3` as `"3"`, `true` as `"yes"`.
`timezone`	Where they are, like `Asia/Riyadh`: a campaign's calling hours are read there.

A number already in the project's phonebook is 409 contact_exists. To add or update many people at once, import them.

Find someone, and change them

Find someone in the phonebook by their number

#!/bin/sh
# Find someone in the phonebook by their number
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/contacts?phone=+12025550131" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

Read a contact

#!/bin/sh
# Read a contact
curl -sS --fail-with-body -X GET "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

Change a contact

#!/bin/sh
# Change a contact. attributes is replaced whole: send every one they should have.
curl -sS --fail-with-body -X PATCH "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY" \
  --json '{
  "attributes": {
    "first_name": "Sara",
    "member_since": "2021"
  }
}'

A change keeps every field you do not send. attributes is replaced whole, so send all of them. A campaign already made keeps the details it copied; the next campaign and the next call read the new ones.

Import a list

Import a list into the phonebook

#!/bin/sh
# Import a list into the phonebook. Matched by number: people already there are updated, so sending it again is safe.
curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/contacts/import" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY" \
  --json '{
  "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
  "contacts": [
    {
      "phone": "+12025550132",
      "name": "Omar Nasser",
      "attributes": {
        "first_name": "Omar"
      }
    },
    {
      "phone": "+12025550133",
      "name": "Lina Saleh",
      "attributes": {
        "first_name": "Lina"
      }
    }
  ]
}'

Up to 1,000 people a request, matched by number, with or without its +: +966501234567 and 966501234567 are one person. A number already there takes the new details, or is left as it is and counted as skipped when you send update_existing: false. A row that does not fit — not a number, not a time zone, the same number twice — is listed in errors by its place in contacts, and the rest are taken, so sending a corrected list again is how you fix one.

Delete someone

Delete a contact

#!/bin/sh
# Delete a contact. Calls already made to them stay where they are.
curl -sS --fail-with-body -X DELETE "https://api.aigently.ai/v1/contacts/5d7f9b1c-3e5a-4c7e-9b1d-3f5a7c9e1b3d" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY"

They leave every group they were in. The calls already made to them stay where they are.