Skip to main content

​
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.
FieldTypeRulesDescription
applicant_idstringrequired, regex: ^\d{10}$Saudi National ID of the applicant (10 digits).
date_of_birthstring (date)required, format: YYYY-MM-DDApplicant date of birth.
genderstringrequired, in: male, femaleApplicant gender.
smokerbooleanrequiredIndicates if applicant is a smoker.
policy_term_yearsintegerrequired, min:5, max:40Policy term in years.
premium_frequencystringrequired, in: monthly, quarterly, semi_annual, annualBilling frequency for premium.
sum_assurednumberrequired if target_premium is missing, min:10000Desired life coverage amount in SAR.
target_premiumnumberrequired if sum_assured is missing, min:50Desired premium amount in SAR for selected frequency.
height_cmnumberoptional, min:100, max:250Applicant height in centimeters.
weight_kgnumberoptional, min:30, max:300Applicant weight in kilograms.
occupation_classstringoptionalOccupation class code/text.
annual_income_sarnumberoptional, min:0Annual income in SAR.
ridersobjectoptionalOptional rider flags such as critical_illness, accidental_death, etc.
distribution_channelstringoptional, in: bank, default:bankDistribution 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.
FieldTypeRulesDescription
offer_idstringrequiredOffer identifier returned by offers API.
applicant_idstringrequired, regex: ^\d{10}$Saudi National ID of the applicant.
date_of_birthstring (date)required, format: YYYY-MM-DDApplicant date of birth.
genderstringrequired, in: male, femaleApplicant gender.
smokerbooleanrequiredIndicates if applicant is a smoker.
policy_term_yearsintegerrequired, min:5, max:40Policy term in years.
premium_frequencystringrequired, in: monthly, quarterly, semi_annual, annualPremium collection frequency.
agreed_premiumnumberrequired, min:50Final agreed premium.
start_datestring (date)required, format: YYYY-MM-DDRequested policy start date.
beneficiariesarrayrequired, min items:1Beneficiary list for payout distribution.
beneficiaries[].namestringrequiredBeneficiary full name.
beneficiaries[].national_idstringrequired, regex: ^\d{10}$Beneficiary national ID.
beneficiaries[].relationshipstringrequired, in: spouse, child, parent, sibling, otherRelationship with applicant.
beneficiaries[].share_percentagenumberrequired, min:0, max:100Share of total claim amount.
consentbooleanrequiredApplicant consent for issuance and auto-debit.
ibanstringoptionalCustomer IBAN for premium collection.
sum_assurednumberoptional, min:10000Coverage 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.
FieldTypeRulesDescription
claim_typestringrequired, in: death, critical_illness, total_permanent_disabilityType of claim being submitted.
event_datestring (date)required, format: YYYY-MM-DDDate of incident/event.
requested_amountnumberoptionalRequested claim amount in SAR.
descriptionstringoptionalAdditional event details.
supporting_documentfileoptionalEvidence 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"
}