Search business data

get

https://api.vcita.biz/v2/search

Overview

Searches across business data entities including clients, conversations, bookings, appointments, estimates, payments, and documents. The search is powered by an Elasticsearch-based Seeker service.

The behavior varies depending on the entity parameter:

No entity or general entities: Returns a combined result with top_hits grouped by entity type and counts per entity type.
entity=appointment: Returns a decorated list of appointments with pagination support for recurring appointment series.
entity=event_instance: Returns a decorated list of event instances with standard pagination.

Rate Limiting

This endpoint is rate-limited to 60 requests per 60 seconds per staff member. Exceeding the limit returns a 429 Too Many Requests response.

Staff Permissions

Search results are filtered based on the requesting staff member's permissions:

Clients are scoped to the staff member's accessible clients unless they have full access.
Payment and document results are hidden if the staff member lacks view permissions for those entities.
Client email, phone, and last name visibility depends on the staff's model view permissions.

Available for Staff and Internal tokens.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

query

string

The search text to match against business data. Supports free-text search across entity fields (e.g., client name, email, phone number).

entity

string

When set, restricts the search to a single entity type. The response format depends on the value:

appointment — Returns a decorated list of appointments with recurring series support and specialized pagination.
event_instance — Returns a decorated list of event instances with standard pagination.
client, conversation, booking, estimate, payment, document — Restricts the general search to the specified entity type, returning the standard top_hits + counts response format.

When omitted, the search spans all entity types and returns the general top_hits + counts response.

entities

string

Comma-separated list of entity types to include in the search results. Applicable when entity is not set. Possible values include: client, conversation, booking, appointment, estimate, payment, document.

page

integer

Defaults to 1

Page number for pagination (1-based). For appointment searches with recurring series, this can also be an object with virtual_count and physical_count to properly paginate mixed physical and virtual appointments.

per_page

integer

Defaults to 25

Number of results per page.

quick

string

When set, performs a quick search with potentially fewer results but faster response time.

search_filter[text_filter]

string

Additional text filter applied within the search. Used for more targeted filtering beyond the main query parameter.

search_filter[staff_filter]

string

Comma-separated list of staff UIDs to filter results by specific staff members.

search_filter[from_filter]

date-time

Start date filter for time-based searches (e.g., appointments, events). ISO 8601 date format.

search_filter[to_filter]

date-time

End date filter for time-based searches (e.g., appointments, events). ISO 8601 date format.

search_filter[sort_type]

string

Field to sort by for appointment and event searches (used when entity=appointment or entity=event_instance). Forwarded to the Seeker service. The most common value is start_time to sort appointments by their start time. This parameter is only meaningful for entity-specific searches — for general search, use the top-level sort_by parameter instead.

search_filter[sort_order]

string

enum

Sort direction for time-based results. Used in conjunction with search_filter[sort_type] for appointment and event searches. After Seeker returns results, the backend also uses this value to re-sort merged appointment lists (physical + virtual recurring instances) by start_time.

Allowed:

search_filter[payment_status_state_filter]

string

Filter appointments by payment status. Accepts an array of payment status values (e.g., "not_paid", "paid").

search_filter[tags_filter]

string

Filter results by tags. Used for tag-based client filtering.

search_filter[tags_relation]

string

enum

Defaults to or

Logical relation for multiple tag filters.

Allowed:

sort_by

string

Field to sort results by for general search only (when entity is not set). The value is mapped through a column identifier mapping for client card fields, or used directly if no mapping exists. Not applicable to appointment or event searches — use search_filter[sort_type] and search_filter[sort_order] instead.

sort_order

string

enum

Sort direction for the primary sort in general search only (when entity is not set). Not applicable to appointment or event searches — use search_filter[sort_order] instead.

Allowed:

secondary_sort_by

string

Secondary field to sort results by, used as a tiebreaker when primary sort values are equal.

secondary_sort_order

string

enum

Sort direction for the secondary sort.

Allowed:

select_all

boolean

When set to true, returns a slimmed-down version of client results suitable for bulk selection operations. Client first_name and last_name are excluded from the response.

new_decoration

string

enum

When set to true, uses the newer matter-based client decoration format. The response will contain counts and matters instead of the default top_hits format for client results.

Allowed:

401Unauthorized. The bearer token is missing, invalid, or not allowed to access the requested resource.

404Not Found. No matching results were found for the given entity search (appointment or event_instance).

429Too Many Requests. The staff member has exceeded the rate limit of 60 requests per 60 seconds.

504Gateway Timeout. The Seeker search service is unavailable or timed out.