DEPRECATED: V2 CrefoTrust API

The API documentation of CrefoTrust in version 2

1) First things first

To integrate with CrefoTrust you need to get login information: a verifier ID as well as an API key. To get those, please contact: support@crefotrust.de.

2) Placing Orders

The process starts with placing an order with the CrefoTrust order service. To do this you call the API endpoint: /orders with the POST method.

We have different environments with different URLs. For development and integration purposes use:

https://api-demo.crefotrust.de/api/orders

For production use:

https://api.crefotrust.de/api/orders

CAUTION: you should make that call from your backend code, otherwise the login information might get extracted, and potentially abused.

2a) Auth

To authenticate with the CrefoTrust order service, place the API key which you received in step one into the request header under the header key: x-crefotrust-key.

2b) Request Body

Provide the required information in the request body:

Verifier ID - key: verifierId

The verifier ID is used to identify you and your orders in the CrefoTrust system. It will be provided to you by support@crefotruts.de.

Required Credentials - key: requiredCredentials

An object representing the information that you require from your customer to continue in your business process (all currently available credentials are listed in point 5)

For Org [OPTIONAL] - key: forOrg

An optional object with two properties: crefoId, and mandatory. You can use it to predefine the company for which the person should be verified as an representative. When you set mandatory to false (the default), the company will be preselected, but the user can select a different company. true will fix the company to the preselected option.

To get the CrefoID (Crefonummer) for a company you might want to use the SSU API. Please contact support@crefotrust.de for an inquiry.

For Person [OPTIONAL] - key: forPerson

An optional object with two properties: crefoId, and mandatory. You can use it to predefine the person whose identity you want to get verified.

ATTENTION: This property is only allowed when used in conjunction with forOrg.

Mandatory set to false (the default) will preselect the person in the list of authorized representatives, but the user can change it. Mandatory true will skip the selection page altogether, since it implies forOrg.mandatory set to true as well.

Accepted ID Methods [OPTIONAL] - key: acceptedIdMethods

An array of strings where you can define which identification providers and methods you are accepting. You have to at least accept all offeredIdMethods (see below).

This property is an optional parameter in the order request. In case it’s not provided (completely missing key) itm_videoident is assumed to be the only accepted method.

Setting this property but not providing valid information will result in an error response, and the order being rejected. See 2c Response for details.

Offered ID Methods [OPTIONAL] - key: offeredIdMethods

An array of strings where you can define which identification providers and methods the user will be able to choose from, in the context of your order. The offeredIdMethods array must include all values from acceptedIdMethods.

If you don’t specify this property (completely missing key) itm_videoident will be the only offered ID method.

Setting this property but not providing valid information will result in an error response, and the order being rejected. See 2c Response for details.

Webhook address - key: webhook

With this property you can define where the data will be sent as soon as it’s available, the orderId will be attached, e.g.: “https://your.backend.service/customerdata/[orderId]”

Redirect URLs - key: redirect

An object with two properties: success and failure. These are the URLs your customer will be sent after they finish the CrefoTrust process (both negative and positive case). Similar to the webhook, the orderID will be attached at the end of the provided URLs.

Options [OPTIONAL] - key: options

An object with one property: verifierName.

This currently allows you to customize the name that will be displayed to the customer when she consents to present you with her credentials.

Here is an example

{
  "verifierId": "[THE_VERIFIER_ID_GIVEN_TO_YOU]",
  "requiredCredentials": {
    "person": ["name", "address"],
    "org": ["legalName"]
    //see below for full list
  },
  // --- OPTIONAL START ---
  "forOrg": {
    "crefoId": "1231234567",
    "mandatory": "false"
  },
  "forPerson": {
    "crefoId": "1237654321",
    "mandatory": "false"
  },
  "acceptedIdMethods": ["itm_videoident", "nect_autoident"],
  "offeredIdMethods": ["itm_videoident", "nect_autoident"],
  "options": {
    //provide your name
    "verifierName": "[YOUR_BRAND]"
  },
  // --- OPTIONAL END ---
  "webhook": "https://your.backend.service/customerdata",
  "redirect": {
    "success": "https://your.frontend.after.process.succeeded",
    "failure": "https://your.frontend.after.process.failed"
  }
}

2c) Response

SUCCESS

When the order is successfully placed the request responds with an orderId and a URL to which your customer needs to get forwarded to, to start the CrefoTrust process for that customer and that order.

{
  "orderId": "[SOME_UUID]",
  "url": "https://crefotrust.de/[SOME_UUID]"
}

You can do this client side, e.g. via an anchor tag or a button. Or you might want to redirect directly from your server.

ERROR CASES

404 - Not Found

You most probably are using the wrong URL. For the production environment remember to leave out the -stage part of the URL. e.g.: https://api.crefotrust.de (instead of https://api-prod.crefotrust.de)

401 - Authentication Error

This might happen if you don’t have an API key yet or it became invalid. Your VerifierID might be wrong as well. Please contact support@crefotrust.de to validate, that you have the correct information.

400 - Bad Request

This error happens if your order request’s body is malformed (not a valid json document), it’s incomplete (missing mandatory fields) or violates a business constraint (wrong ID method options, requiring a person but not an org, …). The returned response body (plain text) might be helpful to further narrow down the problem.

Here are a few possible problems to look out for:

  • Make sure that you only provide valid identification methods
  • Make sure that you accept all ID methods that you offer
  • Make sure that when you preselect a person, the company needs to be preselected as well. It’s further necessary that the person actually is an authorized representative of the preselected company.

2d) Redirect URLs

In case it turns out, that your customer is unable to provide all the information that you require, the customer is redirected to your “failure” redirect URL.

In case the customer has successfully acquired all information and is willing to present them to you, she will be redirected to your “success” redirect URL.

In either case, the URL will be expanded with an oderId query parameter, so that you can relate the outcome of the CrefoTrust process with the order that initiated it:

https://your.frontend.com/success.html?orderId=[ORDER_ID]

2e) Identification Methods

Currently only two identification methods of two different ID providers can be used with CrefoTrust. These are:

IDNow / ITM - Video Ident:

Identified by: itm_videoident

More information can be found here.

Nect - Auto Ident

Identified by: nect_autoident

More information can be found here.

3) Webhook Request

After finishing the CrefoTrust process - and consenting to present the information to you - your webhook is called, with the HTTP POST method. The request body is JSON encoded and contains the orderId from step 2c as well as the requested information about your customer.

Additionally, the orderId will be attached to the path of your webhook. Like so:

https://your.webhook.com/ordersIncoming/[ORDER_ID]

Here is an example of a request body send to the webhook:

{
  "orderId": "[THE_ORDER_ID_FROM_2c]",
  "person": {
    "name": {
      "givenName": "Alexa",
      "familyName": "Musterfrau"
    },
    "address": {
      "streetAddress": "Goethestraße 45",
      "postalCode": "41333",
      "addressLocality": "Bochum",
      "addressCountry": "Deutschland"
    }
  },
  "org": {
    "legalName": "BetterBrot GmbH"
  }
}

(all options and their structure are in 4)

4) Getting Orders

To get the current state of a previously successfully placed order, you issue an GET request against the /orders/[ORDER_ID] endpoint.

4a) Auth

You have to submit your API key in the header x-crefotrust-key, like you did when placing the order.

4b) Request

The request itself is a simple GET call to the /orders/[ORDER_ID] endpoint. With an empty body. Your verifier ID will be deferred from the order ID.

4c) Response

You will receive the current state of the order in the response body, json encoded. The structure, pretty many analogues to the POST order request, is as follows.

{
  "orderId": "[THE_ORDER_ID]",
  "verifierId": "[THE_VERIFIER_ID_GIVEN_TO_YOU]",
  "requiredCredentials": {
    "person": ["name", "address"],
    "org": ["legalName", "address"]
  },
  "webhook": "https://your.backend.service/customerdata",
  "redirect": {
    "success": "https://your.frontend.after.process.succeeded",
    "failure": "https://your.frontend.after.process.failed"
  },
  "options": {
    "verifierName": "[YOUR BRAND]"
  },
  "state": [
    {
      "code": 0,
      "timestamp": "2021-03-04T19:33:01.002Z",
      "comment": "order created"
    },
    {
      "code": 2,
      "timestamp": "2021-03-04T19:33:02.102Z",
      "comment": "logged in"
    }
    //see full list of states below
  ]
}

4d) Order States (Status)

The states in the state history are not guaranteed to be ordered in any way. You can’t defer the order from their code, also. If you need a chronological order of states, you might want to sort the array by timestamp.

Not all states have to be present in the order state history. For example the Account Created state will only show up when your customer registers with CrefoTrust for the first time.

States are not unique. When your customer first logs in via a web browser, but later decides to finish the process via smartphone, there will be two distinct logged-in events; and therefore states, that show up in the state history.

Every state has a timestamp, which is a RFC3339 timestamp string at Zulu time.

If a state represents an error or failure case it has an additional field named error, giving some details about the situation; so that you might be able to solve the issue. These error states have a code greater than 100.

0 - Order Created

Every successfully placed order has this state exactly once in its state history.

{
  "code": 0,
  "timestamp": "2021-08-06T12:23:45.156Z",
  "comment": "order created"
}

1 - Account Created

The customer has successfully created an CrefoTrust account. This state exists only once, for every CrefoTrust user account. And naturally will be missing in subsequent orders.

{
  "code": 1,
  "timestamp": "2021-08-06T12:24:25.256Z",
  "comment": "account created"
}

2 - Logged In

The customer has successfully logged into her CrefoTrust account. This state can exist multiple times even for a single order.

{
  "code": 2,
  "timestamp": "2021-08-06T12:24:25.256Z",
  "comment": "logged in"
}

3 - Request Created

The customer has successfully initiated a request to get her identity verified by our identification partner.

The request with our identification partner has a limited lifespan and will be deleted after 14 days. If an order is not progressing past this state, it will be deleted after 14 days as well.

When the customer is unable to successfully complete the identification process for whatever reason, this state will not be left, until the order times out.

{
  "code": 3,
  "timestamp": "2021-08-06T12:24:25.256Z",
  "comment": "request created"
}

4 - Person Verified

When the customer successfully finishes, the identification process this state is set. In the default case, this state can only be reached once per user account. In edge cases, for example, when the user changes her name, the identification process has to be done again. So, this state and the prior state are not guaranteed to be unique per user account (probably even not unique per order).

{
  "code": 4,
  "timestamp": "2021-08-06T12:24:25.256Z",
  "comment": "person verified"
}

5 - Person is Authorized Representative

When your customer data collected during the identification process matches the data of the company representative she selected, this state will be set.

{
  "code": 5,
  "timestamp": "2021-08-06T12:24:25.256Z",
  "comment": "person is authorized representative"
}

6 - Data Sent

When your webhook could be reached and responded with a 200 HTTP code upon sending the requested information, the Data Sent state will be reached, which also marks the successful end of the process. No further states should be expected.

{
  "code": 6,
  "timestamp": "2021-08-06T12:24:25.256Z",
  "comment": "data sent"
}

101 - Order Timed Out

When the customer didn’t proceed with the order for more than 14 days, the order will be (soft) deleted and the final state Timed Out will be reached.

{
  "code": 101,
  "timestamp": "2021-08-06T12:24:25.256Z",
  "comment": "timed out",
  "error": "customer didn't proceed for 14 days"
}

Next step: if this case happens, it’s probably advisable to contact your customer and ask for details (if this is appropriate in your business context).

102 - Delivery Error

When CrefoTrust is unable to connect to your webhook or when your webhook responds with a something other than the 200 HTTP code, then this state will be set.

{
  "code": 102,
  "timestamp": "2021-08-06T12:24:25.256Z",
  "comment": "delivery error",
  "error": "received: 500 - Internal Server Error"
}

Next step: When this happens please verify that your webhook is working correctly and can be accessed from the outside of your network. A common gotcha might be a self-signed certificate. In case you need to update the webhook, you need to place a new order with CrefoTrust, contact your customer and ask her to send the data again. If the webhook is correct and there was a temporary outage, the customer can pickup the old order and try to send the data again.

103 - Process Canceled

When the customer actively cancels (for whatever reason) the CrefoTrust process at any time, this state will be set. This can happen multiple times. As a result the order remains open (until it times out after 14 days) and the customer might pick up the CrefoTrust process later, using the initial link (including the OrderID).

{
  "code": 103,
  "timestamp": "2021-08-06T12:24:25.256Z",
  "comment": "process canceled",
  "error": "customer actively canceled the process"
}

Next step: This usually happens when the customer realizes she is not listed as a representative. Or eventually when she feels uncomfortable sharing the information that is requested. Active user research is underway to pinpoint reasons for cancelling the process. No action is required from your side.

5) Available Credentials

The data points you receive have different origins. Regarding personal data, this depends on the identification methods used to collect those data and the ID methods you accept in your order.

In case you don’t specify any acceptedIdMethods itm_videoident is currently the only source of personal data.

If you don’t narrow down the accepted identification methods (by explicitly specifying nect_autoident and itm_videoident in the acceptedIdMethods of your order) the most recent credential, regardless of source will be submitted.

5a) Person

Name

An object with the full name of that person, according to the ID document presented during the CrefoTrust process.

Post Order Data

You signal that you require this credential via:

{
  //...
  "requiredCredentials": {
    "person": ["name"]
  }
  //...
}

Webhook Request Data

And will get the data delivered to your webhook as:

{
  //...
  "person": {
    "name": {
      "familyName": "Musterfrau",
      "givenName": "Alexa"
    }
  }
  //...
}

Address

An object with the postal address of that person, according to the ID document presented during the CrefoTrust process.

When the user presented a passport during the identification process (which actually doesn’t contain an address) the values for address will depend upon the identification method used.

As part of the ITM Video Ident process the user will be asked to provide her address by other means. This encompasses usually a utility bill from a local provider (gas, electricity, water, landline, …).

In case of Nect Auto Ident the address will not be available as a credential, when the user identifies herself with a passport.

Post Order Data

You signal that you require this credential via:

{
  //...
  "requiredCredentials": {
    "person": ["address"]
  }
  //...
}

Webhook Request Data

And will get the data delivered to your webhook as:

{
  //...
  "person": {
    "address": {
      "streetAddress": "Goethestraße 45",
      "postalCode": "43113",
      "addressLocality": "Bochum",
      "addressCountry": "Deutschland"
    }
  }
  //...
}

Birthdate

A string with the person’s birthdate, according to the ID document presented during the CrefoTrust process.

Post Order Data

You signal that you require this credential via:

{
  //...
  "requiredCredentials": {
    "person": ["birthdate"]
  }
  //...
}

Webhook Request Data

And will get the data delivered to your webhook as:

{
  "person": {
    "birthdate": "DD.MM.YYYY"
  }
}

(when parsing with moment.js)

CrefoId

A string with the person’s Crefonummer (an identifier used by Creditreform).

Post Order Data

You signal that you require this credential via:

{
  //...
  "requiredCredentials": {
    "person": ["crefoId"]
  }
  //...
}

Webhook Request Data

And will get the data delivered to your webhook as:

{
  //...
  "person": {
    "crefoId": "2010034122"
  }
  //...
}

Nationality

A string with the person’s nationality (short country code in caps), according to the ID document presented during the CrefoTrust process, e.g.:

Post Order Data

You signal that you require this credential via:

{
  //...
  "requiredCredentials": {
    "person": ["nationality"]
  }
  //...
}

Webhook Request Data

And will get the data delivered to your webhook as:

{
  //...
  "person": {
    "nationality": "DE"
  }
  //...
}

5b) Org

Address

An object with the postal address of the company, according to the information that Creditreform has researched.

Post Order Data

You signal that you require this credential via:

{
  //...
  "requiredCredentials": {
    "org": ["address"]
  }
  //...
}

Webhook Request Data

And will get the data delivered to your webhook as:

{
  //...
  "org": {
    "address": {
      "streetAddress": "Schillerstraße 22",
      "postalCode": "31333",
      "addressLocality": "Bielefeld",
      "addressCountry": "Deutschland"
    }
  }
  //...
}

LegalForm

A string with the company’s legal form. Typical values would be:

  • “GmbH”
  • “AG”
  • “UG haftungsbeschränkt”
  • …

Post Order Data

You signal that you require this credential via:

{
  //...
  "requiredCredentials": {
    "org": ["legalForm"]
  }
  //...
}

Webhook Request Data

And will get the data delivered to your webhook as:

{
  //...
  "org": {
    "legalForm": "GmbH"
  }
  //...
}

LegalName

A string with the company’s legal name.

Post Order Data

You signal that you require this credential via:

{
  //...
  "requiredCredentials": {
    "org": ["legalName"]
  }
  //...
}

Webhook Request Data

And will get the data delivered to your webhook as:

{
  //...
  "org": {
    "legalName": "BetterBrot GmbH"
  }
  //...
}

CrefoId

A string with the company’s Crefonummer (an identifier used by Creditreform).

Post Order Data

You signal that you require this credential via:

{
  //...
  "requiredCredentials": {
    "org": ["crefoId"]
  }
  //...
}

Webhook Request Data

And will get the data delivered to your webhook as:

{
  //...
  "org": {
    "crefoId": "2051200045"
  }
  //...
}