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

# REST APIs and custom integrations

> Bring in data from a provider endpoint or a source that needs custom logic.

Choose **Rest Api** for an HTTP API that can be described through request and response settings. Choose **Custom** when a source needs additional code or a specialised extraction workflow.

## Authentication and data flow

For a REST import, Dawn uses the saved credential in the configured request. Token-based requests use the provider's token or key; a configured OAuth flow obtains an access token before requesting data. Confirm the authentication requirements against the provider's documentation.

```mermaid theme={null}
flowchart TD
    A["Saved provider credential"] -.->|"Authenticate request"| B["Dawn import"]
    B -->|"Configured request"| C["Provider endpoint"]
    C -->|"Response data"| B
    B -->|"Fetch configured pages"| C
    B -->|"Extract records and save"| D["Dawn dataset"]
```

The provider receives the request values you configure. If you use values from a Dawn dataset to build requests, those selected values are sent to the provider too. Review the destination and request contents before running the import.

For a Custom integration, the extraction code determines authentication, outbound requests, and how returned data is processed. Review that code and its required credentials; the REST diagram is not a guarantee of a custom workflow's behaviour. Refreshing either type requires another run, and revoking source access does not delete existing imported data.

## Gather the provider details

Before creating a connection, find the provider's API documentation and identify:

* The base URL and endpoint that returns the required data.
* The authentication method and required permissions.
* Request parameters, filters, and any body fields.
* The location of records inside the response.
* Pagination, rate limits, and token expiry behaviour.

Use a credential limited to the intended endpoints where the provider supports that. Do not put tokens into ordinary connection headers or descriptions; use the credential mechanism and have the integration reference it.

## REST API setup

1. Open **Connections → New connection → Rest Api**.
2. Enter the Base URL and any non-sensitive Default header JSON, such as `{"Accept":"application/json"}`.
3. Create or select the appropriate credential and save the connection.
4. Configure the import's URL, method, body, response data field, and pagination as required by the provider.
5. Review a small request before running the full import.

Some APIs use POST for searches. Others use POST to create or change records. Check the endpoint documentation instead of treating the HTTP method as proof of read-only behaviour.

```text theme={null}
Use this API connection and the provider's documentation to prepare an import
of orders. Explain authentication, pagination, and rate limits. Start with one
small page. Do not call endpoints that create or modify source records.
```

## Custom setup

Choose **Custom** and record the Provider, Connector kind, Base URL, and Docs URL where relevant. Add the credential separately. Provide Dawn with the extraction requirements and ask it to prepare a pipeline you can inspect.

Review the requested endpoints, dependency on credentials, transformations, and destination before running generated code. A saved Custom connection is a starting point for an integration; it does not guarantee a provider-specific extractor already exists.

## Validate completeness

A successful HTTP response can still contain an error object or only the first page. Check record counts, pagination completion, date coverage, and how empty results are represented. Compare a known record with the source.

Before recurring runs, decide how retries, rate limits, and duplicate records should be handled. Keep the provider's version and response format in mind when a previously working import starts failing.

## Revoke access

Disable the connection to stop new use through it, review dependent schedules, and revoke the token or app grant at the provider. Previously imported datasets need separate cleanup.