Conventions
Rules shared by every Bima API endpoint: environments, request format, response envelope and data formats.
Environments
| Environment | Base URL | Use |
|---|---|---|
| Production | https://api.bima.om | Live customers and real policies |
| UAT | https://uatapi.bima.om | Integration and testing |
Endpoint paths in these docs are relative to the base URL, e.g. https://uatapi.bima.om/v1/Quotation/Read.
Request format
- Every call is
POSTwith a JSON body andContent-Type: application/json, including reads. - Every call except GetToken sends
Authorization: Bearer <access_token>. See Authentication. lang_codeisenorar; names, cover names and messages come back in that language.
Response envelope
Every endpoint answers with the same envelope:
| Field | Type | Description |
|---|---|---|
| status_code | string | "200" = success. Anything else is a business error (e.g. "600" Invalid request / offer not found), even when HTTP is 200 |
| status_message | string | Human-readable result or error, in lang_code |
| data | object, array or null | The result; null on most errors |
| messages | array | Extra messages, strings or { message / text / title } objects; show them to the customer |
{
"status_code": "200",
"status_message": "Quotation retrieved successfully",
"data": { },
"messages": []
}
HTTP 200 does not mean success
status_code is a string. Always check status_code === "200" before reading data.
See API error codes.
Data formats
| Data | Format | Example |
|---|---|---|
| Money | Omani rial (OMR) with 3 decimals (baisa) | 57.666 |
| Dates sent | dd/MM/yyyy | 04/03/1985 |
| Dates returned | d/M/yyyy h:mm:ss tt or d/M/yyyy | 3/4/1985 12:00:00 AM |
| Mobile number | Dial code without + in country_code, number in national_no (Oman: exactly 8 digits; other countries up to 15) | 968 + 95542930 |
| quotation_id | Long encrypted string (also sent as refid); always URL-encode it in links | dldTUytwK0tReHpW... |
| quotation_no | Short number shown to customers | 26100291362 |
Known quirks
Confirmed behaviour worth knowing before you integrate:
- Id types differ per call: ids in Reprocess are strings (
"cover_id": "9"); in RequiredDocuments the offer ids are numbers ("offer_id": 102328). - refid vs quotation_id: RequiredDocuments and Track take
refid; every other quotation call takesquotation_id. - Reprocess responses have an empty
request_data; keep the request data from the last Read. - Price to show is
total_premium;other_amountis only the sum of selected optional covers. - Insured amounts (
insured_amount) carry their own currency (often$on travel); premiums are always OMR. - Field names with typos are real and must be used as written:
previous_uplodeds,insurers_coverd_count,quotation_expire_Date, VerifyTransaction'sqoutation_id. customer.subscriber_codemay hold only part of the number; usenational_no.- Group offers can be
is_valid_offer: falsewhile their travellers' offers are valid.