Survey Submissions Setup

Retrieve survey submission data with full response details and contact associations through the GHL MCP server. This quick-start covers authentication, fetching submissions by survey ID, and parsing the response payload.

Prerequisites

Before pulling survey submissions, confirm you have:

• A GoHighLevel sub-account with at least one survey that has received submissions
• Access to Settings > Integrations > Private Integrations in the sub-account
• A REST client such as Postman, Insomnia, or curl in your terminal
• Your sub-account’s locationId (found under Settings > Business Profile)
• The surveyId of the survey whose submissions you want to retrieve (get this from Survey Manager)

Set Up Authentication

Survey Submissions endpoints require a Private Integration Token (PIT) with the surveys scope.

Navigate to Settings > Integrations > Private Integrations in your sub-account. Click Create New Integration and name it “Survey Submissions Reader.” Under Scopes, enable the surveys scope. This grants access to both survey configurations and their submission data.

Click Save and copy the generated token. Store it securely. Include Authorization: Bearer {your-pit-token} in every request along with Version: 2021-07-28.

Set your base URL to https://services.leadconnectorhq.com. All endpoints below are relative to that base.

Make Your First Call

Fetch submissions for a specific survey using GET with the survey ID:

GET /surveys/{surveyId}/submissions?locationId={your-location-id}
Authorization: Bearer {your-pit-token}
Version: 2021-07-28

Replace {surveyId} with the actual survey ID obtained from the GET /surveys endpoint. The response contains an array of submissions, each with the respondent’s answers and the associated contactId.

For paginated results, use the page and limit query parameters. The default limit varies, so always check the response metadata for total count and current page position. Process large datasets by iterating through pages until you have retrieved all records.

Handle the Response

A successful call returns a 200 status with a submissions array:

{
  "submissions": [
    {
      "id": "sub_abc123",
      "contactId": "contact_xyz",
      "surveyId": "srv_abc123",
      "createdAt": "2026-02-20T14:30:00Z",
      "others": {
        "field_1": "Very satisfied",
        "field_2": "Great support team"
      }
    }
  ]
}

Each submission includes a contactId linking the response to a contact record. The others object contains the actual field responses keyed by field identifiers. Cross-reference these keys with the field definitions from Survey Manager to map them to human-readable labels.

Common error codes: 401 means your token is invalid or the surveys scope is missing. 404 means the surveyId does not exist or belongs to a different location. 400 indicates a missing or invalid locationId.

Test Your Setup

Validate your integration with these checks:

1. Fetch submissions with GET /surveys/{surveyId}/submissions and confirm a 200 response
2. Verify submission count against the submissions visible in the GHL dashboard for that survey
3. Check a contactId by looking up the contact via GET /contacts/{contactId} to confirm the association
4. Inspect field responses and verify the values match what was submitted through the survey form
5. Test pagination by setting limit=1 and iterating through pages to confirm all records are accessible

If submissions return empty but the dashboard shows data, confirm your surveyId is correct and that the PIT has the surveys scope on the same sub-account.

Next Steps

Read the full Survey Submissions Guide for advanced patterns including response aggregation and export workflows. From here, explore Survey Manager for retrieving field definitions, and Contact Tags for segmenting contacts based on their survey responses.