Create Process

URL Base:

• UAT: https://api.cadastro.uat.unico.app.

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

Create Process

post

Endpoint to create a new process at Unico.

Authorizations

bearerAuth

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

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 type. See flow details in the 'Overview' section of this documentation.

Example: idunicosignPossible 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.

Example: 60837cd3-ed3c-4038-ad7c-0a85ad64b03a

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

bioTokenIdstringOptional

Biometric token identification. Mandatory for the "idtoken" flow and must use an ID from a completed process of any other identity verification flow.

Example: 60837cd3-ed3c-4038-ad7c-0a85ad64b03a

useCasenull · enumOptional

Use case identification. Mandatory for the "idsmart" flow.

Possible values:

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

400

When some parameter are wrong.

application/json

401

Access-token error.

application/json

500

Unexpected error (Internal error or parameter issue).

application/json

post

/client/v1/process

HTTPcURLJavaScriptPython

POST /client/v1/process HTTP/1.1
Host: api.cadastro.uat.unico.app
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 813

{
  "callbackUri": "/",
  "flow": "idunicosign",
  "flow_config": {
    "biometry_capture": {
      "enabled_back_camera": true
    }
  },
  "clientReference": "60837cd3-ed3c-4038-ad7c-0a85ad64b03a",
  "companyBranchId": "60837cd3-ed3c-4038-ad7c-0a85ad64b03a",
  "bioTokenId": "60837cd3-ed3c-4038-ad7c-0a85ad64b03a",
  "useCase": null,
  "person": {
    "duiType": "DUI_TYPE_BR_CPF",
    "duiValue": "12345678909",
    "friendlyName": "Luke Skywalker",
    "phone": "5511912345678",
    "email": "[email protected]",
    "notifications": [
      {
        "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP"
      }
    ]
  },
  "purpose": "creditprocess",
  "expiresIn": "3600s",
  "contextualization": {
    "currency": "BRL",
    "price": 15990.9,
    "locale": {
      "ptBr": {
        "reason": "Abertura de cadastro"
      }
    }
  },
  "payload": [
    {
      "envelopePayload": {
        "documents": [
          {
            "documentName": "teste",
            "fileContents": "JVBERi0xLjMNCiXi48/[...]DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
          }
        ]
      }
    }
  ]
}

{
  "process": {
    "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
    "companyBranchId": "60837cd3-ed3c-4038-ad7c-0a85ad64b03a",
    "flow": "idunicosign",
    "callbackUri": "/path/to/callback-url/",
    "userRedirectUrl": "https://cadastro.dev.unico.app/process/53060f52-f146-4c12-a234-5bb5031f6f5b",
    "state": "PROCESS_STATE_CREATED",
    "createdAt": "2023-10-09T15:15:25.417105Z",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "73689290074",
      "friendlyName": "Luke Skywalker",
      "phone": "5511912345678",
      "email": "[email protected]",
      "notifications": [
        {
          "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP"
        }
      ]
    },
    "purpose": "creditprocess",
    "authenticationInfo": {},
    "capacities": [
      [
        "PROCESS_CAPACITY_IDUNICO",
        "PROCESS_CAPACITY_IDLIVE",
        "PROCESS_CAPACITY_IDSIGN"
      ]
    ],
    "expiresAt": "2023-10-09T15:15:25.417105Z",
    "token": "eyJhbGciOiJSUzI1[...]d_jhQ",
    "companyData": {
      "branchId": "60837cd3-ed3c-4038-ad7c-0a85ad64b03a",
      "countryCode": "BRA"
    },
    "clientReference": "60837cd3-ed3c-4038-ad7c-0a85ad64b03a"
  }
}

• The requirement for parameters in process creation may change depending on the flows used. For example:

  • In flows that involve Electronic Signature, it is mandatory to send the payload object and all its properties.

  • In flows that involve Validation (1:1), it is mandatory to send the bioTokenId property.

  • In flows that involve Smart Validation, it is mandatory to send the bioTokenId and useCase properties.

• The same process ID will be returned upon creation if the user has not yet opened the link, the data sent is identical, and there is an interval of up to 2 minutes in relation to the first process.

Errors

400 Bad Request

code	message	description
3	invalid flow	When the specified flow does not exist.
3	invalid person: friendly name exceeds 50 characters.	When the friendly name exceeds 50 characters,
3	invalid purpose	When the provided proposal is invalid.
3	invalid callbackUri: unable to parse callbackUri: parse "": empty url, invalid callbackUri: url:	When the provided callbackUri is invalid.
3	invalid person: email required for notification channel NOTIFICATION_CHANNEL_EMAIL, invalid email address for notification channel NOTIFICATION_CHANNEL_EMAIL	When the provided email is invalid, but there is email notification.
3	invalid person: phone number required for notification channel NOTIFICATION_CHANNEL_WHATSAPP, phone number does not contain 13 chars for notification channel NOTIFICATION_CHANNEL_WHATSAPP	When the provided phone number is invalid, but there is notification via SMS or WhatsApp.
3	idnsv2/GetPublicID request error: rpc error: code = InvalidArgument desc = invalid dui value	When the provided CPF is invalid.
9	XX ID Apikeys are not set	When an API Key has not been configured correctly.

401 Unauthorized

429 Too Many Requests

500 Internal Server Error