API referencePrivacy

Write a consent record

Keep the evidence of one person's consent beside the calls it covers.

Keep the evidence of one person's consent beside the calls it covers. A record that says consent was already withdrawn puts its phone number on your do-not-call list.

Rate limit: 2000 requests per minute per organization, counted together with every endpoint that has no stricter limit of its own. Exceeding it returns 429 with Retry-After; the X-RateLimit-* response headers report your remaining allowance on every call.

POST

/v2/consent-records

Authorization

`Authorization`
Required
Bearer <token>

Your Graine API key. Create one in the dashboard under Developers, or via POST /v2/api-keys. Send it as Authorization: Bearer <key>.

In: header

Request Body

application/jsonRequired

`subject`
Required
Subject

Who gave it: at least one of phone, email or user_key.

`purpose`
Required
Purpose

What they agreed to.

Maximum length: 200

`notice_version`
Required
Notice Version

Which version of your notice they saw.

Maximum length: 64

`mechanism`
Required
Mechanism

How they agreed.

Maximum length: 64

`given_at`
Required
Given At

When, with a timezone offset.

`withdrawn_at`Withdrawn At | null

When they withdrew it, if they have.

Response Body

201

The record, masked.

`id`
Required
Id

The record's id.

`subject`
Required
Subject

Who it is about, masked.

`purpose`Purpose | null

What they agreed to.

`notice_version`Notice Version | null

Which notice.

`mechanism`Mechanism | null

How they agreed.

`given_at`Given At | null

When.

`withdrawn_at`Withdrawn At | null

When it ended; null while it stands.

`active`
Required
Active

True until it is withdrawn.

`created_by`Created By | null

Who wrote the record.

`created_at`Created At | null

When it was written.

400

1000 — malformed or contradictory input. 1002 — a required parameter is missing.

`error`
Required
Error

Stable integer code from the /v2 error table. Branch on this.

`message`
Required
Message

One human-readable sentence. Wording may change; the code will not.

401

1100 — missing, unknown or inactive API key. 1101 — a browser session token was presented instead of an API key.

`error`
Required
Error

Stable integer code from the /v2 error table. Branch on this.

`message`
Required
Message

One human-readable sentence. Wording may change; the code will not.

403

1102 — the key is valid but lacks the scope this endpoint requires, or names another organization. GET /v2/scopes reports what a key holds.

`error`
Required
Error

Stable integer code from the /v2 error table. Branch on this.

`message`
Required
Message

One human-readable sentence. Wording may change; the code will not.

422

1001 — the body or query failed validation; the message names the first offending field.

`error`
Required
integer

Stable integer code from the error table. Branch on this, not on the message.

`message`
Required
string

One human-readable sentence. Wording may change; the code will not.

429

1300 — the per-organization request rate or concurrent-call limit was reached. Carries Retry-After.

`error`
Required
Error

Stable integer code from the /v2 error table. Branch on this.

`message`
Required
Message

One human-readable sentence. Wording may change; the code will not.

503

1501 — a service this endpoint depends on is unreachable or returned a 5xx.

`error`
Required
Error

Stable integer code from the /v2 error table. Branch on this.

`message`
Required
Message

One human-readable sentence. Wording may change; the code will not.

curl -X POST "https://api.graine.ai/v2/consent-records" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "phone": "+919812345678",
      "email": "person@example.com",
      "user_key": "u1_abcdefghijklmnopqrstuvwxyz"
    },
    "purpose": "Service reminders by phone",
    "notice_version": "2026-10",
    "mechanism": "web_form",
    "given_at": "2026-11-01T09:30:00+05:30",
    "withdrawn_at": "2026-11-02T18:00:00+05:30"
  }'

The record, masked.

{
  "id": "6728f0a1c3d4e5f6a7b8c9d0",
  "subject": {
    "phone_masked": "+91••••••5678",
    "email_masked": "p•••@example.com",
    "has_user_key": false
  },
  "purpose": "Service reminders by phone",
  "notice_version": "2026-10",
  "mechanism": "web_form",
  "given_at": "2026-11-01T04:00:00+00:00",
  "withdrawn_at": "2026-11-02T12:30:00+00:00",
  "active": true,
  "created_by": "key_1a2b3c",
  "created_at": "2026-11-03T10:15:00+00:00"
}

Previous

Withdraw consent POST

Next

Add many numbers to your do-not-call list POST