Contacts API
List contacts
Query parameters
Default 50
Returns
200 with the fields below.
One page of contacts, newest first.
12 properties
The contact's id.
The contact's number in E.164 format, such as `+14155550100`. Unique within your organization.
Your own fields for this contact, as key-value pairs. Empty when there are none.
True when the number is on your do-not-call list. Outbound calls to it are refused.
First name.
Last name.
Email address.
IANA time zone, such as `America/New_York`.
How the contact was added, such as `api` or `import`.
ISO 8601 time the contact was created.
ISO 8601 time the contact last changed.
The lists the contact belongs to. Not included when listing contacts.
2 properties
The list's id.
The list's name.
How many contacts match the filters, across all pages.
Pass as `cursor` to get the next page. Null on the last page.
curl "https://api.dialgem.com/v1/contacts" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"contacts": [
{
"id": "string",
"phone": "+14155550123",
"first_name": "string",
"last_name": "string",
"email": "user@example.com",
"timezone": "string",
"attributes": {},
"source": "string",
"do_not_call": false,
"created_at": "string",
"updated_at": "string",
"lists": [
{}
]
}
],
"total": 0,
"next_cursor": "string"
}Create contact
Request body application/json
Returns
201 with the fields below.
The contact's id.
The contact's number in E.164 format, such as `+14155550100`. Unique within your organization.
Your own fields for this contact, as key-value pairs. Empty when there are none.
True when the number is on your do-not-call list. Outbound calls to it are refused.
First name.
Last name.
Email address.
IANA time zone, such as `America/New_York`.
How the contact was added, such as `api` or `import`.
ISO 8601 time the contact was created.
ISO 8601 time the contact last changed.
The lists the contact belongs to. Not included when listing contacts.
2 properties
The list's id.
The list's name.
curl -X POST "https://api.dialgem.com/v1/contacts" \
-H "X-API-Key: $DIALGEM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+14155550123"
}'{
"id": "string",
"phone": "+14155550123",
"first_name": "string",
"last_name": "string",
"email": "user@example.com",
"timezone": "string",
"attributes": {},
"source": "string",
"do_not_call": false,
"created_at": "string",
"updated_at": "string",
"lists": [
{
"id": "string",
"name": "Example"
}
]
}Get contact by phone
The contact with this number. It is matched as E.164, so `(212) 220-0001` with `default_country=US` finds `+12122200001`. 404 if the organization has no such contact.
Path parameters
Query parameters
Returns
200 with the fields below.
The contact's id.
The contact's number in E.164 format, such as `+14155550100`. Unique within your organization.
Your own fields for this contact, as key-value pairs. Empty when there are none.
True when the number is on your do-not-call list. Outbound calls to it are refused.
First name.
Last name.
Email address.
IANA time zone, such as `America/New_York`.
How the contact was added, such as `api` or `import`.
ISO 8601 time the contact was created.
Show 4 more parameters
ISO 8601 time the contact last changed.
The lists the contact belongs to. Not included when listing contacts.
2 properties
The list's id.
The list's name.
How many calls to or from this number are in your call log.
ISO 8601 start time of the most recent call. Null when there are none.
curl "https://api.dialgem.com/v1/contacts/by-phone/PHONE" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"id": "string",
"phone": "+14155550123",
"first_name": "string",
"last_name": "string",
"email": "user@example.com",
"timezone": "string",
"attributes": {},
"source": "string",
"do_not_call": false,
"created_at": "string",
"updated_at": "string",
"lists": [
{
"id": "string",
"name": "Example"
}
]
}Get contact
Path parameters
Returns
200 with the fields below.
The contact's id.
The contact's number in E.164 format, such as `+14155550100`. Unique within your organization.
Your own fields for this contact, as key-value pairs. Empty when there are none.
True when the number is on your do-not-call list. Outbound calls to it are refused.
First name.
Last name.
Email address.
IANA time zone, such as `America/New_York`.
How the contact was added, such as `api` or `import`.
ISO 8601 time the contact was created.
Show 4 more parameters
ISO 8601 time the contact last changed.
The lists the contact belongs to. Not included when listing contacts.
2 properties
The list's id.
The list's name.
How many calls to or from this number are in your call log.
ISO 8601 start time of the most recent call. Null when there are none.
curl "https://api.dialgem.com/v1/contacts/CONTACT_ID" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"id": "string",
"phone": "+14155550123",
"first_name": "string",
"last_name": "string",
"email": "user@example.com",
"timezone": "string",
"attributes": {},
"source": "string",
"do_not_call": false,
"created_at": "string",
"updated_at": "string",
"lists": [
{
"id": "string",
"name": "Example"
}
]
}Update contact
Path parameters
Request body application/json
Returns
200 with the fields below.
The contact's id.
The contact's number in E.164 format, such as `+14155550100`. Unique within your organization.
Your own fields for this contact, as key-value pairs. Empty when there are none.
True when the number is on your do-not-call list. Outbound calls to it are refused.
First name.
Last name.
Email address.
IANA time zone, such as `America/New_York`.
How the contact was added, such as `api` or `import`.
ISO 8601 time the contact was created.
ISO 8601 time the contact last changed.
The lists the contact belongs to. Not included when listing contacts.
2 properties
The list's id.
The list's name.
curl -X PATCH "https://api.dialgem.com/v1/contacts/CONTACT_ID" \
-H "X-API-Key: $DIALGEM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+14155550123"
}'{
"id": "string",
"phone": "+14155550123",
"first_name": "string",
"last_name": "string",
"email": "user@example.com",
"timezone": "string",
"attributes": {},
"source": "string",
"do_not_call": false,
"created_at": "string",
"updated_at": "string",
"lists": [
{
"id": "string",
"name": "Example"
}
]
}Delete contact
Erase the contact and its list memberships.
Path parameters
Returns
200 with the fields below.
The id that was deleted.
Always true on success.
curl -X DELETE "https://api.dialgem.com/v1/contacts/CONTACT_ID" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"id": "string",
"deleted": false
}List a contact's calls
Calls to or from this contact's number, newest first. Summaries, not transcripts.
Path parameters
Query parameters
Default 25
Returns
200 with the fields below.
How many calls to or from this number are in your call log.
The most recent calls, newest first, up to `limit`.
9 properties
The call's id.
The agent on the call.
`inbound` or `outbound`.
The call's status.
ISO 8601 start time.
ISO 8601 end time. Null while the call is in progress.
Length of the call in seconds.
Why the call ended.
The call summary, when call analysis produced one.
curl "https://api.dialgem.com/v1/contacts/CONTACT_ID/calls" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"total": 0,
"calls": [
{
"id": "string",
"agent_id": "agent_123",
"direction": "string",
"status": "string",
"started_at": "string",
"ended_at": "string",
"duration_s": 0,
"disconnection_reason": "string",
"summary": "string"
}
]
}Inspect a CSV file
Read the file's header and a few rows so the caller can map columns. Imports nothing.
Request body application/json
Returns
200 with the fields below.
The file's column names.
How many data rows the file has.
The suggested column for each contact field, keyed by field name.
Columns that would be kept as custom attributes.
The first few rows, keyed by column name.
curl -X POST "https://api.dialgem.com/v1/contacts/imports/inspect" \
-H "X-API-Key: $DIALGEM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"csv": "string"
}'{
"headers": [
"string"
],
"row_count": 0,
"mapping": {},
"attribute_columns": [
"string"
],
"sample": [
{}
]
}List imports
Returns
200 with the fields below.
Your 20 most recent imports, newest first.
19 properties
The import's id.
`queued`, `running`, `previewed` (a dry run waiting to be applied), `completed`, `failed`, `cancelled` or `expired`.
True when the import only validates and writes nothing.
Rows in the file. Zero until processing starts.
Contacts created.
Existing contacts updated.
Rows skipped because the contact already exists and `on_duplicate` is `skip`.
Rows rejected. Fetch them from the errors route.
True when more rows were rejected than are kept for download.
The file name you gave, if any.
Show 9 more parameters
Why the import failed. Null otherwise.
The column used for each contact field.
Columns kept as custom attributes.
Two-letter country used for numbers without a country code.
`update` or `skip`: what happens to a number that already exists.
The list the imported contacts are added to, if any.
ISO 8601 time the import was created.
ISO 8601 time processing started. Null until then.
ISO 8601 time the import finished. Null until then.
curl "https://api.dialgem.com/v1/contacts/imports" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"imports": [
{
"id": "string",
"status": "string",
"dry_run": false,
"filename": "string",
"total_rows": 0,
"created": 0,
"updated": 0,
"skipped": 0,
"errors": 0,
"errors_truncated": false,
"failure": "string",
"mapping": {}
}
]
}Create import
Request body application/json
Default "update"
Default false
Returns
202 with the fields below.
The import's id.
`queued`, `running`, `previewed` (a dry run waiting to be applied), `completed`, `failed`, `cancelled` or `expired`.
True when the import only validates and writes nothing.
Rows in the file. Zero until processing starts.
Contacts created.
Existing contacts updated.
Rows skipped because the contact already exists and `on_duplicate` is `skip`.
Rows rejected. Fetch them from the errors route.
True when more rows were rejected than are kept for download.
The file name you gave, if any.
Show 9 more parameters
Why the import failed. Null otherwise.
The column used for each contact field.
Columns kept as custom attributes.
Two-letter country used for numbers without a country code.
`update` or `skip`: what happens to a number that already exists.
The list the imported contacts are added to, if any.
ISO 8601 time the import was created.
ISO 8601 time processing started. Null until then.
ISO 8601 time the import finished. Null until then.
curl -X POST "https://api.dialgem.com/v1/contacts/imports" \
-H "X-API-Key: $DIALGEM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"csv": "string"
}'{
"id": "string",
"status": "string",
"dry_run": false,
"filename": "string",
"total_rows": 0,
"created": 0,
"updated": 0,
"skipped": 0,
"errors": 0,
"errors_truncated": false,
"failure": "string",
"mapping": {}
}Get import
Path parameters
Returns
200 with the fields below.
The import's id.
`queued`, `running`, `previewed` (a dry run waiting to be applied), `completed`, `failed`, `cancelled` or `expired`.
True when the import only validates and writes nothing.
Rows in the file. Zero until processing starts.
Contacts created.
Existing contacts updated.
Rows skipped because the contact already exists and `on_duplicate` is `skip`.
Rows rejected. Fetch them from the errors route.
True when more rows were rejected than are kept for download.
The file name you gave, if any.
Show 9 more parameters
Why the import failed. Null otherwise.
The column used for each contact field.
Columns kept as custom attributes.
Two-letter country used for numbers without a country code.
`update` or `skip`: what happens to a number that already exists.
The list the imported contacts are added to, if any.
ISO 8601 time the import was created.
ISO 8601 time processing started. Null until then.
ISO 8601 time the import finished. Null until then.
curl "https://api.dialgem.com/v1/contacts/imports/IMPORT_ID" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"id": "string",
"status": "string",
"dry_run": false,
"filename": "string",
"total_rows": 0,
"created": 0,
"updated": 0,
"skipped": 0,
"errors": 0,
"errors_truncated": false,
"failure": "string",
"mapping": {}
}Cancel import
Stop an import that has not finished. Contacts already written by a running import stay.
Path parameters
Returns
200 with the fields below.
The import's id.
`queued`, `running`, `previewed` (a dry run waiting to be applied), `completed`, `failed`, `cancelled` or `expired`.
True when the import only validates and writes nothing.
Rows in the file. Zero until processing starts.
Contacts created.
Existing contacts updated.
Rows skipped because the contact already exists and `on_duplicate` is `skip`.
Rows rejected. Fetch them from the errors route.
True when more rows were rejected than are kept for download.
The file name you gave, if any.
Show 9 more parameters
Why the import failed. Null otherwise.
The column used for each contact field.
Columns kept as custom attributes.
Two-letter country used for numbers without a country code.
`update` or `skip`: what happens to a number that already exists.
The list the imported contacts are added to, if any.
ISO 8601 time the import was created.
ISO 8601 time processing started. Null until then.
ISO 8601 time the import finished. Null until then.
curl -X DELETE "https://api.dialgem.com/v1/contacts/imports/IMPORT_ID" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"id": "string",
"status": "string",
"dry_run": false,
"filename": "string",
"total_rows": 0,
"created": 0,
"updated": 0,
"skipped": 0,
"errors": 0,
"errors_truncated": false,
"failure": "string",
"mapping": {}
}List import errors
The rows an import rejected, with what each contained. ``format=csv`` is the file to fix and re-upload.
Path parameters
Query parameters
Default "json"
Default 200
Returns
200 with the fields below.
Rejected rows, in file order. With `format=csv` the response is a CSV file instead.
3 properties
The row number in the file.
Why the row was rejected.
What the row contained, keyed by column name.
How many rows were rejected.
True when `errors` holds fewer rows than were rejected.
curl "https://api.dialgem.com/v1/contacts/imports/IMPORT_ID/errors" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"errors": [
{
"row": 0,
"error": "string",
"values": null
}
],
"total": 0,
"truncated": false
}Commit import
Apply a previewed import to the contacts. The file is read again, so what is applied is what was previewed.
Path parameters
Returns
202 with the fields below.
The import's id.
`queued`, `running`, `previewed` (a dry run waiting to be applied), `completed`, `failed`, `cancelled` or `expired`.
True when the import only validates and writes nothing.
Rows in the file. Zero until processing starts.
Contacts created.
Existing contacts updated.
Rows skipped because the contact already exists and `on_duplicate` is `skip`.
Rows rejected. Fetch them from the errors route.
True when more rows were rejected than are kept for download.
The file name you gave, if any.
Show 9 more parameters
Why the import failed. Null otherwise.
The column used for each contact field.
Columns kept as custom attributes.
Two-letter country used for numbers without a country code.
`update` or `skip`: what happens to a number that already exists.
The list the imported contacts are added to, if any.
ISO 8601 time the import was created.
ISO 8601 time processing started. Null until then.
ISO 8601 time the import finished. Null until then.
curl -X POST "https://api.dialgem.com/v1/contacts/imports/IMPORT_ID/commit" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"id": "string",
"status": "string",
"dry_run": false,
"filename": "string",
"total_rows": 0,
"created": 0,
"updated": 0,
"skipped": 0,
"errors": 0,
"errors_truncated": false,
"failure": "string",
"mapping": {}
}List lists
Returns
200 with the fields below.
Your lists, sorted by name.
6 properties
The list's id.
The list's name. Unique within your organization.
How many contacts are in the list.
What the list is for.
ISO 8601 time the list was created.
ISO 8601 time the list last changed.
curl "https://api.dialgem.com/v1/contact-lists" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"lists": [
{
"id": "string",
"name": "Example",
"description": "string",
"member_count": 0,
"created_at": "string",
"updated_at": "string"
}
]
}Create list
Request body application/json
Returns
201 with the fields below.
The list's id.
The list's name. Unique within your organization.
How many contacts are in the list.
What the list is for.
ISO 8601 time the list was created.
ISO 8601 time the list last changed.
curl -X POST "https://api.dialgem.com/v1/contact-lists" \
-H "X-API-Key: $DIALGEM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Example"
}'{
"id": "string",
"name": "Example",
"description": "string",
"member_count": 0,
"created_at": "string",
"updated_at": "string"
}Get list
Path parameters
Returns
200 with the fields below.
The list's id.
The list's name. Unique within your organization.
How many contacts are in the list.
What the list is for.
ISO 8601 time the list was created.
ISO 8601 time the list last changed.
curl "https://api.dialgem.com/v1/contact-lists/LIST_ID" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"id": "string",
"name": "Example",
"description": "string",
"member_count": 0,
"created_at": "string",
"updated_at": "string"
}Update list
Path parameters
Request body application/json
Returns
200 with the fields below.
The list's id.
The list's name. Unique within your organization.
How many contacts are in the list.
What the list is for.
ISO 8601 time the list was created.
ISO 8601 time the list last changed.
curl -X PATCH "https://api.dialgem.com/v1/contact-lists/LIST_ID" \
-H "X-API-Key: $DIALGEM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Example"
}'{
"id": "string",
"name": "Example",
"description": "string",
"member_count": 0,
"created_at": "string",
"updated_at": "string"
}Delete list
Path parameters
Returns
200 with the fields below.
The id of the deleted list. The contacts in it are kept.
Always true on success.
curl -X DELETE "https://api.dialgem.com/v1/contact-lists/LIST_ID" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"id": "string",
"deleted": false
}Add members
Path parameters
Request body application/json
Returns
200 with the fields below.
The list's id.
How many contacts were newly added. Contacts already in the list are not counted.
How many contacts are in the list now.
curl -X POST "https://api.dialgem.com/v1/contact-lists/LIST_ID/members" \
-H "X-API-Key: $DIALGEM_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contact_ids": [
"string"
]
}'{
"id": "string",
"added": 0,
"member_count": 0
}Remove member
Path parameters
Returns
200 with the fields below.
The list's id.
How many contacts are in the list now.
curl -X DELETE "https://api.dialgem.com/v1/contact-lists/LIST_ID/members/CONTACT_ID" \
-H "X-API-Key: $DIALGEM_API_KEY"{
"id": "string",
"member_count": 0
}