Contacts

Keep the people your agents call, import them from a CSV, group them in lists, and see how do-not-call applies.

A contact is a person your organization calls. The phone number identifies them, so each number can be a contact once. Contacts live under Contacts in the dashboard, and in the API at /v1/contacts.

Phone numbers

Numbers are stored in international form, +14155552671, however you write them: (415) 555-2671, 415.555.2671 and +1 415 555 2671 are the same contact. A number that does not start with + needs a country, which you give as default_country (a two-letter code such as US or GB). A number that is not valid for its country is refused with a reason rather than stored, so you do not pay to dial numbers that cannot ring.

bash

curl https://api.dialgem.com/v1/contacts \
  -H "X-API-Key: $DIALGEM_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "phone": "(415) 555-2671", "default_country": "US",
    "first_name": "Ada", "email": "ada@example.com",
    "timezone": "America/Chicago",
    "attributes": { "plan": "pro" }
  }'

attributes holds your own fields as text (up to 50, each value up to 500 characters). timezone is an IANA zone name; calling windows will be evaluated in it.

If the number already exists you get a 409 whose body includes the contact_id of the existing contact, so a sync from your CRM can update it instead.

Lists

A list is a named group of contacts: a campaign audience, a segment. Create them with POST /v1/contact-lists, add contacts with POST /v1/contact-lists/{id}/members, and filter contacts with GET /v1/contacts?list_id=.... Deleting a list never deletes the contacts in it.

Do not call

A contact's do_not_call is not stored on the contact. It is read from your organization's do-not-call list every time, the same list Dialgem checks before it places an outbound call, and the same list an agent adds to when someone says "stop calling me". So:

a number your agent adds to the list mid-call shows as do_not_call: true straight away;
a contact's page has a switch that puts the number on, or takes it off, that list;
the contact list can be filtered by do-not-call status.

Taking a number off the list is for when the person has given renewed consent to be called. Deleting a contact does not remove its number from the list.

Import from a CSV

In the dashboard choose Import, pick a file, check the column mapping, and review what will happen before anything is saved. Through the API:

POST /v1/contacts/imports/inspect with { "csv": "..." } returns the headers, a guessed mapping and a few sample rows.
POST /v1/contacts/imports starts the import. Add "dry_run": true to validate only.
Poll GET /v1/contacts/imports/{id} until status is previewed or completed.
For a preview, POST /v1/contacts/imports/{id}/commit applies exactly what it reported.

The import runs in the background, so a file of tens of thousands of rows is fine (limits: 5 MB and 50,000 rows).

How rows are treated:

Situation	What happens
Valid number, new to you	A contact is created.
Number already a contact	Updated with what the row has (`on_duplicate: "update"`, the default) or left alone (`"skip"`). An empty cell never erases a value you already have, and attributes are merged.
The same number twice in the file	The first row wins; later ones are skipped.
Invalid number, email or time zone	The row is rejected and listed in the error report with its line number and what it contained.

Fix rejected rows from GET /v1/contacts/imports/{id}/errors?format=csv, which is a CSV you can correct and upload again. The uploaded file is deleted as soon as the import finishes, and an unconfirmed preview is discarded after 24 hours.

Export

Export on the Contacts page (optionally for one list) downloads every contact as CSV, in the same shape an import reads, with a do_not_call column. Text that a spreadsheet would run as a formula is prefixed with an apostrophe so opening the file is safe.

Who can do what

Any member can add, edit and look up contacts. Import, export and API keys that do either are limited to owners and admins, because they move an entire customer list at once.

Call history

GET /v1/contacts/{id}/calls lists the calls to or from the contact's number, newest first: direction, outcome, duration and the call's summary. It does not include transcripts; open the call for those.