Graine AI
API referencePrivacy

Withdraw consent

Record that consent ended.

Record that consent ended. A phone number on the record goes 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/{record_id}/withdraw
/v2/consent-records/6728f0a1c3d4e5f6a7b8c9d0/withdraw

The Authorization access token

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/jsonOptional

withdrawn_atWithdrawn At | null

When; now when left out.

Path Parameters

record_id
Required
Record Id

The record's id.

Pattern: "^[A-Za-z0-9_-]{1,64}$"

Response Body

200

The record, masked.

id
Required
Id

The record's id.

subject
Required
Subject

Who it is about, masked.

purposePurpose | null

What they agreed to.

notice_versionNotice Version | null

Which notice.

mechanismMechanism | null

How they agreed.

given_atGiven At | null

When.

withdrawn_atWithdrawn At | null

When it ended; null while it stands.

active
Required
Active

True until it is withdrawn.

created_byCreated By | null

Who wrote the record.

created_atCreated 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.

404

1200 — no such resource in your organization. A resource belonging to another organization answers 404, never 403.

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/6728f0a1c3d4e5f6a7b8c9d0/withdraw" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "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

List your do-not-call numbers GET

Next

Write a consent record POST