Add and manage contacts

Contacts are the people an outbound agent calls, texts, or emails. Each contact belongs to one agent and carries a name, one or more phone numbers (or an email address), and any custom fields your script uses as variables. You can add contacts from a CSV file, type them in by hand, or send them from your own systems through the API (see the Manage contacts API guide).

Contacts are added to outbound agents only. Inbound agents create a record for each incoming call automatically, so the Add Contact button is not shown for them.

Before you start: required columns

Every agent needs a few columns for each contact. The upload screen lists them under “The file must include the following columns”.

Agent type	Always required	Also required
Voice and text	`name`, `phoneNumber`	Every variable used in the script
Email	`name`, `email`	Every variable used in the script

Variables are required when they appear in any published version of the script (or in the draft, if nothing is published yet). Two kinds of variables are optional, and appear as (Optional) columns:

Variables filled by a pre-conversation action.
Call data variables, such as the current date or the dialed number.

See Variables for how columns become variables.

Import contacts from a CSV file

Agent page header showing the agent name, a Running status badge, and the Edit, Test, and Add Contact buttons — The agent header with the Add Contact button that opens the import window.

Open the import window

Go to Agents, open your agent, and click Add Contact. If you’ve imported before, the window opens on Import History. Click Add to start a new import.

Prepare your file

On the Import File tab, click Download Sample CSV to get a file that already has the right headers for this agent. Fill it in using Google Sheets, Excel, or any spreadsheet tool, and save it as CSV.

Upload the file

Drop the file on the upload area or click Select file. Callers checks that the file is a CSV, isn’t empty, and has every required column. If anything is missing you’ll see a Validation Error message naming the problem.

Check the preview

The preview shows the first 10 rows so you can confirm the columns line up. Click Confirm & Upload to start the import, or Cancel to pick another file.

Wait for processing

The import runs in the background. The window shows live progress and the number of contacts Added, Updated, and Failed. You can close the window; the import continues and appears in Import History.

Contact Imports window on the Import File tab with a drop zone, a Select file button, the list of required columns, and a Download Sample CSV link — The Import File tab with the upload area, the required columns, and the Download Sample CSV link.

CSV formatting rules

Only .csv files are accepted. Export Excel or Google Sheets files as CSV first.
Header names are matched to variables. Callers converts each header to camelCase, so Phone Number, phone-number, and PhoneNumber all become phoneNumber, and Property Address becomes propertyAddress. Underscores are kept as they are, so phone_number does not match phoneNumber. Use spaces, hyphens, or camelCase.
Include the country code on every phone number, for example +1 555 555 1234. Spaces, dashes, and parentheses are fine. A 10-digit number without a country code is retried as a US number.
Every other column is stored as contact data and is available to the script as a variable with the same (camelCased) name.
Empty headers are ignored.

contacts.csv

name,phoneNumber,propertyAddress,email
John Smith,+1 555 555 1234,123 Maple Street,john@example.com
Maria Lopez,+1 555 555 5678,456 Oak Avenue,maria@example.com

Start from Download Sample CSV rather than building headers by hand. It contains exactly the columns this agent needs, including every script variable.

Multiple phone numbers per contact

Add a phoneNumbers column to give one contact several numbers, such as mobile, office, and home. Separate numbers with commas, semicolons, or line breaks, and wrap the cell in double quotes when it contains commas.

contacts.csv

name,phoneNumbers,propertyAddress
John Smith,"+1 555 555 1234,+1 555 555 5678",123 Maple Street
Maria Lopez,"+1 555 555 9999;+1 555 555 0000",456 Oak Avenue

How Callers dials them:

Duplicate numbers in the list are removed. The first valid number becomes the contact’s primary phoneNumber.
Each attempt dials the number that has been tried the fewest times, so attempts rotate through the list in order.
A number that fails (for example, it’s invalid or disconnected) is skipped from then on.
The attempt limit scales with the number of valid numbers. With Total Dial Attempts set to 5 and two valid numbers, the contact can be dialed up to 10 times. See Scheduling and retries.

Import history and failed rows

Import History lists your last 50 imports for the agent, newest first. Each row shows the file name (or Manual Import), the number of contacts, the date, and the result:

Result	Meaning
Pending	The import is queued.
Spinner	The import is processing.
N Added / N Updated	The import finished. Updated means the contact already existed and was refreshed.
N failed	Some rows were rejected. Click it, then Download error details to get a CSV with the reason for each row.
Failed	The whole import failed.

Common reasons a row fails:

Missing required fields: …: a required column is empty for that row.
Invalid phone number(s): …: the number couldn’t be parsed. Add the country code.
Phone number is in the local DNC list: the number is on your account’s Do Not Call list and the agent checks it.
A registry match: the agent checks the US Do Not Call registry and the number is listed.

Contacts with several phone numbers aren’t checked against Do Not Call lists at import. They’re checked each time a number is dialed.

Add contacts manually

Use Add Manually for a handful of contacts, or to add a test contact.

Open the Add Manually tab

Click Add Contact on the agent, then the Add Manually tab.

Fill in the grid

Each required field has a column. Click + to add a custom column (enter a Column title), and Add more to add rows.

Import

Click Finalize Import. The button stays disabled until at least one row has every required field. The result appears in Import History as Manual Import.

Time zones

Callers works out each contact’s time zone from their primary phone number:

US and Canada: from the area code.
Other countries: from the country.

The time zone is shown on the contact’s Contact Info tab. It’s used for scheduling when the agent’s Use Contact’s Time Zone setting is on. See Scheduling and retries. To set a time zone yourself, send the timezone field through the API as an IANA name such as America/Chicago. A timezone column in a CSV file is not used for scheduling; CSV contacts always get the time zone that matches their phone number.

Duplicates

By default, a phone number can appear only once per agent. When you import a number that already exists in the agent:

The existing contact is updated, not skipped. It counts as Updated in the import results.
Its name, data fields, phone numbers, and time zone are replaced with the new values.
Its status and attempt count are kept.
If it was archived, it’s restored.

To keep several contacts with the same phone number, turn on Allow Duplicate Phone Numbers under the agent’s Technical Settings. Every imported row then creates a new contact.

Once Allow Duplicate Phone Numbers is turned on, it can’t be turned off for that agent.

Add contacts with the API

Use the API to push contacts from a CRM, a web form, or your own backend. Both endpoints add contacts to one agent and follow the same duplicate rules as CSV imports: sending an existing phone number updates that contact.

Paths use /agents/{agentId}. The older /campaigns/{campaignId} paths still work and behave the same.

Add one contact

POST https://api.callers.ai/agents/{agentId}/contacts

curl -X POST "https://api.callers.ai/agents/AGENT_ID/contacts" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "phoneNumber": "+15555551234",
    "timezone": "America/New_York",
    "data": {
      "propertyAddress": "123 Maple Street",
      "email": "john@example.com"
    }
  }'

const response = await fetch(
  `https://api.callers.ai/agents/${agentId}/contacts`,
  {
    method: "POST",
    headers: {
      Authorization: process.env.CALLERS_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "John Smith",
      phoneNumber: "+15555551234",
      timezone: "America/New_York",
      data: {
        propertyAddress: "123 Maple Street",
        email: "john@example.com",
      },
    }),
  }
);
const result = await response.json();
console.log(result.data.contactId);

import os
import requests

response = requests.post(
    f"https://api.callers.ai/agents/{agent_id}/contacts",
    headers={"Authorization": os.environ["CALLERS_API_KEY"]},
    json={
        "name": "John Smith",
        "phoneNumber": "+15555551234",
        "timezone": "America/New_York",
        "data": {
            "propertyAddress": "123 Maple Street",
            "email": "john@example.com",
        },
    },
)
print(response.json()["data"]["contactId"])

Response

{
  "status": "success",
  "data": {
    "contactId": "6720f3c2a1b4e5d6f7a8b9c0",
    "created": true,
    "modified": false
  }
}

created is true for a new contact. modified is true when an existing contact with the same phone number was updated.

Add many contacts

POST https://api.callers.ai/agents/{agentId}/contacts/bulk

curl -X POST "https://api.callers.ai/agents/AGENT_ID/contacts/bulk?verbose=true" \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      {
        "name": "John Smith",
        "phoneNumber": "+15555551234",
        "data": { "propertyAddress": "123 Maple Street" }
      },
      {
        "name": "Maria Lopez",
        "phoneNumbers": ["+15555555678", "+15555559999"],
        "data": { "propertyAddress": "456 Oak Avenue" }
      }
    ]
  }'

const response = await fetch(
  `https://api.callers.ai/agents/${agentId}/contacts/bulk?verbose=true`,
  {
    method: "POST",
    headers: {
      Authorization: process.env.CALLERS_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      contacts: [
        {
          name: "John Smith",
          phoneNumber: "+15555551234",
          data: { propertyAddress: "123 Maple Street" },
        },
        {
          name: "Maria Lopez",
          phoneNumbers: ["+15555555678", "+15555559999"],
          data: { propertyAddress: "456 Oak Avenue" },
        },
      ],
    }),
  }
);
const { data } = await response.json();
console.log(`${data.added} added, ${data.modified} updated`);

import os
import requests

response = requests.post(
    f"https://api.callers.ai/agents/{agent_id}/contacts/bulk",
    params={"verbose": "true"},
    headers={"Authorization": os.environ["CALLERS_API_KEY"]},
    json={
        "contacts": [
            {
                "name": "John Smith",
                "phoneNumber": "+15555551234",
                "data": {"propertyAddress": "123 Maple Street"},
            },
            {
                "name": "Maria Lopez",
                "phoneNumbers": ["+15555555678", "+15555559999"],
                "data": {"propertyAddress": "456 Oak Avenue"},
            },
        ]
    },
)
data = response.json()["data"]
print(f"{data['added']} added, {data['modified']} updated")

Response (verbose=true)

{
  "status": "success",
  "data": {
    "requested": 2,
    "added": 2,
    "modified": 0,
    "contactDetails": [
      { "contactId": "6720f3c2a1b4e5d6f7a8b9c0", "phoneNumber": "+15555551234", "status": "created" },
      { "contactId": "6720f3c2a1b4e5d6f7a8b9c1", "phoneNumber": "+15555555678", "status": "created" }
    ]
  }
}

Without verbose, the response has a contactIds array instead of contactDetails.

The bulk endpoint silently drops contacts that are missing a required script variable. Compare requested with added + modified to catch them. The single-contact endpoint returns a 400 error instead.

Contact fields

string

required

Contact name. At least 1 character.

string

Phone number with country code, for example +15555551234. 7–20 characters; digits, +, (, ), and - only. Required unless you send phoneNumbers or an email in data.email.

string[]

Several numbers for one contact, dialed in rotation. Same format rules as phoneNumber.

string

IANA time zone name, such as Europe/London. Abbreviations like EST are rejected. If omitted, the time zone comes from the phone number.

object

Custom fields as string key/value pairs. Keys become script variables. For email agents, put the address in data.email. Limits: up to 100 keys, keys up to 120 characters starting with a letter, $, or _, and 4,000 characters in total.

boolean

default:"false"

Create the contact as archived. Sending false (or leaving it out) for an existing archived contact restores it.

Query parameters

Parameter	Endpoints	What it does	Default
`fixUSPhoneNumber`	Single, bulk	Adds a leading `1` to 10-digit numbers.	`false`
`ignorePhoneNumberValidation`	Single only	Skips phone number format validation.	`false`
`verbose`	Bulk only	Returns `contactDetails` with a per-contact `created` or `updated` status.	`false`

The request body can be up to 1 MB. Split very large lists into several bulk requests.

Contacts can’t be added to inbound agents through the API. The request returns an error.

Manage contacts

Open an agent to see its contacts. Admins can archive, restore, update, and export them.

Archive and restore

Archiving removes a contact from dialing without deleting its history.

One contact: hover over the row and click the archive icon, or open the contact and choose Archive Contact from the ⋯ menu. Confirm with Yes, Archive.
Several contacts: select them with the checkboxes, then click Archive Selected.
Restore: open the Archived tab (shown once any contact is archived), select contacts, and click Restore Selected.

On the account-level Contacts page, archiving a contact archives it in every agent it belongs to. Through the API, use DELETE /agents/{agentId}/contacts/{contactId}, DELETE /agents/{agentId}/contacts/bulk with contactIds, or DELETE /agents/{agentId}/contacts/phone-number/bulk with phoneNumbers. Each accepts an optional archiveReason. To restore a contact through the API, add it again with the same phone number.

Update status in bulk

Correct outcomes after reviewing calls, for example to mark contacts as Interested after a human follow-up.

Select contacts

Select up to 50 contacts. Each one needs a finished conversation, so its status must already be Interested, Not interested, Completed, Call later, Do not call, or Wrong number.

Choose the new status

Click Update Status and pick a status. The list includes your agent’s custom success criteria as well as Interested, Not interested, Call later, Do not call, Wrong number, and Completed. Text agents offer Follow up and Unsubscribed instead of Call later and Do not call.

Export

Click Export contacts (Export calls on inbound agents) to download a CSV of the list. The export uses your current search, status, date, and post-call filters and sort order. The button appears only for admins whose member access includes Export contacts or calls. See Team and permissions.

List contacts with the API

GET /agents/{agentId}/contacts returns the agent’s contacts, 50 per page by default.

Query parameter	What it does
`page`, `perPage`	Pagination. `page` starts at 0; `perPage` defaults to 50.
`statuses`	Filter by contact status.
`goals`	Filter by success criteria name.
`archived`	`true` to list archived contacts. Default `false`.
`lastAttemptFrom`, `lastAttemptTo`	Filter by last attempt time, ISO 8601 in UTC.
`sortAttribute`, `sortDirection`	Sort field and `asc` or `desc`.

Troubleshooting

The upload says a required column is missing, but it's in my file

Check the header spelling. Underscores aren’t converted, so phone_number doesn’t match phoneNumber. Use phoneNumber, Phone Number, or phone-number. Every script variable is also required; download the sample CSV to see the full list.

Rows failed with “Invalid phone number”

Add the country code to each number (for example +44 for the UK). Only 10-digit numbers are retried as US numbers automatically.

My import shows Updated instead of Added

Those phone numbers already exist in the agent, so the existing contacts were updated. Their status and attempt history are kept.

The API returned success but fewer contacts were added

The bulk endpoint drops contacts with missing required variables. Compare requested with added and modified, and fill the missing data keys.

I can't see Add Contact or Export contacts

Both are admin-only. Add Contact is also hidden on inbound agents, and export needs the Export contacts or calls member access.

Scheduling and retries

Control when and how often contacts are dialed.

Variables

Use contact fields in your script.

Do Not Call list

Block numbers that must never be dialed.

Statuses and outcomes

What each contact status means.

Get started

Build your agent

Test and deploy

Voice

Channels

Contacts and outreach

Results and analytics

Human operators

Best practices

Account and administration

Enterprise

Resources

Add and manage contacts

Before you start: required columns

Import contacts from a CSV file

CSV formatting rules

Multiple phone numbers per contact

Import history and failed rows

Add contacts manually

Time zones

Duplicates

Add contacts with the API

Add one contact

Add many contacts

Contact fields

Query parameters

Manage contacts

Archive and restore

Update status in bulk

Export

List contacts with the API

Troubleshooting

Scheduling and retries

Variables

Do Not Call list

Statuses and outcomes

​Before you start: required columns

​Import contacts from a CSV file

​CSV formatting rules

​Multiple phone numbers per contact

​Import history and failed rows

​Add contacts manually

​Time zones

​Duplicates

​Add contacts with the API

​Add one contact

​Add many contacts

​Contact fields

​Query parameters

​Manage contacts

​Archive and restore

​Update status in bulk

​Export

​List contacts with the API

​Troubleshooting

​Related

Scheduling and retries

Variables

Do Not Call list

Statuses and outcomes

Before you start: required columns

Import contacts from a CSV file

CSV formatting rules

Multiple phone numbers per contact

Import history and failed rows

Add contacts manually

Time zones

Duplicates

Add contacts with the API

Add one contact

Add many contacts

Contact fields

Query parameters

Manage contacts

Archive and restore

Update status in bulk

Export

List contacts with the API

Troubleshooting

Related