Add a coverage

post

https://api.kalepa.com/external/reports/{report_id}/policies/{policy_id}/coverages

Add a coverage to a policy. coverage_name, coverage_type and coverage_status are required, and coverage_name must be one enabled for your organization.

Limits, deductibles and premiums may be nested in the request body and are created with the coverage. If any of them cannot be created the coverage is removed again, so a failed request leaves nothing behind.

For an excess layer, send coverage_type: EXCESS with the attachment_point it sits above — Kalepa chains the layers from those attachment points, so the underlying policies are never specified directly.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

report_id

string

required

length ≥ 1

Identifies the report: either its Kalepa report ID (the id returned when the report is created) or the external_id you set on the report (on create, or later via PATCH). The value is auto-detected by shape — a UUID-shaped value (for example a dashed UUID or 32 hexadecimal characters; brace-wrapped and urn:uuid: forms count too) is treated as the Kalepa report ID, anything else as your external_id. Use the id_type query parameter to force the interpretation, and org_group / sub_org_group to narrow an external_id that is reused across groups. Deleted reports are never matched. When the same external_id is on several reports, archived reports are ignored if at least one non-archived report matches; if more than one report still matches, the request fails with 400 and error code AMBIGUOUS_IDENTIFIER (in the response body at detail.code). An external_id lookup searches only the reports available to your API client; anything else answers 404. URL-encode reserved characters (e.g. a space as %20). Two values cannot be used in this path segment: an external_id containing a forward slash (/), and the exact value extract when calling GET /external/reports/{report_id} (that path is a different endpoint). For those, look up the Kalepa report ID with GET /external/report_id and use that instead.

policy_id

uuid

required

The id of a policy, as returned by the policy tower endpoint.

Query Params

id_type

string

enum

Overrides how the report_id path value is interpreted: uuid (the Kalepa report ID) or external_id (your own identifier). Omit for auto-detect (a UUID-shaped value is treated as uuid, otherwise as external_id). Set external_id when your identifier is itself UUID-shaped (for example a dashed UUID or 32 hexadecimal characters) and would otherwise be read as a Kalepa report ID. With id_type=uuid, a path value that is not a valid UUID returns 400; any id_type value other than uuid or external_id also returns 400.

Allowed:

org_group

string

Used only when the report is targeted by external_id: exact match on the report's org_group. Pass an empty value (?org_group=) to match reports that have no org_group. Omit the parameter to skip the filter.

sub_org_group

string

Used only when the report is targeted by external_id: exact match on the report's sub_org_group. Pass an empty value (?sub_org_group=) to match reports that have no sub_org_group. Omit the parameter to skip the filter.

Body Params

One coverage on a policy — a line of business and the terms quoted for it. Primary and excess layers of the same line are separate coverages, distinguished by attachment_point.

coverage_name

string | null

The coverage, by name, as enabled for your organization — for example generalLiability or excess. Required when creating a coverage and optional when updating one. A name that is not enabled for your organization is rejected with 422. Returns null for a coverage whose definition has since been withdrawn.

coverage_type

string | null

For example: PRIMARY, EXCESS. Further values may be added over time.

coverage_status

string | null

For example: Requested, Quoted, Bound, Declined, Lost, Expiring. Further values may be added over time.

attachment_point

number | null

For an excess layer, the amount it sits above. This is what distinguishes the layers of a tower from one another, and what Kalepa uses to chain them, so it is required on the second and subsequent layers of the same coverage.

is_lead

boolean | null

Whether this coverage is the lead on a shared or layered placement.

first_dollar_defense

boolean | null

coverage_claim_type

string | null

For example: Claims-Made, Occurrence-Based, Hybrid. Further values may be added over time.

valuation

string | null

For example: Replacement Cost, Actual Cash Value, Agreed Value. Further values may be added over time, and some are specific to the line of business.

defense

string | null

Whether defence costs sit inside or outside the limit. For example: Inside, Outside. Further values may be added over time.

is_foreign

boolean | null

Whether this coverage applies outside the policy's home country.

coverage_country

string | null

ISO 3166-1 alpha-2 country code for a coverage placed in a specific country.

retroactive_date_requested

date | null

retroactive_date_current

date | null

currency

string | null

ISO 4217 code. Omit to leave the stored currency untouched.

limits

array of objects | null

Accepted when creating a coverage and returned on reads. Not accepted when updating a coverage — use the limit endpoints.

limits

deductibles

array of objects | null

Accepted when creating a coverage and returned on reads. Not accepted when updating a coverage — use the deductible endpoints.

deductibles

premiums

array of objects | null

Accepted when creating a coverage and returned on reads. Not accepted when updating a coverage — use the premium endpoints.

premiums

Responses

400

The request is invalid, for example id_type=uuid with a path value that is not a valid UUID, or an id_type other than uuid / external_id.

401

The bearer token is missing or invalid.

403

The report is within your organization and a visible org group, and you are still not permitted to act on it. A report outside your organization or org group answers 404 instead.

404

The report was not found, it belongs to an organization or org group you cannot see, or the addressed policy, coverage, limit, deductible or premium is not part of it. These are reported identically on purpose, so a response cannot be used to discover that a report or a resource exists somewhere you have no access to.

422

The request could not be applied, and nothing was created. Either a field the resource cannot be created without was omitted, or the coverage_name is not one enabled for your organization, or that coverage does not allow the coverage_type requested. The response names the field or the coverage.

Every field in these schemas is nullable, so that fields can be added over time without breaking your generated client — which means the schema itself cannot mark anything required. Each endpoint's description states what it needs in order to create.

Also returned when report_id, read as your external_id, matches more than one report (error code AMBIGUOUS_IDENTIFIER, in the response body at detail.code). Narrow with org_group / sub_org_group, or target the report by its Kalepa report ID.

500

An unexpected error occurred.

201The coverage was created.