Skip to main content

Digital Onboarding API

Introduction​

The following are the services, input models and responses that the Finwave Identification Platform has. All endpoints have the following information in common:

  • Host: https://idgateway-dev.finwave.com
  • Base path: /management

Endpoints​

POST /integrations​

For the generation of the URL, through which the onboarding process is initiated, the client must make use of the following service.

Request​

  • Endpoint: /integrations
  • Method: POST
  • Enctype: application/json
  • Headers: gestok-client-token (contains the customer's unique authorization token)
  • Body: 
    {
      "customId": "string",
      "webhook": "string",
      "lang": "ESP",
      "phoneCountryCode": "string",
      "phone": "string",
      "phoneStep": true,
      "acceptations": [
        {
          "mandatory": true,
          "text": "string"
        }
      ],
      "redirectUrl": {
        "type": 1,
        "url": "string",
        "waitingTime": 0
      }
    }
Description of properties​
  • customId:dentifier set by the client for its own use.
  • webhook: url to which this platform will call at the end of the process, informing the status of the process.
  • lang: indicates the language in which the identity documents are found, at the moment it only allows the value ENG (English).
  • phoneCountryCode: must be the phone code of the country (for example "+34" for Spain).
  • phone: must be a valid phone number.
  • phoneStep: sets if you want the process to include a verification via SMS.
  • acceptations: this is an array with the conditions that the user must visualize when accessing the platform, the mandatory parameter establishes if the condition is mandatory or not.
  • redirectUrl: sets a redirect at the end of the process (auto = 1, manual = 2, none = 3, iframe = 4) (NOTE: for the moment, this functionality is not available in the test version)

Response​

When creating an identification process, the service will return the following response, which includes a process identifier and the url to be shown to the user to start the process, along with the CREATED status.

  • 201 Success:

    {
      "onboardingId": "string",
      "url": "string",
      "status": "CREATED",
    }

    Or in the case that we make the call again for the same customId, and if the user has already started the process, then the response will be the following:

    {
     "onboardingId": "string",
     "url": null,
     "status": "INPROCESS" | "INCOMPLETED" | "TIMEOUT" | "FINISHED",
    }

The possible values of the status property are as follows:

  • CREATED: an identification process has been created that has not yet been started by the user.
  • INPROCESS: the user has started the identification process.
  • INCOMPLETED: the user has not completed the process and has abandoned it.
  • TIMEOUT: the time available to complete the process has expired and the user has not been able to finish it.
  • FINISHED: the user has finished the process completely.
Description of properties​
  • onboardingId: onboarding process identifier.
  • url: url to which the user must be directed to start the process.

Getting status (Webhook events)​

After finishing the onboarding process, the system will be able to make one or several calls to the webhook url, defined by the client in the request of the previous section. These calls will be of POST type and will have the following structure:

Note: The client must have this service available, otherwise it will not be possible to inform the client when a process has finished.

Request​

  • URL: webhook defined by the client in the previous call
  • Method: POST
  • Enctype: application/json
  • Body: 
    {
      "onboardingId": "string",
      "customId": "string",
      "result": "string"
    }

The onboardingId field is the identifier of the onboarding process, which can be used by the client to retrieve the results of the onboarding process, as detailed below. The customId field is a customer's own identifier, set in the previous onboarding call. The result field will be an enumerated string type, which may have the following values:

  • CREATED: an identification process has been created that has not yet been initiated by the user (when the URL is fetched from POST /integrtions).
  • INPROCESS: the user has started the identification process.
  • INCOMPLETED: the user has not completed the process and has abandoned it.
  • TIMEOUT: the time available for the process has expired and the user has not been able to finish it.
  • FINISHED: the user has finished the process completely.

GET /integrations/:onboardingId/result​

By means of the onboardingId of the onboarding process, the information with the results of the process can be retrieved through the following service:

Request​

  • Endpoint: /integrations/:onboardingId/result
  • Method: GET
  • Headers: gestok-client-token (contains the client's unique authorization token)
  • Param: onboardingId

Response​

  • 200 Success: 
    {
      "status": "string"
      "onboardingId": "string",
      "customId": "string",
      "processStatus": {
        "score": 0,
        "steps": {
          "acceptation": true,
          "ocr": true,
          "biometry": true,
          "sms": null
        }
        "startedAt": {
          "date": "2021-03-11 00:00:00",
          "timestamp": 1630510661214,
        },
        "finishedAt": {
          "date": "2021-03-11 00:00:00",
          "timestamp": 1630510661214,
        },
        "errorEvent": "string",
      },
      "acceptations": [
        {
          "text": "string",
          "accepted": true,
          "mandatory": true
        }
      ],
      "evidences": {
        "fullVideo": "string",
        "biometryBlink": "i8x5CWpwU0AvQ-173106313-BLINK.jpg",
        "biometrySmile": "i8x5CWpwU0AvQ-173106313-SMILE.jpg",
        "idDocumentFront": "i8x5CWpwU0AvQ-173106313-FRONT.jpg",
        "idDocumentReverse": "i8x5CWpwU0AvQ-173106313-REVERSE.jpg",
        "biometryTargetImage": "i8x5CWpwU0AvQ-173106313-SELFIE.jpg"
      },
      "ocr": {
        "types": [
          {
            "name": "IDCARD",
            "probability": 0.9090492129325866,
            "year": "2007-2009",
            "country": "PRT",
            "id": "PRT_IDCARD_2007-2009",
            "side": "A"
          }
        ],
        "fields": [
          {
            "name": "DOCUMENT_NUMBER",
            "sources": [
              {
                  "source": "VISUAL",
                  "value": "008390126ZX2",
                  "original_value": "00839012 6ZX2",
                  "probability": 0.9
              }
            ],
            "value": "008390126ZX2",
            "validity_status": true,
            "status": true
          }
        ],
        "images": [
          {
            "name": "PORTRAIT",
            "value": "/9j/4AAQSkZJRgABAQEAxwDHAAD/"
          }
        ],
        "authenticity": [
          {
            "name": "PATTERN_CHECKS",
            "value": true
          }
        ],
        "validations": [
          {
            "name": "OVERALL",
            "value": true
          }
        ]
      },
      "biometry": {
        "score": 99.78421020507812,
        "head": {
          "end": 1731063171,
          "moves": [
              {
                  "end": 1731063171,
                  "type": "MV_HEAD_STRAIGHT",
                  "start": 1731063167
              }
          ],
          "start": 1731063167,
          "success": true
        },
        "blink": {
          "end": 1731063174,
          "start": 1731063167,
          "success": true
        },
        "smile": {
          "end": 1731063173,
          "start": 1731063167,
          "success": true
        }
      },
      "smsEvents": [
        {
          "date": "2021-03-11 00:00:00",
          "timestamp": 1630510661214,
          "code": "string"
        }
      ],
      "logs": [
        {
          "date": "2021-03-11 00:00:00",
          "timestamp": 1630510661214,
          "code": "USER_VISITED_ONBORDING_WEB",
          "description": "he user has visited the web, but has not yet started the process."
        }
      ],
      "userAgent": {
        "os": "string",
        "device": "string",
        "address": "string",
        "browser": "string"
      }
    }

Property ocr​

For detailed information about the OCR result fields, please refer to the OCR API documentation.

Property biometry​

For detailed information about the biometry result fields, please refer to the Liveness API documentation.

status property​

The possible values of the status property are the following:

  • CREATED: an identification process has been created but not yet started by the user.
  • INPROCESS: the user has started the identification process.
  • INCOMPLETED: the user has not completed the process and has abandoned it.
  • TIMEOUT: the time available to complete the process has expired and the user has not been able to finish it.
  • FINISHED: the user has finished the process completely.

Obviously, if the status is CREATED or INPROCESS, the rest of the information will be partial, since until the user has finished the onboargind process, not all the information will be available.

Property processStatus.errorEvent:​

This property describes the type of error that can occur in a process. If no error occurs its value will be null, in case an error occurs it will have one of the following values:

  • TIME_EXPIRED: Time to perform the onboarding process expired.
  • USER_LEAVES_PROCESS: The user abandons the process.
  • SMS_EXCEEDED: Maximum number of SMS messages exceeded.
  • OTP_VALIDATION_EXCEEDED: The maximum number of validation of a code sent by SMS has been exceeded.
  • OCR_RETRIES_EXCEEDED: Maximum number of OCR attempts exceeded.
  • OCR_ERROR: Error in the OCR process.

smsEvents property.​

The values that smsEvents.code can contain are the following:

  • SMS_SENDED: SMS message sent.
  • SUCCESS_OTP: Valid OTP.
  • ERROR_OTP: Invalid OTP.
  • OTP_VALIDATION_EXCEEDED: The maximum number of validation attempts of an OTP code has been exceeded.

logs property​

This property contains an array of events, which informs about what is happening during the whole process. Each element of the array contains the following properties:

  • date: Date and time of the event in string format.
  • timestamp: Date and time of the event in timestamp format.
  • code: Event code (see list below).
  • description: Brief description of the event.

The codes that can come in the code property are the following (in approximate order in which they would occur):

  • USER_VISITED_ONBORDING_WEB: The user has visited the web, but has not yet started the process.
  • USER_START_ONBOARDING_PROCESS: The user has started the login process.
  • OCR_STREAM_STARTED: The OCR process has been started.
  • OCR_RESULT: The OCR process has completed.
  • FRONT_DOCUMENT_SENDED: The user has sent the front part of his ID document.
  • BACK_DOCUMENT_SENDED: The user has sent the back of his ID document.
  • BIOMETRY_STARTED: The biometrics process has been started.
  • BIOMETRY_FINISHED: The biometrics process has completed.
  • SMS_CODE_REQUEST: A code has been requested via SMS.
  • SMS_MAX_REQUESTS: The maximum number of code requests via SMS has been reached.
  • SMS_OTP_VALIDATION: The code has been sent for validation.
  • SMS_OTP_ERROR: An error occurred when validating the code because it was not correct.
  • SMS_OTP_SUCCESSFULLY: The code has been validated correctly.
  • SESSION_EXPIRED: The session has expired.
  • PROCESS_INCOMPLETED: The identification process has not been completed for one of the following reasons: a) The user has abandoned; b) The process has been cancelled for some reason; c) A disconnection has occurred.
  • PROCESS_FINISHED_SUCCESSFULLY: The identification process has been successfully completed.

Evidence retrieval (files)​

By means of the onboardingId of the onboarding process, it will be possible to download the evidence files (images, video, json) compressed in a single ZIP file, through the following service. All the files will have as names those referred to in the filename field of the JSON in the previous section.

GET /integrations/:onboardingId/evidences​

Service to download all files (images and videos) in a single ZIP file.

  • Endpoint: /integrations/:onboardingId/evidences
  • Method: POST
  • Produces: application/zip
  • Headers: gestok-client-token (contains the client's unique authorization token)
  • Param: onboardingId
Soportesoporte.onboarding@finwave.es