Make your first API call
Every Grappi API is paid and activated per account. These five steps take you from a new account to your first successful call.
- 1
Create your account
Sign up with your work email and confirm it with the six-digit code we email you.
- 2
Add money to your wallet
Calls are prepaid. Add money in Dashboard, Usage. Each call is charged to this wallet.
- 3
Subscribe to the APIs you need
In Dashboard, API access, subscribe to each API you plan to call. We switch each one on for your account after your payment.
- 4
Create an API key
In Dashboard, Apps & keys, create an app and then a key. The key is shown once: keep it in your server's secret store, never in browser or mobile code. You can also limit a key to your servers' IP addresses (see security).
- 5
Make your first call
Send the key as a Bearer token. Writes also accept an
Idempotency-Keyheader, so a retried request is not run twice.curl -X POST https://grappi.ai/v1/verify/passport \ -H "Authorization: Bearer $GRAPPI_API_KEY" \ -H "content-type: application/json" \ -d '{"file_number":"BO1065000012345","dob":"1990-08-17"}'A successful reply carries a
request_id, which you can quote to support, and the API's data inresult. The fields ofresultare listed on each API's reference page.{ "request_id": "req_...", "result": { ... } }
When a call is refused
Every refusal has the same shape: a stable code to branch on, a readable message and the request_id. The error reference lists every code.
| Status | Code | What it means | What to do |
|---|---|---|---|
| 403 | api_not_activated | This API is not activated for your account. | Subscribe to it in API access; we switch it on after your payment. |
| 402 | insufficient_balance | Your wallet cannot cover this call. | Add money in Usage, then retry. |
| 503 | api_unavailable | This API is not available right now. | Retry later. If it keeps happening, contact us. |
| 401 | invalid_api_key | The key is missing, wrong or revoked. | Check the key, or create a new one in Apps & keys. |
{
"error": {
"code": "api_not_activated",
"message": "This API is not switched on for your account yet. Subscribe to it in your dashboard and we switch it on for you after your payment.",
"request_id": "req_..."
}
}Requests
- One key works for every API activated on your account.
- Amounts in requests and replies are whole numbers in paise: 100 is one rupee.
- Writes accept an
Idempotency-Keyheader for safe retries.
Your account
- We switch on each API for your account after your payment.
- Calls are prepaid from your wallet; a call that fails on our side or at the data source is refunded. A "no record found" answer is charged.
- Every call is recorded in an insert-only, hash-chained audit log.