Create Endorsement

Create an endorsement to add or remove an employee from a policy. Endorsements are processed asynchronously — the response returns identifiers you can use to track the workflow.

Asynchronous workflow

Endorsements go through an approval lifecycle: PENDING → SENT_TO_INSURER → APPROVED (or REJECTED).

Endpoint

POST /v1/policy/endorsements

Request

Headers

Header	Value
Content-Type	application/json
Authorization	Bearer YOUR_ACCESS_TOKEN

Body

{
  "employee_id": "ba_emp_01jwz3k...",
  "policy_id": "ba_pol_01k...",
  "type": "ADDITION | DELETION",
  "coverage_start_date": "2024-07-01",
  "coverage_end_date": "2024-07-31",
  "sum_insured": 300000
}

Top-level Fields

Field	Type	Required	Description
employee_id	string	Yes	BizzAssure internal employee ID (from Create Employee)
policy_id	string	No	BizzAssure internal policy ID. Omit to use routing logic to assign a policy
type	string	Yes	ADDITION to enrol an employee, DELETION to remove
coverage_start_date	string	Yes	Coverage start date (YYYY-MM-DD)
coverage_end_date	string	Yes	Coverage end date (YYYY-MM-DD)
sum_insured	number	No	Sum insured for this employee (INR). If omitted, the policy default will be used. Only applies to ADDITION

---

Response

Success (200 OK)

{
  "payload": {
    "endorsement_id": "ba_end_01k...",
    "message": "Endorsement workflow started successfully",
    "success": true
  }
}

Response Fields

Field	Type	Description
endorsement_id	string	ID of the endorsement record created to track the status of the endorsement
message	string	Human-readable result message
success	boolean	true if the workflow was started successfully

Endorsement Lifecycle

Once submitted, the endorsement moves through the following statuses:

Status	Description
ENDORSEMENT_STATUS_PENDING	Workflow started, awaiting review
ENDORSEMENT_STATUS_SENT_TO_INSURER	Submitted to the insurer for processing
ENDORSEMENT_STATUS_APPROVED	Approved by the insurer
ENDORSEMENT_STATUS_REJECTED	Rejected by the insurer
ENDORSEMENT_STATUS_CANCELLED	Cancelled

---

Error Responses

Missing Details (400 Bad Request)

{
  "type": "MISSING_ADDITION_DETAILS",
  "title": "Missing addition details",
  "detail": "Addition details are required for addition endorsements",
  "instance": "/v1/policy/ba_pol_01k/endorsements"
}

Invalid Type (400 Bad Request)

{
  "type": "INVALID_ENDORSEMENT_TYPE",
  "title": "Invalid endorsement type",
  "detail": "Endorsement type must be ADDITION, DELETION, or MODIFICATION",
  "instance": "/v1/policy/ba_pol_01k/endorsements"
}

Policy Not Found (404)

{
  "type": "NOT_FOUND",
  "title": "Policy Not Found",
  "detail": "No active policy found with the given ID",
  "instance": "/v1/policy/ba_pol_01k/endorsements"
}

Unauthorized (401)

{
  "type": "UNAUTHORIZED",
  "title": "Unauthorized",
  "detail": "Missing or invalid access token",
  "instance": "/v1/policy/ba_pol_01k/endorsements"
}