ID Dataweb API

Overview

The ID Dataweb API is a stateless REST API that lets you verify user identities without redirecting users to a hosted UI. Your application collects the identity attributes, submits them to the API, and receives a structured response containing a policy decision, acquired attributes, and per-checker assertions.

The API can verify four distinct aspects of a user:

1. Human identity — Digitally verify identity in 40+ countries using country-specific techniques.
2. Affiliation — Verify employment, education, or other organizational affiliations.
3. Device — Collect device identifiers and evaluate against a global fraud prevention network. (Requires a small JavaScript snippet on your registration or login page.)
4. Location — Collect IP address and network signals and evaluate against fraud intelligence. (Requires the same JavaScript snippet as Device.)

How It Works

sequenceDiagram
    participant User
    participant YourApp as Your Application
    participant IDWAPI as ID Dataweb API
    participant Checkers as Checkers

    YourApp->>IDWAPI: POST /token (client_id + secret → access token)
    YourApp->>User: Collect identity attributes
    User-->>YourApp: PII, device data, etc.
    YourApp->>IDWAPI: POST /slverify (access token + attributes)
    IDWAPI->>Checkers: Run configured verification checks
    Checkers-->>IDWAPI: Results
    IDWAPI-->>YourApp: policyDecision + acquiredAttributes + assertions
    YourApp->>YourApp: Act on policyDecision

Authentication

The ID Dataweb API uses the OAuth2 client credentials flow. You must obtain a short-lived access token before making API calls. The API key used for authentication determines which workflow is evaluated.

Credentials

Obtain your API Key and Shared Secret from the Admin Console. The API key specifies the workflow (and associated policy) to evaluate.

Token Request

(POST) https://api.preprod.iddataweb.com/v1/token?grant_type=client_credentials

POST /v1/token?grant_type=client_credentials HTTP/1.1
Host: api.preprod.iddataweb.com
Authorization: Basic <Base64(apiKey:sharedSecret)>
Cache-Control: no-cache

Encode apiKey:sharedSecret as a Base64 string and pass it as HTTP Basic Auth.

Token Response

{
  "errorCode": "",
  "errorDescription": "",
  "access_token": "HXaIThPrEwQ0IejcDVKGsBUvR10A9uodkxqgG_U-7kU",
  "expires_in": "600",
  "token_type": "Bearer"
}

Tokens are valid for 10 minutes by default. A single token can be reused for its entire lifetime.

Using the Token

Include the access token in the Authorization header of all subsequent requests:

Authorization: Bearer <valid-access-token>

API Call Patterns

Single-Step Workflow

For simple workflows, a single /slverify call collects attributes and returns a policy decision:

POST /v1/slverify HTTP/1.1
Host: api.preprod.iddataweb.com
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "apikey": "your-api-key",
  "credential": "[email protected]",
  "userAttributes": [
    {
      "attributeType": "FullName",
      "values": { "fname": "Jane", "lname": "Smith" }
    },
    {
      "attributeType": "InternationalAddress",
      "values": {
        "country": "US",
        "administrative_area_level_1": "VA",
        "locality": "Arlington",
        "postal_code": "22201",
        "route": "Main Ave",
        "street_number": "123"
      }
    }
  ]
}

Multi-Step Workflow

Most verification workflows require multiple API calls — for example, a PII verification step followed by a phone OTP step. Use the session tracking pattern described below to link calls across steps.

When a step returns policyDecision: "obligation", the response includes forwardApiKey — the API key for the next step in the workflow. Your application should load the appropriate UI and submit the required data to /slverify using the forwardApiKey value as the apikey input. See Interpreting Results — API for full obligation handling details.

Session Tracking

Linking multiple API calls into a single session is critical for accurate reporting, billing, and analytics in the Admin Console.

Track Users with credential

Include the credential field in every API call for a user. This can be an email address, a UUID, or any identifier you use to uniquely represent the user. This value will appear in reporting and billing.

{
  "apikey": "12345",
  "credential": "[email protected]"
}

If multiple credential values are used across calls, the system tracks the last-used credential for reporting.

Link Sessions with asi

For multi-step workflows, link all calls together using the Application Session Identifier (ASI).

First call — retrieve transaction_id from the response:

{
  "errorCode": "",
  "errorDescription": "",
  "transaction_id": "76ceb32b-yyyy-xxxx-zzzz-55e54bf93fc3"
}

All subsequent calls — pass transaction_id from the first response as asi in the request body:

{
  "asi": "76ceb32b-yyyy-xxxx-zzzz-55e54bf93fc3",
  "apikey": "67890",
  "credential": "[email protected]"
}

This consolidates all steps of a user's journey into a single session visible in reporting and Admin Console analytics.

Error Handling

API errors are returned in the response body with an errorCode and errorDescription:

{
  "errorCode": "DATA_VALIDATION_ERROR",
  "errorDescription": "Missing attribute. This service requires attribute FullName but it was not found. Please check your inputs and retry."
}

Common Error Codes

Postman Setup

Postman collection available — A pre-built Postman collection covering authentication, /slverify, OTP, and other API endpoints is available. Contact your ID Dataweb team to request it.