Get Result - Onboarding

When the processing of an onboarding request is finished, you may receive the result through:

• The callback if you provided it when setting up a token.

• You may also, fetch yourself the result by calling our API endpoint.

If the analysis result is ready and available you'll have a json doc described here.

Both methods are described below (you may combine both or use just one)

1. Callback

For different services, ShareID provides a callback mechanism.

You may provide a callback to receive the analysis result. Whatever is the service used by the callback, these rules apply:

• the callback must be a public link (or at least accessible from our platform [you may contact us to get our outgoing IP ranges])

• It should be preferably an https link over an http link. In case of a secure link (using TLS), please ensure the validity of the certificate. The callback may be rejected if the certificate is invalid (obsolete, untrusted root certificate etc.)

• The endpoint provided can contains variables in the URL but must respond to an HTTP POST method

  • eg: POST https://example.com/my_endpoint.php?transaction_id=9JD2XNU5

• Also, the data send by our servers will use a json header

  • "Content-Type: application/json"

  • This means that you'll receive the resulting data as a json object

  • Each service will give a description of the object fields

• Our server waits for an http status which must be 200 within 3000ms

  • in case it's an other status or if no response is given after the delay, we consider this is an error and we start a retry mechanism

  • the retry mechanism tries a max of 3 times:

    • if the first call is wrong, the callback is retried after 5 minutes

    • then after 1 hour

    • then after 24 hours

    • after this it is never retried

• If your server need a specific header (like an authorization bearer) please contact us.

2. Calling an API Endpoint

NB: Be aware, this technique is called 'polling', this means that you will call the api until you have a result from our API. Our advise is to wait 5s between each call {API_URL}/flow/onboarding/fetch once you have a valid token. Too many calls in a short window may be rejected.

First get a token:

POST {API_URL}/flow/onboarding/fetch/auth/business
{
  "business_hash": str mandatory,
  "api_key": str mandatory,
}

As a response you will get a json document which includes a field named token. This token has a TTL of 10 minutes, so you can reuse it for multiple calls.

How to use the token ?

You simply add an Authorization Http header to your request with the given token

Authorization: Bearer <TOKEN>

How to get the result of the onboarding ?

You need to call this api, providing the applicant_id you received when getting a token for the onboarding demand.

POST {API_URL}/flow/onboarding/fetch
{
  "applicant_id": str mandatory,
}

As a result of this call you can get a 200 http status:

• But the message is not ready instead of yet so you'll have as a response a json doc containing

{
    "detail": "result not ready yet"
}