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

    Create your account

    Sign up with your work email and confirm it with the six-digit code we email you.

  2. 2

    Add money to your wallet

    Calls are prepaid. Add money in Dashboard, Usage. Each call is charged to this wallet.

  3. 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. 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. 5

    Make your first call

    Send the key as a Bearer token. Writes also accept an Idempotency-Key header, 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 in result. The fields of result are 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.

StatusCodeWhat it meansWhat to do
403api_not_activatedThis API is not activated for your account.Subscribe to it in API access; we switch it on after your payment.
402insufficient_balanceYour wallet cannot cover this call.Add money in Usage, then retry.
503api_unavailableThis API is not available right now.Retry later. If it keeps happening, contact us.
401invalid_api_keyThe 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-Key header 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.