Skip to main content
Create an agreement

Authorizations

Authorization
string
header
required

Personal API key. Send X-Organization-Id. The required cumulative level is listed in x-watchdog-permission.

Headers

X-Organization-Id
string

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.

idempotency-key
string

Optional protection for safely retrying a request after a timeout or lost response. Choose a unique value (for example, a UUID) for each action and reuse it with the same input when retrying. Omit it for a normal request.

Required string length: 1 - 200
Pattern: ^[\x21-\x7e]+$

Body

application/json
status
enum<string>
default:draft

Initial status. Active agreements require a nonblank title. All statuses remain editable.

Available options:
draft,
active,
archived
title
string | null
Maximum string length: 500
effective_date
string | null
Pattern: ^\d{4}-\d{2}-\d{2}$
expiration_date
string | null
Pattern: ^\d{4}-\d{2}-\d{2}$
supplier_ids
string<uuid>[]

Complete supplier selection. An empty array matches no invoices.

recipient_ids
string<uuid>[]

Complete recipient selection. An empty array removes the recipient restriction.

tag_ids
string<uuid>[]

Complete set of existing organization tag IDs. An empty array removes all tags. Tags organize agreements and do not affect invoice matching or compliance freshness.

applicability
object | null
renewal
object | null
instructions
string | null

Additional context for interpreting this agreement during compliance checks. Null clears the instructions. Saving does not run checks.

Maximum string length: 20000
alert_settings
object

When omitted, inherits organization agreement defaults at creation. An explicit object replaces the defaults; omitted flags within it default to false.

matching_settings
object

Stored smart-matching configuration. Replaces the complete object; omitted values default to false and null. Saving does not run matching.

Response

Current resource.

id
string<uuid>
required
title
string | null
required
status
enum<string>
required
Available options:
draft,
active,
archived
effective_date
string | null
required
Pattern: ^\d{4}-\d{2}-\d{2}$
expiration_date
string | null
required
Pattern: ^\d{4}-\d{2}-\d{2}$
suppliers
object[]
required

Complete supplier selection. An empty array matches no invoices.

Example:
recipients
object[]
required

Complete recipient selection. An empty array means any recipient.

Example:
tags
object[]
required

Complete assigned tags, ordered by ID. Empty means no tags.

Example:
version
integer
required
Required range: x >= 0
created_at
string<date-time>
required
updated_at
string<date-time>
required
alert_summary
object
required

All retained alerts of this agreement, as GET /v1/alerts/metrics?agreement_ids={id} reports them. Team filters select agreements; they do not narrow this summary.

relationships
object
required
applicability
object | null
required

Additional invoice-matching conditions over reference and delivery fields. Included in agreement detail; omitted from list summaries. Null means no additional conditions. Existing values retain whitespace and may exceed current write limits; unsupported stored conditions return 409.

renewal
object | null
required
instructions
string | null
required

Additional context used when interpreting this agreement during compliance checks.

alert_settings
object
required

Agreement-specific alert preferences. Replaces the complete object; omitted flags default to false. Saving preferences does not run checks.

matching_settings
object
required

Stored smart-matching configuration. Replaces the complete object; omitted values default to false and null. Saving does not run matching.