Shout API

The Shout API lets you read and manage your forms, responses, contacts and support inbox programmatically, subscribe to webhooks, and connect AI agents over MCP.

It is a versioned REST API. Every path is prefixed with /v1, responses are JSON, and the contract is stable — we won’t rename fields or change shapes under /v1.

Connecting an AI agent?

Shout is agent-ready out of the box: a first-class MCP server exposes your forms, responses, contacts and inbox to Claude, Cursor and any MCP client. Start with Connect an AI agent — step-by-step setup for each client — then try the agent recipes. No code required.

Beta — base URL

The production base URL will be https://publicapi.shout.com. It is not live yet. During the beta, use the base URL we give you when you’re onboarded, and substitute it wherever these docs show https://publicapi.shout.com. Everything else — paths, auth, payloads — is final.

Base URL

https://publicapi.shout.com

All endpoints live under /v1, e.g. https://publicapi.shout.com/v1/forms.

1. Create an API key

API keys are tenant-level — they belong to your organization, not to a personal login, so an integration keeps working after the person who created it leaves.

Only tenant admins can create keys:

1. Click your avatar in Shout, choose Developers, then open the API keys tab.
2. Click Create key, give it a name, and select the scopes it needs.
3. Copy the key. It is shown only once — store it somewhere safe (a secrets manager, not your source code). If you lose it, revoke it and create a new one.

Keys look like this:

sk_MFhTuyO2XVrpAp25dwzJd8vKHvOIGucLtJEenw

2. Make your first call

GET /v1/me confirms your key works and shows what it can do. It requires no scope.

export SHOUT_API_KEY="sk_your_key_here"

curl https://publicapi.shout.com/v1/me \
  -H "Authorization: Bearer $SHOUT_API_KEY"

{
  "keyId": "3f9a1c22-8b4e-4d17-9c02-11a2b3c4d5e6",
  "keyName": "Production integration",
  "tenantId": "0f6060e2-9842-fff3-f184-3a206ef96c98",
  "scopes": [
    "forms:read",
    "responses:read",
    "contacts:read"
  ]
}

You can pass the key as a Bearer token (above) or in the X-Api-Key header — both are equivalent. See Authentication & scopes.

3. List your forms

curl https://publicapi.shout.com/v1/forms?limit=5 \
  -H "Authorization: Bearer $SHOUT_API_KEY"

{
  "items": [
    {
      "id": "90751669-9ebc-4215-9321-538b6c9e29ac",
      "title": "Customer Feedback",
      "status": "active",
      "workspaceId": "34c78488-d53e-09bb-27b9-3a206f1f1ad7",
      "publishedAt": "2026-07-11T11:09:32Z",
      "updatedAt": "2026-07-11T00:00:00Z"
    }
  ],
  "nextCursor": "djE6OTIxOTA1"
}

That’s it — you’re calling the API. From here:

Where to go next

• Connect an AI agent — hook up Claude, Cursor or any MCP client in minutes.
• Agent recipes — proven prompts: build surveys, summarise responses, triage the inbox.
• Authentication & scopes — the two auth headers, the eight scopes, and key lifecycle.
• Pagination & errors — cursors, limits, and the error envelope.
• Forms — list, read, and create forms (all 19 question types).
• Responses — read submissions with filters.
• Contacts — CRM contacts, organisations, groups.
• Inbox & tickets — read and reply to support tickets.
• Webhooks — get pushed events instead of polling.
• MCP server — the tool reference behind the agent connections.
• API Reference — the complete, auto-generated endpoint reference (every path, parameter and schema), always in sync with the API.

Conventions used in these docs

• IDs are UUIDs unless noted (response IDs are opaque strings — see Responses). The IDs in these examples are illustrative placeholders.
• Timestamps are ISO 8601, UTC.
• Examples use $SHOUT_API_KEY for the key and https://publicapi.shout.com for the base URL.

Need help? Contact support.