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 and a verified company domain (the request is signed by your company DID, which only resolves once your domain is verified).

#Issue the request

items are catalog entry ids and/or raw {category, purpose} pairs, resolved server-side to your declared active catalog entries. The offer is signed on the backend (your signing key never leaves it) and the email is sent after commit.

const r = await agreely.consentRequests.create({
  customerId: "cust_8812",
  recipientEmail: "[email protected]",
  // catalog entry ids AND/OR raw {category, purpose} pairs:
  items: ["<catalogEntryId>", { category: "Email address", purpose: "Newsletter" }],
  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]',
    'items'          => ['<catalogEntryId>', ['category' => 'Email address', 'purpose' => 'Newsletter']],
    '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 request create \
  --customer cust_8812 --to [email protected] \
  --item "Email address:Newsletter" --item <catalogEntryId> \
  --valid-until 2031-01-01 --idempotency-key order-4471 --json
# -> {"requestId":"0x...","status":"pending","deepLink":"...","emailDelivered":true,"items":[...]}

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]",
    "items": ["<catalogEntryId>", {"category":"Email address","purpose":"Newsletter"}],
    "validUntil": "2031-01-01"
  }'

The response is the IssuedRequest: requestId (the 0x-hex protocol handle), status: "pending", the deepLink, emailDelivered, and the item labels.

#Optional fields

Beyond customerId, recipientEmail, items, and validUntil (past that date the offer expires), a request accepts two optional inputs:

• the recipient language (French or English), so the offer is presented in their language;
• the minor fields (article 4.1): an "is a minor" flag, parental consent, and by whom it is given.

The interactive /v1 reference gives the exact field names and their constraints.

#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. A settled request is one of pending, approved, refused, expired, or revoked_before_action.

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.