Skip to main content
POST
/
households
Create a new household
curl --request POST \
  --url https://api.givebutter.com/v1/households \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "head_contact_id": 123,
  "note": "<string>",
  "envelope_name": "<string>"
}
'
{
  "id": 123,
  "name": "<string>",
  "head_contact_id": 123,
  "account_id": 123,
  "envelope_name": "<string>",
  "note": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "contacts": [
    {
      "id": "<string>",
      "external_id": "<string>",
      "type": "<string>",
      "prefix": "<string>",
      "first_name": "<string>",
      "middle_name": "<string>",
      "last_name": "<string>",
      "suffix": "<string>",
      "gender": "<string>",
      "pronouns": "<string>",
      "dob": "<string>",
      "company": "<string>",
      "employer": "<string>",
      "company_name": "<string>",
      "title": "<string>",
      "website_url": "<string>",
      "twitter_url": "<string>",
      "linkedin_url": "<string>",
      "facebook_url": "<string>",
      "tiktok_url": "<string>",
      "emails": [
        {
          "type": "<string>",
          "value": "<string>"
        }
      ],
      "phones": [
        {
          "type": "<string>",
          "value": "<string>"
        }
      ],
      "primary_email": "<string>",
      "primary_phone": "<string>",
      "note": "<string>",
      "addresses": [
        {
          "address_1": "<string>",
          "address_2": "<string>",
          "city": "<string>",
          "state": "<string>",
          "zipcode": "<string>",
          "country": "<string>",
          "type": "<string>",
          "is_primary": true,
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z"
        }
      ],
      "primary_address": {
        "address_1": "<string>",
        "address_2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "zipcode": "<string>",
        "country": "<string>",
        "type": "<string>",
        "is_primary": true,
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      },
      "stats": {
        "total_contributions": "<string>",
        "recurring_contributions": "<string>"
      },
      "tags": "<string>",
      "custom_fields": [
        "<unknown>"
      ],
      "external_ids": [
        {
          "id": 123,
          "label": "<string>",
          "external_id": "<string>",
          "created_at": "<string>",
          "updated_at": "<string>"
        }
      ],
      "is_email_subscribed": "<string>",
      "is_phone_subscribed": "<string>",
      "is_address_subscribed": "<string>",
      "email_opt_in": "<string>",
      "sms_opt_in": "<string>",
      "address_unsubscribed_at": "<string>",
      "archived_at": "<string>",
      "created_at": "<string>",
      "updated_at": "<string>",
      "preferred_name": "<string>",
      "salutation_name": "<string>",
      "point_of_contact": {
        "id": "<string>",
        "type": "<string>",
        "prefix": "<string>",
        "first_name": "<string>",
        "middle_name": "<string>",
        "last_name": "<string>",
        "suffix": "<string>",
        "gender": "<string>",
        "pronouns": "<string>",
        "dob": "<string>",
        "employer": "<string>",
        "title": "<string>",
        "twitter_url": "<string>",
        "linkedin_url": "<string>",
        "facebook_url": "<string>",
        "tiktok_url": "<string>",
        "website_url": "<string>",
        "emails": {},
        "phones": {},
        "primary_email": "<string>",
        "primary_phone": "<string>",
        "is_email_subscribed": "<string>",
        "is_phone_subscribed": "<string>",
        "is_address_subscribed": "<string>",
        "address_unsubscribed_at": "<string>",
        "archived_at": "<string>",
        "created_at": "<string>",
        "updated_at": "<string>",
        "first_time_supporter_at": "<string>"
      },
      "associated_companies": [
        {
          "id": "<string>",
          "type": "<string>",
          "company_name": "<string>",
          "title": "<string>",
          "twitter_url": "<string>",
          "linkedin_url": "<string>",
          "facebook_url": "<string>",
          "tiktok_url": "<string>",
          "website_url": "<string>",
          "emails": {},
          "phones": {},
          "primary_email": "<string>",
          "primary_phone": "<string>",
          "is_email_subscribed": "<string>",
          "is_phone_subscribed": "<string>",
          "is_address_subscribed": "<string>",
          "address_unsubscribed_at": "<string>",
          "note": "<string>",
          "addresses": [
            {
              "id": 123,
              "account_id": 123,
              "name": "<string>",
              "address_1": "<string>",
              "address_2": "<string>",
              "city": "<string>",
              "state": "<string>",
              "zipcode": "<string>",
              "country": "<string>",
              "type": "<string>",
              "is_primary": true,
              "created_at": "2023-11-07T05:31:56Z",
              "updated_at": "2023-11-07T05:31:56Z"
            }
          ],
          "primary_address": {
            "id": 123,
            "account_id": 123,
            "name": "<string>",
            "address_1": "<string>",
            "address_2": "<string>",
            "city": "<string>",
            "state": "<string>",
            "zipcode": "<string>",
            "country": "<string>",
            "type": "<string>",
            "is_primary": true,
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z"
          },
          "archived_at": "<string>",
          "created_at": "<string>",
          "updated_at": "<string>",
          "first_time_supporter_at": "<string>"
        }
      ]
    }
  ]
}

Authorizations

Authorization
string
header
required

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

Body

application/json
name
string
required
Maximum string length: 255
head_contact_id
integer | null
note
string | null
envelope_name
string | null
Maximum string length: 255

Response

App.Http.Resources.API.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
required
updated_at
string
required
contacts
ContactResource · object[]