> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bindbee.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up an Integration

> Follow the recommended order for a Bindbee integration.

This is the path a successful Bindbee setup follows. Three steps are optional; the rest apply to every integration.

<Info>
  **Before you start**

  * You have a Bindbee account and an API key for the environment you're building against.
  * You know which models your use case needs.
</Info>

## Steps

<Steps>
  <Step title="Set up scoping for your use case">
    Turn on only the models and fields you actually need. Scoping decides what syncs, so it is easier to get right now than to change later.

    **Result:** The connector requests your models and nothing else. See [Scoping](/get-started/scoping).
  </Step>

  <Step title="Create the connector">
    Pick one path - a Magic Link you send to the customer, or the Embedded SDK inside your own product.

    **Result:** The customer authorizes, and the connector moves to `COMPLETE`. See [Connection methods](/get-started/connection-methods).
  </Step>

  <Step title="Subscribe to connector_sync_started (Optional)">
    Fires the moment a sync begins, which is what you need to show "importing your data…" in your UI.

    **Result:** Your endpoint receives an event at the start of every run. See [Webhooks](/guides/reading-writing/webhooks).
  </Step>

  <Step title="Poll the Connectors API (Optional)">
    Reads `status` and `sync_status` for a connector when you need to check where a connection stands.

    ```bash theme={null}
    curl --request GET \
      --url 'https://api.bindbee.dev/api/hris/v1/connectors' \
      --header 'Authorization: Bearer <BINDBEE_API_KEY>'
    ```

    **Result:** The current state of every connection. See [Get Connectors](/api-reference/connectors/get-connectors).
  </Step>

  <Step title="Fetch attached custom fields (Optional)">
    Where you have mapped custom fields, read the mappings so you know what extra data arrives with each record.

    **Result:** The list of extensions on each model. See [Custom fields via API](/guides/extending/custom-fields/api-workflow).
  </Step>

  <Step title="Subscribe to connector_synced (Recommended)">
    This is the signal that a sync has finished and the data is ready to read. Verify the signature on every request and reply within 10 seconds.

    **Result:** You learn the moment a connector's data is complete, rather than polling for it. See [Webhooks](/guides/reading-writing/webhooks).
  </Step>

  <Step title="Read once the webhook arrives">
    Pull the models you scoped, paging until `cursor` is `null`.

    **Result:** The full census for that customer.

    <Warning>
      The limit is 200 requests per minute per connector, counted against the connector
      token. Set your own concurrency below that - see [Rate limits](/api-reference/basics/rate-limits).
    </Warning>
  </Step>
</Steps>

## After the first sync

The first full read gives you the complete census. From then on you only need the delta, and there are two ways to get it:

* Subscribe to `connector_data_modified` and read the record IDs it hands you.
* Pass [`modified_after`](/guides/reading-writing/reading-data/modified-after) with the highest `modified_at` you saw on the previous run.

Either way, **upsert on `id`** - you will receive the same record more than once.

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Nothing arrives after the customer authorizes">
    The first sync runs on connection, and a large population takes time. Check the run in [Sync status](/guides/troubleshooting/sync-status) before assuming the webhook failed.
  </Accordion>

  <Accordion title="You want to start reading without waiting for the webhook">
    You can, but the data is incomplete until the run finishes. Gate on `connector_synced` rather than a timer - see [Syncing](/guides/reading-writing/syncing).
  </Accordion>

  <Accordion title="A model you scoped returns nothing">
    Read its per-model status on the run. `Skipped` and `Not Supported` both return an empty set with no error - see [Sync status](/guides/troubleshooting/sync-status).
  </Accordion>
</AccordionGroup>

## Related

* [Go-Live checklist](/guides/go-live-checklist) - what to verify once this workflow is built
* [Scoping](/get-started/scoping) - the decision that shapes every later step
* [Webhooks](/guides/reading-writing/webhooks) - the event catalog behind steps 3 and 6
* [Troubleshooting](/guides/troubleshooting/overview) - the order to debug a connector in, once you are live