> ## Documentation Index > Fetch the complete documentation index at: https://docs.stardex.com/llms.txt > Use this file to discover all available pages before exploring further. # Search deals > Search and filter deals with pagination and sorting using the deals_list_query RPC. **Filters**: `keywords` (name + company search), `deal_status_ids_included`/`excluded`, `owner_ids_included`/`excluded`, `show_open_deals_only`, `show_archived`, `closed_date_filter`, `open_date_filter`, and custom attribute filters (`select_attribute_filters`, `numeric_attribute_filters`, `date_attribute_filters`, `team_member_attribute_filters`). **Sorting**: `name`, `amount`, `win_probability`, `company`, `status`, `closed_date`, `open_date`, `last_contacted_at`, `created_at`, or `custom_` for custom attribute sorting. **Include**: Pass `["custom_fields"]` to include deal custom attribute values. ## OpenAPI ````yaml /api-reference/openapi-v1.json post /v1/deals/search openapi: 3.1.0 info: title: Stardex API (v1) version: 1.0.0 description: >- Stardex ATS API — manage candidates, jobs, companies, and recruiting workflows. servers: - url: https://api.stardex.ai description: Production API server security: - bearerAuth: [] tags: - name: Persons description: Manage person records — contacts, work history, and custom fields. - name: Jobs description: Manage job postings — pipeline stages, team members, and custom fields. - name: Candidates description: Manage candidate records and pipeline stage transitions. - name: Companies description: Browse and retrieve company records. - name: Lists description: Create, search, and retrieve saved person and company lists. - name: Person Activities description: Create and manage activity records (notes, emails, meetings) for persons. - name: Team Members description: List team members for use in search filters and assignments. - name: Custom Fields description: Retrieve custom field definitions and tag options for search filters. paths: /v1/deals/search: post: tags: - Deals summary: Search deals description: >- Search and filter deals with pagination and sorting using the deals_list_query RPC. **Filters**: `keywords` (name + company search), `deal_status_ids_included`/`excluded`, `owner_ids_included`/`excluded`, `show_open_deals_only`, `show_archived`, `closed_date_filter`, `open_date_filter`, and custom attribute filters (`select_attribute_filters`, `numeric_attribute_filters`, `date_attribute_filters`, `team_member_attribute_filters`). **Sorting**: `name`, `amount`, `win_probability`, `company`, `status`, `closed_date`, `open_date`, `last_contacted_at`, `created_at`, or `custom_` for custom attribute sorting. **Include**: Pass `["custom_fields"]` to include deal custom attribute values. operationId: searchDeals requestBody: content: application/json: schema: $ref: '#/components/schemas/DealsSearchBody' responses: '200': description: Successful search response content: application/json: schema: $ref: '#/components/schemas/DealsSearchResponse' example: success: true data: - id: aaa11111-bbbb-cccc-dddd-eeeeeeee1111 name: Acme Corp Staffing Agreement amount: 150000 currency_code: USD compensation: 750000 compensation_currency_code: USD pricing_rate: 20 win_probability: 75 closed_date: '2024-06-30T00:00:00Z' open_date: '2024-01-15' last_contacted_at: '2024-05-20T14:30:00Z' deal_status: id: ccc33333-dddd-eeee-ffff-000000003333 name: Proposal Sent created_at: '2024-01-15T10:00:00Z' client_name: Acme Corp client_id: bbb22222-cccc-dddd-eeee-ffffffff2222 deal_lost_reason_id: null deal_lost_reason_text: null deal_lost_reason: null deal_won_reason_id: 66666666-7777-8888-9999-aaaaaaaaaaaa deal_won_reason_text: Client chose us because of prior executive-search success. deal_won_reason: id: 66666666-7777-8888-9999-aaaaaaaaaaaa reason: Strong relationship owners: - id: ddd44444-eeee-ffff-0000-111111114444 name: Jane Smith custom_fields: - attribute_id: f1e2d3c4-b5a6-7890-abcd-ef1234567890 attribute_name: Deal Priority data_type: single-select value: null tag: id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 name: High team_member: null meta: total: 100 offset: 0 limit: 20 '400': description: Validation error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '404': description: Resource not found content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error '500': description: Internal server error content: application/json: schema: type: object properties: success: type: boolean enum: - false description: Always false for error responses. error: type: object properties: code: type: string description: >- Machine-readable error code (e.g. "VALIDATION_ERROR", "NOT_FOUND"). message: type: string description: Human-readable error description. required: - code - message required: - success - error components: schemas: DealsSearchBody: type: object properties: offset: type: integer minimum: 0 default: 0 description: Records to skip for pagination. Defaults to 0. limit: type: integer minimum: 1 maximum: 100 default: 100 description: Max records to return (1–100). Defaults to 100. sort_by: type: string description: >- Column to sort by. Accepted values: - `name` — deal name (alphabetical) - `amount` — deal monetary amount - `win_probability` — win probability percentage - `company` — client company name (alphabetical) - `status` — deal status (by stage order) - `closed_date` — expected or actual close date - `open_date` — deal open date - `last_contacted_at` — most recent engagement with client contacts - `created_at` — creation timestamp (default) - `custom_` — any custom attribute UUID prefixed with `custom_` (e.g. `custom_e5f6a7b8-...`). Sorts by the attribute's decimal, date, string, or tag value. sort_order: type: string enum: - asc - desc default: desc description: Sort direction. Defaults to desc (newest first). keywords: type: array items: type: string description: >- Full-text search across deal name, client company name, and domain. Multiple keywords use OR logic. deal_ids: type: array items: type: string format: uuid description: Pre-filter to a specific set of deal UUIDs. list_id: type: string format: uuid description: Filter to deals belonging to this list. deal_status_ids_included: type: array items: type: string format: uuid description: Include only deals with these status UUIDs. deal_status_ids_excluded: type: array items: type: string format: uuid description: Exclude deals with these status UUIDs. owner_ids_included: type: array items: type: string format: uuid description: >- Include only deals owned by these team members. Get IDs from GET /v1/team-members. owner_ids_excluded: type: array items: type: string format: uuid description: Exclude deals owned by these team members. show_open_deals_only: type: boolean description: When true, only return deals with an "active" status type. show_archived: type: boolean description: >- When true, return archived (soft-deleted) deals instead of active ones. closed_date_filter: type: object properties: start_date: type: - string - 'null' description: Start of date range (ISO 8601). Null for no lower bound. end_date: type: - string - 'null' description: End of date range (ISO 8601). Null for no upper bound. include_empty: type: boolean default: false description: >- When true, also include deals with no value set for this date field. description: >- Filter by closed_date range. Supports start_date, end_date, and include_empty. open_date_filter: type: object properties: start_date: type: - string - 'null' description: Start of date range (ISO 8601). Null for no lower bound. end_date: type: - string - 'null' description: End of date range (ISO 8601). Null for no upper bound. include_empty: type: boolean default: false description: >- When true, also include deals with no value set for this date field. description: >- Filter by open_date range. Supports start_date, end_date, and include_empty. select_attribute_filters: type: array items: type: object properties: attribute_id: type: string format: uuid description: >- Attribute definition UUID. Get from GET /v1/custom-fields/{entity}. values: type: array items: type: string default: [] description: >- Tag option UUIDs to include. Get tag IDs from the attribute's tags array in custom field definitions. excluded_values: type: array items: type: string default: [] description: Tag option UUIDs to exclude. require_all: type: boolean default: false description: >- When true, record must have ALL specified tags (AND logic). When false, any tag matches (OR logic). include_empty: type: boolean default: false description: >- When true, also include records with no value set for this attribute. required: - attribute_id description: >- Filter by select/multi-select custom fields. Get attribute_id and tag IDs from GET /v1/custom-fields/deals. numeric_attribute_filters: type: array items: type: object properties: attribute_id: type: string format: uuid description: >- Attribute definition UUID (integer or decimal type). Get from GET /v1/custom-fields/{entity}. min: type: - number - 'null' description: Minimum value (inclusive). Null for no lower bound. max: type: - number - 'null' description: Maximum value (inclusive). Null for no upper bound. include_empty: type: boolean default: false description: When true, also include records with no value set. required: - attribute_id description: >- Filter by numeric custom fields (min/max range). Get attribute_id from GET /v1/custom-fields/deals. date_attribute_filters: type: array items: type: object properties: attribute_id: type: string format: uuid description: >- Attribute definition UUID (date type). Get from GET /v1/custom-fields/{entity}. start_date: type: - string - 'null' description: Start of date range (ISO 8601). Null for no lower bound. end_date: type: - string - 'null' description: End of date range (ISO 8601). Null for no upper bound. include_empty: type: boolean default: false description: When true, also include records with no value set. required: - attribute_id description: >- Filter by date custom fields (date range). Get attribute_id from GET /v1/custom-fields/deals. team_member_attribute_filters: type: array items: type: object properties: attribute_id: type: string format: uuid description: >- Attribute definition UUID (multi-team-member type). Get from GET /v1/custom-fields/{entity}. values: type: array items: type: string format: uuid default: [] description: >- Team member UUIDs to include. Get IDs from GET /v1/team-members. excluded_values: type: array items: type: string format: uuid default: [] description: Team member UUIDs to exclude. require_all: type: boolean default: false description: >- When true, record must have ALL specified team members (AND logic). include_empty: type: boolean default: false description: >- When true, also include records with no team member assigned for this attribute. required: - attribute_id description: >- Filter by team-member custom fields. Get attribute_id from GET /v1/custom-fields/deals. include: type: array items: type: string enum: - custom_fields description: >- Extra sections to embed. Values: custom_fields. Omit for base fields only. DealsSearchResponse: type: object properties: success: type: boolean enum: - true data: type: array items: $ref: '#/components/schemas/Deal' meta: type: object properties: total: type: number description: Total matching records across all pages. offset: type: number description: Current pagination offset. limit: type: number description: Page size used for this request. required: - total - offset - limit required: - success - data - meta Deal: type: object properties: id: type: string format: uuid description: Unique deal UUID. name: type: string description: Deal name. amount: type: - number - 'null' description: Deal monetary amount — the fee the firm invoices the client. currency_code: type: string description: >- ISO 4217 currency code for the deal amount (e.g. USD, EUR, GBP). Defaults to the organization setting or USD. compensation: type: - number - 'null' description: >- Candidate's expected total annual compensation (salary + bonus + equity). Used to compute the deal amount. compensation_currency_code: type: string description: >- ISO 4217 currency code for the estimated compensation. May differ from currency_code when the candidate is paid in a different currency than the firm invoices in. Defaults to the organization setting or USD. pricing_rate: type: - number - 'null' description: >- Recruitment fee percentage (0–100) charged to the client on a successful placement. win_probability: type: - number - 'null' description: Probability of winning the deal (0–100). closed_date: type: - string - 'null' description: ISO 8601 expected or actual close date. open_date: type: string format: date description: Date the deal was opened (YYYY-MM-DD). last_contacted_at: type: - string - 'null' description: ISO 8601 timestamp of last contact with deal client contacts. deal_status: type: - object - 'null' properties: id: type: string format: uuid description: >- Deal status UUID. Use for deal_status_ids_included/excluded filters. name: type: string description: Human-readable status name (e.g. "Proposal Sent", "Closed Won"). required: - id - name description: Current deal status with id and name. Null if no status assigned. created_at: type: - string - 'null' description: ISO 8601 creation timestamp. client_name: type: - string - 'null' description: Client company name. client_id: type: - string - 'null' format: uuid description: Client company UUID. deal_lost_reason_id: type: - string - 'null' format: uuid description: Selected lost reason UUID, if this deal was lost. deal_lost_reason_text: type: - string - 'null' description: Additional notes explaining why the deal was lost. deal_lost_reason: type: - object - 'null' properties: id: type: string format: uuid description: Deal reason UUID. reason: type: string description: Human-readable deal reason. required: - id - reason description: Selected lost reason details, if this deal was lost. deal_won_reason_id: type: - string - 'null' format: uuid description: Selected won reason UUID, if this deal was won. deal_won_reason_text: type: - string - 'null' description: Additional notes explaining why the deal was won. deal_won_reason: type: - object - 'null' properties: id: type: string format: uuid description: Deal reason UUID. reason: type: string description: Human-readable deal reason. required: - id - reason description: Selected won reason details, if this deal was won. owners: type: array items: type: object properties: id: type: string format: uuid description: Team member UUID. Matches IDs from GET /v1/team-members. name: type: - string - 'null' description: Team member full name. required: - id - name description: Deal owners. custom_fields: type: array items: $ref: '#/components/schemas/CustomFieldValue' description: >- Custom attribute values. Included when include contains "custom_fields". required: - id - name - amount - currency_code - compensation - compensation_currency_code - pricing_rate - win_probability - closed_date - open_date - last_contacted_at - deal_status - created_at - client_name - client_id - deal_lost_reason_id - deal_lost_reason_text - deal_lost_reason - deal_won_reason_id - deal_won_reason_text - deal_won_reason - owners CustomFieldValue: type: object properties: attribute_id: type: string format: uuid description: >- Attribute definition UUID. Get definitions from GET /v1/custom-fields/{entity}. attribute_name: type: string description: Attribute display name. data_type: type: string enum: - string - integer - decimal - multi-select - single-select - boolean - date - multi-team-member - url description: Attribute data type. Determines which value field contains the data. job_id: type: - string - 'null' format: uuid description: >- Job UUID this attribute is scoped to. Null for global person-level attributes. Present when this custom field is specific to a job (candidate-level field). list_id: type: - string - 'null' format: uuid description: >- List UUID this attribute is scoped to. Null for global person-level attributes. value: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: 'null' description: >- Scalar value for string, integer, decimal, date, url, boolean types. Null for select/team-member types. tag: type: - object - 'null' properties: id: type: string format: uuid description: Tag option UUID. name: type: string description: Tag display name. required: - id - name description: >- Tag value for single-select and multi-select types. Null for other types. For multi-select, one CustomFieldValue row per tag. team_member: type: - object - 'null' properties: id: type: string format: uuid description: Team member UUID. name: type: - string - 'null' description: Team member full name. required: - id - name description: >- Team member value for multi-team-member type. Null for other types. One CustomFieldValue row per team member. required: - attribute_id - attribute_name - data_type - job_id - list_id - value - tag - team_member securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ````