A valid request URL is required to generate request examples{
"version": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"document_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"version": 123,
"body_markdown": "<string>",
"summary": "<string>",
"requires_reacceptance": true,
"effective_at": "2023-11-07T05:31:56Z",
"accept_by": "2023-11-07T05:31:56Z",
"published_at": "2023-11-07T05:31:56Z",
"in_force": true,
"acceptances": 123,
"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"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Publish a version
Requires legal:manage. This is the act: the text becomes readable at GET /v1/legal/{publishable_key}/{slug}, the version is frozen, and — if it declared requires_reacceptance — everybody who agreed to an older one becomes pending again, in the same statement, with nothing to backfill.
It happens exactly once per version. A second call answers 404, because a second publish would move the effective date of words people have already agreed to.
effective_at may be in the future, which is what a thirty-day notice is: until that moment the version before it is still the one in force, and it is the one being offered for acceptance. It may not be in the past — back-dating terms asserts that somebody was governed by words that did not exist. Leave it out to publish now. A publication dated ahead that asked to notify announces itself on the day it takes force, not on the day it was published.
It announces legal_document.published, which is deliverable to your webhook endpoints: invalidate the cached terms page on your marketing site, send the notice, re-open the acceptance gate in your own product.
A valid request URL is required to generate request examples{
"version": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"document_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"version": 123,
"body_markdown": "<string>",
"summary": "<string>",
"requires_reacceptance": true,
"effective_at": "2023-11-07T05:31:56Z",
"accept_by": "2023-11-07T05:31:56Z",
"published_at": "2023-11-07T05:31:56Z",
"in_force": true,
"acceptances": 123,
"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"
}
}{
"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.
Body
When these words start governing. RFC 3339 with an offset. Omitted or null means now; a future moment keeps the previous version in force until then; the past is refused.
The far edge of the window where agreeing may WAIT. RFC 3339 with an offset, and after effective_at — a deadline that has already passed is a window nobody gets, refused with accept_by_before_effective.
Until it, the agreement is outstanding and the ask is deferrable: pending_agreements reports deferrable: true, the SDK's card offers a way out, and the person is asked again on their next visit. After it, that door closes. Omit it for the strict shape — outstanding the moment it takes force, with nothing offering to defer it.
It is frozen with the words: extending a deadline is benign and shortening one is hostile, so rather than encode which is which, changing the terms of the asking is publishing another version.
Announce the publication in the in-app bell of everybody it puts in front of a checkbox: an action notification carrying a button that opens the agreement, rather than a link to somewhere else.
Only people who are actually PENDING are told — computed with the same floor the card uses, so a notice cannot disagree with what it tells somebody to open. Anonymous visitors never receive one. Defaults to false, and the default is the decision: a version published to fix a heading must not put a demand in anybody's notifications.
With a future effective_at the announcement WAITS for it. It goes out on the day the terms start governing, to whoever owes them on that day — announcing at publication would reach the people who owe the PREVIOUS version, about words that govern nobody yet, and nothing at all would happen on the date itself. A nightly sweep does it, so the notice lands within a day of the effective moment rather than at it.
Response
The published version.
One version's words. Frozen the moment it is published: body, summary, effective date and requires_reacceptance all become immutable, because an acceptance names this row.
Show child attributes
Show child attributes