> ## Documentation Index
> Fetch the complete documentation index at: https://new.cove.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Consumers

> Manage consumer records (PII) for credit bureau reporting

Consumers represent the individuals whose payments are being reported to credit bureaus. You register a consumer once, then create tradelines and report payments against them.

## Creating a consumer

```bash theme={null}
curl -X POST https://vvdufluovypptsnkihyv.supabase.co/functions/v1/consumers \
  -H "x-api-key: sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Doe",
    "date_of_birth": "1990-05-15",
    "ssn": "123-45-6789",
    "phone": "+15551234567",
    "email": "jane.doe@example.com",
    "address": {
      "street": "123 Main St",
      "city": "Austin",
      "state": "TX",
      "postal_code": "73301"
    },
    "external_id": "sp-user-001"
  }'
```

### Required fields

| Field           | Type   | Description                                |
| --------------- | ------ | ------------------------------------------ |
| `first_name`    | string | Max 25 chars                               |
| `last_name`     | string | Max 25 chars                               |
| `date_of_birth` | string | YYYY-MM-DD                                 |
| `phone`         | string | E.164 format (e.g., `+15551234567`)        |
| `email`         | string | Valid email address                        |
| `address`       | object | Street, city, state (2-char), postal\_code |

### Optional fields

| Field             | Type   | Description                                                        |
| ----------------- | ------ | ------------------------------------------------------------------ |
| `middle_name`     | string | Max 25 chars                                                       |
| `ssn`             | string | SSN (XXX-XX-XXXX or XXXXXXXXX). Encrypted at rest, never returned. |
| `address.country` | string | 2-char ISO code. Default: `US`                                     |
| `external_id`     | string | Your internal ID. Max 255 chars.                                   |

## SSN handling

<Warning>SSNs are encrypted at rest using PGP symmetric encryption and are **never returned** in any API response, including GET requests.</Warning>

You can update an SSN via `PATCH /consumers/:id` — the new value will be re-encrypted.

## Uniqueness

Uniqueness is enforced per-partner on `email` and `external_id`. Attempting to create a duplicate returns `409 CONFLICT`.

## Soft deletion

`DELETE /consumers/:id` is a soft delete:

* Sets `deleted_at` to the current timestamp
* Deactivates all related tradelines (`is_active = false`)
* Consumer no longer appears in list results or is accessible by ID

```json Delete response theme={null}
{ "message": "Consumer deleted" }
```

## Listing and filtering

```bash theme={null}
curl "https://vvdufluovypptsnkihyv.supabase.co/functions/v1/consumers?email=jane.doe@example.com" \
  -H "x-api-key: sk_test_your_api_key_here"
```

| Filter        | Type   | Description |
| ------------- | ------ | ----------- |
| `email`       | string | Exact match |
| `external_id` | string | Exact match |
| `phone`       | string | Exact match |

See [Pagination](/guides/pagination) for `page` and `per_page` params.