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

# API Workflow

> An end-to-end walkthrough from retrieving your allocations to creating links and reconciling completes.

The Supply API endpoints are designed to be used together as part of a business process. The steps below walk through a typical end-to-end workflow. For the example, assume a fictitious Survey `2634` is available to you, and that it contains a Stream `849`.

All calls require your API key in the `Authorization` header. The examples use the staging base URL `https://stage-api.researchdesk.com`; swap in `https://api.researchdesk.com` for production.

<Steps>
  <Step title="Retrieve your allocations">
    Call the Surveys endpoint to obtain the list of Surveys and Streams available to you. Assume you see Survey `2634` and, within it, Stream `849`.

    ```text theme={null}
    GET https://stage-api.researchdesk.com/v2/surveys
    ```

    See [List Surveys & Streams](https://docs.repdata.com/supply/endpoints/get-v2-surveys).
  </Step>

  <Step title="Identify the target Stream">
    For the remainder of this workflow, focus on Survey `2634` and the Stream `849` belonging to it. You can also fetch a single survey directly:

    ```text theme={null}
    GET https://stage-api.researchdesk.com/v2/surveys/2634
    ```

    See [Get Survey](https://docs.repdata.com/supply/endpoints/get-v2-surveys-SurveyNumber).
  </Step>

  <Step title="Get the Stream's qualifications">
    Retrieve the qualifications (respondent eligibility criteria) for Stream `849`.

    ```text theme={null}
    GET https://stage-api.researchdesk.com/v2/surveys/streams/849/qualifications
    ```

    See [Get Stream Qualifications](https://docs.repdata.com/supply/endpoints/get-v2-surveys-streams-StreamNumber-qualifications).
  </Step>

  <Step title="Get the Stream's quotas">
    Retrieve the quotas for Stream `849` so you know which cells are open and how many completes remain.

    ```text theme={null}
    GET https://stage-api.researchdesk.com/v2/surveys/streams/849/quotas
    ```

    See [Get Stream Quotas](https://docs.repdata.com/supply/endpoints/get-v2-surveys-streams-StreamNumber-quotas).
  </Step>

  <Step title="Create the entry links">
    Create the live and test entry links for Stream `849`, supplying your redirect URLs in the request body. Use `[%rid%]` (case sensitive) to pass back the Respondent ID that was originally passed into the entry link as `[%RID%]`.

    ```text theme={null}
    POST https://stage-api.researchdesk.com/v2/surveys/streams/849/link
    ```

    ```json theme={null}
    {
      "SurveyCompleteLink": "https://xyzsample.net/surveydone?status=C&respid=[%rid%]",
      "SurveyTermLink": "https://xyzsample.net/surveydone?status=T&respid=[%rid%]",
      "SecurityFraudTermLink": "https://xyzsample.net/surveydone?status=S&respid=[%rid%]",
      "SurveyOverquotaLink": "https://xyzsample.net/surveydone?status=OQ&respid=[%rid%]"
    }
    ```

    See [Create Links](https://docs.repdata.com/supply/endpoints/post-v2-surveys-streams-StreamNumber-link).
  </Step>

  <Step title="(Optional) Update the entry links">
    If you need a different survey link for any reason, use the Update Links endpoint to generate a new link for Stream `849`, passing the `lud` and `tud` values returned in the previous step.

    ```text theme={null}
    PUT https://stage-api.researchdesk.com/v2/surveys/streams/849/link?lud={LiveLinkUD}&tud={TestLinkUD}
    ```

    See [Update Links](https://docs.repdata.com/supply/endpoints/put-v2-surveys-streams-StreamNumber-link).
  </Step>
</Steps>

<Tip>
  **Polling:** During fieldwork, poll the Surveys and Quotas endpoints every 2–3 minutes to detect changes. Use the `Remaining` (Surveys) and `QuotaRemaining` (Quotas) fields as your primary indicators of whether more respondents are needed. When a value reaches `0`, pause sample to that Stream or quota cell.
</Tip>

Before sending respondents, review [Passing Respondent Data to Research Desk](https://docs.repdata.com/supply/guides/03-passing-respondent-data) for the profiling values that must be appended to entry links.