# Data Types Source: https://docs.yasmina.ai/api-resources/data All Yasmina API responses are in JSON format. Responses with code 204 will not have a body. Below is the common data types that we use throughout our API | Data Type | Format / Description | | --------------------- | --------------------------------------------------------------------------- | | Datetime | ISO 8601 format, e.g., `2025-08-05T13:30:00Z` | | Date | ISO 8601 date format, e.g., `2025-08-05` | | Country | ISO 3166-1 alpha-2 code, e.g., `SA` | | Client ID | UUID format, e.g., `123e4567-e89b-12d3-a456-426614174000` | | Client Secret | A random string. This will be hashed in our databases for enhanced security | | ID | Yasmina internal identifier, this will be an integer | | Provider Policy ID | Policy ID that is provided by Insurance company | | Provider Policy | A file URL (Usually in PDF) | | Cancellation Document | A file URL (Usually in PDF) | # Errors Source: https://docs.yasmina.ai/api-resources/errors Every error the API can return and what each one means. Every error is a JSON body with the same shape, whatever `Accept` header you send. The HTTP status tells you the kind of problem, the `code` tells you the exact case, and the `message` is written to be shown to the customer. ## The error response ```json theme={null} { "code": "40012", "message": "OTP is invalid or expired." } ``` | Field | Present | Description | | --------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | Always | A string of five digits. The first three are the HTTP status, the last two tell apart the cases that share a status: `40012` is the twelfth kind of `400`. Branch on this, never on `message`. | | `message` | Always | What went wrong, in words a customer can read. Sent in English, or in Arabic when the request carries `Accept-Language: ar`. Messages an insurance provider wrote are passed on as received. Wording may change. | | `details` | `42201` only | Field validation errors: each key is the field, each value a list of messages for it. | | `retry_after_seconds` | `429` only | How long to wait before trying again. The same value is in the `Retry-After` header. | A `2xx` response never carries a `code`, and `204` responses have no body at all. ## Common Yasmina errors Any endpoint can answer with these. | Code | Status | Message | When | | ------- | ------ | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `40101` | 401 | Unauthenticated | No `Authorization` header, an expired or revoked token, or a token sent without the `Bearer` scheme. On `POST /oauth/token` the message is `Wrong credentials`: the client id or secret is wrong, or the secret was regenerated. On the iframe's `/car-comp/embed/*` routes the message is `This embed session is not valid any more.`: the session token is unknown or has expired. | | `40301` | 403 | Unauthorized | The token is valid but the product is not enabled on your account, or the account is not approved yet. | | `40401` | 404 | Model not found | The record whose id is in the URL does not exist or belongs to another client. On the iframe's `/car-comp/embed/*` routes the message is `This embed session is not for that quote request.`. | | `40402` | 404 | The route … could not be found. | No such endpoint. | | `40501` | 405 | Method not allowed | The endpoint exists, but not for this HTTP method. | | `42201` | 422 | *the first failing field's message* | A field is missing, malformed, or fails a rule. `details` lists every failing field with its messages. The only 422 the API returns. | | `40000` | 400 | *varies* | Rejected for a reason that has no code of its own yet. | | `42901` | 429 | Too many requests. Please wait 37 seconds and try again. | Rate limited. `retry_after_seconds` says for how long; see [Rate limiting](/api-resources/rate). | | `50001` | 500 | We’re experiencing a temporary server issue. Please try again shortly. | Something failed on Yasmina's side, including an insurer that did not answer in time. | | `50401` | 504 | Gateway error | An insurer could not be reached. | ### Policy cancellation `POST /clients/policies/cancellation` and every product's `POST …/policies/{id}/cancellation` share these. | Code | Status | Message | When | | ------- | ------ | ------------------------------------------- | ----------------------------------------------------------- | | `40401` | 404 | Policy not found | No active policy matches the VIN or id, or it is not yours. | | `40010` | 400 | Policy is already canceled | It was cancelled, or a cancellation is already pending. | | `40017` | 400 | This policy can't be canceled at the moment | The insurer has not issued the policy document yet. | ## Motor insurance (price comparison) | Endpoint | Code | Status | Message | When | | ------------------------------------------------ | ------- | ------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `POST /car-comp/quote-otp` | `42902` | 429 | Verification code was requested recently, try again in 2:41. | One OTP per phone number every three minutes on this endpoint. `retry_after_seconds` says how long; the OTP already sent stays valid. | | | `40005` | 400 | The mobile number does not match the owner ID. Please review both details and try again. | The insurer's identity check found the phone registered to someone else. | | | `40006` | 400 | This mobile number is already in use with another National ID *(or)* another Iqama ID | The phone is already tied to a different id at the insurer. | | | `40016` | 400 | *Request errors coming directly from insurance provider* | A refusal we have no wording of our own for, passed on in the provider's words. | | `POST /car-comp/quote-requests` | `40001` | 400 | You need to request an OTP before getting Quotation | No quote OTP was requested for this phone number. | | | `40012` | 400 | OTP is invalid or expired. | The OTP the customer typed is wrong or too old. | | | `40002` | 400 | We couldn't verify the car details with Yakeen. Please review the car information and try again. | The sequence or customs number does not match the national vehicle registry. | | | `40003` | 400 | We couldn't verify the owner's details with Yakeen. Please review the owner ID and birthdate and try again. | The owner id and birthdate do not match the national identity registry. | | | `40004` | 400 | Unable to verify the details with Yakeen. Please review the car information, owner ID, and birthdate, then try again. | The registry check failed without saying which side. | | | `40016` | 400 | *Request errors coming directly from insurance provider* | The provider declined to quote, or could not register a customs-number vehicle. | | `POST /car-comp/quote-requests/{id}/attachments` | `40009` | 400 | Quote price not found for the selected request. | `quote_price_id` is not one of this quote request's prices. | | | `40014` | 400 | Vehicle photos can only be uploaded for a comprehensive quote. | The price belongs to a TPL quote. | | | `40015` | 400 | The vehicle photos could not be uploaded. Please try again. *(or the provider's own words)* | The insurer rejected an image, for example one it could not read. | | `POST /car-comp/issue-otp` | `42902` | 429 | Verification code was requested recently, try again in 2:41. | One OTP per phone number every three minutes on this endpoint. | | | `40007` | 400 | Quote request not found. | `quote_request_id` belongs to another client. | | | `40013` | 400 | The IBAN number is incorrect or does not belong to the customer | The insurer could not match the IBAN to the owner. | | | `40016` | 400 | *Request errors coming directly from insurance provider* | A refusal we have no wording of our own for, passed on in the provider's words. | | `POST /car-comp/policies` | `40007` | 400 | Quote request not found. | `quote_request_id` belongs to another client. | | | `40001` | 400 | You need to request an OTP before issuing the policy. | No issue OTP was requested for this phone number. | | | `40012` | 400 | OTP is invalid or expired. | The payment OTP the customer typed is wrong or too old. | | | `40008` | 400 | Quote reference not found. | `quote_reference_id` is not one of this quote request's quotes. | | | `40009` | 400 | Quote price not found for the selected request. | `quote_price_id` is not one of that quote's prices. | | | `40011` | 400 | One or more selected benefits are invalid. | A `benefits` entry is not offered on that quote. | | | `40016` | 400 | *Request errors coming directly from insurance provider* | The provider could not create the payment link, for example because the quote expired. | A failed or abandoned payment is never an API error: the customer pays on the insurer's hosted page, and the policy stays unissued until a payment succeeds. Read it back with `GET /car-comp/policies/{id}` or subscribe to the [webhooks](/webhooks/guide). ## SME medical insurance (price comparison) | Endpoint | Code | Status | Message | When | | ------------------------------------------ | ------- | ------ | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | `POST /medical/quote-requests` | `40020` | 400 | Add the company's employees before asking for prices. | The company has no employees yet. | | `POST /medical/policies` | `40009` | 400 | That quote\_price\_id does not belong to this quote request. | The price comes from a different quote request. | | `POST /medical/policies/{id}/declarations` | `40021` | 400 | This policy is already issued. | The insurer has issued the policy; its declarations are final. | | | `40022` | 400 | No employee on this policy matches: 1234567890, [hr@example.com](mailto:hr@example.com). | An `ids_or_emails` entry names nobody on the policy. | Payment has no errors of its own: read the policy, and `pending_declarations` names who still has to declare while `payment_link` appears once nobody does. A failed or abandoned payment leaves the policy unissued (`status` 0, `provider_policy_id` null) until a payment succeeds; the [webhooks](/webhooks/guide) tell you when it is issued. ## Property insurance | Endpoint | Code | Status | Message | When | | ---------------------------------- | ------- | ------ | --------------------- | ------------------------------------- | | `GET /property/address-from-short` | `40019` | 400 | Invalid short address | No address matches the short address. | ## Travel insurance | Endpoint | Code | Status | Message | When | | ------------------------------------------------ | ------- | ------ | -------------------------- | --------------------------------------------------------------------- | | `POST /yasmina-schengen-travel/upload-documents` | `40018` | 400 | Documents already uploaded | The identity and passport documents for this quote were already sent. | # Rate limiting Source: https://docs.yasmina.ai/api-resources/rate Every API call is counted against your client, per minute, by what the call asks of the insurers: | Kind of call | Limit | Which calls | | --------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Reads | 120 requests/minute | Every `GET`: policies, quote requests, employees, payment due, lookups. | | Writes | 60 requests/minute | Every other call not listed below: creating companies, setting employees, requesting quotes, OTPs, uploading photos, embed sessions, filling medical forms. | | Issuing and unwinding | 30 requests/minute | Any non-`GET` call to an endpoint ending in `policies`, `cancellation`, `policy-cancellation`, `claims` or `deletion`: issuing a policy, cancelling it, claiming on it, deleting it. | Each kind has its own bucket, so a burst of quote requests never slows your reads. The bucket belongs to your client id: it is shared across every product you use, and sandbox and production count separately. Calls the customer's browser makes from the Yasmina iframe (`/car-comp/embed/*`) are counted against the customer's IP address instead, so your customers never share one bucket. Two endpoints have a stricter, per-customer limit on top. `POST /car-comp/quote-otp` and `POST /car-comp/issue-otp` accept one request per phone number every three minutes, and answer `429` with code `42902` and the seconds left otherwise. The OTP already sent stays valid meanwhile. `POST /oauth/token` is limited to 60 requests per minute per IP address. Cache the token: it is valid for the `expires_in` it comes with. ## When you go over The call is refused with `429`, the standard [error envelope](/api-resources/errors) with code `42901`, and the seconds to wait in both the body and the `Retry-After` header: ```json theme={null} { "code": "42901", "message": "Too many requests. Please wait 37 seconds and try again.", "retry_after_seconds": 37 } ``` Every counted response also carries `X-RateLimit-Limit` and `X-RateLimit-Remaining`, so you can slow down before you are refused. Retry after `retry_after_seconds`; retrying sooner only extends the wait. # Generate Token Source: https://docs.yasmina.ai/auth-api-reference/oauth-20/generate-token /auth-api-reference/openapi.json post /oauth/token Generates an Oauth token to later use in our API's # Authentication Source: https://docs.yasmina.ai/authentication To access any of our API's. You need to authorize yourself using the Generate Token API. We are using the standard OAuth 2.0 client credentials. The Generate Token API requires your a Client ID and Client Secret. You can can head over to API Management to retrieve them. Insurance flow In this page you can Generate a new client secret. Copy both the Client ID and Client Secret. Now you can get a secure JWT token from the Generate Token API When you generate a new client secret the old one will be invalid, so use the Generate button with care. # Comprehensive Motor Insurance Source: https://docs.yasmina.ai/build-with-ai/motor Use an AI coding assistant to build your Comprehensive Motor Insurance integration. ## Introduction Every page of this documentation is published in an AI-readable format, so an AI coding assistant — Claude Code, Cursor, GitHub Copilot, or any tool that can fetch a URL — can read the [Comprehensive Motor Insurance guide](/price-comparison/motor-insurance) and API reference directly and scaffold the integration for you: authentication, OTPs, quotes, photo uploads, policy issuance, and error handling. You stay in control of the code. The assistant writes the first draft against our guide and OpenAPI spec; you review it, test it in the [Sandbox environment](/environments), and harden it before going live. ## What to feed your assistant Point your assistant at these pages. Appending `.md` to any page URL returns that page as plain Markdown. | Resource | URL | | ----------------------------------------- | ------------------------------------------------------------- | | Comprehensive Motor Insurance guide | `https://docs.yasmina.ai/price-comparison/motor-insurance.md` | | Authentication guide | `https://docs.yasmina.ai/authentication.md` | | Motor Insurance OpenAPI spec | `https://docs.yasmina.ai/car-api-reference/openapi.json` | | Index of every page (for broader context) | `https://docs.yasmina.ai/llms.txt` | ## Connect over MCP If your assistant supports the Model Context Protocol, connect it to our documentation MCP server instead of pasting URLs — it gives the assistant search and retrieval tools over the entire documentation site: ```text MCP server URL theme={null} https://docs.yasmina.ai/mcp ``` ```bash Claude Code theme={null} claude mcp add --transport http yasmina-docs https://docs.yasmina.ai/mcp ``` ```json Cursor (.cursor/mcp.json) theme={null} { "mcpServers": { "yasmina-docs": { "url": "https://docs.yasmina.ai/mcp" } } } ``` ## Ready-made prompt Copy the prompt below into your assistant and let it read the docs before it writes any code. ```text Prompt for your AI assistant theme={null} You are helping me integrate Yasmina's embedded Comprehensive Motor Insurance (Price Comparison) into my platform. Before writing any code, read these documents: - Integration guide: https://docs.yasmina.ai/price-comparison/motor-insurance.md - Authentication: https://docs.yasmina.ai/authentication.md - OpenAPI spec: https://docs.yasmina.ai/car-api-reference/openapi.json Then build a backend integration that: 1. Authenticates with OAuth 2.0 client credentials and reuses the token until it expires. 2. Requests a quote OTP for the customer, then requests quotes and presents them for selection. 3. Uploads the five required vehicle photos (front, back, right, left, chassis number) before issuing a comprehensive policy. 4. Requests an issue OTP and issues the policy with the selected quote. 5. Handles validation and error responses as described in the guide. Use the Sandbox environment (https://sandbox.yasmina.ai). Read the client ID and secret from environment variables, keep all Yasmina API calls on the backend, and never expose the credentials or the access token to the browser. ``` ## Tips for good results * **Always start in Sandbox.** The flows mirror Production, but no real policies are issued — see [Environments](/environments). * **Keep credentials server-side.** Yasmina APIs must be called from your backend; make sure generated code never ships the client secret or token to the browser. * **Review before Production.** Treat the generated integration as a draft: run the full flow end to end in Sandbox and review the code before switching the base URL to Production. Questions along the way? [Contact us](https://www.yasmina.ai/yasmina/contact-us) — we are happy to help. # SME Medical Insurance Source: https://docs.yasmina.ai/build-with-ai/sme-medical-insurance Use an AI coding assistant to build your SME Medical Insurance integration. ## Introduction Every page of this documentation is published in an AI-readable format, so an AI coding assistant — Claude Code, Cursor, GitHub Copilot, or any tool that can fetch a URL — can read the [SME Medical Insurance guide](/price-comparison/sme-medical-insurance) and API reference directly and scaffold the integration for you: authentication, company records, employees, quotes, policy issuance, health declarations, and payment. You stay in control of the code. The assistant writes the first draft against our guide and OpenAPI spec; you review it, test it in the [Sandbox environment](/environments), and harden it before going live. ## What to feed your assistant Point your assistant at these pages. Appending `.md` to any page URL returns that page as plain Markdown. | Resource | URL | | ----------------------------------------- | ------------------------------------------------------------------- | | SME Medical Insurance guide | `https://docs.yasmina.ai/price-comparison/sme-medical-insurance.md` | | Authentication guide | `https://docs.yasmina.ai/authentication.md` | | SME Medical OpenAPI spec | `https://docs.yasmina.ai/medical-api-reference/openapi.json` | | Index of every page (for broader context) | `https://docs.yasmina.ai/llms.txt` | ## Connect over MCP If your assistant supports the Model Context Protocol, connect it to our documentation MCP server instead of pasting URLs — it gives the assistant search and retrieval tools over the entire documentation site: ```text MCP server URL theme={null} https://docs.yasmina.ai/mcp ``` ```bash Claude Code theme={null} claude mcp add --transport http yasmina-docs https://docs.yasmina.ai/mcp ``` ```json Cursor (.cursor/mcp.json) theme={null} { "mcpServers": { "yasmina-docs": { "url": "https://docs.yasmina.ai/mcp" } } } ``` ## Ready-made prompt Copy the prompt below into your assistant and let it read the docs before it writes any code. ```text Prompt for your AI assistant theme={null} You are helping me integrate Yasmina's embedded SME Medical Insurance (Price Comparison) into my platform. Before writing any code, read these documents: - Integration guide: https://docs.yasmina.ai/price-comparison/sme-medical-insurance.md - Authentication: https://docs.yasmina.ai/authentication.md - OpenAPI spec: https://docs.yasmina.ai/medical-api-reference/openapi.json Then build a backend integration that: 1. Authenticates with OAuth 2.0 client credentials and reuses the token until it expires. 2. Creates a company record for the SME. 3. Saves the company's employees with a tier each, then requests prices and presents every provider's quote for selection. 4. Issues the company's policy from the chosen quote. 5. Collects the health declarations, then shares the payment link with the customer and handles the redirect back. Use the Sandbox environment (https://sandbox.yasmina.ai). Read the client ID and secret from environment variables, keep all Yasmina API calls on the backend, and never expose the credentials or the access token to the browser. ``` ## Tips for good results * **Always start in Sandbox.** The flows mirror Production, but no real policies are issued — see [Environments](/environments). * **Keep credentials server-side.** Yasmina APIs must be called from your backend; make sure generated code never ships the client secret or token to the browser. * **Review before Production.** Treat the generated integration as a draft: run the full flow end to end in Sandbox and review the code before switching the base URL to Production. Questions along the way? [Contact us](https://www.yasmina.ai/yasmina/contact-us) — we are happy to help. # Create embed session Source: https://docs.yasmina.ai/car-api-reference/embed-sessions/create-embed-session /car-api-reference/openapi.json post /embed-sessions Requests quotes and opens an embeddable session on them in one call, and returns a URL to put in an iframe or a WebView. Takes everything Request Quotes takes, plus where the session will run. The customer compares quotes, chooses add-ons, gives a payout account, uploads vehicle photos and verifies by OTP inside the embed. The issued policy and its payment link are handed back to your page or your app. To show the quotes again after the hour is up, call this again with the same payload. The quote OTP stays valid for hours, so the customer is not asked to verify twice. Register the sites and app links a session may be opened for in API Management first. # Show embed session Source: https://docs.yasmina.ai/car-api-reference/embed-sessions/show-embed-session /car-api-reference/openapi.json get /embed-sessions/{id} Returns a session you created earlier, including its URL and whether it has expired. # Store vehicle photos for an embed session Source: https://docs.yasmina.ai/car-api-reference/embed-sessions/store-vehicle-photos-for-an-embed-session /car-api-reference/openapi.json post /embed-sessions/{id}/photos **Embedded flow only.** If your site or app already holds the five vehicle photos comprehensive cover needs, hand them over here after opening the session and before the customer opens the embed. The customer is then not asked to upload photos inside the frame: Yasmina registers this set with the insurance provider itself, against whichever quotation the customer picks. Same files and limits as Upload vehicle photos, without a `quote_price_id`. The photos are checked and stored only; nothing is sent to the provider by this call. All five are required together, and calling it again replaces the stored set. Do not use this from a server-to-server integration: there, upload the photos against the selected quote with Upload vehicle photos. # Request OTP for Issuing Policy Source: https://docs.yasmina.ai/car-api-reference/otps/request-otp-for-issuing-policy /car-api-reference/openapi.json post /issue-otp Sends a separate policy issuance OTP. This OTP is valid for 15 minutes and must be submitted to POST /policies before it expires. The 8-hour quote OTP validity does not apply to policy issuance. # Request OTP for quote verification Source: https://docs.yasmina.ai/car-api-reference/otps/request-otp-for-quote-verification /car-api-reference/openapi.json post /quote-otp Sends a quote verification OTP to the provided email and phone number. The OTP remains valid for 8 hours and can be reused for multiple quote requests during that period. Requesting a new quote OTP invalidates the previous one. # Issue policy Source: https://docs.yasmina.ai/car-api-reference/policies/issue-policy /car-api-reference/openapi.json post /policies For issuing a new policy # List policies Source: https://docs.yasmina.ai/car-api-reference/policies/list-policies /car-api-reference/openapi.json get /policies Listing requested policies # Show policy Source: https://docs.yasmina.ai/car-api-reference/policies/show-policy /car-api-reference/openapi.json get /policies/{carPolicy} Show a specific policy # Delete quote Source: https://docs.yasmina.ai/car-api-reference/quotes/delete-quote /car-api-reference/openapi.json delete /quote-requests/{id} # Guideline texts Source: https://docs.yasmina.ai/car-api-reference/quotes/guideline-texts /car-api-reference/openapi.json get /guideline-texts Returns the copy you are expected to show alongside motor quotes — the provider attribution and its Insurance Authority licence, the Shahin support routes, and the buyer FAQ. English and Arabic are returned together, so a bilingual page needs a single request and does not have to hold the strings itself. Fetch it rather than hard-coding the wording: changes reach you without an integration change. # List quotes Source: https://docs.yasmina.ai/car-api-reference/quotes/list-quotes /car-api-reference/openapi.json get /quote-requests # Request quotes Source: https://docs.yasmina.ai/car-api-reference/quotes/request-quotes /car-api-reference/openapi.json post /quote-requests For getting prices with benefits. The Quote IDs can be used later to issue a policy # Show quote Source: https://docs.yasmina.ai/car-api-reference/quotes/show-quote /car-api-reference/openapi.json get /quote-requests/{id} # Upload vehicle photos Source: https://docs.yasmina.ai/car-api-reference/quotes/upload-vehicle-photos /car-api-reference/openapi.json post /quote-requests/{id}/attachments Uploads the five vehicle photos required for comprehensive cover and registers them with the insurance provider against the selected quote. Call it before requesting the payment OTP: the provider downloads and checks every image during this call, so a photo it cannot read is rejected while the customer can still retake it, rather than after they have paid. All five are required together — a partial set is rejected. The provider keeps the first set of photos it accepts for a vehicle, so a later upload for the same vehicle still returns 200 with `already_registered: true` and leaves the registered photos as they are. The quote_price_id must belong to a comprehensive quote. In the embedded flow, photos stored with Store vehicle photos for an embed session are registered by the embed itself; you do not call this endpoint. # List vehicle body types Source: https://docs.yasmina.ai/car-api-reference/vehicle-lookups/list-vehicle-body-types /car-api-reference/openapi.json get /vehicle-body-types Returns body types accepted when requesting a quote with a customs number. # List vehicle makers Source: https://docs.yasmina.ai/car-api-reference/vehicle-lookups/list-vehicle-makers /car-api-reference/openapi.json get /vehicle-makers Returns vehicle makers that have at least one model. Use the returned code when requesting a quote with a customs number. # List vehicle models Source: https://docs.yasmina.ai/car-api-reference/vehicle-lookups/list-vehicle-models /car-api-reference/openapi.json get /vehicle-models Returns models belonging to the selected maker. The model code submitted in a customs-number quote must belong to its maker code. # Cancel policy Source: https://docs.yasmina.ai/cartpl-api-reference-v2/policies/cancel-policy /cartpl-api-reference-v2/openapi.json post /v2/car/policies/{carPolicy}/cancellation Cancel a policy # Cancel policy by VIN Source: https://docs.yasmina.ai/cartpl-api-reference-v2/policies/cancel-policy-by-vin /cartpl-api-reference-v2/openapi.json post /v2/clients/policies/cancellation Cancel policy by VIN # Issue policy Source: https://docs.yasmina.ai/cartpl-api-reference-v2/policies/issue-policy /cartpl-api-reference-v2/openapi.json post /v2/car/policies For issuing a new policy. This version requires an email field and an istimarah document upload. # List policies Source: https://docs.yasmina.ai/cartpl-api-reference-v2/policies/list-policies /cartpl-api-reference-v2/openapi.json get /v2/car/policies Listing requested policies # Changelog Source: https://docs.yasmina.ai/changelog **Every error now has its own code.** The [Errors](/api-resources/errors) page lists the errors any endpoint can return, then the ones specific to each product, with the message and the reason for each. Cases that used to share `40000` are told apart: no OTP requested yet (`40001`), car or owner not verified by Yakeen (`40002`, `40003`, `40004`), phone not the owner's or already in use (`40005`, `40006`), unknown quote request, quote, price or benefit (`40007`, `40008`, `40009`, `40011`), IBAN refused (`40013`), photo problems (`40014`, `40015`), the insurer's own refusal (`40016`), and a policy that cannot be cancelled yet (`40017`). SME medical rules have theirs too: a company with no employees (`40020`), declarations on a policy the insurer already issued (`40021`), an `ids_or_emails` entry naming nobody (`40022`). `422` is reserved for field validation and is always `42201`; the medical rules that used to answer `422` answer `400` now. `code` is always a JSON string now; a few responses used to send a number. Every error is JSON with a `code` whatever the `Accept` header says: business-rule rejections and rate limits used to come back as an HTML page or a bare `message`. `POST /api/v1/car-comp/issue-otp` answers `400` instead of `200` when the quote request belongs to another client. An unreachable insurer is `504` / `50401`, not `502`. **Rate limits are enforced** as described on the rewritten [Rate limiting](/api-resources/rate) page: 120 reads, 60 writes and 30 issue-type calls a minute per client, answered with `429` / `42901` and `retry_after_seconds` when exceeded. Added the Guideline Texts API (`GET /api/v1/car-comp/guideline-texts`): the copy to show alongside motor quotes — the provider attribution with its Insurance Authority licence, the support routes, and the buyer FAQ — returned in English and Arabic together. Fetch it rather than hard-coding the wording, so changes reach you without an integration change. Added the Upload Vehicle Photos API (`POST /api/v1/car-comp/quote-requests/{id}/attachments`): the five vehicle photos (`front`, `back`, `right`, `left`, `chassis`) required for comprehensive cover, sent as file uploads with the selected `quote_price_id`. Call it before requesting the payment OTP — the insurance provider downloads and checks every image during the call, so an unreadable photo is rejected while the customer can still retake it. All five are required together, JPG or PNG up to 3 MB each, and the photos can only be submitted once per vehicle. Moved the `iban` field from the Issue Policy API to the Issue OTP API (`POST /api/v1/car-comp/issue-otp`), where it is now **required**. The customer's Saudi IBAN (`SA` followed by 22 digits) is forwarded to the insurance provider with the payment OTP request and used for claim settlements and refunds. `POST /api/v1/car-comp/policies` no longer accepts the field. Added the optional `iban` field to the Issue Policy API (`POST /api/v1/car-comp/policies`): the customer's Saudi IBAN (`SA` followed by 22 digits) that insurance providers use to transfer claim settlements and refunds. Sending it is strongly recommended; when omitted, payouts are routed through a Yasmina fallback account, which can delay refunds to the customer. Documented TPL Motor Insurance policy cancellation document validation. Cancellation requests now require an updated vehicle information document that matches the policy VIN and sequence number, and confirms that ownership transfer is complete. Added the new `422` cancellation document mismatch response to the TPL Motor Insurance API reference. Removed the unused TPL Motor Insurance v1 API reference from the API Reference navigation. Added `otp` as a required field to the Request Quotes API (`POST /api/v1/car-comp/quote-requests`) and Issue Policy API (`POST /api/v1/car-comp/policies`) documentation. The field was already required by the backend but was missing from the docs and API reference. Added `company_logo_url` and `square_company_logo_url` to motor quote responses so clients can display both the standard company logo and square logo from the CDN. Added the optional `Accept-Language: ar` header to the Car Insurance Request Quotes API for Arabic-localized quote content. Added support for `custom_number` as an alternative to `car_sequence_number` in car quote requests. The `custom_number` is used for newly imported cars and must be between 1000000 and 9999999999. Add start\_date to the Car Insurance Issue Policy API documentation Seperated Products between Multi Providers and Single Provider Added Payment section to Motor Insurance Documentation Revamp Added more sections * Changelog * Authentication * Developer Status Page * Data Types * Error Codes * White-labeling Released Property Insurance and Price comparison * Issue Policies * Cancel Policies * Prices * Claims Released Webhooks Webhooks * Webhook on Policy Status Update * Webhook on Policy Documents Update Released Horses Insurance * Get Livestock (Horse) Insurance from a public form * Also added the ability to get them from APIs # Developer Status Page Source: https://docs.yasmina.ai/developer # Environments Source: https://docs.yasmina.ai/environments Yasmina provides three separate environments to support your full development and integration lifecycle — from internal testing, to integration validation, to going live with real customers *** ### Production This is the live environment where your customers purchase real insurance policies through your platform. All actions here have real-world impact and are subject to live processing and billing. Base URL: [https://production.yasmina.ai](https://production.yasmina.ai) Use this environment only after your integration has been fully tested and approved. *** ### Sandbox The Sandbox environment behaves just like Production — same APIs, same flows — but it uses dummy data. This makes it perfect for: * Testing your API integration * Simulating real-world scenarios * Internal QA or demos Although the flows mirror Production, no real policies are issued and no live data is processed. Base URL: [https://sandbox.yasmina.ai](https://sandbox.yasmina.ai) *** # Issue claim Source: https://docs.yasmina.ai/horse-api-reference/claims/issue-claim /horse-api-reference/openapi.json post /policies/{policyId}/claims Issue a claim to your policy # Cancel policy Source: https://docs.yasmina.ai/horse-api-reference/policies/cancel-policy /horse-api-reference/openapi.json post /policies/{horsePolicy}/cancellation Cancel a policy # Create a horse policy Source: https://docs.yasmina.ai/horse-api-reference/policies/create-a-horse-policy /horse-api-reference/openapi.json post /policies Creates a new horse policy record with detailed horse information. # Getting Started Source: https://docs.yasmina.ai/introduction Welcome to Yasmina integration. Pioneering embedded insurance in Saudi Arabia and the region by offering seamless coverage, delivered at the perfect moment to protect your customers. ### About Yasmina Yasmina makes it easy for online businesses to offer different insurance products to their customers through a fully integrated, API-first solution. Whether you're a tech platform, e-commerce store, or HR system, Yasmina gives you the tools to generate insurance quotes, issue policies, and manage claims — all through a simple, standard RESTful APIs. Our platform sits in the middle of Insurance Providers and Businesses. Insurance flow 💡 Yasmina is fully self-service, which means you can go live without waiting for manual onboarding or lengthy setup processes. ### Onboarding Signing up is quick. Just head up to [https://portal.yasmina.ai/register](https://portal.yasmina.ai/register) and fill in the sign up form Insurance flow Once you sign up, you need to click Enrollment from the sidebar. Insurance flow Once you click, you go through a simple guided wizard where you'll tell us more about your business and how you will use Yasmina. You should also let us know what Products you are planning to use. Here are the products that Yasmina provides: * Single Insurance Provider (In this model you get insurance from a pre-defined insurance company.) * SME Medical Insurance * Comprehensive Motor Insurance * TPL Motor Insurance * Property Insurance * Travel Insurance * Life Insurance (S\&P) * Horse Insurance * Price Comparison (In this model, you can show your customer insurance from multiple companies and your they get to choose one.) * Comprehensive Motor Insurance * TPL Motor Insurance * Property Insurance At the end of the process, you need to carefully review and accept our service agreement to complete your enrollment. Made a mistake or missed something after submission? You can reset your submission and update the details anytime. Waiting for approval is only required in **Production** environment. Your account will be auto-approved on **Sandbox**. Once submitted, our team will review your details and usually approve your account within 24 hours. After approval, your business will have full access to Yasmina, and you’ll be ready to start offering insurance services through your own platform. Insurance flow You can learn how to integrate with our products from our Insurance Integrations Guides. ### Insurance Integrations Guides * **Single Insurance Provider** * [SME Medical Insurance](/single-provider-integrations/sme-medical-insurance) * [Comprehensive Motor Insurance](/single-provider-integrations/car) * [TPL Motor Insurance](/single-provider-integrations/cartpl) * [Property Insurance](/single-provider-integrations/property) * [Travel Insurance](/single-provider-integrations/travel) * [Life Insurance (S\&P)](/single-provider-integrations/life) * [Horse Insurance](/single-provider-integrations/horse) * **Price Comparison** * [Motor Insurance](/price-comparison/motor-insurance) * [Property Insurance](/price-comparison/property) # Submit claim Source: https://docs.yasmina.ai/life-snp/claims/submit-claim /life-snp/openapi.json post /policies/{policyId}/claims Submit a Life S&P claim (death / critical illness / disability). # Life S&P Products Source: https://docs.yasmina.ai/life-snp/offers/life-s&p-products /life-snp/openapi.json post /offers Generates Life S&P offers (premiums and benefits) from multiple insurers for a bank's customers. # Cancel policy Source: https://docs.yasmina.ai/life-snp/policies/cancel-policy /life-snp/openapi.json post /policies/{lifePolicy}/cancellation Cancel a Life S&P policy (e.g., within cooling-off period). # Issue policy Source: https://docs.yasmina.ai/life-snp/policies/issue-policy /life-snp/openapi.json post /policies Issue a Life S&P policy based on a selected offer. # List policies Source: https://docs.yasmina.ai/life-snp/policies/list-policies /life-snp/openapi.json get /policies List Life S&P policies created via the bank channel. # Issue claim Source: https://docs.yasmina.ai/medical-api-reference/claims/issue-claim /medical-api-reference/openapi.json post /policies/{policyId}/claims Issue a claim to your policy # Cancel policy Source: https://docs.yasmina.ai/medical-api-reference/company/cancel-policy /medical-api-reference/openapi.json post /companies/{companyId}/policy-cancellation Cancel a policy for a company # Create company Source: https://docs.yasmina.ai/medical-api-reference/company/create-company /medical-api-reference/openapi.json post /companies You need to create a company record before requesting medical insurance to the employees of the company # List companies Source: https://docs.yasmina.ai/medical-api-reference/company/list-companies /medical-api-reference/openapi.json get /companies To list all the companies that you've created # List the employees Source: https://docs.yasmina.ai/medical-api-reference/employees/list-the-employees /medical-api-reference/openapi.json get /companies/{companyId}/employees The company's employee list as last saved. # Save the employees Source: https://docs.yasmina.ai/medical-api-reference/employees/save-the-employees /medical-api-reference/openapi.json put /companies/{companyId}/employees Replaces the company's employee list with the one given: who is covered, their dependents, and the tier each has picked (`basic`, `standard`, `premium` or `executive`). Nothing is priced here; see Get prices from every provider. # Download the declaration form Source: https://docs.yasmina.ai/medical-api-reference/medical-forms/download-the-declaration-form /medical-api-reference/openapi.json get /medical-forms/download The health declaration as a printable PDF, so a company can hand it to the employees who have to fill it in. Pass a `policy_id` and the file carries one page per employee on that policy, with their name, id and package already filled in; leave it out for a single blank form. # Fill the declarations Source: https://docs.yasmina.ai/medical-api-reference/medical-forms/fill-the-declarations /medical-api-reference/openapi.json post /policies/{policyId}/declarations A company admin answers the health declaration on the employees' behalf. `all_employees` is the default set of answers; `ids_or_emails` overrides them for the employees whose history differs. The answers are stored on the members of the policy, and its `payment_link` appears once nobody is left in `pending_declarations`. # Get the Medical form questions Source: https://docs.yasmina.ai/medical-api-reference/medical-forms/get-the-medical-form-questions /medical-api-reference/openapi.json get /medical-forms This is for showing the required medical questions and presenting it to employees # Delete policy Source: https://docs.yasmina.ai/medical-api-reference/policies/delete-policy /medical-api-reference/openapi.json post /policies/{policyId}/deletion Delete a policy. Important if for example someone resigns # Issue the policy Source: https://docs.yasmina.ai/medical-api-reference/policies/issue-the-policy /medical-api-reference/openapi.json post /policies Issues the company's policy from one of the quotes it was given: the employees as they were priced, the provider that priced them, and its total as the premium. A company has one policy waiting to be paid for at a time; issuing again before payment replaces it. # List policies Source: https://docs.yasmina.ai/medical-api-reference/policies/list-policies /medical-api-reference/openapi.json get /policies List policies that you've requested # Read the policy Source: https://docs.yasmina.ai/medical-api-reference/policies/read-the-policy /medical-api-reference/openapi.json get /policies/{policyId} One policy, with everything needed to take payment: its `price`, `pending_declarations` naming anyone who still has to declare, and `payment_link` once nobody does. The link is a fresh signed URL on every read, valid 15 minutes, and null while the policy cannot be paid for or once it is issued. # List categories Source: https://docs.yasmina.ai/medical-api-reference/products/list-categories /medical-api-reference/openapi.json get /products/categories Each category carries a `price`, the yearly premium per person, which is what the payment flow charges. The medical insurance packages one insurance provider offers. Call it once per provider to compare them. Each item in `categories` carries the `category` and `insurance_provider` values to send when issuing policies. # Get prices from every provider Source: https://docs.yasmina.ai/medical-api-reference/quotes/get-prices-from-every-provider /medical-api-reference/openapi.json post /quote-requests Prices the company's saved employees, at the tiers they picked, with every insurance provider at once. One response, one quote per provider, each with its own `quote_price_id`. The response `id` is the `quote_request_id`. A quote prices the employees as they stood when it was asked for. # Read a quote request Source: https://docs.yasmina.ai/medical-api-reference/quotes/read-a-quote-request /medical-api-reference/openapi.json get /quote-requests/{quoteRequestId} # List payments Source: https://docs.yasmina.ai/payments-api-reference/payments/list-payments /payments-api-reference/openapi.json get /payments Get payment records # Motor Insurance Source: https://docs.yasmina.ai/price-comparison/motor-insurance Seamless insurance for the cars you're selling and the drivers that are buying from you.

Build it with AI — an AI coding assistant can scaffold this entire integration for you straight from these docs. See Build with AI to get started.

## Introduction This guide introduces Yasmina’s **Motor Insurance Price Comparison APIs**, covering both comprehensive and TPL cover (for the single-provider versions, see [Comprehensive](/single-provider-integrations/car) and [TPL](/single-provider-integrations/cartpl)). These APIs enable you to retrieve quotes from several insurance companies before issuing a policy to your customer. The guide covers all key operations, including requesting quotes, issuing and managing policies, generating payment links, and handling claims. Our APIs are built on RESTful principles and follow consistent input and output structures, making them simple to integrate, test, and maintain within your systems ## What you will learn * Request OTPs * Requesting and managing quotes * Uploading vehicle photos * Issuing and managing policies ## Prerequisites 1. **Account in Yasmina** - See the Onboarding section for details. You need "Motor Insurance Comprehensive (Price Comparison)", "Motor Insurance TPL (Price Comparison)", or both in the products field, depending on the cover you want quoted. 2. **Authenticated Token** - You can follow the Authentication guide or head straight to the Generate Token API. 3. **Backend server** - Required to securely call Yasmina APIs. ## Quotes Quotes represent the different premiums, benefits, and deductibles offered by insurance providers. Before issuing a motor insurance policy, you need to provide the car details to retrieve quotes from various insurance providers. A single quote request returns both comprehensive and TPL offers, so the same flow covers either cover type. These quotes are then used when issuing the policy. ### OTP for quotations Before requesting quotations, we need to verify the Phone number of the customer through an OTP. You can do that using the Quote OTP API You need to provide the following properties for the Quote OTP API: | Field | Example Value | Description | | ---------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `owner_id` | `2234567890` | The owner’s national ID (starts with `1` for Saudi nationals) or Iqama ID (starts with `2` for residents). Must be exactly 10 digits. | | `email` | `someone@example.com` | The owner’s email. Must be unique and belong to the one customer (Do not use the same email for multiple customers). | | `phone` | `05XXXXXXXX` | Saudi mobile number. Must start with `05` and be exactly 10 digits. | Example Payload ``` POST /api/v1/car-comp/quote-otp HTTP/1.1 Host: sandbox.yasmina.ai Accept: application/json Authorization: Bearer token Content-Type: application/json Content-Length: 93 { "email": "someone@example.com", "phone": "0512345678", "owner_id": "1234567890" } ``` The customer should then receive an OTP. The API returns `204 No Content`. This quote OTP remains valid for 8 hours and can be reused for multiple quote requests during that period. You do not need to request a new quote OTP before every quotation. The response includes: * `X-OTP-Expires-In`: Remaining validity in seconds * `X-OTP-Expires-At`: Exact expiry time in ISO 8601 format Requesting a new quote OTP invalidates the previously issued quote OTP. After 8 hours, request a new OTP before submitting another quote request. Afterwards you will be ready to Request Quotations. ### Request Quotes In order to provide quotes for your customer you need to execute the Request Quotes API. This API provides an array response from different insurance providers. Each item in this array, represents the name of the company, the logo, the different premiums and deductibles, and also the list of benefits (both free and paid). The Request Quotes API may take longer to respond because it retrieves results from multiple insurance providers. Be sure to increase your timeout to at least 2 minutes before making the request. You need to provider the following properties for the Request Quotes API: | Field | Example Value | Is Required | Description | | ----------------------- | --------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `otp` | `1234` | Yes | The four-digit OTP received by the customer from the Request OTP API. | | `owner_id` | `2234567890` | Yes | The owner’s national ID (starts with `1` for Saudi nationals) or Iqama ID (starts with `2` for residents). Must be exactly 10 digits. | | `email` | `someone@example.com` | Yes | The owner’s email. Must be unique and belong to the one customer (Do not use the same email for multiple customers). | | `birthdate` | `1988-04-20` | Yes | Date of birth of the owner in `YYYY-MM-DD` format. For a Saudi national ID (starts with `1`) give a Hijri date; for an Iqama ID (starts with `2`) give a Gregorian date. | | `phone` | `05XXXXXXXX` | Yes | Saudi mobile number. Must start with `05` and be exactly 10 digits. | | `car_sequence_number` | `52423810` | Conditional | The car’s sequence number (8-9 digits). Required when `custom_number` is not provided. Do not send both vehicle identifiers. | | `custom_number` | `1234567890` | Conditional | Customs card number for an imported vehicle (6-10 digits). Required when `car_sequence_number` is not provided. Also requires `maker_code`, `model_code`, and `body_type_code`. | | `maker_code` | `101` | With customs card | Vehicle maker code returned by the Vehicle Makers API. | | `model_code` | `1001` | With customs card | Vehicle model code returned by the Vehicle Models API for the selected `maker_code`. | | `body_type_code` | `3` | With customs card | Vehicle body-type code returned by the Vehicle Body Types API. | | `is_ownership_transfer` | `false` | No | Boolean flag. `true` if the car is being transferred to a new owner, otherwise `false`. Defaults to `false` when omitted. | | `current_car_owner_id` | `1234567890` | Yes (if transfer) | The current owner’s national ID (starts with `1`) or Iqama ID (starts with `2`). **Only required if** `is_ownership_transfer = true`. | | `car_estimated_cost` | `45000` | Yes | Estimated market cost of the car in SAR. | | `car_model_year` | `2026` | No | Year of manufacture of the car. Must be between 1950 and the next year. If omitted, Yasmina uses the current year. | | `start_date` | `2026-07-28` | No | Start date of the policy in `YYYY-MM-DD` format. It must be after today and before the date 28 days from today. | | `drivers` | See below | No | An array of driver objects. When provided, the sum of all `driving_percentage` values must equal 100, and the owner must be included among the drivers. | ### Customs card vehicle lookup If your customer identifies vehicles only by customs card number, collect the provider-compatible maker, model, and body-type codes before requesting a quote. Do not send codes from your own vehicle catalogue. All three lookup endpoints support an optional `q` query parameter. It searches English and Arabic names without case sensitivity. A complete numeric value searches by exact code. The maximum search length is 100 characters. #### 1. Search vehicle makers ```bash theme={null} curl --request GET \ --url 'https://sandbox.yasmina.ai/api/v1/car-comp/vehicle-makers?q=Toyota' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` Only makers with at least one available model are returned. #### 2. Search models for the selected maker `maker_code` is required. The returned model codes belong only to that maker. ```bash theme={null} curl --request GET \ --url 'https://sandbox.yasmina.ai/api/v1/car-comp/vehicle-models?maker_code=101&q=Corolla' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` #### 3. Search vehicle body types ```bash theme={null} curl --request GET \ --url 'https://sandbox.yasmina.ai/api/v1/car-comp/vehicle-body-types?q=SUV' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` Each lookup endpoint returns an array with the same structure: ```json theme={null} [ { "code": 101, "name_en": "Toyota", "name_ar": "تويوتا" } ] ``` For a customs card quote, send `custom_number`, `maker_code`, `model_code`, and `body_type_code`. Omit `car_sequence_number`. Yasmina registers the imported vehicle with the insurance platform before requesting quotations. If the vehicle is already registered, the quotation continues normally. #### Drivers Array When providing drivers, each driver object must include the following fields: | Field | Example Value | Is Required | Description | | -------------------- | ------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `owner_id` | `2234567890` | Yes | Driver's national ID (starts with `1` for Saudi nationals) or Iqama ID (starts with `2` for residents). Must be exactly 10 digits. | | `birthdate` | `1988-04-20` | Yes | Driver's date of birth in `YYYY-MM-DD` format. | | `driving_percentage` | `50` | Yes | Percentage of driving for this driver. Valid values: `25`, `50`, `75`, or `100`. The sum of all drivers' percentages must equal 100. | When drivers are provided, the vehicle owner must be included among the drivers. Example request ``` POST /api/v1/car-comp/quote-requests HTTP/1.1 Accept: application/json Content-Type: application/json Authorization: •••••• Content-Length: 226 { "otp": "1234", "owner_id": "2234567890", "email": "someone@example.com", "phone": "05XXXXXXXX", "birthdate": "1982-04-20", "custom_number": "1234567890", "maker_code": 101, "model_code": 1001, "body_type_code": 3, "is_ownership_transfer": false, "car_estimated_cost": 45000, "car_model_year": 2024, "drivers": [ { "owner_id": "2234567890", "birthdate": "1982-04-20", "driving_percentage": 50 }, { "owner_id": "1234567891", "birthdate": "1990-06-15", "driving_percentage": 50 } ] } ``` Once you execute this you will get a response that includes pricing and benefits from multiple insurance providers. This is an example of a response, trimmed to a single provider quote: ```json theme={null} { "owner_id": "1234567890", "email": "someone@example.com", "phone": "0555555555", "birthdate": "1990-01-01", "car_sequence_number": 1111111111, "is_ownership_transfer": true, "current_car_owner_id": "1000000000", "car_estimated_cost": 45000, "car_model_year": 2024, "start_date": "2026-07-28", "drivers": [ { "owner_id": "1234567890", "birthdate": "1990-01-01", "driving_percentage": 50 }, { "owner_id": "2345678901", "birthdate": "1985-06-20", "driving_percentage": 50 } ], "quotes": [ { "type": "Comprehensive", "insurance_type_display": "Comprehensive", "insurance_type_display_ar": "شامل", "fix_type": "workshop", "vehicle_estimated_value": 45000, "company_name": "Al Rajhi Takaful", "company_name_ar": "تكافل الراجحي", "company_logo": "/images/company-logos/art.png", "company_logo_url": "https://cdn.yasmina.ai/company-logos/art.png", "square_company_logo_url": "https://cdn.yasmina.ai/insurance-logos/alrajhi.png", "quote_expiry_date": "2026-10-09T22:03:56+00:00", "quote_reference_id": "6c7c18a7-ee89-49fe-9f7e-dde72ad809ce", "prices": [ { "quote_price_id": "f5d52340-3661-48af-b81a-028f251ef6a9", "deductible": 500, "subtotal": 5232.12, "vat_percentage": 15, "vat": 784.82, "total": 6016.94 }, { "quote_price_id": "40fe40ec-e7d0-f011-972d-005056a9891a", "deductible": 1000, "subtotal": 5145.03, "vat_percentage": 15, "vat": 771.75, "total": 5916.78 } ], "benefits": [ { "quote_benefit_id": "f72846cb-98ed-4b78-b3b5-bb0d587f8da5", "id": "1296", "name": "Natural Disasters", "name_ar": "كوارث طبيعية", "amount": 0, "vat": 0, "url": null }, { "quote_benefit_id": "67fe40ec-e7d0-f011-972d-005056a9891a", "id": "600100", "name": "Roadside assistance service", "name_ar": "خدمة المساعدة على الطريق", "amount": 10, "vat": 1.5, "url": null } ] } ], "attachments": null, "client_id": "9f757acd-1ab4-466f-8cb2-d65ddedb2374", "updated_at": "2026-10-06T22:03:56.000000Z", "created_at": "2026-10-06T22:03:56.000000Z", "id": 25 } ``` ### Explaining the Quotes Request response The response has two halves. The first is an **echo of what you sent** — `owner_id`, `email`, `phone`, `birthdate`, the vehicle identifier, `drivers`, `start_date`. Nothing new, but it means a stored response is enough to re-render the customer's page later without keeping your own copy of the request. The second is **the offers**: the top-level `id`, and the `quotes` array with one entry per offer the insurance providers returned. The same insurance company can appear several times in `quotes`. Each entry is a distinct offer — a cover type (`type`) combined with a repair type (`fix_type`). Al Rajhi Takaful, for instance, commonly returns a Comprehensive/Agency offer, a Comprehensive/Workshop offer and a TPL offer: three entries, each with its own `quote_reference_id`, its own prices and its own benefits. Group by `company_name` if you want one card per company in your UI. #### The shape at a glance ```text theme={null} id .......................... the quote request itself → send as quote_request_id quotes[] .................... one entry per provider offer ├── company_name ............ who is offering ├── type / fix_type ......... what cover, and where it is repaired ├── quote_expiry_date ....... how long the offer stands ├── quote_reference_id ...... identifies this offer → send when issuing ├── prices[] ................ one entry per deductible │ ├── quote_price_id ...... identifies the chosen deductible → send when issuing │ └── deductible, subtotal, vat, total └── benefits[] .............. add-ons attached to this offer ├── amount .............. 0 = already included, > 0 = optional extra └── quote_benefit_id .... send only for the paid extras the customer picked ``` #### The identifiers you carry into issuance Policy issuance never re-sends the car or the customer details — it points back at one exact selection inside this response. Four values do that: | What the customer chose | Field you read from this response | Field you send to the Issue APIs | | ------------------------------------ | -------------------------------------- | -------------------------------- | | This quote request | `id` (top level) | `quote_request_id` | | The provider and cover they picked | `quotes[].quote_reference_id` | `quote_reference_id` | | The deductible and price they picked | `quotes[].prices[].quote_price_id` | `quote_price_id` | | Each paid add-on they ticked | `quotes[].benefits[].quote_benefit_id` | `benefits[]` | All four must describe one consistent selection: the price must belong to the same `quotes[]` entry as the reference, and the benefits must belong to that same entry too. A `quote_price_id` from one provider sent with another provider's `quote_reference_id` is rejected. The Issue Policy OTP API takes the first three; the Issue Policy API takes all four. Keep the customer's selection around between the two calls. #### Top-level fields Yasmina's identifier for this quote request. Send it as `quote_request_id` when issuing, and use it to fetch the request again with the Show Quote Request API. The offers returned by the insurance providers. Empty if no provider priced this vehicle and driver combination. Each entry is described under **Each offer (`quotes[]`)** below. The five vehicle photos once they have been uploaded, keyed by position (`front`, `back`, `right`, `left`, `chassis`). `null` until you call the Upload Vehicle Photos API. Your client identifier. Same value on every quote request you create. When the quote request was made. Useful together with `quote_expiry_date` when deciding whether to re-quote. When the record last changed — for example after vehicle photos were uploaded. Alongside those, the request values come back unchanged: `owner_id`, `email`, `phone`, `birthdate`, `is_ownership_transfer`, `current_car_owner_id`, `car_estimated_cost`, `car_model_year`, `start_date` and `drivers`, plus the vehicle identifier you used. Two details are worth knowing: * `current_car_owner_id` is filled with `owner_id` when `is_ownership_transfer` is `false`. * The customs-card fields (`custom_number`, `maker_code`, `model_code`, `body_type_code`) appear only for imported vehicles; `car_sequence_number` appears only for locally registered ones. Anything not listed here or below is internal bookkeeping. Do not build against fields this page does not document — they can change without notice. #### Each offer (`quotes[]`) The provider's identifier for this offer. Send it as `quote_reference_id` when issuing. It is unique per offer, not per company: a company returning three cover types returns three different reference IDs. English name of the insurance company, e.g. `Al Rajhi Takaful`. Arabic name of the same company. Falls back to the English name if a company is not yet mapped. Absolute CDN URL of the company's wide logo — the one to put on a quote card. Empty string if the company has no logo on file. The CDN host differs between sandbox and production, so always render the URL as returned rather than rebuilding it. Absolute CDN URL of the same company's square logo, for avatars, list rows and other tight spaces. Empty string if none is on file. **Deprecated.** A path relative to Yasmina's own web app, not a usable URL from your side. Kept for backward compatibility only — use `company_logo_url`. The normalised cover category, and the field to filter and group on. Always one of: | Value | Meaning | | --------------- | -------------------------------------------------------------------------------------------------------------- | | `Comprehensive` | Covers damage to the customer's own vehicle as well as third parties. | | `TPL` | Third-party liability only. | | `TPL +` | Any enhanced third-party product. Providers name these differently; they are all normalised to this one value. | The provider's own wording for the same product, unnormalised — `TPL Plus`, `TPL + OD`, `Wafi Smart`, and so on. Show this to the customer; filter on `type`. Arabic translation of `insurance_type_display`. Falls back to the English value for provider-specific products that have no translation yet. Where a claim gets repaired: `Agency` (the manufacturer's authorised dealer, more expensive) or `workshop` (an approved independent garage). Empty for TPL offers, which carry no own-damage repair. This is the single biggest reason two offers from the same company differ in price, so it is worth surfacing in the UI. The vehicle value this offer was priced against, in SAR. Normally the provider's own valuation; it falls back to the `car_estimated_cost` you sent when the provider does not return one. Worth showing on Comprehensive offers, since it is the ceiling of an own-damage payout. When the provider's offer lapses. Validity varies by provider and by product — some offers stand for days, others for months. After this moment the offer can no longer be issued, so request fresh quotes rather than replaying a stored response. The price options for this offer, one per deductible. See below. The benefits attached to this offer, both included and optional. See below. #### Price options (`quotes[].prices[]`) One offer carries several prices — the same cover at different deductibles. The deductible is what the customer pays out of their own pocket on a claim, so a higher deductible buys a lower premium. A comprehensive offer routinely comes with ten or more of these; a TPL offer usually has exactly one. Identifies the price the customer picked. Send it as `quote_price_id` when issuing, and to the Upload Vehicle Photos API. The excess in SAR that the customer bears on each claim. `null` on TPL offers, which have no deductible. The premium for this option in SAR, before VAT. The VAT rate applied, as a percentage. `15` in Saudi Arabia today. The VAT amount in SAR for this option. `subtotal` + `vat` — what the customer pays for the cover itself. It does **not** include any optional benefits — see **What the customer actually pays** below. #### Benefits (`quotes[].benefits[]`) Benefits are the add-ons that come with an offer. `amount` alone tells you which of the two kinds you are looking at: | `amount` | Kind | What you do | | -------- | -------- | -------------------------------------------------------------------------------------------------- | | `0` | Included | Already part of the cover. Display it; do **not** send it when issuing. | | `> 0` | Optional | An extra the customer may add. Send its `quote_benefit_id` in `benefits[]` when issuing to buy it. | Identifies this benefit on this offer. Collect the IDs of the paid benefits the customer ticked and send them as the `benefits` array to the Issue Policy API. The ID is specific to one offer — a benefit that also appears on another provider's offer has a different `quote_benefit_id` there. The provider's benefit code, e.g. `600100` for roadside assistance. Stable across quote requests, so it is the right key if you want to remember a customer's preferences or map benefits to your own icons and copy. English name of the benefit, e.g. `Roadside assistance service`. Arabic name of the same benefit. Price of the benefit in SAR, excluding VAT. `0` means it is included in the cover at no extra cost. VAT on `amount`, in SAR. `0` for included benefits. A provider link with the benefit's terms, when the provider supplies one. Usually `null` — render the link only when it is present. #### What the customer actually pays `prices[].total` is the price of the cover on its own. Every paid benefit the customer adds is charged on top of it, with its own VAT. Taking the example response above, with the 500 SAR deductible and roadside assistance added: | Line | Amount (SAR) | | ------------------------------ | ------------ | | Premium (`subtotal`) | 5232.12 | | VAT on the premium (`vat`) | 784.82 | | Roadside assistance (`amount`) | 10.00 | | VAT on roadside assistance | 1.50 | | **Total charged** | **6028.44** | You do not have to compute this yourself to charge the customer — the Issue Policy API returns the final `price` on the policy object and generates a payment link for exactly that amount. Compute it only to show the customer a breakdown before they commit. Included benefits (`amount` = 0) never change the price. Adding them to the `benefits` array when issuing is unnecessary. #### Arabic localisation fields Each quote object includes Arabic counterparts for the fields that typically appear in the UI. Use these when rendering an Arabic experience: | Field | Arabic equivalent | Notes | | ------------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `company_name` | `company_name_ar` | Arabic name of the insurance company | | `insurance_type_display` | `insurance_type_display_ar` | Arabic label for the insurance type as the provider intends it to be shown. Falls back to the English value for provider-specific types without a translation | | `benefits[].name` | `benefits[].name_ar` | Arabic name of each benefit | `type` is a normalised category value used for filtering and grouping (`TPL`, `TPL +`, `Comprehensive`) and has no Arabic equivalent — use `insurance_type_display_ar` for display purposes. Both languages are present in every quote, so rendering an Arabic quote card never takes a second call. ### List Quotes Requests You can list a paginated list of all the quote requests that your account has generated. In order to do so, you can use the List quote requests API You can filter these by using `owner_id` in the query string. This may be useful in case your customer navigated from one page to another and you need to show the quote requests again (rather than making a new request) Example: GET /car-api-reference/quotes/list-quotes?page=2\&per\_page=1\&owner\_id=1234567890 ### Delete Quotes Requests You can delete some of the requests from the system using the Delete Quotes Requests API. This is rarely used, but may be helpful if you'd like to reduce the items listed. ## Vehicle photos If the customer has selected a comprehensive policy, upload the five photos before you issue the policy — front, back, right, left, and the chassis (VIN) number. Use the Upload Vehicle Photos API, against the quote request and the price the customer selected. This step is required for comprehensive cover. If the photos are not uploaded, the customer cannot continue with the purchase. It must happen before you request the payment OTP. Example of a request ``` POST /api/v1/car-comp/quote-requests/11/attachments HTTP/1.1 Authorization: Bearer ***** Content-Type: multipart/form-data quote_price_id=e059d28e-a519-43af-b9d4-e1cc5d97ecb7 front=@front.jpg back=@back.jpg right=@right.jpg left=@left.jpg chassis=@chassis.jpg ``` Example of a response ``` { "attachments": { "front": "https://cdn.yasmina.ai/vehicle-photos/abc123.jpg", "back": "https://cdn.yasmina.ai/vehicle-photos/def456.jpg", "right": "https://cdn.yasmina.ai/vehicle-photos/ghi789.jpg", "left": "https://cdn.yasmina.ai/vehicle-photos/jkl012.jpg", "chassis": "https://cdn.yasmina.ai/vehicle-photos/mno345.jpg" } } ``` | Position | What it shows | | --------- | ---------------------------------- | | `front` | The front of the vehicle | | `back` | The rear of the vehicle | | `right` | The right-hand side of the vehicle | | `left` | The left-hand side of the vehicle | | `chassis` | The chassis (VIN) number | ### Rules * **All five together.** A partial upload is rejected with a `422`. * **JPG or PNG, up to 3 MB each.** Other formats and anything larger are rejected. * **Once per vehicle.** The insurance provider keeps the first set it accepts. A later upload for the same vehicle still returns `200`, with `already_registered: true` in the response, but the registered photos do not change. Check the photos before sending them. * **Comprehensive only.** A `quote_price_id` belonging to a TPL quote is rejected. ## Issuing policies ### Issue Policy OTP When a customer selects a quotation, they need to go through another OTP check. This time you need to request it through the Issue OTP API The Issue Policy OTP requires the following fields: The three quote identifiers must come from the response returned by the earlier `POST /quote-requests` call. Use the provider quote and price selected by the customer from that same response. | Field | Example Value | Description | | -------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `quote_request_id` | `62` | Use the top-level `id` from the quote request response. | | `quote_reference_id` | `feb9e0ec-d71c-4c60-99d4-22ad9a5c97ec` | Use `quotes[].quote_reference_id` from the insurance provider quote selected by the customer. | | `quote_price_id` | `f0a13788-92c3-f011-972d-005056a9891a` | Use `quotes[].prices[].quote_price_id` from the selected price and deductible inside the same provider quote. | | `owner_id` | `2234567890` | The owner’s national ID (starts with `1` for Saudi nationals) or Iqama ID (starts with `2` for residents). Must be exactly 10 digits. | | `email` | `someone@example.com` | The owner’s email. It must belong to this customer. Do not reuse the same email address for different customers. | | `phone` | `0512345678` | Saudi mobile number. Must start with `05` and be exactly 10 digits. | | `iban` | `SA0380000000608010167519` | The customer's Saudi IBAN (`SA` followed by 22 digits, no spaces). It is sent to the insurance provider with the payment OTP request and used to transfer claim settlements and refunds to the customer; the account is never charged. Required. | Example request: ``` POST /api/v1/car-comp/issue-otp HTTP/1.1 Host: sandbox.yasmina.ai Accept: application/json Authorization: Bearer token Content-Type: application/json Content-Length: 249 { "email": "someone@example.com", "phone": "0512345678", "owner_id": "2234567890", "quote_request_id": 62, "quote_reference_id": "feb9e0ec-d71c-4c60-99d4-22ad9a5c97ec", "quote_price_id": "f0a13788-92c3-f011-972d-005056a9891a", "iban": "SA0380000000608010167519" } ``` The customer will receive a separate policy issuance OTP, and the API returns `204 No Content` on success. This OTP is valid for 15 minutes and must be supplied to the Issue Policy API within that period. If it expires, request a new issuance OTP before issuing the policy. The 8-hour quote OTP validity does not apply here. The policy issuance OTP expires after 15 minutes. ### Issuing a policy In order to Issue a policy. You can head to the Issue Policy API Use the same three identifiers previously sent to the Issue Policy OTP API. They must all come from the earlier `POST /quote-requests` response and represent one consistent customer selection. | Field | Description | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `quote_request_id` | Use the top-level `id` returned by the earlier `POST /quote-requests` call. | | `quote_reference_id` | Use `quotes[].quote_reference_id` from the insurance provider quote selected by the customer in that quote response. | | `quote_price_id` | Use `quotes[].prices[].quote_price_id` from the selected price and deductible inside the same provider quote. | | `benefits` | A list of selected benefit IDs. Only required if the benefit has a cost (`amount > 0`). | | `extra_data` | Optional JSON object to store additional metadata or custom values that can later be used in webhooks. Please keep minimal as it can't exceed 255 characters | | `redirect_url` | Optional URL that the customer gets redirected to once a successful purchase is made | | `otp` | The OTP that you got from the issue-otp API | Example of a request ``` POST /api/v1/car-comp/policies HTTP/1.1 Authorization: Bearer ***** Content-Type: application/json Accept: application/json Content-Length: 212 { "otp": "1234", "quote_request_id": 11, "quote_reference_id": "04486448-3433-43ef-a755-b07799d6580f", "quote_price_id": "e059d28e-a519-43af-b9d4-e1cc5d97ecb7", "benefits": [], "extra_data": { "extra_field": 1 } } ``` Once you make a request to the Issue Policy API, you will get the Policy object with a `201` HTTP response code. Here is an example of the Policy object. ``` { "id": 700, "meta_data": { "extra_data": null, "new_owner_id": "2528297837", "quote_price_id": "f5d52340-3661-48af-b81a-028f251ef6a9", "quote_request_id": 25, "previous_owner_id": "1001364939", "car_sequence_number": 723787810 }, "provider_policy_id": null, "provider_policy": null, "created_at": "2025-10-06T23:31:17.000000Z", "status": 0, "payment_link": "http://localhost:8000/short/wVln4", "price": 6016 } ``` This is a summary of the fields returned in the policy object | Field | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Yasmina’s unique identifier for the policy. | | `meta_data` | A JSON object that contains information about the fields that were used to generate this policy. `extra_data` will also be returned here. | | `provider_policy_id` | The policy ID that is returned by the policy provider. | | `provider_policy` | A URL that contains the policy in PDF format. | | `created_at` | When was the policy issued. | | `status` | 0 = Pending, 1 = Issued. | | \`payment\_link | A secure payment link generated by Yasmina | | `price` | The price of the policy in Saudi Riyal | ### Payment and Policy activation When you first make a request to the Issue Policy API. The Policy is not yet activated and the `status` is `0` (which means pending). Also the `provider_policy` and `provider_policy_id` will both be `null`. In order for the policy to be activated, the customer needs to make the purchase from the payment link. Once the customer successfully pays. The policy will be activated and the `status` becomes `1`. Although the payment page is provided by Yasmina, it does not display the Yasmina logo or have any mention of Yasmina.

Yasmina does not receive credit card information, instead the payment page sends card information directly to the payment vendor. On Sandbox, you can use a testing card with the following information:
Card number: 4111 1111 1111 1111
Expiry: 02/27
CVV: 123
Card owner: Yasmina test ### Redirect URL You can supply the payload a `redirect_url`. This is used to redirect the customer to any page or deep link you need. You can also include a query string with policyID and it will automatically replace it with the actual `id` of the policy object. Example for policy `id` 123 ``` { ..., redirect_url: "https://www.example.com?yasmina_policy_id=policyID" } ``` Will become on the response ``` { redirect_url: "https://www.example.com?yasmina_policy_id=123" } ``` And the customer that purchased the policy will be redirected to [https://www.example.com?yasmina\_policy\_id=123](https://www.example.com?yasmina_policy_id=123) ### Showing a policy In order to get a status of a policy, you can use the Show Policy API. This API, takes a Yasmina Policy `id` and will return the policy object This API is ideal when you want to re-fetch a specific policy after the PDF gets generated. Example of a request ``` GET /api/v1/car-comp/policies/123 HTTP/1.1 Host: production.yasmina.ai Authorization: Bearer Content-Type: application/json Accept: application/json ``` Example a response ``` { "id": 659, "meta_data": { "extra_data": { }, "new_owner_id": "2467701575", "quote_price_id": "097116f9-99b1-491f-a2ab-f86b2c535cbe", "quote_request_id": 4, "previous_owner_id": "2467701575", "car_sequence_number": 52423810 }, "product_id": 4, "provider_policy_id": "53018c24-b246-4bef-866f-4a54c2367196", "provider_policy": "policy.pdf", "created_at": "2025-09-07T07:53:55.000000Z", "status": 1, "payment_link": null, "price": null } ``` ### Listing policies You can also use the List Policies API to get a list of all policies that were generated from our system. You might use this on your admin interface, or if you just want to check what has been generated. # Property Insurance Source: https://docs.yasmina.ai/price-comparison/property Seamlessly embed property insurance into your platform, letting your customers insure their properties with just a click. ## Introduction This guide describes the Property Insurance APIs available on Yasmina’s platform. These APIs cover the core operations required for property insurance. This includes getting prices, issuing and managing policies, generating payment links, and handling claims. Our APIs follow the RESTful standard and are structured to provide consistent inputs and outputs, making them straightforward to integrate, test, and maintain within your systems. ## What you will learn * Getting prices for property insurance * Issuing policies * Uploading images for your insured property * Starting a claim ## Prerequisites 1. **Account in Yasmina** - See the Onboarding section for details. You need to add "Property (Price Comparison)" in the products field. 2. **Authenticated Token** - You can follow the Authentication guide or head straight to the Generate Token API. 3. **Backend server** - Required to securely call Yasmina APIs. ## Quotes ### Get prices Yasmina works with multiple insurance providers. You can retrieve and compare prices using the List Prices API. This helps your customers choose their most suitable option. Currently, we are provide pricing from the following five providers: * Walaa * Medgulf * Tawuniya * Takaful Al-Rajhi * Wataniya ### Address from Short Code The GET Address Endpoint allows you to retrieve the **full property address** by providing only a short address code (e.g., Saudi Post short code). It is especially useful when users enter or scan their short address, and you need to automatically fill in the property details in the form. Example of a request ``` GET /api/v1/property/address-from-short?short_address=RRRC7866 HTTP/1.1 Host: production.yasmina.ai Authorization: Bearer Accept: application/json ``` Example of a response ``` { "building_number": "7866", "zip_code": "13342", "additional_number": "2641", "street_name": "Ahmad Al Gazali", "district_name": "Al Arid Dist.", "city_name": "Riyadh" } ``` Please note that the short address API does not provide *unit\_number*. This needs to be supplied separately to the Issue Policy API ## Policies ### Issue a policy To issue policies, use the Issue Policies API. The following fields are required when creating a Property Insurance request. All requests must conform to these validation rules. | Field | Type | Rules | Description | | ------------------------------------ | ------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `insurance_provider` | string | required, in: `walaa` | This comes from the prices API | | `personal_details` | object | required | Contains personal information of the policyholder. | | `personal_details.name` | string | required, max:255 | Full name of the policyholder in English. Must not contain Arabic characters. | | `personal_details.name_ar` | string | required, max:255 | Full name of the policyholder in Arabic script. | | `personal_details.gender` | string | required, in: `M`, `F` | Gender of the policyholder. | | `personal_details.email` | string | required, max:255 | Email address of the policyholder. | | `personal_details.phone_number` | string | required, regex: `/^\+\d{10,15}$/` | Phone number in **international format** (e.g., `+966512345678`). | | `personal_details.birthdate` | date | required | Date of birth (ISO 8601 format recommended, e.g., `1990-05-20`). | | `personal_details.nationality` | string | required, in: list of supported countries | Country code of nationality (must match supported country codes). | | `personal_details.nationality_id` | string | required, max:20 | National ID, Iqama, or passport number. | | `building_details` | object | required | Details of the insured building. | | `building_details.building_age` | integer | required, min:0 | Age of the building in years. | | `building_details.building_type` | string | required, in: `apartment`, `villa`, `private_accommodation` | Type of property. | | `building_details.apartment_size` | integer | required, min:0 | Size of apartment in square meters (if applicable). | | `address` | object | required | Full address of the property. | | `address.street_name` | string | required, max:255 | Street name of the property. | | `address.building_number` | string | required, max:50 | Building number. | | `address.district_name` | string | required, max:255 | District/area name. | | `address.city_name` | string | required, in: availableCities config | City name (must match Yasmina’s supported cities list). | | `address.additional_number` | string | required, max:20 | Additional number (Saudi address standard). | | `address.zip_code` | string | required, max:20 | Zip/postal code. | | `address.unit_number` | string | required, max:20 | Unit/flat number. | | `property_cost` | numeric | nullable, required\_without: `contents_cost` | Estimated value of the building/property. Required if `contents_cost` is not provided. | | `contents_cost` | numeric | nullable, required\_without: `property_cost` | Estimated value of the home contents. Required if `property_cost` is not provided. | | `iban` | string | required, regex: `/^SA\d{22}$/` | The customer's Saudi IBAN (`SA` followed by 22 digits, no spaces). Insurance providers use it to transfer claim settlements and refunds directly to the customer; the account is never charged. | | `start_date` | date | required, after: today | Desired policy start date in `YYYY-MM-DD` format. Must be tomorrow or later. | | `has_agreed_to_terms_and_conditions` | boolean | accepted (`true`, `1`, `yes`) | Must explicitly confirm acceptance of terms and conditions. | Example request: ``` POST /api/v1/property/policies HTTP/1.1 Host: localhost:8000 Accept: application/json Content-Type: application/json Authorization: •••••• Content-Length: 868 { "insurance_provider": "walaa", "personal_details": { "email": "someone@example.com", "gender": "M", "name": "Customer Name", "name_ar": "اسم العميل", "phone_number": "+9665XXXXXXX", "birthdate": "1990-01-01", "nationality": "JO", "nationality_id": "**********" }, "building_details": { "building_age": 20, "building_type": "villa", "apartment_size": 200 }, "address": { "street_name": "Street Name", "district_name": "District Name", "city_name": "Riyadh", "additional_number": "X", "zip_code": "XXXXX", "unit_number": "X", "building_number": "X" }, "property_cost": 500000, "contents_cost": 100000, "iban": "SA0380000000608010167519", "start_date": "2025-12-11", "has_agreed_to_terms_and_conditions": true, "redirect_url": "https://www.example.com?policy_id=XXXXXX" } ``` Example Response ``` { "id": 874, "meta_data": { "address": { "zip_code": "11193", "city_name": "Riyadh", "street_name": "Street Name", "unit_number": "X", "district_name": "District Name", "building_number": "X", "additional_number": "X" }, "property_cost": 500000, "building_details": { "building_age": 20, "building_type": "villa", "apartment_size": 200 }, "personal_details": { "name": "Customer Name", "name_ar": "اسم العميل", "email": "someone@example.com", "gender": "M", "birthdate": "1990-01-01", "nationality": "JO", "phone_number": "+96279XXXXXXX", "nationality_id": "**********" }, "insurance_provider": "walaa", "iban": "SA0380000000608010167519", "start_date": "2025-12-11", "has_agreed_to_terms_and_conditions": true }, "created_at": "2025-11-20T12:06:09.000000Z", "canceled_at": null, "status": 0, "provider_policy": null, "provider_policy_id": null, "client_id": "********-****-****-****-************", "payment_link": "http://localhost:8000/short/XXXXX", "price": 603.75, "redirect_url": "https://www.google.com?policy_id=874", "policy_url": null } ``` ### Retrieving the policy object again You can retrieve the policy objects that were created by you any time by either using the Listing policies API or the Show policy API The Listing policy API can take some filters to retrieve only specific policies. This might be helpful if you have your own internal system and want to list policies by different values. Example Request ``` GET /api/v1/property/policies?nationality_id=9881052027 HTTP/1.1 Accept: application/json Authorization: •••••• ``` The Show Policy API will retrieves a specific policy object based on path ID Example Request ``` GET /api/v1/property/policies/875 HTTP/1.1 Accept: application/json Authorization: •••••• ``` ### Cancellation Status The Cancellation Status API provides real-time visibility into the cancellation state of a policy. Upon receiving a request, Yasmina initiates a query to the relevant insurance provider, fetches the current policy information, and returns a structured response reflecting the latest cancellation status. This ensures your system always displays accurate and timely policy data. Example Request ``` GET /api/v1/property/policies/849/cancellation-status HTTP/1.1 Accept: application/json Authorization: •••••• ``` Example Response ``` { "status": "active" } ``` ### Payment and Policy activation When you first make a request to the Issue Policy API. The Policy is not yet activated and the `status` is `0` (which means pending). Also the `provider_policy` and `provider_policy_id` will both be `null`. In order for the policy to be activated, the customer needs to make the purchase from the payment link. Once the customer successfully pays. The policy will be activated and the `status` becomes `1`. Although the payment page is provided by Yasmina, it does not display the Yasmina logo or have any mention of Yasmina.

Yasmina does not receive credit card information, instead the payment page sends card information directly to the payment vendor. On Sandbox, you can use a testing card with the following information:
Card number: 4111 1111 1111 1111
Expiry: 02/27
CVV: 123
Card owner: Yasmina test ### Redirect URL You can supply the payload a `redirect_url`. This is used to redirect the customer to any page or deep link you need. You can also include a query string with policyID and it will automatically replace it with the actual `id` of the policy object. Example for policy `id` 123 ``` { ..., redirect_url: "https://www.example.com?yasmina_policy_id=policyID" } ``` Will become on the response ``` { ..., redirect_url: "https://www.example.com?yasmina_policy_id=123" } ``` And the customer that purchased the policy will be redirected to [https://www.example.com?yasmina\_policy\_id=123](https://www.example.com?yasmina_policy_id=123) ### Upload Images Supporting documents are required from your clients. These can include home photos, images of valuable contents, or surrounding areas. You can upload these documents using the Upload Document API # SME Medical Insurance Source: https://docs.yasmina.ai/price-comparison/sme-medical-insurance Compare SME medical insurance packages from multiple providers, issue policies for employees, and collect their health declarations.

Build it with AI — an AI coding assistant can scaffold this entire integration for you straight from these docs. See Build with AI to get started.

Want to try it before writing code? Download the [Postman collection](https://docs.yasmina.ai/postman/sme-medical-insurance.postman_collection.json), set your sandbox `client_id` and `client_secret` in its variables, and run it top to bottom. ## Introduction This guide walks you through integrating Yasmina's **SME Medical Insurance Price Comparison APIs** into your platform (for the single-provider version, [click here](/single-provider-integrations/sme-medical-insurance)). These APIs let you retrieve and compare medical insurance packages from several insurance providers before issuing policies to a company's employees. Using our secure and reliable endpoints, you'll be able to request and manage policies, and issue claims. Everything you need to deliver insurance services seamlessly within your application. ### Basic Journey 1. **Authorize**: Get an access token to authenticate all API requests. 2. **Create a Company**: Register the SME that will provide medical insurance for its employees. 3. **Add the Employees**: Save the company's employees, each with the tier they want. 4. **Get Prices**: One request prices those employees with every insurance provider at once. 5. **Issue the Policy**: Pick a quote and issue the company's policy from it. 6. **Health Declarations**: Get the declaration questions, download a printable form, or fill them in on the employees' behalf. 7. **Payment**: Read the policy for its payment link, share it, and get the policy document once it clears. ## Authorization To access any of our API's. You need to authorize yourself using the Generate Token API. We are using the standard OAuth 2.0 client credentials.
The Generate Token API requires `client_id` and `client_secret`. You can get these from your [portal](https://portal.yasmina.ai/api-management).
After making the request, you will get access\_token in the response. The `access_token` must be used on all future Yasmina APIs and be supplied in the Authorization Header in the following form Authorization: Bearer \{access\_token} For security reasons. Do not make your client\_id and client\_secret public in your platform. ## Companies ### Create a Company record After acquiring an access\_token, you can begin using the APIs. Before you produce policies for a company, you must create a company record. After creating the company record, you can request to issue policies to the employees of that company. The The Create Company API, will require a few fields that define details of the company such as Email, Phone, the company's unified national number, a 10-digit sponsor number, and a 10-digit commercial registration number that starts with 7. It will return a response with a unique identifier (id). Here is an example of the response from the POST companies API. ``` { "name": "Example company name", "name_ar": "مثال اسم شركة", "sponsor_number": "1000000001", "unified_national_number": "7000000001", "email_address": "example@example.com", "phone_number": "+966512345678", "commercial_registration_number": "7000000002", "client_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "updated_at": "2025-08-01T14:22:30.000000Z", "created_at": "2025-08-01T14:22:30.000000Z", "id": 42 } ``` You can also visit the [List companies API](/medical-api-reference/company/list-companies) to show all companies you've created ## Prices ### Compare the packages Every insurance provider sells the same four tiers, so an employee's choice can be priced by all of them: `basic`, `standard`, `premium` and `executive`. What each provider puts inside a tier, and what it charges for it, is its own. The [Categories API](/medical-api-reference/products/list-categories) shows one provider's tiers at a time; call it once per provider, passing `insurance_provider` as one of the values below, or omit it for MedGulf. | Insurance provider | `insurance_provider` | | ------------------ | -------------------- | | MedGulf (default) | `medgulf` | | Walaa | `walaa` | | Al-Rajhi Takaful | `alrajhi` | | Tawuniya | `tawuniya` | | Malath | `malath` | Each response carries the provider as `insurance_provider` and its display name as `insurance_provider_name`, then: 1. The Insurance provider PDF * Contains an overview picture of what is provided by the Insurance provider 2. The translations * The translations includes **keys** that map to the instructional text in Arabic and English that were provided by the insurance provider. 3. The categories * One entry per tier, with the coverage values and the yearly `price` per person Coverage values can either be a number (the amount), or a boolean (whether it's covered or not), or a text (the type of coverage). ``` "insurance_provider": "medgulf", "insurance_provider_name": "MedGulf", "medgulf_pdf": "https://...", "translations": { ... }, "categories": { "basic": { "name": "Basic", "category": "basic", "insurance_provider": "medgulf", "price": 300, "maximum_annual_benefit_limit_per_person": 500000, "geography": "Saudi Arabia", "general_coverage": { ... } ... } ``` ### Add the employees The [Employees API](/medical-api-reference/employees/save-the-employees) holds the company's employee list: who is covered, their dependents, and the tier each has picked. It prices nothing. Send the whole list; each call replaces the one before, and you can read it back at any time. ``` { "employees": [ { "name": "John Doe", "nationality_iso": "SA", "category": "basic", "nationality_id": "1111111111", "mobile_number": "0500000001", "date_of_birth": "1409-09-14", "dependents": [ { "name": "Jane Doe", "relationship": "spouse", "nationality_iso": "SA", "nationality_id": "1111111112", "date_of_birth": "1411-01-05" }, { "name": "Jack Doe", "relationship": "child", "nationality_iso": "SA", "nationality_id": "1111111113", "date_of_birth": "1437-04-22" } ] }, { "name": "Richard Roe", "nationality_iso": "JO", "category": "executive", "iqama_id": "2222222222", "mobile_number": "0500000002", "date_of_birth": "1988-04-20", "dependents": [] } ] } ``` John is Saudi (`nationality_iso` is `SA`), so we supply his `nationality_id`. Richard is not Saudi, so we supply his `iqama_id` instead. The API rejects the request if a Saudi employee has no `nationality_id` or a non-Saudi employee has no `iqama_id`. Every identifier, for employees and dependents alike, must be exactly 10 digits, and every employee needs a `mobile_number`. Each employee's `category` is one of the four tiers. Employees can be on different tiers. #### Dependents An employee can bring family members onto the policy through the `dependents` array. Each dependent needs a `name`, a `relationship` to the employee (`spouse`, `child` or `parent`), a `nationality_iso`, a `date_of_birth`, and the same identifier rule as the employee: a 10-digit `nationality_id` for Saudis, a 10-digit `iqama_id` for everyone else. Dependents do not carry their own mobile number. Dependents are covered under the employee's tier; they cannot have one of their own. Leave the array out, or send it empty, for an employee with no dependents. #### Dates of birth Send every `date_of_birth` as `YYYY-MM-DD`. Saudi nationals whose national id starts with `1` give the Hijri (Umm al-Qura) date printed on their id, as John and his family do above; everyone else gives a Gregorian date. Employees must be between 18 and 110 years old; dependents can be any age. ### Get prices from every provider Call the [Quote request API](/medical-api-reference/quotes/get-prices-from-every-provider) with the `company_id` and you get one response with a quote from every insurance provider, each priced for the employees saved above at the tiers they picked. Every quote carries a `quote_price_id`; the response itself carries an `id`, the `quote_request_id`. Keep both for the next step. ``` { "id": "a2bc93db-131e-4726-8a0a-0fed1da5ac0f", "company_id": 1, "employees": [ ... ], "quotes": [ { "quote_price_id": "3fb4e3bb-6c7e-4a8f-9d2a-1b3c5d7e9f01", "insurance_provider": "medgulf", "insurance_provider_name": "MedGulf", "total_price": 1600, "currency": "SAR", "employees": [ { "name": "John Doe", "identifier": "1111111111", "category": "basic", "dependents": 2, "price": 300 }, { "name": "Richard Roe", "identifier": "2222222222", "category": "executive", "dependents": 0, "price": 1300 } ] }, { "quote_price_id": "...", "insurance_provider": "walaa", "total_price": 1700, ... }, ... ] } ``` `total_price` is what the company pays for a year of cover with that provider, and the `employees` lines show where it comes from. A quote prices the employees as they stood when it was asked for; change the list and ask again. ## Policies ### Issue the policy A company buys one policy, and its employees are the members on it, which is how the insurer issues it and how the policy document reads. Call the [Issue policy API](/medical-api-reference/policies/issue-the-policy) with the `quote_request_id` and the `quote_price_id` of the quote the company chose, and you get that one policy back: the provider that priced it, the quoted total as `price`, and every employee inside `meta_data.insured`. ``` { "quote_request_id": "a2bc93db-131e-4726-8a0a-0fed1da5ac0f", "quote_price_id": "3fb4e3bb-6c7e-4a8f-9d2a-1b3c5d7e9f01", "redirect_url": "https://www.example.com?yasmina_policy_id=policyID" } ``` A company has one policy waiting to be paid for at a time. Issue again before payment, from a different quote if you like, and it is replaced. Once it is paid for, the next issue starts a new policy. ### Health declaration forms Insurers require a past medical history from every employee before they will cover them. Yasmina publishes the questions and prints the form; the company collects the answers itself, on paper or inside your own platform. 1. **The questions**: the [Medical form API](/medical-api-reference/medical-forms/get-the-medical-form-questions) returns every question, grouped the way the insurers ask them, so you can build your own screen for it. 2. **The printable form**: the [Download declaration form API](/medical-api-reference/medical-forms/download-the-declaration-form) returns the same declaration as a PDF. Pass the `policy_id` and the file carries one page per employee on the policy, with their name, id and package filled in, ready to print or email. Leave `policy_id` out for a single blank form. 3. **Filling them in for the employees**: a company admin can answer on their behalf with the [Fill the declarations API](/medical-api-reference/medical-forms/fill-the-declarations), addressed to the policy. It takes `all_employees`, the default answers for everyone, and `ids_or_emails`, the employees whose answers differ. Name an employee by their `nationality_id` or `iqama_id`; one that is not on the policy is rejected. The answers are stored on the policy's members, and the policy comes back with `pending_declarations` telling you who is still missing. For example, if nobody has had surgery except [john.doe@example.com](mailto:john.doe@example.com), declare `No` for `past_surgeries` under `all_employees` and override that one employee: ``` { "all_employees": { "allergies": "No", "current_medications": "No", "hospitalizations": "No", "pre_existing_conditions": "No", "past_surgeries": "No", "surgery_complications": "No", "chest_pain_or_breathlessness": "No", "heart_procedures": "No", "smoking": "No", "alcohol_consumption": "No", "physical_activity": "No", "family_history": "No", "chronic_disease": ["None of the above"] }, "ids_or_emails": [ { "id_or_email": "john.doe@example.com", "answers": { "allergies": "No", "current_medications": "No", "hospitalizations": "No", "pre_existing_conditions": "No", "past_surgeries": "Yes", "surgery_complications": "No", "chest_pain_or_breathlessness": "No", "heart_procedures": "No", "smoking": "No", "alcohol_consumption": "No", "physical_activity": "No", "family_history": "No", "chronic_disease": ["Liver Disease"] } } ] } ``` ### Payment Everything needed to take payment is on the policy object. [Read the policy](/medical-api-reference/policies/read-the-policy) and you get: * `price`: what the company pays for a year of cover. * `pending_declarations`: the employees who still have to declare their medical history. The insurers will not cover anyone who has not, so while this list is not empty there is nothing to pay for. * `payment_link`: where the company pays, once `pending_declarations` is empty. It opens Yasmina's secure card page, where the company pays for all of its employees in one go. It is a fresh signed link on every read and expires after 15 minutes, so read the policy when the buyer is ready to pay rather than storing the link. It is null while anyone still has to declare, and again once the policy is issued. The policy returned by issuing and by filling the declarations carries the same fields, so in the simplest flow you issue, fill, and send the customer to the link on the response. ### Payment and Policy activation When you first issue the policy, it is not yet activated and the `status` is `0` (which means pending). Also the `provider_policy` and `provider_policy_id` will both be `null`. In order for the policy to be activated, the customer needs to make the purchase from the payment link. Once the customer successfully pays. The policy will be activated and the `status` becomes `1`, and the policy schedule listing every member becomes available through the [List policies API](/medical-api-reference/policies/list-policies). Although the payment page is provided by Yasmina, it does not display the Yasmina logo or have any mention of Yasmina.

Yasmina does not receive credit card information, instead the payment page sends card information directly to the payment vendor. On Sandbox, you can use a testing card with the following information:
Card number: 4111 1111 1111 1111
Expiry: 02/27
CVV: 123
Card owner: Yasmina test ### Redirect URL You can supply the payload a `redirect_url`. This is used to redirect the customer to any page or deep link you need. You can also include a query string with policyID and it will automatically replace it with the actual `id` of the policy object. Example for policy `id` 123 ``` { ..., redirect_url: "https://www.example.com?yasmina_policy_id=policyID" } ``` Will become on the response ``` { ..., redirect_url: "https://www.example.com?yasmina_policy_id=123" } ``` And the customer that purchased the policy will be redirected to [https://www.example.com?yasmina\_policy\_id=123](https://www.example.com?yasmina_policy_id=123) # Get full address from short address code Source: https://docs.yasmina.ai/property-api-reference/addresses/get-full-address-from-short-address-code /property-api-reference/openapi.json get /address-from-short This endpoint retrieves the full address details based on the provided short address code. Useful for auto-filling property address information when only the short code is available. # Issue claim Source: https://docs.yasmina.ai/property-api-reference/claims/issue-claim /property-api-reference/openapi.json post /policies/{propertyPolicy}/claims Issue a claim to your policy # Cancellation status Source: https://docs.yasmina.ai/property-api-reference/policies/cancellation-status /property-api-reference/openapi.json get /policies/{propertyPolicy}/cancellation-status Get an updated cancellation status on the policy # Issue policy Source: https://docs.yasmina.ai/property-api-reference/policies/issue-policy /property-api-reference/openapi.json post /policies For issuing a new policy # List policies Source: https://docs.yasmina.ai/property-api-reference/policies/list-policies /property-api-reference/openapi.json get /policies Listing requested policies # Show policy Source: https://docs.yasmina.ai/property-api-reference/policies/show-policy /property-api-reference/openapi.json get /policies/{propertyPolicy} Show a specific policy # Upload documents Source: https://docs.yasmina.ai/property-api-reference/policies/upload-documents /property-api-reference/openapi.json post /policies/{propertyPolicy}/documents Upload supporting documents for the related property or contents # List prices Source: https://docs.yasmina.ai/property-api-reference/prices/list-prices /property-api-reference/openapi.json get /prices Shows prices from different insurance companies based on the provided property and contents cost. You must provide at least one of property_cost or contents_cost. You can also provide both # Dotnet Source: https://docs.yasmina.ai/sdks/dotnet # Yasminaai C# Library [![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github\&utm_medium=github\&utm_campaign=readme\&utm_source=https%3A%2F%2Fgithub.com%2FYasminaAI%2Fmotor-dotnet-sdk) [![nuget shield](https://img.shields.io/nuget/v/Yasmina.Motor.DotNet)](https://nuget.org/packages/Yasmina.Motor.DotNet) The Yasminaai C# library provides convenient access to the Yasminaai APIs from C#. ## Table of Contents * [Requirements](#requirements) * [Installation](#installation) * [Reference](#reference) * [Usage](#usage) * [Environments](#environments) * [Exception Handling](#exception-handling) * [Advanced](#advanced) * [Retries](#retries) * [Timeouts](#timeouts) * [Raw Response](#raw-response) * [Additional Headers](#additional-headers) * [Additional Query Parameters](#additional-query-parameters) * [Forward Compatible Enums](#forward-compatible-enums) * [Contributing](#contributing) ## Requirements This SDK requires: ## Installation ```sh theme={null} dotnet add package Yasmina.Motor.DotNet ``` ## Reference A full reference for this library is available [here](https://github.com/YasminaAI/motor-dotnet-sdk/blob/HEAD/./reference.md). ## Usage Instantiate and use the client with the following: ```csharp theme={null} using YasminaaiApi; var client = new YasminaaiApiClient("TOKEN"); await client.Quotes.RequestQuotesAsync( new PostQuoteRequestsRequest { Otp = "123456", OwnerId = "owner_id", Phone = "phone", Birthdate = new DateOnly(2023, 1, 15), CarEstimatedCost = 1.1, } ); ``` ## Environments This SDK allows you to configure different environments for API requests. ```csharp theme={null} using YasminaaiApi; var client = new YasminaaiApiClient(new ClientOptions { BaseUrl = YasminaaiApiEnvironment.Sandbox }); ``` ## Exception Handling When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error will be thrown. ```csharp theme={null} using YasminaaiApi; try { var response = await client.Quotes.RequestQuotesAsync(...); } catch (YasminaaiApiApiException e) { System.Console.WriteLine(e.Body); System.Console.WriteLine(e.StatusCode); // Access the raw HTTP response (status code, URL, headers) off the exception var rawResponse = e.RawResponse; if (rawResponse != null) { System.Console.WriteLine(rawResponse.Url); if (rawResponse.Headers.TryGetValue("X-Request-Id", out var requestId)) { System.Console.WriteLine($"Request ID: {requestId}"); } } } ``` ## Advanced ### Retries The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2). Which status codes are retried depends on the `retryStatusCodes` generator configuration: **`legacy`** (current default): retries on * [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout) * [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests) * [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) (All server errors, including 500) **`recommended`**: retries on * [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout) * [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests) * [502](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502) (Bad Gateway) * [503](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503) (Service Unavailable) * [504](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504) (Gateway Timeout) Use the `MaxRetries` request option to configure this behavior. ```csharp theme={null} var response = await client.Quotes.RequestQuotesAsync( ..., new RequestOptions { MaxRetries: 0 // Override MaxRetries at the request level } ); ``` ### Timeouts The SDK defaults to a 30 second timeout. Use the `Timeout` option to configure this behavior. ```csharp theme={null} var response = await client.Quotes.RequestQuotesAsync( ..., new RequestOptions { Timeout: TimeSpan.FromSeconds(3) // Override timeout to 3s } ); ``` ### Raw Response Access raw HTTP response data (status code, headers, URL) alongside parsed response data using the `.WithRawResponse()` method. ```csharp theme={null} using YasminaaiApi; // Access raw response data (status code, headers, etc.) alongside the parsed response var result = await client.Quotes.RequestQuotesAsync(...).WithRawResponse(); // Access the parsed data var data = result.Data; // Access raw response metadata var statusCode = result.RawResponse.StatusCode; var headers = result.RawResponse.Headers; var url = result.RawResponse.Url; // Access specific headers (case-insensitive) if (headers.TryGetValue("X-Request-Id", out var requestId)) { System.Console.WriteLine($"Request ID: {requestId}"); } // For the default behavior, simply await without .WithRawResponse() var data = await client.Quotes.RequestQuotesAsync(...); // .WithRawResponse() also works on streaming endpoints (returns IAsyncEnumerable + RawResponse) // and on endpoints with no response body (returns RawResponse only). ``` ### Additional Headers If you would like to send additional headers as part of the request, use the `AdditionalHeaders` request option. ```csharp theme={null} var response = await client.Quotes.RequestQuotesAsync( ..., new RequestOptions { AdditionalHeaders = new Dictionary { { "X-Custom-Header", "custom-value" } } } ); ``` ### Additional Query Parameters If you would like to send additional query parameters as part of the request, use the `AdditionalQueryParameters` request option. ```csharp theme={null} var response = await client.Quotes.RequestQuotesAsync( ..., new RequestOptions { AdditionalQueryParameters = new Dictionary { { "custom_param", "custom-value" } } } ); ``` ### Forward Compatible Enums This SDK uses forward-compatible enums that can handle unknown values gracefully. ```csharp theme={null} using YasminaaiApi; // Using a built-in value var postQuoteRequestsRequestAcceptLanguage = PostQuoteRequestsRequestAcceptLanguage.Ar; // Using a custom value var customPostQuoteRequestsRequestAcceptLanguage = PostQuoteRequestsRequestAcceptLanguage.FromCustom("custom-value"); // Using in a switch statement switch (postQuoteRequestsRequestAcceptLanguage.Value) { case PostQuoteRequestsRequestAcceptLanguage.Values.Ar: Console.WriteLine("Ar"); break; default: Console.WriteLine($"Unknown value: {postQuoteRequestsRequestAcceptLanguage.Value}"); break; } // Explicit casting string postQuoteRequestsRequestAcceptLanguageString = (string)PostQuoteRequestsRequestAcceptLanguage.Ar; PostQuoteRequestsRequestAcceptLanguage postQuoteRequestsRequestAcceptLanguageFromString = (PostQuoteRequestsRequestAcceptLanguage)"ar"; ``` ## Contributing While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us! On the other hand, contributions to the README are always very welcome! # Go Source: https://docs.yasmina.ai/sdks/go # Yasminaai Go Library [![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github\&utm_medium=github\&utm_campaign=readme\&utm_source=https%3A%2F%2Fgithub.com%2FYasminaAI%2Fmotor-go-sdk) The Yasminaai Go library provides convenient access to the Yasminaai APIs from Go. ## Table of Contents * [Reference](#reference) * [Usage](#usage) * [Environments](#environments) * [Errors](#errors) * [Request Options](#request-options) * [Advanced](#advanced) * [Response Headers](#response-headers) * [Retries](#retries) * [Timeouts](#timeouts) * [Explicit Null](#explicit-null) * [Contributing](#contributing) ## Reference A full reference for this library is available [here](https://github.com/YasminaAI/motor-go-sdk/blob/HEAD/./reference.md). ## Usage Instantiate and use the client with the following: ```go theme={null} package example import ( context "context" motorgosdk "github.com/YasminaAI/motor-go-sdk" client "github.com/YasminaAI/motor-go-sdk/client" option "github.com/YasminaAI/motor-go-sdk/option" ) func do() { client := client.NewClient( option.WithToken( "", ), ) request := &motorgosdk.PostQuoteRequestsRequest{ Otp: "123456", OwnerID: "owner_id", Phone: "phone", Birthdate: motorgosdk.MustParseDate( "2023-01-15", ), CarEstimatedCost: 1.1, } client.Quotes.RequestQuotes( context.TODO(), request, ) } ``` ## Environments You can choose between different environments by using the `option.WithBaseURL` option. You can configure any arbitrary base URL, which is particularly useful in test environments. ```go theme={null} client := client.NewClient( option.WithBaseURL(api.Environments.Sandbox), ) ``` ## Errors Structured error types are returned from API calls that return non-success status codes. These errors are compatible with the `errors.Is` and `errors.As` APIs, so you can access the error like so: ```go theme={null} response, err := client.Quotes.RequestQuotes(...) if err != nil { var apiError *core.APIError if errors.As(err, apiError) { // Do something with the API error ... } return err } ``` ## Request Options A variety of request options are included to adapt the behavior of the library, which includes configuring authorization tokens, or providing your own instrumented `*http.Client`. These request options can either be specified on the client so that they're applied on every request, or for an individual request, like so: > Providing your own `*http.Client` is recommended. Otherwise, the `http.DefaultClient` will be used, > and your client will wait indefinitely for a response (unless the per-request, context-based timeout > is used). ```go theme={null} // Specify default options applied on every request. client := client.NewClient( option.WithToken(""), option.WithHTTPClient( &http.Client{ Timeout: 5 * time.Second, }, ), ) // Specify options for an individual request. response, err := client.Quotes.RequestQuotes( ..., option.WithToken(""), ) ``` ## Advanced ### Response Headers You can access the raw HTTP response data by using the `WithRawResponse` field on the client. This is useful when you need to examine the response headers received from the API call. (When the endpoint is paginated, the raw HTTP response data will be included automatically in the Page response object.) ```go theme={null} response, err := client.Quotes.WithRawResponse.RequestQuotes(...) if err != nil { return err } fmt.Printf("Got response headers: %v", response.Header) fmt.Printf("Got status code: %d", response.StatusCode) ``` ### Retries The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2). Which status codes are retried depends on the `retryStatusCodes` generator configuration: **`legacy`** (current default): retries on * [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout) * [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests) * [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) (All server errors, including 500) **`recommended`**: retries on * [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout) * [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests) * [502](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502) (Bad Gateway) * [503](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503) (Service Unavailable) * [504](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504) (Gateway Timeout) If the `Retry-After` header is present in the response, the SDK will prioritize respecting its value exactly over the default exponential backoff. Use the `option.WithMaxAttempts` option to configure this behavior for the entire client or an individual request: ```go theme={null} client := client.NewClient( option.WithMaxAttempts(1), ) response, err := client.Quotes.RequestQuotes( ..., option.WithMaxAttempts(1), ) ``` ### Timeouts Setting a timeout for each individual request is as simple as using the standard context library. Setting a one second timeout for an individual API call looks like the following: ```go theme={null} ctx, cancel := context.WithTimeout(ctx, time.Second) defer cancel() response, err := client.Quotes.RequestQuotes(ctx, ...) ``` ### Explicit Null If you want to send the explicit `null` JSON value through an optional parameter, you can use the setters\ that come with every object. Calling a setter method for a property will flip a bit in the `explicitFields` bitfield for that setter's object; during serialization, any property with a flipped bit will have its omittable status stripped, so zero or `nil` values will be sent explicitly rather than omitted altogether: ```go theme={null} type ExampleRequest struct { // An optional string parameter. Name *string `json:"name,omitempty" url:"-"` // Private bitmask of fields set to an explicit value and therefore not to be omitted explicitFields *big.Int `json:"-" url:"-"` } request := &ExampleRequest{} request.SetName(nil) response, err := client.Quotes.RequestQuotes(ctx, request, ...) ``` ## Contributing While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us! On the other hand, contributions to the README are always very welcome! # Yasmina iOS SDK Source: https://docs.yasmina.ai/sdks/ios Integrate Yasmina embedded insurance services into your native iOS apps with the YasminaSDKKit package. # YasminaSDKKit for iOS YasminaSDKKit is the official iOS client for embedding Yasmina insurance experiences into native apps. It is distributed as a prebuilt `.xcframework` and works with Swift Package Manager or CocoaPods. ## Requirements * iOS 13.0 or later * Xcode 15 or later * Swift 5.9 or later ## Installation ### Swift Package Manager Add the package from `https://github.com/YasminaAI/Yasmina-iOS.git` and select version `0.0.1` (or newer). ```swift Package.swift theme={null} .dependencies: [ .package(url: "https://github.com/YasminaAI/Yasmina-iOS.git", from: "0.0.1") ] ``` ### CocoaPods Use the Git repository and tag `0.0.1` from your `Podfile`. ```ruby Podfile theme={null} pod 'YasminaSDKKit', :git => 'https://github.com/YasminaAI/Yasmina-iOS.git', :tag => '0.0.1' ``` Then install: ```bash Terminal theme={null} pod install ``` ## Quick Start 1. Import the SDK and configure it for your environment. ```swift Swift theme={null} import YasminaSDKKit let config = YasminaConfig( environment: .sandbox, // or .production authorization: "", enableLogging: true, logLevel: .all, apiVersion: "v1" ) YasminaSdk.Companion.shared.doInit(config: config) ``` 2. Request an OTP to validate the flow. ```swift Swift theme={null} YasminaSdk.Companion.shared.get().OTPforQuoteVerification( ownerId: "", email: "", phone: "" ) { response, error in if let error = error { print("Error: \(error.message)") return } print("OTP requested successfully") } ``` 3. After validating the OTP, request multi-provider quotes. ```swift Swift theme={null} YasminaSdk.Companion.shared.get().requestMultiProvidersCarQuotes( ownerId: "", email: "", phone: "", birthdate: "", carSequenceNumber: "", isOwnershipTransfer: true, currentCarOwnerId: "", carEstimatedCost: 45000, carModelYear: 2025, otp: "" ) { response, error in if let error = error { print("Error: \(error.message)") return } print("Response \(String(describing: response))") } ``` ## Support * GitHub issues: [Yasmina-iOS](https://github.com/YasminaAI/Yasmina-iOS/issues) * Email: [support@yasmina.ai](mailto:support@yasmina.ai) ## License Distributed under the MIT License. See the `LICENSE` file in the SDK repository for details. # Java Source: https://docs.yasmina.ai/sdks/java # Yasminaai Java Library [![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github\&utm_medium=github\&utm_campaign=readme\&utm_source=https%3A%2F%2Fgithub.com%2FYasminaAI%2Fmotor-java-sdk) [![Maven Central](https://img.shields.io/maven-central/v/io.github.yasminaai/motor-java)](https://central.sonatype.com/artifact/io.github.yasminaai/motor-java) The Yasminaai Java library provides convenient access to the Yasminaai APIs from Java. ## Table of Contents * [Installation](#installation) * [Reference](#reference) * [Usage](#usage) * [Environments](#environments) * [Base Url](#base-url) * [Exception Handling](#exception-handling) * [Advanced](#advanced) * [Custom Client](#custom-client) * [Retries](#retries) * [Timeouts](#timeouts) * [Custom Headers](#custom-headers) * [Access Raw Response Data](#access-raw-response-data) * [Contributing](#contributing) ## Installation ### Gradle Add the dependency in your `build.gradle` file: ```groovy theme={null} dependencies { implementation 'io.github.yasminaai:motor-java:0.1.0' } ``` ### Maven Add the dependency in your `pom.xml` file: ```xml theme={null} io.github.yasminaai motor-java 0.1.0 ``` ## Reference A full reference for this library is available [here](https://github.com/YasminaAI/motor-java-sdk/blob/HEAD/./reference.md). ## Usage Instantiate and use the client with the following: ```java theme={null} package com.example.usage; import com.yasminaai.api.YasminaaiApiClient; import com.yasminaai.api.resources.quotes.requests.PostQuoteRequestsRequest; public class Example { public static void main(String[] args) { YasminaaiApiClient client = YasminaaiApiClient .builder() .token("") .build(); client.quotes().requestQuotes( PostQuoteRequestsRequest .builder() .otp("123456") .ownerId("owner_id") .phone("phone") .birthdate("2023-01-15") .carEstimatedCost(1.1) .build() ); } } ``` ## Environments This SDK allows you to configure different environments for API requests. ```java theme={null} import com.yasminaai.api.YasminaaiApiClient; import com.yasminaai.api.core.Environment; YasminaaiApiClient client = YasminaaiApiClient .builder() .environment(Environment.Sandbox) .build(); ``` ## Base Url You can set a custom base URL when constructing the client. ```java theme={null} import com.yasminaai.api.YasminaaiApiClient; YasminaaiApiClient client = YasminaaiApiClient .builder() .url("https://example.com") .build(); ``` ## Exception Handling When the API returns a non-success status code (4xx or 5xx response), an API exception will be thrown. ```java theme={null} import com.yasminaai.api.core.YasminaaiApiApiException; try{ client.quotes().requestQuotes(...); } catch (YasminaaiApiApiException e){ // Do something with the API exception... } ``` ## Advanced ### Custom Client This SDK is built to work with any instance of `OkHttpClient`. By default, if no client is provided, the SDK will construct one. However, you can pass your own client like so: ```java theme={null} import com.yasminaai.api.YasminaaiApiClient; import okhttp3.OkHttpClient; OkHttpClient customClient = ...; YasminaaiApiClient client = YasminaaiApiClient .builder() .httpClient(customClient) .build(); ``` ### Retries The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2). Before defaulting to exponential backoff, the SDK will first attempt to respect the `Retry-After` header (as either in seconds or as an HTTP date), and then the `X-RateLimit-Reset` header (as a Unix timestamp in epoch seconds); failing both of those, it will fall back to exponential backoff. Which status codes are retried depends on the `retry-status-codes` generator configuration: **`legacy`** (current default): retries on * [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout) * [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests) * [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) (All server errors, including 500) **`recommended`**: retries on * [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout) * [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests) * [502](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502) (Bad Gateway) * [503](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503) (Service Unavailable) * [504](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504) (Gateway Timeout) Use the `maxRetries` client option to configure this behavior. ```java theme={null} import com.yasminaai.api.YasminaaiApiClient; YasminaaiApiClient client = YasminaaiApiClient .builder() .maxRetries(1) .build(); ``` ### Timeouts The SDK defaults to a 60 second timeout. You can configure this with a timeout option at the client or request level. ```java theme={null} import com.yasminaai.api.YasminaaiApiClient; import com.yasminaai.api.core.RequestOptions; // Client level YasminaaiApiClient client = YasminaaiApiClient .builder() .timeout(60) .build(); // Request level client.quotes().requestQuotes( ..., RequestOptions .builder() .timeout(60) .build() ); ``` ### Custom Headers The SDK allows you to add custom headers to requests. You can configure headers at the client level or at the request level. ```java theme={null} import com.yasminaai.api.YasminaaiApiClient; import com.yasminaai.api.core.RequestOptions; // Client level YasminaaiApiClient client = YasminaaiApiClient .builder() .addHeader("X-Custom-Header", "custom-value") .addHeader("X-Request-Id", "abc-123") .build(); ; // Request level client.quotes().requestQuotes( ..., RequestOptions .builder() .addHeader("X-Request-Header", "request-value") .build() ); ``` ### Access Raw Response Data The SDK provides access to raw response data, including headers, through the `withRawResponse()` method. The `withRawResponse()` method returns a raw client that wraps all responses with `body()` and `headers()` methods. (A normal client's `response` is identical to a raw client's `response.body()`.) ```java theme={null} YasminaaiApiHttpResponse response = client.quotes().withRawResponse().requestQuotes(...); System.out.println(response.body()); System.out.println(response.headers().get("X-My-Header")); ``` ## Contributing While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us! On the other hand, contributions to the README are always very welcome! # Php Source: https://docs.yasmina.ai/sdks/php # Yasminaai PHP Library [![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github\&utm_medium=github\&utm_campaign=readme\&utm_source=https%3A%2F%2Fgithub.com%2FYasminaAI%2Fmotor-php-sdk) [![php shield](https://img.shields.io/badge/php-packagist-pink)](https://packagist.org/packages/yasminaai/yasminaai) The Yasminaai PHP library provides convenient access to the Yasminaai APIs from PHP. ## Table of Contents * [Requirements](#requirements) * [Installation](#installation) * [Usage](#usage) * [Environments](#environments) * [Exception Handling](#exception-handling) * [Advanced](#advanced) * [Custom Client](#custom-client) * [Retries](#retries) * [Timeouts](#timeouts) * [Contributing](#contributing) ## Requirements This SDK requires PHP ^8.1. ## Installation ```sh theme={null} composer require yasminaai/yasminaai ``` ## Usage Instantiate and use the client with the following: ```php theme={null} ', ); $client->quotes->requestQuotes( new PostQuoteRequestsRequest([ 'otp' => '123456', 'ownerId' => 'owner_id', 'phone' => 'phone', 'birthdate' => new DateTime('2023-01-15'), 'carEstimatedCost' => 1.1, ]), ); ``` ## Environments This SDK allows you to configure different environments for API requests. ````php theme={null} The SDK defaults to the `Sandbox` environment. To use a different environment, pass it to the client constructor: ```php use Yasminaai\YasminaaiClient; use Yasminaai\Environments; $client = new YasminaaiClient( token: '', options: [ 'baseUrl' => Environments::Staging->value ] ); ```` Available environments: * `Environments::Sandbox` * `Environments::Production` ```` ## Exception Handling When the API returns a non-success status code (4xx or 5xx response), an exception will be thrown. ```php use Yasminaai\Exceptions\YasminaaiApiException; use Yasminaai\Exceptions\YasminaaiException; try { $response = $client->quotes->requestQuotes(...); } catch (YasminaaiApiException $e) { echo 'API Exception occurred: ' . $e->getMessage() . "\n"; echo 'Status Code: ' . $e->getCode() . "\n"; echo 'Response Body: ' . $e->getBody() . "\n"; // Optionally, rethrow the exception or handle accordingly. } ```` ## Advanced ### Custom Client This SDK is built to work with any HTTP client that implements the [PSR-18](https://www.php-fig.org/psr/psr-18/) `ClientInterface`. By default, if no client is provided, the SDK will use `php-http/discovery` to find an installed HTTP client. However, you can pass your own client that adheres to `ClientInterface`: ```php theme={null} use Yasminaai\YasminaaiClient; // Pass any PSR-18 compatible HTTP client implementation. // For example, using Guzzle: $customClient = new \GuzzleHttp\Client([ 'timeout' => 5.0, ]); $client = new YasminaaiClient(options: [ 'client' => $customClient ]); // Or using Symfony HttpClient: // $customClient = (new \Symfony\Component\HttpClient\Psr18Client()) // ->withOptions(['timeout' => 5.0]); // // $client = new YasminaaiClient(options: [ // 'client' => $customClient // ]); ``` ### Retries The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2). A request is deemed retryable when any of the following HTTP status codes is returned: * [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout) * [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests) * [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) (Internal Server Error) The `retryStatusCodes` configuration controls which [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) status codes are retried: * `legacy` (default): Retries `408`, `429`, and all `>= 500` * `recommended`: Retries `408`, `429`, `502`, `503`, `504` only (excludes `500 Internal Server Error` to avoid retrying non-idempotent failures) Use the `maxRetries` request option to configure this behavior. ```php theme={null} $response = $client->quotes->requestQuotes( ..., options: [ 'maxRetries' => 0 // Override maxRetries at the request level ] ); ``` ### Timeouts The SDK defaults to a 30 second timeout. Use the `timeout` option to configure this behavior. ```php theme={null} $response = $client->quotes->requestQuotes( ..., options: [ 'timeout' => 3.0 // Override timeout at the request level ] ); ``` ## Contributing While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us! On the other hand, contributions to the README are always very welcome! # Python Source: https://docs.yasmina.ai/sdks/python # Yasminaai Python Library [![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github\&utm_medium=github\&utm_campaign=readme\&utm_source=https%3A%2F%2Fgithub.com%2FYasminaAI%2Fmotor-python-sdk) [![pypi](https://img.shields.io/pypi/v/motor-python-sdk)](https://pypi.python.org/pypi/motor-python-sdk) The Yasminaai Python library provides convenient access to the Yasminaai APIs from Python. ## Table of Contents * [Installation](#installation) * [Reference](#reference) * [Usage](#usage) * [Environments](#environments) * [Async Client](#async-client) * [Exception Handling](#exception-handling) * [Advanced](#advanced) * [Access Raw Response Data](#access-raw-response-data) * [Retries](#retries) * [Timeouts](#timeouts) * [Custom Client](#custom-client) * [Contributing](#contributing) ## Installation ```sh theme={null} pip install motor-python-sdk ``` ## Reference A full reference for this library is available [here](https://github.com/YasminaAI/motor-python-sdk/blob/HEAD/./reference.md). ## Usage Instantiate and use the client with the following: ```python theme={null} from yasminaai import YasminaaiApi import datetime client = YasminaaiApi( token="", ) client.quotes.request_quotes( otp="123456", owner_id="owner_id", phone="phone", birthdate=datetime.date.fromisoformat("2023-01-15"), car_estimated_cost=1.1, ) ``` ## Environments This SDK allows you to configure different environments for API requests. ```python theme={null} from yasminaai import YasminaaiApi from yasminaai.environment import YasminaaiApiEnvironment client = YasminaaiApi( environment=YasminaaiApiEnvironment.SANDBOX, ) ``` ## Async Client The SDK also exports an `async` client so that you can make non-blocking calls to our API. Note that if you are constructing an Async httpx client class to pass into this client, use `httpx.AsyncClient()` instead of `httpx.Client()` (e.g. for the `httpx_client` parameter of this client). ```python theme={null} import asyncio import datetime from yasminaai import AsyncYasminaaiApi client = AsyncYasminaaiApi( token="", ) async def main() -> None: await client.quotes.request_quotes( otp="123456", owner_id="owner_id", phone="phone", birthdate=datetime.date.fromisoformat("2023-01-15"), car_estimated_cost=1.1, ) asyncio.run(main()) ``` ## Exception Handling When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error will be thrown. ```python theme={null} from yasminaai.core.api_error import ApiError try: client.quotes.request_quotes(...) except ApiError as e: print(e.status_code) print(e.body) ``` ## Advanced ### Access Raw Response Data The SDK provides access to raw response data, including headers, through the `.with_raw_response` property. The `.with_raw_response` property returns a "raw" client that can be used to access the `.headers` and `.data` attributes. ```python theme={null} from yasminaai import YasminaaiApi client = YasminaaiApi(...) response = client.quotes.with_raw_response.request_quotes(...) print(response.headers) # access the response headers print(response.status_code) # access the response status code print(response.data) # access the underlying object ``` ### Retries The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2). Which status codes are retried depends on the `retryStatusCodes` generator configuration: **`legacy`** (current default): retries on * [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout) * [409](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409) (Conflict) * [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests) * [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) (All server errors, including 500) **`recommended`**: retries on * [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout) * [409](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409) (Conflict) * [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests) * [502](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502) (Bad Gateway) * [503](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503) (Service Unavailable) * [504](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504) (Gateway Timeout) Use the `max_retries` request option to configure this behavior. ```python theme={null} client.quotes.request_quotes(..., request_options={ "max_retries": 1 }) ``` ### Timeouts The SDK defaults to a 60 second timeout. You can configure this with a timeout option at the client or request level. ```python theme={null} from yasminaai import YasminaaiApi client = YasminaaiApi(..., timeout=20.0) # Override timeout for a specific method client.quotes.request_quotes(..., request_options={ "timeout_in_seconds": 1 }) ``` ### Custom Client You can override the `httpx` client to customize it for your use-case. Some common use-cases include support for proxies and transports. ```python theme={null} import httpx from yasminaai import YasminaaiApi client = YasminaaiApi( ..., httpx_client=httpx.Client( proxy="http://my.test.proxy.example.com", transport=httpx.HTTPTransport(local_address="0.0.0.0"), ), ) ``` ## Contributing While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us! On the other hand, contributions to the README are always very welcome! # Ruby Source: https://docs.yasmina.ai/sdks/ruby # Yasminaai Ruby Library [![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github\&utm_medium=github\&utm_campaign=readme\&utm_source=https%3A%2F%2Fgithub.com%2FYasminaAI%2Fmotor-ruby-sdk) The Yasminaai Ruby library provides convenient access to the Yasminaai APIs from Ruby. ## Table of Contents * [Reference](#reference) * [Usage](#usage) * [Environments](#environments) * [Errors](#errors) * [Advanced](#advanced) * [Retries](#retries) * [Timeouts](#timeouts) * [Additional Headers](#additional-headers) * [Additional Query Parameters](#additional-query-parameters) * [Contributing](#contributing) ## Reference A full reference for this library is available [here](https://github.com/YasminaAI/motor-ruby-sdk/blob/HEAD/./reference.md). ## Usage Instantiate and use the client with the following: ```ruby theme={null} require "yasminaai" client = Yasminaai::Client.new(token: "") client.quotes.request_quotes( otp: "123456", owner_id: "owner_id", phone: "phone", birthdate: "2023-01-15", car_estimated_cost: 1.1 ) ``` ## Environments This SDK allows you to configure different environments or custom URLs for API requests. You can either use the predefined environments or specify your own custom URL. ### Environments ```ruby theme={null} require "yasminaai" yasminaai = Yasminaai::Client.new( base_url: Yasminaai::Environment::SANDBOX ) ``` ### Custom URL ```ruby theme={null} require "yasminaai" client = Yasminaai::Client.new( base_url: "https://example.com" ) ``` ## Errors Failed API calls will raise errors that can be rescued from granularly. ```ruby theme={null} require "yasminaai" client = Yasminaai::Client.new( base_url: "https://example.com" ) begin result = client.quotes.request_quotes rescue Yasminaai::Errors::TimeoutError puts "API didn't respond before our timeout elapsed" rescue Yasminaai::Errors::ServiceUnavailableError puts "API returned status 503, is probably overloaded, try again later" rescue Yasminaai::Errors::ServerError puts "API returned some other 5xx status, this is probably a bug" rescue Yasminaai::Errors::ResponseError => e puts "API returned an unexpected status other than 5xx: #{e.code} #{e.message}" rescue Yasminaai::Errors::ApiError => e puts "Some other error occurred when calling the API: #{e.message}" end ``` ## Advanced ### Retries The SDK is instrumented with automatic retries. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2). A request is deemed retryable when any of the following HTTP status codes is returned: * [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout) * [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests) * [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) (Internal Server Error) The `retryStatusCodes` configuration controls which [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) status codes are retried: * `legacy` (default): Retries `408`, `429`, `500`, `502`, `503`, `504`, `521`, `522`, `524` * `recommended`: Retries `408`, `429`, `502`, `503`, `504` only (excludes `500 Internal Server Error` to avoid retrying non-idempotent failures) Use the `max_retries` option to configure this behavior. ```ruby theme={null} require "yasminaai" client = Yasminaai::Client.new( base_url: "https://example.com", max_retries: 3 # Configure max retries (default is 2) ) ``` ### Timeouts The SDK defaults to a 60 second timeout. Use the `timeout` option to configure this behavior. ```ruby theme={null} require "yasminaai" response = client.quotes.request_quotes( ..., timeout: 30 # 30 second timeout ) ``` ### Additional Headers If you would like to send additional headers as part of the request, use the `additional_headers` request option. ```ruby theme={null} require "yasminaai" response = client.quotes.request_quotes( ..., request_options: { additional_headers: { "X-Custom-Header" => "custom-value" } } ) ``` ### Additional Query Parameters If you would like to send additional query parameters as part of the request, use the `additional_query_parameters` request option. ```ruby theme={null} require "yasminaai" response = client.quotes.request_quotes( ..., request_options: { additional_query_parameters: { "custom_param" => "custom-value" } } ) ``` ## Contributing While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us! On the other hand, contributions to the README are always very welcome! # Rust Source: https://docs.yasmina.ai/sdks/rust # Yasminaai Rust Library [![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github\&utm_medium=github\&utm_campaign=readme\&utm_source=https%3A%2F%2Fgithub.com%2FYasminaAI%2Fmotor-rust-sdk) [![crates.io shield](https://img.shields.io/crates/v/yasminaai_api)](https://crates.io/crates/yasminaai_api) The Yasminaai Rust library provides convenient access to the Yasminaai APIs from Rust. ## Table of Contents * [Installation](#installation) * [Reference](#reference) * [Usage](#usage) * [Environments](#environments) * [Errors](#errors) * [Request Types](#request-types) * [Advanced](#advanced) * [Retries](#retries) * [Timeouts](#timeouts) * [Additional Headers](#additional-headers) * [Additional Query String Parameters](#additional-query-string-parameters) * [Contributing](#contributing) ## Installation Add this to your `Cargo.toml`: ```toml theme={null} [dependencies] yasminaai_api = "0.1.0" ``` Or install via cargo: ```sh theme={null} cargo add yasminaai_api ``` ## Reference A full reference for this library is available [here](https://github.com/YasminaAI/motor-rust-sdk/blob/HEAD/./reference.md). ## Usage Instantiate and use the client with the following: ```rust theme={null} use yasminaai_api::prelude::*; #[tokio::main] async fn main() { let config = ClientConfig { token: Some("".to_string()), ..Default::default() }; let client = ApiClient::new(config).expect("Failed to build client"); client .quotes .request_quotes( &PostQuoteRequestsRequest { otp: "123456".to_string(), owner_id: "owner_id".to_string(), phone: "phone".to_string(), birthdate: NaiveDate::parse_from_str("2023-01-15", "%Y-%m-%d").unwrap(), car_estimated_cost: 1.1, email: None, car_sequence_number: None, custom_number: None, is_ownership_transfer: None, current_car_owner_id: None, car_model_year: None, start_date: None, drivers: None, }, None, ) .await; } ``` ## Environments This SDK allows you to configure different environments for API requests. ```rust theme={null} use yasminaai_api::prelude::{*}; let config = ClientConfig { base_url: Environment::Sandbox.url().to_string(), ..Default::default() }; let client = Client::new(config).expect("Failed to build client"); ``` ## Errors When the API returns a non-success status code (4xx or 5xx response), an error will be returned. ```rust theme={null} match client.quotes.request_quotes(None)?.await { Ok(response) => { println!("Success: {:?}", response); }, Err(ApiError::HTTP { status, message }) => { println!("API Error {}: {:?}", status, message); }, Err(e) => { println!("Other error: {:?}", e); } } ``` ## Request Types The SDK exports all request types as Rust structs. Simply import them from the crate to access them: ```rust theme={null} use yasminaai_api::prelude::{*}; let request = PostQuoteRequestsRequest { ... }; ``` ## Advanced ### Retries The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2). A request is deemed retryable when any of the following HTTP status codes is returned: * [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout) * [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests) * [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) (Internal Server Error) The `retryStatusCodes` configuration controls which [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) status codes are retried: * `legacy` (default): Retries `408`, `429`, and all `>= 500` * `recommended`: Retries `408`, `429`, `502`, `503`, `504` only (excludes `500 Internal Server Error` to avoid retrying non-idempotent failures) Use the `max_retries` method to configure this behavior. ```rust theme={null} let response = client.quotes.request_quotes( Some(RequestOptions::new().max_retries(3)) )?.await; ``` ### Timeouts The SDK defaults to a 30 second timeout. Use the `timeout` method to configure this behavior. ```rust theme={null} let response = client.quotes.request_quotes( Some(RequestOptions::new().timeout_seconds(30)) )?.await; ``` ### Additional Headers You can add custom headers to requests using `RequestOptions`. ```rust theme={null} let response = client.quotes.request_quotes( Some( RequestOptions::new() .additional_header("X-Custom-Header", "custom-value") .additional_header("X-Another-Header", "another-value") ) )? .await; ``` ### Additional Query String Parameters You can add custom query parameters to requests using `RequestOptions`. ```rust theme={null} let response = client.quotes.request_quotes( Some( RequestOptions::new() .additional_query_param("filter", "active") .additional_query_param("sort", "desc") ) )? .await; ``` ## Contributing While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us! On the other hand, contributions to the README are always very welcome! # Swift Source: https://docs.yasmina.ai/sdks/swift # Yasminaai Swift Library [![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github\&utm_medium=github\&utm_campaign=readme\&utm_source=https%3A%2F%2Fgithub.com%2FYasminaAI%2Fmotor-swift-sdk) ![SwiftPM compatible](https://img.shields.io/badge/SwiftPM-compatible-orange.svg) The Yasminaai Swift library provides convenient access to the Yasminaai APIs from Swift. ## Table of Contents * [Requirements](#requirements) * [Installation](#installation) * [Reference](#reference) * [Usage](#usage) * [Environments](#environments) * [Errors](#errors) * [Request Types](#request-types) * [Advanced](#advanced) * [Additional Headers](#additional-headers) * [Additional Query String Parameters](#additional-query-string-parameters) * [Timeouts](#timeouts) * [Custom Networking Client](#custom-networking-client) * [Contributing](#contributing) ## Requirements This SDK requires: * Swift 5.7+ * iOS 15+ * macOS 12+ * tvOS 15+ * watchOS 8+ ## Installation With Swift Package Manager (SPM), add the following to the top-level `dependencies` array within your `Package.swift` file: ```swift theme={null} dependencies: [ .package(url: "https://github.com/YasminaAI/motor-swift-sdk", from: "0.1.0"), ] ``` ## Reference A full reference for this library is available [here](https://github.com/YasminaAI/motor-swift-sdk/blob/HEAD/./reference.md). ## Usage Instantiate and use the client with the following: ```swift theme={null} import Foundation import Api private func main() async throws { let client = ApiClient(token: "") _ = try await client.quotes.requestQuotes(request: .init( otp: "123456", ownerId: "owner_id", phone: "phone", birthdate: CalendarDate("2023-01-15")!, carEstimatedCost: 1.1 )) } try await main() ``` ## Environments This SDK allows you to configure different environments for API requests. ```swift theme={null} import Api let client = ApiClient( token: "YOUR_API_KEY", environment: .sandbox ) ``` ## Errors The SDK throws a single error enum for all failures. Client-side issues encoding/decoding failures and network errors use dedicated cases, while non-success HTTP responses are wrapped in an `HTTPError` that exposes the status code, a simple classification and an optional decoded message. ```swift theme={null} import Api let client = ApiClient(token: "YOUR_API_KEY") do { let response = try await client.quotes.requestQuotes(...) // Handle successful response } catch let error as ApiError { switch error { case .httpError(let httpError): print("Status code:", httpError.statusCode) print("Kind:", httpError.kind) print("Message:", httpError.body?.message ?? httpError.localizedDescription) case .encodingError(let underlying): print("Encoding error:", underlying) case .networkError(let underlying): print("Network error:", underlying) default: print("Other client error:", error) } } catch { print("Unexpected error:", error) } ``` ## Request Types The SDK exports all request types as Swift structs. Simply import the SDK module to access them: ```swift theme={null} import Api let request = Requests.PostQuoteRequestsRequest( ... ) ``` ## Advanced ### Additional Headers If you would like to send additional headers as part of the request, use the `additionalHeaders` request option. ```swift theme={null} try await client.quotes.requestQuotes(..., requestOptions: .init( additionalHeaders: [ "X-Custom-Header": "custom value" ] )) ``` ### Additional Query String Parameters If you would like to send additional query string parameters as part of the request, use the `additionalQueryParameters` request option. ```swift theme={null} try await client.quotes.requestQuotes(..., requestOptions: .init( additionalQueryParameters: [ "custom_query_param_key": "custom_query_param_value" ] )) ``` ### Timeouts The SDK defaults to a 60-second timeout. Use the `timeout` option to configure this behavior. ```swift theme={null} try await client.quotes.requestQuotes(..., requestOptions: .init( timeout: 30 )) ``` ### Custom Networking Client The SDK allows you to customize the underlying `URLSession` used for HTTP requests. Use the `urlSession` option to provide your own configured `URLSession` instance. ```swift theme={null} import Foundation import Api let client = ApiClient( token: "YOUR_API_KEY", urlSession: // Provide your implementation here ) ``` ## Contributing While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us! On the other hand, contributions to the README are always very welcome! # Ts Source: https://docs.yasmina.ai/sdks/ts # Yasminaai TypeScript Library [![fern shield](https://img.shields.io/badge/%F0%9F%8C%BF-Built%20with%20Fern-brightgreen)](https://buildwithfern.com?utm_source=github\&utm_medium=github\&utm_campaign=readme\&utm_source=https%3A%2F%2Fgithub.com%2FYasminaAI%2Fmotor-typescript-sdk) [![npm shield](https://img.shields.io/npm/v/@yasminaai/motor-typescript)](https://www.npmjs.com/package/@yasminaai/motor-typescript) The Yasminaai TypeScript library provides convenient access to the Yasminaai APIs from TypeScript. ## Table of Contents * [Installation](#installation) * [Reference](#reference) * [Usage](#usage) * [Environments](#environments) * [Request and Response Types](#request-and-response-types) * [Exception Handling](#exception-handling) * [Advanced](#advanced) * [Subpackage Exports](#subpackage-exports) * [Additional Headers](#additional-headers) * [Additional Query String Parameters](#additional-query-string-parameters) * [Retries](#retries) * [Timeouts](#timeouts) * [Aborting Requests](#aborting-requests) * [Access Raw Response Data](#access-raw-response-data) * [Logging](#logging) * [Custom Fetch](#custom-fetch) * [Runtime Compatibility](#runtime-compatibility) * [Contributing](#contributing) ## Installation ```sh theme={null} npm i -s @yasminaai/motor-typescript ``` ## Reference A full reference for this library is available [here](https://github.com/YasminaAI/motor-typescript-sdk/blob/HEAD/./reference.md). ## Usage Instantiate and use the client with the following: ```typescript theme={null} import { YasminaaiApiClient } from "@yasminaai/motor-typescript"; const client = new YasminaaiApiClient({ token: "YOUR_TOKEN" }); await client.quotes.requestQuotes({ otp: "123456", owner_id: "owner_id", phone: "phone", birthdate: "2023-01-15", car_estimated_cost: 1.1, }); ``` ## Environments This SDK allows you to configure different environments for API requests. ```typescript theme={null} import { YasminaaiApiClient, YasminaaiApiEnvironment, } from "@yasminaai/motor-typescript"; const client = new YasminaaiApiClient({ environment: YasminaaiApiEnvironment.Sandbox, }); ``` ## Request and Response Types The SDK exports all request and response types as TypeScript interfaces. Simply import them with the following namespace: ```typescript theme={null} import { YasminaaiApi } from "@yasminaai/motor-typescript"; const request: YasminaaiApi.GetQuoteRequestsIdRequest = { ... }; ``` ## Exception Handling When the API returns a non-success status code (4xx or 5xx response), a subclass of the following error will be thrown. ```typescript theme={null} import { YasminaaiApiError } from "@yasminaai/motor-typescript"; try { await client.quotes.requestQuotes(...); } catch (err) { if (err instanceof YasminaaiApiError) { console.log(err.statusCode); console.log(err.message); console.log(err.body); console.log(err.rawResponse); } } ``` ## Advanced ### Subpackage Exports This SDK supports direct imports of subpackage clients, which allows JavaScript bundlers to tree-shake and include only the imported subpackage code. This results in much smaller bundle sizes. ```typescript theme={null} import { QuotesClient } from '@yasminaai/motor-typescript/quotes'; const client = new QuotesClient({...}); ``` ### Additional Headers If you would like to send additional headers as part of the request, use the `headers` request option. ```typescript theme={null} import { YasminaaiApiClient } from "@yasminaai/motor-typescript"; const client = new YasminaaiApiClient({ ... headers: { 'X-Custom-Header': 'custom value' } }); const response = await client.quotes.requestQuotes(..., { headers: { 'X-Custom-Header': 'custom value' } }); ``` ### Additional Query String Parameters If you would like to send additional query string parameters as part of the request, use the `queryParams` request option. ```typescript theme={null} const response = await client.quotes.requestQuotes(..., { queryParams: { 'customQueryParamKey': 'custom query param value' } }); ``` ### Retries The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2). Which status codes are retried depends on the `retryStatusCodes` generator configuration: **`legacy`** (current default): retries on * [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout) * [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests) * [5XX](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#server_error_responses) (All server errors, including 500) **`recommended`**: retries on * [408](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408) (Timeout) * [429](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) (Too Many Requests) * [502](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502) (Bad Gateway) * [503](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503) (Service Unavailable) * [504](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504) (Gateway Timeout) Use the `maxRetries` request option to configure this behavior. ```typescript theme={null} const response = await client.quotes.requestQuotes(..., { maxRetries: 0 // override maxRetries at the request level }); ``` ### Timeouts The SDK defaults to a 60 second timeout. Use the `timeoutInSeconds` option to configure this behavior. ```typescript theme={null} const response = await client.quotes.requestQuotes(..., { timeoutInSeconds: 30 // override timeout to 30s }); ``` ### Aborting Requests The SDK allows users to abort requests at any point by passing in an abort signal. ```typescript theme={null} const controller = new AbortController(); const response = await client.quotes.requestQuotes(..., { abortSignal: controller.signal }); controller.abort(); // aborts the request ``` ### Access Raw Response Data The SDK provides access to raw response data, including headers, through the `.withRawResponse()` method. The `.withRawResponse()` method returns a promise that results to an object with a `data` and a `rawResponse` property. ```typescript theme={null} const { data, rawResponse } = await client.quotes.requestQuotes(...).withRawResponse(); console.log(data); console.log(rawResponse.headers['X-My-Header']); ``` ### Logging The SDK supports logging. You can configure the logger by passing in a `logging` object to the client options. ```typescript theme={null} import { YasminaaiApiClient, logging } from "@yasminaai/motor-typescript"; const client = new YasminaaiApiClient({ ... logging: { level: logging.LogLevel.Debug, // defaults to logging.LogLevel.Info logger: new logging.ConsoleLogger(), // defaults to ConsoleLogger silent: false, // defaults to true, set to false to enable logging } }); ``` The `logging` object can have the following properties: * `level`: The log level to use. Defaults to `logging.LogLevel.Info`. * `logger`: The logger to use. Defaults to a `logging.ConsoleLogger`. * `silent`: Whether to silence the logger. Defaults to `true`. The `level` property can be one of the following values: * `logging.LogLevel.Debug` * `logging.LogLevel.Info` * `logging.LogLevel.Warn` * `logging.LogLevel.Error` To provide a custom logger, you can pass in an object that implements the `logging.ILogger` interface.
Custom logger examples Here's an example using the popular `winston` logging library. ```ts theme={null} import winston from 'winston'; const winstonLogger = winston.createLogger({...}); const logger: logging.ILogger = { debug: (msg, ...args) => winstonLogger.debug(msg, ...args), info: (msg, ...args) => winstonLogger.info(msg, ...args), warn: (msg, ...args) => winstonLogger.warn(msg, ...args), error: (msg, ...args) => winstonLogger.error(msg, ...args), }; ``` Here's an example using the popular `pino` logging library. ```ts theme={null} import pino from 'pino'; const pinoLogger = pino({...}); const logger: logging.ILogger = { debug: (msg, ...args) => pinoLogger.debug(args, msg), info: (msg, ...args) => pinoLogger.info(args, msg), warn: (msg, ...args) => pinoLogger.warn(args, msg), error: (msg, ...args) => pinoLogger.error(args, msg), }; ```
### Custom Fetch The SDK provides a low-level `fetch` method for making custom HTTP requests while still benefiting from SDK-level configuration like authentication, retries, timeouts, and logging. This is useful for calling API endpoints not yet supported in the SDK. ```typescript theme={null} const response = await client.fetch( "/v1/custom/endpoint", { method: "GET", }, { timeoutInSeconds: 30, maxRetries: 3, headers: { "X-Custom-Header": "custom-value", }, }, ); const data = await response.json(); ``` ### Runtime Compatibility The SDK works in the following runtimes: * Node.js 18+ * Vercel * Cloudflare Workers * Deno v1.25+ * Bun 1.0+ * React Native ## Contributing While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us! On the other hand, contributions to the README are always very welcome! # Comprehensive Motor Insurance Source: https://docs.yasmina.ai/single-provider-integrations/car Seamless insurance for the cars you're selling and the drivers that are buying from you.

Build it with AI — an AI coding assistant can scaffold this entire integration for you straight from these docs. See Build with AI to get started.

## Introduction This guide describes the Yasmina's **Comprehensive Motor Insurance APIs for Single Insurance Provider** (for Multiple Insurance Providers with Price comparison, [click here](/price-comparison/motor-insurance)) available on Yasmina’s platform. These APIs cover the core operations required for working with Comprehensive motor insurance, including issuing and managing policies, generating payment link, and handling claims. Our APIs use the RESTful standard and is structured to provide consistent inputs and outputs, making it quick and easy to integrate, test, and maintain within your systems. ## What you will learn * Uploading vehicle photos * Issuing and managing policies * Payment link * Starting a claim ## Prerequisites 1. **Account in Yasmina** - See the Onboarding section for details. You need to add "Comprehensive Motor Insurance (Single Provider)" in the products field. 2. **Authenticated Token** - Follow the Authentication guide to generate one. 3. **Backend server** - Required to securely call Yasmina APIs. ## Vehicle photos If the customer has selected a comprehensive policy, upload the five photos before you issue the policy — front, back, right, left, and the chassis (VIN) number. Use the Upload Vehicle Photos API, against the quote request and the price the customer selected. This step is required for comprehensive cover. If the photos are not uploaded, the customer cannot continue with the purchase. It must happen before you request the payment OTP. Example of a request ``` POST /api/v1/car-comp/quote-requests/11/attachments HTTP/1.1 Authorization: Bearer ***** Content-Type: multipart/form-data quote_price_id=e059d28e-a519-43af-b9d4-e1cc5d97ecb7 front=@front.jpg back=@back.jpg right=@right.jpg left=@left.jpg chassis=@chassis.jpg ``` * **All five together.** A partial upload is rejected with a `422`. * **JPG or PNG, up to 3 MB each.** * **Once per vehicle.** The insurance provider keeps the first set it accepts. A later upload for the same vehicle still succeeds, with `already_registered: true` in the response, but the registered photos do not change — so check the photos before sending them. * **Comprehensive only.** A `quote_price_id` belonging to a TPL quote is rejected. ## Issue policy In order to Issue a policy. You can head to the Issue Policy API These are the fields that you need to provide: | Field | Example Value | Description | | ----------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `otp` | `123456` | The OTP received by the customer. Required for issuing a policy. | | `owner_id` | `2234567890` | The owner’s national ID (starts with `1` for Saudi nationals) or Iqama ID (starts with `2` for residents). Must be exactly 10 digits. | | `email` | `someone@example.com` | The owner’s email. Must be unique and belong to the one customer (Do not use the same email for multiple customers). | | `birthdate` | `1988-04-20` | Date of birth of the owner in `YYYY-MM-DD` format. For a Saudi national ID (starts with `1`) give a Hijri date; for an Iqama ID (starts with `2`) give a Gregorian date. | | `phone` | `05XXXXXXXX` | Saudi mobile number. Must start with `05` and be exactly 10 digits. | | `car_sequence_number` | `52423810` | The car’s sequence number (8–9 digits). Use this OR `custom_number` — one is required. | | `custom_number` | `1234567890` | Custom car number for newly imported cars. Use this OR `car_sequence_number`. | | `is_ownership_transfer` | `false` | Boolean flag. `true` if the car is being transferred to a new owner, otherwise `false`. | | `current_car_owner_id` | `1234567890` | The current owner’s national ID (starts with `1`) or Iqama ID (starts with `2`). **Only required if** `is_ownership_transfer = true`. | | `car_estimated_cost` | `45000` | Estimated market cost of the car in SAR. | | `car_model_year` | `2026` | Year of manufacture of the car. Must be between 1950 and the next year. | The customer's Saudi IBAN is collected earlier in the flow: it is a required field of the Issue OTP API, not of this endpoint. Example of a request ``` POST /api/v1/car-comp/policies HTTP/1.1 Authorization: Bearer ***** Content-Type: application/json Accept: application/json Content-Length: 212 { "otp": "123456", "owner_id": 2234567890, "email": "someone@example.com", "phone": "05XXXXXXXX", "birthdate": "1982-04-20", "custom_number": "1234567890", "is_ownership_transfer": false, "car_estimated_cost": 45000, "car_model_year": 2024 } ``` Once you make a request to the Issue Policy API, you will get the Policy object with a `201` HTTP response code. Here is an example of the Policy object. ``` { "id": 700, "meta_data": { "extra_data": null, "new_owner_id": "2528297837", "previous_owner_id": "1001364939", "car_sequence_number": 723787810 }, "provider_policy_id": null, "provider_policy": null, "created_at": "2025-10-06T23:31:17.000000Z", "status": 0, "payment_link": "http://localhost:8000/short/wVln4", "price": 6016 } ``` This is a summary of the fields returned in the policy object | Field | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Yasmina’s unique identifier for the policy. | | `meta_data` | A JSON object that contains information about the fields that were used to generate this policy. `extra_data` will also be returned here. | | `provider_policy_id` | The policy ID that is returned by the policy provider. | | `provider_policy` | A URL that contains the policy in PDF format. | | `created_at` | When was the policy issued. | | `status` | 0 = Pending, 1 = Issued. | | \`payment\_link | A secure payment link generated by Yasmina | | `price` | The price of the policy in Saudi Riyal | ### Understanding Payment and Policy activation When you first make a request to the Issue Policy API. The Policy is not yet activated and the `status` is `0` (which means pending). Also the `provider_policy` and `provider_policy_id` will both be `null`. In order for the policy to be activated, the customer needs to make the purchase from the payment link. Once the customer successfully pays. The policy will be activated and the `status` becomes `1`. Although the payment page is provided by Yasmina, it does not display the Yasmina logo or have any mention of Yasmina.

Yasmina does not receive credit card information, instead the payment page sends card information directly to the payment vendor. On Sandbox, you can use a testing card with the following information:
Card number: 4111 1111 1111 1111
Expiry: 02/27
CVV: 123
Card owner: Yasmina test #### Showing a policy In order to get a status of a policy, you can use the Show Policy API. This API, takes a Yasmina Policy `id` and will return the policy object This API is ideal when you want to re-fetch a specific policy after the PDF gets generated. Example of a request ``` GET /api/v1/car-comp/policies/123 HTTP/1.1 Host: production.yasmina.ai Authorization: Bearer Content-Type: application/json Accept: application/json ``` Example a response ``` { "id": 659, "meta_data": { "extra_data": { }, "new_owner_id": "2467701575", "quote_price_id": "097116f9-99b1-491f-a2ab-f86b2c535cbe", "quote_request_id": 4, "previous_owner_id": "2467701575", "car_sequence_number": 52423810 }, "product_id": 4, "provider_policy_id": "53018c24-b246-4bef-866f-4a54c2367196", "provider_policy": "policy.pdf", "created_at": "2025-09-07T07:53:55.000000Z", "status": 1, "payment_link": null, "price": null } ``` ### Listing policies You can also use the List Policies API to get a list of all policies that were generated from our system. You might use this on your admin interface, or if you just want to check what has been generated. ## Claims You can issue a claim using our APIs. When you issue a claim, we communicate it with the Insurance provider, and giving them details of the incident. Go to the Issue Claim API in order to start the claim process for your customer. # TPL Motor Insurance Source: https://docs.yasmina.ai/single-provider-integrations/cartpl Seamless insurance for the cars you're selling and the drivers that are buying from you.

Build it with AI — an AI coding assistant can scaffold this entire integration for you straight from these docs. See Build with AI to get started.

## Introduction This guide describes Yasmina's **TPL Motor Insurance APIs available on Yasmina’s platform** (for Multiple Insurance Providers with price comparison, [click here](/price-comparison/motor-insurance)). These APIs cover the core operations required for working with TPL motor insurance, including issuing and managing policies, generating payment link, and handling claims. Our APIs use the RESTful standard and is structured to provide consistent inputs and outputs, making it quick and easy to integrate, test, and maintain within your systems. ## What you will learn * Issuing and managing policies * Payment link * Starting a claim ## Prerequisites 1. **Account in Yasmina** - See the Onboarding section for details. You need to add "TPL Motor Insurance (Single Provider)" in the products field. 2. **Authenticated Token** - Follow the Authentication guide to generate one. 3. **Backend server** - Required to securely call Yasmina APIs. ## Prerequisites 1. **Account in Yasmina** - See the Onboarding section for details. 2. **Authenticated Token** - Follow the Authentication guide to generate one. 3. **Backend server** - Required to securely call Yasmina APIs. ## Issue policy In order to Issue a policy. You can head to the Issue Policy API These are the fields that you need to provide: | Field | Example Value | Description | | ----------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `owner_id` | `2234567890` | The owner’s national ID (starts with `1` for Saudi nationals) or Iqama ID (starts with `2` for residents). Must be exactly 10 digits. | | `email` | `someone@example.com` | The owner’s email. Must be unique and belong to the one customer (Do not use the same email for multiple customers). | | `birthdate` | `1988-04-20` | Date of birth of the owner in `YYYY-MM-DD` format. For a Saudi national ID (starts with `1`) give a Hijri date; for an Iqama ID (starts with `2`) give a Gregorian date. | | `phone` | `05XXXXXXXX` | Saudi mobile number. Must start with `05` and be exactly 10 digits. | | `car_sequence_number` | `52423810` | The car’s sequence number (8–9 digits). | | `is_ownership_transfer` | `false` | Boolean flag. `true` if the car is being transferred to a new owner, otherwise `false`. | | `current_car_owner_id` | `1234567890` | The current owner’s national ID (starts with `1`) or Iqama ID (starts with `2`). **Only required if** `is_ownership_transfer = true`. | | `car_estimated_cost` | `45000` | Estimated market cost of the car in SAR. | | `car_model_year` | `2026` | Year of manufacture of the car. Must be between 1950 and the next year. | The customer's Saudi IBAN is collected earlier in the flow: it is a required field of the Issue OTP API, not of this endpoint. Example of a request ``` POST /api/v1/car-comp/policies HTTP/1.1 Authorization: Bearer ***** Content-Type: application/json Accept: application/json Content-Length: 212 { "owner_id": 2234567890, "email": "someone@example.com", "phone": "05XXXXXXXX", "birthdate": "1982-04-20", "car_sequence_number": 52423810, "is_ownership_transfer": false, "car_estimated_cost": 45000, "car_model_year": 2024 } ``` Once you make a request to the Issue Policy API, you will get the Policy object with a `201` HTTP response code. Here is an example of the Policy object. ``` { "id": 700, "meta_data": { "extra_data": null, "new_owner_id": "2528297837", "previous_owner_id": "1001364939", "car_sequence_number": 723787810 }, "provider_policy_id": null, "provider_policy": null, "created_at": "2025-10-06T23:31:17.000000Z", "status": 0, "payment_link": "http://localhost:8000/short/wVln4", "price": 6016 } ``` This is a summary of the fields returned in the policy object | Field | Description | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Yasmina’s unique identifier for the policy. | | `meta_data` | A JSON object that contains information about the fields that were used to generate this policy. `extra_data` will also be returned here. | | `provider_policy_id` | The policy ID that is returned by the policy provider. | | `provider_policy` | A URL that contains the policy in PDF format. | | `created_at` | When was the policy issued. | | `status` | 0 = Pending, 1 = Issued. | | \`payment\_link | A secure payment link generated by Yasmina | | `price` | The price of the policy in Saudi Riyal | ### Understanding Payment and Policy activation When you first make a request to the Issue Policy API. The Policy is not yet activated and the `status` is `0` (which means pending). Also the `provider_policy` and `provider_policy_id` will both be `null`. In order for the policy to be activated, the customer needs to make the purchase from the payment link. Once the customer successfully pays. The policy will be activated and the `status` becomes `1`. Although the payment page is provided by Yasmina, it does not display the Yasmina logo or have any mention of Yasmina.

Yasmina does not receive credit card information, instead the payment page sends card information directly to the payment vendor. On Sandbox, you can use a testing card with the following information:
Card number: 4111 1111 1111 1111
Expiry: 02/27
CVV: 123
Card owner: Yasmina test #### Showing a policy In order to get a status of a policy, you can use the Show Policy API. This API, takes a Yasmina Policy `id` and will return the policy object This API is ideal when you want to re-fetch a specific policy after the PDF gets generated. Example of a request ``` GET /api/v1/car-comp/policies/123 HTTP/1.1 Host: production.yasmina.ai Authorization: Bearer Content-Type: application/json Accept: application/json ``` Example a response ``` { "id": 659, "meta_data": { "extra_data": { }, "new_owner_id": "2467701575", "quote_price_id": "097116f9-99b1-491f-a2ab-f86b2c535cbe", "quote_request_id": 4, "previous_owner_id": "2467701575", "car_sequence_number": 52423810 }, "product_id": 4, "provider_policy_id": "53018c24-b246-4bef-866f-4a54c2367196", "provider_policy": "policy.pdf", "created_at": "2025-09-07T07:53:55.000000Z", "status": 1, "payment_link": null, "price": null } ``` ### Listing policies You can also use the List Policies API to get a list of all policies that were generated from our system. You might use this on your admin interface, or if you just want to check what has been generated. ## Claims You can issue a claim using our APIs. When you issue a claim, we communicate it with the Insurance provider, and giving them details of the incident. Go to the Issue Claim API in order to start the claim process for your customer. # Horse Insurance Source: https://docs.yasmina.ai/single-provider-integrations/horse Seamless insurance for the horses you're selling. ## Overview The API's in this documentation has been designed to seamlessly integrate with Yasmina's platform, enabling a smooth and efficient exchange of horse insurance-related data and functionalities. Whether you're looking to request or manage policies, handle claims, or access customer information, this API provides a robust and secure interface. With clear endpoints and comprehensive support, our goal is to simplify the integration process and ensure that our client can leverage the full potential of our insurance services with minimal effort. ### Steps Below is the basic journey to requesting your first insurance(s) Get a an authorization token to use all our API's. [Click for more details](#authorization).
Or go directly to [Authorization API](/horse-api-reference/auth/generate-token) Provide the horse details such as name and owner ID [Click for more details](#request-policies). Or go directly to [Issue policies API](/horse-api-reference/policies/request-policy) ### Authorization To access any of our API's. You need to authorize yourself. We are using [OAuth 2.0 client credentials](https://oauth.net/2/grant-types/client-credentials/) to achieve that.
You will need `client_id` and `client_secret`. You can get these from your [portal](https://portal.yasmina.ai/api-management).

After making the request, you will get access\_token in the response. Example ``` { "token_type": "Bearer", "expires_in": 31536000, "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiI5YmEyOTNmNy01ZjYyLTRlODItYmU5Yi1kODA0Y2M5ZDM5MmMiLCJqdGkiOiJlZWJjMWM5MWEyZThkMTVmNTYxNjZjMjkwM2Q0NTZjM2IzYWM5MTU5ZTdkODQ2YTE5NmFlYjcxMWM5OTJlMjc2MzAzNjY3MDA1MDQzM2U0OSIsImlhdCI6MTczNTkwNTE5OC40NTg5MiwibmJmIjoxNzM1OTA1MTk4LjQ1ODkyMSwiZXhwIjoxNzY3NDQxMTk4LjQ1Njk0LCJzdWIiOiIiLCJzY29wZXMiOltdfQ.Dy6df9fr4eBMLtkjnzcBjrXSg2AZLrmrBBC1NF8wmQaIOjcNffiqMiL9MqdMPj43Dxt4fj9rT1_S8dfwEpSbxNuIweNLOa7iDYpqMQ2l-cKG_sn24G27exZ9shLG8p2FHa4SHxSByRw00aCJceiTzq12LLNfc14rGPKZOv5Pi-HuLAP6ms_NfyN-KafOFOjYym4PyHCuTX8jEkoImgpBUpPgdnq1qyQdrZxL4grp0P_ezkhTgHgWwuzjSYgm4l-Eyga65kua-pdgWbhJ7-I1W_hjWT2dKCivcmk6nR9wtTjWs9hBvZrOfoZmox4YPIjZ_pvImZbHcZui-7xs80dnoaTKRviR8aot0cPIKoqRwinBodjWRh3QEu5juT1b7T-m85Wo_JNRoarKD4pW2Lzq7v1u9Z6PMEeYXvuFchzZ6HPvthblfwbtu3AX6ij0ZGlZPdMRdEiRtZf3dt8nsWdI-E_J0GAD-9wexlpNL92Z-IfuwMXuUQs_j4l92fcfBC_NxlEUTNACyOWPrA3V6ZSLHrga6W4Iz6Por3txzCsxlwvEBQAM70VyGeSqFi0wMLg2V8wVYAEpiEe2dl4RpMbUaPzRNc_KsDUYM_4DqwMTo2v2x4AAPxWmWiRn4PeAXovraN6Ll-eW9zq5hUbt3c-yj0spVYhJADHodoHmAdQM9MA" } ``` Use the access\_token and supply in the headers like this `Authorization: Bearer ` Go to the following link to use the [Authorization API](/horse-api-reference/auth/generate-token). For security reasons. Do not make your client\_id and client\_secret public in your platform. ### Issue policies To issue policies, you need to execute the [Issue policies API](/horse-api-reference/policies/request-policy)). # Life Insurance (S&P) Source: https://docs.yasmina.ai/single-provider-integrations/life Life Insurance – S&P Financial Strength Ratings Integration Guide ## Introduction This guide describes the Life Savings & Protection (Life S\&P) APIs available on Yasmina’s platform for bank channel integrations. These APIs cover the core operations required for life insurance workflows, including generating offers, issuing policies, listing policies, canceling policies, and submitting claims. Our APIs follow the RESTful standard and are designed with consistent request and response structures to make integration, testing, and maintenance easier. ## What you will learn * Generating Life S\&P offers * Issuing life policies based on selected offers * Retrieving created policies * Canceling policies * Submitting claims ## Prerequisites 1. **Account in Yasmina** - See the Onboarding section for details. 2. **Authenticated Token** - Follow the Authentication guide to generate one. 3. **Backend server** - Required to securely call Yasmina APIs. ## Offers ### Generate offers To generate offers, use the Life S\&P Products API. This endpoint (`POST /api/v1/life-snp/offers`) returns premium and coverage options for a customer. The following fields are used when requesting offers. | Field | Type | Rules | Description | | ---------------------- | ------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------- | | `applicant_id` | string | required, regex: `^\d{10}$` | Saudi National ID of the applicant (10 digits). | | `date_of_birth` | string (date) | required, format: `YYYY-MM-DD` | Applicant date of birth. | | `gender` | string | required, in: `male`, `female` | Applicant gender. | | `smoker` | boolean | required | Indicates if applicant is a smoker. | | `policy_term_years` | integer | required, min:5, max:40 | Policy term in years. | | `premium_frequency` | string | required, in: `monthly`, `quarterly`, `semi_annual`, `annual` | Billing frequency for premium. | | `sum_assured` | number | required if `target_premium` is missing, min:10000 | Desired life coverage amount in SAR. | | `target_premium` | number | required if `sum_assured` is missing, min:50 | Desired premium amount in SAR for selected frequency. | | `height_cm` | number | optional, min:100, max:250 | Applicant height in centimeters. | | `weight_kg` | number | optional, min:30, max:300 | Applicant weight in kilograms. | | `occupation_class` | string | optional | Occupation class code/text. | | `annual_income_sar` | number | optional, min:0 | Annual income in SAR. | | `riders` | object | optional | Optional rider flags such as `critical_illness`, `accidental_death`, etc. | | `distribution_channel` | string | optional, in: `bank`, default:`bank` | Distribution channel. | Example request: ``` POST /api/v1/life-snp/offers HTTP/1.1 Host: sandbox.yasmina.ai Accept: application/json Content-Type: application/json Authorization: Bearer { "applicant_id": "0123456789", "date_of_birth": "1990-06-15", "gender": "male", "smoker": false, "height_cm": 178, "weight_kg": 80, "occupation_class": "A", "annual_income_sar": 180000, "policy_term_years": 20, "premium_frequency": "monthly", "target_premium": 250, "riders": { "critical_illness": true, "waiver_of_premium": true }, "distribution_channel": "bank" } ``` Example response: ``` [ { "offer_id": "offer_01J8XYZ123", "insurer": "Insurer A", "sum_assured": 500000, "premium": 250, "premium_frequency": "monthly", "policy_term_years": 20, "riders_included": ["critical_illness", "waiver_of_premium"], "maturity_benefit": false, "notes": "Sample offer" } ] ``` ## Policies ### Issue policies To issue policies, use the Issue Policy API. This endpoint (`POST /api/v1/life-snp/policies`) issues a policy from a selected offer. The following fields are required when creating a Life S\&P policy. | Field | Type | Rules | Description | | ---------------------------------- | ------------- | ------------------------------------------------------------- | ---------------------------------------------- | | `offer_id` | string | required | Offer identifier returned by offers API. | | `applicant_id` | string | required, regex: `^\d{10}$` | Saudi National ID of the applicant. | | `date_of_birth` | string (date) | required, format: `YYYY-MM-DD` | Applicant date of birth. | | `gender` | string | required, in: `male`, `female` | Applicant gender. | | `smoker` | boolean | required | Indicates if applicant is a smoker. | | `policy_term_years` | integer | required, min:5, max:40 | Policy term in years. | | `premium_frequency` | string | required, in: `monthly`, `quarterly`, `semi_annual`, `annual` | Premium collection frequency. | | `agreed_premium` | number | required, min:50 | Final agreed premium. | | `start_date` | string (date) | required, format: `YYYY-MM-DD` | Requested policy start date. | | `beneficiaries` | array | required, min items:1 | Beneficiary list for payout distribution. | | `beneficiaries[].name` | string | required | Beneficiary full name. | | `beneficiaries[].national_id` | string | required, regex: `^\d{10}$` | Beneficiary national ID. | | `beneficiaries[].relationship` | string | required, in: `spouse`, `child`, `parent`, `sibling`, `other` | Relationship with applicant. | | `beneficiaries[].share_percentage` | number | required, min:0, max:100 | Share of total claim amount. | | `consent` | boolean | required | Applicant consent for issuance and auto-debit. | | `iban` | string | optional | Customer IBAN for premium collection. | | `sum_assured` | number | optional, min:10000 | Coverage amount in SAR. | Example request: ``` POST /api/v1/life-snp/policies HTTP/1.1 Host: sandbox.yasmina.ai Accept: application/json Content-Type: application/json Authorization: Bearer { "offer_id": "offer_01J8XYZ123", "applicant_id": "0123456789", "date_of_birth": "1990-06-15", "gender": "male", "smoker": false, "policy_term_years": 20, "premium_frequency": "monthly", "sum_assured": 500000, "agreed_premium": 250, "start_date": "2026-03-01", "iban": "SA0380000000608010167519", "beneficiaries": [ { "name": "Jane Doe", "national_id": "1234567890", "relationship": "spouse", "share_percentage": 100 } ], "consent": true } ``` Example response: ``` { "id": 1201, "client_id": "9f7db0ed-0783-4654-9b18-47c316809204", "provider_policy_id": 88321, "provider_policy": "Insurer A", "start_date": "2026-03-01", "end_date": "2046-03-01", "policy_term_years": 20, "sum_assured": 500000, "premium_amount": 250, "premium_frequency": "monthly", "status": "active", "beneficiaries": [ { "name": "Jane Doe", "national_id": "1234567890", "relationship": "spouse", "share_percentage": 100 } ], "iban_masked": "SA03*****************519", "is_claimed": false, "canceled_at": null, "created_at": "2026-02-20T10:12:00Z", "updated_at": "2026-02-20T10:12:00Z" } ``` ### Retrieving the policy object again You can retrieve previously created policies at any time using the List Policies API. Example request: ``` GET /api/v1/life-snp/policies HTTP/1.1 Accept: application/json Authorization: Bearer ``` ## Policy cancellation Use the Cancel Policy API to request cancellation. This endpoint is `POST /api/v1/life-snp/policies/{lifePolicy}/cancellation`. You can optionally upload a supporting file as `cancellation_document`. Example request: ``` POST /api/v1/life-snp/policies/1201/cancellation HTTP/1.1 Accept: application/json Content-Type: multipart/form-data Authorization: Bearer cancellation_document: ``` Example successful response: ``` HTTP/1.1 204 No Content ``` ## Claims Use the Submit Claim API to submit a life claim. This endpoint is `POST /api/v1/life-snp/policies/{policyId}/claims`. | Field | Type | Rules | Description | | --------------------- | ------------- | ----------------------------------------------------------------------- | ----------------------------------------- | | `claim_type` | string | required, in: `death`, `critical_illness`, `total_permanent_disability` | Type of claim being submitted. | | `event_date` | string (date) | required, format: `YYYY-MM-DD` | Date of incident/event. | | `requested_amount` | number | optional | Requested claim amount in SAR. | | `description` | string | optional | Additional event details. | | `supporting_document` | file | optional | Evidence document (medical report, etc.). | Example request: ``` POST /api/v1/life-snp/policies/1201/claims HTTP/1.1 Accept: application/json Content-Type: multipart/form-data Authorization: Bearer claim_type: death event_date: 2026-01-10 requested_amount: 500000 description: Natural causes supporting_document: ``` Example response: ``` { "claim_id": 782, "claim_type": "death", "requested_amount": 500000, "claim_status": "submitted", "policy_id": 1201, "created_at": "2026-02-20T11:02:00Z", "updated_at": "2026-02-20T11:02:00Z", "supporting_document": "claims/782/death-certificate.pdf" } ``` # Property Insurance Source: https://docs.yasmina.ai/single-provider-integrations/property Seamlessly embed property insurance into your platform, letting your customers insure their properties with just a click. ## Introduction This guide describes the Property Insurance APIs available on Yasmina’s platform. These APIs cover the core operations required for property insurance. This includes issuing and managing policies, generating payment links, and handling claims. Our APIs follow the RESTful standard and are structured to provide consistent inputs and outputs, making them straightforward to integrate, test, and maintain within your systems. ## What you will learn * Issuing policies * Uploading images for your insured property * Starting a claim ## Prerequisites 1. **Account in Yasmina** - See the Onboarding section for details. 2. **Authenticated Token** - Follow the Authentication guide to generate one. 3. **Backend server** - Required to securely call Yasmina APIs. ## Address from Short Code The GET Address Endpoint allows you to retrieve the **full property address** by providing only a short address code (e.g., Saudi Post short code). It is especially useful when users enter or scan their short address, and you need to automatically fill in the property details in the form. Example of a request ``` GET /api/v1/property/address-from-short?short_address=RRRC7866 HTTP/1.1 Host: production.yasmina.ai Authorization: Bearer Accept: application/json ``` Example of a response ``` { "building_number": "7866", "zip_code": "13342", "additional_number": "2641", "street_name": "Ahmad Al Gazali", "district_name": "Al Arid Dist.", "city_name": "Riyadh" } ``` Please note that the short address API does not provide *unit\_number*. This needs to be supplied separately to the Issue Policy API ## Policies ### Issue policies To issue policies, use the Issue Policies API. The following fields are required when creating a Property Insurance request. All requests must conform to these validation rules. | Field | Type | Rules | Description | | ------------------------------------ | ------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------- | | `personal_details` | object | required | Contains personal information of the policyholder. | | `personal_details.name` | string | required, max:255 | Full name of the policyholder. | | `personal_details.gender` | string | required, in: `M`, `F` | Gender of the policyholder. | | `personal_details.email` | string | required, max:255 | Email address of the policyholder. | | `personal_details.phone_number` | string | required, regex: `/^\+\d{10,15}$/` | Phone number in **international format** (e.g., `+966512345678`). | | `personal_details.birthdate` | date | required | Date of birth (ISO 8601 format recommended, e.g., `1990-05-20`). | | `personal_details.nationality` | string | required, in: list of supported countries | Country code of nationality (must match supported country codes). | | `personal_details.nationality_id` | string | required, max:20 | National ID, Iqama, or passport number. | | `building_details` | object | required | Details of the insured building. | | `building_details.building_age` | integer | required, min:0 | Age of the building in years. | | `building_details.building_type` | string | required, in: `apartment`, `villa`, `private_accommodation` | Type of property. | | `building_details.apartment_size` | integer | required, min:0 | Size of apartment in square meters (if applicable). | | `address` | object | required | Full address of the property. | | `address.street_name` | string | required, max:255 | Street name of the property. | | `address.building_number` | string | required, max:50 | Building number. | | `address.district_name` | string | required, max:255 | District/area name. | | `address.city_name` | string | required, in: availableCities config | City name (must match Yasmina’s supported cities list). | | `address.additional_number` | string | required, max:20 | Additional number (Saudi address standard). | | `address.zip_code` | string | required, max:20 | Zip/postal code. | | `address.unit_number` | string | required, max:20 | Unit/flat number. | | `property_cost` | numeric | nullable, required\_without: `contents_cost` | Estimated value of the building/property. Required if `contents_cost` is not provided. | | `contents_cost` | numeric | nullable, required\_without: `property_cost` | Estimated value of the home contents. Required if `property_cost` is not provided. | | `start_date` | date | required, after: today | Desired policy start date in `YYYY-MM-DD` format. Must be tomorrow or later. | | `has_agreed_to_terms_and_conditions` | boolean | accepted (`true`, `1`, `yes`) | Must explicitly confirm acceptance of terms and conditions. | Example request: ``` POST /api/v1/property/policies HTTP/1.1 Host: localhost:8000 Accept: application/json Content-Type: application/json Authorization: •••••• Content-Length: 868 { "insurance_provider": "walaa", "personal_details": { "email": "someone@example.com", "gender": "M", "name": "Customer Name", "phone_number": "+9665XXXXXXX", "birthdate": "1990-01-01", "nationality": "JO", "nationality_id": "**********" }, "building_details": { "building_age": 20, "building_type": "villa", "apartment_size": 200 }, "address": { "street_name": "Street Name", "district_name": "District Name", "city_name": "Riyadh", "additional_number": "X", "zip_code": "XXXXX", "unit_number": "X", "building_number": "X" }, "property_cost": 500000, "contents_cost": 100000, "start_date": "2025-12-11", "has_agreed_to_terms_and_conditions": true, "redirect_url": "https://www.example.com?policy_id=XXXXXX" } ``` Example Response ``` { "id": 874, "meta_data": { "address": { "zip_code": "11193", "city_name": "Riyadh", "street_name": "Street Name", "unit_number": "X", "district_name": "District Name", "building_number": "X", "additional_number": "X" }, "property_cost": 500000, "building_details": { "building_age": 20, "building_type": "villa", "apartment_size": 200 }, "personal_details": { "name": "Customer Name", "email": "someone@example.com", "gender": "M", "birthdate": "1990-01-01", "nationality": "JO", "phone_number": "+96279XXXXXXX", "nationality_id": "**********" }, "insurance_provider": "walaa", "start_date": "2025-12-11", "has_agreed_to_terms_and_conditions": true }, "created_at": "2025-11-20T12:06:09.000000Z", "canceled_at": null, "status": 0, "provider_policy": null, "provider_policy_id": null, "client_id": "********-****-****-****-************", "payment_link": "http://localhost:8000/short/XXXXX", "price": 603.75, "redirect_url": "https://www.google.com?policy_id=874", "policy_url": null } ``` ### Retrieving the policy object again You can retrieve the policy objects that were created by you any time by either using the Listing policies API or the Show policy API The Listing policy API can take some filters to retrieve only specific policies. This might be helpful if you have your own internal system and want to list policies by different values. Example Request ``` GET /api/v1/property/policies?nationality_id=9881052027 HTTP/1.1 Accept: application/json Authorization: •••••• ``` The Show Policy API will retrieves a specific policy object based on path ID Example Request ``` GET /api/v1/property/policies/875 HTTP/1.1 Accept: application/json Authorization: •••••• ``` ### Cancellation Status The Cancellation Status API gets you an updated status of your policy. Yasmina makes a call to the insurance provider to inquire about the policy, and will return a response with updated status. Example Request ``` GET /api/v1/property/policies/849/cancellation-status HTTP/1.1 Accept: application/json Authorization: •••••• ``` Example Response ``` { "status": "active" } ``` ### Understanding Payment and Policy activation When you first make a request to the Issue Policy API. The Policy is not yet activated and the `status` is `0` (which means pending). Also the `provider_policy` and `provider_policy_id` will both be `null`. In order for the policy to be activated, the customer needs to make the purchase from the payment link. Once the customer successfully pays. The policy will be activated and the `status` becomes `1`. Although the payment page is provided by Yasmina, it does not display the Yasmina logo or have any mention of Yasmina.

Yasmina does not receive credit card information, instead the payment page sends card information directly to the payment vendor. On Sandbox, you can use a testing card with the following information:
Card number: 4111 1111 1111 1111
Expiry: 02/27
CVV: 123
Card owner: Yasmina test ### Upload Images Supporting documents are required from your clients. These can include home photos, images of valuable contents, or surrounding areas. You can upload these documents using the Upload Document API # SME Medical Insurance Source: https://docs.yasmina.ai/single-provider-integrations/sme-medical-insurance Issue SME medical insurance policies for a company’s employees and collect their health declarations. ### Overview This guide walks you through integrating Yasmina’s Medical Insurance API into your platform (for Multiple Insurance Providers with package comparison, [click here](/price-comparison/sme-medical-insurance)). Using our secure and reliable endpoints, you’ll be able to request and manage policies, and issue claims. Everything you need to deliver insurance services seamlessly within your application. ### Basic Journey 1. **Authorize**: Get an access token to authenticate all API requests. 2. **Create a Company**: Register the SME that will provide medical insurance for its employees. 3. **Choose a Package**: Retrieve and review available medical insurance packages. 4. **Issue Insurance**: Select the employees who will be covered and create their policies. 5. **Health Declarations**: Complete forms on behalf of employees or send them directly for completion. 6. **Payment**: Receive a secure payment link to finalize the purchase. ### Authorization To access any of our API's. You need to authorize yourself using the Generate Token API. We are using the standard OAuth 2.0 client credentials.
The Generate Token API requires `client_id` and `client_secret`. You can get these from your [portal](https://portal.yasmina.ai/api-management).
After making the request, you will get access\_token in the response. Example ``` { "token_type": "Bearer", "expires_in": 31536000, "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiI5YmEyOTNmNy01ZjYyLTRlODItYmU5Yi1kODA0Y2M5ZDM5MmMiLCJqdGkiOiJlZWJjMWM5MWEyZThkMTVmNTYxNjZjMjkwM2Q0NTZjM2IzYWM5MTU5ZTdkODQ2YTE5NmFlYjcxMWM5OTJlMjc2MzAzNjY3MDA1MDQzM2U0OSIsImlhdCI6MTczNTkwNTE5OC40NTg5MiwibmJmIjoxNzM1OTA1MTk4LjQ1ODkyMSwiZXhwIjoxNzY3NDQxMTk4LjQ1Njk0LCJzdWIiOiIiLCJzY29wZXMiOltdfQ.Dy6df9fr4eBMLtkjnzcBjrXSg2AZLrmrBBC1NF8wmQaIOjcNffiqMiL9MqdMPj43Dxt4fj9rT1_S8dfwEpSbxNuIweNLOa7iDYpqMQ2l-cKG_sn24G27exZ9shLG8p2FHa4SHxSByRw00aCJceiTzq12LLNfc14rGPKZOv5Pi-HuLAP6ms_NfyN-KafOFOjYym4PyHCuTX8jEkoImgpBUpPgdnq1qyQdrZxL4grp0P_ezkhTgHgWwuzjSYgm4l-Eyga65kua-pdgWbhJ7-I1W_hjWT2dKCivcmk6nR9wtTjWs9hBvZrOfoZmox4YPIjZ_pvImZbHcZui-7xs80dnoaTKRviR8aot0cPIKoqRwinBodjWRh3QEu5juT1b7T-m85Wo_JNRoarKD4pW2Lzq7v1u9Z6PMEeYXvuFchzZ6HPvthblfwbtu3AX6ij0ZGlZPdMRdEiRtZf3dt8nsWdI-E_J0GAD-9wexlpNL92Z-IfuwMXuUQs_j4l92fcfBC_NxlEUTNACyOWPrA3V6ZSLHrga6W4Iz6Por3txzCsxlwvEBQAM70VyGeSqFi0wMLg2V8wVYAEpiEe2dl4RpMbUaPzRNc_KsDUYM_4DqwMTo2v2x4AAPxWmWiRn4PeAXovraN6Ll-eW9zq5hUbt3c-yj0spVYhJADHodoHmAdQM9MA" } ``` The `access_token` must be used on all future Yasmina APIs and be supplied in the Authorization Header in the following form Authorization: Bearer \{access\_token} For security reasons. Do not make your client\_id and client\_secret public in your platform. ### Create a Company record After acquiring an access\_token, you can begin using the APIs. Before you produce policies for a company, you must create a company record. After creating the company record, you can request to issue policies to the employees of that company. The The Create Company API, will require a few fields that define details of the company such as Email, Phone, the company's unified national number, a 10-digit sponsor number, and a 10-digit commercial registration number that starts with 7. It will return a response with a unique identifier (id). Here is an example of the response from the POST companies API. ``` { "name": "Example company name", "name_ar": "مثال اسم شركة", "sponsor_number": "1000000001", "unified_national_number": "7000000001", "email_address": "example@example.com", "phone_number": "+966512345678", "commercial_registration_number": "7000000002", "client_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "updated_at": "2025-08-01T14:22:30.000000Z", "created_at": "2025-08-01T14:22:30.000000Z", "id": 42 } ``` You can also visit the [List companies API](/medical-api-reference/company/list-companies) to show all companies you've created ### List available packages After creating a company record, you can list available packages to the company. Check out the [Categories API](/medical-api-reference/products/list-categories). This gives you a list of available insurance categories. 1. The Insurance provider PDF * Contains an overview picture of what is provided by the Insurance provider 2. The translations * The translations includes **keys** that map to the instructional text in Arabic and English that were provided by the insurance provider. 3. The categories * The categories items uses these keys and gives the coverage values Each employee can have a separate package. Coverage values can either be a number (the amount), or a boolean (whether it's covered or not), or a text (the type of coverage) Each item in the categories has a `category` property. This is an important property as it is what you will need to provide when you issue policies. Notice the category field in the following sample of the categories response API. ``` "categories": { "basic": { "name": "Basic", "category": "basic", "maximum_annual_benefit_limit_per_person": 500000, "geography": "Saudi Arabia", "general_coverage": { ... } ... } ``` ### Issue insurance policies To issue policies, you need to execute the [Issue policy API](/medical-api-reference/policies/issue-the-policy). The API takes three fields. The company\_id as referenced above, the insurance\_provider (`medgulf` for this integration), and an array called insured. The insured are the employees that the company wants to issue insurance for. Here is an example of a payload you would send ``` { "insurance_provider": "medgulf", "insured": [ { "name": "John Doe", "nationality_iso": "SA", "category": "basic", "nationality_id": "1111111111", "date_of_birth": "1409-09-14", "dependents": [ { "name": "Jane Doe", "relationship": "spouse", "nationality_iso": "SA", "nationality_id": "1111111112", "date_of_birth": "1411-01-05" }, { "name": "Jack Doe", "relationship": "child", "nationality_iso": "SA", "nationality_id": "1111111113", "date_of_birth": "1437-04-22" } ] }, { "name": "Richard Roe", "nationality_iso": "JO", "category": "standard", "iqama_id": "2222222222", "date_of_birth": "1988-04-20", "dependents": [] } ], "company_id": 1 } ``` Notice in the above, there are two employees within the company. John is Saudi (`nationality_iso` is `SA`), so we supply his `nationality_id`. Richard is not Saudi, so we supply his `iqama_id` instead. The API rejects the request if a Saudi employee has no `nationality_id` or a non-Saudi employee has no `iqama_id`. The `category` that we are supplying is what was returned from the [Categories API](/medical-api-reference/products/list-categories) #### Dependents An employee can bring family members onto the policy through the `dependents` array. Each dependent needs a `name`, a `relationship` to the employee (`spouse`, `child` or `parent`), a `nationality_iso`, a `date_of_birth`, and the same identifier rule as the employee: `nationality_id` for Saudis, `iqama_id` for everyone else. Dependents are covered by the employee's provider and category; they cannot have a package of their own. Leave the array out, or send it empty, for an employee with no dependents. #### Dates of birth Send every `date_of_birth` as `YYYY-MM-DD`. Saudi nationals whose national id starts with `1` give the Hijri (Umm al-Qura) date printed on their id, as John and his family do above; everyone else gives a Gregorian date. Employees must be between 18 and 110 years old; dependents can be any age. ### HR declaration forms The companies that have requested insurance needs to be supply the insurance provider with Medical forms. These are mandatory for insurance providers to know past medical histories. Yasmina offers two ways to collect them: 1. **Fill Medical Forms:** Company administrators fill out the forms on behalf of the employees. 2. **Download the form:** Get a printable PDF and send it to the employees yourself. Detailed explanations for each method are provided below. The fill medical forms allows the company admin to do so on behalf of the employers of the company. It takes two fields of which both are objects `all_employees` and `ids_or_emails`. The idea behind the two fields, is to allow the Company admin to select the default answers for all employees, and then override the answers for specific employees. For example, let us say that all employees except 1 (for example employee with email [john.doe@example.com](mailto:john.doe@example.com)), never had surgeries before, we can declare the answer `No` on the surgery question in the all\_employees field, but declare `Yes` for the other employee.employee Here's an example of such case ``` { "all_employees": { "allergies": "No", "current_medications": "No", "hospitalizations": "No", "pre_existing_conditions": "No", "past_surgeries": "No", "surgery_complications": "No", "chest_pain_or_breathlessness": "No", "heart_procedures": "No", "smoking": "No", "alcohol_consumption": "No", "physical_activity": "No", "family_history": "No", "chronic_disease": ["None of the above"] }, "ids_or_emails": [ { "id_or_email": "john.doe@example.com", "answers": { "allergies": "No", "current_medications": "No", "hospitalizations": "No", "pre_existing_conditions": "No", "past_surgeries": "Yes", "surgery_complications": "No", "chest_pain_or_breathlessness": "No", "heart_procedures": "No", "smoking": "No", "alcohol_consumption": "No", "physical_activity": "No", "family_history": "No", "chronic_disease": ["Liver Disease"] } } ] } ``` Check out the [Fill medical forms API](/medical-api-reference/medical-forms/fill-the-declarations) docs for all the supported props. The [Download declaration form API](/medical-api-reference/medical-forms/download-the-declaration-form) returns the declaration as a PDF. Pass the `company_id` and the file carries one page per employee you have already enrolled, with their name, id and package filled in, so the company can print it or email it on. Leave `company_id` out and you get a single blank form. ### Payment Yasmina will supply a payment link of which your clients can pay for the insurance. You must share this link in your platform. # Travel Insurance Source: https://docs.yasmina.ai/single-provider-integrations/travel Embed Schengen travel insurance into your platform, allowing your customers to insure their trips quickly and seamlessly. ## Introduction This guide describes the **Travel Insurance APIs** available on Yasmina’s platform. These APIs cover the core operations required for issuing and managing travel insurance policies, including quoting, issuing policies, generating payment links, and handling claims. Our APIs follow RESTful standards and are designed with consistent request and response structures, making them easy to integrate, test, and maintain within your systems. ## What you will learn * Creating travel insurance quotes * Handling payments * Issuing and showing the policy ## Prerequisites 1. **Account in Yasmina** – See the Onboarding section for details. 2. **Authenticated Token** - You can follow the Authentication guide or head straight to the Generate Token API. 3. **Backend server** - Required to securely call Yasmina APIs. ## Travel Insurance Overview Travel insurance is designed to cover individuals or groups during international trips. Yasmina currently supports **Schengen-compliant travel insurance**, with configurable trip duration and multi-traveller support. A typical travel insurance flow includes: 1. Collecting trip and traveller information 2. Requesting a quote 3. Issuing the policy 4. Completing payment 5. Downloading policy documents *** ## Request Quote In this step, your customer provides information about the trip and you present them with the price of the insurance. In order to request a quote, you need to execute the following Request Quote API. ### Endpoint `POST /api/v1/travel/quotes` ### Example request ```json theme={null} { "nationality_id": "1234567890", "phone_number": "+966501234567", "email": "someone@example.com", "multi_entry": false, "duration": 10, "start_date": "2026-02-27", "date_of_birth": "1988-04-20", "travellers": [ { "nationality": "SA", "full_name": "Yasmina Alex", "passport_number": "G12345678", "gender": "m", "date_of_birth": "1982-04-20", "relation": "self", "passport_expiry_date": "2026-10-30" } ] } ``` Once you execute the request quote API. You get a response with the quotation object. Most importantly you get a `quote_id` field. The value is needed later in the Purchase Policy API. ### Example response ```json theme={null} { "client_id": "****", "quote_id": "Q-V1GN40HU", "meta_data": { "travellers": [ { "nationality": "SA", "full_name": "Yasmina Alex", "passport_number": "G12345678", "gender": "m", "date_of_birth": "1982-04-20", "relation": "self", "passport_expiry_date": "2026-10-30" } ], "multi_entry": false, "start_date": "2026-02-27", "duration": 10 }, "nationality_id": "1234567890", "phone_number": "+966501234567", "email": "someone@example.com", "date_of_birth": "1988-04-20", "type": "yasmina_schengen_travel_insurance", "bill": { "items": { "adult": { "count": 1, "price": 55, "total": 55 } }, "adminFees": 25 }, "price": 92, "updated_at": "2026-02-03T07:12:38.000000Z", "created_at": "2026-02-03T07:12:38.000000Z", "travellers": [ { "nationality": "SA", "full_name": "Yasmina Alex", "passport_number": "G12345678", "gender": "m", "date_of_birth": "1982-04-20", "relation": "self", "passport_expiry_date": "2026-10-30" } ], "multi_entry": false, "start_date": "2026-02-27", "duration": 10 } ``` *** ## Purchase the Travel Policy Before your customers can get the Travel Insurance Policy, they will need to complete the payment. The Purchase Policy API is used to get a policy object with a payment link. You will need to provide the `quote_id` obtained from the previous step. Afterwards you get a response that has a policy object, and in that response there is a `payment_link`. Redirect the customer to this link to complete the payment process. ### Endpoint `POST /api/v1/yasmina-schengen-travel` ### Example request ```json theme={null} { "quote_id": "Q-FNWXGDPK", } ``` ### Example response ```json theme={null} { "id": 936, "meta_data": { "bill": { "items": { "adult": { "count": 1, "price": 55, "total": 55 } }, "adminFees": 25 }, "email": "someone@example.com", "price": 92, "duration": 10, "quote_id": 1, "start_date": "2026-02-27", "travellers": [ { "gender": "m", "relation": "self", "full_name": "Yasmina Alex", "nationality": "SA", "date_of_birth": "1982-04-20", "passport_number": "G12345678", "passport_expiry_date": "2026-10-30" } ], "multi_entry": false, "phone_number": "+966501234567", "date_of_birth": "1988-04-20", "nationality_id": "1234567890" }, "product_id": 8, "client_id": "a0fd456b-853d-4511-b80f-2bfdb0e66303", "canceled_at": null, "provider_policy_id": null, "provider_policy": null, "start_date": null, "pdf_parsed": 0, "cancellation_document": null, "invoice": null, "has_sent_cancellation_email": 0, "created_at": "2026-02-03T07:12:45.000000Z", "updated_at": "2026-02-03T07:12:45.000000Z", "status": 0, "transfer_date_at": null, "cancellation_request_at": null, "deleted_at": null, "is_old_policy": 0, "payment_link": "https://sandbox.yasmina.ai/short/4OrJN", "price": 92, "insurance_company_id": null, "redirect_url": null, "hidden_meta_data": null, "uploaded_at": null, "policy_url": null, "invoice_url": null } ``` ### Redirect URL In addition to supplying the `quote_id` you can also add `redirect_url`. This is used to redirect the customer to any page or deep link you need after the payment is completed. You can also include a query string with policyID and it will automatically replace it with the actual `id` of the policy object. Example for policy `id` 123 ``` { quote_id: "Q-FNWXGDPK", redirect_url: "https://www.example.com?yasmina_policy_id=policyID" } ``` Will become on the response ``` { redirect_url: "https://www.example.com?yasmina_policy_id=123" } ``` And the customer that purchased the policy will be redirected to [https://www.example.com?yasmina\_policy\_id=123](https://www.example.com?yasmina_policy_id=123) *** ### Showing & Downloading the policy In order to get a status of a policy, you can use the Show Policy API. This API, takes a Yasmina Policy `id` and will return the policy object The response includes both `policy_url` and `invoice_url`, these URLs contain pdf files that your customer can download. # Guide to using Webhooks Source: https://docs.yasmina.ai/webhooks/guide Webhooks allow your system to receive real-time notifications from Yasmina whenever key events occur. This enables seamless integrations and automated workflows. You can manage Webhooks from API Management Webhooks ### Available Webhooks | Event | Description | | ------------------- | -------------------------------------------------- | | **Status Update** | Triggered when the status of a policy changes. | | **Document Update** | Triggered when a document is uploaded to a policy. | Each webhook can be configured with a callback **URL** where you will receive the event payloads. *** ### Webhook Security To ensure the authenticity of incoming requests, Yasmina includes a **Webhook Key** in the header of every webhook request. * **Header**: `x-webhook-key` * **How to get it**: You can generate and manage your Webhook Key by clicking Edit and the refresh icon in the Webook key field Make sure to validate this key in your endpoint handler to confirm that the request originated from Yasmina. *** ### Testing the webhook Yasmina allows you to test your Webhook instantly. Simply Click on "Test call". *** ### Payload Structure Webhook requests are sent as `POST` requests with a JSON body. The payload will be the same object that you acquire when you create a policy, for example: ```json theme={null} { "id": 641, "user_id": 33, "meta_data": { "vin": "****MASKED_VIN****", "new_owner_id": "****MASKED_ID****", "current_car_owner": "****MASKED_ID****", "car_sequence_number": "****MASKED_SEQ****" "extra_fields": {} }, "product_id": 1, "client_id": "****MASKED_UUID****", "canceled_at": null, "provider_policy_id": "****MASKED_POLICY_ID****", "provider_policy": null, "cancellation_document": null, "invoice": null, "has_sent_cancellation_email": 0, "created_at": "2025-08-05T08:29:39.000000Z", "updated_at": "2025-08-05T08:29:39.000000Z", "status": 0, "transfer_date_at": null, "cancellation_request_at": null, "deleted_at": null, "is_old_policy": 0, "policy_url": "", "invoice_url": "", "client": { "id": "****MASKED_UUID****", "user_id": 33, "name": "****MASKED_CLIENT_NAME****", "provider": null, "redirect": "", "personal_access_client": false, "password_client": false, "revoked": false, "created_at": "2025-07-23T11:13:22.000000Z", "updated_at": "2025-07-23T11:19:55.000000Z", "product_id": 1, "is_policy_provider": 0, "is_approved": 1 } } ``` # Motor Insurance Iframe and WebView Source: https://docs.yasmina.ai/whitelabel/motor-insurance Drop the whole comprehensive motor journey into your website or your mobile app. Your customer compares prices, picks a plan and gets a policy without leaving you. Give us the customer's details from your backend, and we give you back a URL. Put that URL in an iframe on your website, or in a WebView in your app, and the rest of the journey happens inside it: comparing quotes across providers, add-ons, the payout account, vehicle photos and the verification code. When the policy is issued we hand it to you with a payment link, and the embed goes blank so your own screen can take over. You do not build any of those screens, and you do not handle the customer's verification code. This covers **Comprehensive Motor Insurance (Multiple Providers)**. Your account needs that product enabled. See [Onboarding](/introduction#onboarding). ## Before you start Register where the embed is allowed to run, in [API Management](https://portal.yasmina.ai/api-management) under **Yasmina Iframe and WebView**. A session can only be opened for something on these lists. | Field | For | Example | | ------------------------------------ | ----------- | ------------------------- | | **Iframe hosts (websites)** | the iframe | `https://www.example.com` | | **WebView deep links (mobile apps)** | the WebView | `myapp://insurance/done` | Add every site you will embed from. `https://example.com` and `https://www.example.com` are different sites to a browser, so list both if you serve both. ## The flow Call the [Quote OTP API](/car-api-reference/otps/request-otp-for-quote-verification) with the customer's ID, email and phone. This one is yours because it happens before the embed exists. Call [Create Embed Session](/car-api-reference/embed-sessions/create-embed-session) with the same payload you would send to [Request Quotes](/car-api-reference/quotes/request-quotes), plus where the session will run. We fetch the quotes and hand back a URL. Put the URL in an iframe or a WebView. We send you the issued policy, including its payment link. Take the customer to payment from there. ## Open a session ``` POST /api/v1/car-comp/embed-sessions ``` Send `Accept: application/json`, as with every Yasmina API. Everything [Request Quotes](/car-api-reference/quotes/request-quotes) takes, plus: `web` for an iframe, `webview` for a mobile app. There is no default: each one requires a different field below. Web only. The site the iframe will sit on, scheme and domain with nothing after it. Must be one of your iframe hosts. WebView only. Where your app is reopened once the policy is issued. Must be one of your registered deep links. `ar` or `en`. Defaults to the customer's browser. ```bash Website theme={null} curl -X POST 'https://sandbox.yasmina.ai/api/v1/car-comp/embed-sessions' \ --header 'Authorization: Bearer ' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "otp": "1234", "owner_id": "1234567890", "email": "customer@example.com", "phone": "0500000000", "birthdate": "1990-01-01", "car_sequence_number": "123456789", "car_estimated_cost": 45000, "car_model_year": 2022, "is_ownership_transfer": false, "platform": "web", "parent_origin": "https://www.example.com" }' ``` ```bash Mobile app theme={null} curl -X POST 'https://sandbox.yasmina.ai/api/v1/car-comp/embed-sessions' \ --header 'Authorization: Bearer ' \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --data '{ "otp": "1234", "owner_id": "1234567890", "email": "customer@example.com", "phone": "0500000000", "birthdate": "1990-01-01", "car_sequence_number": "123456789", "car_estimated_cost": 45000, "car_model_year": 2022, "is_ownership_transfer": false, "platform": "webview", "deep_link": "myapp://insurance/done" }' ``` ```json Response theme={null} { "id": 1, "quote_request_id": 42, "platform": "web", "embed_url": "https://.../embed?session=8TJLiR0YhE8ikWSH3N16br2Q4qDg0ozGu18c5c3E", "expires_at": "2026-01-01T12:00:00+00:00" } ``` There is no permanent embed URL. Each one belongs to one customer and expires after **one hour**. Create a session per customer, when they are ready to see prices. `quote_request_id` is yours to keep for your own records. You never have to send it back. ## On a website ```html theme={null} ``` Listen for the policy. Always check the origin, and use the origin of the `embed_url` you were given rather than hardcoding one: ```js theme={null} const embedOrigin = new URL(embedUrl).origin window.addEventListener('message', (event) => { if (event.origin !== embedOrigin) return if (event.data.type === 'yasmina:policy-issued') { const policy = event.data.policy window.location = policy.payment_link } }) ``` Only the site you registered as `parent_origin` can load the embed. Anywhere else gets a blank frame, refused by the browser. ## In a mobile app Load the same `embed_url` in a WebView. When the policy is issued we reopen your app at your `deep_link` with the policy id on it: ``` myapp://insurance/done?yasmina_policy_id=9001 ``` Look the policy up with [Show Policy](/car-api-reference/policies/show-policy) to get its payment link. A WebView needs setting up before this works. Two things fail **silently** if you skip them: on Android the vehicle photo step does nothing at all without a file chooser, and JavaScript is disabled by default. Neither shows an error. ### iOS ```swift theme={null} import WebKit final class InsuranceViewController: UIViewController, WKNavigationDelegate { private var webView: WKWebView! override func viewDidLoad() { super.viewDidLoad() webView = WKWebView(frame: view.bounds) webView.navigationDelegate = self view.addSubview(webView) webView.load(URLRequest(url: URL(string: embedUrl)!)) } // Required: WKWebView will not open your deep link on its own. func webView( _ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler: @escaping (WKNavigationActionPolicy) -> Void ) { guard let url = navigationAction.request.url else { decisionHandler(.allow) return } if url.scheme == "myapp" { decisionHandler(.cancel) finish(with: url) // read yasmina_policy_id return } decisionHandler(.allow) } } ``` Add `NSCameraUsageDescription` to your `Info.plist`. Without it iOS terminates the app the moment a customer taps **Take Photo** on the vehicle photo step. Choosing an existing photo instead goes through a picker that runs outside your app, and needs no key. ### Android ```kotlin theme={null} webView.settings.javaScriptEnabled = true // off by default webView.settings.domStorageEnabled = true webView.webViewClient = object : WebViewClient() { override fun shouldOverrideUrlLoading( view: WebView, request: WebResourceRequest ): Boolean { if (request.url.scheme == "myapp") { finish(request.url) // read yasmina_policy_id return true } return false } } // Required for the vehicle photos. Without this, tapping does nothing. webView.webChromeClient = object : WebChromeClient() { override fun onShowFileChooser( view: WebView, callback: ValueCallback>, params: FileChooserParams ): Boolean { // Launch your picker, then hand the result to callback. return true } } webView.loadUrl(embedUrl) ``` Request `CAMERA` at runtime if customers will photograph the vehicle in the app. ### Getting the whole policy instead of just the id Optional. If you would rather receive the full policy than look it up, expose a bridge and we will use it, falling back to the deep link if it is not there. ```swift iOS theme={null} let controller = WKUserContentController() controller.add(self, name: "yasmina") // this exact name let config = WKWebViewConfiguration() config.userContentController = controller webView = WKWebView(frame: view.bounds, configuration: config) // WKScriptMessageHandler func userContentController( _ controller: WKUserContentController, didReceive message: WKScriptMessage ) { guard let json = message.body as? String else { return } // { "type": "yasmina:policy-issued", "policy": { ... } } } ``` ```kotlin Android theme={null} class YasminaBridge(private val onMessage: (String) -> Unit) { @JavascriptInterface fun postMessage(payload: String) = onMessage(payload) } webView.addJavascriptInterface( YasminaBridge { json -> /* handle */ }, "YasminaAndroid", // this exact name ) ``` ## What you receive ```json theme={null} { "type": "yasmina:policy-issued", "policy": { "id": 9001, "policy_number": "...", "status": 0, "payment_link": "https://...", "company_name": "..." } } ``` The embed also sends `{ "type": "yasmina:ready" }` once it has loaded, which is useful for hiding your own loading state. The policy is issued but unpaid. Take the customer to `payment_link` to activate it. Your [webhooks](/webhooks/guide) fire on payment as they always do. ## Showing the quotes again The URL works for its full hour and survives a refresh, so a customer who reloads keeps their place. Once the hour is up, call the same endpoint again with the same payload. You can reuse the verification code the customer already gave you, since it stays valid for hours, so they are not asked for a new one. The new session opens on fresh quotes rather than hour-old prices. [Show Embed Session](/car-api-reference/embed-sessions/show-embed-session) returns a session you already created, and tells you whether it has expired. ## Skipping the photo step Comprehensive cover needs five photos of the car, and by default the customer takes them inside the embed. If your site or app already has them, hand them over with [Store Vehicle Photos for an Embed Session](/car-api-reference/embed-sessions/store-vehicle-photos-for-an-embed-session) right after opening the session: the same five files as the upload endpoint, JPG or PNG, up to 3 MB each. The embed then shows no photo step, and Yasmina registers your photos with the provider against whichever quote the customer picks. This call exists for the embed only. A server-to-server integration uploads photos against the selected quote with [Upload Vehicle Photos](/car-api-reference/quotes/upload-vehicle-photos) instead. ## When something is wrong | Response | Meaning | | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `422` on `platform` | Say `web` or `webview`. It is never assumed. | | `422` on `parent_origin` | The site is not one of your iframe hosts. The message names it. | | `422` on `deep_link` | The link is not one of your registered deep links. The message names it. | | `422` on `return_url` or `parent_origin` being prohibited | You sent the field belonging to the other platform. | | A blank iframe | The page is framed on a site you did not register. | | `400` with a quote error | The quote itself failed. Same codes and messages as [Request Quotes](/car-api-reference/quotes/request-quotes). | # HTML Snippets Source: https://docs.yasmina.ai/whitelabel/snippets Yasmina provides ready-to-use HTML Snippets built with Bootstrap 5 (more will be added) to help you quickly add insurance products to your website. These snippets are designed to accelerate your front-end development process by giving you a fully responsive and styled UI out of the box. We currently have it available for Motor Insurance. Motor Insurance snippet ### What Are HTML Snippets? The HTML Snippets are pre-built components that you can copy and paste into your site. ### How to add it? Simply add the following code to your website. Do some tweaks to make it match your website's look & feel. ```html theme={null}
Add Insurance by
Price: 0 SAR
``` You can see a live demo here: [https://www.yasinsurance-demo.site/car-insurance](https://www.yasinsurance-demo.site/car-insurance) *** ### Key Benefits * Speeds up front-end development * Works out-of-the-box with Bootstrap 5 * Fully responsive and mobile-friendly * No backend integration required to get started * Simple enough to be used without extensive documentation *** # List policies Source: https://docs.yasmina.ai/yasmina-schengen-travel-insurance/policies/list-policies /yasmina-schengen-travel-insurance/openapi.json get /policies # Purchase Source: https://docs.yasmina.ai/yasmina-schengen-travel-insurance/policies/purchase /yasmina-schengen-travel-insurance/openapi.json post /policies # Show policy Source: https://docs.yasmina.ai/yasmina-schengen-travel-insurance/policies/show-policy /yasmina-schengen-travel-insurance/openapi.json get /policies/{travelPolicy} Show a specific policy # Request Quote Source: https://docs.yasmina.ai/yasmina-schengen-travel-insurance/quotes/request-quote /yasmina-schengen-travel-insurance/openapi.json post /quotes