Survey Manager Setup

List and retrieve survey configurations from your GoHighLevel sub-account through the GHL MCP server. This quick-start covers authentication, fetching survey definitions, and understanding the response structure for form fields and embeddable surveys.

Prerequisites

Before making your first Survey Manager call, confirm you have:

• A GoHighLevel sub-account with at least one survey created
• 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)
• A published survey you can reference when verifying the response

If you have not created a survey yet, go to Sites > Forms/Surveys in GHL and build one before proceeding.

Set Up Authentication

Survey Manager 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 API Access.” Under Scopes, enable the surveys scope. This grants read access to survey configurations, field definitions, and embed settings.

Click Save and copy the generated token. Store it securely. Include the Authorization: Bearer {your-pit-token} header 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

Retrieve all surveys in your sub-account with a GET request:

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

This returns every survey in the location. Each survey object includes its id, name, and field definitions. To retrieve a specific survey’s full configuration, use GET /surveys/{surveyId} with the ID from the list response.

The field definitions describe each question’s type (text, dropdown, radio, checkbox), label, placeholder text, and validation rules. Use this data to build custom front-ends or sync survey structures to external systems.

Handle the Response

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

{
  "surveys": [
    {
      "id": "srv_abc123",
      "name": "Customer Feedback",
      "locationId": "your-location-id"
    }
  ]
}

Each survey object contains the id you need for retrieving detailed configurations or fetching submissions. The field definitions within each survey describe the input types, labels, and options your users see.

Common error codes: 401 means your token is invalid or the surveys scope is not enabled. 400 indicates a missing locationId. 404 on a specific survey ID means the survey was deleted or belongs to a different location.

Test Your Setup

Validate your integration with these checks:

1. List all surveys with GET /surveys?locationId={id} and confirm you receive a 200 response
2. Count the results and compare with the survey count visible in Sites > Forms/Surveys
3. Fetch a specific survey using GET /surveys/{surveyId} and verify the field definitions match the builder
4. Check field types to confirm dropdowns, radio buttons, and text inputs map correctly
5. Test with an invalid survey ID to confirm you receive a 404, validating your error handling

If the list returns empty but you have surveys in the dashboard, double-check that your PIT belongs to the correct sub-account.

Next Steps

Read the full Survey Manager Guide for advanced patterns including custom form rendering and field mapping. From here, explore Survey Submissions to retrieve actual response data, and Contact CRUD to link survey respondents to contact records.