Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.business.blaaiz.com/llms.txt

Use this file to discover all available pages before exploring further.

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, including review of the Certificate of Incorporation and related business documentation. This longer timeline is standard and expected. 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 a 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. To summarise: wait for the webhook, do not escalate before 2 hours, and only reach out to the operations team if the verification has been pending for 5 hours or longer.

​
Accepted identity documents

  • Individual customers: Only a Driver’s License (drivers_license), Passport (passport), or Resident Permit (resident_permit) is accepted.
  • Business customers: Only a Certificate of Incorporation (certificate_of_incorporation) is accepted.
  • 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.