Bima Bima API Docs v1

Conventions

Rules shared by every Bima API endpoint: environments, request format, response envelope and data formats.

Environments

Environment Base URL Use
Productionhttps://api.bima.omLive customers and real policies
UAThttps://uatapi.bima.omIntegration 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 POST with a JSON body and Content-Type: application/json, including reads.
  • Every call except GetToken sends Authorization: Bearer <access_token>. See Authentication.
  • lang_code is en or ar; names, cover names and messages come back in that language.

Response envelope

Every endpoint answers with the same envelope:

Field Type Description
status_codestring"200" = success. Anything else is a business error (e.g. "600" Invalid request / offer not found), even when HTTP is 200
status_messagestringHuman-readable result or error, in lang_code
dataobject, array or nullThe result; null on most errors
messagesarrayExtra 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
MoneyOmani rial (OMR) with 3 decimals (baisa)57.666
Dates sentdd/MM/yyyy04/03/1985
Dates returnedd/M/yyyy h:mm:ss tt or d/M/yyyy3/4/1985 12:00:00 AM
Mobile numberDial code without + in country_code, number in national_no (Oman: exactly 8 digits; other countries up to 15)968 + 95542930
quotation_idLong encrypted string (also sent as refid); always URL-encode it in linksdldTUytwK0tReHpW...
quotation_noShort number shown to customers26100291362

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 takes quotation_id.
  • Reprocess responses have an empty request_data; keep the request data from the last Read.
  • Price to show is total_premium; other_amount is 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's qoutation_id.
  • customer.subscriber_code may hold only part of the number; use national_no.
  • Group offers can be is_valid_offer: false while their travellers' offers are valid.