Skip to main content

Engage - Campaign and List Management

Updated

Pure CallerID provides a robust suite of APIs for managing Engage Messaging campaigns, campaign lists, and outbound messaging workflows. The endpoints documented within this article are specific to the Engage Messaging service and allow administrators to retrieve campaign status, manage messaging configurations, and activate or pause approved messaging campaigns and campaign lists programmatically.

These endpoints manage campaign and campaign list state only. Outbound messages already accepted or queued by downstream carriers may not be recoverable once submitted for delivery.

For additional API endpoint documentation and platform services, please visit the full Pure CallerID API library by clicking here.

Campaign Object

Example Response

The response returns the Engage Messaging campaign object, including campaign status, sending status, schedule, message configuration, webhook configuration, notification settings, dispositions, and available campaign fields.

{
  "events": [
    {
      "timestamp": "2025-02-17T21:18:50.891Z",
      "type": "INFO",
      "message": "Initialized"
    }
  ],
  "id": "67b3a7bb0fcd117088ca5020",
  "orgId": 1,
  "workspaceId": 14,
  "name": "New campaign",
  "shardingHashCode": 126739791,
  "created": "2025-02-17T21:18:50.891Z",
  "updated": "2025-04-01T12:35:51.532Z",
  "campaignStatus": "READY",
  "sendingStatus": "IDLE",
  "sendingStatusDescription": null,
  "nextRunTime": null,
  "senderSourceType": "SHORT_CODE",
  "senderSourceId": "b1223d69-714f-4525-aae0-4c2e1dd36fbe",
  "aegisWorkflowId": null,
  "carrierDailyLimits": [],
  "schedule": {
    "monday": [
      {
        "start": 480,
        "end": 1260
      }
    ],
    "tuesday": [
      {
        "start": 480,
        "end": 1260
      }
    ],
    "wednesday": [
      {
        "start": 480,
        "end": 1260
      }
    ],
    "thursday": [
      {
        "start": 480,
        "end": 1260
      }
    ],
    "friday": [
      {
        "start": 480,
        "end": 1260
      }
    ],
    "saturday": [],
    "sunday": [],
    "exceptions": []
  },
  "messages": {
    "outgoingMessage": "Hi {{FirstName}}, this Pure CallerId reaching out to you to see if you would like to participate in our upcoming webinar on trust and compliance in 2025. Would you like to join us?",
    "responseMessage": "",
    "helpMessage": "If you need assistance, please visit https://support.purecallerid.com",
    "stopMessage": "No problem, you have been opted out. If you wish to receive messages again, just reply START.",
    "startMessage": "Awesome. Welcome back!"
  },
  "webhooks": {
    "deliveryResult": null,
    "conversationStarted": null,
    "incomingMessage": null,
    "disposition": null,
    "optOut": null,
    "optIn": null
  },
  "notifications": {
    "sendConversationEmail": false,
    "conversationEmail": {
      "to": [],
      "cc": [],
      "bcc": [],
      "from": null,
      "replyTo": null,
      "subject": null,
      "htmlBody": null,
      "textBody": null
    }
  },
  "customFields": [],
  "dispositions": [
    {
      "id": "6e0bf119-c8a1-402f-83c1-318bb6414c7a",
      "disposition": "SALE",
      "success": true,
      "doNotContact": false
    },
    {
      "id": "f741a3af-0beb-465b-8cf9-099eef567f45",
      "disposition": "OPT OUT",
      "success": false,
      "doNotContact": true
    },
    {
      "id": "25930991-5d57-49bd-a6a1-593f7ac1ea99",
      "disposition": "CALL BACK",
      "success": false,
      "doNotContact": false
    }
  ],
  "zendeskApprovalTicketId": null,
  "allCampaignFields": [
    "Phone",
    "Zip",
    "FirstName",
    "LastName",
    "Address1",
    "Address2",
    "City",
    "State"
  ]
}

 

Response Field Reference

The campaign response may include the following fields.

Field Type Description
events Array Campaign event history. Each event includes timestamp, type, and message.
id String Unique campaign identifier.
orgId Number Organization identifier.
workspaceId Number Workspace identifier associated with the campaign.
name String Campaign name.
shardingHashCode Number Internal value used for sharding distribution.
created String Campaign creation timestamp in ISO 8601 format.
updated String Last campaign update timestamp in ISO 8601 format.
campaignStatus Enum Campaign lifecycle status. Possible values include DRAFT, PENDING_APPROVAL, READY, and ACTIVE.
sendingStatus Enum Current message dispatch status. Possible values include IDLE and SENDING.
sendingStatusDescription String / null Additional detail about the current sending status, when available.
nextRunTime String / null Scheduled timestamp for the next campaign run, when available.
senderSourceType Enum Sender source type. Possible values include SHORT_CODE, LONG_CODE, and TOLL_FREE.
senderSourceId String Identifier for the selected sender source.
aegisWorkflowId String / null Identifier for an associated Aegis workflow, when configured.
carrierDailyLimits Array Daily sending limits by carrier, when configured.
schedule Object Permitted messaging windows by day. Times are represented as minutes past midnight in the lead’s local timezone.
messages Object Message templates used by the campaign, including outbound, response, help, stop, and start messages.
webhooks Object Webhook configuration for delivery results, conversation start, incoming messages, dispositions, opt-outs, and opt-ins.
notifications Object Conversation email notification configuration, including recipients and email content settings.
customFields Array Custom fields defined for the campaign.
dispositions Array Campaign dispositions. Each disposition includes an id, label, success flag, and doNotContact flag.
zendeskApprovalTicketId String / null Zendesk ticket identifier associated with campaign approval, when available.
allCampaignFields Array All available campaign data fields, such as Phone, Zip, FirstName, and LastName.

Retrieve Campaign List

Retrieves a complete list of all text messaging campaigns within your Pure CallerID Engage Messaging account. This endpoint returns essential campaign details, such as unique identifiers, status, schedule settings, and statistical summaries, helping developers quickly enumerate available campaigns and assess their configurations.

URL: https://core.purecallerid.app/api/public/engage/campaigns

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.

Return: A JSON array of campaign objects in the workspace 

Retrieve Single Campaign

Fetches detailed information for a specific text messaging campaign. Use this endpoint to obtain comprehensive data including campaign metadata, current status, configuration settings, message content, and performance metrics, which is ideal for troubleshooting or review before updates.

URL: https://core.purecallerid.app/api/public/engage/campaigns/{id}

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.

Return: A single campaign objects in the workspace

Update Campaign Messaging (and request approval)

Enables modifications to the message content or settings associated with an existing campaign. This endpoint supports updating the body of text messages, sender information, scheduling parameters, and other dynamic content, ensuring that campaigns remain aligned with evolving communication strategies and compliance requirements.

URL: https://core.purecallerid.app/api/public/engage/campaigns/{id}/messages

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.

Request Body: Leave blank or null anything that does not require updating:

{
  "outgoingMessage": "Hi {{FirstName}}, this Pure CallerId reaching out to you to see if you would like to participate in our upcoming webinar on trust and compliance in 2025. Would you like to join us?",
  "responseMessage": "",
  "helpMessage": "",
  "stopMessage": "",
  "startMessage": ""
 }

Return: The single campaign object that was activated via the request.

Activate Campaign

Transitions a campaign’s status from inactive or paused to active, allowing messages to start being sent.  It is used when you are ready to roll out the messaging initiative or resume a temporarily halted campaign.

URL: https://core.purecallerid.app/api/public/engage/campaigns/{id}/activate

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.

Return: The single campaign object that was activated via the request.

Pause Campaign

Temporarily suspends an active messaging campaign. When invoked, the endpoint halts all message dispatches while preserving the campaign’s configuration and historical data. This is useful for situations where a campaign requires adjustments, compliance reviews, or temporary market suspension without complete termination.

URL: https://core.purecallerid.app/api/public/engage/campaigns/{id}/pause

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.

Return: The single campaign object that was paused via the request.

Active Lead List (by Name)

Activates a specific lead list using its descriptive name as an identifier. This endpoint is designed to streamline lead management by enabling you to quickly bring a named lead list into an active state for message distribution, ensuring that the latest contact data is engaged in your campaigns.

URL: https://core.purecallerid.app/api/public/engage/campaigns/{id}/lists/activate

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.

Input: 

  • listName -URL Encoded query param - the verbatim list name that was loaded into the messaging campaign
  • updateAll - optional boolean - default value is false; true value will apply update to all lists matching the provided list name

Return: The single campaign list object, or list of campaign objects if updateAll, that was activated via the request.

Pause Lead List (by Name)

Pauses message processing for one or more campaign lists within a messaging campaign using the provided list name as the identifier. This endpoint is commonly used to temporarily halt outbound messaging activity while preserving all campaign configuration, campaign list association, and historical processing data for future reactivation.

Only campaign lists currently in an ACTIVE state are eligible to be paused. Eligible campaign lists will transition to a READY state. Campaign lists in any other status, including COMPLETE, will remain unchanged.

URL: https://core.purecallerid.app/api/public/engage/campaigns/{id}/lists/pause

Method: POST

Content-Type: application/json

Security: A custom HTTP header is required with every request.

Header Description
X-API-KEY An encrypted API key associated with your workspace

Input Parameters

Parameter Type Required Description
listName URL Encoded Query Parameter Yes The exact list name associated with the messaging campaign
updateAll Boolean No Optional flag indicating whether the action should apply to all matching lists within the campaign. Defaults to false

Example Request (Single List)

curl --location --globoff --request POST \
'https://core.purecallerid.app/api/public/engage/campaigns/:campaignId/lists/pause?listName={{listName}}' \
--header 'X-API-KEY: {{apiKey}}'

Example Request (All Matching Lists)

curl --location --globoff --request POST \
'https://core.purecallerid.app/api/public/engage/campaigns/:campaignId/lists/pause?listName={{listName}}&updateAll=true' \
--header 'X-API-KEY: {{apiKey}}'

Return

Returns the single campaign list object updated by the request. If updateAll=true, the response will contain an array of all matching campaign list objects successfully transitioned to the READY state.

Webhooks

There are two webhook events that are available for registration.  These webhooks can alert your system to changes in the status of Campaigns or Lists.

  • MessagingCampaignStatus - Triggers every time the status of a campaign changes.  This includes transitions between DRAFT, PENDING_APPROVAL, READY, ACTIVE, etc.  The entire Campaign object will be provided as the body of the webhook event.
  • MessagingListStatus - Triggers every time the status of a campaign list changes.  This includes transitions between ACTIVE and READY.  The entire Campaign List object will be provided as the body of the webhook event.

Related articles