Skip to main content
Before integrating with the Blaaiz Platform API, review the following guidelines to ensure a smooth and reliable development experience.

​
Using the Blaaiz Platform API

​
Authentication

  • All external API requests must be authenticated using a valid Bearer access token.
  • Generate OAuth credentials from the Blaaiz Dashboard after API Services have been enabled for your account.
  • Exchange those credentials at /oauth/token using grant_type=client_credentials.
  • Request the token with the scopes assigned to your credentials (e.g. wallet:read payout:create). See Authentication — Scopes.
  • Include Authorization: Bearer <access_token> in every external API request.
  • Keep your OAuth client_secret secure and never expose it in client-side code or public repositories.
  • Development and production use different OAuth credentials. Always use the credentials from the same environment as the base URL you are calling.
  • If you cannot see the API & Webhooks page in the dashboard, your account has not been provisioned for API Services yet. See Authentication and Getting Started.
  • Legacy API key creation is disabled. If you still use a legacy API key integration with x-blaaiz-api-key, migrate to OAuth immediately.

​
Customer update rules

  • Only NON-VERIFIED customer details can be fully updated.
  • If a customer is VERIFIED, only fields that are currently null can be updated.
  • The customer’s country must match the identity document provided for KYC.
  • If you need to correct data on a verified customer (wrong document, misspelled name, incorrect details), this cannot be done through the API. You must request a manual correction from the operations team. See Customer data corrections for the full process.

​
Verification timeline

Customer verification is not instant. When you upload identity documents for a customer, those documents enter a review process. The customer’s status will remain PENDING until that review is complete, at which point you will receive either a customer.verified or customer.rejected webhook. For individual customers, the review completes within a few minutes in the majority of cases. In rare cases, documents may need an extra level of checks and screening — for example, if the document triggers additional compliance checks. When this happens, the review can take up to 2 hours. This is expected behaviour and is not a sign that anything has gone wrong. For business customers, verification typically takes 1–5 business days. Business verification involves additional compliance checks against company registries, beneficial-ownership records, and risk databases. This longer timeline is standard and expected. Business customers go through the dedicated KYB flow — beneficial owners and KYB documents — not the legacy /files endpoint. For individual customers, do not raise support tickets or enquiries for verifications that have been pending for less than 2 hours. Such requests will not be attended to, as the review is still within its normal processing window. If an individual customer’s verification has been pending for 5 hours or more, that is a clear signal that something may have gone wrong on our end. At that point — and only at that point — you should contact the operations team at support@blaaiz.com to have the situation investigated and expedited. For business customers, the equivalent escalation threshold is 5 business days. Do not raise tickets within the 1–5 business day window. Wait for the customer.status_changed webhook. To summarise: wait for the webhook. For individuals, do not escalate before 2 hours and only reach out if pending for 5 hours or more. For businesses, only escalate if a customer has been in PROCESSING for more than 5 business days.

​
Accepted identity documents

  • Individual customers: id_type is required and must be Driver’s License (drivers_license), Passport (passport), or Resident Permit (resident_permit). The matching document file is uploaded via the legacy File API.
  • Business customers: id_type and id_number are prohibited at the customer level — sending either returns 422. Businesses identify via registration_number + incorporation_country. The certificate of incorporation goes into the KYB document collection with type=CERTIFICATE_OF_INCORPORATION, not through the File API.
  • ID cards (National Identity Cards) are not accepted. No other identity document types are supported. National ID cards and any other document types will be rejected.

​
Document quality requirements

  • All uploaded documents must be clear, legible, and authentic. Blurry, cropped, obscured, or otherwise unclear images will not be reviewed and will be rejected.
  • Fraudulent or falsified documents will not be tolerated. If a customer submits false, forged, or manipulated documents, the submission will be rejected immediately. Repeated attempts to submit fraudulent or invalid documents will result in the customer being permanently blacklisted from the platform.
  • There are no exceptions or compromises on document quality or authenticity.

​
TIN and identification labels

  • If you need to collect a tin, do not hardcode the label shown to your users.
  • Get the correct label or field from the Get identification type endpoint.

​
Collection method note

  • For the API collection endpoint, the currently documented method is card.
  • Do not describe any additional collection methods in the public docs unless they are explicitly documented and supported.

​
Rate Limits & Usage

  • To ensure fair usage and maintain platform stability, the Blaaiz API enforces rate and usage limits.
  • Requests exceeding these limits may be throttled or temporarily blocked.
  • If you anticipate high request volumes, contact Blaaiz support@blaaiz.com to discuss your use case.

​
Response Format

  • All API responses are returned in JSON format.
  • Successful responses include the requested data.
  • Error responses include a descriptive message field to help you understand and resolve the issue.
Example error response: 
{
  "message": "Invalid or missing access token"
}

​
Best Practices

  • Handle errors gracefully by checking HTTP status codes and error messages.
  • Log API responses during development to aid debugging.
  • Always test integrations in a safe environment before going live.