Skip to main content
POST
/
verifications
Start verification
curl --request POST \
  --url https://api.urtentic.com/api/v1/verifications \
  --header 'Content-Type: application/json' \
  --data '
{
  "flowId": "40f85c69-b27a-46e8-9115-691401acb5df",
  "metadata": {
    "email": "[email protected]",
    "reference": "USER123",
    "customerId": "CUST-456",
    "deviceId": "D-789012"
  }
}
'
{
  "metadata": {
    "email": "[email protected]",
    "reference": "USER123"
  },
  "flowId": "40f85c69-b27a-46e8-9115-691401acb5df",
  "identityId": "32a5b2d6-7c9e-4815-a599-fd03d6b34c53",
  "verificationId": "85c94e71-6e3f-4a19-b15c-781d8a876542",
  "ipAddress": "192.168.1.1",
  "inputs": [
    {
      "fieldName": "SELFIE_VIDEO",
      "description": "A short video of your face for liveness detection",
      "group": 1,
      "fieldType": "FILE",
      "optional": false
    },
    {
      "fieldName": "DOCUMENT_TYPE",
      "description": "Select your ID document type",
      "group": 2,
      "fieldType": "DROPDOWN",
      "data": {
        "options": [
          "PASSPORT",
          "DRIVERS_LICENSE",
          "NATIONAL_ID"
        ]
      },
      "optional": false
    }
  ],
  "settings": [
    {
      "id": 123,
      "createdAt": "2023-06-15T14:30:00Z",
      "updatedAt": "2023-06-15T14:30:00Z",
      "value": "true",
      "fieldName": "GALLERY_RESTRICTION",
      "type": "BOOLEAN"
    }
  ]
}

Body

application/json

Request to start a new verification process. This initiates a verification workflow for a user and returns the verification configuration.

​
flowId
string<uuid>
required

ID of the workflow to be executed

Example:

"40f85c69-b27a-46e8-9115-691401acb5df"

​
metadata
object

Additional data to be associated with the verification. This information is stored with the verification record and can be used for tracking, correlation, or custom business logic.

Common metadata fields:

  • reference: Your internal reference ID
  • email: User's email address
  • userId: Your system's user identifier
  • deviceId: Device identifier
  • ipAddress: User's IP address (automatically captured if not provided)
  • redirectUrl: URL to redirect users after verification (if using redirect flows)
Example:
{
  "email": "[email protected]",
  "reference": "USER123",
  "customerId": "CUST-456",
  "deviceId": "D-789012"
}

Response

Verification started successfully

Response returned when starting a new verification. This contains all the information needed to guide the user through the verification process.

​
metadata
object

Additional metadata associated with the verification

Example:
{
  "email": "[email protected]",
  "reference": "USER123"
}
​
flowId
string<uuid>

Unique identifier of the workflow being used

Example:

"40f85c69-b27a-46e8-9115-691401acb5df"

​
identityId
string<uuid>

Unique identifier for the identity being verified

Example:

"32a5b2d6-7c9e-4815-a599-fd03d6b34c53"

​
verificationId
string<uuid>

Unique identifier for this verification attempt

Example:

"85c94e71-6e3f-4a19-b15c-781d8a876542"

​
ipAddress
string

IP address from which the verification was initiated

Example:

"192.168.1.1"

​
inputs
object[]

List of required input fields for the verification

Example:
[
  {
    "fieldName": "SELFIE_VIDEO",
    "description": "A short video of your face for liveness detection",
    "group": 1,
    "fieldType": "FILE",
    "optional": false
  },
  {
    "fieldName": "DOCUMENT_TYPE",
    "description": "Select your ID document type",
    "group": 2,
    "fieldType": "DROPDOWN",
    "data": {
      "options": [
        "PASSPORT",
        "DRIVERS_LICENSE",
        "NATIONAL_ID"
      ]
    },
    "optional": false
  }
]
​
settings
object[]

List of configuration settings for the verification

Example:
[
  {
    "id": 123,
    "createdAt": "2023-06-15T14:30:00Z",
    "updatedAt": "2023-06-15T14:30:00Z",
    "value": "true",
    "fieldName": "GALLERY_RESTRICTION",
    "type": "BOOLEAN"
  }
]