A set of APIs are provided for integrating the Engage systems with your existing systems.
\nThese APIs can be used directly or in third party tools.
\nVersion : 1.0
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Overview","slug":"overview"}],"owner":"27614813","collectionId":"2379c199-c8db-442e-95ae-03b92fed7e3c","publishedId":"2s9YJgUM73","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2023-10-10T21:46:26.000Z"},"item":[{"name":"Ping","id":"b48f8d39-ab2d-4e26-b7c2-8dadc588f1e6","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"/api//integration/ping","description":"Ping is used to confirm the API is running
\n","urlObject":{"path":["api","","integration","ping"],"host":[""],"query":[],"variable":[]}},"response":[{"id":"2092dd76-f84b-4606-a940-8349f5431da2","name":"Ping","originalRequest":{"method":"GET","header":[],"url":"/api//integration/ping"},"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"success\": true,\r\n \"response\": \"pong\"\r\n}"}],"_postman_id":"b48f8d39-ab2d-4e26-b7c2-8dadc588f1e6"},{"name":"Token","event":[{"listen":"test","script":{"id":"2635e132-3b09-4fb8-996d-f7c06c9c033e","exec":["try","{"," pm.globals.set(\"access_token\", pm.response.json().token);"," console.log(pm.globals.get(\"access_token\"));","}","catch(ex)","{"," console.log(ex);","}"],"type":"text/javascript","packages":{}}}],"id":"b13b437e-5fdd-4869-bd9b-c2b773c3c145","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"email\": \"jane.smith@acme-corporation.com.au\",\r\n \"grant_type\": \"password\"\r\n}"},"url":"/api//integration/account/token","description":"The API uses several levels of authorization. Requests require a JWT to be provided as a bearer token. The token can be generated using your username and password provided. Survey specific queries also require the API key provided for each survey.
\n","urlObject":{"path":["api","","integration","account","token"],"host":[""],"query":[],"variable":[]}},"response":[{"id":"52fdff88-273c-496d-a19e-8b083e18d5fe","name":"Token","originalRequest":{"method":"POST","header":[{"key":"Content-Type","name":"Content-Type","type":"text","value":"application/json"}],"body":{"mode":"raw","raw":"{\r\n \"email\": \"jane.smith@acme-corporation.com.au\",\r\n \"password\": \"insert-password!\",\r\n \"grant_type\": \"password\"\r\n}"},"url":"/api//integration/account/token"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"token\": \"your-token-will-be-returned-here\"\r\n}"}],"_postman_id":"b13b437e-5fdd-4869-bd9b-c2b773c3c145"},{"name":"Survey List","event":[{"listen":"prerequest","script":{"exec":[""],"type":"text/javascript","id":"c6f4ab37-8fb7-44a0-9295-755cffe3a48c"}},{"listen":"test","script":{"exec":["try\r","{\r"," pm.globals.set(\"survey-ref\", pm.response.json()[0].surveyRef);\r"," console.log(pm.globals.get(\"survey-ref\"));\r","}\r","catch(ex)\r","{\r"," console.log(ex);\r","}"],"type":"text/javascript","id":"ce0fbba7-9531-4427-9cb8-a416ced55cb8"}}],"id":"1ef0ac31-c3de-4771-a839-d544985a001b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":"{{access_token}}"},"isInherited":false},"method":"GET","header":[],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"/api//integration/survey","description":"The list of surveys you have access to can be retrieved to get the survey details including the reference.
\n","urlObject":{"path":["api","","integration","survey"],"host":[""],"query":[],"variable":[]}},"response":[{"id":"e386da78-e0b3-4f39-9bb8-c2d276c14556","name":"Survey List","originalRequest":{"method":"GET","header":[{"key":"ApiKey","value":"insert-your-survey-apikey-here","type":"text"}],"url":"/api//integration/survey"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"[\r\n {\r\n \"surveyRef\": \"136b79d8-2b51-4387-bffc-91ddab1b3c91\",\r\n \"name\": \"(SAMPLE) Onboarding Survey\",\r\n \"surveyType\": \"Onboarding Survey\",\r\n \"audienceType\": \"Invitational\",\r\n \"dateFrom\": \"2020-01-01T01:43:00\",\r\n \"dateTo\": \"2023-12-31T23:59:00\",\r\n \"status\": \"Live\"\r\n },\r\n {\r\n \"surveyRef\": \"f5d3bbe9-b943-43cb-b0f5-bde1157504ab\",\r\n \"name\": \"(SAMPLE) Exit Survey\",\r\n \"surveyType\": \"Exit Survey\",\r\n \"audienceType\": \"Invitational\",\r\n \"dateFrom\": \"2021-01-01T22:47:00\",\r\n \"dateTo\": \"2021-12-31T22:47:00\",\r\n \"status\": \"Live\"\r\n }\r\n]"}],"_postman_id":"1ef0ac31-c3de-4771-a839-d544985a001b"},{"name":"Demographic Data-Dictionary","id":"5367b4ed-22e5-4c20-8096-39a33245f80a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":"{{access_token}}"},"isInherited":false},"method":"GET","header":[],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"/api//integration/survey/{{survey-ref}}/demographics/data-dictionary","description":"The demographic data dictionary is used to get the list of demographics that can be used when inviting participants. These pre-loaded demographics will not be shown in the survey but can be drawn directly from existing participant data, and then used when viewing the survey results.
\n","urlObject":{"path":["api","","integration","survey","{{survey-ref}}","demographics","data-dictionary"],"host":[""],"query":[],"variable":[]}},"response":[{"id":"3e4b3b9a-5a85-4726-badf-d22cfbd81e70","name":"Demographics data-dictionary sample","originalRequest":{"method":"GET","header":[{"key":"ApiKey","value":"insert-your-survey-apikey-here","type":"text"}],"url":"/api//integration/survey/{{survey-ref}}/demographics/data-dictionary"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"availableDemographics\": [\r\n {\r\n \"reference\": \"307824\",\r\n \"label\": \"Did this individual leave the organisation voluntarily?\",\r\n \"demographicOptions\": [\r\n {\r\n \"label\": \"Yes\",\r\n \"type\": \"BY-DEMOGRAPHIC-QUESTION\",\r\n \"reference\": \"307824\",\r\n \"value\": \"1\"\r\n },\r\n {\r\n \"label\": \"No\",\r\n \"type\": \"BY-DEMOGRAPHIC-QUESTION\",\r\n \"reference\": \"307824\",\r\n \"value\": \"2\"\r\n },\r\n {\r\n \"label\": \"Not Selected\",\r\n \"type\": \"BY-DEMOGRAPHIC-QUESTION\",\r\n \"reference\": \"307824\",\r\n \"value\": \"-1\"\r\n }\r\n ]\r\n },\r\n {\r\n \"reference\": \"307848\",\r\n \"label\": \"Department:\",\r\n \"demographicOptions\": [\r\n {\r\n \"label\": \"Department A\",\r\n \"type\": \"BY-DEMOGRAPHIC-QUESTION\",\r\n \"reference\": \"307848\",\r\n \"value\": \"1\"\r\n },\r\n {\r\n \"label\": \"Department B\",\r\n \"type\": \"BY-DEMOGRAPHIC-QUESTION\",\r\n \"reference\": \"307848\",\r\n \"value\": \"2\"\r\n },\r\n {\r\n \"label\": \"Department C\",\r\n \"type\": \"BY-DEMOGRAPHIC-QUESTION\",\r\n \"reference\": \"307848\",\r\n \"value\": \"3\"\r\n },\r\n {\r\n \"label\": \"Department D\",\r\n \"type\": \"BY-DEMOGRAPHIC-QUESTION\",\r\n \"reference\": \"307848\",\r\n \"value\": \"4\"\r\n },\r\n {\r\n \"label\": \"Not Selected\",\r\n \"type\": \"BY-DEMOGRAPHIC-QUESTION\",\r\n \"reference\": \"307848\",\r\n \"value\": \"0\"\r\n }\r\n ]\r\n },\r\n {\r\n \"reference\": \"307850\",\r\n \"label\": \"Role:\",\r\n \"demographicOptions\": [\r\n {\r\n \"label\": \"Staff\",\r\n \"type\": \"BY-DEMOGRAPHIC-QUESTION\",\r\n \"reference\": \"307850\",\r\n \"value\": \"1\"\r\n },\r\n {\r\n \"label\": \"Supervisor / Team Leader\",\r\n \"type\": \"BY-DEMOGRAPHIC-QUESTION\",\r\n \"reference\": \"307850\",\r\n \"value\": \"2\"\r\n },\r\n {\r\n \"label\": \"Senior Manager\",\r\n \"type\": \"BY-DEMOGRAPHIC-QUESTION\",\r\n \"reference\": \"307850\",\r\n \"value\": \"3\"\r\n },\r\n {\r\n \"label\": \"Executive\",\r\n \"type\": \"BY-DEMOGRAPHIC-QUESTION\",\r\n \"reference\": \"307850\",\r\n \"value\": \"4\"\r\n },\r\n {\r\n \"label\": \"Not Selected\",\r\n \"type\": \"BY-DEMOGRAPHIC-QUESTION\",\r\n \"reference\": \"307850\",\r\n \"value\": \"0\"\r\n }\r\n ]\r\n }\r\n ]\r\n}"}],"_postman_id":"5367b4ed-22e5-4c20-8096-39a33245f80a"},{"name":"Participant List","id":"aae348f9-a9f6-4c9c-bb60-143ddf1dec0b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":"{{access_token}}"},"isInherited":false},"method":"GET","header":[],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"/api//integration/survey/{{survey-ref}}/participant","description":"Retrieve the list of participants for a survey.
\n","urlObject":{"path":["api","","integration","survey","{{survey-ref}}","participant"],"host":[""],"query":[],"variable":[]}},"response":[{"id":"b7113c3b-64ce-45ce-aee7-2f7c4b5ba588","name":"Participant list sample","originalRequest":{"method":"GET","header":[{"key":"ApiKey","value":"insert-your-survey-apikey-here","type":"text"}],"url":"/api//integration/survey/{{survey-ref}}/participant"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"[\r\n {\r\n \"surveyParticipantId\": 100001,\r\n \"emailAddress\": \"jane.smith@acme-corporation.com.au\",\r\n \"firstName\": \"Jane\",\r\n \"lastName\": \"Smith\",\r\n \"mobilePhone\": \"0411111111\",\r\n \"altEmailAddress\": jane.smith@personal-email.com.au,\r\n \"invitationStatus\": \"Sent\",\r\n \"isComplete\": false,\r\n \"dateCreated\": \"2021-03-30T22:48:24.41\",\r\n \"dateModified\": \"2021-04-12T22:01:15.92\",\r\n \"dateInvited\": \"2021-04-12T22:01:15.92\"\r\n }\r\n]"}],"_postman_id":"aae348f9-a9f6-4c9c-bb60-143ddf1dec0b"},{"name":"Participant Invite","event":[{"listen":"test","script":{"id":"4bdd314a-49f0-4a61-bae2-1b2b9da54b3e","exec":["try\r","{\r"," pm.globals.set(\"survey-participant-id\", pm.response.json().data);\r"," console.log(pm.globals.get(\"survey-participant-id\"));\r","}\r","catch(ex)\r","{\r"," console.log(ex);\r","}"],"type":"text/javascript","packages":{}}}],"id":"874a161e-293e-416a-be86-297627bd587a","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":"{{access_token}}"},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"details\": {\r\n \"lastName\": \"Jane\",\r\n \"firstName\": \"Smith\",\r\n \"emailAddress\": \"jane3.smith@acme-corporation.com.au\",\r\n \"altEmailAddress\": \"jane3.smith@personal-email.com.au\",\r\n \"mobilePhone\": \"04111111111\",\r\n \"referenceDateType\": \"relative\",\r\n \"referenceDate\": \"2023-09-04T20:05:00\",\r\n \"demographics\": [\r\n {\r\n \"demographicType\": \"BY-DEMOGRAPHIC-QUESTION\",\r\n \"demographicReference\": 440435,\r\n \"demographicValue\": 3\r\n },\r\n {\r\n \"demographicType\": \"BY-DEMOGRAPHIC-QUESTION\",\r\n \"demographicReference\": 440435,\r\n \"demographicValue\": 2\r\n },\r\n {\r\n \"demographicType\": \"BY-DEMOGRAPHIC-QUESTION\",\r\n \"demographicReference\": 440435,\r\n \"demographicValue\": 4\r\n }\r\n ]\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"/api//integration/survey/{{survey-ref}}/participant/action/invite","description":"The participant is invited to complete the survey.\nThe participant will receive notifications according to the notification schedule and the reference date. The reference date is used to identify when the participant should be invited. For example in an onboarding survey the participant schedule would be relative to the date the participant is starting and would be after the start date so that the participant had time to become familiar with the organisation. For an exit survey the date would be when the participant is leaving, and ideally would be before they leave.\nThere is also an option to invite the participant immediately.
\nemailAddress (required)\nThe email address is a required field and must be a valid email format
\naltEmailAddress (optional)\nThe alternate email address is not a required field but if it is provided it must be a valid email format
\nfirstName and lastName (optional)\nThe first and last names are not required fields.
\nmobilePhone (optional)\nThe mobile phone number is not a required field
\nreferenceDateType (optional)\nOptions are:
\nreferenceDate\nIf a relative reference date type is used then the relative date can be provided. If it's not provided or is not correctly formated then the current date is used.
\n","urlObject":{"path":["api","","integration","survey","{{survey-ref}}","participant","action","invite"],"host":[""],"query":[],"variable":[]}},"response":[{"id":"2c532634-7255-4ff3-b121-8bde9126bf66","name":"Participant invite sample","originalRequest":{"method":"POST","header":[{"key":"ApiKey","value":"insert-your-survey-apikey-here","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"details\": {\r\n \"lastName\": \"Jane\",\r\n \"firstName\": \"Smith\",\r\n \"emailAddress\": \"jane.smith@acme-corporation.com.au\",\r\n \"altEmailAddress\": \"jane.smith@personal-email.com.au\",\r\n \"mobilePhone\": \"04111111111\",\r\n \"referenceDateType\": \"relative\",\r\n \"referenceDate\": \"2021-07-22T20:05:00\",\r\n \"demographics\": [\r\n {\r\n \"demographicType\": \"BY-DEMOGRAPHIC-QUESTION\",\r\n \"demographicReference\": 307824,\r\n \"demographicValue\": 1\r\n },\r\n {\r\n \"demographicType\": \"BY-DEMOGRAPHIC-QUESTION\",\r\n \"demographicReference\": 307848,\r\n \"demographicValue\": 2\r\n },\r\n {\r\n \"demographicType\": \"BY-DEMOGRAPHIC-QUESTION\",\r\n \"demographicReference\": 307850,\r\n \"demographicValue\": 1\r\n }\r\n ]\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"/api//integration/survey/{{survey-ref}}/participant/action/invite"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"success\": true,\r\n \"message\": \"The participant has been added\",\r\n \"data\": 100001,\r\n \"dataType\": \"Participant Id\"\r\n}"}],"_postman_id":"874a161e-293e-416a-be86-297627bd587a"},{"name":"Notification Types","event":[{"listen":"test","script":{"id":"d03bee78-9245-4c41-91ab-23c715ce6351","exec":[""],"type":"text/javascript","packages":{}}}],"id":"7b61421d-ae3a-423f-972b-2e89f8956999","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":"{{access_token}}"},"isInherited":false},"method":"GET","header":[],"body":{"mode":"raw","raw":"","options":{"raw":{"language":"json"}}},"url":"/api//integration/survey/{{survey-ref}}/participant/notification/type","description":"If notifications are setup for a survey then the types of notifications can be retrieved and used in the send endpoint.
\n","urlObject":{"path":["api","","integration","survey","{{survey-ref}}","participant","notification","type"],"host":[""],"query":[],"variable":[]}},"response":[{"id":"542f2b14-2b69-4ab7-9fa6-a0fae64b2d99","name":"Notification types sample","originalRequest":{"method":"GET","header":[{"key":"ApiKey","value":"insert-your-survey-apikey-here","type":"text"}],"url":"/api//integration/survey/{{survey-ref}}/participant/notification/type"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"[\r\n \"participant-initial\",\r\n \"participant-ongoing\",\r\n \"participant-final\"\r\n]"}],"_postman_id":"7b61421d-ae3a-423f-972b-2e89f8956999"},{"name":"Send Notification","event":[{"listen":"test","script":{"id":"61abe51a-453e-4eb0-aa0e-c5ff0b5d6198","exec":[""],"type":"text/javascript","packages":{}}}],"id":"c9112e92-3b2a-4818-b9c0-9974e7cc284b","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"token":"{{access_token}}"},"isInherited":false},"method":"POST","header":[],"body":{"mode":"raw","raw":"{\r\n \"details\": {\r\n \"notificationType\": \"participant-ongoing\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"/api//integration/survey/{{survey-ref}}/participant/{{survey-participant-id}}/notification/action/send","description":"The API can be used to trigger immediate notifications. There are a number of notification types that can be sent. See ../participant/notification/type for the list of notification types
\n","urlObject":{"path":["api","","integration","survey","{{survey-ref}}","participant","{{survey-participant-id}}","notification","action","send"],"host":[""],"query":[],"variable":[]}},"response":[{"id":"c8e50927-77b6-4495-a221-4a4d07877c2c","name":"Notification send sample","originalRequest":{"method":"POST","header":[{"key":"ApiKey","value":"insert-your-survey-apikey-here","type":"text"}],"body":{"mode":"raw","raw":"{\r\n \"details\": {\r\n \"notificationType\": \"participant-ongoing\"\r\n }\r\n}","options":{"raw":{"language":"json"}}},"url":"/api//integration/survey/{{survey-ref}}/participant/{{survey-participant-id}}/notification/action/send"},"status":"OK","code":200,"_postman_previewlanguage":"Text","header":[],"cookie":[],"responseTime":null,"body":"{\r\n \"success\": true,\r\n \"message\": \"Message sent\",\r\n \"data\": null,\r\n \"dataType\": \"\"\r\n}"}],"_postman_id":"c9112e92-3b2a-4818-b9c0-9974e7cc284b"}],"event":[{"listen":"prerequest","script":{"id":"e30734cb-c304-457d-bd75-e5c48361e19b","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"548e123d-dd40-47df-95f0-603131265fbf","type":"text/javascript","exec":[""]}}],"variable":[{"key":"base-url","value":"","type":"string"},{"key":"version","value":"","type":"string"}]}