---
title: "Start a pull from the ERP"
method: POST
path: "/v1/erp-connections/{connectionId}/sync"
tags: ["ERP sync"]
---

# Start a pull from the ERP

`POST /v1/erp-connections/{connectionId}/sync`

## Request

- Base URL: `https://api.getfinero.com/functions/v1/api`
- URL: `https://api.getfinero.com/functions/v1/api/v1/erp-connections/{connectionId}/sync`
- Auth: HTTP bearer

Starts an invoice pull for this connection and returns immediately with the id of the run it reserved — the pull itself continues in the background. Poll that run until `status` is terminal. Only ONE run can be in flight per connection: if a scheduled or app-triggered pull is already running, this is REFUSED as a conflict rather than queueing a second one — list the connection's runs to find the one in flight and poll that. A `running` answer means the run was RESERVED and dispatched, NOT that the connection authenticated: a connection whose credential has expired accepts this call and the run fails seconds later. Check the connection's `status`, and poll the run to a terminal status before reporting success. Partial runs preserve progress; unresolved rows or schedules block completion. ERP read rate limits receive bounded retries within the pull deadline. This does not change the connection's schedule; the automatic cadence continues unchanged alongside it.

Requires an **admin** API key (has side effects).

## Path parameters

- `connectionId` string, uuid, required

## Response `202`

Success

- object: Accepted. The pull runs in the background.
  - `sync_run_id` string, uuid, required: The run that was reserved — poll GET /v1/sync-runs/{syncRunId}.
  - `status` 'running', required: Always `running`: the run is reserved and the pull has been dispatched.

## Other responses

- `400`: `validation_failed` — The request failed schema validation. See error.details for field messages.
- `401`: `invalid_credentials` — The credential is malformed or does not match an active key. The response never reveals whether a key identifier exists. `missing_credentials` — No Authorization: Bearer header was sent. `revoked_credentials` — The presented key was revoked. Create a new key in Settings → API.
- `403`: `feature_unavailable` — The tenant's tier does not currently include API access. Feature rollout flags cannot grant this entitlement. `permission_denied` — The key's permission does not allow this operation (readonly keys cannot call admin-only operations).
- `404`: `not_found` — No such resource in YOUR tenant. Ids belonging to another tenant are indistinguishable from missing ones.
- `409`: `conflict` — State conflict — e.g. live payment links already cover the installment, or a concurrent identical request is in flight.
- `413`: `payload_too_large` — The request body exceeds the 64 KiB limit.
- `422`: `connection_disconnected` — This ERP connection has been disconnected, so Finero holds no credential for it and a pull cannot be started. A workspace administrator reconnects the ERP in the Finero app; retrying will not change the answer. `sync_disabled` — Invoice sync is switched off for this ERP connection, so there is nothing to pull. A workspace administrator turns it back on in the Finero app; retrying will not change the answer.
- `429`: `rate_limit_exceeded` — Too many requests. Honor the Retry-After header (seconds) before retrying — waiting that long is enough. The RateLimit-* fields on every response say how much headroom is left before this happens; pace against them instead of retrying into a refusal.
- `500`: `internal_error` — Unexpected server error. Safe to retry with the same Idempotency-Key.

---

[API](https://skmtc.dev/getfinero/apis/finero-public-api.md) · [All operations](https://skmtc.dev/getfinero/apis/finero-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getfinero/apis/finero-public-api/revisions/3d456e222775?raw)