Integrations
Use studies, ad-hoc questions and results from other tools via REST or MCP.
An integration lets another tool access your team, for example an AI assistant that speaks MCP or your own script using REST. There are two ways in: an API Key, which you create in the settings, and a connected app, where you connect Claude or ChatGPT to your team by signing in. Both act as the member who created or connected them. Anything that costs money or ends a running survey is always confirmed by that member in the browser.
What an integration can do
An integration sees what its member sees: the member's projects and those shared with them. It can
- list projects, studies, survey designs, files, panels and ad-hoc questions
- check a survey run's status, read its report and the individual responses
- create and update survey designs
- upload images and PDFs to a design's project
- request a survey start, an ad-hoc question or a cancellation, a start also with a goal
The integration can't start, ask or cancel by itself. It receives a confirmation link that its member opens.
Which project it lands in
What an integration creates lies in one of its member's projects. The integration names the project in its call. If it names none, the app creates a new project named after the design, study or question, and the answer names that project so the integration continues there. A study from a design lies in the design's project. You find everything on the project page, like the results of your chats.
| API Key | Connected app | |
|---|---|---|
| Acts as | the member who created it | you, the connecting member |
| Confirm and upload | only that member | only you |
| Upload files | upload page or directly via an upload address | upload page only |
Designs a connected app created or changed appear in the design picker with the note via Claude · your name.
Switch on integrations
Only owners switch on integrations, and they need a paid plan.
- In the account menu, open Settings > Integrations.
- Switch on Integrations. Without a paid plan, it says Paid subscription only next to it.
When you switch them off, the app asks Switch off Integrations?: open confirmation and upload links become invalid for good, even if you switch integrations on again. Members see the switch, the endpoints and their own API Keys and connected apps on this page.

Create an API Key
Every member can create API Keys once integrations are switched on.
- Under API Keys, click Create key.
- Enter a Name that says where the key is used, such as
Claude DesktoporReporting script, and click Create. - The New API Key dialog shows the key. Copy the key now. It is shown only once. Click Copy, then Done.
From then on the table shows Name, Created and Last used, but never the key itself. If you need it again, create a new one. Owners see every member's keys with the Member column, but not their projects.
Treat the key like a password: whoever has it reads and makes requests as you. If a key may have leaked or is no longer needed, click Revoke and confirm. It stops working immediately and the row shows Revoked on …. Open links created with that key become invalid. You revoke your own keys, owners any key of the team.
A key only works while its member is in the team. If the member leaves or is removed, their keys are revoked.
Connect a tool with the key
Endpoints lists the addresses of your access, each with a copy button. Members see only the MCP address:
| Endpoint | Used for |
|---|---|
| MCP | AI assistants and other tools that support the Model Context Protocol |
| REST | your own scripts and automations |
| OpenAPI | the description of all REST endpoints, for developers or code generators |
The tool sends the key in the Authorization: Bearer <key> header. In an MCP-capable tool, add the MCP address as a server and store the key as that header. Your tool's documentation explains how. Claude and ChatGPT need no key: you connect them as a connected app.
Connected apps
You connect Claude and ChatGPT without a key: enter the MCP address, sign in to theconsumer.ai and choose a team. Any member can do this once an owner has switched integrations on. The team needs a paid plan for it.
Connect Claude
- Under Settings > Integrations, copy the MCP address.
- In Claude, open Customize > Connectors and click Add custom connector. Enter the MCP address and click Add. In a Team or Enterprise organization, an owner adds the connector under Organization settings > Connectors; you then click Connect on it.
- Claude opens the page Connect Claude to theconsumer.ai. Sign in if needed. If you have a second factor set up, confirm it too.
- Under Team, choose the team Claude should work in for you and click Connect. Cancel connects nothing. You then return to Claude.

Teams where integrations are off or the plan is missing are greyed out and say why, for example Integrations are off. Ask an owner to switch them on. A connection is for exactly one team. For a second team, connect the app again.
Connect ChatGPT
In ChatGPT, add your own MCP server (Add custom MCP server), enter the MCP address and choose sign-in via OAuth. ChatGPT's documentation has the exact steps. The connection page and the team choice are the same as for Claude; ChatGPT shows up there as Codex.
See and disconnect connections
Under Settings > Integrations > Connected apps you see your connections with App, Connected and Last used. Owners see every member's connections, with a Member column.

Disconnect ends a connection at once: the app loses access to this team, the row shows Disconnected on …, and open confirmation and upload links of that connection become invalid. Surveys you already confirmed keep running. Owners disconnect any connection, members their own. A connection also ends when you leave the team or are removed from it, and by itself after 90 days. While integrations are off or the plan has ended, no connected app gets through until both are back. To reconnect, start the connection again in Claude or ChatGPT.
A connected app doesn't reload the list of tools by itself. When tools change (see API changes), reconnect Claude or ChatGPT so the app knows the new names.
The confirmation page
When an integration requests a start, an ad-hoc question or a cancellation, it gives you a link. Open it in the browser and sign in if needed. Only the member the integration acts for can confirm: for an API Key the one who created it, for a connected app the one who connected it.
The heading names the action: Start survey, Ask question or Cancel survey. Below it you see where the request came from, with the date: Requested via API Key “…” with the key's name, or Requested via Claude · name with the app and the member, then the details:
- Study, Audience with the number of respondents, Questions with their stimuli, Price and Available
- for ad-hoc questions, the question itself and, if set, the Follow-up
- for a cancellation, the consequences: answers so far stay readable, there is no report, only respondents who answered fully are charged.
Confirm with Start, Ask question or Cancel survey, or decline with Discard without anything being charged. A link is valid for 7 days; the page shows the end as Link valid until ….


Whoever confirms counts as the starter: the price counts towards your credit limit and the survey's notifications go to you. The study lies in the project the integration prepared it in; whoever sees that project sees it too. If something changed since the request, the page shows a note such as Something changed. Review it and confirm again.
If another member opens the link, they see no details but Only name can start this survey (for questions … ask this question, for cancellations … cancel this survey) and who they are signed in as. Switch account signs you out and returns to the link after sign-in.

| Result | Meaning |
|---|---|
| Survey started / Question asked | Done. View study opens the study. |
| Discarded | Declined; no credits were charged. |
| Link expired | The 7 days are over. Have the integration request it again. |
| Link invalid | The key was revoked, the connection was disconnected or expired, the member left the team, Integrations were switched off, or the subscription ended. The reason is shown below. |
| Not started | The start didn't go through and no credits were charged. The reason is shown below. |
Ad-hoc questions via an integration
An integration can ask a whole panel one open question, without images. Once you confirm with Ask question, the question lies in the project the integration named, under Ad-hoc questions, like a question from your chat. When it's answered, the confirmation page says Results ready and the integration can fetch the answers. There is no notification for it. How ad-hoc questions work is explained in Ad-hoc questions & recontact.
Files via the upload page
If a design needs images or PDFs, the integration can request an upload link. The Upload files page names where the link came from, as on the confirmation page, the Design and how much room is left, for example 17 of 20 left. Only the integration's member can use the link; other members see Only name can upload here and Switch account.
- Drag the files into the field or choose them: JPG, PNG, WebP up to 10 MB · PDF up to 12 MB.
- Click Done. The page says Files are in the project.
The integration then assigns the files to the design as stimuli. An upload link is also valid for 7 days.
Upload files directly
An API Key can also send files directly via an upload address, without the upload page; a connected app can't. This brings images (JPG, PNG, WebP) and PDFs up to 50 MB into the design's project, a PDF up to 150 pages. The file is then in that project and can be a stimulus of a design. The tighter limits for stimuli (images up to 10 MB, PDFs up to 12 MB and 20 pages, per question up to 12 MB and 60 PDF pages together) are only checked when the integration assigns the file to a design as a stimulus.
The app then reads an uploaded PDF. The integration sees how far it has got when it fetches the file, see below.
Give a goal
An integration can also give the study a goal: the business decision the study supports, in one sentence. With the click on Start, the new study takes it as its goal, and the survey keeps it as it stands then. The confirmation page doesn't show the goal, because it is about scope and cost.
For developers: REST and MCP
REST and MCP offer the same tools under the same names. The full description of every tool is in the OpenAPI description under Endpoints. For projects and files:
| Tool (MCP) | REST | What it does |
|---|---|---|
list_projects | GET /projects | Lists the member's projects: own and shared. Their id goes as projectId to the tools that create. |
start_file_upload | POST /file-uploads | Starts an upload: returns a signed address for the bytes. API Key only. |
finish_file_upload | POST /file-uploads/{uploadId}/finish | Finishes an upload: returns the file. |
list_files | GET /files | Lists the files of the projects the member can see: images and PDFs |
get_file | GET /files/{fileId} | One file with a download address |
request_survey_start | POST /requests/survey-start | Requests a survey start, optionally with studyGoal |
Processing of a PDF. get_file and list_files return the field processing, null for images. For PDFs:
| Field | Values |
|---|---|
state | processing (being read), processed (read), partial (single pages missing), failed (can't be read) |
pageCount | number of pages |
failureReason | only with failed: too_many_pages, unreadable, content_mismatch or no_pages_extracted |
missingPages | only with partial: the missing pages |
indexState | whether the PDF is searchable: pending, indexed or failed; null while state is processing or failed |
After an upload, the integration polls get_file until state is no longer processing.
Goal at launch. studyGoal is text of at most 500 characters; spaces at the start and end are dropped, and a blank goal counts as none. Longer is invalid_request. The goal is part of the request's identity: without a requestKey, a different goal is a different request, and a requestKey with a different goal is invalid_request.
Upload limits. start_file_upload and finish_file_upload check the limits for files: images and PDFs up to 50 MB (maxBytes is 52428800), a PDF up to 150 pages. Above that, start_file_upload (by the stated size) and finish_file_upload (by the uploaded file) answer with invalid_request. The limits for stimuli are only checked by update_survey_design. The upload page (request_image_upload_link) still checks the limits for stimuli.
API changes
November 2026
- Breaking change: An API Key acts as the member who created it, no longer as the team. It sees what that member sees, and only that member confirms what it requests. If the member leaves the team, the key is revoked.
- New tool
list_projects(GET /projects). The tools that create take an optionalprojectId; without one the app creates a new project and names it in the answer. - Breaking change:
request_survey_startno longer takesstudyContextFileIds. What every analysis reads now sits in the project's instructions. - Breaking change: The file tools are now
list_files,get_file,start_file_uploadandfinish_file_upload(before:list_materials,get_material,start_material_uploadandfinish_material_upload). The REST paths move from/materialsto/filesand from/material-uploadsto/file-uploads.materialIdis nowfileId,studyContextMaterialIdsis nowstudyContextFileIds, the error codematerial_unreadableis nowfile_unreadable; the results are calledfilesandfile. The old names and paths are gone. - Reconnect Claude or ChatGPT so the app knows the new tools.
October 2026
- Breaking change:
start_image_uploadis nowstart_material_upload,finish_image_uploadis nowfinish_material_upload. The REST paths move from/image-uploadsto/material-uploads. The old names and paths are gone. - An upload checks the limits for files (50 MB, PDF up to 150 pages) instead of the limits for stimuli. The limits for stimuli are only checked when the file is assigned to a design.
request_survey_startoptionally acceptsstudyContextMaterialIds. New error codematerial_unreadable; an error about one file names it in thematerialIdfield.list_materialslists images and PDFs,get_materialalso returns PDFs. Both have the new fieldprocessing.request_survey_startoptionally acceptsstudyGoal, the goal of the new study (at most 500 characters). It is part of the request's identity.