API Integration Guide

Overview

The Partner API provides endpoints for managing verification sessions and steps for partner integrations. This API allows partners to create and manage verification sessions, handle data sources, and process verification steps.

Authentication

The Partner API uses two types of authentication:

  1. API Key Authentication: Required for endpoints that create sessions or access reviewer data

  2. CSRF Token Authentication: Required for endpoints that interact with an existing verification session

Headers

  • x-api-key: Your API key (required for API key authenticated endpoints)

  • x-csrf-token: CSRF token (required for CSRF protected endpoints)

Getting a CSRF Token

CSRF tokens are obtained through the verification link returned when creating a session. The verification link token is used to authenticate and establish a CSRF token for subsequent requests. CSRF tokens are valid for 15 minutes and are tied to a specific verification session.

Authentication Examples

API Key Authentication:

curl -X POST https://api.example.com/partner/session \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"params": {...}}'

CSRF Token Authentication:

curl -X GET https://api.example.com/partner/sources/session/123 \
  -H "x-csrf-token: your-csrf-token-here"

Endpoints

Get Verification Sources by Session

Retrieves all available verification sources for a specific session.

GET /partner/sources/session/:sessionId

Authentication: CSRF token required

Parameters

  • sessionId (path parameter): ID of the verification session

Response

[
  {
    "id": number,
    "name": string,
    "description": string,
    "sourceName": string,
    "logoUrl": string,
    // ... other source definition fields
  }
]

Error Response

{
  "statusCode": 500,
  "message": "Internal server error"
}

Create Verification Session

Creates a new verification session for partner integrations.

POST /partner/session

Authentication: API key required

Request Body

{
  "params": {
    "expiryDate": "2025-12-31T23:59:59.000Z",
    "metadata": {
      "customField1": "value1",
      "customField2": "value2"
    },
    "applicantId": "unique-applicant-identifier",
    "applicantData": {
      "age": 30,
      "location": "New York"
    },
    "instructions": "Please complete income verification using your latest pay stubs",
    "applicantFirstName": "John",
    "applicantLastName": "Doe",
    "applicantEmail": "[email protected]",
    "allowedSources": [
      {
        "id": 1,
        "name": "PayPal"
      },
      {
        "id": 2,
        "name": "Stripe"
      }
    ],
    "selectedPlatform": 1
  }
}

Request Parameters

  • expiryDate (required): ISO 8601 date string for when the session expires

  • metadata (optional): Custom metadata object to store additional information

  • applicantId (optional): Unique identifier for the applicant

  • applicantData (optional): Additional data about the applicant

  • instructions (optional): Custom instructions to display to the applicant

  • applicantFirstName (optional): Applicant's first name

  • applicantLastName (optional): Applicant's last name

  • applicantEmail (optional): Applicant's email address

  • allowedSources (optional): Array of allowed verification sources

  • selectedPlatform (optional): ID of the pre-selected platform

Response

{
  "success": true,
  "message": "Verification session created successfully",
  "data": {
    "id": 123,
    "status": "PENDING",
    "expiryDate": "2025-12-31T23:59:59.000Z",
    "applicantId": "unique-applicant-identifier",
    "applicantFirstName": "John",
    "applicantLastName": "Doe",
    "applicantEmail": "[email protected]",
    "metadata": {
      "customField1": "value1",
      "customField2": "value2"
    },
    "createdAt": "2025-10-09T10:30:00.000Z",
    "updatedAt": "2025-10-09T10:30:00.000Z",
    "verificationLink": {
      "manualVerificationLink": "https://api.example.com/partner/verification/verify?token=abc123...&sessionId=123",
      "deeplinkVerificationLink": "https://app.example.com/verification-request?token=abc123...&sessionId=123",
      "token": "abc123def456..."
    }
  }
}

Note: The verificationLink object contains:

  • manualVerificationLink: Direct web link for verification (opens in browser)

  • deeplinkVerificationLink: Deep link for mobile app integration

  • token: Verification token that can be used with the /partner/verification/verify endpoint

Error Response

{
  "statusCode": 500,
  "message": "Internal server error"
}

Create SDK Verification Session

Creates a new SDK-based verification session for a specific data source.

POST /partner/sdk/session

Authentication: API key required

Request Body

{
  "sourceName": "PayPal"
}

Request Parameters

  • sourceName (required): Name of the verification source/platform (e.g., "PayPal", "Stripe", "Upwork")

Response

{
  "success": true,
  "data": {
    "sessionId": "session-id-123",
    "providerId": "provider-id-456",
    "appId": "your-app-id",
    "steps": [
      {
        "step": 1,
        "action": "login",
        "description": "Login to your account"
      }
    ]
  }
}

Response Fields

  • sessionId: Unique session identifier for the SDK verification

  • providerId: Provider identifier for the data source

  • appId: Application ID for the Reclaim protocol

  • steps: Array of steps required to complete the verification flow

Error Response

{
  "statusCode": 404,
  "message": "Verification source not found"
}
{
  "statusCode": 404,
  "message": "Login flow not found"
}
{
  "statusCode": 500,
  "message": "Internal server error"
}

Select Data Source

Selects one or more data sources for a verification session.

POST /partner/step/select-data-source

Authentication: CSRF token required

Request Body

{
  "dataSourceIds": [1, 2, 3],
  "sessionId": 123
}

Response

{
  "status": "success"
}

Error Response

{
  "statusCode": 500,
  "message": "Internal server error"
}

Initiate Verification Step

Initiates a verification step and returns necessary data for the verification process.

POST /partner/step/initiate

Authentication: CSRF token required

Request Body

{
  "stepId": 123
}

Response

{
  "status": "success",
  "data": {
    "redirectUrl": "https://verification-provider.com/auth",
    "formData": {
      "field1": "value1",
      "field2": "value2"
    },
    "metadata": {
      "key1": "value1",
      "key2": "value2"
    }
  }
}

Error Response

{
  "statusCode": 500,
  "message": "Internal server error"
}

Get Session Steps

Retrieves all steps for a specific verification session.

GET /partner/steps/session/:sessionId

Authentication: CSRF token required

Parameters

  • sessionId (path parameter): ID of the verification session

Response

{
  "status": "success",
  "data": {
    "steps": [
      {
        "id": number,
        "status": string,
        "type": string,
        "sessionId": number,
        "dataSourceId": number,
        "createdAt": string,
        "updatedAt": string
        // ... other step details
      }
    ]
  }
}

Error Response

{
  "statusCode": 500,
  "message": "Internal server error"
}

Get Reviewer Sessions

Retrieves all verification sessions assigned to the authenticated reviewer with pagination support.

GET /partner/reviewer/sessions

Authentication: API key required

Query Parameters

  • status (optional): Filter sessions by status (PENDING, PROCESSING, COMPLETED, REVIEWING, FAILED, EXPIRED, REJECTED)

  • limit (optional): Number of items per page (default: 20, max: 100)

  • offset (optional): Number of items to skip (default: 0)

  • sortBy (optional): Field to sort by - 'createdAt', 'updatedAt', or 'status' (default: 'createdAt')

  • sortOrder (optional): Sort order - 'asc' or 'desc' (default: 'desc')

Response

{
  "success": true,
  "data": [
    {
      "id": number,
      "status": string,
      "verificationTypeId": number,
      "userId": string,
      "teamId": number,
      "reviewerId": string,
      "createdAt": string,
      "updatedAt": string
      // ... other session details
    }
  ],
  "total": number,
  "limit": number,
  "offset": number
}

Error Response

{
  "statusCode": 500,
  "message": "Internal server error"
}

Get Step Details

Retrieves details of a specific verification step.

GET /partner/steps/:stepId

Authentication: CSRF token required

Parameters

  • stepId (path parameter): ID of the verification step

Response

{
  "id": number,
  "status": string,
  "type": string,
  "sessionId": number,
  "dataSourceId": number,
  "metadata": object,
  "createdAt": string,
  "updatedAt": string
  // ... other step details
}

Error Response

{
  "statusCode": 500,
  "message": "Internal server error"
}

Search Data Sources

Searches for available data sources based on text query.

GET /partner/sources/search

Authentication: CSRF token required

Query Parameters

  • text (required): Search text to filter data sources

  • sessionId (optional): Session ID to filter sources specific to a session

Response

[
  {
    "id": number,
    "name": string,
    "description": string,
    "sourceName": string,
    "logoUrl": string,
    "category": string
    // ... other source definition fields
  }
]

Error Response

{
  "statusCode": 500,
  "message": "Internal server error"
}

Submit Verification Step

Submits verification proofs for a specific step.

POST /partner/step/submit

Authentication: CSRF token required

Request Body

{
  "stepId": 123,
  "proofs": [
    {
      "identifier": "proof-id-123",
      "claimData": {
        "provider": "data-provider",
        "parameters": {},
        "context": "verification-context"
      },
      "signatures": ["signature1", "signature2"],
      "witnesses": [
        {
          "id": "witness-1",
          "url": "https://witness.example.com"
        }
      ]
    }
  ]
}

Response

{
  "status": "success"
}

Error Response

{
  "statusCode": 500,
  "message": "Internal server error"
}

Typical Workflow

Here's a typical workflow for using the Partner API:

1. Create a Verification Session

Start by creating a new verification session using your API key:

POST /partner/session

This returns a session ID, verification links, and other session details. The verification link contains a token that will be used to obtain a CSRF token for subsequent requests.

2. Get Available Data Sources

Retrieve available data sources for the session:

GET /partner/sources/session/:sessionId

Or search for specific data sources:

GET /partner/sources/search?text=<search-term>&sessionId=<session-id>

3. Select Data Sources

User selects one or more data sources to use for verification:

POST /partner/step/select-data-source

4. Get Session Steps

Retrieve the verification steps created for the session:

GET /partner/steps/session/:sessionId

5. Initiate Each Step

For each step, initiate the verification process:

POST /partner/step/initiate

This returns a redirect URL or form data needed to complete the verification.

6. Submit Verification Proofs

After the user completes verification, submit the proofs:

POST /partner/step/submit

Error Handling

The API uses standard HTTP status codes and returns error messages in the following format:

{
  "statusCode": number,
  "message": string,
  "error": string
}

Common error codes:

  • 400: Bad Request

  • 401: Unauthorized

  • 403: Forbidden

  • 404: Not Found

  • 500: Internal Server Error

Rate Limiting

The API implements rate limiting based on your API key. Rate limits are configurable per API key and include:

  • TTL (Time To Live)

  • Request limit

  • Block duration

Session Statuses

  • PENDING

  • PROCESSING

  • COMPLETED

  • REVIEWING

  • FAILED

  • EXPIRED

  • REJECTED

Step Statuses

  • PENDING

  • INITIATED

  • IN_PROGRESS

  • VERIFIED

  • FAILED

  • EXPIRED

  • COMPLETED

Quick Reference

Endpoint Summary

Method
Endpoint
Authentication
Description

GET

/partner/sources/session/:sessionId

CSRF

Get verification sources by session

POST

/partner/session

API Key

Create verification session

POST

/partner/sdk/session

API Key

Create SDK verification session

POST

/partner/step/select-data-source

CSRF

Select data sources for session

POST

/partner/step/initiate

CSRF

Initiate verification step

GET

/partner/steps/session/:sessionId

CSRF

Get all steps for session

GET

/partner/reviewer/sessions

API Key

Get reviewer's sessions

GET

/partner/steps/:stepId

CSRF

Get step details

GET

/partner/sources/search

CSRF

Search data sources

POST

/partner/step/submit

CSRF

Submit verification proofs

Support

For API support or questions, please contact your partner integration manager or refer to the main documentation.

PreviousPartner Portal GuideNextWebhooks

Last updated