Household Admin APIs

Identity Management APIs

List registered households in the system.

get

Retrieves a list of households that are registered in the system. This endpoint is intended for administrative users to manage and view household information. The results can be paginated using the 'limit' and 'start' parameters to control the number of households returned.

💻 Service Credentials is required to access this service.

🔒 Permission: households.list is required in order for the call to succeed. You must configure permissions for the person or service calling this endpoint and add this permission to their identity.

Authorizations

clientCredentials

OAuth2authorizationCodeRequired

An OIDC service account that was authenticated.

Token URL:

Query parameters

limitinteger · int32OptionalDefault: 10

startinteger · int32OptionalDefault: 0

Responses

200

OK

*/*

401

Unauthorized

*/*

get

/identities/admin/households/

HTTPcURLJavaScriptPython

GET /identities/admin/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": "2025-12-16T22:11:23.228Z",
          "start_date": "2025-12-16T22:11:23.228Z",
          "expiration_date": "2025-12-16T22:11:23.228Z",
          "status": "active"
        }
      ],
      "creation_date": "2025-12-16T22:11:23.228Z",
      "modified_date": "2025-12-16T22:11:23.228Z"
    }
  ]
}

Admin creates a new household record.

post

This endpoint allows an admin to create a new household record. The created household will be visible to other users based on their permissions. This operation is essential for managing household identities within the system.

💻 Service Credentials is required to access this service.

🔒 Permission: households.create is required in order for the call to succeed. You must configure permissions for the person or service calling this endpoint and add this permission to their identity.

Authorizations

clientCredentials

OAuth2authorizationCodeRequired

An OIDC service account that was authenticated.

Token URL:

Body

application/json

idstringOptional

namestringOptional

creation_datestring · date-timeOptional

modified_datestring · date-timeOptional

Responses

200

OK

*/*

401

Unauthorized

*/*

post

/identities/admin/households/

HTTPcURLJavaScriptPython

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

{
  "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": "2025-12-16T22:11:23.228Z",
      "start_date": "2025-12-16T22:11:23.228Z",
      "expiration_date": "2025-12-16T22:11:23.228Z",
      "status": "active"
    }
  ],
  "creation_date": "2025-12-16T22:11:23.228Z",
  "modified_date": "2025-12-16T22:11:23.228Z"
}

{
  "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": "2025-12-16T22:11:23.228Z",
      "start_date": "2025-12-16T22:11:23.228Z",
      "expiration_date": "2025-12-16T22:11:23.228Z",
      "status": "active"
    }
  ],
  "creation_date": "2025-12-16T22:11:23.228Z",
  "modified_date": "2025-12-16T22:11:23.228Z"
}

Admin update of a household record

put

Updates the details of a specified household record. This operation is intended for administrative users, allowing them to modify household information for better management and support. Ensure that the provided household data is accurate and complete to maintain data integrity.

💻 Service Credentials is required to access this service.

🔒 Permission: households.update is required in order for the call to succeed. You must configure permissions for the person or service calling this endpoint and add this permission to their identity.

Authorizations

clientCredentials

OAuth2authorizationCodeRequired

An OIDC service account that was authenticated.

Token URL:

Path parameters

householdIdstringRequired

Body

application/json

idstringOptional

namestringOptional

creation_datestring · date-timeOptional

modified_datestring · date-timeOptional

Responses

200

OK

*/*

401

Unauthorized

*/*

put

/identities/admin/households/{householdId}

HTTPcURLJavaScriptPython

PUT /identities/admin/households/{householdId} HTTP/1.1
Host: gateway.dev.klustr.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 656

{
  "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": "2025-12-16T22:11:23.228Z",
      "start_date": "2025-12-16T22:11:23.228Z",
      "expiration_date": "2025-12-16T22:11:23.228Z",
      "status": "active"
    }
  ],
  "creation_date": "2025-12-16T22:11:23.228Z",
  "modified_date": "2025-12-16T22:11:23.228Z"
}

{
  "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": "2025-12-16T22:11:23.228Z",
      "start_date": "2025-12-16T22:11:23.228Z",
      "expiration_date": "2025-12-16T22:11:23.228Z",
      "status": "active"
    }
  ],
  "creation_date": "2025-12-16T22:11:23.228Z",
  "modified_date": "2025-12-16T22:11:23.228Z"
}

Admin delete a specified household

delete

This endpoint allows an admin to delete a household by its ID. The action removes the household from the system, ensuring that all associated data is also purged. This operation is critical for maintaining accurate household records and managing user identities effectively.

💻 Service Credentials is required to access this service.

🔒 Permission: households.delete is required in order for the call to succeed. You must configure permissions for the person or service calling this endpoint and add this permission to their identity.

Authorizations

clientCredentials

OAuth2authorizationCodeRequired

An OIDC service account that was authenticated.

Token URL:

Path parameters

householdIdstringRequired

Responses

200

OK

No content

401

Unauthorized

*/*

delete

/identities/admin/households/{householdId}

HTTPcURLJavaScriptPython

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

No content

Admin update of household member details

put

Updates the information of a specific member within a household. This operation is intended for administrative users and ensures that member data is current and accurate. It is crucial for maintaining the integrity of household profiles and enhancing user experience.

💻 Service Credentials is required to access this service.

🔒 Permission: households.members.update is required in order for the call to succeed. You must configure permissions for the person or service calling this endpoint and add this permission to their identity.

Authorizations

clientCredentials

OAuth2authorizationCodeRequired

An OIDC service account that was authenticated.

Token URL:

Path parameters

householdIdstringRequired

personIdstringRequired

Responses

200

OK

*/*

401

Unauthorized

*/*

put

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

HTTPcURLJavaScriptPython

PUT /identities/admin/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": "2025-12-16T22:11:23.228Z",
      "start_date": "2025-12-16T22:11:23.228Z",
      "expiration_date": "2025-12-16T22:11:23.228Z",
      "status": "active"
    }
  ],
  "creation_date": "2025-12-16T22:11:23.228Z",
  "modified_date": "2025-12-16T22:11:23.228Z"
}

Admin delete a member from a household.

delete

This endpoint allows an administrator to remove a specified member from a household. The action is permanent and affects the household's composition. It is crucial for managing household memberships effectively and ensuring accurate representation of members.

💻 Service Credentials is required to access this service.

🔒 Permission: households.members.update is required in order for the call to succeed. You must configure permissions for the person or service calling this endpoint and add this permission to their identity.

Authorizations

clientCredentials

OAuth2authorizationCodeRequired

An OIDC service account that was authenticated.

Token URL:

Path parameters

householdIdstringRequired

personIdstringRequired

Responses

200

OK

*/*

401

Unauthorized

*/*

delete

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

HTTPcURLJavaScriptPython

DELETE /identities/admin/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": "2025-12-16T22:11:23.228Z",
      "start_date": "2025-12-16T22:11:23.228Z",
      "expiration_date": "2025-12-16T22:11:23.228Z",
      "status": "active"
    }
  ],
  "creation_date": "2025-12-16T22:11:23.228Z",
  "modified_date": "2025-12-16T22:11:23.228Z"
}