Onboarding

Requires: A secret key with APP_ONBOARDING, called from your server.

A community's onboarding is a real gate: rules to accept, a tier to pick, a member-data form to fill. Before these endpoints the only place to pass it was Cobuntu's own pages, so an app either sent members out to a browser mid-signup or let them in ungated and quietly disagreed with the community about who had joined.

Use it to run the community's onboarding inside your own app.

What does this member still owe?

Endpoint: GET /members/{userId}/onboarding

Scope APP_ONBOARDING

The read returns content, not a checklist. It carries the rule text, the tiers, the form's fields and options for whichever step is outstanding, and nothing for the steps that are not. One call draws the whole gate.

That is deliberate: a bare status cannot be rendered, so four round trips to assemble one screen would get wrapped in a client library by every integrator, each slightly wrong.

Submit the member-data form

Endpoint: POST /members/{userId}/onboarding/data

Scope APP_ONBOARDING

{ "segmentId": "…", "answers": { "<fieldId>": "value" } }

Do not use POST /segments/:id/submit for this. It looks like the right endpoint and is not: it is WRITE_APPLICATIONS and records an application. Posting onboarding answers there returns a plausible 200, writes a row nobody reads, and leaves the member gated. Failing silently is the exact problem this endpoint exists to prevent.

Accept the rules

Endpoint: POST /members/{userId}/onboarding/rules

Scope APP_ONBOARDING

Records that this member accepted, with a snapshot of exactly the rules shown and the id of the app that made the claim.

The condition attached to this one. Recording consent is a claim about what a person was shown, not just a timestamp. An app calling this must actually render every rule and make every linked document reachable first. Each rule carries linkUrl and linkLabel for that reason.

Failure contracts are asymmetric, on purpose

The read fails open. Any error means the member goes through. Gating on a failure locks everybody out of your app to enforce a form.

The write fails closed, and says so. "Saved" when it was not is worse than an outage, because they never type it again.