> ## Documentation Index > Fetch the complete documentation index at: https://developers.primulamanagement.com/llms.txt > Use this file to discover all available pages before exploring further. # List family balances > Returns one balance row per family for the requested company and school. Both identifiers are required and must be allowed for the authenticated session. Rows always contain family_id, family_name, balance and transaction_date. Results may be filtered by family IDs or family name and are paginated with page and per_page. ## OpenAPI ````yaml https://api.primulamanagement.com/primula/api/v3/openapi.yaml get /family_balances openapi: 3.1.0 info: title: Primula Tracker API V3 version: 3.0.0 description: >- Reference for the 68 operations registered under `/primula/api/v3` in the V3 release baseline. ## Authentication Create a session with `POST /sessions`, then send `Authorization: Bearer ` on protected operations. Tokens must remain associated with a valid server-side session. The returned refresh token has no refresh endpoint in V3. Session company and school restrictions are documented per operation; company_id is not inferred from the token. ## Responses and errors Collections generally return bare JSON arrays and items return bare JSON objects. Report objects, nested maps, and update summaries are explicitly described below. List metadata travels in response headers rather than an envelope. Empty lists written by collection helpers are `[]`; fields backed by nullable values may be `null`, and omitted properties are distinguished from null properties in schemas. Handlers generally return `{ "error": "message" }`; authentication middleware and activity proxy errors use plain text. Unsupported methods on a registered path return 405 with Allow after any applicable authentication checks. ## Pagination and projections Only operations documenting page/per_page support pagination. Defaults are page=1 and per_page=100. Values exceeding the documented effective cap are clamped, not rejected. X-Total-Count describes the full matching set. Link contains applicable navigation links and is omitted for a single page. Aggregates use limit (default 50, effective cap 200) instead of pagination and send X-Truncated only when rows were omitted. The fields parameter, where available, selects the exact response properties; unsupported fields return 400. ## Query encoding Multi-value parameters documented as arrays accept repeated keys or comma-separated values. Prefer repeated keys for long UUID lists. Except for the two activity proxy operations, query parsing drops the entire query string above 8192 bytes and truncates each decoded query value to 128 bytes. Parameter combinations and interpretation differ by resource and representation; consult each operation. Unknown parameters are rejected only where explicitly documented. ## Dates and writes Calendar dates use YYYY-MM-DD, monthly periods use YYYY-MM, and timestamp formats are described in the corresponding schema. Defaults such as today depend on the server clock. PATCH operations change only the documented properties and reject unknown body properties. Clearing values, authorization, and partial-write behavior vary by resource and are described per operation. Examples use synthetic identifiers and placeholder tokens. Replace the server host before using an interactive API client. servers: - url: https://{host}/primula/api/v3 description: V3 API deployment. Replace the placeholder hostname. variables: host: default: api.example.com security: - bearerAuth: [] tags: - name: sessions x-group: Sessions description: Sessions. - name: schools x-group: Schools description: Schools. - name: companies x-group: Companies description: Companies. - name: rooms x-group: Rooms description: Rooms. - name: programs x-group: Programs description: School programs (Configure Programs). - name: users x-group: Users description: Users. - name: leads x-group: Leads description: Leads. - name: students x-group: Students description: Students. - name: payments x-group: Payments description: Payments. - name: invoices x-group: Invoices description: Invoices. - name: enrollments x-group: Enrollments description: Enrollments. - name: family_balances x-group: Family balances description: Family balances. - name: pre_registration_fallout x-group: Pre registration fallout description: Pre registration fallout. - name: absences x-group: Absences description: Absences. - name: waitlist x-group: Waitlist description: Waitlist. - name: billing_plans x-group: Billing plans description: Billing plans. - name: spaces x-group: Spaces description: Spaces. - name: enrollment_tracker x-group: Enrollment tracker description: Enrollment tracker. - name: efficiency_ratios x-group: Efficiency ratios description: Efficiency ratios. - name: procare_messages x-group: Procare messages description: Procare messages. - name: messages x-group: Messages description: Captured Procare conversations. - name: attendances x-group: Attendances description: Attendances. - name: billing_attendance_audits x-group: Billing attendance audits description: Billing attendance audits. - name: classroom_attendance x-group: Classroom attendance description: Classroom attendance. - name: activities_summary x-group: Activities summary description: Activities summary. - name: activity_details x-group: Activity details description: Activity details. - name: data_refresh x-group: Data refresh description: Data refresh. - name: sibling_discounts x-group: Sibling discounts description: Sibling discounts. - name: new_start_tracker x-group: New start tracker description: New start tracker. - name: withdrawal_tracker x-group: Withdrawal tracker description: Withdrawal tracker. - name: transition_tracker x-group: Transition tracker description: Transition tracker. - name: gusto_companies x-group: Gusto companies description: Gusto companies. - name: gusto_employees x-group: Gusto employees description: Gusto employees. - name: gusto_contractors x-group: Gusto contractors description: Gusto contractors. - name: gusto_payrolls x-group: Gusto payrolls description: Gusto payrolls. - name: procare_staff x-group: Procare staff description: Procare staff. paths: /family_balances: get: tags: - family_balances summary: List family balances description: >- Returns one balance row per family for the requested company and school. Both identifiers are required and must be allowed for the authenticated session. Rows always contain family_id, family_name, balance and transaction_date. Results may be filtered by family IDs or family name and are paginated with page and per_page. operationId: GetFamilyBalancesV3 parameters: - $ref: '#/components/parameters/CompanyId' - name: school_id in: query required: true description: School UUID. Must be allowed for the authenticated session. schema: type: string format: uuid example: 22222222-2222-4222-8222-222222222222 - name: family_ids in: query required: false description: >- Optional family UUIDs. Accepts repeated query parameters or comma-separated values; empty entries are dropped and surrounding whitespace is trimmed. schema: type: array items: type: string format: uuid style: form explode: true - name: family_name in: query required: false description: Case-insensitive family-name substring filter. schema: type: string - name: page in: query required: false description: One-based page number. schema: type: integer minimum: 1 default: 1 example: 1 - name: per_page in: query required: false description: >- Items per page; defaults to 200 and values greater than 200 are clamped to 200. schema: type: integer minimum: 1 default: 200 maximum: 200 example: 200 responses: '200': description: Successful response. content: application/json: schema: type: array items: $ref: '#/components/schemas/FamilyBalance' examples: rows: summary: Family balances value: - family_id: 77777777-7777-4777-8777-777777777777 family_name: Example family balance: 150 transaction_date: '2026-01-15' headers: X-Total-Count: $ref: '#/components/headers/TotalCount' Link: $ref: '#/components/headers/Link' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '405': $ref: '#/components/responses/405' '500': $ref: '#/components/responses/500' components: parameters: CompanyId: name: company_id in: query required: true description: >- Company UUID. Must equal the authenticated session company when that session has a company assigned; the equality check is skipped for sessions without one. schema: type: string format: uuid example: 11111111-1111-4111-8111-111111111111 schemas: FamilyBalance: type: object description: >- A sparse row containing only the selected fields. Default fields: family_id, family_name, balance, transaction_date. properties: family_id: type: string description: Family id. school_id: type: string description: School id. family_name: type: string family_student_count: type: integer transaction_id: type: string description: Transaction id. transaction_date: type: string format: date amount: type: number balance: type: number receipt_number: type: string kind: type: string additionalProperties: false Error: type: object properties: error: type: string description: Human-readable error message. required: - error description: Error. headers: TotalCount: description: >- Total matching rows before pagination, or matching groups before the aggregate limit. For unpaginated arrays, the number of returned rows. schema: type: integer minimum: 0 example: 125 Link: description: >- Pagination links using rel="next", "last", "prev", and "first". Only applicable links are sent; absent when all results fit on one page. Links preserve the original query parameters. schema: type: string example: >- ; rel="next" responses: '400': description: Invalid or missing parameters or request body. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid or missing parameters or request body. '401': description: >- Missing or invalid Bearer token, or an absent, invalid or expired server-side session. The authentication middleware returns plain text with a trailing newline. content: text/plain: schema: type: string examples: missing: value: | missing authorization header invalid: value: | Unauthorized expired: value: | Session expired '403': description: The authenticated session is not allowed to perform this operation. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: >- The authenticated session is not allowed to perform this operation. '405': description: The path exists but does not support this HTTP method. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: The path exists but does not support this HTTP method. headers: Allow: description: Comma-separated HTTP methods accepted by this path. schema: type: string '500': description: The operation could not be completed. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: The operation could not be completed. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Access token issued by POST /sessions and associated with a valid server-side session. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.