V3 CrefoTrust API

The API documentation of CrefoTrust in version 3

1) First things first

To integrate with CrefoTrust you need to get authentication information: a verifier ID and an API key. To acquire 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 call the API only from your backend, 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 by the CrefoTrust team into the request header under the header key: x-crefotrust-key. Futhermore you have to provider your verifier id for each request. You can either do so by adding the custom header x-verifier-id to your requests or by adding it in the body, see 3) for details. Please bear in mind that the latter option is deprecated and will be removed in future releases.

2b) Request Body

With the request body you define the details of the order. This can be (and usually is) different for every instance of your business process.

Here is an example:

{
  "requiredCredentials": {
    "person": ["name", "nationality", "birthdate"],
    "authorizedRepresentative": true,
    "org": ["legalName", "address"]
  },
  "webhook": "https://api.my-backend-system.de/webhook",
  "redirect": {
    "success": "https://www.my-frontend.de/success.html",
    "failure": "https://www.my-frontend.de/error.html"
  },
  "options": {
    "verifierName": "My Brand Name",
    "verifierRef": {
      "referenceId": "my_reference_id",
      "correlationId": "my_correlation_id",
      "userId": "my_user_id"
    }
  },
  "acceptedIdMethods": ["itm_videoident", "nect_autoident"],
  "offeredIdMethods": ["itm_videoident"],
  "forOrg": {
    "mandatory": true,
    "crefoId": "8170295838"
  },
  "forPerson": {
    "mandatory": true,
    "crefoId": "8170295838"
  }
}

Required Credentials (key: requiredCredentials)

Here you define which information you require from your customer in order to continue in your business process (all currently available credentials are listed under point 5). The credentials are grouped by person and org. Furthermore you can request the “authorizedRepresentative” credential on the root level, making the relationship between person and org explicit. Subsequent relationships will be implemented in the future.

Webhook Address (key: webhook)

You define where the data will be sent as soon as it’s available, the orderID will be attached as a path element, e.g.: “https://api.my-backend-system.de/webhook/[orderID]”

Redirect URLs (key: redirect)

Provide an object with the URLs your customer will be sent after they finish the CrefoTrust process. One for the negative (failure) and and one for the positive (success) case.

Similar to the webhook, the orderID will be attached at the end of the provided URLs (as an URL parameter with the name orderId), e.g.: https://www.my-frontend.de/success.html?orderId=[orderID] and https://www.my-frontend.de/error.html?orderId=[orderID].

Verifier Options (key: options) [OPTIONAL]

With verifierName you may customize the name that will be displayed to the customer in the CrefoTrust frontend during the verification process.

With verifierRef you can provide your own IDs (for example a userID or correlationID) that will be sent back unaltered as part of the webhook request meta data.

The following limitations will be enforced:

maximum number of elements: 10
maximum string length: 1024
strings only

Accepted ID Methods (key: acceptedIdMethods) [OPTIONAL]

Here you can define which of the possible identification methods you do accept as part of your business process. Currently we are supporting Video Ident by IdNow (originally ITM) and Auto Ident by Nect.

To be backwards compatible, the default is set to Video Ident only. To enable Auto Ident which doesn’t involve an agent, add “nect_autoident” to the array of accepted ID methods, e.g.:

{
  ...
  acceptedIdMethods: ["nect_autoident", "itm_videoident"]
  ...
}

The ordering is not relevant.

If your customer already is a registered and identified CrefoTrust user acceptedIdMethods decides, if the identification process the customer has already successfully partaken in, is acceptable for you; or if she has to go through another one.

Offered ID Methods (key: offeredIdMethods) [OPTIONAL]

Here you can define which of the possible identification methods you do offer your customers as part of your business process.

The same options and rules as with accepted ID methods apply here.

Offered ID methods becomes relevant when the customer is new for CrefoTrust. So here you decide which of the available ID methods the customer can choose from while going through the CrefoTrust process.

Monetary considerations might play a role here, since the different ID methods usually inflict different costs (depending on your contract).

Preset Organization (key: forOrg) [OPTIONAL]

Here you can define which company will be preselected in CrefoTrust. Either unchangeable for the user (“mandatory”: true) or preselected but editable.

In order to use this option you need the Crefonummer for the company in question. If you don’t know what that is or how to get it, please get in touch with us (support@crefotrust.de).

Preset Person (key: forPerson) [OPTIONAL]

Here you can define which person will be preselected in CrefoTrust. This works only in conjunction with forOrg. It can be defined as unchangeable for the user (“mandatory”: true) or preselected but editable. If forPerson is mandatory forOrg has to be mandatory as well.

Furthermore has the Person-Crefonummer to be known in the context of the company defined in forOrg.

In order to use this option you need the Crefonummer for the person in question. If you don’t know what that is or how to get it, please get in touch with us (support@crefotrust.de).

Failing to adhere to this rules will result in a rejected order.

2c) Response

When the order is successfully placed the request responds with an orderId and an URL to which your customer needs to get forwarded to, to start the CrefoTrust process for that customer and that order. If you have provided more information with your order by using the verifierRef field, this value is also returned.

{
  "orderId": "[SOME_UUID]",
  "url": "https://crefotrust.de/[SOME_UUID]",
  "verifierRef": {
    "referenceId": "my_reference_id",
    "correlationId": "my_correlation_id",
    "userId": "my_user_id"
  }
}

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.

2d) Redirect URLs

In case 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, e.g.:

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

2e) Identification Methods

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

IDNow / ITM - Video Ident; use “itm_videoident” in acceptedIdMethods and/or offeredIdMethods
Nect - Auto Ident use “nect_autoident” in acceptedIdMethods and/or offeredIdMethods

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]

For security reasons you might want to give us an API and Header key during onboarding to authenticate the webhook request at your backend.

Here is an example of a request body send to the webhook (matching the order in 2b):

{
  "orderId": "[THE_ORDER_ID_FROM_2c]",
  "meta": {... see below ...},

  "person":{
    "name":{
        "familyName":"Mustermann",
        "givenName":"Erika"
    },
    "birthdate":"1964-05-03",
    "nationality":"DE"
  },
  "authorizedRepresentative": true,
  "org":{
    "legalName":"Test-Firma",
    "address":{
        "streetAddress":"Teststraße 1a",
        "postalCode":"12345",
        "addressLocality":"Teststadt",
        "addressCountry":"DE"
    }
  }

(all options and their structure are in 4)

Meta Data

Along with the actual data we are providing some meta information about it. On the top level it has the following fields

verifier [DEPRECATED, see 2a]: your verifier ID
verifierRef: the object as provided in the initial order (“options” => “verifierRef”)
person: meta information regarding the identified person (DID for the person) and the requested credentials, structured like the data itself
authorizedRepresentative: the authorizedRepresentative credentials meta information.
org: meta information regarding the selected company (DID for the company) and its requested credentials, structured as the data itself

DID (Decentralized Identifiers)

DID is an (upcoming) W3C standard and defines addressable identity documents. For the basic DID your have a three-part string separated by colon, e.g:

did:method:method-specific-identifier

For the web-method specifically the identifier is made up of the domain name, optional path segments (separated by colon) and an ID string, e.g.:

did:web:api.crefotrust.de:user:a1b2c3d4e5f1a1a

For more information visit the DID specs and web-method specs.

For each credential the following set of meta data will be provided:

issuedAt: the Unix timestamp when the credential was issued to the user presenting the information (the holder, in DID lingo).
status: has an URL, that can be used to check, if the credential is still valid. Possible return values are: VALID and REVOKED (as plain text). If the credential in unknown a 404 HTTP response will be send.
issuer: the entity (specified as DID) that gave the credential to the holder, being the trust root for the credentials claim. Usually this is CrefoTrust itself. But under some conditions the user is the issuer herself, basically when a private address was requested and the user identified with a passport (which doesn’t have a residential address).

Besides this meta data available for every credential, the authorizedRepresentative credential has two more properties, essentially semantically joining the company and person by their relationship:

org: the DID of the company the person is an authorized representative for
person: the DID of the person who is an authorized representative for that company

{
  ...
  "meta": {
    "verifier": "[VERIFIER-ID]",
    "verifierRef": {
      "referenceId": "my_reference_id",
      "correlationId": "my_correlation_id",
      "userId": "my_user_id"
    },
    "person": {
      "id": "did:web:api.crefotrust.de:user:cb3e2e60-a8f8-4bdd-9fe1-fb490e0edefc",
      "credentials": {
        "name": {
          "issuedAt": 1658400571,
          "status": "https://api.crefotrust.de/api/credentials/abc1a061-7cba-43f8-ad23-800b6f993dda/status",
          "issuer": "did:web:api.crefotrust.de"
        },
        "birthdate": {
          "issuedAt": 1658400571,
          "status": "https://api.crefotrust.de/api/credentials/abc1a061-7cba-43f8-ad23-800b6f993dda/status",
          "issuer": "did:web:api.crefotrust.de"
        },
        "nationality": {
          "issuedAt": 1658400571,
          "status": "https://api.crefotrust.de/api/credentials/abc1a061-7cba-43f8-ad23-800b6f993dda/status",
          "issuer": "did:web:api.crefotrust.de"
        }
      }
    },
    "authorizedRepresentative": {
        "issuedAt": 1658400571,
        "person": "did:web:api.crefotrust.de:user:cb3e2e60-a8f8-4bdd-9fe1-fb490e0edefc",
        "org": "did:web:crefotrust.de:org:1234567890",
        "status": "https://api.crefotrust.de/api/credentials/abc1a061-7cba-43f8-ad23-800b6f993dda/status",
        "issuer": "did:web:api.crefotrust.de"
    },
    "org": {
      "id": "did:web:crefotrust.de:org:1234567890",
      "credentials": {
        "legalName": {
          "issuedAt": 1658400571,
          "status": "https://api.crefotrust.de/api/credentials/abc1a061-7cba-43f8-ad23-800b6f993dda/status",
          "issuer": "did:web:api.crefotrust.de"
        },
        "address": {
          "issuedAt": 1658400571,
          "status": "https://api.crefotrust.de/api/credentials/abc1a061-7cba-43f8-ad23-800b6f993dda/status",
          "issuer": "did:web:api.crefotrust.de"
        }
      }
    }
  },
  ...
}

4) Getting Order State

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. Here is an example response:

{
  "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]",
    "verifierRef": {
      "referenceId": "my_reference_id",
      "correlationId": "my_correlation_id",
      "userId": "my_user_id"
    }
  },
  "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

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 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: for example, 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

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.

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) Authorized Representative

This credential represents a special relationship between person and company, It’s meaning is basically that the person might act for that company in certain legal matters or the other way around, that the company is represented by the person in such cases.

Post Order Data

You signal that your require this credential via:

{
  //...
  "requiredCredentials": {
    "authorizedRepresentative": true
  }
  //...
}

If you don’t want this credential, you may leave it out completely or explicitly set the value to false. Please bear in mind that the value is actually a boolean. Other value types will lead to a rejection of the order request.

Webhook Request Data

And will get the data delivered to your webhook as:

{
  //...
  "authorizedRepresentative": true
  //...
}

5c) 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"
  }
  //...
}

6) Data mocking and testing

Attention: This is an experimental feature and will possibly change in the future.

Testing the CrefoTrust System is currently possible via configurable mock cases. The supported cases are predefined and described below and may also change over time. Each mock case stands for a specific combination of requested and verified person and company data. It also defines the outcome (e.g. success or failure). To test your implemented CrefoTrust integration properly you can configure the mock case in the order attribute verifierRef (see above). The possible configuration parameters are:

enableMock: “true” / “false”
mockCaseId: “0” / “1” / …
mockVariant: “0” / “1” / …

Below the different mock case ids with different variants are shown. Each mock case representents a different person idenfitifaction scenario. The listed names all belong to the company AutoIdent VideoIdent Testcase GmbH and can be selected in the app via the company search bar:

Case 0: Success case, positive identification

Variant 0: Knut Küste
Variant 1: Erika Mustermann
Variant 2: Max Mustermann (not authorized representative; not listed)
Variant 3: Knut Küste (Passport)
Variant 4: Erika Mustermann (Passport)

Case 1: Success case, positive identification, input person mismatches output person, output person is also authorized representative
```
Variant 0: Paul Mustermann
Variant 1: Paul Mustermann (Passport)
```

Case 2: Success case, positive identification, middle names

Variant 0: Erika Mustermann
Variant 7: Erika Mustermann (Passport)

Case 3: Failure case, positive identification, identification document has expired
```
Variant 0: Expiry Mustermann
Variant 1: Expiry Mustermann (Passport)
```

Case 4: Failure case, negative identification (different failure reasons)

Variant 0: Mallory Mustermann
Variant 1: Mallory Mustermann
Variant 2: Mallory Mustermann

Case 5: Failure case, negative identification, process was cancelled by user

Variant 0: Knut Küste
Variant 1: Paul Mustermann
Variant 2: Mallory Mustermann
Variant 3: Expiry Mustermann
Variant 4: Erika Mustermann
Variant 5: Erika Sophie Mustermann

Attention: Currently, when data mocking is enabled, you may only create identification requests for the mock-configured persons. Otherwise you could end up with an endless spinner in the user-app. This behavior is intended, as the mocking works end-2-end, including the identification requests, the identification payload of the mocked ident-providers, the mocked Firmenwissen API for authorized representatives and so on. Therefore you should check that your configured mocking matches to your input via the CrefoTrust user-app. For example, if you use the default configuration (case 0, variant 0), you will only be able to create identification requests for Knut Küste and the company AutoIdent VideoIdent Testcase GmbH. To create requests for other cases, configure your mocking accordingly. This behavior is considered to be changed in the future to unlock more flexibility.

7) Identification of a natural person

CrefoTrust has the ability to identify a natural person even without a relation to a company. The person will be asked to verify their identity via video- or auto-ident. As the person is identified without any relation to a company, the user flow will be adapted slightly, i.e. no company selection will be shown and no company related credentials will be created during the process.

Differences

Credential types

To create an order for this scenario, the payload for order creation must be adapted as follows:

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

It is important to not specify any company related credentials types (org or authorizedRepresentative), otherwise a person is always identified in the context of a related company. All supported person related credentials types are available (see here).

Order Presets

Currently the identification process of a natural person does not provide any kind of presets, i.e. the verifier is not able to pre-define which person should be verified. Therefore, the forOrg and forPerson properties must not be used in the order creation payload in the context of a natural person.

Reusability

One core value of CrefoTrust is reusability. This concept is also implemented inside of CrefoTrust regarding context switches with identified accounts. If a person is identified as a natural person inside of CrefoTrust then this identity can be reused in subsequent orders, no matter if it is a order to identify natural persons or to identify a person-company relation.

Example payload

{
  "requiredCredentials": {
    "person": ["name", "address"]
  },
  "webhook": "some valid webhook url",
  "redirect": {
    "success": "some url for success case",
    "failure": "some url for success case"
  },
  "options": {
    "verifierName": "your verifier name",
    "verifierRef": {
      // this can be set or left empty
    }
  },
  "offeredIdMethods": ["itm_videoident", "nect_autoident"],
  "acceptedIdMethods": ["itm_videoident", "nect_autoident"]
}

V3 CrefoTrust API

1) First things first

2) Placing Orders

2a) Auth

2b) Request Body

Required Credentials (key: requiredCredentials)

Webhook Address (key: webhook)

Redirect URLs (key: redirect)

Verifier Options (key: options) [OPTIONAL]

Accepted ID Methods (key: acceptedIdMethods) [OPTIONAL]

Offered ID Methods (key: offeredIdMethods) [OPTIONAL]

Preset Organization (key: forOrg) [OPTIONAL]

Preset Person (key: forPerson) [OPTIONAL]

2c) Response

2d) Redirect URLs

2e) Identification Methods

3) Webhook Request

4) Getting Order State

4a) Auth

4b) Request

4c) Response

4d) Order States

0 - Order Created

1 - Account Created

2 - Logged In

3 - Request Created

4 - Person Verified

5 - Person is Authorized Representative

6 - Data Sent

101 - Order Timed Out

102 - Delivery Error

103 - Process Canceled

5) Available Credentials

5a) Person

Name

Address

Birthdate

CrefoId

Nationality

5b) Authorized Representative

5c) Org

Address

LegalForm

LegalName

CrefoId

6) Data mocking and testing

7) Identification of a natural person

Differences

Credential types

Order Presets

Reusability

Example payload

V2 to V3 API Changes

DEPRECATED: V2 CrefoTrust API

DEPRECATED: V1 CrefoTrust API