Create Verification Request

Create a new verification request to verify someone's identity. This endpoint handles the complete verification flow including user creation, token generation, and notification delivery.

Request Format

POST https://api.vericato.com/v1/verifications/new
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Request Body

{
  "email": "[email protected]",
  "name": "John Doe",
  "chosenPurpose": "identity_verification",
  "phonenumber": "+32471234567",
  "smsNotification": true,
  "language": "en",
  "shareableLink": false,
  "emailNotification": true
}

Request Parameters

Parameter	Type	Required	Description
`email`	string	Yes / No*	Email address of the person to verify. *Email is not required if shareableLink is true
`name`	string	Yes	Full name of the person to verify
`chosenPurpose`	string	Yes	Purpose of the verification. There are 3 predefined ones: "legal_obligations", "processing_gdpr_request" and "ensuring_compliance". You can also input your own like e.g. "This is a custom reason"
`phonenumber`	string	No	Phone number in international E.164 format (e.g., "+31612345678")
`smsNotification`	boolean	No	Whether to send SMS notifications (default: false)
`language`	string	Yes	Language code for communications: `en`, `fr`, or `nl`
`shareableLink`	boolean	No	If true, returns a verification link instead of sending email (default: false)
`emailNotification`	boolean	No	Whether to send email notification (default: true)

Response

Standard Response (emailNotification: true, shareableLink: false):

{
  "message": "Verification request created successfully",
  "verificationId": "abc123def456"
}

Shareable Link Response (shareableLink: true):

{
  "message": "Verification request created successfully",
  "verificationId": "abc123def456",
  "link": "https://[URL_TO_VERIFICATION]"
}

Example Requests

This example will create a new verification request and will send an email and a SMS to the person you want to verify themselves.

JavaScript/TypeScript

const response = await fetch('https://api.vericato.com/v1/verifications/new', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${API_KEY}`
  },
  body: JSON.stringify({
    email: "[email protected]",
    name: "John Doe",
    chosenPurpose: "legal_obligations",
    phonenumber: "+32472345678",
    smsNotification: true,
    language: "en",
    emailNotification: true
  })
});

const data = await response.json();
console.log('Verification ID:', data.verificationId);

Python

import requests

url = "https://api.vericato.com/v1/verifications/new"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}
payload = {
    "email": "[email protected]",
    "name": "John Doe",
    "chosenPurpose": "legal_obligations",
    "phonenumber": "+32472345678",
    "smsNotification": True,
    "language": "en",
    "emailNotification": True
}

response = requests.post(url, json=payload, headers=headers)
data = response.json()
print(f"Verification ID: {data['verificationId']}")

cURL

curl -X POST https://api.vericato.com/v1/verifications/new \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "email": "[email protected]",
    "name": "John Doe",
    "chosenPurpose": "identity_verification",
    "phonenumber": "+32472345678",
    "smsNotification": true,
    "language": "en",
    "emailNotification": true
  }'

Shareable Links

When shareableLink is set to true, the API returns a verification link that you can share through your own channels:

{
  "message": "Verification request created successfully",
  "verificationId": "abc123def456",
  "link": "https://[URL_TO_VERIFICATION]"
}

Data Retention

Verification requests are automatically managed based on your organization's retention settings:

Verification Retention: Configurable in your dashboard
Log Retention: Separate retention period for audit logs
Token Validity: Configurable expiration for verification tokens

All retention periods can be configured in your organization settings.

Error Handling

Status Code	Description
200	Verification request created successfully
403	Unauthorized - Invalid or missing API key
500	Server error - Check error message for details

Error Response Format

{
  "error": "Error message description"
}

Best Practices

Validate Input Data

// Validate email format
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
if (!emailRegex.test(email)) {
  throw new Error('Invalid email format');
}

// Validate phone number (E.164 format)
const phoneRegex = /^\+[1-9]\d{1,14}$/;
if (phonenumber && !phoneRegex.test(phonenumber)) {
  throw new Error('Invalid phone number format');
}

Store Verification IDs
- Save the returned verificationId
- Use it to check verification status later
- Link it to your own user/order records if necessary
Use Webhooks
- Set up webhooks to receive real-time status updates
- Avoid polling the GET endpoint repeatedly
- Handle webhook events asynchronously

Further Information

Get verification details to check status
Set up webhooks for real-time updates
Configure retention settings in your dashboard

Create Verification Request

On this page