Owlbound
Browse the docs

Reference · 3 operations

Contacts

People in the workspace.

Last updated from API version 2026-10-06 at (live spec, refreshed hourly). openapi.json

contacts.list

List contacts, newest first, with index-backed filters.

get/api/v1/contacts
Scope
read
Credits
Free
Idempotency-Key
Not used

Cursor-paginated (meta.page). Archived contacts are excluded unless includeArchived=true. Several filters can be combined; one is served by an index and the others filter its rows, so a page may be shorter than limit: meta.page.hasMore is the only end signal. v0 (legacy) keys keep the v0 contract on this path (company, sort_by, data: {contacts, hasMore, nextCursor}).

Parameters

  • limitqueryinteger

    Page size.

    default 50min 1max 200
  • cursorquerystring

    Opaque cursor from meta.page.nextCursor. Reusing it with other filters is 400 CURSOR_MISMATCH.

  • statusquerystring

    Sales stage. enriching, enriched, qualified, excluded and failed are legacy values still present on older contacts.

    newreadyincompletecontactedrepliedconvertedlostenrichingenrichedqualifiedexcludedfailed
  • sourcequerystring

    Exact source, e.g. csv, linkedin, api.

  • companyIdquerystring

    Contacts linked to this company.

  • emailquerystring

    Exact email.

  • linkedInUrlquerystring

    Exact LinkedIn profile URL.

  • includeArchivedqueryboolean

    Include archived contacts.

    default false
  • sortByquerystring

    Reserved. The sort is fixed (newest first); any value is 400 UNSUPPORTED_FILTER.

  • updatedSincequerystring

    Reserved; any value is 400 UNSUPPORTED_FILTER.

Responses

200
A page of contacts.
Show schema

ContactListResponse

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl "https://app.owlbound.ai/api/v1/contacts" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06"

contacts.search

Full-text search over contact names, titles, companies and emails.

post/api/v1/contacts/search
Scope
read
Credits
Free
Idempotency-Key
none

Results are ordered by relevance and cursor-paginated; send the same query, status and includeArchived with cursor for the next page.

Request body (required) · application/json

ContactSearchRequest

  • querystringrequired
    min length 1max length 500
  • limitinteger
    default 50min 1max 200
  • cursorstring

    meta.page.nextCursor from the previous page of the same search.

    0
  • statusstring

    Sales stage. enriching, enriched, qualified, excluded and failed are legacy values still present on older contacts.

    newreadyincompletecontactedrepliedconvertedlostenrichingenrichedqualifiedexcludedfailed
  • includeArchivedboolean
    default false

Responses

200
A page of matching contacts.
Show schema

ContactListResponse

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl -X POST "https://app.owlbound.ai/api/v1/contacts/search" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "<query>"
}'

contacts.get

Get one contact.

get/api/v1/contacts/{id}
Scope
read
Credits
Free
Idempotency-Key
Not used

A contact in another workspace is 404 NOT_FOUND.

Parameters

  • idpathstringrequired

    Opaque resource id.

Responses

200
The contact.
Show schema

ContactResponse

  • dataContactrequired

    One contact with every public field.

    0
  • metaResponseMetarequired

    Metadata on every success response.

    0

Errors

400 The request is invalid (VALIDATION_ERROR, CURSOR_MISMATCH, UNSUPPORTED_FILTER) · 401 Missing, invalid, expired or revoked key · 403 Missing scope, suspended workspace or unavailable identity · 404 Unknown resource or route. A resource in another workspace is also 404 · 429 Rate limit reached · 500 Unexpected error · 503 The backend is unreachable; retry after `Retry-After`. Every error is {error: {type, code, message, requestId, docUrl}}; see error codes.

curl "https://app.owlbound.ai/api/v1/contacts/$ID" \
  -H "Authorization: Bearer $OWLBOUND_API_KEY" \
  -H "Owlbound-Version: 2026-10-06"

Models on this page

Shared objects the operations above link to. Clients must ignore fields they do not know.

ContactSummaryobject

A contact as listed. Documented fields are always present (null when empty).

  • idstringrequired
    0
  • firstNamestring | nullrequired
    0
  • lastNamestring | nullrequired
    0
  • emailstring | nullrequired
    0
  • phonestring | nullrequired
    0
  • linkedInUrlstring | nullrequired
    0
  • titlestring | nullrequired
    0
  • companystring | nullrequired

    Company name as captured on the contact.

    0
  • companyIdstring | nullrequired
    0
  • locationstring | nullrequired
    0
  • statusstringrequired

    Sales stage. enriching, enriched, qualified, excluded and failed are legacy values still present on older contacts.

    newreadyincompletecontactedrepliedconvertedlostenrichingenrichedqualifiedexcludedfailed
  • sourcestring | nullrequired
    0
  • scorenumber | nullrequired

    Best ICP score, 0 to 100.

    0
  • activityScorenumber | nullrequired
    0
  • tagsarray of stringrequired
    0
  • isArchivedbooleanrequired
    0
  • connectionStatusstring | nullrequired

    LinkedIn connection status.

    0
  • createdAtnumberrequired

    Ms since epoch.

    0
  • updatedAtnumber | nullrequired
    0
PagedResponseMetaobject

Metadata on a paginated success response.

  • requestIdstringrequired
    0
  • creditsCreditsMetarequired
    0
  • pagePageMetarequired

    Cursor pagination. hasMore is the only end signal; pages may be short.

    0
CreditsMetaobject
  • usednumberrequired

    Credits charged by this request. Reads are free.

    0
  • balancenumber
    0
  • estimatednumber

    Dry run only (action operations).

    0
  • availablenumber

    Dry run only (action operations).

    0
  • reservationIdstring | null

    Async operations only; the job settles this reservation.

    0
PageMetaobject

Cursor pagination. hasMore is the only end signal; pages may be short.

  • nextCursorstring | nullrequired
    0
  • hasMorebooleanrequired
    0
  • limitintegerrequired
    min 1max 200
Contactobject

One contact with every public field.

  • idstringrequired
    0
  • firstNamestring | nullrequired
    0
  • lastNamestring | nullrequired
    0
  • emailstring | nullrequired
    0
  • phonestring | nullrequired
    0
  • linkedInUrlstring | nullrequired
    0
  • profilePhotoUrlstring | nullrequired
    0
  • titlestring | nullrequired
    0
  • headlinestring | nullrequired
    0
  • companystring | nullrequired
    0
  • companyIdstring | nullrequired
    0
  • companyDomainstring | nullrequired
    0
  • companyIndustrystring | nullrequired
    0
  • companyEmployeeCountnumber | nullrequired
    0
  • locationstring | nullrequired
    0
  • departmentstring | nullrequired
    0
  • seniorityLevelstring | nullrequired
    0
  • statusstringrequired

    Sales stage. enriching, enriched, qualified, excluded and failed are legacy values still present on older contacts.

    newreadyincompletecontactedrepliedconvertedlostenrichingenrichedqualifiedexcludedfailed
  • sourcestring | nullrequired
    0
  • scorenumber | nullrequired
    0
  • activityScorenumber | nullrequired
    0
  • connectionStatusstring | nullrequired
    0
  • tagsarray of stringrequired
    0
  • notesstring | nullrequired
    0
  • customFieldsCustomFieldsrequired

    Workspace-defined fields, keyed by field key. Empty when none are set.

    0
  • isArchivedbooleanrequired
    0
  • enrichedAtnumber | nullrequired
    0
  • lastContactedAtnumber | nullrequired
    0
  • lastRepliedAtnumber | nullrequired
    0
  • createdAtnumberrequired
    0
  • updatedAtnumber | nullrequired
    0
CustomFieldsobject

Workspace-defined fields, keyed by field key. Empty when none are set.

  • {key}one of | null
    0
    + Show child fields

    One of

    string

    string

    number

    number

    boolean

    boolean

    array

    array of string

ResponseMetaobject

Metadata on every success response.

  • requestIdstringrequired
    0
  • creditsCreditsMetarequired
    0
  • pagePageMeta

    Cursor pagination. hasMore is the only end signal; pages may be short.

    0
  • dryRunboolean

    True only on a dry-run response (action operations).

    0

← All operations