Proposal APIs

The Proposal APIs allow you to create and manage insurance proposals, track their status, and facilitate the policy issuance process. These APIs enable you to convert quotes into formal insurance applications by collecting detailed customer information and policy preferences.

Create Proposal

Create a new insurance proposal with customer and policy details. This endpoint transforms a quote into a formal insurance application by collecting all required policyholder information.

Endpoint

POST /v1/embedded/proposal

Request

Body

{
  "quote_id": "quo_18M6aOiODyyf37DM",
  "recommendation_id": "rec_18M6aOiODyyf37DN",
  "status": "DRAFT",
  "proposer": {
    "title": "MR",
    "first_name": "John",
    "middle_name": "Pastor",
    "last_name": "Doe",
    "email": "johndoe@example.com",
    "mobile": "9876543210",
    "country_code": "+91",
    "date_of_birth": "05/06/1990",
    "address": {
      "address_line_1": "123 XYZ Street",
      "address_line_2": "ABC Layout",
      "address_line_3": "",
      "city": "Bangalore",
      "state": "Karnataka",
      "country": "India",
      "pincode": "560001"
    },
    "nationality": "IND",
    "gender": "MALE",
    "marital_status": "SINGLE",
    "annual_income": "1200000",
    "occupation": "SERVICE",
    "organization": "GOVERNMENT",
    "education": "POST_GRADUATE",
    "employer": "ABC Corp",
    "documents": [
      {
        "document_type": "PAN",
        "document_number": "ABCDE1234F"
      },
      {
        "document_type": "AADHAR",
        "document_number": "123456789012"
      }
    ]
  },
  "insured_members": [
    {
      "title": "MR",
      "first_name": "John",
      "middle_name": "Pastor",
      "last_name": "Doe",
      "email": "johndoe@example.com",
      "mobile": "9876543210",
      "country_code": "+91",
      "date_of_birth": "05/06/1990",
      "address": {
        "address_line_1": "123 XYZ Street",
        "address_line_2": "ABC Layout",
        "address_line_3": "",
        "city": "Bangalore",
        "state": "Karnataka",
        "country": "India",
        "pincode": "560001"
      },
      "nationality": "IND",
      "gender": "MALE",
      "marital_status": "SINGLE",
      "annual_income": "1200000",
      "occupation": "SERVICE",
      "organization": "GOVERNMENT",
      "education": "POST_GRADUATE",
      "employer": "ABC Corp",
      "documents": [
        {
          "document_type": "PAN",
          "document_number": "ABCDE1234F"
        },
        {
          "document_type": "AADHAR",
          "document_number": "123456789012"
        }
      ]
    }
  ],
  "nominee": [
    {
      "title": "MRS",
      "first_name": "Jane",
      "middle_name": "Alice",
      "last_name": "Doe",
      "date_of_birth": "16/10/1992",
      "mobile": "9876543211",
      "country_code": "+91",
      "relationship": "SPOUSE",
      "address": {
        "address_line_1": "123 XYZ Street",
        "address_line_2": "ABC Layout",
        "address_line_3": "",
        "city": "Bangalore",
        "state": "Karnataka",
        "country": "India",
        "pincode": "560001"
      },
      "percentage_sharing": 100,
      "documents": [
        {
          "document_type": "PASSPORT",
          "document_number": "A1B2C3D4E5"
        }
      ],
      "appointee_details": {
        "relationship_to_nominee": "",
        "title": "",
        "first_name": "",
        "middle_name": "",
        "last_name": "",
        "date_of_birth": "",
        "mobile": "",
        "country_code": "+91",
        "address": {
          "address_line_1": "",
          "address_line_2": "",
          "address_line_3": "",
          "city": "",
          "state": "",
          "country": "India",
          "pincode": ""
        },
        "documents": []
      }
    }
  ],
  "context_data": []
}

Fields

Field	Type	Optional	Description
quote_id	string	No	Quote ID obtained from the Create Quote API
recommendation_id	string	No	Recommendation ID from the quote response
status	string	No	Must be set to "DRAFT/SUBMITTED" (see Proposal Status table below)
proposer	object	No	Information about the policy proposer (see Proposer Fields table below)
insured_members	array	No	Array of insured individuals (see Insured Member Fields table below)
nominee	array	Yes	Array of nominee information (see Nominee Details table below)
context_data	array	Yes	Array of context data key-value pairs (see Context Data Fields table below)

Proposer Fields

The proposer object contains information about the individual proposing the insurance:

Field	Type	Optional	Description
title	string	No	Title of the proposer (see Title Fields table below)
first_name	string	No	First name of the proposer
middle_name	string	Yes	Middle name of the proposer
last_name	string	No	Last name of the proposer
email	string	No	Email address of the proposer
mobile	string	No	Mobile number of the proposer (10 digits)
country_code	string	Yes	Country code for the mobile number (defaults to "+91")
date_of_birth	string	No	Date of birth in DD/MM/YYYY format
address	object	No	Address details (see Address Fields table below)
nationality	string	No	Nationality of the proposer (see Nationality Fields table below)
gender	string	No	Gender of the proposer (see Gender Fields table below)
marital_status	string	No	Marital status (see Marital Status Fields table below)
annual_income	string	No	Annual income in INR
occupation	string	No	Occupation of the proposer (see Occupation Fields table below)
organization	string	No	Organization type (see Organization Fields table below)
education	string	No	Education qualification (see Education Fields table below)
employer	string	Yes	Name of the employer
documents	array	No	Array of document information (see Document Fields below)

Proposal Status

The status field indicates the current state of the proposal:

Status	Description
DRAFT	Proposal is saved as a draft and can be modified
PENDING	Proposal is submitted for processing
COMPLETED	Proposal is approved and policy is issued
REJECTED	Proposal is rejected

Insured Member Fields

The insured_members array contains details about the individuals to be insured:

Field	Type	Optional	Description
title	string	No	Title of the insured (see Title Fields table below)
first_name	string	No	First name of the insured
middle_name	string	Yes	Middle name of the insured
last_name	string	No	Last name of the insured
email	string	No	Email address of the insured
mobile	string	No	Mobile number of the insured (10 digits)
country_code	string	Yes	Country code for the mobile number (defaults to "+91")
date_of_birth	string	No	Date of birth in DD/MM/YYYY format
address	object	No	Address details (see Address Fields table below)
nationality	string	No	Nationality of the insured (see Nationality Fields table below)
gender	string	No	Gender of the insured (see Gender Fields table below)
marital_status	string	No	Marital status (see Marital Status Fields table below)
annual_income	string	Yes	Annual income in INR
occupation	string	No	Occupation of the insured (see Occupation Fields table below)
organization	string	Yes	Organization type (see Organization Fields table below)
education	string	No	Education qualification (see Education Fields table below)
employer	string	Yes	Name of the employer
documents	array	No	Array of document information (see Document Fields below)

Address Fields

The address object structure used in multiple places:

Field	Type	Optional	Description
address_line_1	string	No	First line of address
address_line_2	string	No	Second line of address
address_line_3	string	Yes	Third line of address
city	string	No	City name
state	string	No	State name
country	string	Yes	Country name (defaults to "India")
pincode	string	No	6-digit postal code

Nominee Details

The nominee array contains information about the nominees:

Field	Type	Optional	Description
title	string	No	Title of the nominee (see Title Fields table below)
first_name	string	No	First name of the nominee
middle_name	string	Yes	Middle name of the nominee
last_name	string	No	Last name of the nominee
date_of_birth	string	No	Date of birth in DD/MM/YYYY format
mobile	string	Yes	Mobile number of the nominee (10 digits)
country_code	string	Yes	Country code for the mobile number (defaults to "+91")
relationship	string	No	Relationship with the primary insured (see Relationship Fields table below)
address	object	No	Address details (see Address Fields table above)
percentage_sharing	number	No	Percentage allocation for the nominee (total must be 100 across all nominees)
documents	array	No	Array of document information (see Document Fields below)
appointee_details	object	Yes	Appointee details (required if nominee is a minor, see Appointee Fields)

Appointee Fields

The appointee_details object is required if the nominee is a minor:

Field	Type	Optional	Description
relationship_to_nominee	string	No	Relationship with the nominee (see Relationship Fields table below)
title	string	No	Title of the appointee (see Title Fields table below)
first_name	string	No	First name of the appointee
middle_name	string	Yes	Middle name of the appointee
last_name	string	No	Last name of the appointee
date_of_birth	string	No	Date of birth in DD/MM/YYYY format
mobile	string	Yes	Mobile number of the appointee (10 digits)
country_code	string	Yes	Country code for the mobile number (defaults to "+91")
address	object	No	Address details (see Address Fields table above)
documents	array	No	Array of document information (see Document Fields below)

Enum Types

The following tables define the valid values for various enumerated fields:

Title Fields

Value	Description
MR	Male title
MRS	Married female title
MS	Unmarried female title

Gender Fields

Value	Description
MALE	Male gender
FEMALE	Female gender

Marital Status Fields

Value	Description
SINGLE	Never married
SEPARATED	Separated
MARRIED	Currently married
DIVORCED	Legally divorced
WIDOWED	Spouse deceased

Occupation Fields

Value	Description
LABOURER	Manual laborer
UNEMPLOYED	Not currently employed
HOUSEWIFE	Homemaker
RETIRED	No longer working due to retirement
OTHERS	Other occupation not listed. If selected, the specific occupation value should be provided in the context_data array with key "occupation_other"
FARMER	Works in agriculture
SALARIED	Employed with regular salary
SELF_EMPLOYED	Owns a business or is self-employed
SERVICE	Works in service industry
STUDENT	Currently studying

Organization Fields

Value	Description
GOVERNMENT	Government organization
OTHERS	Other organization types. If selected, the specific organization value should be provided in the context_data array with key "organization_other"
PUBLIC_LTD	Public limited company
PRIVATE_LTD	Private limited company

Education Fields

Value	Description
POST_GRADUATE	Post graduation degree completed
GRADUATE	Graduate degree or diploma holder
12TH_PASS	Completed 12th standard
10TH_PASS	Completed 10th standard
BELOW_10TH	Education below 10th standard
ILLITERATE	No formal education

Nationality Fields

Value	Description
FN	Foreign National
IND	Indian
NRI	Non-Resident Indian
OCI	Overseas Citizen of India
PIO	Person of Indian Origin

Document Type Fields

Value	Description
PAN	PAN Card
AADHAR	Aadhaar Card
DRIVING_LICENSE	Driving License
PASSPORT	Passport
ELECTRICITY	Electricity Bill
VOTER_ID	Voter ID Card

Relationship Fields

Value	Description
HUSBAND	Male spouse
SPOUSE	Partner in marriage
FATHER	Male parent
MOTHER	Female parent
SON	Male child
DAUGHTER	Female child
OTHERS	Other relationship
BROTHER	Male sibling
SISTER	Female sibling
WIFE	Female spouse
NEPHEW	Son of one's sibling
GRANDMOTHER	Mother of one's parent
UNCLE	Brother of one's parent
SISTER_IN_LAW	Sister of one's spouse
GRANDFATHER	Father of one's parent

Document Fields

The documents array contains identity document information:

Field	Type	Optional	Description
document_type	string	No	Type of identity document (see Document Type Fields below)
document_number	string	No	Document identification number

Context Data Fields

Field	Type	Description
key	string	Identifier for the context data parameter
values	string[]	Array of string values for the parameter

Response

Success Response (201 Created)

{
  "payload": {
    "proposal_id": "pro_18M6aOiODyyf37DM",
    "status": "PENDING"
  }
}

For draft proposals:

{
  "payload": {
    "proposal_id": "pro_18M6aOiODyyf37DM",
    "status": "DRAFT"
  }
}

Error Response

Validation Error (400 Bad Request)

{
  "type": "V4000",
  "title": "Validation Error",
  "detail": "Missing or invalid fields in the request",
  "instance": "/v1/embedded/proposal",
  "additional_info": [
    {
      "field": "insured_members[0].email",
      "message": "Invalid email format"
    }
  ]
}

Unexpected Error (500 Internal Server Error)

{
  "type": "E5000",
  "title": "An unexpected error occurred",
  "detail": "",
  "instance": "/v1/embedded/proposal"
}

Response Fields

Success Response

Field	Type	Description
proposal_id	string	Unique identifier for the proposal (format: pro_*)
status	string	Current status of the proposal (DRAFT/PENDING/COMPLETED/REJECTED)

Error Response

Field	Type	Description
type	string	Error code (V4000: Validation, E5000: System)
title	string	Brief error description
detail	string	Detailed error message
instance	string	API endpoint where error occurred
additional_info	array	List of field-specific validation errors (for validation errors only)

Get Proposal Status

Retrieve the current status of an insurance proposal.

Endpoint

GET /v1/embedded/proposal/{proposal_id}/status

Path Parameters

Parameter	Type	Description
proposal_id	string	Unique identifier for the proposal (format: pro_*)

Response

Success Response (200 OK)

{
  "payload": {
    "proposal_id": "pro_18M6aOiODyyf37DM",
    "status": "COMPLETED",
    "policy_url": "https://your-bucket-name.s3.amazonaws.com/policies/POL123456789.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=..."
  }
}

For draft proposals:

{
  "payload": {
    "proposal_id": "pro_18M6aOiODyyf37DM",
    "status": "DRAFT"
  }
}

Error Response

Not Found Error (404 Not Found)

{
  "type": "R4040",
  "title": "Resource Not Found",
  "detail": "Proposal with ID pro_18M6aOiODyyf37DM not found",
  "instance": "/v1/embedded/proposal/pro_18M6aOiODyyf37DM/status"
}

Unexpected Error (500 Internal Server Error)

{
  "type": "E5000",
  "title": "An unexpected error occurred",
  "detail": "",
  "instance": "/v1/embedded/proposal/{proposal_id}/status"
}

Response Fields

Success Response

Field	Type	Description
proposal_id	string	Unique identifier for the proposal (format: pro_*)
status	string	Current status of the proposal (DRAFT/PENDING/COMPLETED/REJECTED)
policy_url	string	Short-lived S3 URL to download the policy document (valid for 10 minutes, available when status is COMPLETED)

Error Response

Field	Type	Description
type	string	Error code (R4040: Not Found, E5000: System Error)
title	string	Brief error description
detail	string	Detailed error message (if available)
instance	string	API endpoint where error occurred

Update Proposal

Update an existing proposal's status. This endpoint only accepts the status field in the request body.

Endpoint

PATCH /v1/embedded/proposal/{proposal_id}

Path Parameters

Parameter	Type	Description
proposal_id	string	Unique identifier for the proposal (format: pro_*)

Request

Body

{
  "status": "DRAFT"
}

Fields

Field	Type	Optional	Description
status	string	No	New status for the proposal (see Proposal Status table)

Response

Success Response (200 OK)

{
  "payload": {
    "proposal_id": "pro_18M6aOiODyyf37DM",
    "status": "PENDING"
  }
}

Error Response

Not Found Error (404 Not Found)

{
  "type": "R4040",
  "title": "Resource Not Found",
  "detail": "Proposal with ID pro_18M6aOiODyyf37DM not found",
  "instance": "/v1/embedded/proposal/pro_18M6aOiODyyf37DM"
}

Invalid State Error (400 Bad Request)

{
  "type": "S4000",
  "title": "Invalid State",
  "detail": "Invalid status transition",
  "instance": "/v1/embedded/proposal/pro_18M6aOiODyyf37DM"
}

Unexpected Error (500 Internal Server Error)

{
  "type": "E5000",
  "title": "An unexpected error occurred",
  "detail": "",
  "instance": "/v1/embedded/proposal/{proposal_id}"
}