Advanced Features

Authorized URLs

Authorized URLs allow professionals to skip email verification when accessing their screening, providing a seamless experience when redirecting from your secure environment.

When to Use

Redirecting from your secure portal
Embedding in your application workflow
Professional already authenticated in your system

Generating an Authorized URL

POST https://[api-url]/mfa-prof/authorized-url
Authorization: Bearer YOUR_API_KEY
Authorization-Method: api-token
Content-Type: application/json

{
  "checkToken": "[token]"
}

Response:

{
  "authorizedUrl": "[url]"
}

Important Characteristics

Short validity: Valid for only a few minutes
Single use: Can only be used once
Auto-invalidation: Previous URLs invalidated when generating new one
Generate on-demand: Create during redirect, not in advance

Implementation Example

app.get('/redirect-to-screening/:checkToken', async (req, res) => {
  // Verify user is authenticated
  if (!req.session.authenticated) {
    return res.status(401).send('Unauthorized');
  }
  
  // Generate authorized URL
  const response = await fetch(
    'https://api.otentica.nl/mfa-prof/authorized-url',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Authorization-Method': 'api-token',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        checkToken: req.params.checkToken
      })
    }
  );
  
  const { authorizedUrl } = await response.json();
  
  // Immediately redirect
  res.redirect(authorizedUrl);
});

Logout Redirect Configuration

Configure logout redirect when creating flow:

{
  "firstName": "John",
  "lastName": "Doe",
  "logoutRedirectUrl": "https://yourapp.com/screening-logout",
  "requestedChecks": [...]
}

When professional logs out or session expires, they're redirected to your URL where you can generate a new authorized URL.

Security Notice

Only use authorized URLs when redirecting from your secure environment. You take full responsibility for access control. Ensure only the intended professional can access the URL.

File Downloads

Check results can contain files (e.g., identity documents, diplomas, certificates). Files are represented by UUIDs in the results and can be downloaded using the following endpoint.

Download Endpoint

GET https://[api-url]/files/[uuid]/download
Authorization: Bearer YOUR_API_KEY
Authorization-Method: api-token

File Types

Common file references in check results:

identityDocument - Front side of ID document
identityDocumentBackside - Back side of ID document
selfie - Selfie photo for liveness check
diplomas[].fileId - Diploma documents
Certificate uploads

Example Implementation

async function downloadFile(fileUuid) {
  const response = await fetch(
    `https://api.otentica.nl/files/${fileUuid}/download`,
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Authorization-Method': 'api-token'
      }
    }
  );
  
  if (!response.ok) {
    throw new Error(`Failed to download file: ${response.status}`);
  }
  
  // Get file content
  const blob = await response.blob();
  
  // Save or process the file
  return blob;
}

// Example: Download identity document from check results
async function downloadIdentityDocuments(checkResults) {
  const identityCheck = checkResults.checks.find(
    c => c.checkIdentifier === 'identity-document-v2'
  );
  
  if (identityCheck && identityCheck.status === 'SUCCESS') {
    for (const result of identityCheck.results) {
      if (result.fieldName === 'identityDocument' && result.value) {
        const file = await downloadFile(result.value);
        // Process the document file
        await saveFile(file, `id-document-${result.value}.jpg`);
      }
    }
  }
}

File Retention

Files are available until the screening expiry date
After expiry, files are permanently deleted per GDPR requirements
Download and store files in your system if needed for records

Style Templates

Customize the appearance of Otentica validation flows to match your brand.

Creating a Style

POST https://[api-url]/single-check-style
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
Authorization-Method: api-token

{
  "whitelabelStyleId": "yourStyleId",
  "logoUrl": "https://cdn.company.com/logo.png",
  "primaryColor": "#012345",
  "secondaryColor": "#546798",
  "primaryButtonColor": "#ABCDEF"
}

Style Properties

Property	Description	Requirements
`whitelabelStyleId`	Unique style identifier	Alphanumeric, no spaces
`logoUrl`	Company logo URL	JPG/PNG only, HTTPS required
`primaryColor`	Main brand color	6-character hex with #
`secondaryColor`	Secondary color	6-character hex with #
`primaryButtonColor`	Button color	6-character hex with #

Logo Format

Only JPG and PNG logos are supported. Other formats will cause report generation to fail.

Using Styles

Reference your style when creating flows:

{
  "whitelabelStyleId": "yourStyleId",
  "firstName": "John",
  "lastName": "Doe",
  "requestedChecks": [...]
}

Style Application

Your custom style applies to:

Validation flow interface
Email communications
Generated PDF reports

Multiple Styles

Create different styles for different purposes:

// Department-specific styles
const styles = {
  'hr-style': {
    logoUrl: 'https://cdn.company.com/hr-logo.png',
    primaryColor: '#065F46',
    secondaryColor: '#10B981'
  },
  'recruitment-style': {
    logoUrl: 'https://cdn.company.com/recruitment-logo.png',
    primaryColor: '#1E40AF',
    secondaryColor: '#3B82F6'
  }
};

// Use appropriate style
const flow = await createFlow({
  whitelabelStyleId: department === 'hr' ? 'hr-style' : 'recruitment-style',
  // ...
});

File Downloads

Download documents uploaded during screening.

Files are referenced by a fileId in the check values of the progress response, for example on a diploma.

Download a File

GET https://[api-url]/files/[fileId]/download
Authorization: Bearer YOUR_API_KEY
Authorization-Method: api-token

The response is the file itself, with its content type and file name in the headers.

Get a Temporary Download Link

To hand a file to a browser or another system without your API key, request a temporary link:

GET https://[api-url]/files/[fileId]
Authorization: Bearer YOUR_API_KEY
Authorization-Method: api-token

Response:

{
  "downloadUrl": "https://api.otentica.nl/files/9caf3ebd-460b-4583-9823-1e9309289192/download?accessToken=...",
  "thumbnail256Url": "https://api.otentica.nl/files/9caf3ebd-460b-4583-9823-1e9309289192/thumbnail/256.jpg?accessToken=...",
  "validUntil": "2023-12-18T16:06:52Z"
}

The links work without authentication headers and expire after 10 minutes.

Initial Values (Advanced)

Pre-fill verified data for specific checks. Use only after consulting with Otentica.

Use Case

When you've previously verified identity data and want to run only specific checks:

{
  "firstName": "John",
  "lastName": "Doe",
  "initialValues": {
    "dateOfBirth": {
      "value": "1990-01-15",
      "verified": true
    },
    "firstName": {
      "value": "John",
      "verified": true
    },
    "lastName": {
      "value": "Doe",
      "verified": true
    }
  },
  "requestedChecks": [
    {
      "checkName": "integrity-data",
      "importance": "NOT_SKIPPABLE"
    }
  ]
}

Critical Warning

Data in initialValues must be:

Correct and up-to-date
Previously verified
Official names (not nicknames)

Incorrect data can facilitate fraud. You take full responsibility for supplied data.

Batch Operations

For high-volume operations, consider:

Bulk Flow Creation

async function createBulkFlows(candidates) {
  const flows = await Promise.all(
    candidates.map(candidate => 
      createFlow({
        firstName: candidate.firstName,
        lastName: candidate.lastName,
        email: candidate.email,
        requestedChecks: standardChecks
      })
    )
  );
  
  return flows.map(flow => flow.checkToken);
}

Parallel Status Checking

async function checkMultipleFlows(tokens) {
  const results = await Promise.all(
    tokens.map(token => 
      fetch(`https://api.otentica.nl/validation-flow/check/${token}`, {
        headers: authHeaders
      }).then(res => res.json())
    )
  );
  
  return results;
}

Rate Limits

Flow creation: 100 per minute
Status checks: 1000 per minute
File downloads: 500 per minute

Implement exponential backoff for rate limit errors.

Authorized URLs​

When to Use​

Generating an Authorized URL​

Important Characteristics​

Implementation Example​

Logout Redirect Configuration​

File Downloads​

Download Endpoint​

File Types​

Example Implementation​

File Retention​

Style Templates​

Creating a Style​

Style Properties​

Using Styles​

Style Application​

Multiple Styles​

File Downloads​

Download a File​

Get a Temporary Download Link​

Initial Values (Advanced)​

Use Case​

Batch Operations​

Bulk Flow Creation​

Parallel Status Checking​

Rate Limits​

Authorized URLs

When to Use

Generating an Authorized URL

Important Characteristics

Implementation Example

Logout Redirect Configuration

File Downloads

Download Endpoint

File Types

Example Implementation

File Retention

Style Templates

Creating a Style

Style Properties

Using Styles

Style Application

Multiple Styles

File Downloads

Download a File

Get a Temporary Download Link

Initial Values (Advanced)

Use Case

Batch Operations

Bulk Flow Creation

Parallel Status Checking

Rate Limits