Skip to main content

Real Time - Batch Lead Loading

Updated

In addition to the Single Lead Loading API, Pure CallerID provides a batch mechanism for uploading multiple lead records in a single request. The API is secured by using an API token that can be created and managed within your workspace.

Batch Lead Loading is designed for real time lead generation workflows that produce leads in groups, where making one HTTP request per lead is inefficient. Up to 1,000 leads may be submitted per request. Leads are processed in parallel, and the request is processed synchronously — the response contains an individual Accepted or Rejected result for every lead in the batch, returned in the same order the leads were submitted.

Note: Batch Lead Loading is only available for workspaces configured with the Universal / Premise Connector. Requests made against workspaces using other dialer integrations will be rejected. For all other dialer types, please use the Single Lead Loading API.

 

URL: https://core.purecallerid.app/api/public/lead/load/batch

Method: POST

Content-Type: application/json

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.

 

{
   "campaignId": "65ae6e4b6bf35b2344b109e5",
   "dialerListId": "demoList001",
   "listName": "Real Time Leads - Jan 2024",
   "leads": [
      {
         "fields": [
            {
               "value": "55555551212",
               "dialerField": "phone",
               "type": "Phone"
            },
            {
               "value": "12345",
               "dialerField": "zip",
               "type": "Zip"
            },
            {
               "value": "John",
               "dialerField": "first_name"
            },
            {
               "value": "Doe",
               "dialerField": "last_name"
            }
         ]
      },
      {
         "fields": [
            {
               "value": "55555551313",
               "dialerField": "phone",
               "type": "Phone"
            },
            {
               "value": "54321",
               "dialerField": "zip",
               "type": "Zip"
            },
            {
               "value": "Jane",
               "dialerField": "first_name"
            },
            {
               "value": "Smith",
               "dialerField": "last_name"
            }
         ]
      }
   ]
}

 

  • campaignId - Unique Id of the Pure CallerID campaign the leads will be loaded against. This value can be found when editing a campaign.
  • dialerListId - Must match the Identifier of the list within your dialer instance associated with the campaign.
  • listName - The organizational list name in Pure CallerID that the leads will be loaded into. Note, that this is internal to Pure CallerID and is not related to the dialer list.
  • leads - An array of lead objects. A minimum of 1 and a maximum of 1,000 leads may be included in a single request. Each lead object contains:
    • fields - An array of Field objects that define the lead data
      • field.value - the value of the field. Typically this is the actual name, phone number, zip code, address, etc of the lead.
      • field.dialerField - The dialer column that the field value is to be mapped to
      • field.type - Possible values are "Phone", "Zip", "City", "State", "VeriskLeadId", "TrustedFormCert". A valid Phone is required on all leads. Zip is optional, but recommended and allows the Community CallerID module to map a geographically relevant phone number to the lead. In the event that Zip is not provided, City and State will be used instead. If the data is not a Phone, Zip, City, State, or Token, the type value can be left out of the field element.

 

Batch Requirements

  • Uniform field layout - Every lead in the batch must contain the same fields, in the same order, as the first lead in the batch. The list mapping is created once from the first lead and applied to the entire batch. Any lead that does not match the field layout of the first lead will be individually rejected; the rest of the batch will still be processed.
  • Batch size - The batch must contain between 1 and 1,000 leads. Requests outside of this range are rejected in their entirety.
  • Duplicate prevention - If Duplicate Prevention is enabled on the campaign, duplicate phone numbers within the same batch are automatically rejected. The first occurrence of the phone number is processed and subsequent occurrences are returned with a Rejected status and a reason of DUPLICATE.
  • Webhooks - If a Real Time List Load webhook is configured, a single webhook event containing the full batch response is sent per batch (not one event per lead).

 

A synchronous response will be returned to inform the calling party of the outcome of each lead in the batch. Results are returned in the same order the leads were submitted.

{
   "status": "Completed",
   "message": null,
   "campaignId": "65ae6e4b6bf35b2344b109e5",
   "listId": "681b2fb449ecf659d4a",
   "listName": "Real Time Leads - Jan 2024",
   "submitted": 2,
   "accepted": 1,
   "rejected": 1,
   "results": [
      {
         "index": 0,
         "status": "Accepted",
         "reason": null,
         "message": "OK",
         "lead": {
            "orgId": 1,
            "workspaceId": 14,
            "campaignId": "65ae6e4b6bf35b2344b109e5",
            "listId": "681b2fb449ecf659d4a",
            "phone": "+15555551212",
            "zip": "12345",
            "city": null,
            "state": null,
            "callerId": "+19706329562",
            "status": "LOADED",
            "loaded": "2026-07-23T10:21:28.562Z",
            "fields": [
               "5555551212",
               "12345",
               "John",
               "Doe"
            ]
      },
      {
         "index": 1,
         "status": "Rejected",
         "reason": "DUPLICATE",
         "message": "Duplicate phone number",
         "lead": null
      }
   ]
}

 

  • status - The overall result of the batch request. "Completed" means the batch was processed and per-lead results are available in the results array. "Rejected" means the entire batch was refused (for example, the workspace is not a Universal Connector workspace, the batch was empty, or the batch exceeded 1,000 leads) and the message field will describe why.
  • message - A human-friendly error description when the entire batch is rejected; null when the batch was processed.
  • campaignId - Echo of the campaign the batch was loaded against.
  • listId - Unique ID of the Pure CallerID list the leads were loaded into.
  • listName - The name of the Pure CallerID list the leads were loaded into.
  • submitted - The total number of leads received in the request.
  • accepted - The number of leads that were successfully accepted.
  • rejected - The number of leads that were rejected.
  • results - An array containing one result per submitted lead, in the same order the leads were submitted. Each result contains:
    • index - The zero-based position of the lead in the submitted leads array, allowing each result to be matched back to its original lead.
    • status - "Accepted" or "Rejected" for this individual lead.
    • reason - A machine-readable rejection code (e.g. DUPLICATE, INVALID, DNC, FAILED) when the lead is not accepted; null when no error occurred.
    • message - A human-friendly status message, usually "OK" on success or an error description on failure.
    • lead - The payload object for the individual lead record, identical in structure to the lead object returned by the Single Lead Loading API (including validationResult, doNotCallResult, stateDoNotCallResult, and knownLitigatorCheck when those features are enabled on the campaign). Please refer to the Single Lead Loading article for the complete field-by-field description.