Skip to main content
GET
/
households
Retrieve a list of households
curl --request GET \
  --url https://api.givebutter.com/v1/households \
  --header 'Authorization: Bearer <token>'
[
  {
    "id": 123,
    "name": "<string>",
    "head_contact_id": 123,
    "account_id": 123,
    "envelope_name": "<string>",
    "note": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "contacts": [
      {
        "id": 123,
        "type": "individual",
        "first_name": "<string>",
        "middle_name": "<string>",
        "last_name": "<string>",
        "preferred_name": "<string>",
        "gender": "<string>",
        "pronouns": "<string>",
        "dob": "2023-11-07T05:31:56Z",
        "company": "<string>",
        "employer": "<string>",
        "company_name": "<string>",
        "company_point_of_contact_id": 123,
        "title": "<string>",
        "twitter_url": "<string>",
        "linkedin_url": "<string>",
        "tiktok_url": "<string>",
        "facebook_url": "<string>",
        "primary_email_id": 123,
        "emails": [
          "<unknown>"
        ],
        "primary_email": "<string>",
        "email_deliverability_last_scanned_at": "2023-11-07T05:31:56Z",
        "primary_phone_id": 123,
        "phones": [
          "<unknown>"
        ],
        "primary_phone": "<string>",
        "phone_deliverability_last_scanned_at": "2023-11-07T05:31:56Z",
        "is_email_subscribed": true,
        "is_phone_subscribed": true,
        "note": "<string>",
        "bio": "<string>",
        "total_contributions": 123,
        "recurring_contributions": 123,
        "account_id": 123,
        "import_id": 123,
        "external_id": "<string>",
        "merged_into_id": 123,
        "last_scanned_at": "<string>",
        "suspected_duplicate_id": 123,
        "suspected_duplicate_at": "<string>",
        "archived_at": "2023-11-07T05:31:56Z",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "deleted_at": "2023-11-07T05:31:56Z",
        "website_url": "<string>",
        "prefix": "<string>",
        "suffix": "<string>",
        "first_time_supporter_at": "2023-11-07T05:31:56Z",
        "new_first_time_supporter_at": "<string>",
        "first_donation_id": 123,
        "new_first_donation_id": 123,
        "new_first_donation_at": "2023-11-07T05:31:56Z",
        "last_donation_id": 123,
        "household_id": 123,
        "is_address_subscribed": true,
        "address_unsubscribed_at": "2023-11-07T05:31:56Z",
        "created_by": 123,
        "last_enriched_at": "2023-11-07T05:31:56Z"
      }
    ]
  }
]

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
page
string
default:1

Response

Array of HouseholdResource

​
id
integer
required
​
name
string
required
​
head_contact_id
integer | null
required
​
account_id
integer
required
​
envelope_name
string | null
required
​
note
string | null
required
​
created_at
string<date-time> | null
required
​
updated_at
string<date-time> | null
required
​
contacts
Contact · object[]