A valid request URL is required to generate request examples{
"document": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"slug": "<string>",
"title": "<string>",
"enforcement": "required",
"archived_at": "2023-11-07T05:31:56Z",
"segment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"versions": 123,
"acceptances": 123,
"current_version": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"version": 123,
"summary": "<string>",
"effective_at": "2023-11-07T05:31:56Z",
"published_at": "2023-11-07T05:31:56Z",
"requires_reacceptance": true,
"acceptances": 123
},
"draft": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"version": 123,
"summary": "<string>",
"requires_reacceptance": true,
"updated_at": "2023-11-07T05:31:56Z"
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Create a legal document
Requires legal:manage.
A document is created with no text at all: it is a name, an address and a rule about who must agree. The words are a version, and publishing one is a separate act — creating a document never puts anything in front of anybody.
slug is how the document is addressed everywhere outside this panel: in GET /v1/legal/{publishable_key}/{slug}, in the link inside your sign-up form, in the portal’s path. Lowercase letters, digits, hyphens and underscores — a name is refused rather than normalised, because this string is typed twice in two different places and case is how that goes wrong invisibly. It is unique per environment, so your test environment rehearses next year’s terms under the same name production uses.
enforcement defaults to required: every read that reports an outstanding agreement marks it blocking, and what your product does about that is its decision — nothing here refuses a sign-in over it. optional publishes and asks and is never marked blocking.
A valid request URL is required to generate request examples{
"document": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"environment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"slug": "<string>",
"title": "<string>",
"enforcement": "required",
"archived_at": "2023-11-07T05:31:56Z",
"segment_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"versions": 123,
"acceptances": 123,
"current_version": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"version": 123,
"summary": "<string>",
"effective_at": "2023-11-07T05:31:56Z",
"published_at": "2023-11-07T05:31:56Z",
"requires_reacceptance": true,
"acceptances": 123
},
"draft": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"version": 123,
"summary": "<string>",
"requires_reacceptance": true,
"updated_at": "2023-11-07T05:31:56Z"
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Authorizations
A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange. Only a 401 means it is spent; not_a_member (403) is about the organization named in X-Organization-Id and leaves the token good for the others.
Headers
The organization the caller is acting on — the org_… code that appears in the panel URL. It identifies; the membership JOIN is what authorizes, so a forged code reads nothing: the answer is not_a_member (403), which does not mean the session is over. Absent, the session's default organization answers, or — if that membership was revoked while the session was open — any other one the caller still holds.
Query Parameters
Which environment to act in. A view parameter, valid only on the staff surface — a machine credential never chooses its environment, it is resolved from the key.
live, test Body
Creating or editing a document. On PATCH, an omitted field keeps its value.
Lowercase letters, digits, hyphens and underscores. Refused rather than normalised — it is typed twice, here and in your own markup.
At most 160 characters.
Defaults to required on creation.
required, optional true withdraws the document; false puts it back in circulation. This is how terms are taken down — DELETE refuses a document that ever published anything.
Aims an OPTIONAL document at a segment; null is everybody. A required document may not be aimed, and the pair is checked together — making an aimed document required is refused exactly as aiming a required one is, with required_cannot_be_aimed. The reason is that a term is evidence rather than delivery: a required document is a condition of use rather than a delivery, a pending obligation would evaporate when somebody's attributes changed, and "prove this customer agreed" would become "prove they did not have to" — an answer depending on a past segment membership nothing here versions. An optional document is an offer, so none of that applies: leaving the segment stops the offer and cannot un-agree what was agreed.
Response
The document, with no version yet.
One of your terms: a name, an address, and a rule about whether agreeing is required. The words are versions of it.
Show child attributes
Show child attributes