> ## 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.

# Migration Guide

> Migrate from the legacy SupportPay API to the Cove Data Furnishing API

## Overview

The old API used a single `POST /v1/rent-reporting/report` with all data in one flat request. The new API separates concerns:

| Old Approach                       | New Approach                            |
| ---------------------------------- | --------------------------------------- |
| All PII + payment in every request | Consumer created **once**               |
| Flat structure                     | Tradeline (obligation) created **once** |
| Single endpoint                    | Payments reported **monthly**           |
| No GET endpoints                   | Full read access to all resources       |
| No status tracking                 | Bureau submissions + webhooks           |

## Field mapping

| Old Field                   | New Endpoint       | New Field             | Notes                                     |
| --------------------------- | ------------------ | --------------------- | ----------------------------------------- |
| `first_name`                | `POST /consumers`  | `first_name`          | Same                                      |
| `last_name`                 | `POST /consumers`  | `last_name`           | Same                                      |
| `middle_name`               | `POST /consumers`  | `middle_name`         | Same                                      |
| `date_of_birth`             | `POST /consumers`  | `date_of_birth`       | Same                                      |
| `phone`                     | `POST /consumers`  | `phone`               | Now E.164 format                          |
| `email`                     | `POST /consumers`  | `email`               | Same                                      |
| `address.*`                 | `POST /consumers`  | `address.*`           | Same structure                            |
| `ecoa_code`                 | `POST /tradelines` | `ecoa_code`           | Same values                               |
| `lease_start_date`          | `POST /tradelines` | `account_opened_date` | Renamed                                   |
| `lease_end_date`            | `POST /tradelines` | `account_closed_date` | Set via PATCH or DELETE                   |
| `rent_amount`               | `POST /tradelines` | `payment_amount`      | **Now in cents!** Multiply by 100         |
| `account_status`            | —                  | Auto-computed         | Based on `payment_status`                 |
| `payment_history_profile`   | —                  | Auto-computed         | Built from 24-month rolling records       |
| `date_of_first_delinquency` | —                  | Auto-computed         | Set on first non-current payment          |
| `rent_paid`                 | `POST /payments`   | `amount_paid`         | **Now in cents!**                         |
| `current_balance_due`       | —                  | Auto-computed         | `amount_due - amount_paid` across periods |
| `amount_past_due`           | —                  | Auto-computed         | Sum of unpaid amounts                     |

## Key behavioral differences

1. **Consumer PII submitted once** — not with every payment report.
2. **Payment type is explicit** — use `child_support` instead of cramming into `rent_amount`.
3. **Amounts are in cents** — \$4,500.00 = `450000`. Multiply existing dollar values by 100.
4. **Status is auto-computed** — don't set `account_status` or `payment_history_profile` manually. They're derived from payment records.
5. **GET endpoints exist** — check submission status anytime via `GET /submissions`.
6. **Webhooks** provide push notifications for bureau responses.
7. **Tradeline represents the obligation** — created once, not re-sent with every payment.

## Step-by-step migration

<Steps>
  <Step title="Create consumers">
    For each unique person in your system, call `POST /consumers` once. Save the returned `id`.
  </Step>

  <Step title="Create tradelines">
    For each ongoing payment obligation, call `POST /tradelines` with the consumer's `id` and the correct `payment_type`. Save the returned tradeline `id`.
  </Step>

  <Step title="Report payments monthly">
    Each month, call `POST /payments` with the tradeline `id`, amount due, amount paid, and payment status.
  </Step>

  <Step title="Set up webhooks">
    Configure your `webhook_url` to receive bureau submission status updates.
  </Step>

  <Step title="Monitor submissions">
    Use `GET /submissions` to track bureau processing status.
  </Step>

  <Step title="Switch to production">
    Once integration testing is complete with `sk_test_*` keys, switch to `sk_live_*` for production.
  </Step>
</Steps>