The operation retrieve will fetch a policy, loan, pension, master agreement or contract within an existing master agreement for a single entry, a range or a list of entries. The output consists of the structures needed in the particular situation, so it can be a policyStructure or a masterAgreementStructure (see also policyStructure and masterAgreementStructure).
Once a contract has been submitted, the data is available through the retrieve function. The variant is used to determine the scope of the required information.
How to use variants
If you want to retrieve a contract, choose the operation retrieve. If a particular handling variant is requested, use a variant. If not, select the default variant. The variant determines which attributes are mandatory.
The operation retrieve is a webservice call without a body. The functionVariant is included as a path parameter and the contractNumber (or range of contractNumbers) is included as query parameter in the request. For more information see the Retrieve operations section of the Design principles chapter.
The output will contain a single masterAgreementStructure or policyStructure if only one id is specified, or an array of structures if more than one id is specified, or if no id is specified, at all.
If a negative response is generated, that means the request is technically incorrect, it follows the general rules as described in the Error section of the HTTP status codes and error handling chapter.
Variants
| Variant | Description | policy structure |
masterAgreement structure |
pension structure |
loan structure |
| <default> | Obtain full details of a contract based on the unique reference | Yes | Yes | U/C | U/C |
| bookingList | Retrieve all available bookings of a contract according to a query statement | Yes | Yes | U/C | U/C |
| claimCoverCheck | Obtain policy information such as coverage and deductible based on query parameters and/or claim data in the request body, | Yes | Yes | U/C | U/C |
| documentList | Retrieve all available documents of a contract according to a query statement | Yes | Yes | U/C | U/C |
| documentRange | [DEPRECATED] Obtain documents for one contract based on a range of unique references | Yes | Yes | U/C | U/C |
| invoiceList | Retrieve all available invoices of a contract according to a query statement | Yes | Yes | U/C | U/C |
| list | Retrieve a list of all available contracts according to a query statement | Yes | Yes | U/C | U/C |
| offer | Obtain full details of an offer of a contract based on the unique reference | Yes | Yes | U/C | U/C |
| offerList | Retrieve all available offers for a contract according to a query statement | Yes | Yes | U/C | U/C |
| offerRange | [DEPRECATED] Obtain details of multiple offers based on a range of unique references | Yes | Yes | U/C | U/C |
| range | [DEPRECATED] Obtain details of multiple contracts based on a range of unique references | Yes | Yes | U/C | U/C |
| financialMidTemChange | Obtain financial booking resulting from the mid-term change of a contract (“PMB”) | Yes | Yes | U/C | U/C |
| status | Obtain status information of a contract by a unique reference | Yes | Yes | U/C | U/C |
| statusOffer | Obtain status information of an offer by a unique reference | Yes | Yes | U/C | U/C |
U/C: Under construction.
- <default> – Obtain full details of a contract based on the unique reference
-
The variant default retrieves all contract data using a unique reference.
policyStructure
The policyStructure is used to retrieve the complete policy using a unique reference. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.
Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/policies/{policyId}/retrieve N/A N/A policyStructure
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. policy contractNumber O The identifying characteristic assigned by a company or underwriting agent. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
masterAgreementStructure
The masterAgreementStructure is used to retrieve the complete masterAgreement. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.
It is possible to execute this operation for a subcontract by adding the contract number as a query parameter (filter contractnumber={contractId}). More information on query parameters is available in Design principles.
Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/master-agreements/{masterAgreementId}/retrieve N/A contractNumber={contractId} masterAgreementStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. masterAgreement contractNumber O Number of the masterAgreement contract. policy contractNumber O** The identifying characteristic assigned by a company or underwriting agent. Please note: only applicable with a retrieve policy. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
** See note in the remarks. - bookingList – Retrieve all available bookings of a contract according to a query statement
-
The variant bookingList is used to retrieve a list of all available bookings of a contract based on a query statement. It is possible to request multiple fields.
policyStructure
The policyStructure is used to retrieve a list of all available bookings for a policy based on a query statement. For more information on query parameters refer to the Design principles. The mandatory attributes (in a generic form) are listed in the table Mandatory input and/or output (I/O) attributes.
Endpoint definition
To retrieve a list of all available bookings the query parameter ‘entityType=booking’ must always be included in the endpoint. This requirement is shown in the table below. More information on query parameters is available in the Design principles).
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/policies/{policyId}/financialTransactions/list N/A fields=[{attribute}]
filter=[entityType=booking];
filter=[{attribute}|{operator}|{valueAttribute}]policyStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. policy contractNumber O The identifying characteristic assigned by a company or underwriting agent. financialTransaction.booking refKey O Unique reference key assigned to an entity. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
masterAgreementStructure
The masterAgreementStructure is used to request a list of all available bookings for a specified masterAgreement based on a query statement. The mandatory attributes (in a generic form) are listed in the table Mandatory input and/or output (I/O) attributes.
To retrieve a list of all available bookings the query parameter ‘entityType = booking’ must always be included in the endpoint.
It is also possible to request bookings for a subcontract by adding the contract number as a query parameter (with filter contractNumber={contractId}). For more information on query parameters, refer to the Design principles.
Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/master-agreements/{masterAgreementId}/financial-transactions/list N/A fields=[{attribute}]
filter=[entityType=booking]
filter=[{attribute}|{operator}|{valueAttribute}]
sort=[{attribute}]masterAgreementStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. masterAgreement contractNumber O Number of the masterAgreement contract. policy contractNumber O** The identifying characteristic assigned by a company or underwriting agent. Please note: only applicable with a retrieve policy. financialTransaction.booking refKey O The identifying characteristic assigned by a company or underwriting agent. Please note: only applicable with a retrieve policy. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
** See note in the remarks. - claimCoverCheck – Obtain details of a contract based on claim references
-
The variant claimCoverCheck is used to determine, based on context-specific claim information (such as cause, type, and date of loss), whether a contract provides coverage, which deductible applies, whether there are NCBM (No-Claim Bonus/Malus) consequences, and the insured amount. This allows customers to decide – before submitting a claim – whether to pay for the damage themselves or submit it through their insurance.
claimStructure
The claimStructure is used to submit claim-related information in the request. Required attributes are marked with an ‘I’ in the third column of the table Mandatory input and/or output (I/O) attributes.
policyStructure
The policyStructure is used to return information about the relevant policy and its coverage in the response. Required attributes are marked with an ‘O’ in the third column of the table Mandatory input and/or output (I/O) attributes.
Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks POST { uri }/policies/{policyId}/claim-cover-check claimStructure fields=[{attribute}]
filter=[{attribute}|{operator}|{valueAttribute}]policyStructure A post request with a body is used for flexibility and to conform with the SIVI AFS convention for information-oriented queries. Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion I/O Version of the data catalog on which the message is based. commonFunctional functionVariant I/O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName I/O Name of the AFD-definition. commonFunctional afdDefinitionVersion I/O Version of the AFD-definition. claim dateOfLoss I Date when the accident/damage occurred. incident damageClassification I Default classification for damage aspects, relevant for recording, communicating and reporting damage. policy contractNumber O The identifying characteristic assigned by a company or underwriting agent. coverage coverageCode O Standardized code to indicate the type of coverage and the (group of) risk(s) against which the coverage has been / will be taken out. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
claimStructure
The claimStructure is used to submit claim-related information in the request. Required attributes are marked with an ‘I’ in the third column of the table Mandatory input and/or output (I/O) attributes.
masterAgreementStructure
The masterAgreementStructure is used to return information about the relevant policy and its coverage in the response. Required attributes are marked with an ‘O’ in the third column of the table Mandatory input and/or output (I/O) attributes.
Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks POST { uri }/master-agreements/{masterAgreementId}/contracts/{contractId}/claim-cover-check claimStructure fields=[{attribute}]
filter=[{attribute}|{operator}|{valueAttribute}]masterAgreementStructure A post request with a body is used for flexibility and to conform with the SIVI AFS convention for information-oriented queries. Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion I/O Version of the data catalog on which the message is based. commonFunctional functionVariant I/O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName I/O Name of the AFD-definition. commonFunctional afdDefinitionVersion I/O Version of the AFD-definition. claim dateOfLoss I Date when the accident/damage occurred. incident damageClassification I Default classification for damage aspects, relevant for recording, communicating and reporting damage. masterAgreement contractNumber O Number of the masterAgreement contract. policy contractNumber O The identifying characteristic assigned by a company or underwriting agent. coverage coverageCode O Standardized code to indicate the type of coverage and the (group of) risk(s) against which the coverage has been / will be taken out. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
- documentList – Retrieve all available documents of a contract according to a query statement
-
The variant documentList is used to retrieve all available documents of a contract according to a query statement. It is possible to request multiple fields. The
sequenceNumberis always returned, even if no fields or attributes were requested.policyStructure
The policyStructure is used to retrieve a list of all available documents for a policy based on a query statement. If, for example, only documents valid on a certain date should be retrieved, it is possible to use
validOnas a filter in the query statement. More information on query parameters is available in Design principles. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/policies/{policyId}/documents/list N/A fields=[{attribute}]
filter=[{attribute}|{operator}|{valueAttribute}]
sort=[{attribute}]policyStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. policy contractNumber O The identifying characteristic assigned by a company or underwriting agent. document sequenceNumber O The entity documentis returned as a list.Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
masterAgreementStructure
The masterAgreementStructure is used to request a list of all available documents for a specified masterAgreement based on a query statement. If, for example, only documents valid on a certain date should be retrieved, it is possible to use
validOnas a filter in the query statement. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.It is possible to request documents of a subcontract by adding the contract number as a query parameter (with filter contractNumber={contractId}). More information on query parameters is available in Design principles.
Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/master-agreements/{masterAgreementId}/documents/list N/A fields=[{attribute}]
filter=[{attribute}|{operator}|{valueAttribute}]
sort=[{attribute}]masterAgreementStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. masterAgreement contractNumber O Number of the masterAgreement contract. policy contractNumber O** The identifying characteristic assigned by a company or underwriting agent. Please note: only applicable with a retrieve policy. document sequenceNumber O The entity documentis returned as a list.Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
** See note in the remarks. - documentRange – [DEPRECATED] Obtain details of multiple documents for one contract based on a range of unique references
-
The variant documentRange is used to retrieve multiple documents of a contract, using a list of document numbers.
policyStructure
The policyStructure is used to retrieve multiple documents of a policy based on a query statement. More information on query parameters is available in Design principles. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.
Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/policies/{policyId}/documents/range N/A documents=[{documentId}] policyStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. policy contractNumber O The identifying characteristic assigned by a company or underwriting agent. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
masterAgreementStructure
The masterAgreementStructure is used to retrieve multiple documents of a masterAgreement based on a query statement. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.
If no contract number or documents are added to the query parameter, all documents of the master agreement and subcontracts are returned. If only the contract number is added, then all documents connected to this contract number will be returned. If no subcontract is requested, then all documents of the master agreement are returned. More information on query parameters is available in Design principles.
Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/master-agreements/{masterAgreementId}/documents/range N/A contractNumber={contractId}
documents=[{documentId}]masterAgreementStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
If no document numbers are used, all documents for the selected
masterAgreementare retrieved.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. masterAgreement contractNumber O Number of the masterAgreement contract. policy contractNumber O** The identifying characteristic assigned by a company or underwriting agent. Please note: only applicable with a retrieve policy. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
** See note in the remarks. - invoiceList – Retrieve all available invoices of a contract according to a query statement
-
The variant invoiceList is used to retrieve all available invoices of a contract based on a query statement. It is possible to request multiple fields.
policyStructure
The policyStructure is used to retrieve a list of all available invoices for a policy, based on a query statement. The mandatory attributes (in a generic form) are listed in the table Mandatory input and/or output (I/O) attributes. For more information on query parameters, refer to the Design principles.
Endpoint definition
To retrieve a list of all available invoices, the query parameter ‘entityType=invoice’ must always be included in the endpoint. This requirement is illustrated in the table below. More information on query parameters is available in he Design principles.
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/policies/{ policyId }/financial-informations/list N/A fields=[{attribute}]
filter=[entityType=invoice]
filter=[{attribute}|{operator}|{valueAttribute}]policyStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
For more information about query parameters, see Design principles
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. policy contractNumber O The identifying characteristic assigned by a company or underwriting agent. financialTransaction.invoice refKey O Unique reference key assigned to an entity. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
masterAgreementStructure
The masterAgreementStructure is used to request a list of available invoices for a specified masterAgreement, based on a query statement. The mandatory attributes (in a generic form) are listed in the table Mandatory input and/or output (I/O) attributes.
To retrieve a list of all available invoices the query parameter ‘entityType=invoice’ must always be included in the endpoint.
It is also possible to request invoices for a subcontract by adding the contract number as a query parameter (filter contractnumber=[{contractId}). More information on query parameters is available in he Design principles.Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/master-agreements/{masterAgreementId}/financial-informations/list N/A fields=[{attribute}]
filter=[entityType=invoice]
filter=[{attribute}|{operator}|{valueAttribute}]masterAgreementStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. masterAgreement contractNumber O Number of the masterAgreement contract. policy contractNumber O** The identifying characteristic assigned by a company or underwriting agent. Please note: only applicable with a retrieve policy. financialTransaction.invoice refKey O Unique reference key assigned to an entity. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
** See note in the remarks. - list – Retrieve a list of all available contracts according to a query statement
-
The variant list is used to retrieve a list of contracts, using the contract number by default, but this can be extended by a certain number of extra attributes.
policyStructure
The policyStructure is used to retrieve a list of policies based on a query statement. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes. More information on query parameters is available in Design principles.
Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/policies/list N/A fields=[{attribute}]
filter=[{attribute}|{operator}|{valueAttribute}]policyStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
For more information about query parameters, see Design principles
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. policy contractNumber O The identifying characteristic assigned by a company or underwriting agent. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
masterAgreementStructure
The masterAgreementStructure is used to retrieve a list of masterAgreements based on a query statement. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.
Endpoint definition
If all
masterAgreements(including the underlying contracts) are subject to this operation and variant, no path parameter is included in the endpoint. This is shown in the table below. More information about query parameters is available in Design principles.Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/master-agreements/list N/A fields=[{attribute}]
filter=[{attribute}|{operator}|{valueAttribute}]masterAgreementStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
If not all
masterAgreementsare subject to this operation and variant but only a specificmasterAgreement, a path parameter ({masterAgreementId}) is included in the endpoint. This is shown in the table below. More information about query parameters is available in Design principles.Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/master-agreements/{masterAgreementId}/list N/A fields=[{attribute}]
filter=[{attribute}|{operator}|{valueAttribute}]masterAgreementStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. masterAgreement contractNumber O Number of the masterAgreement contract. policy contractNumber O** The identifying characteristic assigned by a company or underwriting agent. Please note: only applicable with a retrieve policy. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
** See note in the remarks. - offer – Obtain full details of an offer of a contract based on the unique reference
-
The variant offer is used to retrieve all data of the offer, using a unique reference.
policyStructure
The policyStructure is used to retrieve all data of an offer for a policy. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.
Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/policies/offers/{offerId}/retrieve N/A N/A policyStructure
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. policy offerNumber O Number of the offer. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
masterAgreementStructure
The masterAgreementStructure is used to retrieve all data of an offer for a masterAgreement. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.
Endpoint definition
If an offer for a complete
masterAgreement(including the underlying contracts) is subject to this operation, one path parameter ({offerId}) is included in the endpoint. This is shown in the table below.Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/master-agreements/offers/{offerId}/retrieve N/A N/A masterAgreementStructure
If not the complete
masterAgreementis subject to this operation and variant, but only a particular contract within amasterAgreement, two path parameters ({offerId} and {masterAgreementId}) are included in the endpoint. This is shown in the table below.Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/master-agreements/{masterAgreementId}/offers/{offerId}/retrieve N/A N/A masterAgreementStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. masterAgreement contractNumber O** Number of the masterAgreement contract. Please note: only applicable with a retrieve offer policy. masterAgreement offerNumber O** Number of the offer. Please note: only applicable with a retrieve offer masterAgreement. policy offerNumber O** Number of the offer. Please note: only applicable with a retrieve offer policy. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
** See note in the remarks. - offerList – Retrieve all available offers for a contract according to a query statement
-
The variant offerList is used to retrieve all available offers for a contract based on a query statement. It is possible to request multiple fields. The
offerNumberis always returned, even if no fields or attributes were requested.policyStructure
The policyStructure is used to retrieve a list of all available offers for a policy based on a query statement. More information on query parameters is available in Design principles. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.
Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/policies/offers/list N/A fields=[{attribute}]
filter=[{attribute}|{operator}|{valueAttribute}]policyStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. policy offerNumber O Number of the offer. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
masterAgreementStructure
The masterAgreementStructure is used to request a list of all available offers for a specified masterAgreement based on a query statement. More information on query parameters is available in Design principles. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.
Endpoint definition
If all
masterAgreements(including the underlying contracts) are subject to this operation and variant, no path parameter is included in the endpoint. This is shown in the table below. More information on query parameters is available in Design principles.Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/master-agreements/offers/list N/A fields=[{attribute}]
filter=[{attribute}|{operator}|{valueAttribute}]masterAgreementStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
If not all
masterAgreementsare subject to this operation and variant but only a specificmasterAgreement, a path parameter ({masterAgreementId}) is included in the endpoint. This is shown in the table below. More information about query parameters is available in Design principles.Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/master-agreements/{masterAgreementId}/offers/list N/A fields=[{attribute}]
filter=[{attribute}|{operator}|{valueAttribute}]masterAgreementStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. masterAgreement contractNumber O** Number of the masterAgreement contract. Please note: only applicable with a retrieve offer policy. masterAgreement offerNumber O** Number of the offer. Please note: only applicable with a retrieve offer masterAgreement. policy offerNumber O** Number of the offer. Please note: only applicable with a retrieve offer policy. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
** See note in the remarks. - offerRange – [DEPRECATED] Obtain details of multiple offers based on a range of unique references
-
The variant offerRange is used to retrieve multiple offers for a contract, using a list of offer numbers.
policyStructure
The policyStructure is used to retrieve multiple offers for a policy based on a query parameter. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes. More information on query parameters is available in Design principles.
Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/policies/offers/range N/A offers=[{offerId}] policyStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. policy offerNumber O Number of the offer. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
masterAgreementStructure
The masterAgreementStructure is used to retrieve multiple offers for a masterAgreement based on a query parameter. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.
Endpoint definition
If the complete
masterAgreement(including the underlying contracts) is subject to this operation and variant, no path parameter is included in the endpoint. This is shown in the table below. More information on query parameters is available in Design principles.Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/master-agreements/offers/range N/A offers=[{offerId}] masterAgreementStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
If not the complete
masterAgreementis subject to this operation and variant, but only a particular contract within thatmasterAgreement, a path parameter ({masterAgreementId}) is added to the endpoint. This is shown in the table below.Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/master-agreements/{masterAgreementId}/offers/range N/A offers=[{offerId}] masterAgreementStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
If no offer numbers are used as a query parameter, all offers for the selected
masterAgreementare retrieved. More information on query parameters is available in Design principles.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. masterAgreement contractNumber O** Number of the masterAgreement contract. Please note: only applicable with a retrieve offer policy. masterAgreement offerNumber O** Number of the offer. Please note: only applicable with a retrieve offer masterAgreement. policy offerNumber O** Number of the offer. Please note: only applicable with a retrieve offer policy. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
** See note in the remarks. - range – [DEPRECATED] Obtain details of multiple contracts based on a range of unique references
-
The variant range is used to retrieve details of multiple contracts based on a range of unique references.
policyStructure
The policyStructure is used to retrieve details of multiple policies based on a range of unique references. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes. More information on query parameters is available in Design principles.
Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/policies/range N/A contracts=[{contractId}] policyStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. policy contractNumber O The identifying characteristic assigned by a company or underwriting agent. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
masterAgreementStructure
The masterAgreementStructure is used to retrieve details for multiple contracts within a masterAgreement. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.
Endpoint definition
If the complete
masterAgreement(including the underlying contracts) is subject to this operation and variant, no path parameter is included in the endpoint. This is shown in the table below. More information on query parameters is available in Design principles.Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/master-agreements/range N/A contracts=[{contractId}] masterAgreementStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
If not the complete
masterAgreementis subject to this operation and variant, but only a range of particular contract within thatmasterAgreement, a path parameter ({masterAgreementId}) is added to the endpoint. This is shown in the table below.
It is possible to execute this operation for a subcontract by adding the contract number as a query parameter (filter contractnumber={contractId}). If no contract numbers are used as a query parameter, all contracts of the selectedmasterAgreementwill be retrieved.
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/master-agreements/{masterAgreementId}/range N/A contracts=[{contractId}] masterAgreementStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. masterAgreement contractNumber O Number of the masterAgreement contract. policy contractNumber O** The identifying characteristic assigned by a company or underwriting agent. Please note: only applicable with a retrieve policy. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
** See note in the remarks. - financialMidTermChange – Obtain financial booking resulting from the mid-term change of a contract (“PMB”)
-
The variant financialMidTermChange returns the financial result of a mid-term change in an existing contract.
policyStructure
The policyStructure is used to return the financial result of a mid-term change for a policy. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.
Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/policies/{policyId}/financial-mid-term N/A N/A policyStructure
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. policy contractNumber O The identifying characteristic assigned by a company or underwriting agent. policy effectiveChangeDate O Effect date of the change itself. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
masterAgreementStructure
The masterAgreementStructure is used to return the financial result of a mid-term change for a masterAgreement. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.
It is possible to execute this operation for a subcontract by adding the contract number as a query parameter (filter contractnumber={contractId}). If no contract numbers are used as a query parameter, all contracts of the selectedmasterAgreementwill be retrieved. More information on query parameters is available in Design principles.
Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/master-agreements/{masterAgreementId}/financial-mid-term N/A fields=[{attribute}]
filter=[{attribute}|{operator}|{valueAttribute}]
sort=[{attribute}]masterAgreementStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. masterAgreement contractNumber O Number of the masterAgreement contract. masterAgreement effectiveChangeDate O** Effect date of the change itself. Please note: only applicable with a retrieve masterAgreement. policy contractNumber O** The identifying characteristic assigned by a company or underwriting agent. Please note: only applicable with a retrieve policy. policy effectiveChangeDate O** Effect date of the change itself. Please note: only applicable with a retrieve policy. Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
** See note in the remarks. - status – Obtain status information of a contract by a unique reference
-
The variant status retrieves the status of the process and the contract.
policyStructure
The policyStructure is used to retrieve the status of the policy. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.
Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/policies/{policyId}/retrieve/status N/A N/A policyStructure
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. policy contractNumber O The identifying characteristic assigned by a company or underwriting agent. policy statusType O The status of the policy (codelist ADNSTS) within the entityTypepolicyDetails.Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
masterAgreementStructure
The masterAgreementStructure is used to retrieve the status of the masterAgreement based on a query parameter. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.
It is possible to execute this operation for a subcontract by adding the contract number as a query parameter (filter contractnumber={contractId}). If no contract numbers are used as a query parameter, all contracts of the selectedmasterAgreementwill be retrieved. More information on query parameters is available in Design principles.
Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/master-agreements//{masterAgreementId}/retrieve/status N/A contractNumber={contractId} masterAgreementStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. masterAgreement contractNumber O Number of the masterAgreement contract. masterAgreement statusType O** The status of the masterAgreement (codelist ADNSTS). Please note: only applicable with a retrieve status masterAgreement.policy contractNumber O** The identifying characteristic assigned by a company or underwriting agent. Please note: only applicable with a retrieve status policy. policy statusType O** The status of the policy (codelist ADNSTS) within the entityTypepolicyDetails. Please note: only applicable with a retrieve status policy.Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
** See note in the remarks. - statusOffer – Obtain status information of an offer by a unique reference
-
The variant statusOffer is used to request the status of an offer (using an {offerId}).
policyStructure
The policyStructure is used to request the status of an offer for a policy. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.
Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/policies/offers/{offerId}/status N/A N/A policyStructure
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. policy offerNumber O Number of the offer. policy statusType O The status of the policy (codelist ADNSTS) within the entityTypepolicyDetails.Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
masterAgreementStructure
The masterAgreementStructure is used to request the status of an offer for the masterAgreement based on a query parameter. The mandatory attributes (in a generic way) are listed in the table Mandatory input and/or output (I/O) attributes.
It is possible to execute this operation for a subcontract by adding the contract number as a query parameter (filter contractnumber={contractId}). If no contract numbers are used as a query parameter, all contracts of the selectedmasterAgreementwill be retrieved. More information on query parameters is available in Design principles.
Endpoint definition
Method Endpoint Request Query
parameter(s)Response Remarks GET { uri }/master-agreements/offers/{offerId}/status N/A contractNumber={contractId} masterAgreementStructure Note: As of July 1, 2025, query parameters should no longer contain underscores. A transition period is in effect until July 1, 2026. Use of underscores is discouraged, and existing implementations should migrate to the updated naming convention.
Mandatory input and/or output (I/O) attributes
Entity Attribute I/O Remarks commonFunctional dataCatalogVersion O Version of the data catalog on which the message is based. commonFunctional functionVariant O The function variant is used to determine the additional set of required and optional input and output data. commonFunctional afdDefinitionName O Name of the AFD-definition. commonFunctional afdDefinitionVersion O Version of the AFD-definition. masterAgreement contractNumber O** Number of the masterAgreement contract. Please note: only applicable with a retrieve offer status policy. masterAgreement offerNumber O** Number of the offer. Please note: only applicable with a retrieve offer status masterAgreement. masterAgreement statusType O** The status of the masterAgreement (codelist ADNSTS). Please note: only applicable with a retrieve offer status masterAgreement.policy offerNumber O** Number of the offer. Please note: only applicable with a retrieve offer status policy. policy statusType O** The status of the policy (codelist ADNSTS) within the entityTypepolicyDetails. Please note: only applicable with a retrieve offer status policy.Note: since the attribute “entityType” is mandatory for all used structures, it is not mentioned in this table for clarity reasons.
** See note in the remarks.
Post your comment on this topic.