---
title: "Embedded Ingestion via Headless API"
slug: "embedded-ingestion-via-headless-api"
updated: 2026-07-12T16:17:17Z
published: 2026-07-12T16:17:17Z
canonical: "docs.dataddo.com/embedded-ingestion-via-headless-api"
---

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

# Embedded Ingestion via Headless API

By the end of this article, you will have Dataddo's integration engine running invisibly inside your own product: your customers connect their accounts (Google, Facebook, Snapchat, and hundreds more) through **your UI**, and your backend provisions sources, flows, and destinations **programmatically** so the data lands wherever you or your customer choose. Choose this pattern when you are building a product on top of data integration rather than integrating your own data. If you just need pipelines for your own team, start with [Batch Ingestion to Data Warehouses](/docs/batch-ingestion-to-data-warehouses-etl-elt); if you want AI agents rather than your own code driving Dataddo, see [Data Delivery to AI & Agents](/docs/data-delivery-to-ai-agents).

## Architecture

Everything the Dataddo UI can do, the API can do: the Dataddo app itself is built on top of the same API (see [Endpoints](/headless/docs/endpoints)). An embedded integration has three layers:

1. **Your frontend** renders the connection experience. For OAuth services, it only needs to redirect the end user to an authorization URL that your backend obtains from Dataddo, then handle the callback.
2. **Your backend** authenticates to the Dataddo API with a JWT bearer token and performs full CRUD over **authorizers, sources, flows, and destinations** at `https://headless.dataddo.com/customer-api/v1`.
3. **Dataddo** runs the extraction, transformation, and delivery. Data lands in a destination you control (your product's warehouse) or one your customer controls; see [Data Storages via API](/headless/docs/data-storages-via-api) and [Dashboarding Apps via API](/headless/docs/dasboarding-apps-via-api).

Your end users never see Dataddo unless you choose the Dataddo-branded App Flow for authorization.

## Choosing an Authorization Model

The main design decision is how your end users authorize their accounts. Dataddo supports three [OAuth 2.0 flows](/headless/docs/creating-an-authorizer):

|  | App Flow | Authorization Code Flow | Refresh Token Flow |
| --- | --- | --- | --- |
| Users exposed to Dataddo branding | Yes | No | No |
| Need your own validated OAuth 2.0 app | No | Yes | Yes |
| Implementation difficulty | Simple | Medium | Advanced |
| You handle refresh tokens | No | No | Yes |

The rule of thumb from [Authorizing OAuth 2.0 Services](/headless/docs/creating-an-authorizer#which-oauth-20-flow-to-use): if you can already obtain refresh tokens from users in your existing app, use the **Refresh Token Flow**; otherwise use the **Authorization Code Flow** (white-label, your OAuth app) or the **App Flow** (fastest, Dataddo-branded consent). Services that do not use OAuth 2.0 are covered in [Non-OAuth 2.0 Services](/headless/docs/authorizing-non-oauth-20-service).

## Decision Guide

Where the data lands is a per-tenant write-strategy decision like any other Dataddo flow: **upsert** for destination tables that must stay deduplicated across repeated extractions, **insert** for append-only event-style data, **truncate insert** for full refreshes. Flows created via the API use the same write modes and [metadata features](/docs/metadata-inclusion) as flows created in the UI.

## Setup Walkthrough: The Embedded Integration Lifecycle

The [End-to-End Example](/headless/docs/end-to-end-example) walks the whole lifecycle with Snapchat as the worked example; the steps below map it to the articles that document each stage.

1. **Authenticate your backend to the Dataddo API.** Create a dedicated "system" team member (username and password, not SSO) and exchange its credentials for an access and refresh token pair via `POST /auth`. See [Authorization](/headless/docs/dataddo-api-authorization) for token refresh and revocation.
2. **Authorize the end user's service (create an authorizer).** From your backend, request an OAuth redirect URL, send the user there from your frontend, and handle the callback. [Implementing App Flow Authorization](/headless/docs/implementing-app-flow-authorization) shows the backend and frontend halves with code; [Authorizing OAuth 2.0 Services](/headless/docs/creating-an-authorizer) covers all three flows, including re-authorization. Redirect URIs pointing to your application must be whitelisted by Dataddo support.
3. **Create the source.** Call the connector's `create-source` endpoint with the authorizer ID from step 2 plus connector-specific parameters (accounts, metrics, date range, sync frequency). See the source-creation part of the [End-to-End Example](/headless/docs/end-to-end-example#creating-a-source), and [Fixed-Schema Connectors](/headless/docs/dataset-based-connectors-via-api) vs. [Custom-Schema Connectors](/headless/docs/flexible-schema-connectors-via-api) for the two connector families.
4. **Create the destination.** Provision the warehouse, database, or file storage target via API ([Data Storages via API](/headless/docs/data-storages-via-api)), or expose the data to a dashboarding app directly ([Dashboarding Apps via API](/headless/docs/dasboarding-apps-via-api)).
5. **Create the flow.** Attach the source(s) to the destination; the [End-to-End Example](/headless/docs/end-to-end-example#adding-a-source-to-the-flow) shows the request and response.
6. **Monitor and backfill.** Load historical data for new tenants with [Data Backfilling via Dataddo API](/headless/docs/data-backfilling-via-dataddo-api). Watch the rate limit headers on every response (see Operations below).

## Development Tooling

- **Sandbox Application**: a downloadable Vue.js/TypeScript skeleton implementing API authorization, source listing, data preview, and data quality checks. Use it as the starting point for your own embedded UI. See [Sandbox Application](/headless/docs/sandbox-application).
- **Postman Collection**: explore the endpoints interactively before writing code. See [Postman Collection](/headless/docs/postman).
- **Live reference**: the full endpoint documentation lives at [headless.dataddo.com](https://headless.dataddo.com), and because the Dataddo app runs on the same API, browser developer tools against the app show a live implementation (requests go to `public-api.dataddo.com` there; your integration must call `headless.dataddo.com`). See [Endpoints](/headless/docs/endpoints).

## Operations

- **Rate limits**: 10,000 API calls per day by default across all endpoints, including authorization. Track `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Retry-After` response headers in your backend. See [Headless API Overview](/headless/docs/headless-api-overview#rate-limits).
- **Token lifecycle**: access tokens expire (`expires_in`, typically 3600 seconds); refresh them with `POST /refresh` rather than re-sending credentials. See [Authorization](/headless/docs/dataddo-api-authorization).
- **Backfilling per tenant**: onboarding a customer usually means loading their history; see [Data Backfilling via Dataddo API](/headless/docs/data-backfilling-via-dataddo-api).
- **Re-authorization**: when a user's grant expires or scopes change, re-run the OAuth flow passing the existing `serviceId`, as described in [Authorizing OAuth 2.0 Services](/headless/docs/creating-an-authorizer#reauthorizing-the-user).

## Troubleshooting

- **OAuth callback returns an error**: Dataddo appends `error` and `errorDescription` parameters to your redirect URI; surface these to the user (commonly missing scopes or a denied consent). See [Authorizing OAuth 2.0 Services](/headless/docs/creating-an-authorizer#handling-the-callback).
- **Redirect URI rejected**: URIs for your application must be whitelisted; contact Dataddo support.
- **401 responses after a period of success**: the access token expired; implement the refresh flow from [Authorization](/headless/docs/dataddo-api-authorization#refreshing-access-token).
- For pipeline-level issues (broken sources, failed flows), see [Troubleshooting](/docs/troubleshooting).