Graine AI
API referencePrivacy

Add a number to your do-not-call list

Nothing is dialled to this number from now on, whichever way a call is placed: calls waiting for it are cancelled and never count as attempts or failures.

Nothing is dialled to this number from now on, whichever way a call is placed: calls waiting for it are cancelled and never count as attempts or failures. Calls the person makes to you are not affected. Idempotent.

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/do-not-call
/v2/do-not-call

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

phone
Required
Phone

The number, with its country code.

Minimum length: 1Maximum length: 64

reasonReason | null

Why, in a few words. Avoid personal details.

Maximum length: 200

Response Body

201

The entry.

id
Required
Id

The entry's id.

phone_maskedPhone Masked | null

The number, masked.

sourceSource | null

How it got here: manual, csv, api, erasure or opt_out.

reasonReason | null

Why, if you said.

added_byAdded By | null

Who added it: a member or a key.

created_atCreated At | null

When it was added.

created
Required
Created

False when the number was already on the list.

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/do-not-call" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+919812345678",
    "reason": "Asked not to be called"
  }'

The entry.

{
  "id": "6728f0a1c3d4e5f6a7b8c9d0",
  "phone_masked": "+91••••••5678",
  "source": "api",
  "reason": "Asked not to be called",
  "added_by": "member-live-1a2b",
  "created_at": "2026-11-03T10:15:00+00:00",
  "created": true
}

Previous

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

Next

Take a number off your do-not-call list DELETE