> ## Documentation Index > Fetch the complete documentation index at: https://docs.watchdog.no/llms.txt > Use this file to discover all available pages before exploring further. # Start a sync > Reads invoices for a period from the provider and imports them. The returned id is also the workflow run id: follow progress with GET /v1/workflow-runs/{id}, read imported and failed invoices from its items, and stop it with POST /v1/workflow-runs/{id}/cancel. One sync runs per integration at a time. Without Admin the scope must include named suppliers. A running estimate for the integration is cancelled once the sync is admitted; a rejected request leaves it running. ## OpenAPI ````yaml /openapi-preview.json post /v1/integrations/{id}/syncs openapi: 3.1.0 info: title: Watchdog API (preview) version: 1.0.0 description: >- Development preview for agreements, price items, document relationships, canonical invoices, alerts and alert topics, claims and attached alerts, shared entity activity and comments, Document uploads, invoice imports, explicit invoice-agreement matching, and workflow runs. This contract is under development and is not served by api.watchdog.no. Request bodies are limited to 2 MiB (2,097,152 bytes), including all JSON fields and line data, except POST /v1/support/contact which permits 32 MiB for base64 attachments. File bytes are uploaded directly to storage. The existing public REST service retains its separate contract. servers: - url: http://localhost:3500 description: Local development Worker security: [] paths: /v1/integrations/{id}/syncs: post: tags: - Integrations summary: Start a sync description: >- Reads invoices for a period from the provider and imports them. The returned id is also the workflow run id: follow progress with GET /v1/workflow-runs/{id}, read imported and failed invoices from its items, and stop it with POST /v1/workflow-runs/{id}/cancel. One sync runs per integration at a time. Without Admin the scope must include named suppliers. A running estimate for the integration is cancelled once the sync is admitted; a rejected request leaves it running. operationId: startIntegrationSync parameters: - name: X-Organization-Id in: header required: false schema: type: string description: >- Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization. - schema: type: string format: uuid required: true name: id in: path requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/StartIntegrationSync' responses: '202': description: The sync was admitted and is running. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. Location: schema: type: string required: false description: >- Relative resource URL. Present on synchronous resource creation and accepted workflow admissions or replays; absent for a known primary-file duplicate. content: application/json: schema: $ref: '#/components/schemas/IntegrationSync' '400': description: >- Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes). headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: '#/components/schemas/Error_validation_error' example: error: code: validation_error message: >- Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes). request_id: req_example '401': description: Missing or invalid bearer credential. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. WWW-Authenticate: schema: type: string required: false description: Bearer authentication challenge, when supplied. content: application/json: schema: $ref: '#/components/schemas/Error_invalid_token' example: error: code: invalid_token message: Missing or invalid bearer credential. request_id: req_example '403': description: >- Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: >- #/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required example: error: code: forbidden message: >- Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions. request_id: req_example '404': description: The resource does not exist in the current organization. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: '#/components/schemas/Error_not_found' example: error: code: not_found message: The resource does not exist in the current organization. request_id: req_example '409': description: >- A sync is already running (workflow_run_id names it), or the integration is disabled or not tested. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: >- #/components/schemas/Error_sync_in_progress_integration_not_syncable_conflict example: error: code: sync_in_progress message: >- A sync is already running (workflow_run_id names it), or the integration is disabled or not tested. request_id: req_example '429': description: The IP or authenticated credential exceeded its request limit. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. Retry-After: schema: type: string example: '60' required: true description: Seconds to wait before retrying the request. content: application/json: schema: $ref: '#/components/schemas/Error_rate_limit_exceeded' example: error: code: rate_limit_exceeded message: >- The IP or authenticated credential exceeded its request limit. request_id: req_example '500': description: >- Unexpected server failure. Include the request ID when contacting support. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: '#/components/schemas/Error_internal_error' example: error: code: internal_error message: >- Unexpected server failure. Include the request ID when contacting support. request_id: req_example '503': description: >- Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. Retry-After: schema: type: string example: '60' required: true description: Seconds to wait before retrying the request. content: application/json: schema: $ref: '#/components/schemas/Error_service_unavailable' example: error: code: service_unavailable message: >- Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided. request_id: req_example security: - ApiKeyBearer: [] - ClerkSessionBearer: [] components: schemas: StartIntegrationSync: type: object properties: date_from: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: First invoice date to read, inclusive. date_through: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Last invoice date to read, inclusive. scope: $ref: '#/components/schemas/IntegrationRunScope' max_files: type: integer exclusiveMinimum: 0 maximum: 100000 description: Stop after this many new invoices. additionalProperties: false IntegrationSync: type: object properties: id: type: string format: uuid description: 'Also the workflow run id: progress, items and cancel use it.' integration_id: type: string format: uuid trigger: type: string enum: - manual - scheduled mode: type: string enum: - period - incremental description: >- period reads a requested date range; incremental continues from the last sync. period: type: - object - 'null' properties: from: type: string format: date-time to: type: string format: date-time required: - from - to description: 'Invoice dates read: from is inclusive, to is exclusive.' scope: allOf: - $ref: '#/components/schemas/IntegrationScope' - type: - object - 'null' description: The scope this run used, frozen when it started. max_files: type: - integer - 'null' status: type: string enum: - queued - running - completed - failed - cancelled coverage: type: string enum: - in_progress - full - partial description: >- partial: the run ended without reading everything it was asked to (discovery stopped early, invoices were deferred, or it was cancelled). retryable says whether a retry can complete it. discovery: type: object properties: state: type: string enum: - executing - failed - complete - capacity_limited - cancelled records_scanned: type: integer selected: type: integer description: Invoices chosen for import so far. deferred: type: integer skipped: type: integer required: - state - records_scanned - selected - deferred - skipped description: Finding the invoices to import; items then import them one by one. items: type: object properties: queued: type: integer running: type: integer completed: type: integer failed: type: integer cancelled: type: integer skipped: type: integer description: >- Includes invoices deferred because the organization reached its capacity. required: - queued - running - completed - failed - cancelled - skipped invoices: type: object properties: created: type: integer updated: type: integer required: - created - updated retryable: type: boolean description: POST …/retry would resume discovery or re-queue failed invoices. retry_blocked_by: type: - string - 'null' enum: - superseded - configuration_changed - integration_disabled - active_sync - null failure: type: - object - 'null' properties: code: type: string message: type: string required: - code - message created_by: type: - object - 'null' properties: id: type: string name: type: - string - 'null' required: - id - name created_at: type: string format: date-time finished_at: type: - string - 'null' format: date-time required: - id - integration_id - trigger - mode - period - scope - max_files - status - coverage - discovery - items - invoices - retryable - retry_blocked_by - failure - created_by - created_at - finished_at Error_validation_error: type: object properties: error: type: object properties: code: type: string enum: - validation_error message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_invalid_token: type: object properties: error: type: object properties: code: type: string enum: - invalid_token message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required: type: object properties: error: type: object properties: code: type: string enum: - forbidden - token_disabled - organization_required - insufficient_role - mfa_required message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_not_found: type: object properties: error: type: object properties: code: type: string enum: - not_found message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_sync_in_progress_integration_not_syncable_conflict: type: object properties: error: type: object properties: code: type: string enum: - sync_in_progress - integration_not_syncable - conflict message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_rate_limit_exceeded: type: object properties: error: type: object properties: code: type: string enum: - rate_limit_exceeded message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_internal_error: type: object properties: error: type: object properties: code: type: string enum: - internal_error message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_service_unavailable: type: object properties: error: type: object properties: code: type: string enum: - service_unavailable message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error IntegrationRunScope: type: object properties: suppliers: type: object properties: mode: type: string enum: - all - include - exclude items: type: array items: type: object properties: id: type: string minLength: 1 maxLength: 255 name: type: string maxLength: 500 code: type: string maxLength: 255 group: type: object properties: kind: type: string enum: - vendor-sites prefixes: type: array items: type: string minLength: 1 maxLength: 255 minItems: 1 maxItems: 1000 site_count: type: integer exclusiveMinimum: 0 inactive_site_count: type: integer minimum: 0 required: - kind - prefixes - site_count - inactive_site_count description: >- Set when one supplier stands for several provider vendor sites. required: - id - name maxItems: 5000 required: - mode - items additionalProperties: false companies: type: array items: type: object properties: id: type: string minLength: 1 maxLength: 255 name: type: string maxLength: 500 country_code: type: - string - 'null' maxLength: 10 accounting_currency_code: type: - string - 'null' maxLength: 10 required: - id - name maxItems: 1000 description: Provider companies to read. Empty or omitted reads every company. processing_statuses: type: array items: type: string minLength: 1 maxLength: 100 minItems: 1 maxItems: 50 path_globs: type: array items: type: string minLength: 1 maxLength: 256 maxItems: 20 additionalProperties: false description: >- Omit to read the integration’s saved scope. When sent, it replaces the saved scope for this run: every dimension it leaves out reads everything instead of falling back to the saved value. IntegrationScope: type: object properties: suppliers: type: object properties: mode: type: string enum: - all - include - exclude items: type: array items: type: object properties: id: type: string minLength: 1 maxLength: 255 name: type: string maxLength: 500 code: type: string maxLength: 255 group: type: object properties: kind: type: string enum: - vendor-sites prefixes: type: array items: type: string minLength: 1 maxLength: 255 minItems: 1 maxItems: 1000 site_count: type: integer exclusiveMinimum: 0 inactive_site_count: type: integer minimum: 0 required: - kind - prefixes - site_count - inactive_site_count description: >- Set when one supplier stands for several provider vendor sites. required: - id - name maxItems: 5000 include_unidentified: type: boolean description: >- With mode include or exclude, also read invoices whose supplier the provider does not identify. Omitted reads them. required: - mode - items additionalProperties: false companies: type: array items: type: object properties: id: type: string minLength: 1 maxLength: 255 name: type: string maxLength: 500 country_code: type: - string - 'null' maxLength: 10 accounting_currency_code: type: - string - 'null' maxLength: 10 required: - id - name maxItems: 1000 description: Provider companies to read. Empty or omitted reads every company. processing_statuses: type: array items: type: string minLength: 1 maxLength: 100 minItems: 1 maxItems: 50 path_globs: type: array items: type: string minLength: 1 maxLength: 256 maxItems: 20 module_company_codes: type: object properties: costinvoice: type: array items: type: string minLength: 1 maxLength: 100 maxItems: 50 purchaseorder: type: array items: type: string minLength: 1 maxLength: 100 maxItems: 50 additionalProperties: false securitySchemes: ApiKeyBearer: type: http scheme: bearer description: >- Personal API key. Send X-Organization-Id. The required cumulative level is listed in x-watchdog-permission. ClerkSessionBearer: type: http scheme: bearer description: Clerk session with an active organization. ````