> ## 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. # List retainer packs > A retainer pack is a set of retainers sold to a client company on one invoice. Each placement at that client claims the next open retainer, which is deducted from what the placement bills. Placements claim retainers when they are logged in the app. **Filters**: `organization_company_id` and `is_closed` (`false` returns the packs offered when logging a placement). **Sorting**: newest first. **Pagination**: `offset` and `limit` (default 20, max 100). A retainer claimed by a placement on a confidential job you cannot see shows `claim.is_restricted: true` with only the placement ID. **Access**: Everyone in the workspace can read retainer packs. API keys need the `fees:read` scope. ## OpenAPI ````yaml /api-reference/openapi-v1.json get /v1/retainer-packs 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. - name: Campaigns description: >- Create and edit email campaigns, enroll people through enrollment batches, and manage who is enrolled. paths: /v1/retainer-packs: get: tags: - Retainer Packs summary: List retainer packs description: >- A retainer pack is a set of retainers sold to a client company on one invoice. Each placement at that client claims the next open retainer, which is deducted from what the placement bills. Placements claim retainers when they are logged in the app. **Filters**: `organization_company_id` and `is_closed` (`false` returns the packs offered when logging a placement). **Sorting**: newest first. **Pagination**: `offset` and `limit` (default 20, max 100). A retainer claimed by a placement on a confidential job you cannot see shows `claim.is_restricted: true` with only the placement ID. **Access**: Everyone in the workspace can read retainer packs. API keys need the `fees:read` scope. operationId: listRetainerPacks parameters: - schema: type: string format: uuid description: Only return packs for this client company. required: false description: Only return packs for this client company. name: organization_company_id in: query - schema: type: boolean description: >- `false` returns open packs only (the ones offered when logging a placement), `true` closed packs only. Omit for both. required: false description: >- `false` returns open packs only (the ones offered when logging a placement), `true` closed packs only. Omit for both. name: is_closed in: query - schema: type: - integer - 'null' minimum: 0 default: 0 description: Records to skip for pagination. Defaults to 0. required: false description: Records to skip for pagination. Defaults to 0. name: offset in: query - schema: type: integer minimum: 1 maximum: 100 default: 20 description: Max records per page (1-100). Defaults to 20. required: false description: Max records per page (1-100). Defaults to 20. name: limit in: query responses: '200': description: Retainer packs fetched content: application/json: schema: $ref: '#/components/schemas/RetainerPacksListResponse' example: success: true data: - id: 0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d organization_company_id: 2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e organization_company_name: Acme Corp name: Q4 2026 GTM pack currency_code: USD invoice_number: INV-1042 link_extra_hires: true firm_commission_percent: 10 is_closed: false closed_at: null fee_status: id: 5e6f7a8b-9c0d-4e1f-8a3b-4c5d6e7f8a9b name: Paid status_type: paid color: '#22c55e' expected_date: '2026-10-01' actual_payment_date: '2026-10-15' amount_each: 12000 default_split: - team_member_id: 6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c team_member_name: Theo Grant role: Sales split_percentage: 70 - team_member_id: 7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d team_member_name: Ana Ruiz role: null split_percentage: 30 retainers: - id: 1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e position: 1 amount: 12000 firm_commission_percent: 10 claim: is_restricted: false placement_fee_event_id: 9c0d1e2f-3a4b-4c5d-8e6f-7a8b9c0d1e2f job_id: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d job_title: VP of Engineering candidate_id: 3c4d5e6f-7a8b-4c9d-8e1f-2a3b4c5d6e7f person_id: 4d5e6f7a-8b9c-4d0e-9f2a-3b4c5d6e7f8a person_name: Jordan Lee start_date: '2026-11-03' splits: - team_member_id: 7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d team_member_name: Ana Ruiz role: Recruiter split_percentage: 60 split_amount: 6480 - team_member_id: 6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c team_member_name: Theo Grant role: Sales split_percentage: 40 split_amount: 4320 - id: 2c3d4e5f-6a7b-4c8d-8e9f-1a2b3c4d5e6f position: 2 amount: 12000 firm_commission_percent: 10 claim: is_restricted: true placement_fee_event_id: 0d1e2f3a-4b5c-4d6e-9f7a-8b9c0d1e2f3a splits: - team_member_id: 6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c team_member_name: Theo Grant role: Sales split_percentage: 70 split_amount: 7560 - team_member_id: 7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d team_member_name: Ana Ruiz role: null split_percentage: 30 split_amount: 3240 - id: 3d4e5f6a-7b8c-4d9e-8f0a-2b3c4d5e6f7a position: 3 amount: 12000 firm_commission_percent: 10 claim: null splits: - team_member_id: 6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c team_member_name: Theo Grant role: Sales split_percentage: 70 split_amount: 7560 - team_member_id: 7a8b9c0d-1e2f-4a3b-8c5d-6e7f8a9b0c1d team_member_name: Ana Ruiz role: null split_percentage: 30 split_amount: 3240 extra_hires: [] adjustments: [] summary: retainer_count: 3 claimed_count: 2 open_count: 1 extra_hire_count: 0 total_amount: 36000 remaining_amount: 12000 adjustments_total: 0 net_retained: 36000 created_at: '2026-09-28T09:12:44.000Z' updated_at: '2026-10-15T16:03:10.000Z' - id: 4e5f6a7b-8c9d-4e0f-9a1b-3c4d5e6f7a8b organization_company_id: 2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e organization_company_name: Acme Corp name: H1 2026 leadership pack currency_code: EUR invoice_number: INV-0981 link_extra_hires: true firm_commission_percent: 0 is_closed: true closed_at: '2026-07-01T10:00:00.000Z' fee_status: id: 5e6f7a8b-9c0d-4e1f-8a3b-4c5d6e7f8a9b name: Paid status_type: paid color: '#22c55e' expected_date: '2026-01-15' actual_payment_date: '2026-02-01' amount_each: 10000 default_split: - team_member_id: 6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c team_member_name: Theo Grant role: Sales split_percentage: 100 retainers: - id: 5f6a7b8c-9d0e-4f1a-8b2c-4d5e6f7a8b9c position: 1 amount: 10000 firm_commission_percent: 0 claim: is_restricted: false placement_fee_event_id: 1e2f3a4b-5c6d-4e7f-8a8b-9c0d1e2f3a4b job_id: 6a7b8c9d-0e1f-4a2b-9c3d-5e6f7a8b9c0d job_title: Chief Financial Officer candidate_id: 7b8c9d0e-1f2a-4b3c-8d4e-6f7a8b9c0d1e person_id: 8c9d0e1f-2a3b-4c4d-9e5f-7a8b9c0d1e2f person_name: Priya Shah start_date: '2026-03-02' splits: - team_member_id: 6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c team_member_name: Theo Grant role: Sales split_percentage: 100 split_amount: 10000 - id: 6a7b8c9d-0e1f-4a2b-8c3d-5e6f7a8b9c0e position: 2 amount: 10000 firm_commission_percent: 0 claim: is_restricted: false placement_fee_event_id: 2f3a4b5c-6d7e-4f8a-9b9c-0d1e2f3a4b5c job_id: 9d0e1f2a-3b4c-4d5e-8f6a-8b9c0d1e2f3a job_title: Head of Sales candidate_id: 0e1f2a3b-4c5d-4e6f-9a7b-9c0d1e2f3a4b person_id: 1f2a3b4c-5d6e-4f7a-8b8c-0d1e2f3a4b5c person_name: Marcus Webb start_date: '2026-04-13' splits: - team_member_id: 6f7a8b9c-0d1e-4f2a-9b4c-5d6e7f8a9b0c team_member_name: Theo Grant role: Sales split_percentage: 100 split_amount: 10000 extra_hires: - placement_fee_event_id: 3a4b5c6d-7e8f-4a9b-8c0d-1e2f3a4b5c6d job_id: 2a3b4c5d-6e7f-4a8b-9c9d-1e2f3a4b5c6e job_title: VP of Marketing candidate_id: 4b5c6d7e-8f9a-4b0c-9d1e-2f3a4b5c6d7e person_id: 5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f person_name: Elena Novak start_date: '2026-06-01' adjustments: - id: 6d7e8f9a-0b1c-4d2e-9f3a-4b5c6d7e8f9a amount: 2500 comment: Goodwill credit after a guarantee replacement adjusted_on: '2026-07-01' created_at: '2026-07-01T10:00:00.000Z' summary: retainer_count: 2 claimed_count: 2 open_count: 0 extra_hire_count: 1 total_amount: 20000 remaining_amount: 0 adjustments_total: 2500 net_retained: 17500 created_at: '2026-01-10T08:30:00.000Z' updated_at: '2026-07-01T10:00:00.000Z' meta: total: 2 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. details: type: object additionalProperties: {} description: >- Extra facts about the error when they help you fix it, such as a limit and when it resets. 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. details: type: object additionalProperties: {} description: >- Extra facts about the error when they help you fix it, such as a limit and when it resets. 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. details: type: object additionalProperties: {} description: >- Extra facts about the error when they help you fix it, such as a limit and when it resets. required: - code - message required: - success - error components: schemas: RetainerPacksListResponse: type: object properties: success: type: boolean enum: - true data: type: array items: $ref: '#/components/schemas/RetainerPack' 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 RetainerPack: type: object properties: id: type: string format: uuid description: Retainer pack UUID. organization_company_id: type: string format: uuid description: Client company the pack belongs to. organization_company_name: type: - string - 'null' description: Client company name. name: type: string description: Pack name. currency_code: type: string description: ISO 4217 currency code. invoice_number: type: - string - 'null' description: Invoice number of the pack. link_extra_hires: type: boolean description: >- Whether hires after the last claimed retainer still link to the pack at 0. firm_commission_percent: type: number description: Percent of each open retainer the firm keeps. is_closed: type: boolean description: Closed packs are no longer offered when logging placements. closed_at: type: - string - 'null' description: ISO 8601 time the pack was closed. fee_status: type: object properties: id: type: string format: uuid description: Fee status UUID. name: type: string description: Status name (e.g. "Paid"). status_type: type: string enum: - pending - invoiced - paid - cancelled description: >- Lifecycle category of the status: `pending`, `invoiced`, `paid` or `cancelled`. Revenue reports count `paid` fees as collected. color: type: string description: Hex color code of the status badge. required: - id - name - status_type - color description: Status of the pack invoice, shared by every retainer. expected_date: type: - string - 'null' format: date description: Invoice date. actual_payment_date: type: - string - 'null' format: date description: Date the pack was marked paid. amount_each: type: number description: >- Amount of each open retainer (the pack's current per-retainer amount). default_split: type: array items: type: object properties: team_member_id: type: string format: uuid description: Credited team member UUID. team_member_name: type: - string - 'null' description: Team member full name. role: type: - string - 'null' description: Why this person is credited, if set. split_percentage: type: number description: Share of the credit in percent. required: - team_member_id - team_member_name - role - split_percentage description: The pack's retainer split, used by its open retainers. retainers: type: array items: type: object properties: id: type: string format: uuid description: Retainer UUID. position: type: number description: '1-based position for display (#1, #2, ...).' amount: type: number description: Retainer amount in the pack currency. firm_commission_percent: type: number description: Percent of this retainer the firm keeps. claim: oneOf: - type: object properties: is_restricted: type: boolean enum: - false description: The placement is visible to you. placement_fee_event_id: type: string format: uuid description: Placement UUID. job_id: type: string format: uuid description: Job the placement was logged on. job_title: type: string description: Job title. candidate_id: type: - string - 'null' format: uuid description: Candidate record (the person on that job). person_id: type: - string - 'null' format: uuid description: Placed person UUID. person_name: type: - string - 'null' description: Placed person name. start_date: type: - string - 'null' format: date description: Placement start date. required: - is_restricted - placement_fee_event_id - job_id - job_title - candidate_id - person_id - person_name - start_date - type: object properties: is_restricted: type: boolean enum: - true description: >- The placement is on a confidential job you cannot see; only its ID is returned. placement_fee_event_id: type: string format: uuid description: Placement UUID. required: - is_restricted - placement_fee_event_id - type: 'null' description: >- The placement that used this retainer, or null while it is open. splits: type: array items: type: object properties: team_member_id: type: string format: uuid description: Credited team member UUID. team_member_name: type: - string - 'null' description: Team member full name. role: type: - string - 'null' description: Why this person is credited, if set. split_percentage: type: number description: Share of the credit in percent. split_amount: type: number description: >- This person's credit for the retainer, after the firm commission. required: - team_member_id - team_member_name - role - split_percentage - split_amount description: >- Credit for this retainer. Open retainers follow the pack's split; claimed ones keep the split they were claimed with. required: - id - position - amount - firm_commission_percent - claim - splits description: Every retainer in the pack, in order. extra_hires: type: array items: type: object properties: placement_fee_event_id: type: string format: uuid description: Placement UUID. job_id: type: string format: uuid description: Job the placement was logged on. job_title: type: string description: Job title. candidate_id: type: - string - 'null' format: uuid description: Candidate record (the person on that job). person_id: type: - string - 'null' format: uuid description: Placed person UUID. person_name: type: - string - 'null' description: Placed person name. start_date: type: - string - 'null' format: date description: Placement start date. required: - placement_fee_event_id - job_id - job_title - candidate_id - person_id - person_name - start_date description: >- A placement linked to the pack after every paid retainer was claimed, at a 0 retainer and billed the full fee. description: Placements linked to the pack at a 0 retainer. adjustments: type: array items: type: object properties: id: type: string format: uuid description: Adjustment UUID. amount: type: number description: Money returned, stored positive. comment: type: - string - 'null' description: Note on the adjustment. adjusted_on: type: string format: date description: Date of the adjustment. created_at: type: string description: ISO 8601 creation timestamp. required: - id - amount - comment - adjusted_on - created_at description: Refunds and other money returned on the pack, oldest first. summary: type: object properties: retainer_count: type: number description: Number of retainers in the pack. claimed_count: type: number description: Retainers used by a placement. open_count: type: number description: Retainers not used yet. extra_hire_count: type: number description: Placements linked after every retainer was claimed. total_amount: type: number description: Sum of every retainer amount. remaining_amount: type: number description: Sum of the open retainer amounts. adjustments_total: type: number description: Sum of the adjustments. net_retained: type: number description: Total amount minus adjustments. required: - retainer_count - claimed_count - open_count - extra_hire_count - total_amount - remaining_amount - adjustments_total - net_retained created_at: type: string description: ISO 8601 creation timestamp. updated_at: type: string description: ISO 8601 last update timestamp. required: - id - organization_company_id - organization_company_name - name - currency_code - invoice_number - link_extra_hires - firm_commission_percent - is_closed - closed_at - fee_status - expected_date - actual_payment_date - amount_each - default_split - retainers - extra_hires - adjustments - summary - created_at - updated_at securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate with a Bearer token: API key, OAuth token, or session token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.