Caller Lists API

Manage the caller lists on a Target or a Campaign. Add and remove numbers on the caller lists.

A Caller List allows you to associate a list of caller numbers with a Target or a Campaign and use these caller numbers when making routing decisions.

A common use case is a “suppressed” numbers list where certain calls should not be sent to this Target or Campaign.

Another common use case is “a book of business” numbers list where a Target has certain clients and they should only receive calls when the caller is on their book of business.

Targets and Campaigns

A caller list lives on either a Target or a Campaign. Everything in this article works the same way for both. Wherever the examples below use /api/v2/targets/:target_id/... you can use /api/v2/campaigns/:campaign_id/... instead and pass a Campaign id.

The examples below use Targets, but the Campaign URLs behave identically. A list is created on, and scoped to, whichever object the URL points at — a Target list and a Campaign list are independent even when they share the same name.

Access

To use the API a postback key should be issued from the type “Caller List Management”. A key can be issued on a single Target, a single Campaign, or on the whole Company (a Company key can manage the lists on any Target or Campaign in that company).

Permissions

The key must also be granted the permissions for the actions you want to perform. A key that is missing the required permission for a request will receive an HTTP 403 Forbidden response. Permissions are set when the key is created or edited.

Because every number, upload and check action loads the caller list first, the key needs caller_list__show in addition to the action-specific permission. For example, downloading the numbers on a list requires both caller_list__show and caller_list_number__index.

Caller List

Caller lists are created on a specific Target or Campaign.

Numbers can be managed on the caller list after creating them.

Create caller list

Send a POST request.

curl -X POST 'https://api.retreaver.com/api/v2/targets/:target_id/caller_lists.json?key=:postback_key_uuid' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer :postback_key_secret_key" \
    -d '{"caller_list": { "name": "suppressed" }}'

Delete a caller list

Send a DELETE request.

curl -X DELETE 'https://api.retreaver.com/api/v2/targets/:target_id/caller_lists/:name.json?key=:postback_key_uuid' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer :postback_key_secret_key"

Deletes the caller list.

Show caller list

Send a GET request.

Shows the name of the caller list along with some metadata.

curl 'https://api.retreaver.com/api/v2/targets/:target_id/caller_lists/:name.json?key=:postback_key_uuid' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer :postback_key_secret_key"

The above command returns JSON structured like this:

{
  "caller_list": {
    "name": "suppressed",
    "caller_listable_type": "Target",
    "caller_listable_id": 43103
  }
}

Caller List Number

Manage the numbers on a caller list — add a number, remove a number, check a single number, or download the whole list.

Listing the numbers on a caller list

Download all the numbers on a caller list as JSON, one page at a time. Use this to export a list or to keep a local copy in sync.

The response is paginated like the rest of the API — the body is a plain array and the page metadata is in the Total, Per-Page and Link response headers. The numbers are returned newest first.

curl 'https://api.retreaver.com/api/v2/targets/:target_id/caller_lists/:name/caller_list_numbers.json?key=:postback_key_uuid&page=1&per_page=100' \
    -H "Authorization: Bearer :postback_key_secret_key"

This action requires the caller_list_number__index permission (in addition to caller_list__show).

The above command returns JSON structured like this:

[
  { "caller_list_number": { "number": "+15855752500", "created_at": "2026-06-10T12:00:00.000Z" } },
  { "caller_list_number": { "number": "+15855752501", "created_at": "2026-06-10T12:00:01.000Z" } }
]

and sets pagination headers like this:

Total: 2
Per-Page: 100
Link: <...caller_list_numbers.json?...&page=2>; rel="next", <...caller_list_numbers.json?...&page=5>; rel="last"

Follow the Link header’s rel="next" to walk through every page until it is no longer present.

Adding a single number to a caller list

curl -X POST 'https://api.retreaver.com/api/v2/targets/:target_id/caller_lists/:name/caller_list_numbers.json?key=:postback_key_uuid' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer :postback_key_secret_key" \
    -d '{"caller_list_number": { "number": "+15855752500" }}'

Response format

API could respond in different formats. Use “.json” for a json response or the Accept: header. If no format is provided the server will default to json.

Deleting a single number from caller list

curl -X DELETE 'https://api.retreaver.com/api/v2/targets/:target_id/caller_lists/:name/caller_list_numbers/+15855752500.json?key=:postback_key_uuid' \
    -H "Authorization: Bearer :postback_key_secret_key"

Checking if a number is on a caller list

curl 'https://api.retreaver.com/api/v2/targets/:target_id/caller_lists/:name/caller_list_numbers/+15855752500.json?key=:postback_key_uuid' \
    -H "Authorization: Bearer :postback_key_secret_key"

If the caller number is on the list there will be an HTTP 200 response showing the number and the number metadata. When the caller number is not on the list there will be an HTTP 404 response and this caller number is not on the caller lists. When a status number of 200 is required even when the caller number is not present on the list, then the endpoint for CallerListChecks could be used.

Caller List Checks

The Caller List Checks endpoint returns a JSON object indicating whether a phone number is present in the caller list.

The preferred approach is to use the Caller List Number endpoint (GET /…/caller_list_numbers/:number). However, some platforms may not handle 404 Not Found responses correctly when a number does not exist. In such cases, the Caller List Checks endpoint provides an alternative — it always returns an HTTP 200 OK response with a status field describing the result.

curl -X POST 'https://api.retreaver.com/api/v2/targets/:target_id/caller_lists/:name/caller_list_checks.json?key=:postback_key_uuid' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer :postback_key_secret_key" \
    -d '{"caller_list_check": { "number": "+15855752500" }}'

The above command returns JSON structured like this:

{
  "status": "present"
}

Create Caller List Check

Endpoint

POST /api/v2/targets/:target_id/caller_lists/:name/caller_list_checks.json

Description

Checks for a caller number.

Params

Response

Caller List Uploads

Mass update caller lists.

Add many numbers to a caller list

curl -X POST 'https://api.retreaver.com/api/v2/targets/:target_id/caller_lists/:name/caller_list_uploads.json?key=:postback_key_uuid' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer :postback_key_secret_key" \
    -d '{
      "caller_list_upload": {
        "numbers": "+15855752500\n15855752501"
      }
    }'

The above command returns JSON structured like this:

{
  "caller_list_upload": {
    "status": "waiting",
    "created_at": "2025-04-30T13:29:40.100+03:00",
    "error_messages": [],
    "clear_before_upload": false,
    "action": "create",
    "csv_file_url": "https://retreaver.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBHUT09IiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--026fb3531e87edb843c5fb432b766e56d3f1a9db/numbers_fb99fc78?disposition=attachment"
  }
}

Remove many numbers from a caller list

Same parameters as Add.

curl -X POST 'https://api.retreaver.com/api/v2/targets/:target_id/caller_lists/:name/caller_list_uploads.json?key=:postback_key_uuid' \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer :postback_key_secret_key" \
    -d '{
      "caller_list_upload": {
        "action": "delete",
        "numbers": "+15855752500\n15855752501"
      }
    }'