List pending household matches

GET

/api/household-matches

const url = 'https://example.com/api/household-matches';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://example.com/api/household-matches \
  --header 'Authorization: Bearer <token>'

Authorizations

BearerAuth

Parameters

Query Parameters

needId

string format: uuid

Responses

200

A list of household matches

application/json

Array<object>

object

required

Unique identifier (UUID v4) for the resource.

string format: uuid

organizationId

required

Unique identifier (UUID v4) for the parent organization.

string format: uuid

constituentId

required

UUID (v4) of the constituent record.

string format: uuid

potentialHouseholdId

required

UUID (v4) of the matched potential household group.

string format: uuid

confidenceScore

required

Machine learning match confidence score (0.0 to 1.0).

number format: float

reason

required

Explanation of why the record match was flagged.

string

status

required

Current status of the record or process.

string

createdAt

required

UTC ISO-8601 timestamp when the record was created.

string format: date-time

resolvedBy

UUID (v4) of the admin user who resolved the record match.

string format: uuid

resolvedAt

UTC ISO-8601 timestamp when the match was resolved.

string format: date-time

constituentName

Full name of constituent involved in record match.

string

constituentPhone

Phone number of constituent involved in record match.

string

constituentEmail

Email of constituent involved in record match.

string

constituentAddress

Physical address of constituent involved in record match.

string

potentialHouseholdName

Display name of potential household match.

string

potentialHouseholdAddress

Address of potential household match.

string

Example

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
    "organizationId": "10000000-0000-0000-0000-000000000001",
    "constituentId": "40000000-0000-0000-0000-000000000004",
    "potentialHouseholdId": "60000000-0000-0000-0000-000000000006",
    "confidenceScore": 0.94,
    "reason": "Matching phone number (+17045550199) and physical street address.",
    "status": "IN_PROGRESS",
    "createdAt": "2026-07-28T12:00:00Z",
    "resolvedBy": "a1b2c3d4-e5f6-7890-abcd-1234567890ab",
    "resolvedAt": "2026-07-28T15:00:00Z",
    "constituentName": "Sarah Jenkins",
    "constituentPhone": "+17045550199",
    "constituentEmail": "sarah.j@example.com",
    "constituentAddress": "456 Oak Avenue Concord NC",
    "potentialHouseholdName": "Jenkins Household",
    "potentialHouseholdAddress": "456 Oak Avenue Concord NC"
  }
]

401

Unauthorized

403

Forbidden