Get Result - Authenticate

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.

1. Callback

For different services, ShareID provides a callback mechanism.

You may provide a callback to recieve 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.

POST {API_URL}/flow/authenticate/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 authenticate ?

You need to call this api, providing the flow_id you received when opening a session to authenticate a user.

POST {API_URL}/flow/authenticate/fetch
{
  "flow_id": str mandatory,
}

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

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

{
    "detail": "applicant not found"
}

Last updated