Create, update and delete surveys on Workplace via Graph API, and receive participant answers via webhooks.
It is currently only possible to create surveys in draft mode via this API.
A Workplace admin with Manage Surveys permission is required to schedule them manually via the Surveys UI on Workplace.
POST /community/surveys
Creates a new survey with the specified configuration.
Fields passed in the request body as an object:
Field Name | Description | Data Type |
---|---|---|
| Required. Currently supports only one value: |
|
| Required. Survey title. |
|
| Optional (default: |
|
| Optional (default: standard message). Invitation message |
|
| Required. Objects describing questions | Array of |
| Required. Scheduling configuration | A |
{
"id":"{id_of_survey}"
}
POST /community/surveys?creation_mode=DRAFT
&title=TSurvey5
&questions=[{
"question_type": "FREE_TEXT"
"text": "Q1",
},{
"question_type": "FREE_TEXT"
"text": "Q2",
}]
&scheduling_config={
"start_timestamp": 1629222600,
"end_timestamp": 1629223600,
"frequency": "ONCE",
"response_window_days": 7,
"audience":1233455666
}
The questions
field on the survey creation endpoint takes an array of objects with the following fields:
Field Name | Description | Data Type |
---|---|---|
| Required. Question text. |
|
| Optional. Whether the question is optional or not. |
|
| Required. Question type. |
|
| Required where |
|
| Optional. Zero-based index of the question in this array this question depends on. Dependency question should precede this question in the questions array. Free text questions can’t act as a dependency for the other questions. |
|
| Required if |
|
The scheduling_config
field on the survey creation endpoint takes an object with the following fields:
Field Name | Description | Data Type |
---|---|---|
| Required. Timestamp denoting when to start the survey. |
Unix epoch: The number of seconds that have elapsed since January 1, 1970 |
| Required. Timestamp denoting when the survey delivery should end. |
Unix epoch: The number of seconds that have elapsed since January 1, 1970 |
| Required. Values other than |
|
| Required. The number of days the audience of the survey will have to respond. |
|
| Required. Identifier of the rule-based people set, members of which will be used as the survey audience. |
|
GET /{survey_id}
Retrieves the configuration of the survey by its id survey_id
An object containing the following fields (later referred to as Survey Object for brevity):
Field Name | Data Type | Description |
---|---|---|
|
| The ID of the survey |
|
| Survey title |
|
| Indicates whether this survey is a test survey. |
|
| The survey's invitation message |
| JSON | A |
| An object representing the schedule configuration |
GET /{survey_id}?
fields=title,scheduling_config.fields(start_timestamp,end_timestamp)
GET /community/surveys?name={survey_title}
Retrieves the configuration of the survey by its title
name
: Title of a surveyIn case there is a survey with exactly matching title, it returns an object with the following field:
data
: an array containing a Survey Object (described above) with the matching titleGET /community/surveys?
name=TSurvey4
&fields=title,questions.fields(text)
GET /community/surveys
Returns an array of objects:
data
: An array containing Survey Objects as described aboveGET /community/surveys?fields=title,questions.fields(text,is_optional)
GET /{participation_id}
Retrieves the answers by provided participation id, as obtained from the participation completion webhook described below.
participation_id
- path param - id of a participationReturns an object with the following field:
data
- an array containing objects with the following fields:
name
- string - name of the column, similar to how this row would appear in the survey export results (could be one of the following: "question text"; “Run” - for multi run surveys).value
- string - value of the column (could be one of the following: answer to the question; int for “Run” column which means survey run number)GET /{participation_id}?fields=data.fields(name)
POST /{survey_id}
Update a survey using the specified configuration.
It is currently only possible to update surveys whose creation_mode
is set to DRAFT
.
survey_id
- int - required - id of the survey to updateFields passed in the request body as a JSON object are the same as during survey creation.
{"success":"true"}
POST /{survey_id}?creation_mode=DRAFT&title=TSurvey5&questions=[
{
"text": "Q1",
"question_type": "FREE_TEXT"
},
{
"text": "Q2",
"question_type": "FREE_TEXT"
}
]&scheduling_config={
"start_timestamp": 1629222840,
"end_timestamp": 1629223600,
"frequency": "ONCE",
"response_window_days": 7,
"audience":1234555666
}
DELETE /{survey_id}
Delete the survey with the specified id.
It is currently only possible to delete surveys whose creation_mode
is set to DRAFT
.
survey_id
- int - required - id of the survey to update{"success":"true"}
DELETE /{survey_id}
Survey API supports sending updates via the surveys
webhook topic. See Webhooks for more information on subscribing to Workplace webhooks.
When a survey is created, updated or deleted, a webhook is sent containing an object with the following fields:
object
string = “workplace_community”entry
- array of objects with the following fields:
changes
- array of the objects with the following fields:
field
- string = “surveys”value
- object with the following fields:
survey
- Survey Object (described above) - if survey was deleted, it will only have “id” field.verb
- string (one of add
, update
, delete
) - denotes the action that happenedWhen a participant completes survey participation, it sends a request containing the object with the following fields:
object
string = “workplace_community”
entry
- array of objects with the following fields:
changes
- array of the objects with the following fields:
field
- string = “survey_participations”
value
- object with the following fields:
survey_id
- string - id of changed surveyparticipation_id
- string - id of participationparticipation
- object that contains the following fields:
data
- an array containing objects with the following fields:
name
- string - name of the column, similar to how this row would appear in the survey export results (could be one of the following: question text;“Run” - for multi run surveys;)value
- string - value of the column (could be one of the following: answer to the question; int for “Run” column which means survey run number. Note: the value is subject to regular survey results privacy policy: the first three participations’ answers will be hidden and will be sent without this field.POST /community/export_survey_data
Endpoint to schedule a job exporting surveys data to a CSV. Returns an ID that can be used to check the status and retrieve the results.
Fields passed in the request body as an object:
Field Name | Data Type | Description |
---|---|---|
|
| Required. The ID of the survey to export. |
POST /community/export_survey_data
Field Name | Data Type | Description |
---|---|---|
|
| Required. ID of the export job, that can be used to retrieve the results. |
POST /community/export_survey_data?survey_id=12345679944
{ "task_id": "790625491793069" }