Skip to main content

Getting started

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!

 

About us

We are the global leader in trade credit insurance and a recognised specialist in the areas of surety, collections, structured trade credit and political risk.

bottom_nav_picture

We are Allianz. We are here to make insurance simple for you.