Thirdfort Client API Documentation

Welcome to the Thirdfort Client API documentation. This API enables integrators to perform comprehensive client due diligence and compliance checks, providing programmatic access to identity verification, screening, and document collection services.

Getting Started

1. Authentication - Learn how to obtain OAuth 2.0 access tokens
2. API Design Principles - Understand our API patterns and conventions
3. Code Generation - Generate type-safe client libraries
4. API Reference - Explore all available endpoints

Environments

Environment	API Base URL	Token Endpoint
Nonproduction (Sandbox)	https://api.thirdfort.dev/client/api	https://creative-jungle-73-staging.authkit.app/oauth2/token
Production	https://api.thirdfort.com/client/api	https://discerning-holiday-58.authkit.app/oauth2/token

Core Concepts

Checks

A Check is the primary resource representing a due diligence request. Checks are created from templates and can include:

• Identity Verification - Verify an individual's identity using government-issued documents
• Source of Funds - Verify the origin and legitimacy of funds
• Enhanced Due Diligence - Comprehensive background screening

Organizations and Teams

Resources are organized hierarchically:

• Organizations represent your business entities
• Teams group users and checks within an organization
• Brands define the visual identity shown to consumers

Resource Names

Resources are identified using hierarchical resource names:

organizations/{org_id}/teams/{team_id}/checks/{check_id}

Use - as a wildcard to query across all resources:

organizations/-/teams/-/checks

Common Operations

Creating a Check

POST /v1alpha2/checks
Content-Type: application/json

{
  "parent": "organizations/{org_id}/teams/{team_id}",
  "template": "templates/identity-verification",
  "subject": {
    "individual": {
      "given_name": "John",
      "family_name": "Smith",
      "email": "john.smith@example.com"
    }
  }
}

Listing Checks with Filtering

The ListChecks API supports AIP-160 filtering syntax. Note that you will need to URL encode the filter string. They are displayed unencoded in this document for readability.

GET /v1alpha2/organizations/-/teams/-/checks?filter=state = "COMPLETE"

Common filter expressions:

• state = "PENDING" - Checks awaiting consumer action
• state = "COMPLETE" - Finished checks
• create_time > "2024-01-01T00:00:00Z" - Checks created after a date

Pagination

List operations return paginated results. Use page_token to retrieve subsequent pages:

GET /v1alpha2/checks?page_size=25&page_token={next_page_token}

Notifications

Receive notifications when important events occur, such as checks completing or reports being updated.

Consumption Methods

• Pull (API): Poll GET /v1alpha2/{parent}/notifications to retrieve notifications
• Push (Webhooks): Receive notifications via webhooks for real-time delivery (contact your Thirdfort account manager or email api-support@thirdfort.com to set up webhook delivery)

Polling for Notifications

Retrieve the latest notifications for your organization:

GET /v1alpha2/organizations/{organization}/notifications?page_size=25

Using Page Tokens

Use the next_page_token from each response to efficiently retrieve new notifications:

# First request
GET /v1alpha2/organizations/acme-corp/notifications?page_size=25

# Response includes next_page_token
# Use it in subsequent requests
GET /v1alpha2/organizations/acme-corp/notifications?page_size=25&page_token=eyJsYXN0X2lkIjoiMDFKUkE0...

Filtering notifications

Filtering by time

The ListNotifications API supports AIP-160 filtering syntax. Note that you will need to URL encode the filter string. They are displayed unencoded in this document for readability.

GET /v1alpha2/organizations/acme-corp/notifications?filter=create_time > "2024-06-01T00:00:00Z"

Filtering by type

Retrieve only specific notification types:

GET /v1alpha2/organizations/acme-corp/notifications?filter=type = "notification.client.check_complete.v1"

Combining filters

Combine multiple filters with AND or OR:

GET /v1alpha2/organizations/acme-corp/notifications?filter=type = "notification.client.check_complete.v1" AND create_time > "2024-06-01T00:00:00Z"

Notification Types

Type	Payload	Description
notification.client.check_complete.v1	CheckCompleteData	A check has completed processing
notification.client.report_updated.v1	ReportUpdatedData	A report has been updated (e.g., finding reviewed)
notification.client.ongoing_monitoring_hit.v1	OngoingMonitoringHitData	Ongoing monitoring screening match detected
notification.client.ongoing_monitoring_renewal_reminder.v1	OngoingMonitoringRenewalReminderData	Ongoing monitoring subscription renewal due

Notification Payload Example

{
  "name": "organizations/acme-corp/notifications/01JRA4ABC123",
  "type": "notification.client.check_complete.v1",
  "createTime": "2024-06-15T10:30:00Z",
  "payload": {
    "@type": "type.googleapis.com/thirdfort.client.notifications.v1alpha1.CheckCompleteData",
    "check": "organizations/acme-corp/teams/default/checks/01JRA3XYZ789",
    "displayName": "John Smith ID Verification",
    "state": "ACTIVE",
    "recommendation": "APPROVE",
    "completeTime": "2024-06-15T10:29:55Z"
  }
}

Idempotency

Notifications include a unique resource name (e.g., organizations/{org}/notifications/01JRA4ABC123). Use the notification ID portion for deduplication when processing notifications.

Webhooks

For real-time push delivery, Thirdfort configures webhook endpoints to receive notifications as they occur. Contact your Thirdfort account manager or email api-support@thirdfort.com to set up webhook delivery.

Webhook Payload

Webhook payloads match the notification structure and include the following headers:

Header	Description
x-thirdfort-notification-id	The notification ID (e.g., 01JRA4ABC123)
x-thirdfort-notification-type	The notification type (e.g., notification.client.check_complete.v1)
x-thirdfort-signature	HMAC-SHA256 signature for verification

Signature Verification

Verify webhook authenticity by confirming the x-thirdfort-signature header matches the SHA-256 HMAC of the payload body using your shared secret.

Example:

import hashlib
import hmac
import base64
import os

THIRDFORT_WEBHOOK_SECRET = os.getenv("THIRDFORT_WEBHOOK_SECRET")

def verify_webhook(request) -> bool:
    if THIRDFORT_WEBHOOK_SECRET is None:
        raise RuntimeError("THIRDFORT_WEBHOOK_SECRET is not set")

    # Extract x-thirdfort-signature header from the request
    hmac_header = request.headers.get("x-thirdfort-signature")

    # Create a hash based on the raw body
    hash = base64.b64encode(
        hmac.new(
            THIRDFORT_WEBHOOK_SECRET.encode(), request.data, hashlib.sha256
        ).digest()
    ).decode()

    # Compare the created hash with the value of the x-thirdfort-signature
    return hash == hmac_header

Support

• Status Page: status.thirdfort.com
• Email: api-support@thirdfort.com