# Create Process {% hint style="info" %} **URL Base**: * UAT: `https://api.cadastro.uat.unico.app`. * Production: `https://api.cadastro.unico.app`. {% endhint %} ## Create Process > Endpoint to create a new process at Unico. ```json {"openapi":"3.0.0","info":{"title":"CreateProcess","version":"1.0.0"},"servers":[{"url":"https://api.cadastro.uat.unico.app"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/client/v1/process":{"post":{"summary":"Create Process","description":"Endpoint to create a new process at Unico.","requestBody":{"description":null,"required":true,"content":{"application/json":{"schema":{"type":"object","required":["callbackUri","flow","purpose"],"properties":{"callbackUri":{"type":"string","required":true,"description":"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 '/')."},"flow":{"type":"string","enum":["idlive","id","idlivetrust","idcheck","iddocs","idsign","iddocssign","idchecktrust","idchecktrustdocs","idchecktrustsign","idchecktrustdocssign","idcheckserpro","idcheckserprodocs","idcheckserprodocssign","creditoconsignado","idtrust","idunicodocs","idunicosign","idunicodocssign","idunicoserprodocssign","idtrustdocs","idtrustsign","idtrustdocssign","idtoken","idtokentrust","idtokensign","idsmart","idage","idagedocumentless"],"required":true,"description":"Flow type. See flow details in the 'Overview' section of this documentation."},"flow_config":{"type":"object","properties":{"biometry_capture":{"type":"object","properties":{"enabled_back_camera":{"type":"boolean","description":"Indicates whether the journey of this process will use the device's rear camera. Important: 1. If this parameter is not sent, the front camera will be used by default; 2. The selected camera will be maintained throughout the journey, and it will not be possible to change it after it has started; 3. The use of the rear camera is not compatible with journeys that involve document capture and/or electronic signature."}}}}},"clientReference":{"type":"string","required":true,"description":"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."},"companyBranchId":{"type":"string","required":true,"description":"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."},"bioTokenId":{"type":"string","required":false,"description":"Biometric token identification. Mandatory for the \"idtoken\" flow and must use an ID from a completed process of any other identity verification flow."},"useCase":{"type":null,"description":"Use case identification. Mandatory for the \"idsmart\" flow.","enum":["USE_CASE_LOGIN","USE_CASE_IDENTITY_REVALIDATION_30_MINUTES","USE_CASE_IDENTITY_REVALIDATION_7_DAYS","USE_CASE_ACC_MANAGEMENT","USE_CASE_SENSITIVE_ACC_MANAGEMENT","USE_CASE_FIN_TRANSACTIONS","USE_CASE_SENSITIVE_FIN_TRANSACTIONS","USE_CASE_SENSITIVE_FIN_SERVICES","USE_CASE_CUSTOM","USE_CASE_SENSITIVE_CUSTOM"]},"person":{"type":"object","description":"User information.","required":["duiType","duiValue"],"properties":{"duiType":{"type":"string","required":true,"enum":["DUI_TYPE_BR_CPF","DUI_TYPE_MX_CURP","DUI_TYPE_US_SSN"],"description":"Identification document type. Possible values: 'DUI_TYPE_BR_CPF' - if you want to use the brazilian CPF as a identifier; 'DUI_TYPE_MX_CURP' - if you want to use the mexican CURP as a identifier; 'DUI_TYPE_US_SSN' - if you want to use the american SSN as a identifier."},"duiValue":{"type":"string","required":true,"description":"Identification document value (e.g., CPF number). Must be sent without dots or dashes."},"friendlyName":{"type":"string","required":false,"description":"User's name."},"phone":{"type":"string","required":false,"description":"User's phone number. Mandatory if sending a notification via SMS or WhatsApp. Must contain 13 characters and be sent without dots or dashes, in the DDI + DDD + phone number format."},"email":{"type":"string","required":false,"description":"The person's email address. It becomes mandatory if the 'Electronic Signature' capability is used."},"notifications":{"type":"array","description":"Notification information. This parameter is not required if notifications are not needed.","items":{"type":"object","properties":{"notificationChannel":{"type":"string","required":false,"description":"Notification channel. Possible values: NOTIFICATION_CHANNEL_WHATSAPP; NOTIFICATION_CHANNEL_SMS; NOTIFICATION_CHANNEL_EMAIL (it's also possible to send notifications to multiple channels by informing more than one)."}}}}}},"purpose":{"type":"string","enum":["creditprocess","biometryonboarding","carpurchase"],"required":true,"description":"Purpose of the process."},"expiresIn":{"type":"string","required":true,"description":"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."},"contextualization":{"type":"object","description":"Contextual information about the process. These fields are presented in the user journey, improving conversion by contextualizing the reason for biometric capture.","properties":{"currency":{"type":"string","enum":["BRL","MXN","USD"],"description":"Currency that will be used for the format of the price field. Possible values: 'BRL' for processes carried out in Brazil, 'MXN' for processes carried out in Mexico, and 'USD' for processes carried out in the United States."},"price":{"type":"number","description":"Defines the value displayed in the process contextualization."},"locale":{"type":"object","required":false,"description":"Object that defines the location and language of the process, along with the corresponding reason message. Each key in the object represents a supported locale code (ptBr, enUs, esMx).","properties":{"ptBr":{"type":"object","properties":{"reason":{"type":"string","description":"Reason for the process in Portuguese (Brazil)."}}}}}}},"payload":{"type":"array","description":"Array containing document information. All items in the array become mandatory if using any flow with electronic signature.","items":{"type":"object","properties":{"envelopePayload":{"type":"object","description":"Object containing document information. Only one envelope per payload is allowed, but multiple documents can be included in the same envelope.","properties":{"documents":{"type":"array","description":"Document information. Multiple documents can be included in the same envelope.","items":{"type":"object","properties":{"documentName":{"type":"string","required":false,"description":"Name of the document to be signed."},"fileContents":{"type":"string","required":false,"description":"Document to be signed, encoded in base64."}}}}}}}}}}}}}},"responses":{"200":{"description":"Process successfully created.","content":{"application/json":{"schema":{"type":"object","properties":{"process":{"type":"object","description":"Information about the Unico process.","properties":{"id":{"type":"string","description":"Process ID."},"companyBranchId":{"type":"string","description":"The ID of the branch where the process was created. If no value was provided for companyBranchId, this parameter will not be returned in the response."},"flow":{"type":"string","description":"Selected flow."},"callbackUri":{"type":"string","description":"Callback URI."},"userRedirectUrl":{"type":"string","description":"URL for the user journey."},"state":{"type":"string","enum":["PROCESS_STATE_CREATED","PROCESS_STATE_FAILED"],"description":"Process state. Possible values: 'PROCESS_STATE_CREATED' - Process created; 'PROCESS_STATE_FAILED' - Process failed."},"createdAt":{"type":"string","description":"Process creation date."},"person":{"type":"object","description":"User information.","properties":{"duiType":{"type":"string","description":"Identification document type."},"duiValue":{"type":"string","description":"Identification document value."},"friendlyName":{"type":"string","description":"User's name."},"phone":{"type":"string","description":"User's phone number."},"email":{"type":"string","description":"User's email."},"notifications":{"type":"array","description":"Notification information.","items":{"type":"object","properties":{"notificationChannel":{"type":"string","description":"Notification channel."}}}}}},"purpose":{"type":"string","enum":["creditprocess","biometryonboarding","carpurchase","ageverification"],"description":"Process purpose."},"authenticationInfo":{"type":"object","description":"Authentication information.","properties":{}},"capacities":{"type":"array","description":"Process capacities.","items":{"type":"string"}},"expiresAt":{"type":"string","description":"Process expiration date."},"token":{"type":"string","description":"Signed token containing the necessary parameters to initialize the Unico web SDK."},"companyData":{"type":"object","description":"Information about the company where the process was created. Refers to the 'companyBranchId' field.","properties":{"branchId":{"type":"string"},"countryCode":{"type":"string"}}},"clientReference":{"type":"string","required":true,"description":"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."},"webAppToken":{"type":"string","description":"Signed token containing the necessary parameters to initialize the Unico native SDK."}}}}}}}},"400":{"description":"When some parameter are wrong.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"message":{"type":"string","description":"Error description."},"details":{}}}}}},"401":{"description":"Access-token error.","content":{"application/json":{"schema":{"type":"string","description":"Error description."}}}},"500":{"description":"Unexpected error (Internal error or parameter issue).","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","description":"Error code."},"message":{"type":"string","description":"Error description."},"details":{}}}}}}}}}}} ``` {% hint style="warning" %} * 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. * It is possible to use the Age Validation feature with or without the identifier (`DUI_TYPE`). * If you use the `idage` flow, the identifier is mandatory. * If you use the `idagedocumentless` flow, the identifier is optional. * Do not parse or modify the URL provided for the created process, as any changes may break or directly affect the user experience. Please note that this URL may change at any time without notice. {% endhint %} ### Errors {% tabs %} {% tab title="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. | | {% endtab %} | | | {% tab title=" 401 Unauthorized" %} | message | description | | ------------------------------- | --------------------------------------------------------- | | `Jwt header is an invalid JSON` | When the access token used contains incorrect characters. | | `Jwt is expired` | When the access token used has expired. | | {% endtab %} | | {% tab title="429 Too Many Requests" %} No detailed error code will be provided for this situation, only the HTTP status code. {% endtab %} {% tab title="500 Internal Server Error" %}
codemessagedescription
99999Internal failure! Try again laterWhen there is an internal error.
{% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://devcenter.unico.io/unico-idcloud/by-unico-integration/by-unico-api/api-reference/create-process.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.