Onboarding

In this section, you will find how to create a Onboarding process in the by Unico Integration

Getting started

Your API requests are authenticated using an access token. Any request that does not include a valid access token will return an error.

You can learn more about generating an access token here.

Base URL:

  • Sandbox: https://api.idcloud.uat.unico.app;

  • Production: https://api.idcloud.unico.app.

Create Process

post

Endpoint to create a new Onboarding process in by Unico integration.

Authorizations
Body
callbackUristringRequired

Defines where the user will be redirected at the end of the process. Possible values are: A URL (e.g., https://developers.unico.io/callback), a Schema URL for redirection in native mobile applications (e.g., br.com.meupacote.app://callback - the callback must be registered in your mobile app), or no redirection (just include '/').

Example: /
flowstring · enumRequired

Flow used for Onboarding processes

Example: idonboardingPossible values:
clientReferencestringOptional

It is a non-mandatory identifier that will be used as an indexer in the portal and you can use it as a form of association (foreign key) between your system and IDCloud.

companyBranchIdstringOptional

The ID of the branch where the process will be created. If there is only one branch associated with the service account, this parameter is not required. If there is a separation of processes by branch, you will receive the branch IDs from the Unico team.

Example: 60837cd3-ed3c-4038-ad7c-0a85ad64b03a
purposestring · enumRequired

Purpose of the process.

Example: creditprocessPossible values:
expiresInstringOptional

Expiration time of the process in seconds from its creation. The value must be in the format "10080s", with "s" at the end. If not provided, the default value of 7 days will be used.

Example: 3600s
Responses
200

Process successfully created.

application/json
post
POST /client/v1/process HTTP/1.1
Host: api.idcloud.uat.unico.app
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 456

{
  "callbackUri": "/",
  "flow": "idonboarding",
  "flow_config": {
    "biometry_capture": {
      "enabled_back_camera": true
    }
  },
  "clientReference": "",
  "companyBranchId": "60837cd3-ed3c-4038-ad7c-0a85ad64b03a",
  "person": {
    "duiType": "DUI_TYPE_MX_CURP",
    "duiValue": "HEWW580907HGRSHL05",
    "friendlyName": "Luke Skywalker",
    "phone": "525536558888",
    "email": "[email protected]",
    "notifications": [
      {
        "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP"
      }
    ]
  },
  "purpose": "creditprocess",
  "expiresIn": "3600s"
}
{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "flow": "idonboarding",
    "callbackUri": "/path/to/callback-url/",
    "userRedirectUrl": "https://cadastro.dev.unico.app/process/53060f52-f146-4c12-a234-5bb5031f6f5b",
    "state": "PROCESS_STATE_CREATED",
    "result": "PROCESS_RESULT_UNSPECIFIED",
    "createdAt": "2023-10-09T15:15:25.417105Z",
    "person": {
      "duiType": "DUI_TYPE_MX_CURP",
      "duiValue": "HEWW580907HGRSHL05",
      "friendlyName": "Luke Skywalker",
      "email": "[email protected]",
      "phone": "525536558888",
      "notifications": [
        {
          "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP"
        }
      ],
      "phoneCountryCodeAlpha3": ""
    },
    "purpose": "creditprocess",
    "services": [],
    "authenticationInfo": {
      "authenticationId": ""
    },
    "capacities": [
      [
        "PROCESS_CAPACITY_IDCLOUDONE"
      ]
    ],
    "expiresAt": "2023-10-09T15:15:25.417105Z",
    "token": "eyJhbGciOiJSUzI1[...]d_jhQ",
    "companyData": {
      "branchId": "60837cd3-ed3c-4038-ad7c-0a85ad64b03a",
      "countryCode": "MEX"
    },
    "webAppToken": "eyJhbGciOiJSUzI1[...]d_jhQ"
  }
}

Processes must be created exclusively through backend-to-backend communication, due to our CORS policy, which prevents processes from being created through frontend-to-backend communication.

Error Responses

Get Result

get

Endpoint to get the result of a process in by Unico.

Authorizations
Path parameters
processIdstringRequired

Process ID.

Responses
200

Process details retrieved successfully.

application/json
get
GET /client/v1/process/{processId} HTTP/1.1
Host: api.idcloud.uat.unico.app
Authorization: Bearer JWT
Accept: */*

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "flow": "idonboarding",
    "callbackUri": "/",
    "userRedirectUrl": "https://cadastro.dev.unico.app/process/53060f52-f146-4c12-a234-5bb5031f6f5b",
    "state": "PROCESS_STATE_FINISHED",
    "result": "PROCESS_RESULT_LIVE",
    "person": {
      "duiType": "DUI_TYPE_MX_CURP",
      "duiValue": "HEWW580907HGRSHL05",
      "friendlyName": "Luke Skywalker",
      "email": "[email protected]",
      "phone": "525536558888",
      "notifications": [
        {
          "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP"
        }
      ],
      "phoneCountryCodeAlpha3": ""
    },
    "purpose": "creditprocess",
    "services": [],
    "authenticationInfo": {
      "authenticationId": "fd433602-d496-4291-adbb-dda95a3e50b1"
    },
    "capacities": [
      "PROCESS_CAPACITY_IDCLOUDONE"
    ],
    "expiresAt": "2023-10-09T15:15:25.417105Z",
    "token": "",
    "companyData": {
      "branchId": "60837cd3-ed3c-4038-ad7c-0a85ad64b03a",
      "countryCode": "MEX"
    }
  }
}

To implement your business rules, always validate the parameters in the following order:

  • If state = PROCESS_STATE_FINISHED, then look at the result parameter return and make the decision.

You can also use our Webhook to know when make to request to retrieve the validation result.

To test the responses, use the following CURPs:

  • HEWW580907HGRSHL05 -> PROCESS_RESULT_NOT_APPROVED;

  • BAWB700219HNLTYR01 -> PROCESS_RESULT_HIGH_RISK;

  • IIFA830702HDFGNN06 -> PROCESS_RESULT_CRITICAL_RISK;

  • PASP901014HDFRPT03 -> PROCESS_RESULT_LIVE.

PreviousAPI ReferenceNextTransactional

Last updated