Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.0.1
info:
title: Acko for Enterprise API Documentation
servers:
- url: http://demand-internet.internal.live.acko.com
description: Generated server url
tags:
- name: Overview
description: 'The Acko Embedded Insurance API suite provides a comprehensive set of endpoints that enable partners to seamlessly
integrate insurance solutions into their platforms. This documentation covers authentication methods, base URLs, and standardized
request/response formats. Our API documentation is organized into three main categories: Issuance for policy creation,
Endorsements for policy modifications, and Claims for managing the claims process. Each section is further tailored to
specific business verticals including Credit, Travel, Gig, Health, and Home insurance products. The APIs are further sub-divided
into two versions V1 and V2. While we support both versions, we encourage you to go ahead with integrating with our V2
APIs'
- name: Authentication
description: Authentication is managed through OAuth 2.0, ensuring secure access to our APIs. Partners must obtain an access
token by providing their client credentials. The token must be included in the Authorization header of each request. This
section details the authentication flow, token management, and error handling for unauthorized requests.
- name: Policy Retrieval
description: The Policy Retrieval API provides access to policy details by policy id and policy number. It returns comprehensive
policy information including coverage limits, premium schedules, and endorsement history. The endpoint supports pagination
for handling multiple policies and allows filtering by status or date range.
- name: Policy Issuance
description: The Policy Issuance APIs enable real-time policy generation and premium calculation. These endpoints allow
partners to instantly issue live policies to their customers at the point of service. This section details the mandatory
request headers, idempotency keys for preventing duplicate transactions, payment status callbacks, and performance benchmarks
for both synchronous and asynchronous integration modes. Follow our implementation guidelines to ensure smooth policy
issuance with minimal latency.
- name: Policy Endorsement
description: Our Policy Endorsement APIs provide the ability to modify active policies throughout their lifecycle. Whether
you need to cancel a policy, process early closures, add dependents, or update customer information, these endpoints handle
all post-issuance policy changes. This section explains versioning protocols, effective-date rules, and premium pro-rating
calculations to ensure accurate financial adjustments when policies are modified
- name: Claims Management
description: The Claims Management APIs streamline the end-to-end claims management process for your customers. This section
guides partners through creating First Notice of Loss (FNOL), uploading supporting documentation, and monitoring claim
status through automated webhooks. Our claims infrastructure is designed to provide real-time status updates while maintaining
compliance with regulatory requirements and optimizing the customer experience during the claims journey.
- name: Policy Proposal
description: The Policy Proposal APIs manage the proposal lifecycle for policies that require pre-approval before issuance.
This section includes endpoints for creating proposals, batch processing multiple proposals, and updating proposal statuses.
- name: Loan-Shield
description: The Credit Insurance APIs offer protection solutions specifically designed for lending products. These endpoints
support loan-life coverage, EMI protection, and income-loss insurance. Integration requires basic loan parameters including
loan ID, outstanding amount, tenor, and borrower KYC details. The API supports various loan types—personal, gold, and
housing loans—through product-specific configuration flags. Upon successful validation, the system instantly binds coverage
and returns a digitally signed e-policy PDF.
- name: Trip
description: The Trip Insurance APIs are designed for on-demand travel coverage. These endpoints allow partners to issue
policies for single trips, multi-city itineraries, or annual travel plans. Integration requires trip details such as departure/arrival
dates, destination countries, and traveler demographics. The API supports real-time premium calculations based on trip
duration and coverage limits, with policy documents generated instantly upon successful payment.
- name: GIG
description: The Gig Worker Insurance APIs enable on-demand coverage for task-based or shift-based workforce. These endpoints
accept job identifiers, task duration parameters, and worker profiles to provide tailored protection. Pricing is calculated
per minute of service or per delivery, with policies that automatically expire at task completion. The API includes webhooks
for task start/stop events to ensure precise coverage periods for gig economy platforms.
- name: Health
description: Our Health Insurance APIs facilitate Group Mediclaim (GMC) implementation with streamlined onboarding processes.
Features include census data upload, configurable sum-insured grids, and optional riders for OPD and mental wellness benefits.
The API returns group policy documentation and individual member e-cards. A specialized bulk-endorsement endpoint handles
monthly employee additions and exits to maintain accurate coverage records.
- name: House
description: The Home Insurance APIs provide protection for both structure and contents. Integration requires property details
including geo-coordinates, built-up area, construction type, and coverage start date. The premium calculation includes
options for burglary and gadget protection add-ons. Policy documentation includes a comprehensive valuation schedule for
insured items and property.
- name: Credit Life
description: The Credit Life Issuance API enables policy generation during loan disbursal by capturing customer, loan, insured,
and nominee details. The endpoint validates mandatory declarations and premium data, issues the policy in real time, and
returns the policy number along with certificate URLs and premium breakup for reconciliation.
- name: Credit Life Proposal
description: The Credit Life Proposal API enables the creation and management of credit life insurance proposals for loans
that require underwriting approval. The endpoint handles proposal submission, bulk processing capabilities, and status
updates throughout the approval workflow. Upon proposal acceptance, the policy can be issued using the standard issuance
API with the approved proposal reference.
- name: Credit Life Templates
description: 'The Credit Life Templates section provides downloadable Excel templates for bulk proposal operations. Partners
can download standardized templates for proposal issuance and updates, share them with business teams, and upload completed
sheets for batch processing. This streamlines the proposal workflow by enabling efficient bulk data handling through familiar
spreadsheet interfaces.
**Available Templates:**
📄 **Proposal Issuance Template**: [Access Google Sheets Template](https://docs.google.com/spreadsheets/d/1j9cSJPQ8nJ8k0cIbB4ZesQuTMMetNvZTAWUHlI0k5bM/edit?usp=sharing)
- Use this template for bulk proposal issuance data entry - Contains all required fields for creating new Credit Life
proposals - Can be shared with business teams for data collection
📄 **Proposal Update Template**: [Access Google Sheets Template](https://docs.google.com/spreadsheets/d/1j9cSJPQ8nJ8k0cIbB4ZesQuTMMetNvZTAWUHlI0k5bM/edit?gid=572464409#gid=572464409)
- Use this template for updating existing proposal statuses - Contains fields required for proposal status modifications
- Supports bulk update operations for multiple proposals
**Instructions:** 1. Click on the template links above to access the Google Sheets 2. Make a copy of the template for
your use 3. Fill in the required data according to your proposal needs 4. Share the completed template with the appropriate
business teams for processing'
- name: Fire
description: The Fire Issuance API enables the creation and issuance of fire insurance policies by accepting detailed order
information, insured property details, selected coverage plans, user and nominee data, and premium breakdowns. The response
provides confirmation of policy issuance along with status updates and transaction metadata, supporting efficient policy
processing and management. This API encompasses the Loan Against Property (LAP) use case.
- name: Cyber Protection
description: The Cyber Protection Issuance API provides coverage for digital assets and online transactions. It requires
user details, device information, and transaction parameters to calculate premiums based on risk profiles. The API supports
real-time policy issuance with digital documentation and secure storage of policy certificates.
- name: Electronics
description: The Electronic Device Issuance API allows partners to issue policies for electronic devices such as smartphones,
laptops, and tablets. It requires device specifications, user details, and coverage options to calculate premiums. The
API supports instant policy issuance with digital certificates and provides endpoints for managing device claims.
- name: Financial
description: The Financial Endorsement API handles all policy modifications that affect premium calculations. Use these
endpoints when implementing sum-insured adjustments, adding coverage options, or extending policy tenure. The API calculates
revised premiums, generates appropriate debit/credit notes, and maintains payment reference integrity. All transactions
return updated policy versions with complete audit trails.
- name: Non-Financial
description: Our Non-Financial Endorsement API processes data-only changes such as contact information or address updates
that don't impact premium amounts. These modifications are processed instantly and don't require payment adjustments.
The API supports JSON Patch format for atomic updates and maintains comprehensive audit logging for all changes.
- name: Create Claims
description: The Claim Creation API enables First Notice of Loss (FNOL) submission to initiate the claims process. The endpoint
requires policy identifier, incident details, claimant information, and supporting documentation. Upon validation, the
system generates a unique claim identifier and provides secure upload URLs for additional documentation submission
- name: Get Claims
description: The Claim Retrieval API provides comprehensive access to claim information by claim or policy identifier. Response
data includes detailed status history, payout information, assessor notes, and pending actions. The endpoint supports
pagination for handling multiple claims and state-based filtering to facilitate efficient claim status tracking
paths:
/product/{partner}/proposal-policies:
put:
tags:
- Credit Life Proposal
summary: Update Credit Life Proposal Status
operationId: updateCreditLifeProposal
parameters:
- name: Authorization
in: header
description: "username={partner} algorithm={algo} created_on={time} secret={secret} \n This will be shared over mail\
\ when the product is onboarded"
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateProposalStatusRequest'
required: true
responses:
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: Bad configuration error
code: PERR_001
error:
reference_id: <reference_id>
status_code: 500
message: Plan agreement does not exist
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: Client Input Validation Failed
code: IVERR_001
error:
reference_id: <reference_id>
status_code: 400
message: plan is a required field
'409':
description: Conflict
content:
'*/*':
schema:
type: string
'429':
description: Too Many Requests
content:
'*/*':
schema:
type: object
'503':
description: Service Unavailable
content:
'*/*':
schema:
type: string
'403':
description: Forbidden
content:
'*/*':
schema:
type: string
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: AUTHENTICATION_FAILED
code: UNAUERR_001
error:
status_code: 401
message: Not Authorized!!
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateProposalStatusResponse'
post:
tags:
- Credit Life Proposal
summary: Credit Life Proposal Policy
operationId: creditLifeProposal
parameters:
- name: partner
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: "username={partner} algorithm={algo} created_on={time} secret={secret} \n This will be shared over mail\
\ when the product is onboarded"
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreditLifePolicyRequestDTO'
required: true
responses:
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: Bad configuration error
code: PERR_001
error:
reference_id: <reference_id>
status_code: 500
message: Plan agreement does not exist
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: Client Input Validation Failed
code: IVERR_001
error:
reference_id: <reference_id>
status_code: 400
message: plan is a required field
'409':
description: Conflict
content:
'*/*':
schema:
type: string
'429':
description: Too Many Requests
content:
'*/*':
schema:
type: object
'503':
description: Service Unavailable
content:
'*/*':
schema:
type: string
'403':
description: Forbidden
content:
'*/*':
schema:
type: string
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: AUTHENTICATION_FAILED
code: UNAUERR_001
error:
status_code: 401
message: Not Authorized!!
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CreditLifePolicyResponseDTO'
/product/{partner}/batch/proposal-policies:
put:
tags:
- Credit Life Proposal
summary: Bulk Update Credit Life Proposal Status
operationId: bulkUpdateCreditLifeProposal
parameters:
- name: Authorization
in: header
description: "username={partner} algorithm={algo} created_on={time} secret={secret} \n This will be shared over mail\
\ when the product is onboarded"
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UpdateProposalStatusRequest'
required: true
responses:
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: Bad configuration error
code: PERR_001
error:
reference_id: <reference_id>
status_code: 500
message: Plan agreement does not exist
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: Client Input Validation Failed
code: IVERR_001
error:
reference_id: <reference_id>
status_code: 400
message: plan is a required field
'409':
description: Conflict
content:
'*/*':
schema:
type: string
'429':
description: Too Many Requests
content:
'*/*':
schema:
type: object
'503':
description: Service Unavailable
content:
'*/*':
schema:
type: string
'403':
description: Forbidden
content:
'*/*':
schema:
type: string
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: AUTHENTICATION_FAILED
code: UNAUERR_001
error:
status_code: 401
message: Not Authorized!!
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateProposalStatusResponse'
post:
tags:
- Credit Life Proposal
summary: Credit Life Bulk Proposal Policy
operationId: creditLifeBulkProposal
parameters:
- name: partner
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: "username={partner} algorithm={algo} created_on={time} secret={secret} \n This will be shared over mail\
\ when the product is onboarded"
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/CreditLifePolicyRequestDTO'
required: true
responses:
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: Bad configuration error
code: PERR_001
error:
reference_id: <reference_id>
status_code: 500
message: Plan agreement does not exist
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: Client Input Validation Failed
code: IVERR_001
error:
reference_id: <reference_id>
status_code: 400
message: plan is a required field
'409':
description: Conflict
content:
'*/*':
schema:
type: string
'429':
description: Too Many Requests
content:
'*/*':
schema:
type: object
'503':
description: Service Unavailable
content:
'*/*':
schema:
type: string
'403':
description: Forbidden
content:
'*/*':
schema:
type: string
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: AUTHENTICATION_FAILED
code: UNAUERR_001
error:
status_code: 401
message: Not Authorized!!
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CreditLifePolicyResponseDTO'
/realms/partnership/protocol/openid-connect/token:
post:
tags:
- Authentication
summary: Token Generation
operationId: tokenGeneration
parameters:
- name: grant_type
in: query
description: Type of grant being requested
required: true
schema:
type: string
- name: client_id
in: query
description: The unique identifier for the partner
required: true
schema:
type: string
- name: client_secret
in: query
description: The secret key associated with the partner’s client_id
required: true
schema:
type: string
example: s3cr3t
- name: Authorization
in: header
description: "username={partner} algorithm={algo} created_on={time} secret={secret} \n This will be shared over mail\
\ when the product is onboarded"
required: true
schema:
type: string
responses:
'401':
description: Unauthorized – invalid client credentials
content:
application/json:
schema:
$ref: '#/components/schemas/InvalidClientCredentials'
examples:
InvalidClientCredentials:
description: InvalidClientCredentials
value:
error: unauthorized_client
error_description: Invalid client or Invalid client credentials
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/CentralAuthResponse'
'/product/{partners}/policies/{policyId}/endorsements ':
post:
tags:
- Financial
summary: Cancellation V1
description: The Policy Cancellation API enables mid-term termination of active policies. The endpoint requires cancellation
reason codes and effective dates to process the request. Upon validation, the system calculates refundable premium
amounts based on the unused policy period and triggers the appropriate refund webhook. The response includes updated
policy status and credit note reference details
operationId: endorsePolicyCancellationV1
parameters:
- name: Authorization
in: header
description: Bearer <accessToken> Generate one via [Token Generation](#operation/tokenGeneration).
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LifeEndorsementRequestDTO'
required: true
responses:
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: Bad configuration error
code: PERR_001
error:
reference_id: <reference_id>
status_code: 500
message: Plan agreement does not exist
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: Client Input Validation Failed
code: IVERR_001
error:
reference_id: <reference_id>
status_code: 400
message: plan is a required field
'409':
description: Conflict
content:
'*/*':
schema:
type: string
'429':
description: Too Many Requests
content:
'*/*':
schema:
type: object
'503':
description: Service Unavailable
content:
'*/*':
schema:
type: string
'403':
description: Forbidden
content:
'*/*':
schema:
type: string
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: AUTHENTICATION_FAILED
code: UNAUERR_001
error:
status_code: 401
message: Not Authorized!!
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/EndorsementResponse'
'/product/{partners}/policies/{policyId}/endorsements ':
post:
tags:
- Financial
summary: Preclosure
description: The Policy Preclosure API is specifically designed for credit-life policies when the underlying loan closes
early. This endpoint accepts loan identifier and closure date parameters, calculates unearned premium refunds, and
generates pre-closure certification documentation. The streamlined process ensures proper policy termination aligned
with loan closure events
operationId: endorsePolicyPreClosure
parameters:
- name: Authorization
in: header
description: Bearer <accessToken> Generate one via [Token Generation](#operation/tokenGeneration).
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LifeEndorsementRequestDTO'
required: true
responses:
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: Bad configuration error
code: PERR_001
error:
reference_id: <reference_id>
status_code: 500
message: Plan agreement does not exist
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: Client Input Validation Failed
code: IVERR_001
error:
reference_id: <reference_id>
status_code: 400
message: plan is a required field
'409':
description: Conflict
content:
'*/*':
schema:
type: string
'429':
description: Too Many Requests
content:
'*/*':
schema:
type: object
'503':
description: Service Unavailable
content:
'*/*':
schema:
type: string
'403':
description: Forbidden
content:
'*/*':
schema:
type: string
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: AUTHENTICATION_FAILED
code: UNAUERR_001
error:
status_code: 401
message: Not Authorized!!
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/EndorsementResponse'
'/product/{partners}/policies/{policyId}/endorsements ':
post:
tags:
- Non-Financial
summary: Dependent Updation V1
description: The Dependent Update API is optimized for Group Mediclaim policies, allowing the addition or removal of
dependents during the policy term. The endpoint handles waiting-period calculations and processes any required premium
adjustments. Upon successful update, the system generates refreshed e-cards reflecting the updated coverage details
operationId: endorsePolicyRequestDependentUpdationV1
parameters:
- name: Authorization
in: header
description: Bearer <accessToken> Generate one via [Token Generation](#operation/tokenGeneration).
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EndorsementDependentUpdationDTO'
required: true
responses:
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: Bad configuration error
code: PERR_001
error:
reference_id: <reference_id>
status_code: 500
message: Plan agreement does not exist
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/SwaggerErrorResponse'
example:
category: Client Input Validation Failed
code: IVERR_001
error:
reference_id: <reference_id>
status_code: 400
message: plan is a required field
'409':
description: Conflict
content:
'*/*':
schema:
type: string
'429':
description: Too Many Requests
content:
'*/*':
schema:
type: object
'503':
description: Service Unavailable
content:
'*/*':
schema:
type: string
'403':
description: Forbidden
content:
'*/*':
schema:
type: string
# --- truncated at 32 KB (447 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ackogeneralinsurance/refs/heads/main/openapi/ackogeneralinsurance-enterprise-openapi.yml