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": []

}

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.: 551190000-0000
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.
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.

Note

(*) The person.phone parameter becomes Mandatory when the notifications.notificationChannel field is filled in.

Request example

{
  "callbackUri": "/path/to/url",
  "flow": "idcheck",
  "person": {
    "duiType": "DUI_TYPE_BR_CPF",
    "duiValue": "73689290074"
  },
  "purpose": "biometryonboarding",
  "payload": [
    {
      "envelopePayload": {
        "documents": [
          {
            "documentName": "test",
            "fileContents": "JVBERi0xLjMNCiXi48/[...]DQoNCnN0YXJ0eHJlZg0KMjcxNA0KJSVFT0YNCg=="
          }
        ]
      }
    }
  ]
}

For more examples, see Request Examples

Ways of making a request (request)

cURL

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"
}'

Postman

To use Postman, follow these steps:

1. Select the POST method.
2. Enter the URL https://api.cadastro.uat.unico.app/client/v1/process/.
3. Select the Authorization tab.
4. In the Type list, select Bearer Token.
5. Enter the token obtained in the Token field with the prefix Bearer.
6. 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"
}

NodeJS

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);
  });

Java

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();
        }
    }
}

C#

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);
        }
    }
}

Go

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",
    "company": {
      "code": "unico",
      "friendlyName": "Orquestrador",
      "logoUrl": "https://unico.io/wp-content/themes/theme_unico/img/logo/unico-color.svg"
    },
    "callbackUri": "https://unico.io",
    "userRedirectUrl": "https://cadastro.dev.unico.app/process/057f8d90-6ff6-4f52-ba05-ead6123f73bd",
    "state": "PROCESS_STATE_FINISHED",
    "result": "PROCESS_RESULT_OK",
    "person": {
      "duiType": "DUI_TYPE_BR_CPF",
      "duiValue": "11693205629",
      "friendlyName": "Rodrigo"
    },
    "purpose": "creditprocess",
    "authenticationInfo": {
      "authenticationResult": "AUTHENTICATION_RESULT_INCONCLUSIVE",
      "scoreEngineResult": {
        "scoreEnabled": "SCORE_ENABLED_TRUE",
        "score": 50
      }
    },
    "createdAt": "2023-08-09T15:15:09.751991Z",
    "finishedAt": "2023-08-09T15:15:25.417105Z"
  }
}

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.
company.code	Flags the company code in the Unico ecosystem.
company.friendlyName	Flags the customer name displayed in the user journey.
company.logoUrl	Flags the customer logo displayed in the user journey.
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.
authenticationInfo.authenticationResult	Result of identity validation using ID. AUTHENTICATION_RESULT_UNSPECIFIED: Waiting for the authentication process to return. AUTHENTICATION_RESULT_INCONCLUSIVE: Inconclusive authentication result. AUTHENTICATION_RESULT_POSITIVE: Positive authentication result.
authenticationInfo.authenticationResult. scoreEngineResult.scoreEnabled	Indicates whether the process has Check enabled in case the ID is inconclusive. SCORE_ENABLED_TRUE: Enabled. SCORE_ENABLED_FALSE: Disabled.
authenticationInfo.authenticationResult. scoreEngineResult.score	Indicates the result of the Check score. 0: If disabled. -100 to 100: score result.
createdAt	Indicates the moment the process was created.
finishedAt	Indicates the moment at which the process was completed by the user.

Request error

For information on the errors returned, see the list available in the article Response Errors.

Any concerns?

Missing something or still need help? If you are already a customer or partner, you can contact us through the Help Center.