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

---

Schema

Name	Type	Mandatory/ Optional	Description
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.

Example

{
  "callbackUri": "/path/to/url",
  "flow": "iddocssign",
  "person": {
    "duiType": "DUI_TYPE_BR_CPF",
    "duiValue": "73689290074"
    "friendlyName": "Luke Skywalker",
    "phone": "5511974749090",
    "email": "[e-mail]",
    "notifications":
    [
      {
        "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP"
      },
      {
        "notificationChannel": "NOTIFICATION_CHANNEL_SMS"
      },
      {
        "notificationChannel": "NOTIFICATION_CHANNEL_EMAIL"
      }
    ]
  },
  "purpose": "biometryonboarding",
  "expiresIn": "3600",
  "payload": [
    {
      "envelopePayload": {
        "documents": [
          {
            "documentName": "teste",
            "fileContents": "JVBERi0xLjMNCiXi48/[...]xNA0KJSVFT0YNCg=="
          }
        ]
      }
    }
  ]
}

GetProcess - Request Response

---

Schema

Name	Type	Description
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.

Example

{
    "process": {
        "id": "53060f52-f146-4c12-a234-5bb5031f6f5b",
        "flow": "iddocssign",
        "callbackUri": "/path/to/callback-url/",
        "userRedirectUrl": "https://cadastro.dev.unico.app/process/53060f52-f146-4c12-a234-5bb5031f6f5b",
        "state": "PROCESS_STATE_FINISHED",
        "result": "PROCESS_RESULT_OK",
        "person": {
            "duiType": "DUI_TYPE_BR_CPF",
            "duiValue": "73689290074",
            "friendlyName": "John Doe",
            "notifications": [
                {
                    "notificationChannel": "NOTIFICATION_CHANNEL_WHATSAPP"
                },
                {
                    "notificationChannel": "NOTIFICATION_CHANNEL_SMS"
                }
            ],
        },
        "purpose": "creditprocess",
        "authenticationInfo": {
            "authenticationResult": "AUTHENTICATION_RESULT_INCONCLUSIVE",
            "scoreEngineResult": {
                "scoreEnabled": "SCORE_ENABLED_TRUE",
                "score": 50
            },
            "authenticationId": "fd433602-d496-4291-adbb-dda95a3e50b1",
            "livenessResult": "LIVENESS_RESULT_LIVE"
        },
        "capacities": [
            "PROCESS_CAPACITY_IDUNICO",
            "PROCESS_CAPACITY_IDCHECK",
            "PROCESS_CAPACITY_IDDOCS",
            "PROCESS_CAPACITY_IDSIGN",
            "PROCESS_CAPACITY_IDLIVE"
        ],
        "services": [
            {
                "documents": [
                    {
                        "doc": {
                            "version": 2,
                            "code": "RG",
                            "data": {
                                "dataExpiracao": "2025-10-35T00:00:00Z",
                                "dataHabilitacao": "2022-08-09T00:00:00Z",
                                "dataNascimento": "1950-06-30T00:00:00Z",
                                "nomeCivil": "John Doe",
                                "rgNumero": "5478854",
                                "categoria": "D",
                                "cpfNumero": "73689290074",
                                "dataEmissao": "2020-08-09T00:00:00Z",
                                "localEmissao": "DEREX SP",
                                "numero": "85775532778",
                                "renachNumero": ""
                            },
                        },
                        "typified": true,
                        "cpf_match": true,
                        "face_match": true,
                        "doc_id": "1e61a978-3673-4fdd-8fa8-808d0a26d131",
                        "validate_doc": true,
                        "reused_doc": true,                        
                        "signed_url": "https://api.datafortress.dev.private.unico.run/url-signer/signature/dmF1bHQ6[...]OXc9PQ%3D%3D"
                    }
                ],
                "consent_granted": true
            },
            {
                "envelopeId": "4d4f3d90-04a3-4259-b63b-930ab10d2e47",
                "documentIds": [
                    "03307601-b518-49ca-b368-ae3919e24e54"
                ]
            }
        ],
        "createdAt": "2023-10-05T18:28:58.537985Z",
        "finishedAt": "2023-10-09T15:15:25.417105Z",
        "expiresAt": "2023-10-09T15:15:25.417105Z"
    }
}

GetSelfie - Request Response

---

Schema

Nome	Tipo	Descriçã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.

Example

{
  "fileContents": "/9j/4AAQSkZJRgABAQA[...]QkeQUjE",
  "contentType": "image/jpeg"
}

GetEvidenceSet - Request Response

---

Schema

Nome	Tipo	Descriçã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.

Example

{
  "fileContents": "JVBERi0xLjUNCiWDk[...]NCg==",
  "contentType": "x-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.