Tutorial Turnover Declaration

Manage and submit your turnover and outstanding declarations as defined by your policy terms.

Prerequisites

To start your integration, please download the following Open API Specification files from our portal:

 

 

Note

If you paste the endpoints without downloading the files, missing headers might lead to call failures.

 

 

Link to business uses cases

Submit my periodic turnover/outstanding declaration

Access and submit your turnover/outstanding declarations.

 

Read more

 

 

1. Get an authentication token

Generate an OAuth token, which will be valid for 1 hour. 

 

See Identity Provider (IDP) Tutorial

 

 

2. Retrieve declaration list

Retrieve the list of your declarations using a GET call.

EnvironmentMethodURL
TestGEThttps://api-services.uat.1placedessaisons.com/uatm/turnover-declaration/v1/declarations
ProductionGEThttps://api.allianz-trade.com/turnover-declaration/v1/declarations 

You can filter results using the following query parameters:

ParameterTypeDescription
businessUnitCodestringBusiness unit code for the policy (e.g. SFAC)
policyIdstringPolicy identifier (e.g. P00000001)
extensionIdstringPolicy extension identifier (e.g. 00001)
declarationStatusCodesarrayFilter by status: TODO, DRAFT, DONE

 

Example request
GET /declarations?businessUnitCode=SFAC&policyId=P00000001&declarationStatusCodes=TODO
Example response
[
  {
    "declarationId": "DECL-2024-001",
    "policyId": "P00000001",
    "extensionId": "00001",
    "declarationPeriodStartDate": "2024-01-01",
    "declarationPeriodEndDate": "2024-12-31",
    "submissionDueDate": "2025-01-31",
    "declarationStatusCode": "TODO",
    "declarationFrequencyCode": "A",
    "declarationCategoryTypeCode": "TURNOVER",
    "declarationBreakdownTypeCode": "COUNTRY",
    "declarationCurrencyCode": "EUR"
  }
]

 

3. Get the exchange rates

If your internal financial data is recorded in a different currency than your policy's declarationCurrencyCode, use this step to retrieve the applicable exchange rate and convert your amounts before submission.

EnvironmentMethodURL
TestGEThttps://api-services.uat.1placedessaisons.com/uatm/turnover-declaration/v1/exchangeRates
ProductionGEThttps://api.allianz-trade.com/turnover-declaration/v1/exchangeRates 

You can filter results using the following query parameters:

FieldDescription
currencyInCodeOrigin currency (e.g. USD)
currencyOutCodesTarget currencies — use your declarationCurrencyCode (e.g. EUR)
referenceDateReference date for the rate

 

Example request
GET /exchangeRates?currencyInCode=USD&currencyOutCode=EUR&referenceDate=2024-12-31
Example response
[
    {
        "currencyInCode": "USD",
        "currencyOutCode": "EUR",
        "exchangeRateTypeCode": "1002",
        "rate": "0.95537445901921",
        "inverseRate": "1.04671000000000",
        "referenceDate": "2024-12-31"
    }
]

Body response:

FieldDescription
currencyInCodeOrigin currency (e.g. USD)
currencyOutCodeTarget currency (e.g. EUR)
exchangeRateTypeCodeRate type. 1002 for WM/Reuters monthly average rate
rateExchange rate value (14 decimals, 5 significant)
inverseRateInverse of the rate
referenceDateReference date for the rate

Use the rate to convert your amounts into the declarationCurrencyCode before populating the insurableAmount fields in the next steps.

4. Submit a declaration

Once you have your declarationId and converted amounts, submit your declaration via POST.

ONLY for declarations with declarationStatusCode:"TODO"

Declarations with declarationStatusCode:"DRAFT" can only be amended/submitted via PUT endpoint.

EnvironmentMethodURL
TestPOSThttps://api-services.uat.1placedessaisons.com/uatm/turnover-declaration/v1/declarations/{declarationId}/submissions
ProductionPOSThttps://api.allianz-trade.com/turnover-declaration/v1/declarations/{declarationId}/submissions 

Set isDraft: true to save as a draft, or isDraft: false to finalize and submit. 

A submission isDraft: false definitely submitted and can not be amended later on. The declaration will get declarationStatusCode:"DONE". 

A submission isDraft: true can be amended later on and definitely submitted via PUT endpoint. The declaration will get declarationStatusCode:"DRAFT". 

 

The breakdownDetailCode depends on your policy's declarationBreakdownTypeCode:

  • BLENDED → BLR (Total Insurable Amount)
  • DOMEXP → DOM (Domestic) + EXP (Export)
  • COUNTRY → ISO country code per country (get your covered countries list from Policy Management API). You don't need to fill all countries, just the countries with a declared amount > 0. The API will set all other countries with insurableAmount as 0.
  • OTHER → BLR
 
Example body request for COUNTRY
{
  "globalUninsuredAmount": 1800,
  "isDraft": true,
  "submissionPolicy": {
    "businessUnitCode": "SFAC",
    "policyId": "P00000001",
    "extensionId": "00001",
    "submissionDetails": [
      { "breakdownDetailCode": "FR", "insurableAmount": 18000},
      { "breakdownDetailCode": "SK", "insurableAmount": 3000},
    ]
  }
}
Example body response for COUNTRY
{
    "submissionId": "001234567",
    "isDraft": true,
    "globalUninsuredAmount": 1800,
    "submissionPolicy": {
        "businessUnitCode": "SFAC",
        "policyId": "P00000001",
        "extensionId": "00001"
        "submissionDetails": [
            {
                "breakdownDetailCode": "AD",
                "insurableAmount": 0,
                "isInsurableIndirectExport": false,
                "insurableIndirectExportAmount": 0
            },
            ................;
            {
                "breakdownDetailCode": "FR",
                "insurableAmount": 18000,
                "isInsurableIndirectExport": false,
                "insurableIndirectExportAmount": 0
            },
            ............
            {
                "breakdownDetailCode": "SK",
                "insurableAmount": 3000,
                "isInsurableIndirectExport": false,
                "insurableIndirectExportAmount": 0
            },
            ........;
        ],
    },
    "receivedDateTime": "2026-07-15T07:15:15.337000Z",
    "updateDateTime": "2026-07-15T07:15:15.350000Z"
}

 

Example body request for BLENDED or OTHER
{
  "globalUninsuredAmount": 1800,
  "isDraft": true,
  "submissionPolicy": {
    "businessUnitCode": "SFAC",
    "policyId": "P00000001",
    "extensionId": "00001",
    "submissionDetails": [
      { "breakdownDetailCode": "BLR", "insurableAmount": 18000}
    ]
  }
}
Example body response for BLENDED or OTHER
{
    "submissionId": "001234567",
    "isDraft": true,
    "globalUninsuredAmount": 1800,
    "submissionPolicy": {
        "businessUnitCode": "SFAC",
        "policyId": "P00000001",
        "extensionId": "00001"
        "submissionDetails": [
            {
                "breakdownDetailCode": "BLR",
                "insurableAmount": 18000,
                "isInsurableIndirectExport": false,
                "insurableIndirectExportAmount": 0
            }
        ],
    },
    "receivedDateTime": "2026-07-15T07:15:15.337000Z",
    "updateDateTime": "2026-07-15T07:15:15.350000Z"
}

 

Example body request for DOMEXP
{
  "globalUninsuredAmount": 1800,
  "isDraft": true,
  "submissionPolicy": {
    "businessUnitCode": "SFAC",
    "policyId": "P00000001",
    "extensionId": "00001",
    "submissionDetails": [
      { "breakdownDetailCode": "DOM", "insurableAmount": 60000},
      { "breakdownDetailCode": "EXP", "insurableAmount": 40000}
    ]
  }
}
Example body response for BLENDED
{
    "submissionId": "001234567",
    "isDraft": true,
    "globalUninsuredAmount": 1800,
    "submissionPolicy": {
        "businessUnitCode": "SFAC",
        "policyId": "P00000001",
        "extensionId": "00001"
        "submissionDetails": [
            {
                "breakdownDetailCode": "DOM",
                "insurableAmount": 60000,
                "isInsurableIndirectExport": false,
                "insurableIndirectExportAmount": 0
            },
            {
                "breakdownDetailCode": "EXP",
                "insurableAmount": 40000,
                "isInsurableIndirectExport": false,
                "insurableIndirectExportAmount": 0
            }
        ],
    },
    "receivedDateTime": "2026-07-15T07:15:15.337000Z",
    "updateDateTime": "2026-07-15T07:15:15.350000Z"
}

 

Note

Fields isInsurableIndirectExport and isInsurableIndirectExport  are applicable only to UK policyholders and the UK country.

5. Update a draft declaration

If you saved a declaration as a draft (isDraft: true), use a PUT call to update amounts or finalize it before the submissionDueDate.

ONLY for declarations with declarationStatusCode:"DRAFT"

EnvironmentMethodURL
TestPUThttps://api-services.uat.1placedessaisons.com/uatm/turnover-declaration/v1/declarations/{declarationId}/submissions/{submissionId}
ProductionPUThttps://api.allianz-trade.com/turnover-declaration/v1/declarations/{declarationId}/submissions/{submissionId}

The PUT fully overwrite your draft.

As for POST:

Set isDraft: true to keep saving as a draft, or isDraft: false to finalize and submit. 

A submission isDraft: true  is definitely submitted and can not be amended later on. The declaration will get declarationStatusCode:"DONE". 

A submission isDraft: true can be amended later on and definitely submitted via PUT endpoint. The declaration will keep declarationStatusCode:"DRAFT". 

6. Attach a document to a declaration

EnvironmentMethodURL
TestPOSThttps://api-services.uat.1placedessaisons.com/uatm/turnover-declaration/v1/declarations/{declarationId}/documents
ProductionPOSThttps://api.allianz-trade.com/turnover-declaration/v1/declarations/{declarationId}/documents

The response returns a presigned URL to upload the file directly to secure storage via a PUT request.

 

Example request

{
  "fileName": "My_document.pdf"
}

 

Example response

{
    "fileName": "My_document.pdf",
    "fileUrl": "https://mypresigneURLtouploadFile"
}

 

Use fileUrl with PUT to upload your file as binary file.

To retrieve the list of documents attached to a declaration, use GET /declarations/{declarationId}/submissions/{submissionId} endpoint.

7. View the details of a submission

See submission details for a DONE or DRAFT declaration.

EnvironmentMethodURL
TestGEThttps://api-services.uat.1placedessaisons.com/uatm/turnover-declaration/v1/declarations/{declarationId}/submissions/{submissionId}
ProductionGEThttps://api.allianz-trade.com/turnover-declaration/v1/declarations/{declarationId}/submissions/{submissionId}

Replace {declarationId} and {submissionId} with the declarationId from step 2 (GET /declarations).

 

Example request

GET /declarations/001234567/submissions/001234567

Example response

{
    "submissionId": "001234567",
    "isDraft": true,
    "globalUninsuredAmount": 1800,
    "submissionPolicy": {
        "businessUnitCode": "SFAC",
        "policyId": "P00000001",
        "extensionId": "00001"
        "submissionDetails": [
            {
                "breakdownDetailCode": "AD",
                "insurableAmount": 0,
                "isInsurableIndirectExport": false,
                "insurableIndirectExportAmount": 0
            },
            ................;
            {
                "breakdownDetailCode": "FR",
                "insurableAmount": 18000,
                "isInsurableIndirectExport": false,
                "insurableIndirectExportAmount": 0
            },
            ............
            {
                "breakdownDetailCode": "SK",
                "insurableAmount": 3000,
                "isInsurableIndirectExport": false,
                "insurableIndirectExportAmount": 0
            },
            ........;
        ],
    },
    "receivedDateTime": "2026-07-15T07:15:15.337000Z",
    "updateDateTime": "2026-07-15T07:15:15.350000Z",
    "documents": [
        {
            "documentId": "00xxxx5",
            "fileName": "My_document.pdf",
    		"fileUrl": "https://documentURL"
        }
    ]
}

Note

fileURL is a URL allowing to generate and get a presigned URL. The generated presigned URL will allow to download the file.