Technical documentation

Date of update: 11/18/2025

General description

The API is designed to exchange documents in order for the Insurance Company to approve the services provided by the Clinic and, in case of a positive decision, to send a letter of guarantee or the number of the approval sheet for the requested list of services.  

Integration is implemented according to the REST API. Authorization is implemented according to the OAuth 2.0 specification.

API methods by role: 

API methods (full list):

I. Authorization

Getting an authorization token
POST /insurance_approval/auth/token/
Updating the authorization token
POST /insurance_approval/auth/refresh_token/

II. Reference books

Getting a list of available insurance companies (available only to the Clinic)
GET /insurance_approval/catalog/insurance_companies/
Getting a list of available clinics
GET /insurance_approval/catalog/clinics/

III. Orders

Creating an order
POST /insurance_approval/orders/
Getting an order
GET /insurance_approval/orders/{uuid}/
Getting a list of orders
GET /insurance_approval/orders/
Order Update
PATCH /insurance_approval/orders/{uuid}/

IV. Services for approval

Uploading a list of services
POST /insurance_approval/orders/{uuid}/attachments/bulk_create/
Editing the list of services (only the UK is available)
PATCH /insurance_approval/orders/{uuid}/services/bulk_update/

V. Reception protocols

Adding a list of appointment protocols (available only to the Clinic)
POST /insurance_approval/orders/{uuid}/protocols/bulk_create/

VI. Clinic branches

Adding a list of clinic branches for which a letter of guarantee is issued (only IC is available)
POST /insurance_approval/orders/{uuid}/filials_for_letter_of_guarantee/bulk_create/

VII. Letters of guarantee

Uploading a letter of guarantee (only the UK is available)
POST /insurance_approval/orders/{uuid}/letter_of_guarantee_pdf/
Receiving a letter of guarantee
GET /insurance_approval/orders/{uuid}/letter_of_guarantee_pdf/

VII. Attachment files

Uploading a list of files (available only to the Clinic)
POST /insurance_approval/orders/{uuid}/attachments/bulk_create/
Getting the file
GET /insurance_approval/orders/{uuid}/attachments/{attachment_id}/

The status model

Order statuses:

«1» - Creating an order
«2» - Awaiting approval
«3» - Request for additional information
«4» - Additional information provided
«5» - Partially or completely agreed, there is no GP
«6» - Agreed in part or in full, the GP is transmitted in the attachment
«7» - Partially or fully agreed, awaiting GP (to be implemented in the next iterations)
«8» - Partially or completely agreed, the GP is formed, sent to the UK (to be implemented in the next iterations)
«9» - Partially or fully agreed, GP received, awaiting signature from the UK (to be implemented in the next iterations)
«10» - Partially or fully agreed, GP signed (to be implemented in the next iterations)
«11» - Rejected by the Clinic
«12» - GP cancelled
«13» - Rejected by the UK

The statuses of the orders «7», «8», «9», «10»are required for the issuance of the GP in XML format with further signing of the EDS on the side of the Insurance Company. At the moment, the status model is embedded, but this functionality is not available, as it is planned to be implemented in subsequent iterations.

Restrictions on the use of statuses

The order statuses can only move upward. At the same time, it is not necessarily consistent.

The order statuses «11»- Rejected by the UK Clinic, «12»- GP cancelled, «13»- Rejected by the UK are final. The order cannot be edited in such statuses.

The clinic can edit the order only when the order has one of the following statuses:

«1» - Creating an order
«3» - Request for additional information

The insurance company can edit the order only when the order has one of the following statuses:

«1» - Creating an order
«2» - Awaiting approval
«4» - Additional information provided
«6» - Agreed in part or in full, the GP is transmitted in the attachment

Service statuses:

«1» – Awaiting approval
«2» – Agreed without GP
«3» – Agreed by GP
«4» – Rejected
«5» – Transferred to another medical institution

Recommendations for using the API

If a clinic wants to send a request for approval of 2 or more services, it should determine whether the services are homogeneous or heterogeneous (outpatient / hospital / laboratory). In the case of heterogeneous services, it is worth creating 2 or more different orders.
In the case of a phased approval of services by the insurance company, when the order is in the status «2 - Ожидает согласования»or«4 - Дополнительная информация предоставлена», the clinic provides services agreed by the insurance company at its own risk

Basic business cases

The test cases with JSON examples are collected in the table

The clinic requests approval of services, GP is not required

Description: the clinic requests approval from the Insurance Company for the list of services, the Insurance company decides whether to fully or partially coordinate the services in the order.

The clinic creates an order using the POST /insurance_approval/orders/ method. At the same time, in the "lpu_ids" field, the clinic indicates the expected branch ids of its network, to which the insured patient can apply for the provision of agreed services after approval from the UK.
The clinic adds services for approval to the order using the POST /insurance_approval/orders/{uuid}/services/bulk_create/ method. For each service, you must specify:
1. the cost in the "price" field
2. for quantitative services, their number is in the "count" field
3. ""letter_of_guarantee" field has a value of "false"
The clinic adds information from the appointment protocols (complaints, medical history, diagnosis, etc.) to the order using the POST /insurance_approval/orders/{uuid}/protocols/bulk_create/ method, specifying the order id in the URL
""The clinic submits the order for approval to the IC by passing the value "2" in the "status" field (Awaiting approval) using the PATCH /insurance_approval/orders/{uuid}/ method. After "2" order status changes, the clinic can make changes to the order, services, protocols and files only if the UK changes the status of the order to "3" (Request for additional information)
The UK requests a list of orders with a certain frequency using the GET /insurance_approval/orders/ method. ""dt_updated_gte" and "dt_updated_lte" parameters corresponding to the update frequency must be specified to receive only updated orders.
The UK receives a new order in the list of orders with the status "2" (Awaiting approval)
The UK processes the information from the order and decides on the approval of services
The UK has decided to coordinate the services and specifies PATCH /insurance_approval/orders/{uuid}/services/bulk_update in the PATCH /insurance_approval/orders/{uuid}/bulk_update method for each service in the order/:
1. """0"" in "agreed_count" field and "4"" in "status" field (Rejected) for each uncoordinated service.
2. ""for each agreed service: in the "agreed_count" field, the agreed quantity, in the "status" field, the value "2" (Agreed without GP)
The "UK" transfers the agreed order to the clinic by changing the value of the "status" field of the order to "5" (Partially or completely agreed, no GP) using the PATCH/insurance_approval/orders/{uuid} method/
1. (optional) specifies the approval sheet number in the approval_list.number field
2. changes the ""status"" field value of the order to "5" (Partially or fully agreed, there is no GP)
The clinic requests a list of orders with a certain frequency using the GET /insurance_approval/orders/ method. ""dt_updated_gte" and "dt_updated_lte" parameters corresponding to the update frequency must be specified to receive only updated orders.
The clinic receives a new order in the list of orders with the status "5" (Partially or completely agreed, no GP) with a list of agreed services.

The clinic requests approval of services, GP is expected and transferred

Description: the clinic indicates which services from the list it expects to receive a letter of guarantee upon approval, and which services can be agreed without a letter of guarantee. The insurance company coordinates the services and transmits the letter of guarantee via API

The clinic creates an order using the POST /insurance_approval/orders/ method. At the same time, in the "lpu_ids" field, the clinic indicates the expected branch ids of its network, to which the insured patient can apply for the provision of agreed services after approval from the UK.
The clinic adds services for approval to the order using the POST /insurance_approval/orders/{uuid}/services/bulk_create/ method. For each service, you must specify:
1. the cost in the "price" field
2. for quantitative services, their number is in the "count" field
3. the ""letter_of_guarantee"" field has the value "true"
The clinic adds information from the appointment protocols (complaints, medical history, diagnosis, etc.) to the order using the POST /insurance_approval/orders/{uuid}/services/bulk_create/ method, specifying the order id in the URL
""The clinic submits the order for approval to the IC by passing the value "2" in the "status" field (Awaiting approval) using the PATCH /insurance_approval/orders/{uuid}/ method. After "2" order status changes, the clinic can make changes to the order, services, protocols and files only if the UK changes the status of the order to "3" (Request for additional information)
The UK requests a list of orders with a certain frequency using the GET /insurance_approval/orders/ method. ""dt_updated_gte" and "dt_updated_lte" parameters corresponding to the update frequency must be specified to receive only updated orders.
The UK receives a new order in the list of orders with the status "2" (Awaiting approval)
The UK processes the information from the order and decides on the approval of services
The UK has decided to coordinate the services and indicates in the order for each service:
1. """0"" in "agreed_count" field and "4"" in "status" field (Rejected) for each uncoordinated service.
2. ""for each agreed service that does not require GP: in the "agreed_count" field, the agreed quantity, in the "status" field, the value "2" (Agreed without GP)
3. ""Agreed quantity" is indicated in the "agreed_count" field for each agreed service requiring GP, and "3" is indicated in the "status" field (Agreed according to GP).
(optional) The UK specifies which branches of the Clinic's network the insured patient can contact to provide GP-agreed services using the POST /insurance_approval/orders/{uuid}/filials_for_letter_of_guarantee/bulk_create/ method. This is optional information. If specific branches of the Clinic are not specified, it is assumed that the insured patient can contact any branch of the Clinic to provide GP-agreed services.
The UK uploads the GP file using the POST /insurance_approval/orders/{uuid}/letter_of_guarantee_pdf method/
The UK transmits the agreed order to the clinic using the method: PATCH /insurance_approval/orders/{uuid}/:
1. (optional) specifies the approval sheet number in the approval_list.number field
2. specifies the GP parameters in the "letter_of_guarantee" object
3. changes the ""status"" field value of the order to "6" (Partially or fully agreed, GP is provided in the attachment)
The clinic requests a list of orders with a certain frequency using the GET /insurance_approval/orders/ method. ""dt_updated_gte" and "dt_updated_lte" parameters corresponding to the update frequency must be specified to receive only updated orders.
The clinic receives a new order in the list of orders with the status "6" (Partially or completely agreed, GP submitted in the attachment) with a list of agreed services and (optional) the list of branches where it is possible to provide the insured patient with GP-agreed services
The clinic requests the GP file using the GET /insurance_approval/orders/{uuid}/letter_of_guarantee_pdf method/

Request for additional information

Description: The Insurance Company does not have enough information provided by the Clinic to make a decision, and the Insurance Company requests additional information from the Clinic via the API, and the clinic transmits it via the API as well

The clinic creates an order using the POST /insurance_approval/orders/ method. At the same time, in the "lpu_ids" field, the clinic indicates the expected branch ids of its network, to which the insured patient can apply for the provision of agreed services after approval from the UK.
The clinic adds services for approval to the order using the POST /insurance_approval/orders/{uuid}/services/bulk_create/ method. For each service, you must specify:
1. the cost in the "price" field
2. for quantitative services, their number is in the "count" field
3. ""letter_of_guarantee" field has a value of "false"
The clinic adds information from the appointment protocols (complaints, medical history, diagnosis, etc.) to the order using the POST /insurance_approval/orders/{uuid}/services/bulk_create/ method, specifying the order id in the URL
""The clinic submits the order for approval to the IC by passing the value "2" in the "status" field (Awaiting approval) using the PATCH /insurance_approval/orders/{uuid}/ method. After "2" order status changes, the clinic can make changes to the order, services, protocols and files only if the UK changes the status of the order to "3" (Request for additional information)
The UK requests a list of orders with a certain frequency using the GET /insurance_approval/orders/ method. ""dt_updated_gte" and "dt_updated_lte" parameters corresponding to the update frequency must be specified to receive only updated orders.
The UK receives a new order in the list of orders with the status "2" (Awaiting approval)
The UK processes the information from the order and decides whether to request additional information, as there is not enough data to make a decision.
The UK specifies a comment in the "comment" field using the PATCH /insurance_approval/orders/{uuid}/services/bulk_update method for each service for which there is insufficient information./:
The UK submits an order to clarify the information to the Clinic using the PATCH /insurance_approval/orders/{uuid} method/:
1. specifies a general comment on the order in the "information" field
2. changes the ""status"" field value of the order to "3" (Request for additional information)
The clinic requests a list of orders with a certain frequency using the GET /insurance_approval/orders/ method. ""dt_updated_gte" and "dt_updated_lte" parameters corresponding to the update frequency must be specified to receive only updated orders.
"The clinic" receives a new order in the list of orders with the status "3" (Request for additional information), where, in the fields "information" and data.services.comment, the UK indicated which information it lacks on which services
(optional) The clinic adds documents to the order (tests, scans, conclusions, etc.) using the POST /insurance_approval/orders/{uuid}/attachments/bulk_create method/
The clinic provides additional information and transmits the order to the UK using the PATCH /insurance_approval/orders/{uuid} method/:
1. specifies a general comment on the order in the "information" field
2. changes the ""status"" field value of the order to "4" (Additional information is provided)
The UK requests a list of orders with a certain frequency using the GET /insurance_approval/orders/ method. ""dt_updated_gte" and "dt_updated_lte" parameters corresponding to the update frequency must be specified to receive only updated orders.
"""" The UK receives a new order in the list of orders with the status "4" (Additional information is provided), where the clinic has provided additional information in the "information" field and has provided attachment files in the "data.attachments" object.
The UK requests attachments to the order one at a time using the GET /insurance_approval/orders/{uuid}/attachments/{attachment_id} method/
The UK processes the information received and decides on the approval of services.
The UK has decided to coordinate the services and specifies PATCH /insurance_approval/orders/{uuid}/services/bulk_update in the PATCH /insurance_approval/orders/{uuid}/bulk_update method for each service in the order/:
1. """0"" in "agreed_count" field and "4"" in "status" field (Rejected) for each uncoordinated service.
2. ""for each agreed service: in the "agreed_count" field, the agreed quantity, in the "status" field, the value "2" (Agreed without GP)
The "UK" transfers the agreed order to the clinic by changing the value of the "status" field of the order to "5" (Partially or completely agreed, no GP) using the PATCH/insurance_approval/orders/{uuid} method/
1. (optional) specifies the approval sheet number in the approval_list.number field
2. changes the ""status"" field value of the order to "5" (Partially or fully agreed, there is no GP)
The clinic requests a list of orders with a certain frequency using the GET /insurance_approval/orders/ method. ""dt_updated_gte" and "dt_updated_lte" parameters corresponding to the update frequency must be specified to receive only updated orders.
The clinic receives a new order in the list of orders with the status "5" (Partially or completely agreed, no GP) with a list of agreed services.

The insurance company initiates the process by submitting the order and GP to the clinic.

Description: The insured patient contacted the insurance company, the insurance company referred the insured patient to the Clinic and sent an order to the Clinic in advance via API without a list of services. Based on the results of the appointment, the clinic independently fills out the order and sends it for approval.

The UK creates an order using the POST /insurance_approval/orders/ method. At the same time, in the "lpu_ids" field, the UK indicates the ID of the branches of the Clinic's network to which the insured patient can apply for the provision of agreed services.
(optional) The UK specifies which branches of the Clinic's network the insured patient can contact to provide GP-agreed services using the POST /insurance_approval/orders/{uuid}/filials_for_letter_of_guarantee/bulk_create/ method. This is optional information. If specific branches of the Clinic are not specified, it is assumed that the insured patient can contact any branch of the Clinic to provide GP-agreed services.
The UK uploads the GP file using the POST /insurance_approval/orders/{uuid}/letter_of_guarantee_pdf method/
The UK transmits the agreed order to the clinic using the method: PATCH /insurance_approval/orders/{uuid}/:
1. (optional) specifies the approval sheet number in the approval_list.number field
2. ""specifies the GP parameters in the "letter_of_guarantee" object, including the value of the "money_limit" field (GP liability limit)
3. changes the ""status"" field value of the order to "6" (Partially or fully agreed, GP is provided in the attachment)
The clinic requests a list of orders with a certain frequency using the GET /insurance_approval/orders/ method. ""dt_updated_gte" and "dt_updated_lte" parameters corresponding to the update frequency must be specified to receive only updated orders.
The clinic receives a new order in the list of orders with the status "6" (Partially or completely agreed, GP submitted in the attachment) with a list of agreed services and (optional) the list of branches where it is possible to provide the insured patient with GP-agreed services
The clinic requests the GP file using the GET /insurance_approval/orders/{uuid}/letter_of_guarantee_pdf method/
The clinic adds services to provide the insured patient within the limits of the liability limit agreed upon by the GP to the order using the POST /insurance_approval/orders/{uuid}/services/bulk_create/ method, for each service it is necessary to specify:
1. the cost in the "price" field
2. for quantitative services, their number is in the "count" field
3. the ""letter_of_guarantee"" field has the value "true"

Cancellation of GP

Description: The insurance company cancels the previously issued GP

Steps 1-14 are identical to the case The clinic requests approval of services, GP is expected and transferred

The UK cancels the GP using the PATCH /insurance_approval/orders/{uuid} method/:
1. in the "letter_of_guarantee.cancellation_date" field, specify the date of cancellation of the GP
  b. The ""status"" field must have the value "12" (GP cancelled).
The clinic requests a list of orders with a certain frequency using the GET /insurance_approval/orders/ method. ""dt_updated_gte" and "dt_updated_lte" parameters corresponding to the update frequency must be specified to receive only updated orders.
The clinic receives a new order in the list of orders with the status "12" (GP cancelled)

Rejection of the order by the Clinic

Description:The clinic rejects the approval order in full. You can reject an order regardless of its current status.

The clinic rejects the order using the PATCH /insurance_approval/orders/{uuid} method/:
1. (optional) indicates the reason for the rejection in the "information" field
2. changes ""status"" field value to "11" - (Rejected by the clinic)
The UK requests a list of orders with a certain frequency using the GET /insurance_approval/orders/ method. ""dt_updated_gte" and "dt_updated_lte" parameters corresponding to the update frequency must be specified to receive only updated orders.
The UK receives a new order in the list of orders with the status "11" - (Rejected by the clinic)

The order status is "11" - (Rejected by the clinic) final - editing of the order in this status, its services, protocols, etc. is not available

Rejection of an order by an Insurance company

Description:The UK rejects the approval order in full. You can reject an order regardless of its current status. At the same time, in the order statuses «5 - Согласовано частично или полностью, нет ГП»and «6 - Согласовано частично или полностью, ГП передано во вложении»editing the list of services will not be available, you do not need to send a request to edit them.

(if the order is in statuses 1, 2, or 4) the UK rejects services using the PATCH /insurance_approval/orders/{uuid}/services/bulk_update method.:
1. """0"" in "agreed_count" field and "4"" in "status" field (Rejected) for each uncoordinated service.
The UK rejects the order using the PATCH /insurance_approval/orders/{uuid} method/:
1. (optional) indicates the reason for the rejection in the "information" field
2. changes ""status"" field value to "13" - (Rejected by the UK)
The clinic requests a list of orders with a certain frequency using the GET /insurance_approval/orders/ method. ""dt_updated_gte" and "dt_updated_lte" parameters corresponding to the update frequency must be specified to receive only updated orders.
The clinic receives a new order in the list of orders with the status "13" - (Rejected by the UK)

The order status is "13" - (Rejected by the UK) final - editing the order in this status, its services, protocols, etc. is not available

Step-by-step approval of services by the insurance company, all services are agreed

Initial data: the clinic has sent an order for approval of 3 services, 2 of which are outpatient and can be approved by the insurance company within 1 hour, and the remaining 1 service requires hospitalization of the patient and can be approved within 24 hours

Decision:

The insurance company receives the warrant without changing its status
The insurance company, using the /insurance_approval/orders/{uuid}/services/bulk_update/ method, changes the status of 2 services to «2 – Согласована без ГП»or «3 – Согласована по ГП»within an hour
The clinic requests orders based on the update date with the required frequency or manually.
Upon receiving the updated order, the clinic looks at the agreed services and receives information that the insurance company has agreed on 2 of them and can provide these services to the patient.
A day later, the insurance company approves the 3rd of the services of the order (hospitalization), while changing the status of the service in the «2 – Согласована без ГП»or order «3 – Согласована по ГП»and the status of the «5 - Согласовано частично или полностью, нет ГП»or order itself.«6 - Согласовано частично или полностью, ГП передано во вложении»

The case "Step-by-step approval of services by an insurance company, not all services are agreed upon"

Decision:

The insurance company receives the warrant without changing its status
The insurance company, using the /insurance_approval/orders/{uuid}/services/bulk_update/ method, changes the status of 2 services to «2 – Согласована без ГП»or «3 – Согласована по ГП»within an hour
The clinic requests orders based on the update date with the required frequency or manually.
Upon receiving the updated order, the clinic looks at the agreed services and receives information that the insurance company has agreed on 2 of them and can provide these services to the patient.
A day later, the insurance company approves the 3rd of the services of the order (hospitalization), while changing the status of the service in the order «4 – Отклонена»and the status of the order itself for «5 - Согласовано частично или полностью, нет ГП»or«6 - Согласовано частично или полностью, ГП передано во вложении»

The case study "Step-by-step approval of services by an insurance company, all services were refused"

Decision:

The insurance company receives the warrant without changing its status
The insurance company, using the /insurance_approval/orders/{uuid}/services/bulk_update/ method, changes the status of 2 services to «4 – Отклонена»within an hour
The clinic requests orders based on the update date with the required frequency or manually.
Upon receiving the updated order, the clinic looks at the agreed services and receives information that the insurance company refused to approve 2 of them.
A day later, the insurance company refuses to approve the 3rd of the services of the order (hospitalization), while changing the status of the service in the order «4 – Отклонена»and the status of the order itself«13 - Отклонен СК»

Technical documentation

Table of contents

General description

API methods by role:

API methods (full list):

The status model

Order statuses:

Service statuses:

Recommendations for using the API

Basic business cases

The clinic requests approval of services, GP is not required

The clinic requests approval of services, GP is expected and transferred

Request for additional information

The insurance company initiates the process by submitting the order and GP to the clinic.

Cancellation of GP

Rejection of the order by the Clinic

Rejection of an order by an Insurance company

Step-by-step approval of services by the insurance company, all services are agreed

The case "Step-by-step approval of services by an insurance company, not all services are agreed upon"

The case study "Step-by-step approval of services by an insurance company, all services were refused"

API methods by role: 