A campaign refers to an outbound auto-dialer feature that sequentially reaches out to a list of contacts, initiates outbound calls, and connects each contact to an available agent. Campaign endpoints provide access to campaign-related data, allowing retrieval of campaign and contact objects.
Campaign object represents a single campaign within the platform.
Contact object represents an individual campaign contact within a specific campaign.
Campaign endpoints let users to add, update, and delete contacts of an existing campaign. The available endpoints include:
Campaign contact status
The status field can be in any of the following states:
| Campaign Contact Status | Description |
|---|---|
| Upcoming | Contact is next to be dialed. |
| Dialing | Contact is right now being dialed. |
| Queued | Call for a given contact is queued. |
| Connected | Contact is connected with an agent. |
| Finished | Call has completed. |
| Transferred | Call has been transferred. |
| Transferred and Finished | Call has been transferred and then completed. |
| Not Picked Up | No answer from end user or never reached the end user. |
| Not Reached to Contact | Call never reached the contact. |
| Abandoned by Contact | For preview, end user hangs up before connected to an agent. For both progressive and predictive, end user hangs up the call within 5 seconds after connecting to the agent. |
| Skipped | Contact has been skipped by agent and will be available to be connected to another agent. |
| Skipped & Closed | On Preview, agent skips and close a contact. This contact should now be always skipped in this campaign. |
| Invalid Number | Contact with invalid phone number. |
| Carrier Error | This error is driven by carrier. |
| Abandoned by Dialer | Contact has been abandoned by dialer. |
| Voicemail Hung Up | On Predictive, the dialer determines the end user is a machine (ie. voicemail). |
| Dialer General Error | Call failed due to dialer error. |
| Redial Scheduled | Temporary status. Redial scheduled in the future. |
| Do Not Call | The number was in Do-Not-Call number list. |
| Invalid Outbound Number | Contact with invalid outbound number. |
| Blocked Phone Number | Contact with invalid/blocked international number. |
Add a single contact to a campaign
| Parameter | Required | Data Type | Definition |
|---|---|---|---|
| campaign_id | TRUE | Integer | The ID of the campaign to add a contact to. |
Endpoint:
Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/outbound_dialer/campaigns/{campaign_id}/contacts
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"name": "string",
"email": "customer@somedomain.com",
"phone_number": "+1 111-111-1111",
"outbound_number": "+1 760-867-5309",
"external_unique_id": "UID_123456"
}
Example request and responses
The following sections provide example requests to the endpoint.
Add single contact to a campaign
This example demonstrates how to add a contact to a specific campaign ID.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| campaign_id | integer | The ID of the campaign to add the contact to |
Body:
{
"name": "string",
"email": "customer@somedomain.com",
"phone_number": "+1 111-111-1111",
"outbound_number": "+1 760-867-5309",
"external_unique_id": "UID_123456"
}
Response
{
"valid_contacts": [
{
"name": "string",
"email": "customer@somedomain.com",
"phone_number": "+1 111-111-1111",
"outbound_number": "+1 760-867-5309",
"external_unique_id": "UID_123456"
}
],
"invalid_contacts": []
}
Status Code: 200
Get contacts for a campaign
| Parameter | Required | Data Type | Definition |
|---|---|---|---|
| campaign_id | TRUE | Integer | The ID of the campaign to retrieve the contacts from. |
Endpoint:
Method: GET
Type:
URL: https://{subdomain}.{domain}/apps/api/v1/outbound_dialer/campaigns/{campaign_id}/contacts
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| campaign_id | integer | The ID of the campaign to add the contact to |
Example request and responses
The following sections provide example requests to the endpoint.
Get contacts for a campaign
The following example demonstrates how to retrieve the contacts for the given campaign ID.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| campaign_id | integer | Campaign ID of the campaign to query |
Response
[
{
"name": "string",
"email": "customer@somedomain.com",
"phone_number": "+1 111-111-1111",
"outbound_number": "+1 760-867-5309",
"external_unique_id": "UID_123456"
}
]
Status Code: 200
Import multiple contacts to a campaign
| Parameter | Required | Data Type | Definition |
|---|---|---|---|
| file | TRUE | String | json file containing the multiple contacts to add to a campaign. |
| campaign_id | TRUE | Integer | The ID of the campaign to add the contacts to. |
Endpoint:
Method: POST
Type: FORM DATA
URL: https://{subdomain}.{domain}/apps/api/v1/outbound_dialer/campaigns/{campaign_id}/contacts/import
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | multipart/form-data |
Body:
'FORM DATA'
File content:
[
{
"name": "string",
"email": "customer@somedomain.com",
"phone_number": "+1 111-111-1111",
"outbound_number": "+1 760-867-5309",
"external_unique_id": "UID_123456"
}
]
Example request and responses
The following sections provide example requests to the endpoint.
Import multiple contacts from a file
This example demonstrates the adding of contacts to a campaign based on a file being posted to the endpoint. The file is posted as form data.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | multipart/form-data |
Query:
| Key | Value | Description |
|---|---|---|
| campaign_id | integer | Campaign ID to add the contacts to |
File content:
[
{
"name": "string",
"email": "customer@somedomain.com",
"phone_number": "+1 111-111-1111",
"outbound_number": "+1 760-867-5309",
"external_unique_id": "UID_123456"
}
]
Response
None
Status Code: 202 (Accepted)
Jobs
| Parameter | Required | Data Type | Definition |
|---|---|---|---|
| job_id | TRUE | Integer | The job ID that you want to retrieve |
| campaign_id | TRUE | Integer | The campaign ID that the job ID belongs to. |
Endpoint:
Method: GET
Type:
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/outbound_dialer/campaigns/{campaign_id}/contacts/jobs/{job_id}
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Example request and responses
The following sections provide example requests to the endpoint.
Successfully completed
The following example demonstrates how to retrieve the job and identify if they have been successfully completed.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| campaign_id | 1 | The campaign ID that the job belongs to |
| job_id | 530 | The job ID to check the status of |
Response
{
"id": 530,
"status": "completed",
"type": "Jobs::Bulk::Campaign::ParentJob"
}
Status Code: 200
Importing still in progress
The following example demonstrates how to retrieve the job and identify if the importation is still ongoing.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| campaign_id | 1 | The campaign ID that the job belongs to |
| job_id | 530 | The job ID to check the status of |
Response
{
"id": 530,
"status": "in_progress",
"type": "Jobs::Bulk::Campaign::ParentJob"
}
Status Code: 200
Failed job
The following example demonstrates how to retrieve the job and identify if the job has failed.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Query:
| Key | Value | Description |
|---|---|---|
| campaign_id | 1 | The campaign ID that the job belongs to |
| job_id | 523 | The job ID to check the status of |
Response
{
"error_details": "NativePowerDial::ContactService::DuplicateContactPhoneOnCampaign",
"error_message": "Internal Error",
"id": 523,
"status": "failed",
"type": "Jobs::Bulk::Campaign::StartImport"
}
Status Code: 200
Update a single contact
| Parameter | Required | Data Type | Definition |
|---|---|---|---|
| campaign_id | TRUE | Integer | The campaign ID that the job ID belongs to. |
Endpoint:
Method: PATCH
Type: RAW
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/outbound_dialer/campaigns/{campaign_id}/contact
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"contact_id": 16312,
"name": "string",
"email": "customer@somedomain.com",
"phone_number": "+1 111-111-1111",
"external_unique_id": "UID_123456"
}
Example request and responses
The following sections provide example requests to the endpoint.
Update a contact for a campaign
This example demonstrates how to update a contact that is in a specific campaign.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"contact_id": 7,
"name": "Bob Smith",
"email": "customer@somedomain.com",
"phone_number": "+1 111-111-1111",
"external_unique_id": "UID_123456"
}
Response
{
"id": 7,
"name": "Bob Smith",
"campaign_id": 6,
"assigned_call_id": null,
"assigned_participant_id": null,
"outbound_number": "+1-(201)-471-6992",
"priority": null,
"created_at": "2024-08-05T14:51:49.000Z",
"updated_at": "2024-08-05T21:01:16.000Z",
"status": "Upcoming",
"user_custom_metadata": {
"NAME (REQUIRED)": "Bob Smith",
"PHONE (REQUIRED)": "+1 111-111-1111",
"EMAIL (REQUIRED)": "customer@somedomain.com"
}
}
Status Code: 200
Remove single contact
| Parameter | Required | Data Type | Definition |
|---|---|---|---|
| campaign_id | TRUE | Integer | The campaign ID that the job ID belongs to. |
Endpoint:
Method: DELETE
Type: RAW
URL: https://{{subdomain}}.{{domain}}/apps/api/v1/outbound_dialer/campaigns/{campaign_id}/contact
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"contact_id": integer,
"phone_number": "string",
"external_unique_id": "string"
}
Example request and responses
The following sections provide example requests to the endpoint.
Remove a contact by contact ID
This example demonstrates how to remove a contact from a campaign based on the contact ID of the contact.
Request
Headers:
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json |
Body:
{
"contact_id": 7,
}
Query:
| Key | Value | Description |
|---|---|---|
| campaign_id | 1 | The campaign ID that the job belongs to |
Response
{
"id": 7,
"name": "Bob Smith",
"campaign_id": 6,
"assigned_call_id": null,
"assigned_participant_id": null,
"outbound_number": "+1-(201)-471-6992",
"priority": null,
"created_at": "2024-08-05T14:51:49.000Z",
"updated_at": "2024-08-05T21:01:16.000Z",
"status": "Upcoming",
"user_custom_metadata": {
"NAME (REQUIRED)": "Bob Smith",
"PHONE (REQUIRED)": "+1 111-111-1111",
"EMAIL (REQUIRED)": "customer@somedomain.com"
}
}
Status Code: 200