Search

Beta
GET/v1/core/search

This endpoint is idempotent. Learn more

Searches across multiple resource types at once and returns lightweight entity references to the matches.

Each result carries the matched record's ID, its resource type, and a display name and secondary handle, so it can be shown in a picker or turned into a link; fetch the record itself through its own endpoint for full detail.

q is required unless the search is narrowed with types; scoping to one or more types lets you omit q to browse that type's most recent records. Matches are drawn from every searchable type you can read, then interleaved so no single type crowds out the others, and the combined result set is capped at limit. Results are not paginated — limit is the total you get. If one resource type fails to respond, it contributes no results instead of failing the whole search.

Permissions requiredValues:sales_orders:readpurchase_orders:readinvoices:read
The role behind your API key or agent must grant every one of these permissions.
cursoroptional string

Opaque cursor token identifying where the page of results starts.

Use the cursor value embedded in a previous response's next_page_url or previous_page_url to fetch the adjacent page. Omit to start from the first page.

limitoptional integer

Maximum number of results to return in a single page.

qoptional string

Free-text search term used to filter results.

Which fields are matched against the term varies by endpoint.

types[]optional arrayenumValues:accountactorentity

Filter the search to specific resource types.

Only a subset of resource types is searchable: sales_order, purchase_order, invoice, customer, item, product, shipment, messaging_contact, and agent_definition. Any other value is rejected. Types you lack read permission for are silently dropped rather than rejected, so narrowing to a type you cannot read simply returns no results. Omit to search every searchable type you can read.

customeroptional string

Restrict the search to a single customer by their account ID.

When set, only resource types that are safe to expose to a customer are searched (their sales orders, invoices, and shipments), and results are limited to records belonging to that customer. This is intended for composing customer-facing replies, so a reference can never point at a record the customer is not entitled to see.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of entity

Resources in this page.

idstring

Unique identifier for the entity.

objectstringenumValues:entity

Resource type identifier.

typestringenumValues:accountactorentity

The resource kind that this entity references, as an object-type value (e.g. user, account).

Unlike object — which is always entity — this names the underlying resource the id points to.

namestringnullable

Human-readable display name for the entity (e.g. a user's full name, a sales order number).

handlestringnullable

Secondary human-readable identifier (e.g. email address, username, redacted API key value).

Responses

200

Successful response for Search