Pure CallerID provides a simple mechanism for uploading a list file into an existing Engage messaging campaign. The API is secured by using an API token within your workspace. Files must be submitted in valid CSV format as a multi-part file attachment in the HTTP Post request.
Pure CallerID provides a simple mechanism for uploading a list file into an existing campaign. The API is secured by using an API token within your workspace. Files must be submitted in valid CSV format as a multi-part file attachment in the HTTP Post request.
Request structure and payload:
URL: https://core.purecallerid.app/api/public/engage/list/load
Method: POST
Content-Type: multipart/form-data
Security: A custom HTTP header must be included in the POST request. The Header name is "X-API-KEY" and the value passed within this header is one of the encrypted API keys associated with your workspace.
Example HTTP Request:
POST /api/public/engage/list/load HTTP/1.1
Host: core.purecallerid.com
Content-Length: 2673535
Accept: */*
Accept-Encoding: gzip, deflate, br
Cache-Control: no-cache
Content-Type: multipart/form-data; boundary=--------------------------500666498957632650479872
X-Api-Key: 1EfXYOGjUQIZiW7rZpFB7A+i3nDUxcAjczeescc0q4c=
There are 3 input parameters which must be sent along with the HTTP post request.
- campaignId - The Pure CallerID campaign identifier for which the leads will be processed against. This ID can be found within the Campaign Edit modal labeled "ID".
- file - MultiPart file attachment of the CSV containing the leads to be loaded
- processRequest - Stringified JSON that defines the mapping and general settings to be utilized during the list load process. The JSON processRequest format is:
{
"deDupe": false,
"firstRowHeaders": true,
"webhookUrl": "https://my.webhooksite.com/89sjakzi33"
"mappedCols": [
{
"columnIndex":0,
"columnId":"Phone"
},
{
"columnIndex":1,
"columnId":"FirstName"
},
{
"columnIndex":2,
"columnId":"LastName"
},
{
"columnIndex":3,
"columnId":"Address1"
},
{
"columnIndex":4,
"columnId":"City"
},
{
"columnIndex":5,
"columnId":"State"
},
{
"columnIndex":6,
"columnId":"Zip"
},
{
"columnIndex":7,
"columnId":"Email"
}
]
}
- deDupe - true or false if you want to scrub the list for duplicates
- dialerListId - Must match the Identifier of the list within your dialer instance associated with the campaign.
- firstRowHasHeaders - true or false depending on whether the CSV file contains headers
- mappedCols: Array of column mappings where columnIndex is the column in the CSV file being sent to the campaign and columnId is the ID of the column in the dialer that the data point is being mapped to. A columnId of Phone and Zip are required in every request.
- webhookUrl: (optional) - valid HTTPS URL to send status updates to as the list is processing and eventually completed. See webhook payload definition below.
Result and Webhook Payload:
The following object will be returned and the status will always be UPLOADED as the list processing is asynchronous. If you would like to be notified upon completion of the list load process, you can provide a webhook URL in the request payload.
If a webhook URL is provided in the processRequest JSON payload, the Pure CallerID list loader will send HTTP POST requests to the URL specified with a JSON payload describing the list processing request. The "status" property in the JSON can be used to determine whether the list is currently in process, completed processing, or encountered an error.
{
"events": [],
"id": "67c8909c33b2f47101d4dfb7",
"orgId": 1,
"workspaceId": 14,
"messagingCampaignId": "67a64d8a95cca62641af5249",
"name": "test-list-geoff-number.csv",
"status": "UPLOADED",
"metrics": {
"supplied": 0,
"loaded": 0,
"invalid": 0,
"duplicate": 0,
"suppressed": 0,
"litigator": 0,
"tokenError": 0,
"sent": 0,
"delivered": 0,
"failed": 0
},
"carrierBreakDown": {},
"uploaded": "2025-03-05T17:57:47.497Z",
"processingStart": null,
"processingFinish": null,
"processedBy": null,
"webhookUrl": null,
"processingDuration": 0
}