openapi: 3.1.0 info: title: Givebutter Households API version: 1.0.0 description: The Households surface of the Givebutter Public API — 5 operation(s). Split by tag from Givebutter's own published OpenAPI at https://givebutter.com/docs/api.json (harvested 2026-09-12). Operations, schemas and responses are verbatim from the provider's spec. contact: name: Givebutter API Documentation url: https://docs.givebutter.com/api-reference/authentication servers: - url: https://api.givebutter.com/ security: - http: [] tags: - name: Households paths: /v1/households: get: operationId: households.index summary: List all households tags: - Households parameters: - name: headContactId in: query schema: type: - string - 'null' - name: contacts in: query schema: type: - string - 'null' - name: query in: query schema: type: - string - 'null' - name: sortBy in: query schema: type: - string - 'null' - name: sortByDesc in: query schema: type: - string - 'null' - name: page in: query schema: type: string default: 1 responses: '200': description: Array of `HouseholdResource` content: application/json: schema: type: array items: $ref: '#/components/schemas/HouseholdResource' '422': $ref: '#/components/responses/ValidationException' post: operationId: households.store summary: Create a household tags: - Households requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/HouseholdStoreRequest' responses: '200': description: '`App.Http.Resources.API.HouseholdResource`' content: application/json: schema: $ref: '#/components/schemas/App.Http.Resources.API.HouseholdResource' '403': $ref: '#/components/responses/AuthorizationException' '422': $ref: '#/components/responses/ValidationException' /v1/households/{household}: get: operationId: households.show summary: Get a household tags: - Households parameters: - name: household in: path required: true description: The household ID schema: type: integer responses: '200': description: '`App.Http.Resources.API.HouseholdResource`' content: application/json: schema: $ref: '#/components/schemas/App.Http.Resources.API.HouseholdResource' '403': $ref: '#/components/responses/AuthorizationException' '404': $ref: '#/components/responses/ModelNotFoundException' put: operationId: households.update summary: Update a household tags: - Households parameters: - name: household in: path required: true description: The household ID schema: type: integer requestBody: content: application/json: schema: $ref: '#/components/schemas/HouseholdUpdateRequest' responses: '200': description: '`App.Http.Resources.API.HouseholdResource`' content: application/json: schema: $ref: '#/components/schemas/App.Http.Resources.API.HouseholdResource' '403': $ref: '#/components/responses/AuthorizationException' '404': $ref: '#/components/responses/ModelNotFoundException' '422': $ref: '#/components/responses/ValidationException' delete: operationId: households.destroy summary: Delete a household tags: - Households parameters: - name: household in: path required: true description: The household ID schema: type: integer responses: '204': description: No content '404': $ref: '#/components/responses/ModelNotFoundException' components: schemas: App.Http.Resources.API.HouseholdResource: type: object properties: id: type: integer name: type: string head_contact_id: type: - integer - 'null' account_id: type: integer envelope_name: type: - string - 'null' note: type: - string - 'null' created_at: type: string updated_at: type: string contacts: type: array items: $ref: '#/components/schemas/ContactResource' required: - id - name - head_contact_id - account_id - envelope_name - note - created_at - updated_at title: App.Http.Resources.API.HouseholdResource HouseholdResource: type: object properties: id: type: integer name: type: string head_contact_id: type: - integer - 'null' account_id: type: integer envelope_name: type: - string - 'null' note: type: - string - 'null' created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time contacts: type: array items: type: object properties: id: type: string account_id: type: string company_name: type: string first_name: type: string first_name_display: type: string last_name: type: string last_name_display: type: string middle_name: type: string name_display: type: string pronouns: type: string primary_email: type: string primary_phone: type: string type: type: string required: - id - account_id - company_name - first_name - first_name_display - last_name - last_name_display - middle_name - name_display - pronouns - primary_email - primary_phone - type required: - id - name - head_contact_id - account_id - envelope_name - note - created_at - updated_at title: HouseholdResource AssociatedCompanyResource: type: object properties: id: type: string type: type: string company_name: type: string name_display: type: string title: type: string twitter_url: type: string linkedin_url: type: string facebook_url: type: string tiktok_url: type: string instagram_url: type: string website_url: type: string image_url: type: - string - 'null' emails: type: object additionalProperties: {} phones: type: object additionalProperties: {} primary_email: type: string primary_phone: type: string is_email_subscribed: type: string is_phone_subscribed: type: string is_address_subscribed: type: string address_unsubscribed_at: type: string note: type: string addresses: type: array items: $ref: '#/components/schemas/AddressResource' primary_address: $ref: '#/components/schemas/AddressResource' archived_at: type: string created_at: type: string updated_at: type: string first_time_supporter_at: type: string required: - id - type - company_name - name_display - title - twitter_url - linkedin_url - facebook_url - tiktok_url - instagram_url - website_url - image_url - emails - phones - primary_email - primary_phone - is_email_subscribed - is_phone_subscribed - is_address_subscribed - address_unsubscribed_at - note - addresses - primary_address - archived_at - created_at - updated_at - first_time_supporter_at title: AssociatedCompanyResource PointOfContactResource: type: object properties: id: type: string type: type: string prefix: type: string first_name: type: string middle_name: type: string last_name: type: string suffix: type: string gender: type: string pronouns: type: string dob: type: string employer: type: string title: type: string twitter_url: type: string linkedin_url: type: string facebook_url: type: string tiktok_url: type: string instagram_url: type: string website_url: type: string emails: type: object additionalProperties: {} phones: type: object additionalProperties: {} primary_email: type: string primary_phone: type: string is_email_subscribed: type: string is_phone_subscribed: type: string is_address_subscribed: type: string address_unsubscribed_at: type: string archived_at: type: string created_at: type: string updated_at: type: string first_time_supporter_at: type: string required: - id - type - prefix - first_name - middle_name - last_name - suffix - gender - pronouns - dob - employer - title - twitter_url - linkedin_url - facebook_url - tiktok_url - instagram_url - website_url - emails - phones - primary_email - primary_phone - is_email_subscribed - is_phone_subscribed - is_address_subscribed - address_unsubscribed_at - archived_at - created_at - updated_at - first_time_supporter_at title: PointOfContactResource App.Http.Resources.API.AddressResource: type: object properties: address_1: type: string address_2: type: - string - 'null' city: type: string state: type: - string - 'null' zipcode: type: - string - 'null' country: type: string type: type: string is_primary: type: boolean created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time required: - address_1 - address_2 - city - state - zipcode - country - type - is_primary - created_at - updated_at title: App.Http.Resources.API.AddressResource ExternalIdResource: type: object properties: id: type: integer label: type: string external_id: type: string created_at: type: string updated_at: type: string required: - id - label - external_id - created_at - updated_at title: ExternalIdResource HouseholdStoreRequest: type: object properties: name: type: string maxLength: 255 head_contact_id: type: - integer - 'null' note: type: - string - 'null' envelope_name: type: - string - 'null' maxLength: 255 required: - name title: HouseholdStoreRequest AddressResource: type: object properties: id: type: integer account_id: type: - integer - 'null' name: type: - string - 'null' address_1: type: string address_2: type: - string - 'null' city: type: string state: type: - string - 'null' zipcode: type: - string - 'null' country: type: string type: type: string is_primary: type: boolean created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time required: - id - account_id - name - address_1 - address_2 - city - state - zipcode - country - type - is_primary - created_at - updated_at title: AddressResource PhoneResource: type: object properties: type: type: - string - 'null' value: type: - string - 'null' required: - type - value title: PhoneResource EmailResource: type: object properties: type: type: - string - 'null' value: type: - string - 'null' required: - type - value title: EmailResource HouseholdUpdateRequest: type: object properties: name: type: string maxLength: 255 head_contact_id: type: - integer - 'null' note: type: - string - 'null' envelope_name: type: - string - 'null' maxLength: 255 title: HouseholdUpdateRequest ContactResource: type: object properties: id: type: string external_id: type: string contact_since: type: string type: type: string prefix: type: string first_name: type: string preferred_name: type: string middle_name: type: string last_name: type: string suffix: type: string gender: type: string pronouns: type: string dob: type: string company: type: string employer: type: string company_name: type: string point_of_contact: anyOf: - $ref: '#/components/schemas/PointOfContactResource' - type: 'null' associated_companies: type: - array - 'null' items: $ref: '#/components/schemas/AssociatedCompanyResource' title: type: string website_url: type: string twitter_url: type: string linkedin_url: type: string facebook_url: type: string tiktok_url: type: string instagram_url: type: string emails: type: array items: $ref: '#/components/schemas/EmailResource' phones: type: array items: $ref: '#/components/schemas/PhoneResource' primary_email: type: string primary_phone: type: string note: type: string addresses: type: array items: $ref: '#/components/schemas/App.Http.Resources.API.AddressResource' primary_address: anyOf: - $ref: '#/components/schemas/App.Http.Resources.API.AddressResource' - type: 'null' last_donation_amount: type: string stats: type: object properties: total_contributions: type: string recurring_contributions: type: string required: - total_contributions - recurring_contributions tags: type: string custom_fields: type: array items: {} external_ids: type: array items: $ref: '#/components/schemas/ExternalIdResource' is_email_subscribed: type: string is_phone_subscribed: type: string is_address_subscribed: type: string email_opt_in: type: string sms_opt_in: type: string address_unsubscribed_at: type: string archived_at: type: string created_at: type: string updated_at: type: string salutation_name: type: string required: - id - external_id - contact_since - type - prefix - first_name - preferred_name - middle_name - last_name - suffix - gender - pronouns - dob - company - employer - company_name - title - website_url - twitter_url - linkedin_url - facebook_url - tiktok_url - instagram_url - emails - phones - primary_email - primary_phone - note - addresses - primary_address - last_donation_amount - stats - tags - custom_fields - external_ids - is_email_subscribed - is_phone_subscribed - is_address_subscribed - email_opt_in - sms_opt_in - address_unsubscribed_at - archived_at - created_at - updated_at - salutation_name title: ContactResource responses: AuthorizationException: description: Authorization error content: application/json: schema: type: object properties: message: type: string description: Error overview. required: - message ValidationException: description: Validation error content: application/json: schema: type: object properties: message: type: string description: Errors overview. errors: type: object description: A detailed description of each field that failed validation. additionalProperties: type: array items: type: string required: - message - errors ModelNotFoundException: description: Not found content: application/json: schema: type: object properties: message: type: string description: Error overview. required: - message securitySchemes: http: type: http scheme: bearer x-source: https://givebutter.com/docs/api.json x-harvested: '2026-09-12'