Developer documentation

Concepts & Vocabulary

The terms that show up across the SDK, API, and webhook examples — what each one is, what it looks like, and where you'll see it.

At a Glance

1. Application

An Application is your project on Overturo. It owns the credentials you use to make API calls and the flows you publish to your users. You create one from Connect.

Each application gets a unique ID with format tp_<region>_<hashid> (for example tp_dev_7J580kDeZ6vGmnyxUaPAKblW… in development, tp_us_… or tp_eu_… in production), a publishable key for client-side identification, and one or more API tokens for server-side calls. Webhook deliveries, audit-trail records, and rate limits are all scoped per-application.

You'll see it as: the application_id field in webhook payloads and API responses.

2. Publishable Key

A Publishable Key identifies your application from client-side code (browser, mobile, embedded SDK). It cannot read sensitive data, modify resources, or list other users — only create consent sessions. Safe to commit to source control and ship in JavaScript bundles.

Two flavours: pk_test_* hits a sandbox; pk_live_* hits production. Sent on every request as the X-Publishable-Key header — the SDK does this for you when you pass publishableKey to the constructor.

Find it in: Credentials → Publishable Keys. Used in: JavaScript SDK initialization.

3. API Token

An API Token is a server-only bearer credential with full account-level access. Use it for server-to-server calls: creating applications, managing flows, fetching audit records, processing webhooks.

Treat like a password: never expose to a browser, never commit to source control, rotate regularly. Sent as Authorization: Bearer <token>. The token itself is an opaque high-entropy string with no marketed prefix; the surrounding record (creation time, scopes, last-used) has a api_token_* ID you'll see in the dashboard.

Find it in: Credentials → API Tokens. Used in: Authentication §1.

4. Flow

A Flow is a reusable consent template you author once and reference for every consent session. It declares: which data fields the user is consenting to share, the purpose of use, retention, revocation policy, and the multi-step UX the user walks through.

A flow has a stable ID like flw_dev_V3d1oQ6Z… (or flw_* in production). Once activated, a flow's terms are immutable — to change them, you publish a new version; the old version keeps governing previously-collected consents.

You'll pass it as: flowId when creating a consent session.

5. Consent Session

Scope: the Consent Session and Consent Token concepts below describe the integration model for consent flows (Flows — see §4). Other artifact types — Agreements, Authorities, data deals — have analogous lifecycle objects with different semantics; see "Other surface artifacts" at the end of §6.

A Consent Session is a short-lived link between a specific user and a specific Flow. You create one when a user is about to consent (the SDK creates it for you when you call overturo.consent({ flowId })); the user is then walked through the Flow's UX. The session expires whether or not the user finishes.

Carries a session_token used to render the embed and an embed_url the iframe loads. The session is the request to consent; the Consent Token below is the receipt.

How to start one: see Embedding for the three integration paths (redirect link, inline iframe, JavaScript SDK) — each handles session creation differently.

6. Consent Token

A Consent Token is the receipt the user produces by completing a Flow. It's the cryptographic answer to "did this user actually click through and consent to these terms?" — your backend verifies it, and only then trusts that consent has been granted. Like §5, this concept applies specifically to Flow-shaped artifacts; other surfaces produce different receipts (see below).

Properties:

• Single-use. Verifying the token clears it server-side; replays return expired.
• Time-limited. 5-minute lifetime from issuance. Verify promptly.
• Opaque. A 32-byte URL-safe base64 string. Don't parse it client-side; treat it as a bearer.
• Browser-issued. Delivered to your page via postMessage as event.data.consent_token on the overturo:complete event.

Always verify server-side. Verification returns valid: true plus a status — one of nine values. The two states you act on are fulfilled (proceed) and anything else (don't):

Status values

Two lifecycle paths — standard (pending → authenticating → verifying → reviewing → fulfilled) and informed-consent (pending → informed → evidenced → fulfilled) — converge on fulfilled on success or expired / revoked on failure.

Verify with: Ruby SDK (client.consent.consent_sessions.verify(token)) or the equivalent REST call from any backend.

7. AI Agent Token

An AI Agent Token (prefixed ra_agent_*) is a credential issued to an AI agent acting on a user's behalf. Unlike a user's API token, it carries explicit authority bounds — scope, action, value, time, escalation, reputation — that the user set when delegating.

See: Authentication §4 for the issuance flow and the bounds reference.

8. Delegation Grant

A Delegation Grant (format dlg_<region>_<hashid>) lets one human act on another's behalf — guardian for a minor, caregiver for a patient, legal POA, IT admin for an employee, peer for a friend. The delegate authenticates as themselves and includes the grant ID in the X-Delegation-Grant-Id header alongside their own token.

Different from an agent token: agent tokens are for AI software, delegation grants are for human-to-human authority. See: Authentication §5.

9. Audit Trail

Every consent decision — granted, denied, modified, revoked — is recorded in a tamper-proof audit trail. Each record is hash-chained to the one before it, so a single after-the-fact edit invalidates every later record's signature. The chain head is published to an external witness every fifteen minutes, which means even Overturo can't rewrite history retroactively without producing visible evidence.

Three guarantees this gives you:

• Non-repudiation. A consent that was granted can be proven granted at a specific time, and a denial can be proven denied — no matter who later disputes it.
• Witness trail. If the consent record changes, the cryptographic chain breaks; an external auditor can detect tampering without trusting Overturo.
• Discoverable. The full history of any consent — every state transition, every actor, every signature — is queryable from your application's audit endpoints.

Practical implication: when a regulator, partner, or end-user asks "did this user actually consent?", the audit trail is the answer of record. Don't keep your own duplicate log unless you have a compliance reason — the canonical trail is here.

Authentication Guide

Five authentication mechanisms, each suited to different integration scenarios.

At a Glance

1. API Tokens

API tokens provide simple bearer authentication for server-to-server calls. Create tokens from Credentials.

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  https://overturo.com/api/v1/me

2. OAuth 2.0 / OIDC

For applications that need to act on behalf of users, use the OAuth 2.0 Authorization Code flow with PKCE. Overturo is an OpenID Connect provider.

GET /oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  response_type=code&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=openid+profile+email&
  state=RANDOM_STATE

curl -X POST https://overturo.com/oauth/token \
  -d grant_type=authorization_code \
  -d code=AUTHORIZATION_CODE \
  -d redirect_uri=YOUR_REDIRECT_URI \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  https://overturo.com/api/v1/me

Available Scopes

Additional Grant Types

• Device Authorization (RFC 8628) — for devices without a browser
• Token Exchange (RFC 8693) — for AI agent delegation flows
• Pushed Authorization Requests (RFC 9126) — for secure parameter transmission

3. Publishable Keys

Publishable keys (prefixed pk_live_ or pk_test_) are safe for use in client-side code. They identify your application but cannot access sensitive data.

import { Overturo } from "@overturo/js"

const overturo = new Overturo({
  publishableKey: "pk_live_abc123"
})

// Or via HTTP header:
// X-Publishable-Key: pk_live_abc123

curl -X POST \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"allowed_origin":{"origin":"https://yourdomain.com"}}' \
  https://overturo.com/api/v1/applications/YOUR_APP_ID/allowed_origins

4. AI Agent Tokens

AI agents authenticate using agent tokens (prefixed ra_agent_) obtained through the token exchange flow. These tokens carry bounded authority constraints.

1. Register an AI agent identity via the Delegate API
2. The user grants a delegation with specific authority bounds
3. Exchange the delegation grant for an agent token via /oauth/token/exchange
4. Use the agent token for API calls, including the MCP gateway

curl -H "Authorization: Bearer ra_agent_abc123..." \
  https://overturo.com/mcp/v1/agent

Authority Bounds

5. Delegation Grants

Delegation grants allow a human delegate (guardian, caregiver, authorized representative) to make API calls on behalf of another user.

1. The principal creates a delegation grant specifying the delegate and allowed scopes
2. The delegate authenticates normally with their own credentials
3. The delegate includes the X-Delegation-Grant-Id header alongside their Authorization header
4. The API processes the request in the context of the principal

curl -H "Authorization: Bearer DELEGATE_USER_TOKEN" \
  -H "X-Delegation-Grant-Id: dlg_dev_abc123" \
  https://overturo.com/api/v1/me

Delegation Types

Country-aware addressing

Each person's records are homed in their own country, and the API serves a resource from the country where it's homed. You don't choose the country per request — it follows the subject. The home country is reported as an ISO country code (for example IT).

If you address a resource through the wrong country, the API returns an explicit error carrying a home_country field that tells you which country to re-issue the request against. It never leaks the resource or its data — a "wrong door" signal, not a failure.

The exact error code and JSON shape are in the OpenAPI reference.

OAuth Authorization

Pushed Authorization Request (PAR) — required for every authorization flow. Sits alongside the REST API but follows OAuth 2.0 conventions rather than RESTful CRUD.

Endpoint

PAR is required for all OAuth clients (require_par: true is the platform-wide default). Push your authorization parameters server-to-server, then redirect the user to /oauth/authorize with only client_id and request_uri.

Discovery

Standard OIDC discovery endpoints live under /.well-known/* — see the Authentication tab.

The discovery document also advertises five OIDC-A extension fields (agent_claims_supported, agent_types_supported, delegation_methods_supported, oap_jwks_uri, oap_protocol_versions_supported). See the AI Agent Authorization → OIDC-A Interop surface for the full schema.

API Reference

The Overturo API is organized around REST. All requests and responses use JSON.

Base URL

https://overturo.com/api/v1/

Authentication

The API supports multiple authentication mechanisms. See the Authentication tab for full details.

Authorization: Bearer YOUR_API_TOKEN

Response Format

All responses are returned as JSON. Successful responses include the resource or collection directly. Errors include a message field.

{
  "id": "app_abc123",
  "name": "My Application",
  "environment": "sandbox",
  "created_at": "2025-01-15T10:30:00Z"
}

Error Codes

Endpoints by Surface

• Core 7 endpoints →
• Connect 90 endpoints →
• Consent 30 endpoints →
• Verify 34 endpoints →
• Protect 38 endpoints →
• Agree 31 endpoints →
• Delegate 50 endpoints →
• Comply 20 endpoints →
• Marketplace 19 endpoints →

Well-Known Endpoints

Discovery endpoints following standard specifications. Receipt-specific machine endpoints (the published receipt schema and export flavors) are documented on the Receipts tab.

Cross-border endpoints

Read and prove the cross-border story. All are scoped to your application and carry no personal data unless noted. Full reference is in the OpenAPI document.

A subject's right of access / portability is fulfilled across countries through the self-service data export. The signing decision kind rides the Decisions API — see the Embedding tab.

Embedding a Decision

Four delivery modes (embed, popup, redirect, direct) for both kinds of Decision (consent, approval). Pick the simplest that meets your needs — you can always upgrade later. The same <overturo-decision> element and the same postMessage protocol handle both kinds.

Keeping your own form? The Forms documentation covers the Overturo field, the capture snippet, Typeform and the Record API.

At a Glance

1. Choosing your integration

Start at the top and stop at the first "yes":

• Is a plain link acceptable — user clicks, navigates to Overturo, completes the Flow, returns to your site? → Redirect link. One line of HTML, no JavaScript.
• Do you want the Flow to render inside your page without the user navigating away? → Inline iframe. One line of HTML; add a postMessage listener if you need to react to the consent result.
• Do you need callbacks (success / cancel / error), popup mode, dynamic Flow IDs, or anything beyond a static embed? → JavaScript SDK. npm install @overturo/js + a few lines of code.

All three approaches reach the same Flow. The choice is purely about how much surrounding JavaScript you're willing to write — not about which features you can use.

2. Prerequisite: activate your Flow first

Embedding works only against active Flows. A Flow in draft status will return 404 from the Flow URL and reject session creation. Activation is one click in the Flow's editor — and once activated, the Flow's terms are immutable, so do it after you've confirmed the field set, retention, and presentation are correct.

2.5 Prerequisite: register your origin

Browser-based integrations (§4 iframe, §5 SDK) load resources and call API endpoints from your site's origin. The Application's CORS allowlist must include that origin or the browser blocks the request — typically with no error visible inside the Flow, just a failed preflight in the network tab. Server-side calls authenticated with a Bearer token are unaffected.

3. Redirect link

The simplest possible integration: a plain <a> tag pointing at the Flow's hosted page. Zero JavaScript. The user clicks, walks through the Flow on a page hosted by Overturo, then returns to your redirect_uri.

<a href="https://trust.overturo.com/accord/FLOW_ID?redirect_uri=https://yoursite.com/consented">
  Give Consent
</a>

Substitute FLOW_ID with your Flow's ID (format flw_dev_… in development, flw_us_… / flw_eu_… in production — see Concepts §4).

How completion is signalled

Redirect mode signals completion in two channels — the URL the user lands on, and a webhook your backend receives. The trust signal is the webhook; the URL is for UX.

• On success — the user lands at your redirect_uri with no query parameters appended. Do not infer consent from the bare arrival; an attacker can hit your callback URL directly.
• On decline — the user lands at redirect_uri?error=access_denied. Use this to render a "you can try again" page; do not treat absence of error as proof of consent.
• The Consent Token arrives via webhook — when the user completes the Flow, your Application's webhook endpoint receives a consent.granted event carrying the consent token, the user identifier, and the Flow ID. That's the trust boundary. Verify the webhook signature, look up the user, and treat consent as granted from that point.

Wiring webhooks: see the Ruby SDK's webhook handler reference (search for "Webhooks") — the same payload shape applies regardless of the language receiving it. Webhook endpoints are configured per-Application on Credentials → Webhooks.

4. Inline iframe

Render the Flow inside an iframe on your page. The user never navigates away. You receive completion events via window.postMessage.

<iframe
  src="https://trust.overturo.com/accord/FLOW_ID"
  sandbox="allow-forms allow-scripts allow-same-origin"
  style="width: 100%; height: 600px; border: none;"
  allow="publickey-credentials-get *">
</iframe>

The sandbox attribute is required and must include allow-forms allow-scripts allow-same-origin at minimum. The allow="publickey-credentials-get" permission is needed for passkey-based authentication inside the Flow.

The hosting page's origin must be on the Application's CORS allowlist or the browser will block the iframe's API calls — see §2.5.

Receiving events

The iframe broadcasts events on the parent window — completion, cancellation, resize, ready. The handler shape is the same one the JavaScript SDK uses internally; the JavaScript SDK reference documents the full event vocabulary (look for "Handle Consent Events"). Always verify event.origin === "https://overturo.com" before processing — the postMessage you receive is your prompt to verify the consent token server-side, not your proof of consent.

5. JavaScript SDK

For everything beyond a static embed — function callbacks, popup mode, programmatic Flow IDs, dynamic configuration — install @overturo/js and call overturo.consent({ flowId, container, onComplete }). The SDK handles session creation, iframe lifecycle, postMessage routing, and origin validation for you.

Three things the SDK gives you that the raw iframe doesn't:

• Popup mode. overturo.popup(...) opens the Flow in a separate window and posts the result back when the user finishes — useful when iframe sizing is awkward.
• Function callbacks. onComplete, onCancel, onError, onResize, onStep — typed callbacks instead of message-event dispatch.
• Typed errors. OverturoApiError exposes statusCode and the response body — easier to branch on than a generic fetch failure.

The hosting page's origin must be on the Application's CORS allowlist or every SDK call from the browser will fail preflight — see §2.5.

Full reference: JavaScript SDK — installation, complete examples, and error handling.

6. Per-Flow snippets

Each Flow has its own Embed tab in the Consent surface that generates copy-paste-ready snippets pre-baked with the Flow's actual URL, publishable key, and any sandbox / postMessage configuration you've set on the Flow. The snippets there are the same shapes documented above; the difference is they have your real values filled in.

The per-Flow Embed tab also lets you configure things this developer-portal page intentionally doesn't cover — sandbox flag tuning, allowed parent origins for postMessage, embed styling, session-token issuance, and embed analytics. Those are operational concerns scoped to a specific Flow; this tab is the conceptual reference for what's possible across all Flows.

Delivery modes

The per-Flow Embed tab generates two HTML-shape snippets, and popup is an SDK-managed shape:

• redirect — same shape as §3 above, with your Flow's URL filled in.
• iframe — same shape as §4 above, with your Flow's URL and any sandbox-flag overrides you've set.
• popup — SDK-managed (window.open, postMessage, focus restoration), not a static HTML snippet. Use the JavaScript SDK's overturo.popup(...) method.

How to find the per-Flow Embed tab: Consent surface → open your Flow → Embed tab. Available once the Flow is active.

Or: start from the Application instead of the Flow

This per-Flow Embed tab generates snippets for one Flow across any host. There is a complementary per-Application configurator that generates snippets for one Application across any of its Flows — useful when several Flows live under the same Application and you want the publishable key already filled in.

How to find it: Connect surface → open your Application → Integration tab. The tab includes a Flow picker, three runnable integration patterns (embed / popup / redirect), and an Authentication-only section for the standards-OAuth path (see the gate at the top of this page).

The signing decision kind

Cross-border signing is delivered as a third Decision kind — signature_request — alongside consent and approval. The kind is inferred server-side from the session token, so the <overturo-decision> markup is unchanged: you mount it exactly as you do for consent.

A signing decision resolves to one of four outcomes — signed, declined, expired, countered — surfaced on the complete event and the matching signature.* webhooks. Signing decision state also carries the signer's home country (an ISO country code) and the signature assurance level.

Consent in your own forms

You keep your sign-up, lead, intake, booking or checkout form. Overturo becomes the consent system of record behind the checkbox: the versioned wording the person read, a signed receipt they hold, a withdrawal path that reaches your systems, and the audit evidence that demonstrates consent.

Four ways in

Want Overturo's page instead of your form? See Embedding.

Which flows can be captured

A flow can be captured when its consent needs nothing but a decision: no verification, data-collection or bank step, and a declared consent duration (what bounds how long the person's details are kept for a consent they never claimed an account for). A capture carries decisions and how they were presented, never collected data fields. The flow page's Records tab shows the verdict.

What a capture may attest

For every purpose the flow resolves, a capture states the decision and the presentation it was made under (shown ticked by default, mandatory). The same rules that govern Overturo's own decision screens apply here: a pre-ticked or mandatory box is never consent.

A purpose the flow does not resolve, or a missing consent purpose, is refused by name. Your terms-of-service acceptance is a contract purpose, not a consent checkbox.

1. Your own form

Newsletter, lead, checkout, promotion, loyalty, messaging and research opt-ins have ready-made flows under the Opt-ins solution; every one of them is capturable here.

<!-- Two scripts: the core and the field entry (loaded explicitly, never fetched behind your back) -->
<script src="https://overturo.com/sdk/v1/overturo.js"></script>
<script src="https://overturo.com/sdk/v1/overturo-field.js"></script>

<form id="signup-form" action="/signup" method="post">
  <input id="email" name="email" type="email" required>
  <!-- Overturo renders the consent control here: the published wording, shown unticked, in your form -->
  <overturo-consent-field name="consent" flow="flw_…" locale="en"
    appearance='{"fontFamily":"system","accent":"#2563eb","radius":"6px","density":"regular"}'></overturo-consent-field>
  <label><input name="terms" type="checkbox" required> I accept the terms</label>
  <button type="submit">Create account</button>
</form>

const overturo = new Overturo({ publishableKey: "pk_live_…" })

// The field is a form control: at submit it captures from its own frame and
// hands the capture token to your form (a hidden input and the element's value).
overturo.forms.attach({
  flowId: "flw_…",
  form: "#signup-form",
  field: "overturo-consent-field",          // the element inside the form (one per flow)
  subjectField: "#email",
  externalIdField: "#customer_id",          // optional: your own identifier
  onCaptured: (r) => console.log("capture token", r.token),
  onError: (e) => console.warn("capture failed; the form submitted anyway", e.message),
})

// Then, on your server, commit the token with your application credential —
// exactly as for the snippet. The receipt says the control was rendered by Overturo.

The snippet: your own control, captured at submit

At submit, before the form leaves the page, the snippet reads each mapped control (ticked or not, shown ticked by default or not, required or not), builds a sanitised snapshot (consent controls and labels kept, every other input value stripped) and posts one capture with your publishable key. It receives a capture token, writes it into a hidden input named overturo_capture_token, and lets the submission proceed. If Overturo is unreachable, the form still submits and the error event fires.

import { Overturo } from "@overturo/js"

const overturo = new Overturo({ publishableKey: "pk_live_…" })

// Your existing form keeps every input. Map each consent control to its purpose,
// name the email field, and let the snippet capture the decision at submit.
overturo.forms.attach({
  flowId: "flw_…",
  form: "#signup-form",
  map: { marketing: "#marketing_opt_in", analytics: "#analytics_opt_in" },
  subjectField: "#email",
  externalIdField: "#customer_id",            // optional: your own identifier
  labels: { marketing: "#marketing_label" },  // the label the person reads: its digest is attested (match / drift in the record)
  // wording: { marketing: "#marketing_label" }, // or: write the published wording into the label
  onCaptured: (r) => console.log("capture token", r.token, "wording", r.wordingVerdict),
  onError: (e) => console.warn("capture failed; the form submitted anyway", e.message),
})

Nothing is recorded until your server commits the token with your application credential. The commit binds the person by the email you supply, freezes the receipt, sends the receipt email (unless you suppress it) and fires your webhooks.

# The capture token came in with the form submission; commit it with your application credential.
curl -X POST "https://overturo.com/api/v1/decisions/$CAPTURE_TOKEN/authorize" \
  -H "Authorization: Bearer $OVERTURO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "subject": { "email": "[email protected]", "external_id": "crm-42" } }'

# Your form handler receives the hidden field overturo_capture_token with the submission.
client = Overturo::Client.new(api_key: ENV["OVERTURO_API_KEY"])

decision = client.consent.decisions.authorize(
  params[:overturo_capture_token],
  subject: {email: params[:email], external_id: current_customer.id},
  suppress_receipt: false
)
decision.status
decision.record_id  # the consent record; its receipt is at /api/v1/consent_receipts/{record_id}

An uncommitted capture expires after 24 hours and leaves no record. Name the labels the person reads (labels, purpose → selector) and the snippet attests a digest of each label's text with the capture, so the record says purpose by purpose whether your wording matched the wording published for the flow; or ask it to write the published wording into your labels (wording) so the two are the same by construction.

No server? Enable browser commit on the application (it requires allowed origins). The browser then commits in the same call and every such record carries a lower-assurance channel in its receipt.

2. Form platforms: TypeformBeta

A form hosted by Typeform cannot run the snippet and has no server to commit. Typeform's own signed submission webhook is the commit.

1. On the application's Forms tab, connect the form: its form id and the flow it answers. Overturo gives you a webhook URL and a secret (shown once). With a Typeform personal access token connected, Overturo installs the webhook on the form for you and reads the form definition.
2. Map the fields by reference: the email field; optionally a hidden field as your own identifier; one field per consent purpose (a yes/no or legal field, granted when true; or one choice of a multiple-choice, checkbox, dropdown or picture-choice field, granted when that choice is among the chosen); and one field per right-to-object purpose (the person must be able to object in the form, so it is mapped like a consent field).
3. A consent purpose mapped to a field the definition marks required is refused at mapping time; so is a decision mapped to a field that cannot carry one (a rating, a number, free text), and a choice field mapped without the reference of the choice that means yes. Without a token the required flag cannot be read, so you attest that the field is optional and the receipt records that it was attested rather than read.

Each submission: the signature is verified (the previous secret is honoured for a day after a rotation), the response token is the idempotency key (a retry returns the existing record), the mapped field's title is the attested wording, the submitted time is the capture time, and a mapped consent field with no answer is a decline. Typeform's "send test request" is answered as accepted and records nothing; the connection shows "test delivery received".

Alternatives. A Typeform that redirects on completion can hand off to the hosted flow with the email recalled; the person confirms the address on the hosted page. A server that receives Typeform's webhook can call the Record API below. Prefer the connector when you want the wording drift verdict and no server; prefer the redirect when the person should see Overturo's own screen; prefer the Record API when you already process submissions server-side.

3. Your server: the Record API and the import

One call records a consent your server captured: the flow, the subject reference (email and optionally your identifier), the per-purpose decisions with their presentation, the time you captured it, an optional digest of the notice text, and an idempotency key of your choosing. A later request for the same person and flow with changed decisions produces a new record and withdraws the purposes that moved from granted to declined, so your webhooks fire.

curl -X POST https://overturo.com/api/v1/consent_records \
  -H "Authorization: Bearer $OVERTURO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow_id": "flw_...",
    "subject": { "email": "[email protected]", "external_id": "crm-42" },
    "decisions": { "marketing": { "decision": "granted", "default_checked": false, "mandatory": false } },
    "captured_at": "2026-10-12T09:01:30Z",
    "idempotency_key": "signup-42"
  }'

client = Overturo::Client.new(api_key: ENV["OVERTURO_API_KEY"])

record = client.consent.consent_records.create(
  flow_id: "flw_...",
  subject: {email: "[email protected]", external_id: "crm-42"},
  decisions: {marketing: {decision: "granted", default_checked: false, mandatory: false}},
  captured_at: Time.now.utc.iso8601,
  idempotency_key: "signup-42"
)
record.status
record.purposes

import { OverturoConsentRecords } from "@overturo/sdk"

const records = new OverturoConsentRecords({ baseUrl: "https://overturo.com", apiToken: process.env.OVERTURO_API_KEY })

const { consent_record } = await records.create({
  flow_id: "flw_...",
  subject: { email: "[email protected]", external_id: "crm-42" },
  decisions: { marketing: { decision: "granted", default_checked: false, mandatory: false } },
  captured_at: new Date().toISOString(),
  idempotency_key: "signup-42",
})
console.log(consent_record.status, consent_record.purposes)

Historical consents are imported, not back-dated: each row keeps your original capture time as captured_at and the platform's time as recorded_at; the declared duration counts from your time; no receipt email goes out unless you ask; rows that break the rules above are refused by name. Run a dry run first.

# Dry run first: what would be recorded, what would be refused — nothing is written.
curl -X POST https://overturo.com/api/v1/consent_records/imports \
  -H "Authorization: Bearer $OVERTURO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow_id": "flw_...",
    "dry_run": true,
    "records": [
      { "subject": { "email": "[email protected]" },
        "decisions": { "marketing": { "decision": "granted" } },
        "captured_at": "2025-03-01T10:00:00Z",
        "idempotency_key": "crm-row-1" }
    ]
  }'
# Then read the outcome: GET /api/v1/consent_records/imports/{id}

What flows back

• The person receives the receipt with the wording as published, your organisation named, and the account offer; a person with an existing account sees the record among their decisions with a "This was not me" action.
• Your consent.granted, consent.revoked and consent.purpose_revoked webhooks carry the subject reference you supplied and the per-purpose outcome.
• With a connected mailing audience, every record event is written to the member's marketing permissions and tags, and the member carries a merge field with the person's own records link; put that merge tag where your unsubscribe link is. The person can withdraw one purpose, object, or agree again from there.
• The connection's inbound endpoint receives the audience's unsubscribe and permission-change events. A change is applied only after the member is read back from the audience, and only as a withdrawal: a subscription made in the mailing tool is never recorded as a consent — it is listed on the connection for you to resolve by capturing consent in your form. Changes made through the API are excluded from the subscription, so the two systems never echo each other.
• The status read answers for a subject reference as well as a person id:

# The per-purpose status for a person, by the reference you supplied (email or your identifier).
curl "https://overturo.com/api/v1/applications/$APPLICATION_ID/consent_status?subject[external_id]=crm-42" \
  -H "Authorization: Bearer $OVERTURO_API_TOKEN"

The flow page's Records tab lists every record with its channel, platform, attester, wording verdict and subject reference. Manage your forms, Typeform connections and settings on the application's Forms tab; the receipt vocabulary is documented under Receipts.