> ## 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. # Preview a matching refresh > Counts what refreshing matched invoices would unlink, link and delete under a proposed configuration, without saving or changing anything. Omitted fields use the stored agreement; supplied fields have PATCH semantics. An empty JSON object ({}) previews a refresh of the stored configuration. Counts describe the relationships and alerts at read time; invoice syncs can change them before the refresh. Counts assume the agreement is active; refreshing a draft or archived agreement changes nothing until it is activated. Callers decide when to confirm, for example when removed or alerts.deleted is positive or smart_matching_changed is true. ## OpenAPI ````yaml /openapi-preview.json post /v1/agreements/{id}/match-invoices/preview 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/agreements/{id}/match-invoices/preview: post: tags: - Agreements summary: Preview a matching refresh description: >- Counts what refreshing matched invoices would unlink, link and delete under a proposed configuration, without saving or changing anything. Omitted fields use the stored agreement; supplied fields have PATCH semantics. An empty JSON object ({}) previews a refresh of the stored configuration. Counts describe the relationships and alerts at read time; invoice syncs can change them before the refresh. Counts assume the agreement is active; refreshing a draft or archived agreement changes nothing until it is activated. Callers decide when to confirm, for example when removed or alerts.deleted is positive or smart_matching_changed is true. operationId: previewAgreementInvoiceMatching 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: true content: application/json: schema: type: object properties: effective_date: type: - string - 'null' pattern: ^\d{4}-\d{2}-\d{2}$ expiration_date: type: - string - 'null' pattern: ^\d{4}-\d{2}-\d{2}$ supplier_ids: type: array items: type: string format: uuid description: >- Complete supplier selection. An empty array matches no invoices. recipient_ids: type: array items: type: string format: uuid description: >- Complete recipient selection. An empty array removes the recipient restriction. applicability: type: - object - 'null' properties: match: type: string enum: - all - any conditions: type: array items: oneOf: - type: object properties: field: type: string enum: - all_references - order_references - buyer_reference - seller_reference - contract_reference - project_reference - accounting_cost - delivery_address - delivery_name - delivery_street - delivery_postal_code - delivery_city - delivery_state - delivery_country operator: type: string enum: - contains value: type: string minLength: 1 maxLength: 2000 required: - field - operator - value additionalProperties: false - type: object properties: field: type: string enum: - all_references - order_references - buyer_reference - seller_reference - contract_reference - project_reference - accounting_cost - delivery_address - delivery_name - delivery_street - delivery_postal_code - delivery_city - delivery_state - delivery_country operator: type: string enum: - not_contains value: type: string minLength: 1 maxLength: 2000 required: - field - operator - value additionalProperties: false - type: object properties: field: type: string enum: - all_references - order_references - buyer_reference - seller_reference - contract_reference - project_reference - accounting_cost - delivery_address - delivery_name - delivery_street - delivery_postal_code - delivery_city - delivery_state - delivery_country operator: type: string enum: - in values: type: array items: type: string minLength: 1 maxLength: 2000 minItems: 1 maxItems: 100 required: - field - operator - values additionalProperties: false - type: object properties: field: type: string enum: - all_references - order_references - buyer_reference - seller_reference - contract_reference - project_reference - accounting_cost - delivery_address - delivery_name - delivery_street - delivery_postal_code - delivery_city - delivery_state - delivery_country operator: type: string enum: - not_in values: type: array items: type: string minLength: 1 maxLength: 2000 minItems: 1 maxItems: 100 required: - field - operator - values additionalProperties: false - type: object properties: field: type: string enum: - all_references - order_references - buyer_reference - seller_reference - contract_reference - project_reference - accounting_cost - delivery_address - delivery_name - delivery_street - delivery_postal_code - delivery_city - delivery_state - delivery_country operator: type: string enum: - is_empty required: - field - operator additionalProperties: false - type: object properties: field: type: string enum: - all_references - order_references - buyer_reference - seller_reference - contract_reference - project_reference - accounting_cost - delivery_address - delivery_name - delivery_street - delivery_postal_code - delivery_city - delivery_state - delivery_country operator: type: string enum: - is_not_empty required: - field - operator additionalProperties: false minItems: 1 maxItems: 100 required: - match - conditions additionalProperties: false matching_settings: type: object properties: smart_matching_enabled: type: boolean default: false smart_matching_criterion: type: - string - 'null' minLength: 1 maxLength: 1000 default: null additionalProperties: false description: >- Stored smart-matching configuration. Replaces the complete object; omitted values default to false and null. Saving does not run matching. additionalProperties: false responses: '200': description: Refresh impact. 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 - private, no-store, no-transform required: false description: >- Organization-scoped API responses must not be cached. Responses with an ETag also prohibit transformations to preserve its strong validator. 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. ETag: schema: type: string required: true content: application/json: schema: type: object properties: invoices: type: object properties: current: type: integer minimum: 0 description: Invoices matched now. removed: type: integer minimum: 0 description: >- Matched invoices outside the proposed configuration, which a refresh unlinks. A minimum when smart matching is enabled. added: type: integer minimum: 0 description: >- Unmatched invoices inside the proposed configuration, which a refresh links. A maximum when smart matching is enabled, since smart matching judges each one. required: - current - removed - added alerts: type: object properties: deleted: type: integer minimum: 0 description: >- Alerts of the unlinked invoices that a refresh deletes. kept: type: integer minimum: 0 description: >- Alerts of unlinked invoices kept because a claim holds them. lost_decisions: type: integer minimum: 0 description: >- Claim and dismiss decisions recorded on the alerts a refresh deletes. required: - deleted - kept - lost_decisions counts_exact: type: boolean description: >- False when smart matching applies under the proposed configuration: removed is then a minimum and added a maximum. smart_matching_changed: type: boolean description: >- The proposed smart-matching toggle or criterion differs from the stored one. With smart matching enabled, a refresh then re-judges every existing match. etag: type: string description: >- The agreement ETag (not a preview validator) the counts were computed against. Send it as If-Match when saving the configuration. Also returned in the ETag header. required: - invoices - alerts - counts_exact - smart_matching_changed - etag '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 - private, no-store, no-transform required: false description: >- Organization-scoped API responses must not be cached. Responses with an ETag also prohibit transformations to preserve its strong validator. 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 - private, no-store, no-transform required: false description: >- Organization-scoped API responses must not be cached. Responses with an ETag also prohibit transformations to preserve its strong validator. 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 - private, no-store, no-transform required: false description: >- Organization-scoped API responses must not be cached. Responses with an ETag also prohibit transformations to preserve its strong validator. 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 - private, no-store, no-transform required: false description: >- Organization-scoped API responses must not be cached. Responses with an ETag also prohibit transformations to preserve its strong validator. 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: Stored applicability cannot be represented by this API. 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 - private, no-store, no-transform required: false description: >- Organization-scoped API responses must not be cached. Responses with an ETag also prohibit transformations to preserve its strong validator. 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_conflict' example: error: code: conflict message: Stored applicability cannot be represented by this API. 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 - private, no-store, no-transform required: false description: >- Organization-scoped API responses must not be cached. Responses with an ETag also prohibit transformations to preserve its strong validator. 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 - private, no-store, no-transform required: false description: >- Organization-scoped API responses must not be cached. Responses with an ETag also prohibit transformations to preserve its strong validator. 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 - private, no-store, no-transform required: false description: >- Organization-scoped API responses must not be cached. Responses with an ETag also prohibit transformations to preserve its strong validator. 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: 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_conflict: type: object properties: error: type: object properties: code: type: string enum: - 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 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. ````