{"info":{"_postman_id":"99d22e19-4cb6-4901-abe5-e8fea8d83e25","name":"Circle API Training","description":"

Welcome to the Circle API training.

This documentation includes two Circle API samples to help you get started with the Circle API training.

For details about each API, see the Circle API reference
For step-by-step training instructions, download this Circle API walkthrough.

In addition, if you are using a custom SMS provider, see the Custom SMS Provider API in this documentation which enables you to push the SMS analytics to the Circle data warehouse.

\n
Use of the Circle API is restricted to customers who purchased Circle API or uProduce API. The use of the Custom SMS Provider API is available to all.
\n

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"15113667","collectionId":"99d22e19-4cb6-4901-abe5-e8fea8d83e25","publishedId":"TzRVdRUT","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2021-05-13T08:46:46.000Z"},"item":[{"name":"Circle API Sample 1","item":[{"name":"Login and get token","event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"b3ae360f-0545-49ab-9422-0c5a699d7c15"}},{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","postman.setEnvironmentVariable(\"TokenID\", jsonData.Value);",""],"id":"ec39be88-1d24-42e5-ac6f-6c53dd54bb36"}}],"id":"9237222e-f95e-4c1a-a1c0-8ba0393f3d6e","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/x-www-form-urlencoded"},{"key":"Cache-Control","value":"no-cache"}],"body":{"mode":"urlencoded","urlencoded":[{"key":"UserName","value":"{{UserName}}","type":"text"},{"key":"UserPassword","value":"{{UserPassword}}","type":"text"}]},"url":"https://eu.xmcircle.com/CloudAPI/v1/system/login","description":"\n

Overview

This request to Circle API passes the Circle username and password in the request body and returns a security token which is used for following requests.

Request URL

https://eu.xmcircle.com/CloudAPI/v1/system/login\n

Request Headers

Key: Content-Type \nValue: application/x-www-form-urlencoded\n\nKey: Cache-Control\nValue: no-cache\n

Request Body

Key: UserName\nvalue: [your Circle username]\n\nKey: UserPassword\nValue [your Circle password]\n

Tests

The Postman Tests are used to capture the response.Value parameter and store it in an Environment Variable for use with further requests.

var jsonData = JSON.parse(responseBody);\npostman.setEnvironmentVariable(\"TokenID\", jsonData.Value);\n

\n","urlObject":{"protocol":"https","path":["CloudAPI","v1","system","login"],"host":["eu","xmcircle","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"9237222e-f95e-4c1a-a1c0-8ba0393f3d6e"},{"name":"Get project's current automation mode","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","if (jsonData.AutomationMode == \"1\") {"," //project is currently draft, set nextAutomationMode to be start"," postman.setEnvironmentVariable(\"nextAutomationMode\", \"start\");","} else {"," //project is currently live, set nextAutomationMode to be stop"," postman.setEnvironmentVariable(\"nextAutomationMode\", \"stop\");","}","","pm.test(\"Got the current Project Automation Mode\", function () {"," var jsonData = pm.response.json();"," pm.expect(jsonData.AutomationMode).to.be.oneOf([1,2]);","});","",""],"id":"550fc5ac-5cd5-498a-a8c7-87467d4d72fc"}}],"id":"ad82a5e9-bf9e-4f89-a73f-105612449450","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Circle {{TokenID}}"},{"key":"Content-Type","value":"application/json"},{"key":"Cache-Control","value":"no-cache"}],"url":"https://eu.xmcircle.com/CloudAPI/v1/{{SubscriptionID}}/projects/{{ProjectID}}","description":"

Get project's current automation mode

Overview

This request gets the current status of the project's automation mode and sets the nextAutomationMode variable which is used in the following request.

Request URL

https://eu.xmcircle.com/CloudAPI/v1/{{SubscriptionID}}/projects/{{ProjectID}}\n

Request Headers

Key: Authorization\nValue: Circle {{TokenID}}\n\nKey: Content-Type \nValue: application/json\n\nKey: Cache-Control\nValue: no-cache\n

Tests

There are 2 Postman Tests.

The first is used to capture the response.AutomationMode and depending on its value store the nextAutomationMode in an Environment Variable for use with the next request.

The second is a Postman test to ensure the returned value is either 1 (draft) or 2 (live).

var jsonData = JSON.parse(responseBody);\nif (jsonData.AutomationMode == \"1\") {\n    //project is currently draft, set nextAutomationMode to be start\n    postman.setEnvironmentVariable(\"nextAutomationMode\", \"start\");\n} else {\n    //project is currently live, set nextAutomationMode to be stop\n    postman.setEnvironmentVariable(\"nextAutomationMode\", \"stop\");\n}\n\npm.test(\"Got the current Project Automation Mode\", function () {\n    var jsonData = pm.response.json();\n    pm.expect(jsonData.AutomationMode).to.be.oneOf([1,2]);\n});\n\n

\n","urlObject":{"protocol":"https","path":["CloudAPI","v1","{{SubscriptionID}}","projects","{{ProjectID}}"],"host":["eu","xmcircle","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"ad82a5e9-bf9e-4f89-a73f-105612449450"},{"name":"Toggle automation mode","event":[{"listen":"test","script":{"type":"text/javascript","exec":["pm.test(\"Circle API returned successfully\", function () {"," pm.expect(pm.response.text()).to.include(\"true\");","});"],"id":"ff813835-4c72-4cbf-81f1-fb04efbbd41a"}}],"id":"19f5ee01-2ac0-4add-b2c4-69e2529e6b56","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Circle {{TokenID}}"},{"key":"Content-Type","value":"application/json"},{"key":"Cache-Control","value":"no-cache"}],"url":"https://eu.xmcircle.com/CloudAPI/v1/{{SubscriptionID}}/projects/{{ProjectID}}/automation/{{nextAutomationMode}}","description":"

Toggle automation mode

Overview

This request changes the status of the project automation based on the nextAutomationMode variable.

Request URL

https://eu.xmcircle.com/CloudAPI/v1/{{SubscriptionID}}/projects/{{ProjectID}}/automation/{{nextAutomationMode}}\n

Request Headers

Key: Authorization\nValue: Circle {{TokenID}}\n\nKey: Content-Type \nValue: application/json\n\nKey: Cache-Control\nValue: no-cache\n

Tests

The Postman test checks that the Circle API reponse was \"true\" (success).

pm.test(\"Circle API returned successfully\", function () {\n    pm.expect(pm.response.text()).to.include(\"true\");\n});\n

\n","urlObject":{"protocol":"https","path":["CloudAPI","v1","{{SubscriptionID}}","projects","{{ProjectID}}","automation","{{nextAutomationMode}}"],"host":["eu","xmcircle","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"19f5ee01-2ac0-4add-b2c4-69e2529e6b56"}],"id":"62f9ca3b-7384-46e4-85f6-f1d20ce49f76","description":"

Turning on or off Project Automation

Circle provides automation features – for example to schedule an email to automatically be sent to campaign recipients on a particular date and time, or after a defined interval from an event.

Circle projects have different statuses. For example, while the team is working on the project, the status would be \"Draft\" and when ready to enable automation, the project would be changed to \"Live\" status. At the application level, programatically, this status is known as the AutomationMode and can have values of 1 (Draft) or 2 (Live).

This sample shows how a Circle project status can be changed from Live to Draft (or vice versa) programmatically using the Circle API. For example, a custom application could be created to turn on automation once your accounting system received payment; or a web application could be created to provide a user the ability to turn on or off automation without needing to access Circle directly.

This Circle API sample uses the following API calls:

https://eu.xmcircle.com/CloudAPI/v1/system/login\nhttps://eu.xmcircle.com/CloudAPI/v1/{{SubscriptionID}}/projects/{{ProjectID}}\nhttps://eu.xmcircle.com/CloudAPI/v1/{{SubscriptionID}}/projects/{{ProjectID}}/automation/{{nextAutomationMode}}\n

Notes:

The environment variables in the URLs (above) will be replaced when the requests are made. Please refer to Preparation (below) for information on how to setup the variables.

Preparation

Before using this sample, you need to define a Postman environment, and declare several environment variables:

Key: UserName\nValue: [your Circle username]\n\nKey: Password\nValue: [your Circle password]\n\nKey: SubscriptionID\nValue: [your Circle subscription ID]\n\nKey: ProjectID\nValue: [the ID of the Circle Project that you want to change the automation status for]\n\nKey: TokenID\nValue:\n\nKey: nextAutomationMode\nValue: \n

Notes:

The username and password required are the credentials you use to login to Circle
The SubscriptionID and ProjectID can be identified by opening a project in Circle. The URL will show two GUIDs. The first GUID is the SubscriptionID, and the second is the ProjectID of the open project.
TokenID and nextAutomationMode can be left blank/empty. They will be updated automatically by Postman Tests when running the requests.

\n","event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"c15976f4-6431-4983-8dd8-53552aaf5f3d"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"0c00c236-95aa-43d8-8332-c1671e9a9540"}}],"_postman_id":"62f9ca3b-7384-46e4-85f6-f1d20ce49f76"},{"name":"Circle API Sample 2","item":[{"name":"Login and get token","event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"c357ae41-dd32-4bf2-8820-568816925cd7"}},{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","postman.setEnvironmentVariable(\"TokenID\", jsonData.Value);",""],"id":"f0f93f1f-08fd-45d2-bf14-591a4b099aad"}}],"id":"c6d88d9f-4bbd-4af4-b7b8-08000aef2f54","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/x-www-form-urlencoded"},{"key":"Cache-Control","value":"no-cache"}],"body":{"mode":"urlencoded","urlencoded":[{"key":"UserName","value":"{{UserName}}","type":"text"},{"key":"UserPassword","value":"{{UserPassword}}","type":"text"}]},"url":"https://eu.xmcircle.com/CloudAPI/v1/system/login","description":"\n

Overview

This request to Circle API passes the Circle username and password in the request body and returns a security token which is used for following requests.

Request URL

https://eu.xmcircle.com/CloudAPI/v1/system/login\n

Request Headers

Key: Content-Type \nValue: application/x-www-form-urlencoded\n\nKey: Cache-Control\nValue: no-cache\n

Request Body

Key: UserName\nvalue: [your Circle username]\n\nKey: UserPassword\nValue [your Circle password]\n

Tests

The Postman Tests are used to capture the response.Value parameter and store it in an Environment Variable for use with further requests.

var jsonData = JSON.parse(responseBody);\npostman.setEnvironmentVariable(\"TokenID\", jsonData.Value);\n

Get first subscription

Overview

This request to Circle API passes the TokenID in the header and receives a list of Circle subscriptions accessible by the Circle user.

Request URL

https://eu.xmcircle.com/CloudAPI/v1/system/subscriptions\n

Request Headers

Key: Authorization\nValue: Circle {{TokenID}}\n\nKey: Content-Type \nValue: application/json\n\nKey: Cache-Control\nValue: no-cache\n

Tests

The Postman Tests are used to capture the response.ID parameter of the first subscription and store it in an Environment Variable for use with further requests.

var jsonData = JSON.parse(responseBody);\npostman.setEnvironmentVariable(\"SubscriptionID\", jsonData[0].ID);//just get the first subscription id\n

\n","urlObject":{"protocol":"https","path":["CloudAPI","v1","system","subscriptions"],"host":["eu","xmcircle","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"9f959090-1088-4ad6-ab19-f4678dbee419"},{"name":"Get first project","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","postman.setEnvironmentVariable(\"ProjectID\", jsonData[0].ID);//just get the first project id"],"id":"7d773530-fef9-4360-9a49-08f940fa2155"}}],"id":"84d84b45-5141-4ae8-a8df-f5e74506c245","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Circle {{TokenID}}"},{"key":"Content-Type","value":"application/json"},{"key":"Cache-Control","value":"no-cache"}],"url":"https://eu.xmcircle.com/CloudAPI/v1/{{SubscriptionID}}/projects?types[0]=1&statuses=1&sortBy=1&sortOrder=2","description":"

Get first project

Overview

This request to Circle API passes the TokenID in the header and the subscriptionID in the URL to get a list of Circle projects in the Circle subscription. Note that URL parameters are used to select particular project types and statuses as well as to sort the returned data.

Request URL

https://eu.xmcircle.com/CloudAPI/v1/{{SubscriptionID}}/projects?types[0]=3&statuses=1&sortBy=1&sortOrder=2\n

Request Headers

Key: Authorization\nValue: Circle {{TokenID}}\n\nKey: Content-Type \nValue: application/json\n\nKey: Cache-Control\nValue: no-cache\n

Tests

The Postman Tests are used to capture the response.ID parameter of the first project and store it in an Environment Variable for use with further requests.

var jsonData = JSON.parse(responseBody);\npostman.setEnvironmentVariable(\"ProjectID\", jsonData[0].ID);//just get the first project id\n

\n","urlObject":{"protocol":"https","path":["CloudAPI","v1","{{SubscriptionID}}","projects"],"host":["eu","xmcircle","com"],"query":[{"key":"types[0]","value":"1"},{"key":"statuses","value":"1"},{"key":"sortBy","value":"1"},{"key":"sortOrder","value":"2"}],"variable":[]}},"response":[],"_postman_id":"84d84b45-5141-4ae8-a8df-f5e74506c245"},{"name":"Get first print touchpoint","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","var testData;","//loop over the touchpoints and get the first print touchpoint id","// Types: 1 = Print; 2 = Email; 3 = Web; 4 = PDF on demand; 5 = Triggered Email","// Statuses: 1 = active; 2 = deleted","for(var i = 0; i < jsonData.length; i++) {"," var obj = jsonData[i];"," if (obj.Type == \"1\" && obj.Status == \"1\") {"," postman.setEnvironmentVariable(\"TouchpointID\", obj.ID);"," testData = obj.ID;"," break;"," }","}","","tests[\"Got a print touchpoint\"] = testData !== null;",""],"id":"fb642fe6-f930-4cfe-8504-f0994a9f51b0"}}],"id":"39801f44-ee7e-4685-80d3-fec4b6a42db5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Circle {{TokenID}}"},{"key":"Content-Type","value":"application/json"},{"key":"Cache-Control","value":"no-cache"}],"url":"https://eu.xmcircle.com/CloudAPI/v1/{{SubscriptionID}}/projects/{{ProjectID}}/touchPoints","description":"

Get first print touchpoint

Overview

This request to Circle API passes the TokenID in the header and the subscriptionID and ProjectID in the URL to get a list of Circle touchpoints in the Circle project.

Request URL

https://eu.xmcircle.com/CloudAPI/v1/{{SubscriptionID}}/projects/{{ProjectID}}/touchPoints\n

Request Headers

Key: Authorization\nValue: Circle {{TokenID}}\n\nKey: Content-Type \nValue: application/json\n\nKey: Cache-Control\nValue: no-cache\n

Tests

The Postman Tests are used to capture the response.ID parameter of the first print touchpoint and store it in an Environment Variable for use with further requests.

var jsonData = JSON.parse(responseBody);\nvar testData;\n//loop over the touchpoints and get the first print touchpoint id\n// Types: 1 = Print; 2 = Email; 3 = Web; 4 = PDF on demand; 5 = Triggered Email\n// Statuses: 1 = active; 2 = deleted\nfor(var i = 0; i < jsonData.length; i++) {\n    var obj = jsonData[i];\n    if (obj.Type == \"1\" && obj.Status == \"1\") {\n        postman.setEnvironmentVariable(\"TouchpointID\", obj.ID);\n        testData = obj.ID;\n        break;\n    }\n}\n\ntests[\"Got a print touchpoint\"] = testData !== null;\n

\n","urlObject":{"protocol":"https","path":["CloudAPI","v1","{{SubscriptionID}}","projects","{{ProjectID}}","touchPoints"],"host":["eu","xmcircle","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"39801f44-ee7e-4685-80d3-fec4b6a42db5"},{"name":"Get first sample recipient","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","var testData = jsonData[0].RecipientKey;","postman.setEnvironmentVariable(\"RecipientKey\", jsonData[0].RecipientKey);","","tests[\"Got a recipient id\"] = testData !== null;"],"id":"c7ac18a3-bea2-48ca-a2aa-e58650892a49"}}],"id":"3b4e29fe-5008-4418-a644-c43cc923581f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"Circle {{TokenID}}"},{"key":"Content-Type","value":"application/json"},{"key":"Cache-Control","value":"no-cache"}],"url":"https://eu.xmcircle.com/CloudAPI/v1/{{SubscriptionID}}/projects/{{ProjectID}}/sampleRecipients/full","description":"

Get first sample recipient

Overview

This request to Circle API passes the TokenID in the header and the subscriptionID and ProjectID in the URL to get a list of sample recipients in the Circle project.

Request URL

https://eu.xmcircle.com/CloudAPI/v1/{{SubscriptionID}}/projects/{{ProjectID}}/touchPoints\n

Request Headers

Key: Authorization\nValue: Circle {{TokenID}}\n\nKey: Content-Type \nValue: application/json\n\nKey: Cache-Control\nValue: no-cache\n

Tests

The Postman Tests are used to capture the response.RecipientKey parameter from the first sample recipient and store it in an Environment Variable for use with further requests.

var jsonData = JSON.parse(responseBody);\nvar testData = jsonData[0].RecipientKey;\npostman.setEnvironmentVariable(\"RecipientKey\", jsonData[0].RecipientKey);\n\ntests[\"Got a recipient id\"] = testData !== null;\n

\n","urlObject":{"protocol":"https","path":["CloudAPI","v1","{{SubscriptionID}}","projects","{{ProjectID}}","sampleRecipients","full"],"host":["eu","xmcircle","com"],"query":[],"variable":[]}},"response":[],"_postman_id":"3b4e29fe-5008-4418-a644-c43cc923581f"},{"name":"Get touchpoint preview ","event":[{"listen":"test","script":{"type":"text/javascript","exec":["var jsonData = JSON.parse(responseBody);","var previewUrl = jsonData.Url;","tests[\"Got a url to a PDF\"] = previewUrl !== null && previewUrl !== \"\";",""],"id":"8034b17d-5389-4eb7-ad71-3c28ca749ada"}}],"id":"34d3d798-584b-4383-8c36-0d7392964df2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"Circle {{TokenID}}"},{"key":"Content-Type","value":"application/json"},{"key":"Cache-Control","value":"no-cache"}],"url":"https://eu.xmcircle.com/CloudAPI/v1/{{SubscriptionID}}/touchPoints/{{TouchpointID}}/preview?recipientKey={{RecipientKey}}&ignoreCache=true","description":"

Get touchpoint preview

Overview

This request to Circle API passes the TokenID in the header and the SubscriptionID and TouchpointID in the URL to get the URL to a print touchpoint preview, or the HTML preview of a web or email touchpoint. Note that URL parameters are needed to identify the sample recipient.

Request URL

https://eu.xmcircle.com/CloudAPI/v1/{{SubscriptionID}}/touchPoints/{{TouchpointID}}/preview?recipientKey={{RecipientKey}}&ignoreCache=true\n

Request Headers

Key: Authorization\nValue: Circle {{TokenID}}\n\nKey: Content-Type \nValue: application/json\n\nKey: Cache-Control\nValue: no-cache\n

Tests

The Postman Tests are used to capture the response.Url parameter. This value could be used to redirect the browser to display the PDF, or to stream the PDF bytes to a disk file.

var jsonData = JSON.parse(responseBody);\nvar previewUrl = jsonData.Url;\ntests[\"Got a url to a PDF\"] = previewUrl !== null && previewUrl !== \"\";\n

\n","urlObject":{"protocol":"https","path":["CloudAPI","v1","{{SubscriptionID}}","touchPoints","{{TouchpointID}}","preview"],"host":["eu","xmcircle","com"],"query":[{"key":"recipientKey","value":"{{RecipientKey}}"},{"key":"ignoreCache","value":"true"}],"variable":[]}},"response":[],"_postman_id":"34d3d798-584b-4383-8c36-0d7392964df2"}],"id":"c6847fa4-af28-4bcb-999b-5aecb1256f4b","description":"

Previewing a Circle Project Touchpoint

The Circle user interface allows the preview of a Touchpoint (print, email or web page) for different sample recipients.

This sample shows how to access and display the Touchpoint preview in a separate custom application. For example, a custom application could be created to preview touchpoints without needing to access Circle UI directly.

The sample is provided in two versions – one using a Postman collection that will get the preview of the first print touchpoint for the first sample recipient in the first project of the first subscription. The sample could be modified slightly get a different touchpoint from any specific project. This is shown in the second example using JQuery on an html page.

This Circle API sample uses the following API calls:

https://eu.xmcircle.com/CloudAPI/v1/system/login/\nhttps://eu.xmcircle.com/CloudAPI/v1/system/subscriptions/\nhttps://eu.xmcircle.com/CloudAPI/v1/{{SubscriptionID}}/projects/\nhttps://eu.xmcircle.com/CloudAPI/v1/{{SubscriptionID}}/projects/{{ProjectID}}/touchpoints\nhttps://eu.xmcircle.com/CloudAPI/v1/{{SubscriptionID}}/projects/{{ProjectID}}/sampleRecipients/full\nhttps://eu.xmcircle.com/CloudAPI/v1/{{SubscriptionID}}/touchpoints/{{TouchpointID}}/preview\n

Notes:

The environment variables in the URLs (above) will be replaced when the requests are made. Please refer to Preparation (below) for information on how to setup the variables.

Preparation

Before using this sample, you need to define a Postman environment, and declare several environment variables:

Key: UserName\nValue: [your Circle username]\n\nKey: Password\nValue: [your Circle password]\n\nKey: SubscriptionID\nValue: \n\nKey: ProjectID\nValue: \n\nKey: TokenID\nValue:\n\nKey: TouchpointID\nValue: \n\nKey: RecipientKey\nValue:\n

Notes:

The username and password required are the credentials you use to login to Circle
The remaining variables are set by Postman tests on the relevant requests. For example, the Test on the login request will set the TokenID variable which is used on subsequent requests.
The default Postman Tests will select the first available subscription, the last modified project and the first print touchpoint and sample recipient. The tests can be edited to select other options. Also, the JQuery-HTML example that comes together with this Postman collection also demonstrates how to use the same Circle API calls while providing more user interaction for the selected subscription/project/touchpoint/sample recipient.

\n","event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"a6d876f1-c125-487a-a486-248f23b1b477"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"723f4954-984a-4e95-846f-0c21a3f47d77"}}],"_postman_id":"c6847fa4-af28-4bcb-999b-5aecb1256f4b"},{"name":"Custom SMS Provider API","item":[{"name":"Delivery Recipients","id":"f152ad79-796d-48f7-99ed-0b2d3d8428a8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"messageID\": \"6b20c1d0-7750-11eb-8f6e-1b4ea37f6c75\",\r\n \"providerID\": \"3a384ec6-14bd-435d-9127-ca552a879155\",\r\n \"eventDate\": \"2021-02-23T10:32:42Z\",\r\n \"eventType\": 1\r\n}","options":{"raw":{"language":"json"}}},"url":"https://analytics.xmcircle.com/sms/custom/delivery-recipients","description":"

Description

If you're using a custom SMS delivery provider, and you wish to enable Circle to track the SMS events, use the Custom SMS Provider API to push the SMS analytics to the Circle data warehouse.

This API is called only if tracking of the SMS is required (enableTracking is set to true).

Example:

{ \n    \"message\": { \n        \"from\": \"some phone\",\n        \"to\": \"some phone\",\n        \"text\": \"Hello\"\n    }, \n    \"providerParameters\": { \n        \"user\": \"test\", \n        \"password\": \"1\" \n    }, \n    \"context\": { \n        \"runID\": \"6b20c1d0-7750-11eb-8f6e-1b4ea37f6c75\", \n        \"deliveryProviderID\": \"3a384ec6-14bd-435d-9127-ca552a879155\", \n        \"enableTracking\": true \n    } \n} \n

SMS parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Group Name	Parameter Name	Type	Description
message	from	string	Phone number of a sender
message	to	string	Phone number of a recipient
message	text	string	Message to a recipient
providerParameters		object	Data from custom delivery provider settings in Circle
context	runID	string	Run ID; one run may have several SMS messages
context	deliveryProviderID	string	Custom delivery provider ID used in Circle
context	enableTracking	bool	Value of true indicates that SMS events must be tracked and SMS analytics must be stored in the Circle data warehouse

Tracking event parameters

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Parameter Name	Type	Description
messageID	string	Unique text value of a message ID
providerID	string	Delivery provider ID in Circle
eventDate	ISO 8601 date	Event creation date
eventType	number	Numeric status of SMS sending: 1 – Delivered, 2 – Failed
failureType	number	Optional status specifying a reason why SMS send failed. The property must have a value only if eventType = 2 (Failed).

Values of failureType

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Value	Meaning
1	Unknown
2	Absent Subscriber - Temporary
3	Absent Subscriber - Permanent
4	Call barred by user
5	Portability Error
6	Anti-Spam Rejection
7	Handset Busy
8	Network Error
9	Illegal Number
10	Invalid Message
11	Unroutable
12	Destination Un-Reachable
13	Subscriber Age Restriction
14	Number Blocked By Carrier
15	Pre-Paid Insufficient Funds

","urlObject":{"protocol":"https","path":["sms","custom","delivery-recipients"],"host":["analytics","xmcircle","com"],"query":[],"variable":[]}},"response":[{"id":"e7beda0e-fbc6-4995-b334-121ffa9ff76b","name":"Delivery Recipients","originalRequest":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"messageID\" : \"6b20c1d0-7750-11eb-8f6e-1b4ea37f6c75\",\r\n \"providerID\" : \"3a384ec6-14bd-435d-9127-ca552a879155\",\r\n \"eventDate\" : \"2021-02-23T10:32:42Z\",\r\n \"eventType\" : 2,\r\n \"failureType\": 5\r\n}","options":{"raw":{"language":"json"}}},"url":"https://analytics.xmcircle.com/sms/custom/delivery-recipients"},"code":200,"_postman_previewlanguage":"json","header":[],"cookie":[],"responseTime":null,"body":"// A response may be ignored because it's sufficient to check the status code\r\n{\r\n \"result\": \"ok\"\r\n}"}],"_postman_id":"f152ad79-796d-48f7-99ed-0b2d3d8428a8"}],"id":"36602307-63c1-4b3f-98d9-52249f461b8e","_postman_id":"36602307-63c1-4b3f-98d9-52249f461b8e","description":""}],"event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"3b8df8db-0968-4494-adf8-7fb4e4b4a1e3"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"505e5a56-778e-4abf-b02f-0222361eeabe"}}]}