Issue a consent request

A check only ever returns allow once a person has actually granted the cell. This guide obtains that grant. You issue a signed consent request, Agreely emails the recipient a secure deep link, and their approval produces a receipt and activates the cell.

You need an issue-scoped key, a verified company domain (the request is signed by your company DID, which only resolves once your domain is verified), and a published form in the company app, under Information and consent > Forms.

#Issue the request

A request is always issued under a published form (a consent document): it asks for exactly the items that form discloses, so the signed offer can never diverge from the text the person reads. Pass either documentCode, the form's code (the server takes its current published version), or consentDocumentId, the id of one exact version; agreely documents list or GET /v1/consent-documents gives them. An items field is refused (422). The offer is signed on the server, with your company's Agreely-hosted signing key, and the email is sent after commit.

const r = await agreely.consentRequests.create({
  customerId: "cust_8812",
  recipientEmail: "[email protected]",
  // the published form: its code, or consentDocumentId for one exact version
  documentCode: "infolettre",
  validUntil: "2031-01-01",
}, { idempotencyKey: "order-4471" });

console.log(r.requestId);     // 0x... 64 hex, the public handle
console.log(r.deepLink);      // the recipient's secure approval link
console.log(r.emailDelivered);

$r = $agreely->consentRequests()->create([
    'customerId'     => 'cust_8812',
    'recipientEmail' => '[email protected]',
    'documentCode'   => 'infolettre',
    'validUntil'     => '2031-01-01',
], ['idempotencyKey' => 'order-4471']);

echo $r->requestId;       // 0x... 64 hex
echo $r->deepLink;        // the recipient's secure approval link
var_dump($r->emailDelivered);

agreely documents list --json   # find the code of the published form

agreely request create \
  --customer cust_8812 --to [email protected] \
  --document-code infolettre \
  --valid-until 2031-01-01 --idempotency-key order-4471 --json
# -> {"requestId":"0x...","status":"pending","deepLink":"...","emailDelivered":true,"items":[...],"document":{...}}

curl -sS https://api.agreely.ca/v1/consent-requests \
  -H "Authorization: Bearer $AGREELY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-4471" \
  -d '{
    "customerId": "cust_8812",
    "recipientEmail": "[email protected]",
    "documentCode": "infolettre",
    "validUntil": "2031-01-01"
  }'

The response is the IssuedRequest: requestId (the 0x-hex protocol handle), status: "pending", the deepLink, emailDelivered, the item labels, and the document (the code, name and version of the form the offer commits to).

#The fields

The API accepts customerId, recipientEmail, validUntil (the consent's end if approved: a plain date, meaning the end of that day in your company's timezone, or an instant with its offset, at most 10 years after the start) and documentCode or consentDocumentId. The offer's language follows your company's correspondence language.

To choose the recipient's language, or to declare a minor (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), issue the request from the company app, under Requests or from the customer dossier: those fields are offered there, not in the API.

#Track the request

const page = await agreely.consentRequests.list({ status: "pending" });
const one  = await agreely.consentRequests.get(r.requestId); // by the 0x handle

A request is pending until the recipient answers. If they do not answer within the 30-day window it lazily flips to expired. On approval it becomes approved, the cell's enforcement record goes active, and the very next check for that cell returns allow. The possible statuses are pending, approved, asks_declined (the person answered by declining every consent ask and only acknowledged the information lines), refused, expired, revoked_before_action, and erased (an approval whose consent was entirely erased).

To wait for settlement instead of polling by hand, use waitForSettlement (or agreely request wait on the CLI). It polls get until the request settles, then returns the final record.

const settled = await agreely.consentRequests.waitForSettlement(r.requestId, {
  intervalMs: 2000,   // default
  timeoutMs: 120000,  // default; a client-side timeout throws AgreelyTimeoutError, not an outage
});

#What the recipient does

The deep link opens the approval flow. A first-time recipient creates a citizen DID and a passkey; a returning one signs in. They review the exact (category, purpose) cells and approve with their passkey. That passkey assertion plus your company signature become the two proofs in the receipt.

#Next

• Verify a receipt.
• Record an offline consent when the recipient has no passkey.
• Gate the feature the consent unlocks.