---
title: "Sync Source to Workflow"
method: POST
path: "/api/v1/sources/{source_instance_id}/sync"
tags: ["Sources"]
---

# Sync Source to Workflow

`POST /api/v1/sources/{source_instance_id}/sync`

## Request

- Base URL: `http://localhost:3009`
- URL: `http://localhost:3009/api/v1/sources/{source_instance_id}/sync`
- Auth: HTTP bearer

Connect a created source to a workflow and (by default) backfill the workflow with the source's existing rows. `source_instance_id` is the UUID returned by Create.

`field_mapping` keys are public workflow input references (`input.<field>`); each value is the source field NAME to pull — the row's top-level key exactly as it appears in the Preview response (e.g. `Name`, `email`, `business_id`), NEVER a nested path like `Name.value`. The import resolves each field's value automatically, including for sources whose preview cells render as `{label, value}`. Each key is resolved to the matching workflow input. Keys are CASE-SENSITIVE — use the exact lowercase snake_case `reference` from List Inputs (minus the `{{ }}`); variants like `Input.Email` or `input.firstName` return 400. Surrounding `{{ }}` is tolerated.

`push_existing` (default true) toggles the backfill. Whether landed rows execute the workflow — backfilled and future rows alike — is the sheet's `auto_run` toggle: set it with Update Sheet (`PATCH /api/v1/workflows/{workflow_id}/sheets/{sheet_id}`) before syncing, and use Run Rows for explicit `row_ids`. The legacy `run` field is deprecated: it is accepted, ignored, and reported in `warnings[]`.

## Path parameters

- `source_instance_id` string, required

## Request body

- SyncSourceBody: Body for Sync Source to Workflow. Maps workflow inputs to source fields and (by default) backfills existing rows.
  - `workflow_id` string, uuid, required: UUID of the destination workflow.
  - `field_mapping` object, required: Map of workflow input reference → source field, e.g. `{ "input.email": "email", "input.first_name": "firstname" }`. Keys are `input.<field>` references from the workflow's inputs; values are source field names. Keys are CASE-SENSITIVE and must be the exact lowercase snake_case form returned by List Inputs (the input's `reference` without the `{{ }}` braces) — e.g. `input.first_name`, not `Input.First_Name` or `input.firstName`. Surrounding `{{ }}` is tolerated; case/spelling variants are not, and return 400 `unknown input`.
  - `push_existing` boolean: Whether to backfill the workflow with the source's current rows. Defaults to true.
  - `run` string: Deprecated and ignored (reported in `warnings[]`). Whether landed rows execute is the sheet's `auto_run` toggle — set it with Update Sheet before syncing. Will be rejected in a future release.

## Response `201`

Default Response

- object
  - `status` integer
  - `warnings` object[]: Non-blocking issues, e.g. a deprecated body field that was ignored.
    - `field` string
    - `code` string
    - `message` string
  - `data` SyncSourceResponse: Confirmation that the source is connected to the workflow.
    - `source_instance_id` string, required: The connected source's instance UUID.
    - `workflow_id` string, required: The destination workflow's UUID.
    - `push_existing` boolean: Whether existing rows were queued for backfill.
    - `fields_mapped` integer: Number of workflow inputs mapped.

## Other responses

- `400`: Invalid body, or a field_mapping key doesn't match a workflow input.
- `401`: Unauthorized — missing or invalid API key
- `403`: Forbidden. `code` says which permission refused: ROLE_FORBIDDEN (your role), INSUFFICIENT_SCOPE (the API key's scopes), WORKFLOW_FORBIDDEN (no access to the workflow), KEY_WORKFLOW_FORBIDDEN (the API key's workflow restriction).
- `404`: Source not found (or not owned by the caller's org).
- `409`: The source is already connected to this workflow. Update the existing connection instead of syncing again.
- `429`: Too Many Requests — rate limit exceeded. Check `Retry-After` header for seconds until the limit resets.

---

[API](https://skmtc.dev/floqer/apis/floqer-public-api.md) - [All operations](https://skmtc.dev/floqer/apis/floqer-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/floqer/apis/floqer-public-api/revisions/fce50dc07b20?raw)