Introduction
Dear Customer,
Welcome to the Allianz Trade API world! We are excited to help you digitalize our data exchange through APIs, and boost your trade credit insurance (TCI) to next level. Once you have integrated our APIs, you will be able to manage your credit limit request or cover requests from your ERP and monitor your limits or covers through automated processes, reducing your effort and time spent.
Before you begin your integration, please be aware that Allianz Trade API does not have access to any of your underlying data and does not pull any information from your systems. Allianz Trade API is designed to only receive the information you push to it, and to send data as per your requests, that is out of respect for the privacy of your company’s data.
This document has been prepared to facilitate your integration. For a comprehensive list of Allianz Trade API suite, please refer to the Allianz Trade API catalog.
Your first API calls
Prerequisites
Allianz TradeAPI is using the OAUTH2 protocol as a secure authentication layer with each call. Be sure you have generated your own private API key before completing this tutorial (you can generate your test API key here).
We recommend you to test our REST APIs with tools like Postman, Insomnia or HTTPie, you can download our OpenAPI (Swagger) collections from this Portal and import them into such tools.
Obtain your OAUTH2 token
To obtain your OAUTH2 token, valid during 60 minutes, please use the following endpoints:
Test:
POST https://api-services.uat.1placedessaisons.com/uatm/v1/idp/oauth2/authorize
Production:
POST https://api.allianz-trade.com/v1/idp/oauth2/authorize
Headers:
Content-Type: application/json
Body:
{
"apiKey": "YOUR_API_KEY"
}
In response you have:
200 OK
{
"access_token": "YOUR_ACCESS_TOKEN",
"token_type": "Bearer",
"expires_in": 3600
}
As indicated by the expires_in property in the response, OAUTH2 tokens are valid for a one hour timespan. If your token is expired, you can't renew it and need to get another valid token by calling this endpoint again.
Now that you have obtained your OAUTH2 access token, you can proceed with the rest of this tutorial.
Search for a Company
Companies are indexed in our database with a unique identifier called the CompanyId. If you don't know this information yet, you may use the Company Search API in order to find this identifier. Let's see an example:
Test:
POST https://api-services.uat.1placedessaisons.com/search/uatm-v2/companies/advancedSearch
Production:
POST https://api.allianz-trade.com/search/v2/companies/advancedSearch
Headers:
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
Body:
{
"companyName": "SOME_COMPANY_NAME",
"countryCode": "FR",
"pageSize": 1
}
More fields are available for company searches. Please refer to the Company Search API documentation for more information.
Response:
200 OK
{
"results": [
{
"company": {
"communicationChannels": [],
"employeesData": {
"minNumber": 0,
"maxNumber": 0
},
"financialData": {
"shareCapitalAmount": 100,
"currencyCode": "EUR"
},
"groupLinks": [],
"companyId": "123456789",
"address": {
"streetNumber": "1",
"streetName": "RUE PASCAL",
"postCodes": [
{
"postCodeTypeCode": "POSTCODE",
"postCodeValue": "75001"
}
],
"town": "PARIS 1",
"subdivisionCode": "75",
"countryCode": "FR"
},
"legalData": {
"companyName": "SOME_COMPANY_NAME",
"secondaryNames": [],
"creationDate": "2008-06-26",
"businessStartDate": "2008-06-26",
"companyStatusCode": "A",
"companyTypeCode": "C",
"legalFormCode": "SCIM",
"tradeSectors": [
{
"nomenclatureCode": "NAF",
"tradeSectorCode": "6820B",
"isMainTradeSector": true
}
],
"languageCode": "FR",
"isPublicCompany": false,
"isDataProtected": false
},
"companyIdentifiers": [
{
"priorityNumber": 1,
"isNationalIdentifier": true,
"idTypeCode": "SIREN",
"idValue": "0123456789"
},
]
},
"score": 1.0,
"sources": [
"ES"
],
"isHeadQuarterMatched": true,
"isBranchMatched": false
}
],
"providerProblems": [],
"displayedSize": 1,
"requestedSize": 10
}
As you can see, the Company Search API can return more than one results. The score property indicates the relevancy of the entry and may vary between 0 and 1, 1 means the highest relevancy.
You can now use the CompanyId in all your subsequent API calls.
Request a Cover
⚠️ The cover request process may depend regarding on your policies. For the sake of clarity, we will here use the generic Cover resource but you may be interested in the GradeBasedCover (which handles the DLR process) or the GradeRequest (for GI/GR).
1. Obtain a job-url
Test:
POST https://api-services.uat.1placedessaisons.com/uatm/riskinfo/v2/covers
Production:
POST https://api.eulerhermes.com/riskinfo/v2/covers
Headers:
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
Body:
{
"coverTypeCode": "CreditLimit",
"requestOrigin": "ExternalPlatform",
"requestData": {
"amount": 30000,
"currencyCode": "EUR",
"companyId": "0123456789"
},
"policy": {
"policyId": "0123456789",
"extensionId": "001",
"businessUnitCode": "SFAC"
}
}
Response:
202 Accepted
job-url: SOME_UNIQUE_JOB_URL
Because cover requests processing may need additional treatment that causes delay in the response, applying for a cover request won't give you an immediate response but you will obtain instead a job-url header. You may then poll this url to track the request treatment status.
2. Track the cover request treatment status
Test:
GET https://api-services.uat.1placedessaisons.com/uatm/riskinfo/v2/jobs/YOUR_JOB_ID
Production:
GET https://api.allianz-trade.com/riskinfo/v2/jobs/YOUR_JOB_ID
Headers:
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
Response:
200 OK
{
"jobStatusCode": "PROCESSED",
"resourceUrl": SOME_RESSOURCE_URL
}
Where SOME_RESSOURCE_URL will have the following form: https://{DOMAIN}/riskinfo/v2/covers/{COVER_ID}
3. Get the cover request response
Test:
GET https://api-services.uat.1placedessaisons.com/uatm/riskinfo/v2/covers/{COVER_ID}
Production:
GET https://api.allianz-trade.com/riskinfo/v2/covers/{COVER_ID}
Headers:
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN
Response:
200 OK
{
"coverId": "LIM0123456789",
"coverStatusCode": "Accepted",
"coverTypeCode": "CreditLimit",
"isStrategic": false,
"coverLastUpdateDate": "2021-07-02",
"request": {
"coverRequestId": "0123456789",
"requestDate": "2021-07-02",
"requestedAmount": 30000,
"requestedCurrencyCode": "EUR",
"requestOrigin": "MyEH",
"customerCompanyReference": "A600EV2J"
},
"decision": {
"coverLimitId": "0123456789",
"decisionDate": "2021-07-02",
"permanent": {
"permanentAmount": 30000,
"permanentStartDate": "2021-07-02"
},
"currencyCode": "EUR",
"isCurrent": true,
"hasConditions": false,
"customerCompanyReference": "A600EV2J"
},
"policy": {
"businessUnitCode": "SFAC",
"policyId": "0123456789",
"extensionId": "001"
},
"company": {
"companyId": "0123456789",
"companyName": "SOME_COMPANY_ID"
}
}
Numerous variations of this response data could be returned depending to the treatment of the request. For a detailed explanation of every cases, please refer to the Info Risk API reference documentation.
Next steps
We hope this brief overview will help you to kickstart your journey with Allianz Trade API. As a next step, we advise you to check our API catalogue where you could find all our OpenAPI references. For any inquiries or question, feel free to contact our experts at api@allianz-trade.com. We'd be happy to help!