Skip to main content

Multi-Part (Bulk) Form List Upload

Updated

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.

URL: https://api.purecallerid.app/api/public/lists/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/lists/load HTTP/1.1
Host: api.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.

  1. 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".
  2. file - MultiPart file attachment of the CSV containing the leads to be loaded
  3. processRequest - Stringified JSON that defines the mapping and general settings to be utilized during the list load process.  The JSON processRequest format is:
{
"mode": "REPLACE",
"dialerListId": "Test List",
"firstRowHasHeaders": false,
"webhookUrl":"https://tls-proxy.ngrok.io/test",
"mappedCols":[
  {
    "columnIndex": 0,
    "columnId": "number1"
  },
  {
     "columnIndex": 1,
     "columnId": "zip"
  }
 ]
}
  • mode - APPEND or REPLACE - controls whether the contents of the dialer list should be appended to or deleted and re-loaded with the new file. This functionality is only applicable to the Five9 integration.
  • 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
  • webhookUrl: (optional) - valid HTTPS URL to send status updates to as the list is processing and eventually completed.  See webhook payload definition below.
  • mappedCols: Array of column mappings where columnIndex is the column in the CSV file being sent to the dialer and columnId is the ID of the column in the dialer that the data point is being mapped to.


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. 

Valid values for the "status" property are:

  • UPLOADED - File has been uploaded to the secure file system
  • QUEUED - List processing request is queued for processing
  • PROCESSING - List is currently being processed and records are being incrementally delivered to the dialer
  • ERROR - An error has occurred during processing and the list did not complete sending all records to the dialer
  • FINALIZED - The list has completed processing successfully

 

The metrics data can be used to determine the counts of leads that were sent in the list and how many were successfully transmitted to the dialer.

  • valid - clean number delivered to the dialer
  • invalid - phone number was malformed or not 10 digits
  • inactive - phone number is not currently in service (data boost tier-0)
  • dnc - phone number is currently on a federal, state, or tcpa watch list (data boost tier-1)
  • total - sum all of numbers provided


The JSON provided in both the webhook and as the response body of the initial HTTP request is as follows:

{
  "events": [
     {
       "timestamp": "2023-07-24T16:22:43.615Z",
       "type": "INFO",
       "message": "list successfully loaded."
     },
     {
       "timestamp": "2023-07-24T16:21:28.715Z",
       "type": "INFO",
       "message": "Starting processing"
     },
     {
       "timestamp": "2023-07-24T16:21:28.581Z",
       "type": "INFO",
       "message": "Queued for processing"
     }
  ],
"id": "64bea5059eeb965380fc2d56",
"orgId": 1,
"workspaceId": 1,
"campaignId": "64bea458113cb476419c560b",
"dialerListId": "Alpha List",
"firstRowHeaders": true,
"name": ATTEMPT.csv",
"uploaded": "2023-07-24T16:21:23.679Z",
"status": "FINALIZED",
"metrics": {
   "valid": 0,
   "invalid": 12430,
   "inactive": 0,
   "dnc": 0,
   "total": 12430
},
"mode": "REPLACE",
"processingStart": "2023-07-24T16:21:28.715Z",
"processingFinish": "2023-07-24T16:22:43.615Z",
"processedBy": {
"id": "64be9f3183fbc9f26c7abeb1",
"firstName": "API",
"lastName": "USER",
"email": "api-user@workspace.com"
},
"mapping": [
  {
    "columnIndex": 0,
    "columnId": "number1"
  },
  {
    "columnIndex": 1,
    "columnId": "zip"
  },
  {
    "columnIndex": 2,
    "columnId": "Five9ColumnId3"
  }
],
"webhookUrl": "https://webhooktest.test.com/test",
"processingDuration": 74
}

 

Dialer Specific Implementations

Five9

All records added via this API will be inserted into the Five9 dialer platform without duplicate checking. Records are subject to the Default dialing order. Please refer to Five9 documentation for more information on fieldEntry keys and modes referenced to ensure intended functionality.

Required: Phone and all Lead Key fields

Optional: leadKeyFields, crmUpdateMode, crmAddMode, and listAddMode are optional fields that may be included in the request body. If these fields are not included the request will be processed with the default values.

  • Lead Key Fields: default values are set on the Workspace
    • If a value has not been set on the Workspace, a default of "number1" will be used to match leads based on phone number
    • One or more alternative dialer fields may by supplied instead, and all lead keys specified will be required to have mapped field values included in the request
  • CRM Update Mode: UPDATE_ALL
    • Alternative options: UPDATE_FIRST, UPDATE_SOLE_MATCHES, DONT_UPDATE
  • CRM Add Mode: ADD_NEW
    • Alternative option: DONT_ADD
  • List Add Mode: ADD_ALL
    • Alternative options: ADD_FIRST, ADD_IF_SOLE_CRM_MATCH
{
  "mode": "REPLACE",
  "dialerListId": "Test List",
  "firstRowHasHeaders": false,
  "webhookUrl":"https://tls-proxy.ngrok.io/test",
  "leadKeyFields": [
    "number1", 
    "zip"
  ],
  "crmUpdateMode": "UPDATE_ALL",
  "crmAddMode": "ADD_NEW",
  "listAddMode": "ADD_ALL",
  "mappedCols":[
    {
      "columnIndex": 0,
      "columnId": "number1"
    },
    {
      "columnIndex": 1,
      "columnId": "zip"
    }
  ]
}

RingCX

Dedupe is required and may be supplied one of the following values:

  • RING_REMOVE_ALL_EXISTING
  • RING_REMOVE_FROM_LIST
  • RING_RETAIN_ALL
{
"mode": "APPEND",
"dialerListId": "Test List",
"dedupe":"RING_RETAIN_ALL",
"mappedCols":[
  {
    "columnIndex": 0,
    "columnId": "leadPhone"
  },
  {
    "columnIndex": 1,
    "columnId": "zip"
  },
  {
    "columnIndex": 2,
    "columnId": "externId"
  }
 ]
}

Related articles