Skip to main content
GET
/
v3
/
businesses
curl
curl -X GET 'https://verification.didit.me/v3/businesses/?limit=50&status=ACTIVE' \
  -H 'x-api-key: YOUR_API_KEY'
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "didit_internal_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "vendor_data": "company-123",
      "display_name": null,
      "legal_name": "Acme Trading Ltd",
      "registration_number": "12345678",
      "country_code": "GB",
      "effective_name": "Acme Trading Ltd",
      "status": "ACTIVE",
      "session_count": 2,
      "approved_count": 1,
      "declined_count": 0,
      "in_review_count": 1,
      "features": {
        "KYB_REGISTRY": "Approved",
        "KYB_AML": "Approved",
        "KYB_DOCUMENTS": "In Review"
      },
      "features_list": [
        {
          "feature": "KYB_REGISTRY",
          "status": "Approved"
        },
        {
          "feature": "KYB_AML",
          "status": "Approved"
        },
        {
          "feature": "KYB_DOCUMENTS",
          "status": "In Review"
        }
      ],
      "last_session_at": "2026-03-15T10:30:00Z",
      "first_session_at": "2026-01-10T08:00:00Z",
      "last_activity_at": "2026-03-15T10:30:00Z",
      "tags": [
        {
          "uuid": "t1111111-2222-3333-4444-555555555555",
          "name": "VIP",
          "color": "#2567FF"
        }
      ],
      "created_at": "2026-01-10T08:00:00Z"
    }
  ]
}

​
Overview

Returns a paginated list of Business entities for the authenticated application.

​
When to use it

  • Sync your business table to an external BI or warehouse.
  • Analyst queues — filter by status=FLAGGED to drive a review inbox.
  • Search by display_name, legal_name, registration_number, or vendor_data.

​
Filters and pagination

Query parameterDescription
statusACTIVE, FLAGGED, or BLOCKED.
searchSubstring match on display name, legal name, registration, vendor_data.
country_codeISO 3166-1 alpha-3 country of incorporation.
created_after, created_beforeCreation date window.
last_activity_after, last_activity_beforeActivity window.
page_size1–200. Default 50.
cursorPagination cursor.

​
Notes

  • vendor_data may be null if the originating session or transaction did not provide one.
  • Cursor-based pagination — persist the next cursor between calls.
  • See the Business data model for every field.

​
Permissions

Role must grant list:businesses.

Authorizations

​
x-api-key
string
header
required

Query Parameters

​
status
enum<string>

Filter by lifecycle status. ACTIVE is the default for any business, FLAGGED marks it for manual review, BLOCKED prevents future sessions for the same vendor_data and adds the identifier to the system blocklist.

Available options:
ACTIVE,
FLAGGED,
BLOCKED
​
search
string

Free-text search across vendor_data, display_name, legal_name, and registration_number.

​
country
string

Filter by country of incorporation (ISO 3166-1 alpha-2, e.g. GB, US).

​
limit
integer
default:50

Page size. Maximum 200; defaults to 50.

Required range: 1 <= x <= 200
​
offset
integer
default:0

Zero-based offset of the first record to return. Prefer following the next URL from the previous page.

Required range: x >= 0

Response

Paginated list of businesses with status, session counts, and feature breakdown.

​
count
integer

Total number of businesses matching filters

​
next
string | null

URL of next page

​
previous
string | null

URL of previous page

​
results
object[]