Parameter Specification

In this section, you will find the specification of all the parameters for the REST API of the by Unico integration


CreateProcess - Request Payload


NameTypeMandatory/ OptionalDescription

flow

string

Mandatory

Define the journey to be executed.

idlive: Flow with liveness, without identity validation.

id: Identity validation flow with facial biometrics.

idcheck: Identity validation flow with facial biometrics and scoring in case of inconclusive results.

iddocs: Identity validation flow with document capture and reuse (RG or CNH).

idsign: Identity validation flow with electronic signature.

iddocssign: Identity validation flow, document capture/reuse (RG or CNH), and electronic signature.

idcheckserpro: SERPRO consultation flow and identity validation with facial biometrics and scoring in case of inconclusive results.

idtoken: Flow to verify the authenticity of facial biometrics in relation to a previously conducted process.

callbackUri

string

Mandatory

Define where the user will be redirected at the end of the process.

  • URL: You can use a URL to a web page in your flow. Example: https://developers.unico.io/callback. You can customize it as desired.

  • URL Scheme: You can also redirect to native mobile applications. Example: br.com.myapp.app://callback. This callback must be registered in your mobile application.

  • No Redirection: If you are using the solution in a messaging flow, use the value / to avoid redirection at the end of the flow.

To learn more about how to redirect the user, see the section "Redirecting the User" here.

person.personDuiType

string

Mandatory

Define the type of user identifier.

  • DUI_TYPE_BR_CPF: To use CPF (Cadastro de Pessoas Físicas) as the identifier.

person.personDuiValue

string

Mandatory

Define the value of the user identifier specified in the personDuiType field.

Example: In the case of using the identifier DUI_TYPE_BR_CPF, provide a valid CPF without formatting: 73689290074.

Note: This is mandatory for SMS and WhatsApp flows.

person.friendlyName

string

Optional

DDefine the name of the user. Ex.: Luke Skywalker.

person.phone

string

Optional(*)

Define the user's phone number. Ex.: 5511900000000

person.email

string

Optional(*)

Define the user's email address.

notifications.notificationChannel

string

Optional

notifications: This is an array that defines the channels for sending notifications. This field should be filled with the desired notification types: SMS, WhatsApp, or both channels.

Example of usage:

{
        "notificationChannel": "NOTIFICATION_CHANNEL_SMS"
    },
    {
        "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP"
    }
]

Notes:

  • If you are only sending a URL, do not include the notifications field.

  • Make sure to choose the appropriate channels based on user preferences and the requirements of your integration process.

purpose

string

Mandatory

Define the purpose of use and data collection for the user. This is aimed at providing transparency and ensuring the proper handling of data according to LGPD (General Data Protection Law).

Purpose Options:

  • creditprocess: If you are using the solution to offer credit to the user.

  • biometryonboarding: If you are using the solution for user onboarding.

  • carpurchase: If you are using the solution related to the purchase of a vehicle.

Example Usage:

"purpose": "creditprocess"

Notes:

  • Ensure that the purpose is clearly stated and relevant to the user’s interaction with your service.

  • This information should be included in the data processing agreement to comply with LGPD regulations.

bioTokenId

string

Optional(**)

Define the ID of the transaction 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 the authenticationInfo.authenticationId from the process returned when performing the GetProcess of an idcheck process.

payload

array

Mandatory

The payload field is an array that provides a location for inserting files necessary for 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 one or more.

Each document object has:

  • documentName: Name of the document.

  • fileContents: Base64 of the PDF to be signed.

This field is mandatory when using the electronic signature capability.

expiresIn

string

Optional

This field defines the time in seconds for the expiration of the process, based on the created_at date. For example, for the expiration to occur in 7 days, it is necessary to specify as "expires_in": "10080s". If no value is provided, the default value set for the client will be used; if this value does not exist, the default value of 7 days will be applied.

contextualization.price

float

Optional

This field defines the value that will be displayed in the process contextualization.

contextualization.currency

string

Optional(***)

Esse campo define a moeda que será uThis field defines the currency that will be used for formatting the price field.

contextualization.locale.ptBr.Reason

string

Optional

This field defines the information that will be displayed in the Reason field of the process when the pt-br language is selected.

contextualization.locale.enUs.Reason

string

Optional

This field defines the information that will be displayed in the Reason field of the process when the en-us language is selected.

contextualization.locale.esMx.Reason

string

Optional

This field defines the information that will be displayed in the Reason field of the process when the es-mx language is selected.

GetProcess - Request Response


NameTypeDescription

id

string

The identifier of the process.

flow

string

Indicates the journey that was created.

idlive: Flow with liveness, without identity validation.

id: Identity validation flow with facial biometrics.

idcheck: Identity validation flow with facial biometrics and a score in case of inconclusive results.

iddocs: Identity validation flow with document capture and reuse (RG or CNH).

idsign: Identity validation flow with electronic signature.

iddocssign: Identity validation flow, document capture/reuse (RG or CNH), and electronic signature.

idcheckserpro: Consultation flow in SERPRO and identity validation with facial biometrics and a score in case of inconclusive results.

idtoken: Flow to verify the authenticity of a facial biometrics in relation to a previously completed process.

callbackUri

string

Indicates where the user will be redirected at the end of the process.

userRedirectUrl

string

Indicates the URL to which you should redirect the user to complete the journey.

state

string

Indicates the current state of the process, which can be of the type:

PROCESS_STATE_CREATED: Process created and not yet completed by the user.

PROCESS_STATE_FINISHED: Process successfully completed by the user.

PROCESS_STATE_FAILED: Process encountered an error.

result

string

IIndicates the result of the user's journey process, which can be of the type:

PROCESS_RESULT_OK: Process successfully completed.

PROCESS_RESULT_ERROR: Process completed with some type of error.

PROCESS_RESULT_INVALID_IDENTITY: Process completed with a failure in liveness, or inconclusive result when flow = ID, or when in flow = IDCheck, there was a divergence taking longer than the established time.

PROCESS_RESULT_UNSPECIFIED: Returned when the client uses IDUnico alone. Process completed with unspecified result.

createdAt

string

Indicates the moment when the process was created.

finishedAt

string

Indicates the moment when the process was completed.

person.personDuiType

string

Indicates the type of identifier for the user.

DUI_TYPE_BR_CPF: For CPF as the identifier.

person.personDuiValue

string

Indicates the value of the user identifier specified in the personDuiType field.

person.email

string

Indicates the email value of the user specified in the email field during the process creation.

person.phone

string

IndiIndicates the phone number value of the user specified in the phone field during the process creation.

person.friendlyName

string

IIndicates the name of the user, for example, Luke Skywalker.

notifications.notificationChanell

string

Indicates the channel used for sending notifications during the creation of the process.

purpose

string

Indicates the purpose of collecting the user's data at the time the process was created.

authenticationInfo.authenticationResult

string

It refers to the Identity Verification capability.

AUTHENTICATION_RESULT_UNSPECIFIED: This is returned when the client uses Identity Verification alone. Possible return situations include:

  • The user could not be found in the authenticated database.

  • There was no timely response from the orchestration with the risk score (by Unico waits up to 60 seconds for conflict resolutions).

AUTHENTICATION_RESULT_INCONCLUSIVE: Result of an inconclusive authentication.

AUTHENTICATION_RESULT_POSITIVE: Result of a positive authentication.

authenticationInfo.scoreEngineResult.scoreEnabled

string

Indicates whether the Risk Score capability is enabled in this journey.

authenticationInfo.scoreEngineResult.score

integer

Indicates the Risk Score for cases where the Identity Verification response was inconclusive.

authenticationInfo.authenticationId

string

Indicates the ID of the process that derived to the Risk Score. It can be used in the idtoken flow as a value for the bioTokenId parameter.

authenticationInfo.livenessResult

string

Indicates the result of the liveness check.

LIVENESS_RESULT_UNSPECIFIED: Unexpected return.

LIVENESS_RESULT_NOT_LIVE: The user did not pass the liveness check.

LIVENESS_RESULT_LIVE: The user's liveness check was verified.

serproResult.score

integer

Indicates the result of the similarity score from SERPRO. Currently available only for the idcheckserpro flow.

services.documents.reused_doc

boolean

Indicates whether there was (true) or not (false) reuse of the document. A document is reused when it already exists in Unico's database and the user has granted permission to reuse it without the need for a new capture.

services.documents.cpf_match

boolean

Indicates whether the CPF in the request is the same as the document's CPF. If yes, (true); if no, (false).

services.documents.typified

boolean

Indicates whether the document was classified (true) or not (false). A document is classified when its layout can be identified.

services.documents.doc_id

string

Unique identifier of the shared document.

services.documents.signed_url

string

Indicates the signed URL of the document.

services.documents.validate_doc

boolean

Indicates whether the document was validated (true) or not (false).

services.documents.face_match

boolean

Indicates whether the person in the request photo is the same as the one on the document. If yes (true), if no (false).

services.documents.doc.version

integer

Indicates the version of document.

services.documents.doc.data

object

When the document is typed, it will return the extracted data from the document: RG: numero, orgaoEmissor, ufEmissor, cpfNumero, carteiraProfissionalNumero, certificadoMilitarNumero, cnsNumero, nisPisPasepNumero, ctpsNumero, ctpsSerie, ctpsUf, tituloEleitorNumero, nomeCivil, nomeSocial, filiacao, dataNascimento, naturalidade, dataEmissao. CIN: rgNumero, cpfNumero, nomeCivil, nomeSocial, filiacao, dataNascimento, dataExpiracao, dataEmissao, orgaoEmissor, localEmissao, naturalidade, nacionalidade. CNH: numero, rgNumero, cpfNumero, nomeCivil, filiacao, dataNascimento, dataHabilitacao, dataExpiracao, dataEmissao, localEmissao, categoria, renachNumero.

services.documents.doc.code

string

When typed, it will return RG, CIN, or CNH; if not, it will return "Unknown."

RG: Indicates that the shared document is of type RG.

CIN: Indicates that the shared document is of type CIN.

CNH: Indicates that the shared document is of type CNH.

A document is typed when it is possible to identify the layout of that document during the image capture.

services.consent_granted

boolean

Indicates whether there was (true) or was not (false) user consent.

services.envelope_id

string

Indicates the identifier of the electronic signature envelope.

services.document_ids

string

Indicates the identifier of the document that was signed during the journey.

capacities

string

Indicates which IDCloud capabilities were used in the respective process flow. It can have the following returns: PROCESS_CAPACITY_IDLIVE; PROCESS_CAPACITY_IDUNICO; PROCESS_CAPACITY_IDCHECK; PROCESS_CAPACITY_IDDOCS; PROCESS_CAPACITY_IDSIGN; PROCESS_CAPACITY_IDTOKEN; PROCESS_CAPACITY_IDSERPRO.

expiresAt

string

Indicates the moment when the process will have expired or has expired. The value of this field is calculated from the expires_in field provided during the process creation, along with the creation date of the process, created_at.

GetSelfie - Request Response


NomeTipoDescrição

fileContents

string

It is a Base64-encoded string that should be converted to an image file in your application.

contentType

string

Indicates that the content in fileContents is a jpeg or png image.

GetEvidenceSet - Request Response


NomeTipoDescrição

fileContents

string

It is a Base64-encoded string that should be converted to an image file in your application.

contentType

string

Indicates that the content in fileContents is a .pdf.


Still need help?

Didn't find something or still need help? If you're already a client or partner, you can reach out through our Help Center.

Atualizado

Institucional

Sobre nós

Copyright © 2024 unico. All rights reserved