Retrieve policy

Returns a policy's detail: identity and correlation keys, status, the insurer's policy number, the product classification, the premium decomposition (gross, IOF and net), the term, the effective coverages and the event trail.

Request

ENDPOINT

/v1/insurance/policies/{policy_key}

METHOD

GET

Path params

Parameter	Type	Required	Description
policy_key	string	required	Policy key, obtained from the listing by order or from the policy webhooks.

Response

STATUS

200

Response Body

{
  "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
  "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "provider_product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
  "provider_key": "c4a2e8b0-1f6d-4e3a-9c7b-5d0a2e8f4b61",
  "status": "issued",
  "external_policy_number": "APL-2026-000123",
  "customer_document_number": "96969879003",
  "product_category": "insurance",
  "insurance_class": {
    "name": "credit_life",
    "class_number": "0977",
    "group_number": "09"
  },
  "regulator_registration": "15414.900388/2015-21",
  "gross_premium_amount": 617.28,
  "iof_amount": 2.35,
  "net_premium_amount": 614.93,
  "term": {
    "start_date": "2026-07-16",
    "end_date": "2027-07-15"
  },
  "effective_services": [
    {
      "effective_service_key": "7f3a9c2e-0b5d-4e8a-a1c6-9d4b2e7f0a53",
      "provider_service_key": "0a3c5e7f-2b4d-4a6c-8e0f-1a3b5c7d9e2f",
      "service_type": {
        "code": "credit_life",
        "name": "Prestamista (Credit Life)"
      },
      "service_category": "insurance",
      "regulator_registration": null,
      "insured_amount": 150000.00,
      "gross_premium_amount": 617.28,
      "deductible_data": {
        "deductible_type": "monetary_amount",
        "value": 1500.00
      },
      "waiting_period_days": 30,
      "service_attributes": {},
      "term": {
        "start_date": "2026-07-16",
        "end_date": "2027-07-15"
      }
    }
  ],
  "events": [
    {
      "new_status": "issuance_requested",
      "agent_type": "system",
      "created_at": "2026-07-16T14:03:25.481Z"
    },
    {
      "new_status": "issued",
      "agent_type": "provider",
      "created_at": "2026-07-16T15:00:00.000Z"
    }
  ]
}

Response attributes

Field	Type	Description
policy_key	string	Unique policy key.
order_key	string	Key of the order that originated the policy.
provider_product_key	string	Catalog key of the product.
provider_key	string	Key of the issuing insurer.
status	string	Current status. See the lifecycle.
external_policy_number	string	Policy number at the insurer. null until issuance is confirmed (issued).
customer_document_number	string	Insured person's document.
product_category	string	Product category: insurance, capitalization or benefit.
insurance_class	object	Insurance class: { name, class_number, group_number }. null for non-insurance products. class_number and group_number are strings — leading zeros are significant.
regulator_registration	string	Product registration at the regulator (e.g. SUSEP process).
gross_premium_amount	number	Gross premium (the amount paid by the insured person), IOF-inclusive.
iof_amount	number	IOF component of the premium.
net_premium_amount	number	Net premium (gross minus IOF).
term	object	Policy term: { start_date, end_date }.
effective_services	array	Effective coverages of the policy.
events	array	Trail of status transitions, in chronological order — the lifecycle instants (issuance, cancellation request, cancellation) derive from it.

Object in effective_services

Field	Type	Description
effective_service_key	string	Unique key of the effective coverage.
provider_service_key	string	Catalog key of the coverage.
service_type	object	Coverage type: { code, name }.
service_category	string	Coverage category: insurance, capitalization or benefit.
regulator_registration	string	Coverage's own registration at the regulator. null when it inherits the product's.
insured_amount	number	Contracted insured amount.
gross_premium_amount	number	Gross premium of the coverage.
deductible_data	object	Contracted deductible: { deductible_type, value }.
waiting_period_days	integer	Waiting period in days.
service_attributes	object	Fixed coverage attributes.
term	object	Coverage term: { start_date, end_date }.

Object in events

Field	Type	Description
new_status	string	The status assumed in the transition.
agent_type	string	Who caused the transition: requester (your integration), provider (insurer), system (automatic) or operator (QI Tech operations).
created_at	string	Instant of the transition.

Possible errors

Every error (non-2xx) returns the standard body { "title", "description", "translation", "code" } — programmatically handle only the code field.

Status	Code	Description
401 / 403	—	Authentication or authorization failure.
404	POL000001	Policy nonexistent or belonging to another integration — the cases are indistinguishable.
429	—	Request limit exceeded — retry with backoff.
500	QIT000500	Internal error — safe to retry the call.
503	POL000030	Service unavailable — safe to retry the call.