> ## Documentation Index > Fetch the complete documentation index at: https://api-docs.helpyousponsor.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a household > Creates an active household and attaches the primary plus deduplicated additional donors under one membership lock. Every member must be active in this organization and outside any existing household. Material stewardship impact returns 409 with an expiring confirmation token and required contact/archive repairs; resubmit the same reviewed change with plan_impact_version and plan_repairs. ## OpenAPI ````yaml post /admin/households openapi: 3.0.0 info: title: Gratona API description: >- REST API for the Gratona fundraising platform, including donor, donation, sponsorship, program, event, and integration workflows. Endpoints are organized by tag. Most endpoints require either a Passport bearer token or an issued API key — see the Security Schemes section. contact: name: Gratona Engineering url: https://gratona.com email: devs@gratona.com version: 1.0.0 servers: - url: https://api.gratona.com/v1 description: Server Version 1.0.0 security: [] tags: - name: Auth description: >- Login, signup, logout, password reset, and email verification for admin users and donors. - name: Donors description: >- Donor records: CRUD, profile fields, household linkage, search, filters, merge, and duplicate detection. - name: Donations description: >- Individual donation records, recurring commitments, soft credits, refunds, designations, and exports. - name: Sponsorships description: >- Donor-to-entity commitment relationships, lifecycle transitions, and commitment-specific filters. - name: Entities description: >- Recipient records (children, families, projects, animals, etc.), their status, and entity-level fields. - name: Programs description: >- Program / campaign configuration: hierarchy, settings, and program-level metadata. - name: Forms description: >- Custom form builder (HysForm), form fields, standardized donor fields, and field migrations. - name: Trips description: >- Mission-trip management: trips, participants, budgets, tasks, e-signatures, fundraising milestones, and background checks. - name: Communications description: >- Email templates, SMS, newsletters, donor email manager, and per-donor notes. - name: Payments description: >- Payment-gateway management (Stripe, PayPal, Flutterwave, QuickBooks). Excludes inbound webhooks — see the Webhooks tag. - name: Reports description: Dashboards, analytics, scheduled reports, and exports. - name: Admin description: >- Client-account administration: users, groups/permissions, settings, integrations, and account lifecycle. - name: Donor Portal description: >- Endpoints consumed by the donor-facing portal (donor login, dashboard, donation history, messages). - name: Recipient Portal description: Endpoints consumed by the recipient-facing portal. - name: Public description: >- Unauthenticated public endpoints: donor signup, public trip pages, peer-to-peer campaigns, public checkout. - name: Webhooks description: >- Inbound webhooks from third parties (Stripe, PayPal, Flutterwave, Checkr, DropboxSign). Annotated minimally for reference; payload shapes are owned by the upstream provider. - name: Events description: >- Event setup, invitations, registration, ticketing, attendance and event reporting. - name: Journeys description: >- Journey graphs, activation, enrollment, message templates and event follow-up automations. - name: Tasks description: Workspace tasks, assignments, saved task views and record collaboration. - name: Fundraising description: >- Fundraising portfolios, stewardship plans, giving anniversaries and personal donor follow-up. - name: Impact Stories description: Story intake, review, assets, consent and publication workflows. - name: Integrations description: Workspace integration connections, mappings, synchronization and recovery. - name: Email Calendar description: Connected email/calendar accounts and donor interactions. - name: Spaces description: Workspace Spaces and collaborative Pages. - name: Library description: Workspace documents, source connections, files and analysis. - name: Intelligence description: Donor intelligence and Tali workspace workflows. - name: Automation description: >- V3 automation primitive discovery, input validation, invocation and Zapier contracts. - name: Schema description: V3 model, enum, capability and scope discovery. - name: Zapier description: Zapier automation connections, polling feeds and actions. - name: Files description: Files - name: Client description: Client - name: Payment Gateways description: Payment Gateways - name: Email Settings description: Email Settings - name: Admin Dashboard description: Admin Dashboard - name: Recipients description: Recipients - name: Historical Archived Updates description: Historical Archived Updates - name: Team & access description: Team & access - name: Settings description: Settings - name: Notifications description: Notifications - name: Participation description: Participation - name: Users description: Users - name: Wrapped description: Wrapped - name: Donor SignUp description: Donor SignUp - name: Frontend description: Frontend - name: User description: User - name: Workspace description: Workspace paths: /admin/households: post: tags: - Donors summary: Create a household description: >- Creates an active household and attaches the primary plus deduplicated additional donors under one membership lock. Every member must be active in this organization and outside any existing household. Material stewardship impact returns 409 with an expiring confirmation token and required contact/archive repairs; resubmit the same reviewed change with plan_impact_version and plan_repairs. operationId: HouseholdController_store requestBody: required: true content: application/json: schema: required: - name - primary_contact_id properties: name: description: Nonblank household name. type: string maxLength: 255 example: Doe household primary_contact_id: description: >- Active organization donor, automatically included in membership. type: integer example: 42 address: properties: line1: description: Household line1. type: string maxLength: 255 example: 10 Main Street nullable: true line2: description: Household line2. type: string maxLength: 255 example: Apt 2 nullable: true city: description: Household city. type: string maxLength: 100 example: Kampala nullable: true state: description: Household state. type: string maxLength: 100 example: Central nullable: true postal_code: description: Household postal_code. type: string maxLength: 20 example: '00000' nullable: true country: description: Household country. type: string maxLength: 100 example: Uganda nullable: true type: object nullable: true json_fields: description: >- Household custom values; request accepts a JSON object or list. oneOf: - type: object additionalProperties: true - type: array items: type: string - type: string enum: - null nullable: true donor_ids: type: array items: description: Active member donor; primary is included automatically. type: integer example: 42 nullable: true plan_impact_version: description: >- Token from a 409 stewardship impact response; required when open plan impact is material. type: string maxLength: 4096 example: issued-household-impact-version nullable: true plan_repairs: type: array items: required: - plan_id - action properties: plan_id: description: Affected plan. type: integer minimum: 1 example: 42 action: description: >- Chosen required repair: replace_action_donor or archive_plan. type: string maxLength: 64 example: replace_action_donor action_donor_id: description: Eligible replacement action donor when required. type: integer example: 42 nullable: true reason: description: Nonblank reason for archive_plan. type: string maxLength: 1000 example: Household is being removed. nullable: true type: object nullable: true type: object responses: '201': description: Create a household completed. content: application/json: schema: properties: success: description: Operation completed. type: boolean example: true message: description: Confirmation. type: string example: Household created successfully household: $ref: '#/components/schemas/CrmApiHouseholdRecord' type: object '401': description: Authentication is required. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Insufficient permission or feature access. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Primary donor not found in the organization. content: application/json: schema: $ref: '#/components/schemas/NotFoundResponse' '409': description: >- Household membership or stewardship plan impact changed or needs confirmation. content: application/json: schema: properties: status: description: Conflict status. type: string example: error code: description: Plan lifecycle conflict. type: string example: PLAN_IMPACT_CONFIRMATION_REQUIRED message: description: Review prompt. type: string example: Review household plan impact before saving. data: $ref: '#/components/schemas/CrmApiHouseholdPlanImpact' type: object '422': description: Invalid household input or membership/primary-contact restriction. content: application/json: schema: $ref: '#/components/schemas/RequestRejection' '500': description: Household operation failed. content: application/json: schema: properties: success: description: Operation failed. type: boolean example: false message: description: Failure summary. type: string example: Failed to update household error: description: Underlying error message. type: string example: Unable to complete household change. type: object security: - bearerAuth: [] - apiKeyAuth: [] components: schemas: CrmApiHouseholdRecord: properties: id: description: Household ID. type: integer example: 42 client_id: description: Organization ID. type: integer example: 42 migration_id: description: Optional legacy migration identifier. type: string example: Example nullable: true name: description: Household name. type: string example: Doe household primary_contact_id: description: Primary donor ID. type: integer example: 42 nullable: true assigned_fundraiser_user_id: description: Household relationship manager. type: integer example: 42 nullable: true donor_ids: type: array items: description: Member donor ID. type: integer example: 42 fundraising_profile_json: description: Decoded household fundraising profile. oneOf: - type: object additionalProperties: true - type: array items: type: string - type: string enum: - null nullable: true json_fields: description: Decoded custom household values. oneOf: - type: object additionalProperties: true - type: array items: type: string - type: string enum: - null nullable: true is_active: description: Whether household is active. type: boolean example: false address_line1: description: Household line1. type: string maxLength: 255 example: 10 Main Street nullable: true address_line2: description: Household line2. type: string maxLength: 255 example: Apt 2 nullable: true city: description: Household city. type: string maxLength: 100 example: Kampala nullable: true state: description: Household state. type: string maxLength: 100 example: Central nullable: true postal_code: description: Household postal_code. type: string maxLength: 20 example: '00000' nullable: true country: description: Household country. type: string maxLength: 100 example: Uganda nullable: true created_at: description: Created. type: string format: date-time example: '2026-10-20T12:00:00Z' nullable: true updated_at: description: Updated. type: string format: date-time example: '2026-10-20T12:00:00Z' nullable: true type: object ErrorResponse: title: ErrorResponse description: >- Generic error envelope used by most controllers. Most error responses pair a human-readable `message` with `status: error`. Some endpoints additionally include `errors` (validator errors), `error` (legacy single-error string), `code`, or domain-specific context fields. required: - message properties: message: description: Human-readable error message. type: string example: Something went wrong. Please try again. status: description: >- Always the literal string `error` for failures. Some endpoints omit this field. type: string example: error error: description: Legacy single error code/string used by older endpoints. type: string example: invalid_request nullable: true code: description: >- Optional application-level error code (not all endpoints populate this). type: string example: DONOR_NOT_FOUND nullable: true type: object NotFoundResponse: title: NotFoundResponse description: >- Returned with HTTP 404 when a resource lookup misses (typically because the id doesn't exist OR is scoped to a different `client_id`). Note: many endpoints intentionally collapse 'not found' and 'forbidden' into a single 404 to avoid leaking which records exist in another tenant. required: - message properties: message: description: >- Human-readable message. Often a more specific string like `Donor not found` or `Trip not found`. type: string example: Not Found status: type: string example: error type: object CrmApiHouseholdPlanImpact: properties: material_impact: description: >- Membership, primary contact or removal materially affects open plans. type: boolean example: false affected_plans: type: array items: $ref: '#/components/schemas/StewardshipPlanImpactHeader' group_plans: type: array items: type: string maxItems: 0 transfer_candidates: type: array items: type: string maxItems: 0 scope_changes: type: array items: properties: plan_id: description: Affected plan. type: integer example: 42 next_members: type: array items: properties: member_type: description: Plan member kind. type: string enum: - donor - household - relationship_group example: donor member_id: description: Member ID. type: integer example: 42 scope_role: description: Member role. type: string example: core type: object eligible_action_donor_ids: type: array items: description: Eligible remaining action donor. type: integer example: 42 invalid_open_move_ids: type: array items: description: Open move needing a contact repair. type: integer example: 42 type: object eligible_action_donor_ids: type: array items: description: Proposed member. type: integer example: 42 collisions: type: array items: properties: plan_id: description: Affected plan. type: integer example: 42 conflicting_plan: description: Existing overlapping plan header. type: object additionalProperties: true type: object authority_changes: type: array items: type: string maxItems: 0 required_repairs: type: array items: properties: plan_id: description: Plan requiring review. type: integer example: 42 choices: type: array items: description: Repair permitted by this impact. type: string enum: - replace_action_donor - archive_plan example: replace_action_donor eligible_action_donor_ids: type: array items: description: Allowed replacement contact. type: integer example: 42 recommended_action_donor_id: description: Recommended replacement contact. type: integer example: 42 nullable: true type: object proposed_member_donor_ids: type: array items: description: Proposed household donor. type: integer example: 42 primary_contact_id: description: Proposed primary. type: integer example: 42 nullable: true plan_repairs: type: array items: properties: plan_id: description: Plan to archive on household deactivation. type: integer example: 42 type: object command: description: Confirmation command. type: string enum: - household_membership - household_deactivate example: household_membership expires_at: description: Five-minute confirmation expiry. type: string format: date-time example: '2026-10-20T12:00:00Z' nullable: true impact_version: description: Signed actor/client/household/command/impact confirmation. type: string example: issued-household-impact-version conflicts: description: >- Overlap details returned instead of full impact for PLAN_SCOPE_OVERLAP. type: array items: properties: plan_id: description: Affected plan. type: integer example: 42 conflicting_plan: description: Existing overlapping plan header. type: object additionalProperties: true type: object type: object RequestRejection: description: >- Request or workflow rejection. Framework field-validation failures contain errors; semantic rejections may contain message without errors; legacy/provider failures may use error and error_code. The operation description identifies the rejected condition. Domain responses may add current revision, limits or other conflict context. anyOf: - $ref: '#/components/schemas/ValidationErrorResponse' - $ref: '#/components/schemas/ErrorResponse' - required: - error properties: error: description: Legacy or provider-facing error message. type: string example: The request could not be completed. error_code: description: Stable domain error code, when provided. type: string example: WORKFLOW_UNAVAILABLE type: object StewardshipPlanImpactHeader: properties: id: description: Record identifier in this organization. type: integer example: 42 nullable: false subject: properties: type: type: string enum: - donor - household - relationship_group example: donor id: description: Record identifier in this organization. type: integer example: 42 nullable: false type: object stage: type: string enum: - qualifying - managed example: qualifying status: type: string enum: - draft - active - paused - completed - archived example: draft period: properties: start: description: Calendar date. type: string format: date example: '2026-10-20' nullable: true end: description: Calendar date. type: string format: date example: '2026-10-20' nullable: true type: object version: description: Optimistic concurrency version. type: integer example: 2 nullable: false action_donor_id: description: Record identifier in this organization. type: integer example: 42 nullable: true scope_version: description: Count. type: integer example: 2 nullable: false type: object ValidationErrorResponse: title: ValidationErrorResponse description: >- Returned with HTTP 422 when `Validator::make($data, $rules)` fails. The `errors` map is keyed by the failing field name; each value is an array of human-readable error messages for that field. Most controllers also include a top-level `status: error`. required: - errors properties: errors: description: >- Map of field name to array of validator error messages. Example: `{email: [The email field is required.], amount: [The amount must be a number.]}`. type: object additionalProperties: type: array items: type: string status: description: Always the literal string `error`. type: string example: error message: description: >- Optional summary message — present on some endpoints, absent on others. type: string example: The given data was invalid. nullable: true type: object securitySchemes: bearerAuth: type: http description: Passport bearer token authentication for legacy admin sessions. scheme: bearer bearerFormat: JWT apiKeyAuth: type: apiKey description: Gratona API key sent with the compatibility header X-HYS-API-Key. name: X-HYS-API-Key in: header ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.