Campaign Management

This guide describes the APIs available to automatically manage Engage campaigns. Using these APIs you can:

Enumerate all of your campaigns
Retrieve campaign details
Create a campaign
Publish a Campaign

Run a campaign
Update a campaign
Retrieve campaigns in error
Delete a campaign

Overview

Campaigns can be manually managed through the Engage menu option at the top of the CPaaS Portal or the Engage application within the Customer Portal, but you can also automate campaign management through our APIs.

Getting Started

Before you begin using these APIs make sure you've obtained an authentication token, and check out the API Basics page to learn more about basic requirements for using the APIs.

Note: For all requests, Content-Type and Accept headers must be in JSON format.

Base URL

All of the following endpoints share the same base URL:

https://engage.intelepeer.com

(e.g., GET/https://engage.intelepeer.com/_rest/v2/campaigns).

Campaign Management APIs

Click on the APIs below to view the parameters and code samples associated with each endpoint.

Campaign Management

Use this endpoint to enumerate all of your campaigns in Engage.

Endpoint

GET /_rest/v2/campaigns

Parameters

Headers

Authorization: xxxxxxxxxxxxxxxxx

Content-Type: application/json

Field	Type	Description
Authorization	String	Authorization token (for more information, see API Authentication)
Content-Type	String	application/json

Error Name	Type	Description
code	Integer	Error code
error	String	Error description

Sample Responses

Code 200 Response

Response code 200 returns a list of campaign objects.

{
	"listRel": [
 		"5c1a4728717a743602510e48"
 		],
 	"location": "US",
 	"_id": "5cf02630e313d620ca9743e4",
 	"campaignName": "testing ethel",
 	"campaignDescription": "",
 	"callerIdentification": "+13122735567",
 	"startDate": "2019-06-26T00:00:00.000Z",
 	"endDate": "2019-06-29T00:00:00.000Z",
 	"active": 1,
 	"numAttempts": 1,
 	"appId": "5cf02606b4623d6a23167b23",
 	"runNow": false,
 	"modifiedDate": "2019-06-26T19:58:00.871Z",
 	"modifiedBy": "ethel",
 	"customerId": "9999999",
 	"createdDate": "2019-05-30T18:51:28.963Z",
 	"createdBy": "ethel",
 	"deleteFlag": false,
 	"lastExecuted": "",
 	"scheduled": "5d13bfcd4c36cca2d46a0a8d",
 	"retryInterval": 0,
 	"flowId": "5bef29e1c5480c40e2ab4ef0",
 	"timezone": "(CET) - mainterritory of Spain"
}

Code 401 Response

Response code 401 returns an error that the authorization token is invalid.

{
	"message": "string",
	"status": 401
}

Code 500 Response

Response code 500 returns an error when trying to retrieve a list of your campaigns.

{
	"message": "Something went wrong during the listing of a customer's campaigns",
	"status": 500
}

Retrieve Campaign Details

Use this endpoint to retrieve details on a particular campaign.

Endpoint

GET /_rest/v2/campaigns?id=xxxxxx

Parameters

Note: Either the "Id" or "Name" parameter is required.

Id:
- Key = id; Value = campaignId
Name:
- Key = name; Value = campaignName

Sample Request

Example with Id:

GET/_rest/v2/campaigns/?id=5c19078a717a743602510e23

Example with Name:

GET/_rest/v2/campaigns/?name=testing

Note: Your query must include at least four characters and spaces are allowed.

Sample Responses

Code 200 Response

Response code 200 returns a campaign object.

{
	"listRel": [
 		"5c1a4728717a743602510e48"
 		],
 	"location": "US",
 	"_id": "5cf02630e313d620ca9743e4",
 	"campaignName": "testing ethel",
 	"campaignDescription": "",
 	"callerIdentification": "+13122735567",
 	"startDate": "2019-06-26T00:00:00.000Z",
 	"endDate": "2019-06-29T00:00:00.000Z",
 	"active": 1,
 	"numAttempts": 1,
 	"appId": "5cf02606b4623d6a23167b23",
 	"runNow": false,
 	"modifiedDate": "2019-06-26T19:58:00.871Z",
 	"modifiedBy": "ethel",
 	"customerId": "9999999",
 	"createdDate": "2019-05-30T18:51:28.963Z",
 	"createdBy": "ethel",
 	"deleteFlag": false,
 	"lastExecuted": "",
 	"scheduled": "5d13bfcd4c36cca2d46a0a8d",
 	"retryInterval": 0,
 	"flowId": "5bef29e1c5480c40e2ab4ef0",
 	"timezone": "(CET) - mainterritory of Spain"
}

Code 401 Response

Response code 401 returns an error that the authorization token is invalid.

{
	"message": "string",
	"status": 401
}

Code 404 Response

Response code 404 returns a message that the campaign id or name is wrong and the campaign is not found.

Code 500 Response

Response code 500 returns an error when trying to retrieve campaign details.

{
	"message": "Something went wrong when trying to get campaign details",
	"status": 500
}

Create a Campaign

Use this endpoint to create and save a new campaign in Engage.

Note: The campaign won't be published.

Endpoint

POST /_rest/v2/campaigns

Note: You must send your request in JSON format.

Body

No fields are required in the request body
Optional Fields: campaignDescription, campaignName, callerIdentification, and flowId

Sample Request

{
    "campaignDescription":"A new Engage Campaign description", 
    "campaignName":"A brand new Campaign!", 
    "callerIdentification":"0000000000",
    "flowId":"61a9a3ecf6b8387f078d52a1"
}

Sample Responses

Code 201 Response

Response code 201 returns a campaign object when a campaign has successfully been created.

{
    "listRel": [],
    "lists": [],
    "location": "US",
    "_id": "62151c1cc6c0c841da2fe8c5",
    "deleteFlag": false,
    "campaignDescription": "A new Engage Campaign description",
    "campaignName": "A brand new Campaign!",
    "callerIdentification": "0000000000",
    "flowId": "61a9a3ecf6b8387f078d52a1",
    "startDate": null,
    "endDate": null,
    "active": 0,
    "numAttempts": 1,
    "retryInterval": 0,
    "runNow": false,
    "scheduleId": null,
    "rate": 1,
    "timezone": "",
    "appId": "62151c1ab0fcee1e165d4540",
    "createdDate": "2022-02-22T17:23:40.073Z",
    "createdBy": "*",
    "customerId": "1028811",
    "plan": "professional",
    "modifiedDate": "2022-02-22T17:23:40.073Z",
    "modifiedBy": "*"
}

Code 401 Response

Response code 401 returns an error that the authorization token is invalid.

{
	"message": "string",
	"status": 401
}

Code 500 Response

Response code 500 returns an error during campaign creation.

{	
	"message": "Something went wrong during campaign creation",
	"status": 500
}

Publish a Campaign

Use this endpoint to make a campaign active and ready to be run or available for scheduling.

Note: A campaign can only be run via API if it is in Published status.

Endpoint

POST /_rest/v2/campaigns/:id/action

Note: You must send your request in JSON format.

Parameters

Campaign Id

Body

Required field:

action

Sample Request

{
	"action": "publish"
}

Sample Responses

Code 200 Response

Response code 200 returns a boolean value of true indicating that the campaign is published successfully.

Code 401 Response

Response code 401 returns an error that the authorization token is invalid.

Code 404 Response

Response code 404 returns a message of not found if the campaign Id is wrong in the parameter.

Code 422 Response

Response code 422 returns a message that the required parameters are missing, or if the action field is missing, empty, or invalid.

Code 500 Response

Response code 500 returns an error when trying to publish the campaign.

Run a Campaign

Use this endpoint to conduct a campaign in Engage.

Note: A campaign can only be run via API if it is in Published status.

Endpoint

POST /_rest/v2/campaigns/:id/action

Note: You must send your request in JSON format.

Parameters

Campaign Id

Body

Required field:

action

Sample Request

{
	"action": "run"
}

Sample Responses

Code 200 Response

Response code 200 returns a boolean value of true indicating that the campaign is running or has run.

true

Code 401 Response

Response code 401 returns an error that the authorization token is invalid.

{
	"message": "string",
	"status": 401
}

Code 404 Response

Response code 404 returns a message that the campaign id is incorrect.

Code 422 Response

Response code 422 returns a message that the action field is missing, empty, or invalid.

{
	"message": "The 'action' parameter is required",
	"status": 422
}

Code 500 Response

Response code 500 returns an error when trying to run the campaign, or the campaign is not published yet and in Draft status.

{
	"message": "Something went wrong when trying to run the campaign",
	"status": 500
}

Update a Campaign

Use this endpoint to revise an existing campaign in Engage.

You can only use this endpoint if your campaign is linked to a flow in SmartFlows. Learn more about integrating SmartFlows and Engage here.

Endpoint

PUT /_rest/v2/campaigns/:id

Note: You must send your request in JSON format.

Parameters

Campaign Id

Body

Required fields:

campaignName
flowId

Note: The Flow ID is only accessible from the SmartFlows interface. You must log into your account, open the flow, and copy the Flow ID from the configurations panel.
callerIdentification

Optional field:

campaignDescription

Note: These fields can be updated in the body.

Sample Request

{
  "callerIdentification": "+16075175200",
  "campaignName": "Florida SMS Test",  
  "flowId": "5bef29e1c5480c40e2ab4ef0",
  "campaignDescription": "This is a Florida SMS Test"
}

Sample Responses

Code 200 Response

Response code 200 returns a campaign object.

{
	"campaignName": "Texas SMS Test",
	"campaignId": "5c1097c6717a743602510c9c",
	"campaignDescription": "This is a Texas SMS test",
	"callerIdentification": "+13122735567",
	"flowTypeId": "5d24c0e64886e81bb4cbf069",
	"startDate": "2019-06-18",
	"endDate": "2019-06-18",
	"active": 1,
	"numAttempts": "5",
	"retryInterval": "10",
	"appId": "",
	"runNow": "true",
	"scheduleId": "5f24c065jkl0p81bb4cbf069",
	"modifiedDate": "2019-06-18T00:14:03Z",
	"modifiedBy": "sspeirs",
	"createdDate": "2019-06-18T00:14:03Z",
	"createdBy": "sspeirs",
	"deleteFlag": "false",
	"customerId": 9999999,
	"listRel": [
		"4kk11065jkl0985bb48mf054"
		],
	"utcName": "United States Minor Outlying Islands - Baker Island",
	"utcOffset": "−12:00"
}

Code 401 Response

Response code 401 returns an error that the authorization token is invalid.

{
	"message": "string",
	"status": 401
}

Code 404 Response

Response code 404 returns a message that the campaign id parameter is incorrect.

{
	"message": "The 'campaign id' parameter is required",
	"status": 404
}

Code 500 Response

Response code 500 returns an error when trying to update the campaign.

{
	"message": "Something went wrong when trying to update the campaign",
	"status": 500
}

Retrieve Campaigns in Error

Use this endpoint to determine if any of your campaigns are experiencing an error.

Endpoint

GET /_rest/v2/campaigns/errors

Parameters

Headers

Authorization: Authorization token (string)

Content-Type: application/json

Query Parameters

None

Body

No fields are required in the request body.

Sample Request

GET/https://engage.intelepeer.com/_rest/v2/campaigns/errors

Sample Responses

Code 200 Response

Success response example:

[
	{
		"listRel": [ "6346d4529ba9c200096f3e8"
		"lists": [{"listId": "6346d4529ba9c200096f3e8", "moc": "phone", "autoDetectTZ": true}],
		"location": "US",
		"_id": "636d528fdda97296908aa762",
		"deleteFlag": false,
		"campaignName": "Customer Campaign 1",
		"callerIdentification": "+17077316030",
		"active": 0,
		"numAttempts": 1,
		"retryInterval": 0
		"appId": "6375157c88992d5714e99153",
		"runNow": false,
		"scheduleId": null, 
		"modifiedBy": "user-id",
		"createdBy": "user-id",
		"timezone": "",
		"rate": 1,
		"startDate": null,
		"endDate"; null,
		"modifiedDate": "2023-03-10T17:44:57.311Z",
		"createdDate": "2022-11-23T19:35:43.387Z",
		"customerId": "9999999",
		"plan": "enterprise",
		"status": "Error",
		"flowId": "636bf2ed0a56acfd104bc2f",
		"publishedDate": "2023-03-09T20:15:15.095Z",
		"runId": "636d528fdda97296908aa762:166871156336"
	}
]

Code 401 Response

Missing, invalid, or expired token response example:

{
	"message": "Authorization token is invalid",
	"status": 401
}

Delete a Campaign

Use this endpoint to remove a campaign in Engage.

Endpoint

DELETE /_rest/v2/campaigns/:id

Parameters

Campaign Id

Sample Request

DELETE /_rest/v2/campaigns/5d3f47f23d29d148c5f6218e

Sample Responses

Code 202 Response

Response code 202 returns a boolean value of true indicating that the campaign is in the process of deleting or has been deleted.

true

Code 401 Response

Response code 401 returns an error that the authorization token is invalid.

{
	"message": "string",
	"status": 401
}

Code 404 Response

Response code 404 returns a message that the campaign id parameter is incorrect.

{
	"message": "The 'campaign id' parameter is required",
	"status": 404
}

Code 500 Response

Response code 500 returns an error when trying to delete the campaign.

{
	"message": "Something went wrong when trying to delete the campaign",
	"status": 500
}