Bima Bima API Docs v1

Get Started

Learn how the Bima APIs fit together, from the first token to an issued policy.

Before you start

  • API account: contact it@bima.om to get your API credentials.
  • Environments: build against UAT (https://uatapi.bima.om) and switch to production (https://api.bima.om) when you go live. See Conventions.
  • Request format: every call is POST with a JSON body, and every response uses the same response envelope.

End-to-end flow

The complete process of purchasing any product is divided into the same nine steps. While the overall workflow remains the same for all products, the Create Quotation and Submit bodies vary based on the specific requirements of each product, and some products add a step before Submit.

  1. 1
    Get a token
    Request a bearer token and send it on every other call. Load the lookups you need (countries, nationalities, titles…) before building the quote.
  2. 2
    Create the quotation
    Send the product's request (request_type_code) with the customer and the subject insured. The body differs per product; the response gives the quotation_id.
    Edit a quote: call Create again with the changed data; a new quotation is created
  3. 3
    Read offers until Quoted
    Poll while the status is Awaiting or Processing and show offers as they arrive. Process regenerates all offers when needed.
  4. 4
    Add or remove optional covers Optional · repeat per change
    Save the optional covers of one offer; the offer comes back priced again.
  5. 5
    Customer picks an offer
    Use insurance_type_code to open the right details form. Read the offer's questions if it has any. Offers that need insurer approval go to follow-up instead of payment.
  6. 6
    Submit the chosen offer
    Lock the offer and save the policy holder's details, answers and documents. The status becomes Submitted.
    Before Submit (when documents are needed, e.g. Motor): Quotation/RequiredDocuments Before Submit (Travel): Quotation/UpdateInsurers
  7. 7
    Review the amount to pay
    Returns only the chosen offer and the final payment amounts.
  8. 8
    Finalize and open payment
    Freeze the quote and send the customer to the payment page. Partners that collect payment themselves confirm the purchase instead.
    Own payment gateway: Quotation/Confirmation
  9. 9
    Verify payment, issue policy
    Confirm the gateway result, issue the policy, then track the request to download the policy documents.
Key step Optional step Product-specific or alternative call

Choosing the next page after an offer is picked

After the customer picks an offer (step 5), use the quotation's insurance_type_code to decide which details form to show before Submit:

Product insurance_type_code Before Submit
Motor MOTOR_THIRD_PARTY MOTOR_COMPREHENSIVE Owner's name as on the Mulkiya and the required documents
Travel TRAVEL_OUTBOUND TRAVEL_INBOUND Each traveller's name, passport and gender (UpdateInsurers)
Domestic, Home, Credit Life, Malpractice See the product page Product data, question answers and documents in the Submit body
Detailed flow diagram including offer questions diagram
Bima APIs process flow with offer questions
Process flow with offer questions

Quick start

  1. Authenticate: get a token and send it as Authorization: Bearer <access_token>.
  2. Load lookups: countries, nationalities, titles, genders and relations.
  3. Pick a product: follow its page to create and submit the quotation.
  4. Work with offers: read, re-price and choose an offer.
  5. Take payment: review, pay, verify and issue the policy.