Account Level API

Account Level API Documentation

Overview

The Account Level API provides programmatic access to your Polling.com account data, enabling you to retrieve comprehensive information about your surveys, respondents, and session data. This RESTful API is designed for post-collection analytics and integrations, allowing you to extract survey results and respondent information after responses have been collected.

Key Capabilities

• Retrieve detailed survey configurations and questions
• Access complete respondent profiles with demographic data
• Query session data for specific survey-respondent combinations
• List all respondents who have completed a given survey
• Export cross-survey respondent activity

API Availability

The Account Level API is available exclusively on the Standard Plan and above. To upgrade your plan or learn more about pricing, please visit your account settings.

Account Level API vs. Embeds Integration

Understanding the distinction between these two integration methods will help you choose the right approach for your use case:

Use the Account Level API when you need to: Extract completed survey data for reporting, analytics, or integration with your own systems.

Use Embeds when you need to: Display surveys within your application, control survey triggers, or capture real-time respondent interactions.

Base URL

https://api.polling.com

Authentication

All API requests require authentication using one of the following methods:

• Header: Include your API token in the token header
• Query Parameter: Include your token as a token parameter in the URL

To access your account data, you'll need to provide the API key linked to your account, which can be found on: Integrations > API Integration > API Key tab

Endpoints

Get Survey Details

Retrieve details about a specific survey, including its configuration, settings, and questions.

Endpoint:

GET /api/account/surveys/{uuid}

Parameters:

• uuid (path parameter, required): The unique identifier (UUID) of the survey

Response:

{
  "id": 123, // Internal ID
  "uuid": "550e8400-e29b-41d4-a716-446655440000", // Unique identifier of the survey
  "name": "Customer Satisfaction Survey",
  "status": "active",
  "json": {...}, // Raw survey JSON from survey builder, including questions and pages
  "description": "Survey description text",
  "settings": {
    "stop_criteria": "forever", // Defines if the survey should be stopped at a given date, responses limit or never 
    "stop_value": null,
    "reward_amount": null, // Given reward details
    "reward_name": null,
    "complete_json": {...}, // Custom JSON added on the survey settings
    "complete_html": "<p>Thank you!</p>", // HTML that appears when the survey is completed
    "start_trigger": "now", // Defines the survey start trigger, start right away or on a given date
    "start_at": null, 
    "is_anonymous": false, // Anonymous survey or not
    "redirect_url": "https://example.com/thanks", // URL to be redirected after successful completion
    "redirect_type": "none", // Defines if the completion redirect URL is enabled or not
    "user_hash_method": "cookie", // Device or IP based
    "redirect_url_disqualified": "https://example.com/disqualified" //  URL to be redirected after being disqualified
  },
  "questions": [ // Questions of the survey
    {
      "id": 1, // Internal ID
      "identifier": "qIknp2l5Kh", // Question identifier, used as field names on the survey
      "type": "rating", // Question type
      "question": "How satisfied are you with our service?", // Question title
      "json": {...} // Raw question JSON
    },
        ...
  ],
  "created_at": "2024-01-01T00:00:00Z", // When the survey was created
  "updated_at": "2024-01-15T12:00:00Z" // Last udpated at time
}

Get Sessions by Respondent

Retrieve all sessions for a specific respondent within a given survey.

Endpoint:

GET /api/account/surveys/{uuid}/sessions-by-respondent/{respondent_id}

Parameters:

• uuid (path parameter, required): The unique identifier (UUID) of the survey
• respondent_id (path parameter, required): The external_id or customer_id of the respondent

Response:

[
  {
    "id": 456, // Internal session ID
    "is_completed": true, // User finsihed the survey (by reaching the last question or being disqualified)
    "is_disqualified": false, // If the user was disqualified
    "started_at": "2024-01-20T14:30:00Z", // Session start timestamp
    "completed_at": "2024-01-20T14:45:00Z", // Session end timestamp
    "answers": [ // List of the answers of the session
      {
        "id": 789, // internal answer ID
        "question_identifier": "qIknp2l5Kh", // Question identifier
        "question": "How satisfied are you with our service?", // Question title
        "answer": "Very satisfied" // user answer
      },
        ...
    ]
  },
    ... // Can have multiple sessions if the survey allows
]

Get Respondent Details

Retrieve complete details about a respondent, including demographic information and all their survey sessions.

Endpoint:

GET /api/account/respondents/{respondent_id}

Parameters:

• respondent_id (path parameter, required): The external_id or customer_id of the respondent

Response:

{
  "id": 101,
  "external_id": "user_12345", // External ID provided on your Embed integration as customer_id
  "country": "US",
  "region": "California",
  "city": "San Francisco",
  "language": "en",
  "is_anonymous": false, // Defines if the data is anonymized or not
  "is_mobile": true, // if the survey was taken on a mobile device
  "lat": 37.7749,
  "lon": -122.4194,
  "last_access_at": "2024-01-20T14:45:00Z", // Last time the respondent interacted with any of Polling.com's embeds or SDKs
  "sessions": [ // list of sessions
    {
      "id": 456,
      "survey_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "is_completed": true, // User finsihed the survey (by reaching the last question or being disqualified)
      "is_disqualified": false, // If the user was disqualified
      "started_at": "2024-01-20T14:30:00Z", // Session start timestamp
      "completed_at": "2024-01-20T14:45:00Z", // Session end timestamp
      "answers": [ // List of the answers of the session
        {
          "id": 789, // internal answer ID
          "question_identifier": "qIknp2l5Kh", // Question identifier
          "question": "How satisfied are you with our service?", // Question title
          "answer": "Very satisfied" // user answer
        },
        ...
      ]
    }
  ],
  "created_at": "2024-01-10T08:00:00Z"
}

Note: Sessions include a survey_uuid field to identify which survey each session belongs to.

List Survey Respondents

Retrieve a list of all respondent identifiers who have completed a specific survey. Only respondents who have finished or been disqualified are included.

Endpoint:

GET /api/account/surveys/{uuid}/respondents/list

Parameters:

• uuid (path parameter, required): The unique identifier (UUID) of the survey

Response:

[
  "external_id1",
  "external_idRespondet2",
  "user_12345",
  "customer_67890"
]

Note: Only respondents who have completed the survey (either finished or disqualified) are returned. Respondents who started but did not complete the survey are not included in this list.

Status Codes

• 200 OK: Request successful
• 401 Unauthorized: Invalid or missing authentication token
• 403 Forbidden: Authentication token valid, but your account plan doesn't have access to the API feature (only Standard and above)
• 404 Not Found: Resource not found
• 500 Internal Server Error: Server error