B2B database
Search the shared prospect catalog and add selected people to workspace contacts.
These endpoints use the /v1 prefix, require a selected organization, and use the standard authentication and error envelope.
| Method | Path | API permissions | Member permissions |
|---|---|---|---|
| GET | /b2b-database/metadata | READ_CONTACTS | View contacts |
| POST | /b2b-database/people | READ_CONTACTS | View contacts |
| POST | /b2b-database/companies | READ_CONTACTS | View contacts |
| POST | /b2b-database/import | READ_CONTACTS and WRITE_CONTACTS | View contacts and Manage contacts |
Catalog metadata
GET /b2b-database/metadata returns people, companies, countries, seniorities, departments, source, and source_period. Totals and facets describe the entire catalog and are cached for one hour. They do not count a filtered search.
Search
People and Companies accept JSON filters with optional cursor and limit. Default limit is 50; accepted limits are 1 through 100. These POSTs are read-only and naturally safe to retry.
{
"country": "united states",
"title": "director",
"seniority": "director",
"email": "valid",
"limit": 50
}| Filter | Meaning |
|---|---|
q | People: name contains, or exact email when it contains @. Companies: name or domain contains |
country, state, city | Exact location, case-insensitive |
domain | Exact primary company domain, lowercase, optional leading www. removed |
industry, technology | Exact lowercase company array value |
min_employees, max_employees | Inclusive unsigned company size bounds; unknown sizes excluded |
company_id | Exact 24-character lowercase catalog company ID |
title | People only: job title contains |
seniority, department | People only: exact lowercase catalog value |
email | People only: present, missing, or valid (syntax only) |
String filters are trimmed, lowercased, and limited to 200 bytes. All supplied filters combine with AND. Company filters on People match the primary company. People-specific filters on Companies return 400. Supply catalog labels from metadata or record details, not the workspace lead database's derived bucket names.
Both list endpoints return:
{
"data": [],
"pagination": { "next_cursor": null, "has_more": false }
}When has_more is true, send next_cursor with the same filters on the next request. People are ordered by country, seniority, person ID; companies by country, employee count (unknown sorts as zero), company ID. There is no offset or random page jump. IDs are catalog strings, not workspace UUIDs. Person rows include a bounded, hydrated company object when a matching primary company exists. Unknown numbers are null, missing text is empty, and source timestamps are historical UTC strings.
Import selected people
{ "person_ids": ["0123456789abcdef01234567"] }Select between 1 and 100 unique person IDs. All must exist and have valid email syntax. The server retrieves the records, creates or updates workspace contacts through the existing contact flow, records an audit event, and schedules verification. Historical source status is preserved as a custom field, not an imported verification verdict. Returns { "data": [/* contacts */], "count": 1 }.
Use Idempotency-Key for retries of an import. This endpoint uses the standard organization-scoped idempotency middleware. It never enrolls a contact in a campaign automatically.
Errors and limits
| Code | HTTP | Meaning |
|---|---|---|
invalid_b2b_filter | 400 | Unsupported filter value, invalid company ID, or inconsistent size range |
invalid_limit | 400 | Limit outside 1–100 |
invalid_cursor | 400 | Malformed cursor or cursor bound to another search; restart from the first page |
invalid_selection | 400 | Invalid, duplicate, missing, or too many selected IDs |
b2b_email_required | 400 | Selected person has no syntactically valid email |
b2b_unavailable | 503 | No configured catalog connection |
b2b_query_failed | 503 | Query could not finish within the service budget or connection failed; narrow filters and retry |
Workspace contact limit and validation errors also apply to import. Queries have a 32-second backend deadline, four concurrent query slots per backend process, and an 8 MiB response cap. Configure the database user with SELECT-only access, a 30-second execution limit, two threads, and a 2 GiB memory limit.