Skip to main content
List agreements

Authorizations

Authorization
string
header
required

Personal API key sent as a bearer token, together with X-Organization-Id. The key must have at least the access level the endpoint requires (read, write or admin).

Headers

X-Organization-Id
string

The organization to act in. Required for personal API keys; list the organizations you can access with GET /v1/organizations.

Query Parameters

fields
string

Return only these fields of each row, comma-separated; use dots for nested fields, such as suppliers.id. id is always returned. Fields: id, title, status, effective_date, expiration_date, suppliers, recipients, tags, projects, owner_user_id, owner, readiness, renewal_action, version, created_at, updated_at, alert_summary, relationships.

mine
enum<string>

Only records matched by the filters of teams you belong to. Teams combine with OR; other filters combine with AND. Cannot be combined with team_ids.

Available options:
true,
false
team_ids
string

Only records matched by the filters of these teams: at most 50, comma-separated in a query string or an array in a JSON body. Teams combine with OR. Unknown teams return 404.

ids
string

Only these agreement IDs (maximum 50).

renewal_action_kinds
string

Agreements whose next renewal action is any of these kinds: cancel_by (renews automatically unless cancelled by the deadline), renew_by (ends unless renewed by the deadline), automatic_notice (renews automatically with no expiration date; it can be ended at any time with the notice period, so there is no deadline), missing_details (renewal terms exist but the deadline cannot be computed), none (does not renew, or no renewals remain).

renewal_deadline_from
string

Renewal action deadline on or after this date.

Pattern: ^\d{4}-\d{2}-\d{2}$
renewal_deadline_through
string

Renewal action deadline on or before this date.

Pattern: ^\d{4}-\d{2}-\d{2}$
upcoming_through
string

Agreements with a renewal deadline or an expiration date from today, in the organization's timezone, through this date: what must be cancelled, renewed or will end soon.

Pattern: ^\d{4}-\d{2}-\d{2}$

Text in the agreement title or a supplier name.

Required string length: 1 - 200
statuses
string

Agreements with any of these statuses: draft (being set up), active (Watchdog checks invoices against it) or archived (no longer checked). It does not say whether the contract term is in force: use expiration_date, renewal_action or the valid_on filter for that.

supplier_ids
string

Agreements covering any of these suppliers.

recipient_ids
string

Agreements covering any of these recipients, including agreements for any recipient.

tag_ids
string

Agreements with any of these tags.

project_ids
string

Any selected project. Always combined with other dimensions using AND. Unavailable IDs return 404.

owner_user_ids
string

Any selected owner. IDs are case-sensitive. Unavailable members return 404.

supplier_operator
enum<string>
Available options:
is,
is_not
tag_operator
enum<string>
Available options:
is,
is_not
join_operator
enum<string>

Combine supplier and tag ID filters with AND (default) or OR. Other filters and the organization boundary always apply.

Available options:
and,
or
has_alert_verdicts
string

Agreements with at least one alert with any of these verdicts. Combine with has_alert_credited to match both on the same alert. Comma-separated: pending, accepted, dismissed.

has_alert_credited
enum<string>

Agreements with at least one alert that is (true) or is not (false) credited.

Available options:
true,
false
effective_from
string

Effective (start) date on or after this date; excludes agreements without one.

Pattern: ^\d{4}-\d{2}-\d{2}$
effective_through
string

Effective (start) date on or before this date; excludes agreements without one.

Pattern: ^\d{4}-\d{2}-\d{2}$
expiration_from
string

Expiration date on or after this date; excludes agreements without one.

Pattern: ^\d{4}-\d{2}-\d{2}$
expiration_through
string

Expiration date on or before this date; excludes agreements without one.

Pattern: ^\d{4}-\d{2}-\d{2}$
valid_on
string

Agreements in force on this date: effective on or before it and expiring on or after it. A missing effective or expiration date counts as open-ended.

Pattern: ^\d{4}-\d{2}-\d{2}$
limit
integer
default:50

Maximum number of results per page.

Required range: 1 <= x <= 1000
cursor
string

Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page.

Maximum string length: 4096
sort
enum<string>
default:created_at

alert_progress is the share of alerts that are no longer pending. open_alert_impact is the pending and claimed impact in the organization currency.

Available options:
created_at,
status,
renewal_deadline,
title,
effective_date,
expiration_date,
supplier,
pending_topic_count,
alert_progress,
open_alert_impact
direction
enum<string>
default:desc
Available options:
asc,
desc

Response

A page of agreements.

data
object[]
required
Maximum array length: 1000
next_cursor
string | null
required