Agreely Docs
FR EN

Consent requests

A consent request is a signed offer, made to one customer, under a published form that groups catalog cells. You issue it from Information and consent > Requests, or from the customer's dossier. It is delivered as a secure deep link (and sent by email) that the person concerned opens to review the offer and consent with a passkey in the Citizen portal.

What a request carries

  • The form: the published version of the consent document, whose catalog cells are the items the offer targets.
  • The company's customer id (customer_id): your own id for this customer, never a citizen's decentralized identifier.
  • The recipient email: where the link is sent.
  • The valid-until date (valid-until): past it, the offer expires.
  • The recipient language: French or English, so the offer is presented in the person's language. It defaults to the company's correspondence language.
  • The minor fields (P-39.1 s. 4.1; A-2.1 s. 64.1): an "is a minor" flag, parental consent, and by whom it is given.

Issuing conditions

Issuing a request requires a verified domain and an active signing key. The reason is direct: an offer is signed on behalf of the company, so that it is independently verifiable. Without a did:web identity minted by domain verification and without an active signing key, there is nothing to sign the offer with, and issuing is blocked.

Domain verification comes first

If issuing is blocked, the most common cause is an unverified domain or the absence of an active signing key. See Domain and branding to verify the domain and manage keys.

The lifecycle

A request moves through a precise status set (displayed label, then API value):

  • Pending (pending): issued, awaiting the person's response.
  • Approved (approved): the person concerned consented.
  • Refused (refused): the person concerned declined.
  • Expired (expired): the valid-until date passed with no response.
  • Withdrawn (revoked_before_action): the company cancelled the offer before the person acted.

An approved request produces the consent in effect for the targeted cells; that status is what a verification then reads, as described in Core concepts.

Issuing via the API

The same request can be issued via the /v1 API: POST /v1/consent-requests, under the issue scope. The form is named by its id or its code, and it determines the items. Issuing accepts an idempotency key, so that a replayed send does not create a duplicate offer. GET /v1/consent-requests and POST /v1/consent-requests/{id}/cancel list and cancel them. This is the preferred path for issuing in bulk or embedding issuance in your own flows.

See the API reference for the full contract, along with the TypeScript SDK, the PHP SDK, and the CLI to issue from your code or your terminal.

Not every person concerned has a passkey. For the no-passkey case (for example an elderly person who signs on paper), there is a separate path: offline, company-attested consent. The person concerned holds a hand-signed PDF, and the company records that consent from the customer's dossier (Record a consent already obtained) or through the API (POST /v1/manual-consents, attest scope). The dossier also offers recording a verbal consent, followed by its paper sheet.

A separate path, not a shortcut

Attested consent carries no passkey assertion from the person concerned: it is the company attesting that it collected a paper consent. It is a legitimate path for no-passkey cases, distinct from the signed offer the person approves themselves. Through the API it requires the attest scope; in every case, a retained supporting document.

See the Citizen portal and the offline consent guide for the full path on the person's side.

Next