Skip to main content

Engage - Lead Management

Updated

Pure CallerID provides a simple mechanism for searching and deleting leads in your Engage SMS campaigns. The API is secured using an API token that can be created and managed within your workspace.

Search Leads

Search for one or more leads in an Engage Messaging Campaign by phone number. The result returns the post-processing representation of each matching lead.

URL: https://core.purecallerid.app/api/public/engage/lead/search

Method: GET

Content-Type: application/json

Security: A custom HTTP header must be included in the request. The header name is X-API-KEY and the value is one of the encrypted API keys associated with your workspace.

Required URL Params

  • campaignId – Unique Id of the Engage campaign you are querying.
  • phone – The phone number to search (E.164 or digits).

A successful response will return an array of matching lead records (zero or more):

[
  {
    "id": "68d924e28e4dad3e2ec2a4xx",
    "orgId": 1,
    "workspaceId": 14,
    "messagingCampaignId": "68ce79e6eb059948f5eff3xx",
    "messagingListId": "68d924de8e4dad3e2ec2a4xx",
    "status": "DELIVERED",
    "statusMessage": null,
    "carrier": "CELLCO PARTNERSHIP DBA VERIZON WIRELESS ",
    "normalizedCarrier": "Verizon Wireless",
    "phone": "+15555551213",
    "fromNumber": "+17165279548",
    "timeZone": "America/New_York",
    "zip": "12866",
    "state": "NY",
    "lat": 43.075993,
    "lon": -73.774821,
    "leadData": {
      "Zip": "12833",
      "Phone": "15555551213"
    },
    "created": "2025-09-28T12:06:58.570Z",
    "sent": "2025-09-28T12:07:12.675Z",
    "result": "2025-09-28T12:07:18.997Z",
    "retryAfter": null,
    "conversationStarted": false,
    "responseIntention": null,
    "disposition": null,
    "dispositionTimestamp": null
  }
]
  • status – Current processing state of the lead within the campaign (e.g., READY, DELIVERED).
  • carrier / normalizedCarrier – The line’s reported and normalized mobile provider.
  • leadData – Field/value pairs originally loaded for the lead (e.g., Phone, Zip, FirstName, etc.).

Delete Lead(s)

Delete a single lead by its unique lead Id or delete all leads that match a given phone number within the specified campaign.

URL: https://core.purecallerid.app/api/public/engage/lead/delete

Method: DELETE

Content-Type: application/json

Security: Include the X-API-KEY header with a valid workspace API key. 

  • campaignId – Unique Id of the Engage campaign the deletion will apply to.
  • id – (Optional) Lead Id to delete a single record.
  • phone – (Optional) Phone number to delete all matching records.

Note: You must provide either id or phone. If neither is provided, the request will return an error.

A synchronous response will be returned indicating the outcome of the delete request:

{
  "success": true,
  "message": "Deleted 1 lead",
  "recordsDeleted": 1
}
  • success – true if the delete action completed without error, otherwise false.
  • message – Human-readable description of the outcome (e.g., number of records deleted or reason for failure).
  • recordsDeleted – Count of lead records removed.

Error Example (missing id/phone):

{
  "success": false,
  "message": "Either leadId or phone must be provided",
  "recordsDeleted": 0
}

Headers

  • X-API-KEY – Required. Your workspace API key for authentication.

Quick cURL Examples

Search by phone:

curl -X GET "https://core.purecallerid.app/api/public/engage/lead/search?campaignId=68ce79e6eb059948f5effxxx&phone=5555551212" \
  -H "X-API-KEY: YOUR_API_KEY"

Delete by lead Id:

curl -X DELETE "https://core.purecallerid.app/api/public/engage/lead/delete?campaignId=68ce79e6eb059948f5effxxx&id=68d924e28e4dad3e2ec2axxx" \
  -H "X-API-KEY: YOUR_API_KEY"

Delete by phone:

curl -X DELETE "https://core.purecallerid.app/api/public/engage/lead/delete?campaignId=68ce79e6eb059948f5effxxx&phone=5555551212" \
  -H "X-API-KEY: YOUR_API_KEY"

Summary

  • Search Leads – GET /api/public/engage/lead/search: find campaign leads by phone number.
  • Delete Lead(s) – DELETE /api/public/engage/lead/delete: remove by lead Id or by phone number.

Related articles