Life Insurance (S&P)

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

Account in Yasmina - See the Onboarding section for details.
Authenticated Token - Follow the Authentication guide to generate one.
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 <token>

{
	"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 <token>

{
	"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 <token>

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 <token>

cancellation_document: <file>

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 <token>

claim_type: death
event_date: 2026-01-10
requested_amount: 500000
description: Natural causes
supporting_document: <file>

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"
}

Getting Started

Insurance Integration Guides

API Resources

Webhooks

White-labeling Solutions

Introduction

What you will learn

Prerequisites

Offers

Generate offers

Policies

Issue policies

Retrieving the policy object again

Policy cancellation

Claims

​Introduction

​What you will learn

​Prerequisites

​Offers

​Generate offers

​Policies

​Issue policies

​Retrieving the policy object again

​Policy cancellation

​Claims

Introduction

What you will learn

Prerequisites

Offers

Generate offers

Policies

Issue policies

Retrieving the policy object again

Policy cancellation

Claims