Skip to main content
All Numero API responses follow a consistent format, making it easy to handle both successful and failed requests.

​
Standard response format

Every API response is wrapped in the following structure: 
{
  "status": true,
  "message": "Successful",
  "code": "200",
  "version": "v1",
  "reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": { },
  "error": null
}
FieldTypeDescription
statusbooleantrue if the request was successful, false otherwise
messagestringA human-readable description of the result
codestringThe response code (e.g., "200", "400", "403")
versionstringThe API version
referencestringA unique reference for the request, useful for support queries
dataobjectThe response payload — varies per endpoint
errorobject | nullError details when status is false

​
Error response format

When a request fails, status is false and the error object contains details: 
{
  "status": false,
  "message": "Unsuccessful",
  "code": "400",
  "version": "v1",
  "reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": null,
  "error": {
    "message": "Invalid account number"
  }
}

​
Common error codes

CodeMeaningDescription
200SuccessRequest completed successfully
400Bad RequestThe request was invalid — check the error.message for details
403ForbiddenAuthentication failed, insufficient permissions, or IP not whitelisted
500Server ErrorSomething went wrong on our end — contact support if the issue persists

​
Handling errors

  • Always check the status field to determine if the request was successful
  • Use the error.message field for user-facing error messages or debugging
  • Include the reference value when contacting support — it helps us trace the request
  • All endpoints return HTTP 200 at the transport level; the business-level status is indicated by the status and code fields in the response body

​
Pagination

Endpoints that return lists support pagination via query parameters:
ParameterTypeDefaultDescription
pageNumberinteger1The page to retrieve
pageSizeinteger50Number of records per page
Paginated responses include: 
{
  "data": {
    "items": [ ... ],
    "pageNumber": 1,
    "pageSize": 50,
    "totalCount": 150
  }
}