Create Process
This article explains how to create a process in By Unico via the REST API.
How to use it?
Make a POST request for the endpoint:
- UAT: https://api.cadastro.uat.unico.app/client/v1/process
- Production: https://api.cadastro.unico.app/client/v1/process
With a valid access token, make a request to the endpoint sending the following parameters:
{
"callbackUri": "/path/to/url",
"flow": "<FLOW_TYPE>",
"person": {
"duiType": "<DUI_TYPE>",
"duiValue": "<DUI_VALUE>",
"friendlyName": "<USER_FRIENDLY_NAME>",
"phone": "<USER_PHONE_NUMBER>",
"email": "<USER_EMAIL>",
"notifications": [
{
"notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP"
},
{
"notificationChannel": "NOTIFICATION_CHANNEL_SMS"
}
],
},
"purpose": "<DATA_COLLECT_PURPOSE>",
"payload": [],
"expiresIn": "<EXPIRES_IN>",
"contextualization": {
"currency": "BRL",
"price": "<FLOAT_NUMBER>",
"locale": {
"ptBr": {
"reason": "<REASON_PTBR>"
},
"enUs": {
"reason": "<REASON_ENUS>"
},
"esMX": {
"reason": "<REASON_ESMX>"
}
}
}
}
Request parameters
Name | Type | Mandatory/Optional | Description |
---|---|---|---|
flow | String | Mandatory | Defines the journey to be executed. id : Identity validation flow with facial biometrics. idcheck : Identity validation flow with facial biometrics with score in the case of inclusion. iddocs : Identity validation flow with document capture and reuse (RG or CNH). idsign : Identity validation flow with electronic signature. iddocssign : Identity validation flow, capture/reuse of documents (RG or CNH) and electronic signature. |
callbackUri | String | Mandatory | Defines where the user will be redirected at the end of the process. URL: You can use a URL for a web page in your flow. Example: https://developers.unico.io/callback . You can customize as you wish. URL Scheme: You can also perform redirection to native mobile applications. Example: br.com.meupacote.app://callback . This callback needs to be registered in your mobile application. No redirection: If you are using the solution in a message flow, use the value / to avoid a redirection at the end of the flow. |
person.personDuiType | String | Mandatory | Defines the user identifier type. DUI_TYPE_BR_CPF : To use CPF as an identifier. |
person.personDuiValue | String | Mandatory | Sets the value of the user identifier specified in the personDuiType field. Example: If using the identifier DUI_TYPE_BR_CPF for CPF, use a valid CPF without formatting: 73689290074 . Note: Mandatory in SMS and WhatsAPP flows. |
person.friendlyName | String | Optional | Sets the user name. Ex.: John Doe . |
person.phone | String | Optional(*) | Sets the user's phone number. Ex.: 5511900000000 |
| person.email | String | Optional | Defines the user's email. |
| notifications.notificationChannel | String | Optional | notifications
: It is an array that defines the notification sending channel. The field must be filled in with the desired notifications: SMS, or WhatsApp, or both channels.
Example of use:
notificationChannel
: NOTIFICATION_CHANNEL_SMS
notificationChannel
: NOTIFICATION_CHANNEL_WHATSAPP
Do not send notification fields in case of receiving URL only.|
| purpose | String | Mandatory | Defines the purpose of using and collecting user data. It aims to provide transparency and ensure correct data processing under the LGPD.
creditprocess
: If you are using the solution to offer credit to the user.
biometryonboarding
: If you are using the solution to perform user onboarding.
carpurchase
: If you are using the solution to purchase a vehicle. |
| bioTokenId | String | Optional() | Define the transaction Id that you want to compare with the validation of the idtoken
flow.
The value of this field can be the value of the id
field or authenticationInfo.authenticationId
of the process returned when performing the GetProcess
of an idcheck
process. |
| payload | Array | Mandatory | The payload
field is an Array that offers a place to insert files necessary for some specific flows, such as idsign
.
Within the payload
Array another Array can be used to create signature flow envelopes.
The documents
field is an Array that receives the documents that make up each envelope, which can be 1 or more.
Each Object document
has:
- documentName
: Name of the document.
- fileContents
: Base64 of the PDF to be signed.
This field is required for integration with IDSign. |
| expiresIn | String | Optional | This field defines the time in seconds for the process expiration, based on the created_at date. Example: to expire in 24 hours, use "expires_in": "86400s"
. The default is 7 days if not specified. |
| contextualization.price | float | Optional | Defines the value to be displayed in the process contextualization. |
| contextualization.currency | String | Optional (*) | Defines the currency that will be used to format the price
field. |
| contextualization.locale.ptBr.Reason | String | Optional | Defines the information displayed in the Reason
field of the process when the pt-br
language is selected. |
| contextualization.locale.enUs.Reason | String | Optional | Defines the information displayed in the Reason
field of the process when the en-us
language is selected. |
| contextualization.locale.esMx.Reason | String | Optional | Defines the information displayed in the Reason
field of the process when the es-mx
language is selected. |
| companyBranchId | String | Optional | Defines the id
of the branch to which the created process is related. |
(*) The person.phone parameter becomes Mandatory when the notifications.notificationChannel field is filled in.
(**) The bioTokenId parameter becomes mandatory when the flow field is of type idtoken
. The creation of the idtoken
flow is only possible after the successful completion of an idcheck
flow.
(***) The contextualization.currency parameter becomes mandatory when the contextualization.price field is filled. Example of how the user interface will look with the contextualization:
For the idtoken
flow, the CPF is only validated if the value provided is the id
field of the process. If the value passed in the idtoken
field is authenticationInfo.authenticationId
, the CPF will not be guaranteed.
For the creation of processes with a service account that has permission for only one branch, it is not necessary to provide the companyBranchId
field.
For a service account that has permission for more than one branch, it is necessary to provide the companyBranchId
field with the desired branch id
value.
Request example
{
"callbackUri": "/path/to/url",
"flow": "idsign",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "73689290074",
"friendlyName": "John Doe",
"notifications": [
{
"notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP"
},
{
"notificationChannel": "NOTIFICATION_CHANNEL_SMS"
}
],
},
"purpose": "creditprocess",
"payload": [
{
"envelopePayload": {
"documents": [
{
"documentName": "FileToSign",
"fileContents": "JVBERi0xLjMNCiXi48/[...]DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
}
]
}
}
],
"companyBranchId": "9ea8e39a-188a-4295-b5d7-3dd8791ab199",
"expiresIn": "86400s",
"contextualization": {
"currency": "BRL",
"price": 15990.9,
"locale": {
"ptBr": {
"reason": "Validação de identidade"
},
"enUs": {
"reason": "Identity validation"
}
}
}
}
For more examples, see Request Examples
Ways of making a request (request)
- cURL
- Postman
- NodeJS
- Java
- C#
- Go
curl -X 'POST' \
'https://api.cadastro.uat.unico.app/client/v1/process/' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {{TOKEN}}'
-d '{
"callbackUri": "/",
"flow": "id",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "73689290074"
},
"purpose": "creditprocess"
}'
To use Postman, follow these steps:
- Select the POST method.
- Enter the URL
https://api.cadastro.uat.unico.app/client/v1/process/
. - Select the Authorization tab.
- In the Type list, select Bearer Token.
- Enter the token obtained in the Token field with the prefix
Bearer
. - Select the Body tab and enter the data below according to your needs.
{
"callbackUri": "/paht/callback-url",
"flow": "id",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "73689290074"
},
"purpose": "creditprocess"
}
const axios = require("axios");
const apiUrl = "https://api.cadastro.uat.unico.app/client/v1/process/";
const token = "<YOUR_TOKEN_HERE>";
const requestData = {
callbackUri: "/path/to/url",
flow: "id",
person: {
duiType: "DUI_TYPE_BR_CPF",
duiValue: "73689290074",
},
purpose: "creditprocess",
};
const headers = {
"Content-Type": "application/json",
Authorization: `Bearer ${token}`,
accept: "application/json",
};
axios
.post(apiUrl, requestData, { headers })
.then((response) => {
console.log("API response:", response.data);
})
.catch((error) => {
console.error("Error:", error);
});
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.HashMap;
import java.util.Map;
public class Main {
public static void main(String[] args) {
String apiUrl = "https://api.cadastro.uat.unico.app/client/v1/process/";
String token = "<YOUR_TOKEN_HERE>";
// Create the request body in JSON format
String requestBody = "{\"callbackUri\":\"/\",\"flow\":\"id\",\"person\":{\"duiType\":\"DUI_TYPE_BR_CPF\",\"duiValue\":\"73689290074\"},\"purpose\":\"creditprocess\"}";
// Set up the request headers
Map<String, String> headers = new HashMap<>();
headers.put("Content-Type", "application/json");
headers.put("Authorization", "Bearer " + token);
headers.put("accept", "application/json");
// Create the HttpClient instance
HttpClient httpClient = HttpClient.newBuilder().build();
// Create the HTTP POST request
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(apiUrl))
.headers(headers.entrySet().stream()
.map(e -> e.getKey() + ":" + e.getValue())
.toArray(String[]::new))
.POST(HttpRequest.BodyPublishers.ofString(requestBody))
.build();
try {
// Envie a solicitação e obtenha a resposta
HttpResponse<String> response = httpClient.send(request, HttpResponse.BodyHandlers.ofString());
// Exiba a resposta da API
System.out.println("Status da resposta: " + response.statusCode());
System.out.println("Corpo da resposta: " + response.body());
} catch (Exception e) {
e.printStackTrace();
}
}
}
using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
string apiUrl = "https://api.cadastro.uat.unico.app/client/v1/process/";
string token = "<YOUR_TOKEN_HERE>";
// Create the request body in JSON format
string requestBody = "{\"callbackUri\":\"/\",\"flow\":\"id\",\"person\":{\"duiType\":\"DUI_TYPE_BR_CPF\",\"duiValue\":\"73689290074\"},\"purpose\":\"creditprocess\"}";
// Set up the request headers
HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Add("Content-Type", "application/json");
client.DefaultRequestHeaders.Add("Authorization", "Bearer " + token);
client.DefaultRequestHeaders.Add("accept", "application/json");
try
{
// Send HTTP POST request
HttpResponseMessage response = await client.PostAsync(apiUrl, new StringContent(requestBody, Encoding.UTF8, "application/json"));
// Check the response status
if (response.IsSuccessStatusCode)
{
string responseBody = await response.Content.ReadAsStringAsync();
Console.WriteLine("Response status: " + response.StatusCode);
Console.WriteLine("Body of the response: " + responseBody);
}
else
{
Console.WriteLine("Request error. Response status: " + response.StatusCode);
}
}
catch (Exception e)
{
Console.WriteLine("Erro: " + e.Message);
}
}
}
package main
import (
"bytes"
"fmt"
"net/http"
)
func main() {
apiURL := "https://api.cadastro.uat.unico.app/client/v1/process/"
token := "<YOUR_TOKEN_HERE>";
// Create the request body in JSON format
requestBody := []byte(`{
"callbackUri": "/path/to/url",
"flow": "id",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "73689290074"
},
"purpose": "creditprocess"
}`)
// Create an HTTP client
client := &http.Client{}
// Create an HTTP POST request
req, err := http.NewRequest("POST", apiURL, bytes.NewBuffer(requestBody))
if err != nil {
fmt.Println("Error when creating HTTP request:", err)
return
}
// Set the request headers
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("accept", "application/json")
// Make the HTTP request
resp, err := client.Do(req)
if err != nil {
fmt.Println("Error when making HTTP request:", err)
return
}
defer resp.Body.Close()
// Check the response status
if resp.StatusCode == http.StatusOK {
// Reading the response body
var responseBody []byte
_, err := resp.Body.Read(responseBody)
if err != nil {
fmt.Println("Error reading the body of the answer:", err)
return
}
fmt.Println("Response status:", resp.Status)
fmt.Println("Body of the response:", string(responseBody))
} else {
fmt.Println("Request Error. Response status:", resp.Status)
}
}
Request executed successfully
If the request was successful, the return response is a 200 OK
and a JSON containing the following parameters:
{
"process": {
"id": "057f8d90-6ff6-4f52-ba05-ead6123f73bd",
"flow": "idcheck",
"callbackUri": "https://unico.io",
"userRedirectUrl": "https://cadastro.dev.unico.app/process/6291d10b-0450-453e-a5e8-5a6b2fe060e0",
"state": "PROCESS_STATE_CREATED",
"createdAt": "2024-07-18T18:34:30.328743Z",
"expiresAt": "2024-07-25T18:34:30.328743Z",
"person": {
"duiType": "DUI_TYPE_BR_CPF",
"duiValue": "73689290074",
"friendlyName": "John Doe"
},
"purpose": "creditprocess",
"authenticationInfo": {},
"capacities": [
"PROCESS_CAPACITY_IDLIVE",
"PROCESS_CAPACITY_IDUNICO",
"PROCESS_CAPACITY_IDCHECK"
],
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
}
The return parameters are:
Name | Description |
---|---|
id | The process identifier. |
flow | Defines the journey that was created. id : Identity validation flow with facial biometrics. idcheck : Identity validation flow with facial biometrics with score in the case of inclusion. iddocs : Identity validation flow with document capture and reuse (RG or CNH). idsign : Identity validation flow with electronic signature.iddocssign : Identity validation flow, capture/reuse of documents (RG or CNH) and electronic signature. |
callbackUri | Defines where the user will be redirected at the end of the process. More details in Request Parameters. |
userRedirectUrl | URL where you should redirect the user to complete the journey |
state | Indicates the current state of the process, as it is of the type: PROCESS_STATE_CREATED : Process created and not yet finished by the user. PROCESS_STATE_FINISHED : Process completed by the user successfully. PROCESS_STATE_FAILED : Process created or terminated with error. |
result | Indicates the result of the user journey process, which may be of the type: PROCESS_RESULT_OK : Process completed successfully. PROCESS_RESULT_WARNING : Process ended with alert. PROCESS_RESULT_ERROR : Process ended with some type of error. PROCESS_RESULT_UNSPECIFIED : It is returned when the client uses the IDUnico alone. Process ended with unspecified result. |
person.personDuiType | Defines the user identifier type. DUI_TYPE_BR_CPF : For CPF as identifier. |
person.personDuiValue | Sets the value of the user identifier specified in the personDuiType field. |
person.friendlyName | Sets the user name, for example, John Doe . |
createdAt | Indicates the moment the process was created. |
expiresAt | Indicates the moment when the process will expire/has expired, and the value of this field is calculated from the expires_in field provided during the creation of the process, based on the creation date, created_at . |
token | Signed token that contains the necessary parameters to initialize the by Unico web SDK, allowing integration via iFrame. |
Request error
For information on the errors returned, see the list available in the article Response Errors.
For more information about this endpoint, consult the API Reference.
Example of contextualization in the interface
Any concerns?
Missing something or still need help? If you are already a customer or partner, you can contact us through the Help Center.