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; if you want AI agents rather than your own code driving Dataddo, see 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). 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 and Dashboarding 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:

The rule of thumb from Authorizing OAuth 2.0 Services: 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.

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 as flows created in the UI.

Setup Walkthrough: The Embedded Integration Lifecycle

The 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 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 shows the backend and frontend halves with code; Authorizing OAuth 2.0 Services 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, and Fixed-Schema Connectors vs. Custom-Schema Connectors for the two connector families.
4. Create the destination. Provision the warehouse, database, or file storage target via API (Data Storages via API), or expose the data to a dashboarding app directly (Dashboarding Apps via API).
5. Create the flow. Attach the source(s) to the destination; the End-to-End Example shows the request and response.
6. Monitor and backfill. Load historical data for new tenants with 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.
• Postman Collection: explore the endpoints interactively before writing code. See Postman Collection.
• Live reference: the full endpoint documentation lives at 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.

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.
• Token lifecycle: access tokens expire (expires_in, typically 3600 seconds); refresh them with POST /refresh rather than re-sending credentials. See Authorization.
• Backfilling per tenant: onboarding a customer usually means loading their history; see 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.

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.
• 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.
• For pipeline-level issues (broken sources, failed flows), see Troubleshooting.