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 KeyConnected app
Acts asthe member who created ityou, the connecting member
Confirm and uploadonly that memberonly you
Upload filesupload page or directly via an upload addressupload 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.

  1. In the account menu, open Settings > Integrations.
  2. 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.

Integrations page with the switch on, the API Keys table with a key named Claude Desktop and the MCP, REST and OpenAPI endpoints
Integrations with one API Key

Create an API Key

Every member can create API Keys once integrations are switched on.

  1. Under API Keys, click Create key.
  2. Enter a Name that says where the key is used, such as Claude Desktop or Reporting script, and click Create.
  3. 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:

EndpointUsed for
MCPAI assistants and other tools that support the Model Context Protocol
RESTyour own scripts and automations
OpenAPIthe 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

  1. Under Settings > Integrations, copy the MCP address.
  2. 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.
  3. Claude opens the page Connect Claude to theconsumer.ai. Sign in if needed. If you have a second factor set up, confirm it too.
  4. Under Team, choose the team Claude should work in for you and click Connect. Cancel connects nothing. You then return to Claude.
Page Connect Claude to theconsumer.ai with the team choice, in which one team can be chosen and a second is greyed out with the note that integrations are off, plus the buttons Connect and Cancel
The connection page with the team choice

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.

Connected apps section with one row Claude, the member, the connection date, the last use and the Disconnect button
Connected apps as an owner sees them

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 ….

Confirmation page headed Start survey, with the line naming the API Key that made the request, the rows Study, Audience, Questions and Price, and the buttons Start and Discard
An API Key requests a survey start
Confirmation page headed Start survey, with the line Requested via Claude and the member's name, the rows Study, Audience, Questions and Price, and the buttons Start and Discard
A connected app requests a survey start

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.

Confirmation page headed Only Alex Becker can start this survey, the note that you are signed in as another member and the survey was prepared through Alex Becker's connection to Claude, and the button Switch account
Another member opens the link
ResultMeaning
Survey started / Question askedDone. View study opens the study.
DiscardedDeclined; no credits were charged.
Link expiredThe 7 days are over. Have the integration request it again.
Link invalidThe 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 startedThe 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.

  1. Drag the files into the field or choose them: JPG, PNG, WebP up to 10 MB · PDF up to 12 MB.
  2. 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)RESTWhat it does
list_projectsGET /projectsLists the member's projects: own and shared. Their id goes as projectId to the tools that create.
start_file_uploadPOST /file-uploadsStarts an upload: returns a signed address for the bytes. API Key only.
finish_file_uploadPOST /file-uploads/{uploadId}/finishFinishes an upload: returns the file.
list_filesGET /filesLists the files of the projects the member can see: images and PDFs
get_fileGET /files/{fileId}One file with a download address
request_survey_startPOST /requests/survey-startRequests a survey start, optionally with studyGoal

Processing of a PDF. get_file and list_files return the field processing, null for images. For PDFs:

FieldValues
stateprocessing (being read), processed (read), partial (single pages missing), failed (can't be read)
pageCountnumber of pages
failureReasononly with failed: too_many_pages, unreadable, content_mismatch or no_pages_extracted
missingPagesonly with partial: the missing pages
indexStatewhether 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 optional projectId; without one the app creates a new project and names it in the answer.
  • Breaking change: request_survey_start no longer takes studyContextFileIds. What every analysis reads now sits in the project's instructions.
  • Breaking change: The file tools are now list_files, get_file, start_file_upload and finish_file_upload (before: list_materials, get_material, start_material_upload and finish_material_upload). The REST paths move from /materials to /files and from /material-uploads to /file-uploads. materialId is now fileId, studyContextMaterialIds is now studyContextFileIds, the error code material_unreadable is now file_unreadable; the results are called files and file. The old names and paths are gone.
  • Reconnect Claude or ChatGPT so the app knows the new tools.

October 2026

  • Breaking change: start_image_upload is now start_material_upload, finish_image_upload is now finish_material_upload. The REST paths move from /image-uploads to /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_start optionally accepts studyContextMaterialIds. New error code material_unreadable; an error about one file names it in the materialId field.
  • list_materials lists images and PDFs, get_material also returns PDFs. Both have the new field processing.
  • request_survey_start optionally accepts studyGoal, the goal of the new study (at most 500 characters). It is part of the request's identity.