Introduction
Welcome to the Allianz Trade API. We are excited to help you take your credit insurance policy to the next level. Allianz Trade API enables Allianz Trade credit insurance solutions to be integrated into your company’s systems and automated processes.
The following tutorial has been designed to give you a first glance over the EH API possibilities. For a comprehensive list of Allianz Trade API endpoints, 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 every call. Be sure you have generated your own private API key before completing this tutorial (you can generate a production key here but we do recommend you to test with our sandbox environment first of all).
Furthermore, a REST API testing application, such as Postman, Insomnia or HTTPie will prove itself very convenient as we will provide you with REST OpenAI (Swagger) collections you can import into such tools.
Obtain your OAUTH2 token
To obtain your OAUTH2 token, use the following endpoint:
Sandbox:
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"
}
Which will give you in response:
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:
Sandbox:
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 a custom 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.
You can now use the CompanyId to identify the company 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
Sandbox:
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
Sandbox:
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
Sandbox:
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 catalog where you could find all our OpenAPI references. And of course, for any inquiries or question, feel free to contact us directly at api@allianz-trade.com. We'd be happy to help!
