Company do not call (DNC) list endpoints

The company DNC (do not call) list lets you block direct, manual outbound calls as well as outbound and scheduled calls created by the Apps API.

CCAI Platform Apps API provides the following three endpoints for DNC:

Add phone numbers to DNC list.
Remove phone numbers from DNC list.
Check whether a phone number is in the DNC list.

Add phone numbers to the DNC list

Parameter	Required	Data Type	Definition
contacts	TRUE	Array contacts	An array of contacts. Each contact has a `phone_number` attribute and optional `expires_at` attribute

Endpoint:

Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/outbound_dialer/dnc

Headers:

Key	Value	Description
Content-Type	application/json

Body:

{
    "contacts": [
        {
            "phone_number": "+1-7187309219",
            "expires_at": "2022-10-29 00:00:00 UTC"
        },
        {
            "phone_number": "+1-(358)-213-1634"
        }
    ]
}

Example request and responses

The following sections provide example requests to the endpoint.

Add some contacts to the DNC list

This example shows the adding of contacts to the DNC list.

Request

Headers:

Key	Value	Description
Content-Type	application/json

Body:

{
    "contacts": [
        {
            "phone_number": "+1-7187309219",
            "expires_at": "2022-10-29 00:00:00 UTC"
        },
        {
            "phone_number": "+1-(358)-213-1634"
        },
        {
            "phone_number": "+1-4151113333",
            "expires_at": "2022-10-30 00:00:00 UTC"
        },
        {
            "phone_number": "+1-4151115555"
        },
        {
            "phone_number": "+1-7187309219",
            "expires_at": "2022-10-27 00:00:00 UTC"
        },
        {
            "phone_number": "sssssss"
        },
        {
            "phone_number": "911",
            "expires_at": "2023-02-05 00:00:00 UTC"
        }
    ]
}

Response

[
    {
        "phone_number": "+1-7187309219",
        "expires_at": "2022-10-29 00:00:00 UTC",
        "status": "created"
    },
    {
        "phone_number": "+1-(358)-213-1634",
        "status": "created"
    },
    {
        "phone_number": "+1-4151113333",
        "expires_at": "2022-10-30 00:00:00 UTC",
        "status": "updated"
    },
    {
        "phone_number": "+1-4151115555",
        "status": "updated"
    },
    {
        "phone_number": "+1-7187309219",
        "expires_at": "2022-10-27 00:00:00 UTC",
        "error": "expires_at cannot be past date/time",
        "status": "failed"
    },
    {
        "phone_number": "sssssss",
        "error": "phone_number is invalid",
        "status": "failed"
    },
    {
        "phone_number": "911",
        "expires_at": "2023-02-05 00:00:00 UTC",
        "error": "emergency phone number is not allowed",
        "status": "failed"
    }
]

Code: 200

Remove numbers from the DNC list

Parameter	Required	Data Type	Definition
phone_numbers	TRUE	Array String	An array containing phone numbers that should be removed from the DNC list.

Endpoint:

Method: POST
Type: RAW
URL: https://{subdomain}.{domain}/apps/api/v1/outbound_dialer/dnc/remove

Headers:

Key	Value	Description
Content-Type	application/json

Body:

{
    "phone_numbers": [
        "1-415-111-1111"
    ]
}

Example request and responses

The following sections provide example requests to the endpoint.

Remove a list of phone numbers

This example shows how to remove phone numbers from the list.

Request

Headers:

Key	Value	Description
Content-Type	application/json

Body:

{
    "phone_numbers": [
        "1-415-111-1111",
        "1-415-222-2222",
        "1-415-333-333-3333"
    ]
}

Response: Success

{}

Status Code: 200

Check whether a phone number is on the DNC list

Parameter	Required	Data Type	Definition
phone_number	TRUE	String	The phone number to check if it is in the DNC list

Endpoint:

Method: GET
Type: 
URL: URL: https://{subdomain}.{domain}/apps/api/v1/outbound_dialer/dnc/check?phone_number={phone_number}

Headers:

None

Body:

None

Example request and responses

The following sections provide example requests to the endpoint.

Check if number is in the DNC list

This example showes how to check if a phone number is in the DNC list.

Request

Key	Value
phone_number	{PHONE_NUMBER} (Number) The end-user's phone number.

GET https://{subdomain}.{domain}/apps/api/v1/outbound_dialer/dnc/check?phone_number={PHONE_NUMBER}

Response

{
"phone_number": "1-415-111-1111",
"expired_at": "2023-08-05 22:02:36.362009 +0000"
"do_not_call": true
}

Code: 200