Skip to main content
GET
/
v3
/
businesses
List Businesses
curl --request GET \
  --url https://verification.didit.me/v3/businesses/ \
  --header 'x-api-key: <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 business status

Available options:
Active,
Flagged,
Blocked
​
search
string

Search by legal name, display name, vendor_data, or registration number

​
country
string

Filter by country of incorporation (ISO2 code)

​
limit
integer
default:50

Results per page (max 200)

​
offset
integer
default:0

Pagination offset

Response

200 - application/json

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[]