FAQs
Find answers to the most common developer questions when integrating with the ClearGrid API.
Authentication & Tokens
Q: How do I get my lender ID? Your lender ID is provided by ClearGrid during onboarding. It is a unique identifier for your institution and is required in login and account creation requests.
Q: What happens if my access token expires?
Access tokens are short-lived for security reasons. When expired, use your refreshToken with the Refresh Token API to get a new token. Example:
POST https://core-dev.cleargrid.ae/api/v1/auth/{lender}/refresh-token
{
"refreshToken": "<your_refresh_token>"
}Response:
{ "token": "<new_access_token>" }Q: Can I store the refresh token permanently? Store the refresh token securely (e.g., in an encrypted database). Never hard-code it in applications. If compromised, contact ClearGrid to revoke and issue new credentials.
Usage & Development
Q: Should I test in production? No. Always test integrations in the dev environment first:
Core APIs → https://core-dev.cleargrid.ae/api/v1
Job APIs → https://job-dev.cleargrid.ae/api/v1
Only switch to production (core-prod / job-prod) once tested successfully.
Q: Do I need to send all sub-accounts every time? No. The API supports incremental updates. You can:
Add new sub-accounts anytime
Update existing ones (e.g., update due date or fees)
Withdraw/cancel a sub-account
The main accountId aggregates update automatically.
Q: What date format should I use? All dates must be in dd/MM/yyyy format. Example: "15/08/2025" for 15th August 2025.
Incorrect formats like "2025-08-15" will be rejected with a 400 Bad Request.
Q: What languages are supported? Currently:
en → English
ar → Arabic
Pass the language code in the language field of the account request.
API Behavior
Q: What is the meaning of status in the Accounts API?
1 → Create a new account/sub-account
2 → Update an existing account/sub-account
3 → Withdraw or cancel a sub-account
Example: To update a fee on an existing sub-account, send the same accountId + subAccountId with status = 2.
Q: What loan types are supported? Supported loan types (via loanType field):
Credit Card
Lease
Personal Loan
BNPL (Buy Now Pay Later)
Car Rental
Subscription
Charge Back
Salary Advance Loan
Q: How are errors reported? Errors are returned in a standard JSON structure. Example:
{
"code": 400,
"errors": [
{
"accountId": "acc123",
"errors": ["Invalid date format", "Missing principal amount"]
}
]
}Limits & Performance
Q: Is there a rate limit on the APIs? Yes.
Authentication: 5 requests/minute per lender
Accounts API: 10 requests/minute per lender, with a maximum of 50 accounts per request body.
Exceeding this returns a 429 Too Many Requests.
Q: How quickly are account updates processed? API requests return a 200 Accepted response immediately after validation. Actual account ingestion and processing happens asynchronously in the background. Most requests complete within a few seconds.
Q: What happens if I send duplicate accountIds? Duplicate accountId submissions with the same data are ignored. If fields differ, the latest update overwrites previous values.
Security
Q: How should I secure API credentials?
Never expose credentials or tokens in client-side code.
Store them in a secure vault or encrypted configuration store.
Rotate tokens regularly using the refresh flow.
Q: Can I revoke a refresh token if it is compromised? Yes. Contact ClearGrid support immediately to revoke the compromised token and issue a new one.
Last updated