NAV
http

Overview

The GetFeedback Reporting API is simple, modern, RESTful, and JSON-based. All API access is over HTTPS to the api.getfeedback.com domain. Appropriate HTTP verbs are used to manipulate resources.

Authentication

Authorization: Bearer mF_9.B5f-4.1JqM

API bearer tokens should be sent in an HTTP Authorization header. Follow the RFC 6750 spec section 2.1.

Representation

All dates or timestamps are returned and expected as ISO 8601 strings.

The Accept HTTP header must always be sent to signify the correct resource representation. At this time only application/json is supported.

Responses

Get All Responses

GET /surveys/:survey_id/responses HTTP/1.1
Authorization: Bearer YOUR_GETFEEDBACK_ACCESS_TOKEN
Content-Type: application/json

{
  "active_models": [
    {
      "id": 525,
      "token": "cTmIyeFWNwqTJcZbEpHYmA",
      "status": "completed",
      "created_at": "2014-03-17T17:22:10.055-07:00",
      "updated_at": "2014-03-17T17:22:36.041-07:00",
      "merge_map": {
        "xid": "xxxxxxxxxxxxxxxxxx"
      },
      "answers": [
        {
          "id": 509,
          "type": "MultipleChoiceAnswer",
          "component_id": 73,
          "created_at": "2014-03-17T17:22:35.906-07:00",
          "choices": [
            {
              "id": 52,
              "text": "Yes",
              "is_other": false
            }
          ]
        },
        {
          "id": 507,
          "type": "RatingAnswer",
          "component_id": 92,
          "created_at": "2014-03-17T17:22:34.097-07:00",
          "number": 4,
          "scale": 5
        }
      ],
    },
    { },
    ...
  ]
}

HTTP Request

GET /surveys/:survey_id/responses

Query Parameters

Parameter Description
since Timestamp from which to return responses. If set with an ISO 8601 datestamp, responses are returned in ascending timestamp ordered by the since_field (see below). If not set or an incorrect format is passed, returns responses in descending timestamp order by created_at.
since_field If using since, date on responses to compare to. Can be created_at, updated_at, or completed_at. When set to completed_at, status is filtered to only completed responses. Defaults to created_at.
until If using since, timestamp to which to return responses. If set with an ISO 8601 datestamp, it will be the endcap date to the since param.
status Can be set to started or completed and then only responses in that state will be returned. If not set, returns all responses.
per_page Responses to return per page. Defaults to 30. Maximum 100.
page Page number when paging through responses. Note there is no server cursor state.

Definitions

merge_map: Parameters that were appended to the URL when the taker opened the survey.

component_id: Identifier for the survey question the answer represents.

Get a Specific Response

GET /surveys/:survey_id/responses/:id HTTP/1.1
Authorization: Bearer YOUR_GETFEEDBACK_ACCESS_TOKEN
Content-Type: application/json

The above command returns JSON structured like this:

{
  "response": {
    "id": 101413,
    "token": "du7x49xk6A29BpVmU2fwm4",
    "status": "completed",
    "created_at": "2020-04-14T13:12:44.394-07:00",
    "updated_at": "2020-04-14T13:12:44.394-07:00",
    "completed_at": "2020-04-14T13:12:44.394-07:00",
    "limited": false,
    "merge_map": {},
    "platform": null,
    "browser": null,
    "country_code_with_emoji": null,
    "answers": [
      {
        "id": 102025,
        "type": "NetPromoter",
        "component_id": 9,
        "text": null,
        "created_at": "2020-04-14T13:12:44.439-07:00",
        "updated_at": "2020-04-14T13:12:44.439-07:00",
        "response_id": 101413,
        "comment": "",
        "embedded": false,
        "number": 9,
        "grid_item": null
      },
      {
        "id": 102026,
        "type": "CustomerSatisfaction",
        "component_id": 10,
        "text": null,
        "created_at": "2020-04-14T13:12:44.501-07:00",
        "updated_at": "2020-04-14T13:12:44.501-07:00",
        "response_id": 101413,
        "comment": "",
        "embedded": false,
        "number": 3,
        "grid_item": null
      },
      {
        "id": 102027,
        "type": "CustomerEffort",
        "component_id": 11,
        "text": null,
        "created_at": "2020-04-14T13:12:44.533-07:00",
        "updated_at": "2020-04-14T13:12:44.533-07:00",
        "response_id": 101413,
        "comment": "",
        "embedded": false,
        "number": 6,
        "grid_item": null
      }
    ]
  }
}

HTTP Request

GET /responses/:id

GET /surveys/:survey_id/responses/:id

URL Parameters

Parameter Description
id The id of the response to retrieve
survey_id The id of the parent survey of the response to retrieve

Surveys

Get all surveys

GET /surveys HTTP/1.1
Authorization: token YOUR_GETFEEDBACK_ACCESS_TOKEN
Content-Type: application/json

The above command returns JSON structured like this:

{
  "surveys": [
    {
      "id": 1,
      "name": "Customer Feedback",
      "questions_count": 1,
      "background_image_brightness": 0,
      "merge_keys": [],
      "embedded_answer_key_errors": [],
      "language": "en",
      "locale": "en-US",
      "folder_id": null,
      "use_rich_text": null,
      "multilanguage": false,
      "enabled_languages": [],
      "financial_data_paths": [],
      "financial_data_field": null,
      "store_ipdata": null,
      "only_defined_merge_keys": null,
      "discard_invalid_values": null,
      "public_host_settings": {
          "host": "",
          "protocol": "http"
      },
      "font_override": null,
      "background_display_override": null,
      "background_type_override": null,
      "background_color_override": null,
      "question_color_override": null,
      "answer_color_override": null,
      "button_color_override": null,
      "user_id": 1,
      "created_at": "2020-08-31T11:58:03.668-07:00",
      "updated_at": "2020-08-31T11:58:03.668-07:00",
      "started_responses_count": 0,
      "completed_responses_count": 0,
      "limited_responses_count": 0,
      "notification_level": "all",
      "show_incomplete_responses": null,
      "send_incomplete_responses": null,
      "walkthrough": 0,
      "shares": {
          "shares": []
      },
      "survey_shares": {
          "survey_shares": []
      },
      "publish_to_id": null,
      "draft_id": null,
      "theme": {
          "id": 1,
          "name": "Default",
          "category": "colors",
          "background_image_brightness": 0,
          "font": "Open Sans",
          "background_display": "fill",
          "background_type": "color",
          "background_color": 16777215,
          "question_color": 3355443,
          "answer_color": 3355443,
          "button_color": 10066329,
          "background_image": null
      },
      "logo_media_object": null,
      "background_image_override": null
    }
  ]
}

HTTP Request

GET /surveys

URL Parameters

Parameter Description
filter When shared, returns user's shared surveys, otherwise returns user's active surveys

Get a specific survey

GET /surveys/:survey_id HTTP/1.1
Authorization: token YOUR_GETFEEDBACK_ACCESS_TOKEN
Content-Type: application/json

The above command returns JSON structured like this:

{
  "survey": {
    "id": 1,
    "name": "Customer Feedback",
    "questions_count": 1,
    "background_image_brightness": 0,
    "merge_keys": [],
    "embedded_answer_key_errors": [],
    "language": "en",
    "locale": "en-US",
    "folder_id": null,
    "use_rich_text": null,
    "multilanguage": false,
    "enabled_languages": [],
    "financial_data_paths": [],
    "financial_data_field": null,
    "store_ipdata": null,
    "only_defined_merge_keys": null,
    "discard_invalid_values": null,
    "public_host_settings": {
      "host": "",
      "protocol": "http"
    },
    "font_override": null,
    "background_display_override": null,
    "background_type_override": null,
    "background_color_override": null,
    "question_color_override": null,
    "answer_color_override": null,
    "button_color_override": null,
    "user_id": 1,
    "created_at": "2020-08-31T11:58:03.668-07:00",
    "updated_at": "2020-08-31T11:58:03.668-07:00",
    "started_responses_count": 0,
    "completed_responses_count": 0,
    "limited_responses_count": 0,
    "notification_level": "all",
    "show_incomplete_responses": null,
    "send_incomplete_responses": null,
    "walkthrough": 0,
    "shares": {
      "shares": []
    },
    "survey_shares": {
      "survey_shares": []
    },
    "publish_to_id": null,
    "draft_id": null,
    "share_token": "samplesharetoken",
    "whitelabeled": null,
    "automagic_salesforce_sync": null,
    "merge_field_encryption": null,
    "draft_salesforce_credential_id": null,
    "draft_pardot_credential_id": null,
    "draft_differs": false,
    "last_published": null,
    "publishing": null,
    "response_graph_token": "sampletoken",
    "server_held_change_count": 0,
    "theme": {
      "id": 1,
      "name": "Default",
      "category": "colors",
      "background_image_brightness": 0,
      "font": "Open Sans",
      "background_display": "fill",
      "background_type": "color",
      "background_color": 16777215,
      "question_color": 3355443,
      "answer_color": 3355443,
      "button_color": 10066329,
      "background_image": null
    },
    "logo_media_object": null,
    "user": {
      "id": 1,
      "email": "email@example.com",
      "name": "Example Name",
      "status": "active",
      "source": "organic",
      "permissions": 5,
      "time_zone": null,
      "team_id": 1,
      "has_invalid_card": false,
      "card_expiration_date": null,
      "is_team_owner": true,
      "default_tab": "surveys"
    },
    "background_image_override": null,
    "custom_domain": null,
    "salesforce_credential": null,
    "pardot_credential": null,
    "ordered_components": [
      {
        "id": 1,
        "survey_id": 1,
        "type": "CoverPage",
        "markup": null,
        "title": "Hey There.",
        "required": true,
        "randomize": false,
        "show_media": false,
        "is_question": false,
        "description": "Thanks for using GetFeedback. We're eager to hear anything that's on your mind.",
        "show_description": true,
        "has_grid_items": false,
        "stats": {},
        "choices_stats": [],
        "answers_count": 0,
        "mappable_field_types": [],
        "randomize_grid_items": false,
        "lhs_condition_ids": [],
        "target_action_ids": [],
        "comment_enabled": false,
        "comment_header": "",
        "commentable": false,
        "alignment": null,
        "show_top_media": true,
        "should_hide_merge_fields": false,
        "can_hide_merge_fields": false,
        "is_embedded_auto": false,
        "embedded_answer_key": "gf_q[1]",
        "is_embedded_answerable": false,
        "is_email_embeddable": false,
        "button_text": "Let's Get Started",
        "choices": [],
        "grid_items": [],
        "media_object": null,
        "top_media_object": null,
        "ordered_rules": [],
        "translations": []
      },
      {
        "id": 2,
        "survey_id": 1,
        "type": "ShortAnswer",
        "markup": null,
        "title": "What would you like to tell us?",
        "required": true,
        "randomize": false,
        "show_media": true,
        "is_question": true,
        "description": null,
        "show_description": true,
        "has_grid_items": false,
        "stats": {},
        "choices_stats": [],
        "answers_count": 0,
        "mappable_field_types": [
          "string",
          "textarea"
        ],
        "randomize_grid_items": false,
        "lhs_condition_ids": [],
        "target_action_ids": [],
        "comment_enabled": false,
        "comment_header": "",
        "commentable": false,
        "alignment": null,
        "show_top_media": false,
        "should_hide_merge_fields": false,
        "can_hide_merge_fields": false,
        "is_embedded_auto": true,
        "embedded_answer_key": "gf_q[2]",
        "is_embedded_answerable": false,
        "is_email_embeddable": false,
        "multiline": true,
        "choices": [],
        "grid_items": [],
        "media_object": null,
        "top_media_object": null,
        "ordered_rules": [],
        "translations": []
      },
      {
        "id": 3,
        "survey_id": 1,
        "type": "ThankYouPage",
        "markup": null,
        "title": "Thanks! We appreciate it.",
        "required": true,
        "randomize": false,
        "show_media": true,
        "is_question": false,
        "description": "We've just been notified and will follow up shortly.",
        "show_description": true,
        "has_grid_items": false,
        "stats": {},
        "choices_stats": [],
        "answers_count": 0,
        "mappable_field_types": [],
        "randomize_grid_items": false,
        "lhs_condition_ids": [],
        "target_action_ids": [],
        "comment_enabled": false,
        "comment_header": "",
        "commentable": false,
        "alignment": null,
        "show_top_media": false,
        "should_hide_merge_fields": false,
        "can_hide_merge_fields": false,
        "is_embedded_auto": false,
        "embedded_answer_key": "gf_q[3]",
        "is_embedded_answerable": false,
        "is_email_embeddable": false,
        "button_text": "Done",
        "button_url": null,
        "choices": [],
        "grid_items": [],
        "media_object": null,
        "top_media_object": null,
        "ordered_rules": [],
        "translations": []
      }
    ],
    "campaigns": [
      {
        "id": 2,
        "survey_id": 1,
        "type": "WebLink",
        "token": "feedback",
        "ended_at": null,
        "expiry_period": null,
        "custom_urls": [],
        "logo_media_object": null
      },
      {
        "id": 1,
        "survey_id": 1,
        "type": "WebLink",
        "token": "ZD3EgRWm",
        "ended_at": null,
        "expiry_period": null,
        "custom_urls": [],
        "logo_media_object": null
      }
    ],
    "pardot_object_mappings": [],
    "salesforce_mapping_failure_strategy": {
      "id": 1,
      "email_notifications_enabled": false,
      "email_summaries_enabled": false,
      "email_summaries_sent_count": 0,
      "email_summary_scheduled_for": null
    },
    "rules": [],
    "defined_merge_keys": []
  }
}

HTTP Request

GET /surveys/:survey_id

Send to a list from Getfeedback

POST /surveys/:survey_id/send_invites HTTP/1.1
Authorization: token YOUR_GETFEEDBACK_ACCESS_TOKEN
Content-Type: application/json
Body:

  {
    "subject": "[name] - Take this survey",
    "title": "Hi [first_name],",
    "from_email_name": "john",
    "from_email_domain": "v6fl23ps.getfeedback-cx.com",
    "body": "Here's your test survey from API request. Your user ID is [user_id].",
    "button_color": "#40c326",
    "logo_image_url": "https://logos-world.net/wp-content/uploads/2021/07/Momentive-Emblem.png",
    "embedded_component_id": 11186336,
    "footer": "Click the link below to unsubscribe.",
    "subscriber_list": [
      {
        "name": "Steve Jones",
        "email": "test@surveymonkey.com",
        "first_name": "Steve",
        "last_name": "Jones",
        "user_id": 12345,
      }
    ]
  }

The above command returns JSON structured like this:

{
  "total_recipients": 10,
  "subject": "[name] - Take this survey",
  "title": "Hi [first_name],"
}

This endpoint sends out invites in bulk

HTTP Request

POST /surveys/:survey_id/send_invites

URL Parameters

Parameter Description
anonymize When true, turns off click and open tracking and hides survey responses from recipient records
from_email_name Sender's name
from_email_domain Sender's email domain
subject Email invite subject
title Email invite title
body Email invite body
button_label Email invite button label
subscriber_list An array of objects that include these keys: email, first_name and last_name
gf_test When true, import subscribers without emailing them
embedded_component_id Question ID used for the call-to-action
button_color Hex color value for call-to-action button
logo_image_url URL of the logo
reply_to Email address visible to recipients when they reply to the sender
footer Email footer

Custom Variables

Custom variables in the subject, title, and body can be replaced with the data from fields for each subscriber.

For example:

The custom variable [user_id] in the body can be replaced with the data from the user_id field:

{ "body": "Your user ID is [user_id],", "subscriber_list": [ { "user_id": 12345 }, ... ] }

Errors

Standard HTTP error codes are used to signal success and errors:

Code Meaning
200 Request was successful and a representation is included in the body.
204 No Content: Request was successful. No body is returned.
400 Bad Request: There was an issue parsing your request. Check the JSON.
422 Unprocessable Entity: The request made an invalid state change or didn’t pass application-level validation. Check the errors returned in the body.
http