Survey API

Create, update and delete surveys on Workplace via Graph API, and receive participant answers via webhooks.

Survey Creation

POST /community/surveys

Creates a new survey with the specified configuration.

Fields

Fields passed in the request body as an object:

Endpoint Response

    {
      "id":"{id_of_survey}"
    }

Example Request

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
  }

Question Object Format

The questions field on the survey creation endpoint takes an array of objects with the following fields:

Scheduling Configuration Object

The scheduling_config field on the survey creation endpoint takes an object with the following fields:

Fetching Survey Configuration Information

Get Survey By ID

GET /{survey_id}

Retrieves the configuration of the survey by its id survey_id

Endpoint Response

An object containing the following fields (later referred to as Survey Object for brevity):

Sample Request

GET /{survey_id}?
  fields=title,scheduling_config.fields(start_timestamp,end_timestamp)

Get Surveys by Title

GET /community/surveys?name={survey_title}

Retrieves the configuration of the survey by its title

Request Parameters

• name: Title of a survey

Endpoint Response

In 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 title

Sample Request

GET /community/surveys?
  name=TSurvey4
  &fields=title,questions.fields(text)

Fetching All Existing Surveys

GET /community/surveys

Request Parameters

• No parameters

Response

Returns an array of objects:

• data: An array containing Survey Objects as described above

Sample Request

GET /community/surveys?fields=title,questions.fields(text,is_optional)

Getting Participation Answers By Participation ID

GET /{participation_id}

Retrieves the answers by provided participation id, as obtained from the participation completion webhook described below.

Request Parameters

• participation_id - path param - id of a participation

Endpoint Response

Returns 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)

Sample Request

GET /{participation_id}?fields=data.fields(name)

Updating a Survey

POST /{survey_id}

Update a survey using the specified configuration.

Request Parameters

• survey_id - int - required - id of the survey to update

Fields passed in the request body as a JSON object are the same as during survey creation.

Endpoint Response

• {"success":"true"}

Sample Request

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
}

Deleting a Survey

DELETE /{survey_id}

Delete the survey with the specified id.

Request Parameters

• survey_id - int - required - id of the survey to update

Endpoint Response

• {"success":"true"}

Sample Request

DELETE /{survey_id}

Survey Webhooks

Survey API supports sending updates via the surveys webhook topic. See Webhooks for more information on subscribing to Workplace webhooks.

Webhook for Survey Changes

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 happened

Webhook for Survey Participation Completion

When 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 survey
      • participation_id - string - id of participation
      • participation - 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.

Exporting Survey Data

Schedule a survey data export

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.

Request format

Fields passed in the request body as an object:

Request example

POST /community/export_survey_data

Response format

Sample Request

POST /community/export_survey_data?survey_id=12345679944

Response example

{ "task_id": "790625491793069" }