Campaigns

01. List campaigns

Get a list of campaigns, created by or shared with you. Items are return in reverse chronological order (newest first).

GET /int/v1/campaign

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Query Parameters

Name	Type	Description
limit	int	optional Maximum number of records to return. Default is 100. Maximium is 1000.Default value: 100
previousLastId	String	optional The last id value of previous return, use this to query more outside of limit
status	String	optional Only return results matching the supplied status code. '0' for draft, '1' for live, 3 for 'closed', 4 for 'scheduled'Allowed values: '0','1','3','4'
category	String	optional Only return results matching the supplied category code.
minLiveDate	Date	optional Only return results with go-live later than specified date (ECMAScript Date Time String format).
maxLiveDate	Date	optional Only return results with go-live earlier than specified date (ECMAScript Date Time String format).
all	String	optional Return all platform campaigns. Only works for Super Users. Mutually exclusive with onlyApi.
onlyApi	String	optional Only return campaigns created by Public API. Mutually exclusive with all.

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -X GET https://<url>/int/v1/campaign?limit=10

Javascript Example:

(async (url, token) => {

  try{
    const response = await(
      const params = new URLSearchParams({
        limit: 10
      });
      await fetch(
        `${url}/int/v1/campaign?${params}`,
        {
          method: "GET",
          headers: {
            "Authorization": `Bearer ${token}`
          }
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN);

Parameters examples

json - Request Page:

{
  "limit": 10
}

json - Request Next Page:

{
  "limit": 10,
  "previousLastId": "65dff01ac8072756ac1b7947"
}

json - Request Filtered by Status/Category:

{
  "status": "0",
  "category": "foo",
  "limit": 100
}

json - Request All:

{
  "all": "1",
  "limit": 1000
}

json - Request Created by Public API:

{
  "onlyApi": "1",
  "limit": 100
}

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
data	Array	optionalList of campaign objects. Present when success is true.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
  "success":true,
  "data":[
    {
      "_id": "66022a461b7ab8f92e9844c7",
      "sharedGroups": [],
      "name": "Welcome to the All Staff Channel",
      "title": "Welcome to the All Staff Channel",
      "description": "We're super happy to have you here with us.",
      "categories": [],
      "imageUrl": "https://cf.communic8.com/poit/image/upload/w_600/v1705384435/c8test/John/pexels-nathan-cowley-1192671_GHyJS.jpg",
      "enableEmail": true,
      "enableMobileNotification": true,
      "commentVisibility": "disabled",
      "status": "1",
      "liveDate": "2024-07-14T23:50:18.554Z",
      "sender": {
          "_id": "60f4aeb09279e27183c0a9da",
          "email": "john@communic8.com",
          "firstName": "John",
          "lastName": "Smith",
          "displayName": "John Smith"
      },
      "sharedUsers": [
          {
              "_id": "60f4aeb09279e27183c0a9da",
              "email": "john@communic8.com",
              "firstName": "John",
              "lastName": "Smith",
              "displayName": "John Smith"
          }
      ],
      "adminIds": [
          "60f4aeb09279e27183c0a9da"
      ],
      "recipientAmount": 7,
      "campaignUrl": "https://test.communic8.com/admin/web/#/campaigns/sent/details/66022a461b7ab8f92e9844c7"
    }
  ]
}

Success response example - Error:

HTTP/1.1 200 OK
{
  "success":false,
  "message":"Illegal parameters"
}

02. Get a campaign

Back to top

Get the details of an individual campaign.

GET /int/v1/campaign/:id

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Parameters - URL Parameters

Name	Type	Description
id	String	Campaign _id value.

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -X GET https://<url>/int/v1/campaign/<id>

Javascript Example:

(async (url, token, id) => {

  try{
    const response = await(
      await fetch(
        `${url}/int/v1/campaign/${id}`,
        {
          method: "GET",
          headers: {
            "Authorization": `Bearer ${token}`
          }
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN, process.env.CAMPAIGN_ID);

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
data	Object	optionalCampaign object. Present when success is true.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
  "success":true,
  "data":{
    "_id": "66022a461b7ab8f92e9844c7",
    "sharedGroups": [],
    "name": "Welcome to the All Staff Channel",
    "title": "Welcome to the All Staff Channel",
    "description": "We're super happy to have you here with us.",
    "categories": [],
    "imageUrl": "https://cf.communic8.com/poit/image/upload/w_600/v1705384435/c8test/John/pexels-nathan-cowley-1192671_GHyJS.jpg",
    "enableEmail": true,
    "enableMobileNotification": true,
    "commentVisibility": "disabled",
    "status": "1",
    "sender": {
        "_id": "60f4aeb09279e27183c0a9da",
        "email": "john@communic8.com",
        "firstName": "John",
        "lastName": "Smith",
        "displayName": "John Smith"
    },
    "sharedUsers": [
        {
            "_id": "60f4aeb09279e27183c0a9da",
            "email": "john@communic8.com",
            "firstName": "John",
            "lastName": "Smith",
            "displayName": "John Smith"
        }
    ],
    "adminIds": [
        "60f4aeb09279e27183c0a9da"
    ],
    "recipientAmount": 7,
    "campaignUrl": "https://test.communic8.com/admin/web/#/campaigns/sent/details/66022a461b7ab8f92e9844c7"
  }
}

Success response example - Error:

HTTP/1.1 200 OK
{
  "success":false,
  "message":"Not Found."
}

03. Get a campaign analytics report

Back to top

Get the analytics report of an individual campaign.

GET /int/v1/campaign/:id/report

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Parameters - Parameter

Name	Type	Description
id	String	(URL Query Parameter) campaign _id

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -X GET https://<url>/int/v1/campaign/<id>/report

Javascript Example:

(async (url, token, id) => {

  try{
    const response = await(
      await fetch(
        `${url}/int/v1/campaign/${id}/report`,
        {
          method: "GET",
          headers: {
            "Authorization": `Bearer ${token}`
          }
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN, process.env.CAMPAIGN_ID);

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
data	Object	optionalReport object. Present when success is true.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
  "success":true,
  "data":{
    "recipientsAmount": 7,
    "commentCount": 0,
    "readCount": 1,
    "likeCount": 0,
    "completeReadCount": 1,
    "emailCount": 1,
    "smsCount": 0,
    "mobileNotificationCount": 1
  }
}

04. Create (and send) a new campaign

Back to top

Create a new campaign to one or more existing or new client recipients. Supply a list of email addresses or recipient group IDs to send to existing recipients. Supply a list of recipient objects to send to new recipients.

POST /int/v1/campaign

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Request Body

Name	Type	Description
name	String	The campaign name
title	String	optional The campaign title. Used in email/mobile notifications. If not provided, the value of name will be used.
description	String	The campaign description. Used in email/mobile notifications.
status	String	optional Campaign status. By default the campaign will be sent (status "live"). If the value is "draft", the campaign will not be sent, and be saved as draft_Default value: live_ Allowed values: "live","draft"
scheduledTime	Date	optional scheduled go-live time for campaign in ISO 8601 format (only used if status is not already 'live' or 'draft')
templateId	String	optional campaign template id
templateData	String	optional the json data to render the template page by EJS syntax
categories	String	optional campaign category array, case sensitive. If not provided, the categories will come from the template
imageUrl	String	optional image url link of the campaign, by default it is from template. The image will be used in email and mobile app.
enableEmail	Boolean	optional campaign delivery by email, default is true unless it is disabled in the client_Default value: true_
enableMobileNotification	Boolean	optional campaign delivery by mobile, default is true unless it is disabled in the client_Default value: true_
emailReplyTo	String	optional campaign email reply email address
commentVisibility	String	optional Configuration for the comment of the campaign. "0" for comment only visible to campaign team, "1" for comment also visible to other recipeints in the campaign; default is "disabled", comment will be disabled_Default value: disabled_
senderUserEmail	String	optional Email address of the campaign sender user, it requires corresponding console user created. By default it is the token owner user. This is not the sender from email address used in campaign.
ownerUserEmail	String	optional Email address of the campaign owner, it requires corresponding console user created. By default it is the token owner user
sharedGroups	String[]	optional Array of team group id of the campaign
recipientEmails	String[]	optional Array of recipient emails. Mutually exclusive with recipientGroups and recipients.
recipientGroups	String[]	optional Array of recipient group IDs. Mutually exclusive with recipientEmails and recipients.
recipients	Object[]	optional Array of recipient object. Mutually exclusive with recipientEmails and recipientGroups.
recipients.email	String	recipient email
recipients.firstName	String	recipient first name
recipients.lastName	String	recipient last name

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -X POST https://<url>/int/v1/campaign \
     -d '{"name": "My new campaign", "description": "Welcome to my campaign", "templateId": "6304601198ed1f21a6219337"}'

Javascript Example:

(async (url, token) => {

  try{
    const response = await(
      await fetch(
        `${url}/int/v1/campaign`,
        {
          method: "POST",
          headers: {
            "Authorization": `Bearer ${token}`,
            "Content-Type": "application/json"
          },
          body: JSON.stringify(
            {
              "name": "My new campaign",
              "description": "Welcome to my campaign",
              "templateId": "6304601198ed1f21a6219337"
            }
          )
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN);

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
data	Object	optionalCampaign object. Present when success is true.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
   "success":true,
   "data": {
      "_id": "6082698f9523af9f3ff2dc50",
      "campaignUrl": "http://test.communic8.com/web/#/campaigns/sent/details/60827c1e58f3efedf54df6f5"
    }
}

Success response example - Error:

HTTP/1.1 200 OK
{
  "success":false,
  "message":"description is mandatory"
}

05. Update a campaign

Back to top

Update an existing campaign.

PUT /int/v1/campaign/:id

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Parameters - Parameter

Name	Type	Description
id	String	(URL Query Parameter) campaign _id

Request Body

Name	Type	Description
name	String	optional campaign name
title	String	optional campaign title which used in email/mobile notification, if not provided, the value of name will be used
description	String	optional campaign description which used in email/mobile notificaiton
status	String	optional Campaign status. Can only be updated for "draft" or "scheduled" campaigns.Allowed values: "live"
categories	String	optional campaign category array, case sensitive. If not provided, the categories will come from the template
imageUrl	String	optional image url link of the campaign, by default it is from template. The image will be used in email and mobile app.
enableEmail	Boolean	optional campaign delivery by email, default is true unless it is disabled in the client_Default value: true_
enableMobileNotification	Boolean	optional campaign delivery by mobile, default is true unless it is disabled in the client_Default value: true_
emailReplyTo	String	optional campaign email reply email address
commentVisibility	String	optional Configuration for the comment of the campaign. "0" for comment only visible to campaign team, "1" for comment also visible to other recipeints in the campaign; default is "disabled", comment will be disabled_Default value: disabled_
templateId	String	optional campaign template id
templateData	String	optional the json data to render the template page by EJS syntax

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -X PUT https://<url>/int/v1/campaign/<id> \
     -d '{"title": "My new campaign title"}'

Javascript Example:

(async (url, token, id) => {

  try{
    const response = await(
      await fetch(
        `${url}/int/v1/campaign/${id}`,
        {
          method: "PUT",
          headers: {
            "Authorization": `Bearer ${token}`,
            "Content-Type": "application/json"
          },
          body: JSON.stringify(
            {
              "title": "My new campaign title"
            }
          )
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN, process.env.CAMPAIGN_ID);

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
data	Object	optionalCampaign object. Present when success is true.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
   "success":true,
   "data": {
      "_id": "6082698f9523af9f3ff2dc50",
      "campaignUrl": "http://test.communic8.com/web/#/campaigns/sent/details/60827c1e58f3efedf54df6f5"
    }
}

Success response example - Error:

HTTP/1.1 200 OK
{
  "success":false,
  "message":"description is mandatory"
}

06. Close a campaign

Back to top

Close an existing campaign so that is inaccessible to recipients.

PUT /int/v1/campaign/:id/close

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Parameters - Parameter

Name	Type	Description
id	String	(URL Query Parameter) campaign _id

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -X PUT https://<url>/int/v1/campaign/<id>/close

Javascript Example:

(async (url, token, id) => {

  try{
    const response = await(
      await fetch(
        `${url}/int/v1/campaign/${id}/close`,
        {
          method: "PUT",
          headers: {
            "Authorization": `Bearer ${token}`,
            "Content-Type": "application/json"
          }
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN, process.env.CAMPAIGN_ID);

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
data	Object	optionalCampaign object. Present when success is true.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
   "success":true,
   "data": {
      "_id": "6082698f9523af9f3ff2dc50",
      "campaignUrl": "http://test.communic8.com/web/#/campaigns/sent/details/60827c1e58f3efedf54df6f5"
    }
}

07. Add recipients to a campaign

Back to top

Add one or more existing or new client recipients to a campaign. Supply a list of email addresses or recipient group IDs to send to existing recipients. Supply a list of recipient objects to send to new recipients.

PUT /int/v1/campaign/:id/addRecipients

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Parameters - Parameter

Name	Type	Description
id	String	(URL Query Parameter) campaign _id

Request Body

Name	Type	Description
recipientEmails	String[]	optional Array of recipient emails. Mutually exclusive with recipientGroups and recipients.
recipientGroups	String[]	optional Array of recipient group IDs. Mutually exclusive with recipientEmails and recipients.
recipients	Object[]	optional Array of recipient object. Mutually exclusive with recipientEmails and recipientGroups.
recipients.email	String	recipient email
recipients.firstName	String	recipient first name
recipients.lastName	String	recipient last name

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -X PUT https://<url>/int/v1/campaign/<id>/addRecipients \
     -d '{"recipientEmails": ["john@communic8.com"]}'

Javascript Example:

(async (url, token, id) => {

  try{
    const response = await(
      await fetch(
        `${url}/int/v1/campaign/${id}/addRecipients`,
        {
          method: "PUT",
          headers: {
            "Authorization": `Bearer ${token}`,
            "Content-Type": "application/json"
          },
          body: JSON.stringify(
            {
              "recipientEmails": [
                "john@communic8.com"
              ]
            }
          )   
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN, process.env.CAMPAIGN_ID);

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
data	Object	optionalCampaign object. Present when success is true.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
   "success":true,
   "data": {
      "_id": "6082698f9523af9f3ff2dc50",
      "campaignUrl": "http://localhost:6111/web/#/campaigns/sent/details/60827c1e58f3efedf54df6f5"
    }
}

08. Cancel campaign recipient

Back to top

cancel recipient in campaign

PUT /int/v1/campaign/:id/cancelRecipients

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Parameters - Parameter

Name	Type	Description
id	String	(URL Query Parameter) campaign _id

Request Body

Name	Type	Description
recipientEmails	String[]	optional Array of recipient emails

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -X PUT https://<url>/int/v1/campaign/<id>/cancelRecipients \
     -d '{"recipientEmails": ["john@communic8.com"]}'

Javascript Example:

(async (url, token, id) => {

  try{
    const response = await(
      await fetch(
        `${url}/int/v1/campaign/${id}/cancelRecipients`,
        {
          method: "PUT",
          headers: {
            "Authorization": `Bearer ${token}`,
            "Content-Type": "application/json"
          },
          body: JSON.stringify(
            {
              "recipientEmails": [
                "john@communic8.com"
              ]
            }
          )   
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN, process.env.CAMPAIGN_ID);

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
data	Object	optionalCampaign object. Present when success is true.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
   "success":true,
   "data": {
      "_id": "6082698f9523af9f3ff2dc50",
      "campaignUrl": "http://localhost:6111/web/#/campaigns/sent/details/60827c1e58f3efedf54df6f5"
    }
}

09. Get campaign survey data

Back to top

Get campaign survey data

GET /int/v1/campaign/:id/surveyData

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Parameters - URL Parameters

Name	Type	Description
id	String	Campaign _id value.

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -X GET https://<url>/int/v1/campaign/<id>/surveyData

Javascript Example:

(async (url, token, id) => {

  try{
    const response = await(
      await fetch(
        `${url}/int/v1/campaign/${id}/surveyData`,
        {
          method: "GET",
          headers: {
            "Authorization": `Bearer ${token}`
          }
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN, process.env.CAMPAIGN_ID);

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
  "success":true,
  "data": {
    "name": "Employee satisfaction survey",
    "anonymous": false,
    "senderName": "John Smith",
    "senderUserEmail": "john@communic8.com",
    "liveDate": "2024-01-18T23:53:10.789Z",
    "questions": [
        {
            "_id": "65a9b941df5626c3e310ccbb",
            "required": false,
            "desc": "",
            "title": "Satisfaction Survey",
            "options": [
                0,
                1,
                2,
                3,
                4,
                5,
                6,
                7,
                8,
                9,
                10
            ],
            "tags": [],
            "matrixQuestions": []
        }
    ],
    "result": [
        {
            "responseSubmitted": true,
            "read": true,
            "submitted": true,
            "submittedDate": "2024-05-13T05:29:00.639Z",
            "userId": "60f4aeb09279e27183c0a9da",
            "userDisplayName": "John Smith",
            "userEmail": "john@communic8.com",
            "responseDuration": 9431014,
            "q.1": 10
        }
    ]
  }
}

Success response example - Error:

HTTP/1.1 200 OK
{
  "success":false,
  "message":"Campaign is not a survey"
}

10. List campaign files

Back to top

Get a list of files linked to a campaign. Items are return in alphabetical order by name.

GET /int/v1/campaign/:id/file

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Parameters - URL Parameters

Name	Type	Description
id	String	Campaign _id value.

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -X GET https://<url>/int/v1/campaign/<id>/file

Javascript Example:

(async (url, token, id) => {

  try{
    const response = await(
      await fetch(
        `${url}/int/v1/campaign/${id}/file`,
        {
          method: "GET",
          headers: {
            "Authorization": `Bearer ${token}`,
            "Content-Type": "application/json"
          }
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN, process.env.CAMPAIGN_ID);

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
message	String	optionalError message. Present when success is false.
data	Array	optionalList of campaign file objects. Present when success is true.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
  "success":true,
  "data": [
    {
      "_id": "664175738ec4cb1c684b5fb7",
      "campaignId": "65dff01ac8072756ac1b7947",
      "draftUsed": false,
      "activeUsed": false,
      "name": "Screenshot_2024-05-09_at_3.25.02 pm.png",
      "type": "file",
      "media": "image",
      "ready": true,
      "deleted": false,
      "mime": "image/png",
      "_type": "pb_c_campaign_file",
      "size": 1121,
      "width": 44,
      "height": 42,
      "format": "png",
      "mDate": "2024-05-13T02:05:39.983Z",
      "aDate": "2024-05-13T02:05:39.773Z",
      "__v": 0,
      "VersionId": "wxZ33s5PxQ9Z48eXsjEI4i6Vr.btVZ3M",
      "lastVersionDate": "2024-05-13T02:05:39.972Z",
      "storageId": "test/cmp/65dff01ac8072756ac1b7947/image/664175738ec4cb1c684b5fb7/Screenshot_2024-05-09_at_3.25.02 pm.png",
      "url": "/file/664175738ec4cb1c684b5fb7/Screenshot_2024-05-09_at_3.25.02 pm.png"
    }
  ]
}

Success response example - Error:

HTTP/1.1 200 OK
{
  "success":false,
  "message":"campaign Id is required"
}

11. Read campaign file details by file id

Back to top

Get the details of an individual campaign file.

GET /int/v1/campaign/:id/file/:fileId

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Parameters - URL Parameters

Name	Type	Description
id	String	Campaign _id value.
fileId	String	File _id value.

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -X GET https://<url>/int/v1/campaign/<id>/file/<fileId>

Javascript Example:

(async (url, token, id, fileId) => {

  try{
    const response = await(
      await fetch(
        `${url}/int/v1/campaign/${id}/file/${fileId}`,
        {
          method: "GET",
          headers: {
            "Authorization": `Bearer ${token}`,
            "Content-Type": "application/json"
          }
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN, process.env.CAMPAIGN_ID, process.env.FILE_ID);

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
data	Object	optionalThe campaign file object. Present when success is true.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
  "success":true,
  "data": {
    "_id": "664175738ec4cb1c684b5fb7",
    "campaignId": "65dff01ac8072756ac1b7947",
    "draftUsed": false,
    "activeUsed": false,
    "name": "Screenshot_2024-05-09_at_3.25.02 pm.png",
    "type": "file",
    "media": "image",
    "ready": true,
    "deleted": false,
    "mime": "image/png",
    "_type": "pb_c_campaign_file",
    "size": 1121,
    "width": 44,
    "height": 42,
    "format": "png",
    "mDate": "2024-05-13T02:05:39.983Z",
    "aDate": "2024-05-13T02:05:39.773Z",
    "__v": 0,
    "VersionId": "wxZ33s5PxQ9Z48eXsjEI4i6Vr.btVZ3M",
    "lastVersionDate": "2024-05-13T02:05:39.972Z",
    "storageId": "test/cmp/65dff01ac8072756ac1b7947/image/664175738ec4cb1c684b5fb7/Screenshot_2024-05-09_at_3.25.02 pm.png",
    "url": "/file/664175738ec4cb1c684b5fb7/Screenshot_2024-05-09_at_3.25.02 pm.png"
  }
}

Success response example - Error:

HTTP/1.1 200 OK
{
  "success":false,
  "message":"campaign Id is required"
}

12. Upload a new campaign file

Back to top

Create a new file and link it to a campaign.

POST /int/v1/campaign/:id/file

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).
Content-Type	String	multipart/form-data

Parameters - URL Parameters

Name	Type	Description
id	String	Campaign _id value.

Request Body

Name	Type	Description
file	File	New file data.
media	String	optional Media type of new file_Default value: raw_ Allowed values: 'raw','image','video'

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -X POST https://<url>/int/v1/campaign/<id>/file \
     -F file=@image.png -F media=image

Javascript Example:

(async (url, token, id) => {
  try{
    const fs = require('fs/promises');
    const fileName = "image.png";
    const filePath = `./${fileName}`;
    const body = new FormData();
    const blob = new Blob([await fs.readFile(filePath)]);
    body.set("media", "image");
    body.set("file", blob, fileName);

    const response = await(
      await fetch(
        `${url}/int/v1/campaign/${id}/file`,
        {
          method: "POST",
          headers: {
            "Authorization": `Bearer ${token}`
          },
          body
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN, process.env.CAMPAIGN_ID);

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
data	Object	optionalThe new file object. Present when success is true.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
  "success":true,
  "data": {
    "_id": "664175738ec4cb1c684b5fb7",
    "campaignId": "65dff01ac8072756ac1b7947",
    "draftUsed": false,
    "activeUsed": false,
    "name": "Screenshot_2024-05-09_at_3.25.02 pm.png",
    "type": "file",
    "media": "image",
    "ready": true,
    "deleted": false,
    "mime": "image/png",
    "_type": "pb_c_campaign_file",
    "size": 1121,
    "width": 44,
    "height": 42,
    "format": "png",
    "mDate": "2024-05-13T02:05:39.983Z",
    "aDate": "2024-05-13T02:05:39.773Z",
    "__v": 0,
    "VersionId": "wxZ33s5PxQ9Z48eXsjEI4i6Vr.btVZ3M",
    "lastVersionDate": "2024-05-13T02:05:39.972Z",
    "storageId": "test/cmp/65dff01ac8072756ac1b7947/image/664175738ec4cb1c684b5fb7/Screenshot_2024-05-09_at_3.25.02 pm.png",
    "url": "/file/664175738ec4cb1c684b5fb7/Screenshot_2024-05-09_at_3.25.02 pm.png"
  }
}

Success response example - Error:

HTTP/1.1 200 OK
{
  "success":false,
  "message":"campaign Id is required"
}

13. Upload new version of existing campaign file

Back to top

Upload and replace an existing campaign file with a new version

POST /int/v1/campaign/:id/file/:fileId

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).
Content-Type	String

Parameters - URL Parameters

Name	Type	Description
id	String	Campaign _id value.
fileId	String	File _id value.

Request Body

Name	Type	Description
file	File	New file data.
media	String	optional Media type of new file_Default value: raw_ Allowed values: 'raw','image','video'

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -X POST https://<url>/int/v1/campaign/<id>/file/<fileId> \
     -F file=@image.png -F media=image

Javascript Example:

(async (url, token, id, fileId) => {
  try{
    const fs = require('fs/promises');
    const fileName = "image.png";
    const filePath = `./${fileName}`;
    const body = new FormData();
    const blob = new Blob([await fs.readFile(filePath)]);
    body.set("media", "image");
    body.set("file", blob, fileName);

    const response = await(
      await fetch(
        `${url}/int/v1/campaign/${id}/file/${fileId}`,
        {
          method: "POST",
          headers: {
            "Authorization": `Bearer ${token}`
          },
          body
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN, process.env.CAMPAIGN_ID, process.env.FILE_ID);

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
data	Object	optionalThe updated file object. Present when success is true.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
  "success":true,
  "data": {
    "_id": "664175738ec4cb1c684b5fb7",
    "campaignId": "65dff01ac8072756ac1b7947",
    "draftUsed": false,
    "activeUsed": false,
    "name": "Screenshot_2024-05-09_at_3.25.02 pm.png",
    "type": "file",
    "media": "image",
    "ready": true,
    "deleted": false,
    "mime": "image/png",
    "_type": "pb_c_campaign_file",
    "size": 1121,
    "width": 44,
    "height": 42,
    "format": "png",
    "mDate": "2024-05-13T02:05:39.983Z",
    "aDate": "2024-05-13T02:05:39.773Z",
    "__v": 0,
    "VersionId": "wxZ33s5PxQ9Z48eXsjEI4i6Vr.btVZ3M",
    "lastVersionDate": "2024-05-13T02:05:39.972Z",
    "storageId": "test/cmp/65dff01ac8072756ac1b7947/image/664175738ec4cb1c684b5fb7/Screenshot_2024-05-09_at_3.25.02 pm.png",
    "url": "/file/664175738ec4cb1c684b5fb7/Screenshot_2024-05-09_at_3.25.02 pm.png"
  }
}

Success response example - Error:

HTTP/1.1 200 OK
{
  "success":false,
  "message":"campaign Id is required"
}

14. Delete existing campaign file

Back to top

Delete an existing campaign file. If the file is in use, the operation will fail unless the deleteFileInUse query parameter is set to true.

DELETE /int/v1/campaign/:id/file/:fileId

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Parameters - URL Parameters

Name	Type	Description
id	String	Campaign _id value.
fileId	String	File _id value.

Parameters - URL Query Parameters

Name	Type	Description
deleteFileInUse	String	optional Delete the file even if it is in use.Default value: false

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
     -X DELETE https://<url>/int/v1/campaign/<id>/file/<fileId>

Javascript Example:

(async (url, token, id, fileId) => {
  try{
    const response = await(
      await fetch(
        `${url}/int/v1/campaign/${id}/file/${fileId}`,
        {
          method: "DELETE",
          headers: {
            "Authorization": `Bearer ${token}`
          }
        }
      )
    ).json();
    console.log("API response:", response);
  }catch(error){
    console.error("API error:", error);
  }
})(process.env.URL, process.env.TOKEN, process.env.CAMPAIGN_ID, process.env.FILE_ID);

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
  "success":true
}

Success response example - Error:

HTTP/1.1 200 OK
{
  "success":false,
  "message":"Please confirm delete for file used in campaign content."
}

15. Create a campaign survey

Back to top

Create a new survey campaign. This operation creates a 'draft' status campaign with the requested survey questions. If a campaign template is provided that already includes one or more survey subsections, this operation will overwrite the first survey subsection with the requested questions.

POST /int/v1/campaign/survey

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Request Body

Name	Type	Description
name	String	The campaign name
title	String	optional The campaign title. Used in email/mobile notifications. If not provided, the value of name will be used.
description	String	The campaign description. Used in email/mobile notifications.
templateId	String	optional campaign template id.
templateData	String	optional the json data to render the template page by EJS syntax.
questions	Object[]	Array of survey questions to update the campaign with.
questions.templateCode	String	Question type.Allowed values: "input","textarea","radio","dropdown","multiselect","matrix","rank","rating","date","time","email","number"
questions.title	String	The title label of the question.
questions.desc	String	optional Description text for the question.
questions.placeholder	String	optional Text that appears in the form control when it has no value set.
questions.required	Boolean	optional The question requires a response before survey can be submitted.Default value: true
questions.questionId	String	optional Unique identifier name for matching fork questions to their child branch questions.
questions.fork	Boolean	optional The question supports forking answers. When fork=true, a 'questionId' parameter must also be provided, so that answer options can be linked to subsequent child 'branch questions' via their questionIds.Default value: false
questions.branch	Boolean	optional The question is a branch from a previous 'fork question'. Branch questions must provide a 'questionId' parameter so they can be referenced by the answer options in a fork question.Default value: false
questions.options	`String[]	Number[]
questions.options.value	`String	Number`
questions.options.branchQuestionId	`String	Number`
questions.layout	String	optional Layout direction of answer options in "radio" and "multiselect" type questions.Default value: Horizontal Allowed values: "Horizontal, Vertical"
questions.hideText	String	optional Hide the answser option text in "radio" or "multiselect" type questions.Default value: false
questions.zeroLabel	String	optional Text label for the lower extreme of a "rating" type question.
questions.tenLabel	String	optional Text label for the upper extreme of a "rating" type question.
questions.min	Number	optional Lowest accepted answer to a "number" type question.Default value: -9999999999
questions.max	Number	optional Highest accepted answer to a "number" type question.Default value: 9999999999
questions.decimal	Number	optional Number of decimal digits accepted in a "number" type question.Default value: 2 Allowed values: -99
questions.matrixQuestions	String[]	optional List of answer options to use as the row labels (vertical axis) in a "matrix" type question.
surveySettings	Object	optional Survey settings configuration object.
surveySettings.show_questions_individually	Boolean	optional Show each question on its own page.Default value: false
surveySettings.show_user_response	Boolean	optional Allow the recipient to view already submitted survey responses.Default value: false
surveySettings.full_height	Boolean	optional Makes the survey subsection's minimum height match the screen height.Default value: false
surveySettings.adaptive_height	Boolean	optional Makes the survey subsection height adapt to the height of the current question.Default value: false
surveySettings.text_width	String	optional The width of the titles and descriptions *relative to the form width (not the page)Default value: 100%
surveySettings.text_color	String	optional The color of survey title and description text fields.Default value: #ffffff
surveySettings.text_position	String	optional The position of the titles and descriptions.Default value: Left Allowed values: "Left","Right","Center"
surveySettings.input_width	String	optional The width of the text, textarea, number, email and dropdown form fields, relative to the form width (not the page)Default value: 100%
surveySettings.input_color	String	optional The color of active text fields and selected options.Default value: #ffffff
surveySettings.input_position	String	optional The position of the question inputs within the form.Default value: Left Allowed values: "Left","Right","Center"
surveySettings.required_color	String	optional The color of the "required" text for mandatory questions.Default value: #ea4f4f
surveySettings.page_button_position	String	optional The position of the previous and next buttons.Default value: Bottom Allowed values: "Top","Bottom"
surveySettings.prev_button_text_color	String	optional Text Color of the 'Previous' question page button_Default value: #ffffff_
surveySettings.prev_button_background_color	String	optional Color of the 'Previous' question page button_Default value: #070707_
surveySettings.next_button_text_color	String	optional Text Color of the 'Next' question page button_Default value: #ffffff_
surveySettings.next_button_background_color	String	optional Color of the 'Previous' question page button_Default value: #070707_

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
        -H "Content-Type: application/json" \
        -X POST https://<url>/int/v1/campaign/survey \
        -d '{ "questions": [{
              "templateCode": "input",
              "title": "Text Example",
              "desc": "What is your answer to this survey question?"
            }]}'

Javascript Example:

try {
  const url = process.env.URL;
  const token = process.env.TOKEN;
  const options = {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ "questions": [{
      "templateCode": "input",
      "title": "Text Example",
      "desc": "What is your answer to this survey question?"
    }]}),
  };
  const response = await fetch(`https://${url}/int/v1/campaign/survey`, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

Question Types Example:

// The payload in this example demonstrates intended usage of the 12 available question 'templateCode' types
try {
  const url = process.env.URL;
  const token = process.env.TOKEN;
  const options = {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ "questions": [
      {
        "templateCode": "input",
        "title": "Text Example",
        "placeholder": "Please write a short response here",
        "desc": "What is your answer to this survey question?",
        "required": true
      },
      {
        "templateCode": "textarea",
        "title": "Long Text Example",
        "required": false,
        "placeholder": "Please write a longer response here",
        "desc": "Optionally describe how you arrived at the answer above."
      },
      {
        "templateCode": "radio",
        "title": "Single Select Example",
        "required": false,
        "desc": "Preferred web browser?",
        "options": [
          "Chrome",
          "Edge",
          "Safari",
          "Firefox",
          "Other"
        ],
        "layout": "Horizontal"
      },
      {
        "templateCode": "dropdown",
        "title": "Dropdown Example",
        "placeholder": "Please select a web browser",
        "desc": "Preferred web browser?",
        "required": false,
        "options": [
          "Chrome",
          "Edge",
          "Safari",
          "Firefox",
          "Other"
        ]
      },
      {
        "templateCode": "multiselect",
        "title": "Multi Select Example",
        "desc": "Preferred web browser(s)?",
        "required": false,
        "options": [
          "Chrome",
          "Edge",
          "Safari",
          "Firefox",
          "Other"
        ],
        "layout": "Horizontal"
      },
      {
        "templateCode": "matrix",
        "title": "Matrix Example",
        "desc": "Preferred web browser per platform?",
        "required": false,
        "options": [
          "Chrome",
          "Edge",
          "Safari",
          "Firefox",
          "Other"
        ],
        "matrixQuestions": [
          "Desktop",
          "Laptop",
          "Mobile"
        ]
      },
      {
        "templateCode": "rank",
        "title": "Ranking Example",
        "desc": "Please order your preferences from 1 (most favourite) to 3 (least favourite)",
        "required": false,
        "options": [
          "Apples",
          "Oranges",
          "Bananas"
        ]
      },
      {
        "templateCode": "rating",
        "title": "Rating Example",
        "desc": "How likely are you to complete this survey more than once?",
        "required": false,
        "hideText": false,
        "zeroLabel": "Extremely Unlikely",
        "tenLabel": "Extremely Likely",
        "options": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
      },
      {
        "templateCode": "date",
        "title": "Date Example",
        "placeholder": "16 July 1969",
        "desc": "Please select any day of the year",
        "required": false
      },
      {
        "templateCode": "time",
        "title": "Time Example",
        "desc": "Please specify any time of day",
        "required": false
      },
      {
        "templateCode": "email",
        "title": "Email Example",
        "placeholder": "Please enter a valid email address",
        "desc": "What is your email address?",
        "required": false
      },
      {
        "templateCode": "number",
        "title": "Number Example",
        "placeholder": "Please enter a number between 1 and 100",
        "min": 1,
        "max": 100,
        "decimal": 0,
        "desc": "Can you guess what number I am thinking of?",
        "required": false
      }
    ]}),
  };
  const response = await fetch(`https://${url}/int/v1/campaign/survey`, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

Fork/Branch Example:

// The payload in this example demonstrates intended usage of fork and branch subquestions.
// In question "fork1", when a respondent selects "Chrome", "branch1" and "branch3" questions will become active and "branch2" will remain hidden.
// When "FireFox" is selected, "branch2" and "branch3" will become active and "branch1" will remain hidden.
  try {
    const url = process.env.URL;
    const token = process.env.TOKEN;
    const options = {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ "questions": [
        {
          "questionId": "fork1",
          "fork": true,
          "templateCode": "multiselect",
          "title": "Fork Example",
          "desc": "Preferred web browser?",
          "required": false,
          "options": [
            {
              "value": "Chrome",
              "branchQuestions": ["branch1", "branch3"]
            },
            {
              "value": "Firefox",
              "branchQuestions": ["branch2", "branch3"]
            }
          ],
          "layout": "Horizontal"
        },
        {
          "questionId": "branch1",
          "branch": true,
          "templateCode": "rating",
          "title": "Branch #1 Example",
          "desc": "How much do you like Chrome?",
          "required": false,
          "zeroLabel": "Not at all",
          "tenLabel": "Very much",
          "options": [ 0, 1, 2, 3, 4, 5]
        },
        {
          "questionId": "branch2",
          "branch": true,
          "templateCode": "rating",
          "title": "Branch #2 Example",
          "desc": "How much do you like Firefox?",
          "required": false,
          "zeroLabel": "Not at all",
          "tenLabel": "Very much",
          "options": [ 0, 1, 2, 3, 4, 5]
        },
        {
          "questionId": "branch3",
          "branch": true,
          "templateCode": "input",
          "title": "Branch #3 Example",
          "desc": "Additional feedback about your browser choice.",
          "required": false
        }
      ]}),
    };
    const response = await fetch(`https://${url}/int/v1/campaign/survey`, options);
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error(error);
  }

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
data	Object	optionalCampaign object. Present when success is true.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
   "success":true,
   "data": {
      "_id": "6082698f9523af9f3ff2dc50",
      "campaignUrl": "http://test.communic8.com/web/#/campaigns/sent/details/60827c1e58f3efedf54df6f5"
    }
}

Success response example - Error:

HTTP/1.1 200 OK
{
  "success":false,
  "message":"Invalid campaign ID for survey creation, 'draft' campaign required"
}

16. Update a campaign survey

Back to top

Update survey questions on an existing draft campaign. This operation will create a new survey subsection on the draft campaign, or overwrite the first survey subsection when one or more survey subsections already exists.

PUT /int/v1/campaign/survey/:id

Headers - Header

Name	Type	Description
Authorization	String	Prefix with "Bearer ". Token value (either Access Key from Admin Console or access_token via OAuth result).

Parameters - Parameter

Name	Type	Description
id	String	campaign record ID

Request Body

Name	Type	Description
questions	Object[]	Array of survey questions to update the campaign with.
questions.templateCode	String	Question type.Allowed values: "input","textarea","radio","dropdown","multiselect","matrix","rank","rating","date","time","email","number"
questions.title	String	The title label of the question.
questions.desc	String	optional Description text for the question.
questions.placeholder	String	optional Text that appears in the form control when it has no value set.
questions.required	Boolean	optional The question requires a response before survey can be submitted.Default value: true
questions.questionId	String	optional Unique identifier name for matching fork questions to their child branch questions.
questions.fork	Boolean	optional The question supports forking answers. When fork=true, a 'questionId' parameter must also be provided, so that answer options can be linked to subsequent child 'branch questions' via their questionIds.Default value: false
questions.branch	Boolean	optional The question is a branch from a previous 'fork question'. Branch questions must provide a 'questionId' parameter so they can be referenced by the answer options in a fork question.Default value: false
questions.options	`String[]	Number[]
questions.options.value	`String	Number`
questions.options.branchQuestionId	`String	Number`
questions.layout	String	optional Layout direction of answer options in "radio" and "multiselect" type questions.Default value: Horizontal Allowed values: "Horizontal, Vertical"
questions.hideText	String	optional Hide the answser option text in "radio" or "multiselect" type questions.Default value: false
questions.zeroLabel	String	optional Text label for the lower extreme of a "rating" type question.
questions.tenLabel	String	optional Text label for the upper extreme of a "rating" type question.
questions.min	Number	optional Lowest accepted answer to a "number" type question.Default value: -9999999999
questions.max	Number	optional Highest accepted answer to a "number" type question.Default value: 9999999999
questions.decimal	Number	optional Number of decimal digits accepted in a "number" type question.Default value: 2 Allowed values: -99
questions.matrixQuestions	String[]	optional List of answer options to use as the row labels (vertical axis) in a "matrix" type question.
surveySettings	Object	optional Survey settings configuration object.
surveySettings.show_questions_individually	Boolean	optional Show each question on its own page.Default value: false
surveySettings.show_user_response	Boolean	optional Allow the recipient to view already submitted survey responses.Default value: false
surveySettings.full_height	Boolean	optional Makes the survey subsection's minimum height match the screen height.Default value: false
surveySettings.adaptive_height	Boolean	optional Makes the survey subsection height adapt to the height of the current question.Default value: false
surveySettings.text_width	String	optional The width of the titles and descriptions *relative to the form width (not the page)Default value: 100%
surveySettings.text_color	String	optional The color of survey title and description text fields.Default value: #ffffff
surveySettings.text_position	String	optional The position of the titles and descriptions.Default value: Left Allowed values: "Left","Right","Center"
surveySettings.input_width	String	optional The width of the text, textarea, number, email and dropdown form fields, relative to the form width (not the page)Default value: 100%
surveySettings.input_color	String	optional The color of active text fields and selected options.Default value: #ffffff
surveySettings.input_position	String	optional The position of the question inputs within the form.Default value: Left Allowed values: "Left","Right","Center"
surveySettings.required_color	String	optional The color of the "required" text for mandatory questions.Default value: #ea4f4f
surveySettings.page_button_position	String	optional The position of the previous and next buttons.Default value: Bottom Allowed values: "Top","Bottom"
surveySettings.prev_button_text_color	String	optional Text Color of the 'Previous' question page button_Default value: #ffffff_
surveySettings.prev_button_background_color	String	optional Color of the 'Previous' question page button_Default value: #070707_
surveySettings.next_button_text_color	String	optional Text Color of the 'Next' question page button_Default value: #ffffff_
surveySettings.next_button_background_color	String	optional Color of the 'Previous' question page button_Default value: #070707_

Examples

CURL Example:

curl -H "Authorization: Bearer <token>" \
        -H "Content-Type: application/json" \
        -X PUT https://<url>/int/v1/campaign/survey/<id> \
        -d '{ "questions": [{
              "templateCode": "input",
              "title": "Text Example",
              "desc": "What is your answer to this survey question?"
            }]}'

Javascript Example:

try {
  const url = process.env.URL;
  const token = process.env.TOKEN;
  const id = process.env.CHANNEL_ID;
  const options = {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ "questions": [{
      "templateCode": "input",
      "title": "Text Example",
      "desc": "What is your answer to this survey question?"
    }]}),
  };
  const response = await fetch(`https://${url}/int/v1/campaign/survey/${id}`, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

Question Types Example:

// The payload in this example demonstrates intended usage of the 12 available question 'templateCode' types
try {
  const url = process.env.URL;
  const token = process.env.TOKEN;
  const id = process.env.CHANNEL_ID;
  const options = {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ "questions": [
      {
        "templateCode": "input",
        "title": "Text Example",
        "placeholder": "Please write a short response here",
        "desc": "What is your answer to this survey question?",
        "required": true
      },
      {
        "templateCode": "textarea",
        "title": "Long Text Example",
        "required": false,
        "placeholder": "Please write a longer response here",
        "desc": "Optionally describe how you arrived at the answer above."
      },
      {
        "templateCode": "radio",
        "title": "Single Select Example",
        "required": false,
        "desc": "Preferred web browser?",
        "options": [
          "Chrome",
          "Edge",
          "Safari",
          "Firefox",
          "Other"
        ],
        "layout": "Horizontal"
      },
      {
        "templateCode": "dropdown",
        "title": "Dropdown Example",
        "placeholder": "Please select a web browser",
        "desc": "Preferred web browser?",
        "required": false,
        "options": [
          "Chrome",
          "Edge",
          "Safari",
          "Firefox",
          "Other"
        ]
      },
      {
        "templateCode": "multiselect",
        "title": "Multi Select Example",
        "desc": "Preferred web browser(s)?",
        "required": false,
        "options": [
          "Chrome",
          "Edge",
          "Safari",
          "Firefox",
          "Other"
        ],
        "layout": "Horizontal"
      },
      {
        "templateCode": "matrix",
        "title": "Matrix Example",
        "desc": "Preferred web browser per platform?",
        "required": false,
        "options": [
          "Chrome",
          "Edge",
          "Safari",
          "Firefox",
          "Other"
        ],
        "matrixQuestions": [
          "Desktop",
          "Laptop",
          "Mobile"
        ]
      },
      {
        "templateCode": "rank",
        "title": "Ranking Example",
        "desc": "Please order your preferences from 1 (most favourite) to 3 (least favourite)",
        "required": false,
        "options": [
          "Apples",
          "Oranges",
          "Bananas"
        ]
      },
      {
        "templateCode": "rating",
        "title": "Rating Example",
        "desc": "How likely are you to complete this survey more than once?",
        "required": false,
        "hideText": false,
        "zeroLabel": "Extremely Unlikely",
        "tenLabel": "Extremely Likely",
        "options": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
      },
      {
        "templateCode": "date",
        "title": "Date Example",
        "placeholder": "16 July 1969",
        "desc": "Please select any day of the year",
        "required": false
      },
      {
        "templateCode": "time",
        "title": "Time Example",
        "desc": "Please specify any time of day",
        "required": false
      },
      {
        "templateCode": "email",
        "title": "Email Example",
        "placeholder": "Please enter a valid email address",
        "desc": "What is your email address?",
        "required": false
      },
      {
        "templateCode": "number",
        "title": "Number Example",
        "placeholder": "Please enter a number between 1 and 100",
        "min": 1,
        "max": 100,
        "decimal": 0,
        "desc": "Can you guess what number I am thinking of?",
        "required": false
      }
    ]}),
  };
  const response = await fetch(`https://${url}/int/v1/campaign/survey/${id}`, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

Fork/Branch Example:

// The payload in this example demonstrates intended usage of fork and branch subquestions.
// In question "fork1", when a respondent selects "Chrome", "branch1" and "branch3" questions will become active and "branch2" will remain hidden.
// When "FireFox" is selected, "branch2" and "branch3" will become active and "branch1" will remain hidden.
  try {
    const url = process.env.URL;
    const token = process.env.TOKEN;
    const id = process.env.CHANNEL_ID;
    const options = {
      method: 'PUT',
      headers: {
        Authorization: `Bearer ${token}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ "questions": [
        {
          "questionId": "fork1",
          "fork": true,
          "templateCode": "multiselect",
          "title": "Fork Example",
          "desc": "Preferred web browser?",
          "required": false,
          "options": [
            {
              "value": "Chrome",
              "branchQuestions": ["branch1", "branch3"]
            },
            {
              "value": "Firefox",
              "branchQuestions": ["branch2", "branch3"]
            }
          ],
          "layout": "Horizontal"
        },
        {
          "questionId": "branch1",
          "branch": true,
          "templateCode": "rating",
          "title": "Branch #1 Example",
          "desc": "How much do you like Chrome?",
          "required": false,
          "zeroLabel": "Not at all",
          "tenLabel": "Very much",
          "options": [ 0, 1, 2, 3, 4, 5]
        },
        {
          "questionId": "branch2",
          "branch": true,
          "templateCode": "rating",
          "title": "Branch #2 Example",
          "desc": "How much do you like Firefox?",
          "required": false,
          "zeroLabel": "Not at all",
          "tenLabel": "Very much",
          "options": [ 0, 1, 2, 3, 4, 5]
        },
        {
          "questionId": "branch3",
          "branch": true,
          "templateCode": "input",
          "title": "Branch #3 Example",
          "desc": "Additional feedback about your browser choice.",
          "required": false
        }
      ]}),
    };
    const response = await fetch(`https://${url}/int/v1/campaign/survey/${id}`, options);
    const data = await response.json();
    console.log(data);
  } catch (error) {
    console.error(error);
  }

Success response

Success response - Success 200

Name	Type	Description
success	Boolean	Indicates whether the operation was successful.
data	Object	optionalCampaign object. Present when success is true.
message	String	optionalError message. Present when success is false.

Success response example

Success response example - Success:

HTTP/1.1 200 OK
{
   "success":true,
   "data": {
      "_id": "6082698f9523af9f3ff2dc50",
      "campaignUrl": "http://test.communic8.com/web/#/campaigns/sent/details/60827c1e58f3efedf54df6f5"
    }
}

Success response example - Error:

HTTP/1.1 200 OK
{
  "success":false,
  "message":"Invalid campaign ID for survey creation, 'draft' campaign required"
}