> ## Documentation Index > Fetch the complete documentation index at: https://docs.getprescience.com/llms.txt > Use this file to discover all available pages before exploring further. # Report a completed payroll's HSA withholding > Post after every completed payroll. Stored once per eventId and version; a repeat returns what was stored. Prescience deposits only what is reported as withheld. See the Payroll results guide. ## OpenAPI ````yaml /api-reference/openapi.json post /groups/{groupId}/payroll-results openapi: 3.1.0 info: title: Prescience Partner API version: 1.1.0 description: >- Create employer groups, submit census records, generate preliminary market-rate quotes, create iframe sessions, create enrollments, and read aggregate account data. Money is always integer cents. Dates are `YYYY-MM-DD`; timestamps are ISO 8601 UTC. Final pricing, eligibility, network availability, and plan documents are confirmed during underwriting and onboarding. A BAA and data processing agreement are executed before live mode is enabled. contact: name: Prescience partner engineering email: partners@getprescience.com servers: - url: https://www.getprescience.com/api/partner/v1 description: >- Production. Test and live traffic share this host; mode comes from your API key. security: - bearerAuth: [] tags: - name: Health description: Connectivity and key checks. - name: Plans description: Static plan metadata. - name: Groups description: 'Employer groups: the root resource of every integration.' - name: Census description: Pre-enrollment census intake and ongoing member sync. - name: Quotes description: >- Preliminary quotes built from the stored census and current local market-plan snapshot. - name: Enrollments description: Plan selection and employer provisioning. - name: Account description: Aggregate, de-identified employer account data. - name: Webhooks description: Signed event delivery (standard-webhooks scheme). paths: /groups/{groupId}/payroll-results: post: tags: - Enrollments summary: Report a completed payroll's HSA withholding description: >- Post after every completed payroll. Stored once per eventId and version; a repeat returns what was stored. Prescience deposits only what is reported as withheld. See the Payroll results guide. operationId: postPayrollResults parameters: - name: groupId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PayrollResultEvent' responses: '200': description: Already received; the stored event. content: application/json: schema: $ref: '#/components/schemas/StoredPayrollResultEvent' '202': description: Stored and processed. content: application/json: schema: $ref: '#/components/schemas/StoredPayrollResultEvent' '400': description: Invalid fields. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid_request message: Payroll result failed validation. '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '409': description: Same eventId and version with different content. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: conflict message: >- Event evt_2026_10_30_regular version 1 was already received with different content. Send changes as a new version. '422': description: Inconsistent report. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid_request message: Payroll result is inconsistent. '429': $ref: '#/components/responses/RateLimited' components: schemas: PayrollResultEvent: type: object additionalProperties: false required: - eventId - version - companyId - payrollRunId - contributionYear - payday - type - status - isVoid - sourceReference - sourceTimestamp - rosterComplete - employees properties: eventId: type: string version: type: integer minimum: 1 companyId: type: string description: Your company ID (the group's externalId). payrollRunId: type: string contributionYear: type: integer payday: type: string format: date type: type: string enum: - regular - off_cycle - amendment - balancing - third_party_sick_pay description: >- Check payroll.type. Amendments and balancing payrolls are corrections. status: type: string enum: - draft - pending - processing - failed - partially_paid - paid description: Check payroll.status. Draft, pending and processing are held. isVoid: type: boolean description: Check payroll.is_void. sourceReference: type: string sourceTimestamp: type: string format: date-time rosterComplete: type: boolean description: >- Every employee with a Prescience HSA deduction on this payroll is listed, including zeros. employees: type: array items: type: object additionalProperties: false required: - employeeId - email - employmentStatus - payrollItemId - itemStatus - hsaWithheldCents - deductionId properties: employeeId: type: string email: type: string format: email employmentStatus: type: string enum: - active - inactive hsaWithheldCents: type: - integer - 'null' description: >- Actual pre-tax HSA withholding. 0 = confirmed none; null = unknown. Negative only on a completed correction. expectedHsaCents: type: - integer - 'null' minimum: 0 payrollItemId: type: string description: The employee's payroll item (Check payroll_item.id). itemStatus: type: string enum: - paid - failed - partially_paid - processing - pending - draft description: >- The item's status. A paid or partially paid item on a completed payroll counts as withheld. voidOf: type: - string - 'null' description: The payroll item this one voids (Check void_of). deductionId: type: - string - 'null' maxItems: 10000 StoredPayrollResultEvent: type: object properties: id: type: string eventId: type: string version: type: integer status: type: string enum: - received - held - processed - partial - failed holdReason: type: - string - 'null' employees: type: array items: type: object properties: employeeId: type: string outcome: type: string enum: - recorded - needs_review - validated - not_on_roster - not_tracked - before_tracking - payday_in_future - busy - rejected message: type: string receivedAt: type: string format: date-time processedAt: type: - string - 'null' format: date-time Error: type: object required: - error - message properties: error: type: string enum: - invalid_request - unauthorized - live_mode_disabled - forbidden - not_found - conflict - rates_pending - quote_expired - market_unavailable - census_required - rate_limited - server_error - not_configured - email_not_allowed - verification_failed description: >- Stable machine-readable error code. `email_not_allowed` and `verification_failed` come only from the iframe's own endpoints, which partners do not call. message: type: string description: >- Human-readable explanation. Wording may change; branch on `error`, not `message`. details: type: array description: Present on `invalid_request`. One entry per failed field. items: type: object required: - field - message properties: field: type: string example: zip message: type: string example: zip must be a 5-digit ZIP code index: type: integer description: >- For array payloads (census rows), the zero-based index of the failing row. example: 7 responses: Unauthorized: description: Missing, malformed, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthorized message: >- Provide a valid partner API key as `Authorization: Bearer psk_...`. NotFound: description: >- No such resource in this mode. Test keys only see test resources; live keys only see live resources. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: not_found message: No group grp_8c2f41d09a3e found. RateLimited: description: Rate limit exceeded. Honor `Retry-After`. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: rate_limited message: Too many requests. Please retry later. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 12 securitySchemes: bearerAuth: type: http scheme: bearer description: >- Partner API key. `psk_test_<32 hex>` for test mode, `psk_live_<32 hex>` for live mode. Store them in your secrets manager on issue. Live keys are shown once; the scoped partner portal can show an active sandbox key again. ````