Household APIs

Identity Management APIs

Retrieve linked households for the authenticated user

get

This endpoint retrieves all households associated with the authenticated user, including those that have expired. It provides visibility into the user's household affiliations, allowing for better management of their digital profile.

👤 User Credential: You must login and authenticate a user and use their access token to invoke this service. This will operate the action under the specified user.

Authorizations

authorizationCode

OAuth2clientCredentialsRequired

An OIDC service account that was authenticated.

Authorization URL: Token URL:

Responses

200

OK

*/*

401

Unauthorized

*/*

get

/identities/me/households

HTTPcURLJavaScriptPython

GET /identities/me/households HTTP/1.1
Host: gateway.dev.klustr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "count": 1,
  "limit": 1,
  "skip": 1,
  "docs": [
    {
      "id": "text",
      "name": "text",
      "contact": {
        "phones": [
          {
            "phone": "text",
            "country_code": "text",
            "phone_type": "MOBILE"
          }
        ],
        "addresses": {
          "address_line_1": "text",
          "address_line_2": "text",
          "postal_code": "text",
          "city_ward": "text",
          "floor": "text",
          "usage": "residence",
          "building_name": "text",
          "state_prefecture": "text",
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "country_code": "US"
        },
        "email": "text"
      },
      "members": [
        {
          "person_id": "text",
          "primary": true,
          "create_date": "2026-02-13T01:34:01.860Z",
          "start_date": "2026-02-13T01:34:01.860Z",
          "expiration_date": "2026-02-13T01:34:01.860Z",
          "status": "active"
        }
      ],
      "creation_date": "2026-02-13T01:34:01.860Z",
      "modified_date": "2026-02-13T01:34:01.860Z"
    }
  ]
}

Create a household for the authenticated user.

post

This endpoint allows the current user to create a household. The household serves as a customizable digital profile that reflects the user's online presence. It is essential for managing identity and visibility within the platform.

👤 User Credential: You must login and authenticate a user and use their access token to invoke this service. This will operate the action under the specified user.

Authorizations

authorizationCode

OAuth2clientCredentialsRequired

An OIDC service account that was authenticated.

Authorization URL: Token URL:

Body

application/json

namestringOptional

Responses

200

OK

*/*

401

Unauthorized

*/*

post

/identities/me/households

HTTPcURLJavaScriptPython

POST /identities/me/households HTTP/1.1
Host: gateway.dev.klustr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "name": "text"
}

{
  "id": "text",
  "name": "text",
  "contact": {
    "phones": [
      {
        "phone": "text",
        "country_code": "text",
        "phone_type": "MOBILE"
      }
    ],
    "addresses": {
      "address_line_1": "text",
      "address_line_2": "text",
      "postal_code": "text",
      "city_ward": "text",
      "floor": "text",
      "usage": "residence",
      "building_name": "text",
      "state_prefecture": "text",
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "country_code": "US"
    },
    "email": "text"
  },
  "members": [
    {
      "person_id": "text",
      "primary": true,
      "create_date": "2026-02-13T01:34:01.860Z",
      "start_date": "2026-02-13T01:34:01.860Z",
      "expiration_date": "2026-02-13T01:34:01.860Z",
      "status": "active"
    }
  ],
  "creation_date": "2026-02-13T01:34:01.860Z",
  "modified_date": "2026-02-13T01:34:01.860Z"
}

Retrieve my linked households including expired ones.

get

This endpoint allows users to fetch their associated households, including those that may have expired. It provides visibility into all households linked to the user's profile, ensuring users can manage their household information effectively.

👤 User Credential: You must login and authenticate a user and use their access token to invoke this service. This will operate the action under the specified user.

Authorizations

authorizationCode

OAuth2clientCredentialsRequired

An OIDC service account that was authenticated.

Authorization URL: Token URL:

Path parameters

householdIdstringRequired

Responses

200

OK

*/*

401

Unauthorized

*/*

get

/identities/me/households/{householdId}

HTTPcURLJavaScriptPython

GET /identities/me/households/{householdId} HTTP/1.1
Host: gateway.dev.klustr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "id": "text",
  "name": "text",
  "contact": {
    "phones": [
      {
        "phone": "text",
        "country_code": "text",
        "phone_type": "MOBILE"
      }
    ],
    "addresses": {
      "address_line_1": "text",
      "address_line_2": "text",
      "postal_code": "text",
      "city_ward": "text",
      "floor": "text",
      "usage": "residence",
      "building_name": "text",
      "state_prefecture": "text",
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "country_code": "US"
    },
    "email": "text"
  },
  "members": [
    {
      "person_id": "text",
      "primary": true,
      "create_date": "2026-02-13T01:34:01.860Z",
      "start_date": "2026-02-13T01:34:01.860Z",
      "expiration_date": "2026-02-13T01:34:01.860Z",
      "status": "active"
    }
  ],
  "creation_date": "2026-02-13T01:34:01.860Z",
  "modified_date": "2026-02-13T01:34:01.860Z"
}

Retrieve actions for household owner

get

This endpoint retrieves and returns any actions that the household owner needs to take. It is designed to provide visibility into necessary tasks for managing household responsibilities effectively.

👤 User Credential: You must login and authenticate a user and use their access token to invoke this service. This will operate the action under the specified user.

Authorizations

authorizationCode

OAuth2clientCredentialsRequired

An OIDC service account that was authenticated.

Authorization URL: Token URL:

Path parameters

householdIdstringRequired

Responses

200

OK

*/*

401

Unauthorized

*/*

get

/identities/me/households/{householdId}/actions

HTTPcURLJavaScriptPython

GET /identities/me/households/{householdId}/actions HTTP/1.1
Host: gateway.dev.klustr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "id": "text",
    "type": "text",
    "timestamp": "2026-02-13T01:34:01.860Z",
    "person": {
      "given_name": "text",
      "family_name": "text",
      "photo": "text",
      "id": "text"
    },
    "payload": {}
  }
]

List people in your household

get

Retrieves detailed information about individuals within your household. This endpoint provides visibility into the members associated with your household, ensuring you have access to their profiles. It is intended for personal use, allowing you to manage and view relationships within your household.

👤 User Credential: You must login and authenticate a user and use their access token to invoke this service. This will operate the action under the specified user.

Authorizations

authorizationCode

OAuth2clientCredentialsRequired

An OIDC service account that was authenticated.

Authorization URL: Token URL:

Path parameters

householdIdstringRequired

Responses

200

OK

*/*

401

Unauthorized

*/*

get

/identities/me/households/{householdId}/members

HTTPcURLJavaScriptPython

GET /identities/me/households/{householdId}/members HTTP/1.1
Host: gateway.dev.klustr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "person": {
      "id": "text",
      "namespace": "text",
      "deleted": true,
      "verification": {
        "status": "started",
        "reason": "text",
        "timestamp": "2026-02-13T01:34:01.860Z"
      },
      "name": [
        {
          "given_name": "text",
          "family_name": "text",
          "middle_name": "text",
          "source": "user",
          "locale": "text"
        }
      ],
      "citizenship": [
        {
          "citizenship_country_code": "text",
          "residency_country_code": "text",
          "residency_type": "PERMANENT_VISA",
          "residency_expiration": "2026-02-13T01:34:01.860Z"
        }
      ],
      "contact": {
        "phones": [
          {
            "phone": "text",
            "country_code": "text",
            "phone_type": "MOBILE"
          }
        ],
        "addresses": {
          "address_line_1": "text",
          "address_line_2": "text",
          "postal_code": "text",
          "city_ward": "text",
          "floor": "text",
          "usage": "residence",
          "building_name": "text",
          "state_prefecture": "text",
          "metadata": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "country_code": "US"
        },
        "email": "text"
      },
      "ids": [
        {
          "external_id": "text",
          "source": "text",
          "creation_date": "2026-02-13T01:34:01.860Z",
          "expiration_date": "2026-02-13T01:34:01.860Z",
          "update_date": "2026-02-13T01:34:01.860Z"
        }
      ],
      "documents": [
        {
          "type": "VISA",
          "country_code": "text",
          "link": "https://example.com",
          "date_effective": "2026-02-13T01:34:01.860Z",
          "date_expires": "2026-02-13T01:34:01.860Z",
          "date_created": "2026-02-13T01:34:01.860Z",
          "vendor_reference_data": "text",
          "vendor": "text"
        }
      ],
      "credentials": {
        "oidc": {
          "type": "text",
          "identifiers": [
            "text"
          ]
        },
        "password": {
          "type": "text",
          "config": {
            "password": "text"
          }
        }
      },
      "creation_date": "2026-02-13T01:34:01.860Z",
      "status": {
        "supervised_status": {
          "avatar": "deny",
          "third_party_consent": "deny_all"
        },
        "relationship_status": "single",
        "parental_status": "parent"
      },
      "traits": {
        "name": {
          "given_name": "text",
          "family_name": "text",
          "middle_name": "text"
        },
        "birthdate": "2026-02-13",
        "email": "text",
        "username": "text",
        "gender": "male",
        "citizenship": "text",
        "locale": "text"
      },
      "metadata_public": {
        "picture": "text"
      }
    },
    "member": {
      "person_id": "text",
      "primary": true,
      "create_date": "2026-02-13T01:34:01.860Z",
      "start_date": "2026-02-13T01:34:01.860Z",
      "expiration_date": "2026-02-13T01:34:01.860Z",
      "status": "active"
    }
  }
]

Add a member to your household

post

This endpoint allows a user to register a new member under their specified household. The operation ensures that the new member's account is linked appropriately, enhancing the household's digital profile. This action is intended for personal use and contributes to the management of household identities.

👤 User Credential: You must login and authenticate a user and use their access token to invoke this service. This will operate the action under the specified user.

Authorizations

authorizationCode

OAuth2clientCredentialsRequired

An OIDC service account that was authenticated.

Authorization URL: Token URL:

Path parameters

householdIdstringRequired

Body

application/json

given_namestringOptional

family_namestringOptional

date_of_birthstringOptional

genderstringOptional

usernamestringOptional

passwordstringOptional

Responses

200

OK

*/*

401

Unauthorized

*/*

post

/identities/me/households/{householdId}/members

HTTPcURLJavaScriptPython

POST /identities/me/households/{householdId}/members HTTP/1.1
Host: gateway.dev.klustr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 117

{
  "given_name": "text",
  "family_name": "text",
  "date_of_birth": "text",
  "gender": "text",
  "username": "text",
  "password": "text"
}

{
  "data": {
    "person_id": "text",
    "primary": true,
    "create_date": "2026-02-13T01:34:01.860Z",
    "start_date": "2026-02-13T01:34:01.860Z",
    "expiration_date": "2026-02-13T01:34:01.860Z",
    "status": "active"
  },
  "errors": [
    "text"
  ]
}

Retrieve details for a specific household member

get

This endpoint allows you to obtain the details of a person within a specified household. It is intended for users to access their own household member information securely. The data retrieved is part of the user's digital profile and is customizable based on their preferences.

👤 User Credential: You must login and authenticate a user and use their access token to invoke this service. This will operate the action under the specified user.

Authorizations

authorizationCode

OAuth2clientCredentialsRequired

An OIDC service account that was authenticated.

Authorization URL: Token URL:

Path parameters

householdIdstringRequired

personIdstringRequired

Responses

200

OK

*/*

401

Unauthorized

*/*

get

/identities/me/households/{householdId}/members/{personId}

HTTPcURLJavaScriptPython

GET /identities/me/households/{householdId}/members/{personId} HTTP/1.1
Host: gateway.dev.klustr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "person": {
    "id": "text",
    "namespace": "text",
    "deleted": true,
    "verification": {
      "status": "started",
      "reason": "text",
      "timestamp": "2026-02-13T01:34:01.860Z"
    },
    "name": [
      {
        "given_name": "text",
        "family_name": "text",
        "middle_name": "text",
        "source": "user",
        "locale": "text"
      }
    ],
    "citizenship": [
      {
        "citizenship_country_code": "text",
        "residency_country_code": "text",
        "residency_type": "PERMANENT_VISA",
        "residency_expiration": "2026-02-13T01:34:01.860Z"
      }
    ],
    "contact": {
      "phones": [
        {
          "phone": "text",
          "country_code": "text",
          "phone_type": "MOBILE"
        }
      ],
      "addresses": {
        "address_line_1": "text",
        "address_line_2": "text",
        "postal_code": "text",
        "city_ward": "text",
        "floor": "text",
        "usage": "residence",
        "building_name": "text",
        "state_prefecture": "text",
        "metadata": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "country_code": "US"
      },
      "email": "text"
    },
    "ids": [
      {
        "external_id": "text",
        "source": "text",
        "creation_date": "2026-02-13T01:34:01.860Z",
        "expiration_date": "2026-02-13T01:34:01.860Z",
        "update_date": "2026-02-13T01:34:01.860Z"
      }
    ],
    "documents": [
      {
        "type": "VISA",
        "country_code": "text",
        "link": "https://example.com",
        "date_effective": "2026-02-13T01:34:01.860Z",
        "date_expires": "2026-02-13T01:34:01.860Z",
        "date_created": "2026-02-13T01:34:01.860Z",
        "vendor_reference_data": "text",
        "vendor": "text"
      }
    ],
    "credentials": {
      "oidc": {
        "type": "text",
        "identifiers": [
          "text"
        ]
      },
      "password": {
        "type": "text",
        "config": {
          "password": "text"
        }
      }
    },
    "creation_date": "2026-02-13T01:34:01.860Z",
    "status": {
      "supervised_status": {
        "avatar": "deny",
        "third_party_consent": "deny_all"
      },
      "relationship_status": "single",
      "parental_status": "parent"
    },
    "traits": {
      "name": {
        "given_name": "text",
        "family_name": "text",
        "middle_name": "text"
      },
      "birthdate": "2026-02-13",
      "email": "text",
      "username": "text",
      "gender": "male",
      "citizenship": "text",
      "locale": "text"
    },
    "metadata_public": {
      "picture": "text"
    }
  },
  "member": {
    "person_id": "text",
    "primary": true,
    "create_date": "2026-02-13T01:34:01.860Z",
    "start_date": "2026-02-13T01:34:01.860Z",
    "expiration_date": "2026-02-13T01:34:01.860Z",
    "status": "active"
  }
}

Add a member to your household

put

This endpoint allows the primary contact of a household to add a member. The caller must be authenticated and authorized as the primary contact. This operation updates the household's member list, ensuring that only authorized users can make changes.

👤 User Credential: You must login and authenticate a user and use their access token to invoke this service. This will operate the action under the specified user.

Authorizations

authorizationCode

OAuth2clientCredentialsRequired

An OIDC service account that was authenticated.

Authorization URL: Token URL:

Path parameters

householdIdstringRequired

personIdstringRequired

Responses

200

OK

*/*

401

Unauthorized

*/*

put

/identities/me/households/{householdId}/members/{personId}

HTTPcURLJavaScriptPython

PUT /identities/me/households/{householdId}/members/{personId} HTTP/1.1
Host: gateway.dev.klustr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "id": "text",
  "name": "text",
  "contact": {
    "phones": [
      {
        "phone": "text",
        "country_code": "text",
        "phone_type": "MOBILE"
      }
    ],
    "addresses": {
      "address_line_1": "text",
      "address_line_2": "text",
      "postal_code": "text",
      "city_ward": "text",
      "floor": "text",
      "usage": "residence",
      "building_name": "text",
      "state_prefecture": "text",
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "country_code": "US"
    },
    "email": "text"
  },
  "members": [
    {
      "person_id": "text",
      "primary": true,
      "create_date": "2026-02-13T01:34:01.860Z",
      "start_date": "2026-02-13T01:34:01.860Z",
      "expiration_date": "2026-02-13T01:34:01.860Z",
      "status": "active"
    }
  ],
  "creation_date": "2026-02-13T01:34:01.860Z",
  "modified_date": "2026-02-13T01:34:01.860Z"
}

Remove a member from your household.

delete

This endpoint allows you to remove a specified person from your household. The action affects the visibility of the person's association with the household, ensuring that your household's composition is accurately reflected. This operation is intended for personal use and requires appropriate authentication.

👤 User Credential: You must login and authenticate a user and use their access token to invoke this service. This will operate the action under the specified user.

Authorizations

authorizationCode

OAuth2clientCredentialsRequired

An OIDC service account that was authenticated.

Authorization URL: Token URL:

Path parameters

householdIdstringRequired

personIdstringRequired

Responses

200

OK

*/*

401

Unauthorized

*/*

delete

/identities/me/households/{householdId}/members/{personId}

HTTPcURLJavaScriptPython

DELETE /identities/me/households/{householdId}/members/{personId} HTTP/1.1
Host: gateway.dev.klustr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "id": "text",
  "name": "text",
  "contact": {
    "phones": [
      {
        "phone": "text",
        "country_code": "text",
        "phone_type": "MOBILE"
      }
    ],
    "addresses": {
      "address_line_1": "text",
      "address_line_2": "text",
      "postal_code": "text",
      "city_ward": "text",
      "floor": "text",
      "usage": "residence",
      "building_name": "text",
      "state_prefecture": "text",
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "country_code": "US"
    },
    "email": "text"
  },
  "members": [
    {
      "person_id": "text",
      "primary": true,
      "create_date": "2026-02-13T01:34:01.860Z",
      "start_date": "2026-02-13T01:34:01.860Z",
      "expiration_date": "2026-02-13T01:34:01.860Z",
      "status": "active"
    }
  ],
  "creation_date": "2026-02-13T01:34:01.860Z",
  "modified_date": "2026-02-13T01:34:01.860Z"
}

Invite a member to your household

patch

Sends an invitation to the specified user to join your household. The user will receive the invitation upon their next login or through other activation channels. This operation facilitates user engagement and enhances household connectivity.

👤 User Credential: You must login and authenticate a user and use their access token to invoke this service. This will operate the action under the specified user.

Authorizations

authorizationCode

OAuth2clientCredentialsRequired

An OIDC service account that was authenticated.

Authorization URL: Token URL:

Path parameters

householdIdstringRequired

personIdstringRequired

Responses

200

OK

*/*

401

Unauthorized

*/*

patch

/identities/me/households/{householdId}/members/{personId}

HTTPcURLJavaScriptPython

PATCH /identities/me/households/{householdId}/members/{personId} HTTP/1.1
Host: gateway.dev.klustr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "id": "text",
  "name": "text",
  "contact": {
    "phones": [
      {
        "phone": "text",
        "country_code": "text",
        "phone_type": "MOBILE"
      }
    ],
    "addresses": {
      "address_line_1": "text",
      "address_line_2": "text",
      "postal_code": "text",
      "city_ward": "text",
      "floor": "text",
      "usage": "residence",
      "building_name": "text",
      "state_prefecture": "text",
      "metadata": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "country_code": "US"
    },
    "email": "text"
  },
  "members": [
    {
      "person_id": "text",
      "primary": true,
      "create_date": "2026-02-13T01:34:01.860Z",
      "start_date": "2026-02-13T01:34:01.860Z",
      "expiration_date": "2026-02-13T01:34:01.860Z",
      "status": "active"
    }
  ],
  "creation_date": "2026-02-13T01:34:01.860Z",
  "modified_date": "2026-02-13T01:34:01.860Z"
}

Update avatar for household member.

post

This endpoint allows the user to update the avatar of a specified member within their household. The calling user must be the owner of the household to perform this action. Ensure that the provided householdId and personId correspond to the intended member. This operation enhances the digital profile visibility of the user.

👤 User Credential: You must login and authenticate a user and use their access token to invoke this service. This will operate the action under the specified user.

Authorizations

authorizationCode

OAuth2clientCredentialsRequired

An OIDC service account that was authenticated.

Authorization URL: Token URL:

Path parameters

householdIdstringRequired

personIdstringRequired

Body

application/json

uristringOptional

Responses

200

OK

No content

401

Unauthorized

*/*

post

/identities/me/households/{householdId}/members/{personId}/avatar

HTTPcURLJavaScriptPython

POST /identities/me/households/{householdId}/members/{personId}/avatar HTTP/1.1
Host: gateway.dev.klustr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 14

{
  "uri": "text"
}

No content

Update profile for a household member

post

This endpoint allows the owner of a household to update the profile information of a specified member. The calling user must have ownership of the household to perform this action. Ensure that the provided information reflects the member's digital profile accurately.

👤 User Credential: You must login and authenticate a user and use their access token to invoke this service. This will operate the action under the specified user.

Authorizations

authorizationCode

OAuth2clientCredentialsRequired

An OIDC service account that was authenticated.

Authorization URL: Token URL:

Path parameters

householdIdstringRequired

personIdstringRequired

Body

application/json

given_namestringOptional

family_namestringOptional

date_of_birthstringOptional

genderstringOptional

Responses

200

OK

No content

401

Unauthorized

*/*

post

/identities/me/households/{householdId}/members/{personId}/profile

HTTPcURLJavaScriptPython

POST /identities/me/households/{householdId}/members/{personId}/profile HTTP/1.1
Host: gateway.dev.klustr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 81

{
  "given_name": "text",
  "family_name": "text",
  "date_of_birth": "text",
  "gender": "text"
}

No content

Update third party app consent for a household member

post

Allows a user to enable or disable consent for third party applications related to their household. This operation is intended for supervised accounts and ensures that users can manage their privacy preferences effectively.

👤 User Credential: You must login and authenticate a user and use their access token to invoke this service. This will operate the action under the specified user.

Authorizations

authorizationCode

OAuth2clientCredentialsRequired

An OIDC service account that was authenticated.

Authorization URL: Token URL:

Path parameters

householdIdstringRequired

personIdstringRequired

Body

application/json

permissionstring · enumOptionalPossible values:

Responses

200

OK

No content

401

Unauthorized

*/*

post

/identities/me/households/{householdId}/members/{personId}/thirdparties

HTTPcURLJavaScriptPython

POST /identities/me/households/{householdId}/members/{personId}/thirdparties HTTP/1.1
Host: gateway.dev.klustr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 25

{
  "permission": "deny_all"
}

No content