Graine AI
API referencePrivacy

Add many numbers to your do-not-call list

Numbers as a list, or a CSV as text.

Numbers as a list, or a CSV as text. A number already on the list is left as it is.

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

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

numbersNumbers | null

Numbers, with their country codes (at most 10,000).

csvCsv | null

A CSV as text instead: one number per row, in a column named phone, number, phone_number or mobile_number when there is a header, else the first column.

Response Body

200

What happened to each.

added
Required
Added

Numbers newly on the list.

already_listed
Required
Already Listed

Numbers that were on it already.

rejected
Required
Rejected

Rows that are not phone numbers.

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/bulk" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "numbers": [
      "+919812345678",
      "+919898765432"
    ],
    "csv": "phone\n+919812345678\n"
  }'

What happened to each.

{
  "added": 2,
  "already_listed": 0,
  "rejected": 0
}

Previous

Write a consent record POST

Next

Add a number to your do-not-call list POST