> ## Documentation Index
> Fetch the complete documentation index at: https://docs.repdata.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Supply API Overview
> Capabilities, core Survey and Stream concepts, and the end-to-end integration lifecycle for the Research Desk Supply API.
*This page provides an overview of Supply API capabilities, integration steps, and other helpful details for business stakeholders and developers.*
***
## 1. What is Research Desk?
**Reliable, Repeatable Data Collection**
Research Desk is Rep Data's industry-leading quantitative research sample platform. It empowers buyers to collect high-quality data at a fair price by bringing together respondent targeting, fraud prevention, fieldwork management, and reconciliation in one streamlined interface.
**Why integrate as a supplier?**
* Receive dedicated sample allocations programmatically, without manual coordination
* Read live qualifications and quotas so you only send respondents that fit open targets
* Automate entry-link generation and respondent redirects
* Automate reconciliation so low-quality records are processed quickly and accurately
***
## 2. What is the Supply API?
The Research Desk Supply API lets sample suppliers integrate directly with Research Desk for programmatic sample order placement and fulfillment. Your platform can retrieve the surveys and streams allocated to you, read their targeting criteria and quotas, generate respondent links, and receive reconciliations — all without working inside the Research Desk interface.
The API is a RESTful service, which means it follows widely adopted conventions that make it straightforward for any modern engineering team to work with. It uses standard HTTP methods and returns JSON-formatted data.
| Detail | Value |
| ------------------- | ------------------------------------------------------- |
| API Type | RESTful (JSON) |
| Production URL | `https://api.researchdesk.com` |
| Staging/Testing URL | `https://stage-api.researchdesk.com` |
| Authentication | API key (obfuscated GUID) in the `Authorization` header |
| HTTP Methods Used | GET, POST, PUT |
***
## 3. Core Concepts: Surveys & Streams
Surveys and Streams are two of the key objects represented in the Supply API.
| Object | What It Represents |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Survey | A series of questions designed to collect information from a specific set of respondents. A Survey has an LOI, an incidence rate, an expected number of completes, and often sub-quotas. |
| Stream | A unique sample plan for the respondents needed to fill a Survey's quotas. Each Stream has its own qualifications and quotas. |
A Survey has a **1:many** relationship with Streams; a Stream always has a **1:1** relationship with its Survey. Simple sample requirements may use a single Stream, while more complex requirements frequently use multiple Streams.
In the diagram below, a Survey called "Consumer Study" requires 400 completes overall. The sample buyer created two Streams to match the Survey's requirements: Stream 1 covers US "Gen Pop" sub-quotas (age, gender, ethnicity, household income) for 300 completes at a $2.00 CPI, and Stream 2 adds an "ethnic minority boost" for 100 completes at a $3.00 CPI.
When multiple Streams are associated with the same Survey, respondents sent for one Stream must be mutually exclusive from the other Stream(s). A respondent cannot participate in a Survey more than once — for example, a respondent who entered through Stream 1 cannot participate again through Stream 2.
***
## 4. High-Level Integration Flow
A typical Supply API integration follows this lifecycle. The [API Workflow](https://docs.repdata.com/supply/guides/02-api-workflow) guide walks through each step with example calls.
Request an API key from Rep Data's Supply team. The key is passed in the `Authorization` header of every request.
Go to: [Authentication & Access](https://docs.repdata.com/supply/guides/01-authentication)
Call the Surveys endpoint to retrieve the Surveys and Streams allocated to you, along with their status, country, language, LOI, IR, and CPI.
Go to: [List Surveys & Streams](https://docs.repdata.com/supply/endpoints/get-v2-surveys)
For each Stream, retrieve its qualifications (respondent eligibility criteria) and quotas (target cells and how many completes remain).
Go to: [Get Stream Qualifications](https://docs.repdata.com/supply/endpoints/get-v2-surveys-streams-StreamNumber-qualifications) · [Get Stream Quotas](https://docs.repdata.com/supply/endpoints/get-v2-surveys-streams-StreamNumber-quotas)
Generate live and test entry links for a Stream, supplying the redirect URLs respondents should return to for each disposition (complete, terminate, security, over-quota).
Go to: [Create Links](https://docs.repdata.com/supply/endpoints/post-v2-surveys-streams-StreamNumber-link)
Send respondents into the survey using the live link, passing their profiling data on the query string. Poll the Surveys and Quotas endpoints to track remaining completes and pause sample to cells that are full.
Go to: [Passing Respondent Data](https://docs.repdata.com/supply/guides/03-passing-respondent-data)
Receive reconciliations via webhook so low-quality records are processed automatically.
Go to: [Reconciliation Push](https://docs.repdata.com/supply/guides/06-reconciliation-push)
**Redirect Links — A Critical Integration Requirement**
When you create links, you must supply Research Desk with your redirect URLs for each disposition (complete, terminate, security/fraud, over-quota). Research Desk uses these to pass respondents back to your platform with the correct status code and respondent ID. Without them, outcomes cannot be returned to you.
***
## 5. Environments
Research Desk provides staging and production environments for integration work. See [Environments & Status Codes](/supply/overview/01-environments-and-status-codes) for base URLs and recommended staging test surveys. See [Respondent Status Codes](/supply/overview/04-respondent-status-codes) for the supplier-facing `isc` values returned on redirects.
***
## 6. Accessing the API
To obtain authentication credentials, first contact Rep Data's Supply team at [supply@repdata.com](mailto:supply@repdata.com) and request credentials. Suppliers that have not worked with Rep Data previously will also need to complete the new supplier onboarding process with Rep Data's Finance team.
**Support:** For integration questions or to get started, contact your Research Desk representative directly, or reach out to [supply@repdata.com](mailto:supply@repdata.com).
***
## 7. API Endpoint Overview
Below is a summary of the main endpoint groups available in the Supply API. Full documentation for each endpoint — including request/response schemas, parameters, and examples — is available in subsequent sections of this site.
| Endpoint Group | What It Does |
| ----------------- | --------------------------------------------------------------------------------- |
| Surveys & Streams | Retrieve allocated surveys and streams, and read stream qualifications and quotas |
| Links | Create and update respondent entry links and redirects |
| Lookups | Retrieve languages, countries, and the qualification library |
| Reconciliation | Register a webhook endpoint to receive reconciliation pushes |
***