Quick Start

Step 1: Set your API key

All requests require the x-api-key header. Use sk_test_* keys during development.

x-api-key: sk_test_your_api_key_here

Sandbox keys (sk_test_*) create real data but Metro 2 files never reach bureaus. Use them freely during development.

Step 2: Create a consumer

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",
      "country": "US"
    },
    "external_id": "sp-user-001"
  }'

const response = await fetch(
  'https://vvdufluovypptsnkihyv.supabase.co/functions/v1/consumers',
  {
    method: 'POST',
    headers: {
      'x-api-key': 'sk_test_your_api_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      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',
        country: 'US',
      },
      external_id: 'sp-user-001',
    }),
  }
);
const consumer = await response.json();

import requests

response = requests.post(
    "https://vvdufluovypptsnkihyv.supabase.co/functions/v1/consumers",
    headers={
        "x-api-key": "sk_test_your_api_key_here",
        "Content-Type": "application/json",
    },
    json={
        "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",
            "country": "US",
        },
        "external_id": "sp-user-001",
    },
)
consumer = response.json()

Response (201)

{
  "id": "d1ba6184-b708-4e76-91fc-85dd6443c890",
  "first_name": "Jane",
  "last_name": "Doe",
  "middle_name": null,
  "date_of_birth": "1990-05-15",
  "phone": "+15551234567",
  "email": "jane.doe@example.com",
  "address": {
    "street": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "postal_code": "73301",
    "country": "US"
  },
  "external_id": "sp-user-001",
  "created_at": "2026-02-16T06:16:47.385307+00:00",
  "updated_at": "2026-02-16T06:16:47.385307+00:00"
}

The SSN is encrypted at rest and never returned in any API response. Save the id for creating tradelines.

Step 3: Create a tradeline

A tradeline represents an ongoing payment obligation being reported to credit bureaus.

curl -X POST https://vvdufluovypptsnkihyv.supabase.co/functions/v1/tradelines \
  -H "x-api-key: sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "consumer_id": "d1ba6184-b708-4e76-91fc-85dd6443c890",
    "payment_type": "child_support",
    "payment_type_label": "Monthly Child Support",
    "account_opened_date": "2025-01-01",
    "payment_amount": 150000,
    "payment_frequency": "monthly",
    "ecoa_code": "individual",
    "metro2_account_type": "installment",
    "report_to_bureaus": ["equifax", "transunion", "experian"]
  }'

Response (201)

{
  "id": "9c843590-8552-4490-a50c-f0cc413d8b69",
  "consumer_id": "d1ba6184-b708-4e76-91fc-85dd6443c890",
  "partner_id": "b3937f42-ca94-469d-a318-75fd149b3dfe",
  "payment_type": "child_support",
  "payment_type_label": "Monthly Child Support",
  "account_status": "current",
  "current_balance": 0,
  "amount_past_due": 0,
  "payment_history": "",
  "is_active": true,
  "created_at": "2026-02-16T06:16:56.200531+00:00",
  "updated_at": "2026-02-16T06:16:56.200531+00:00"
}

payment_amount is in cents. $1,500.00 = 150000. Save the tradeline id for payment reporting.

Step 4: Report a payment

Each month, report payments against the tradeline. The API automatically updates the tradeline’s status, balance, and payment history.

curl -X POST https://vvdufluovypptsnkihyv.supabase.co/functions/v1/payments \
  -H "x-api-key: sk_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tradeline_id": "9c843590-8552-4490-a50c-f0cc413d8b69",
    "payment_date": "2026-02-01",
    "period_start": "2026-02-01",
    "period_end": "2026-02-28",
    "amount_due": 150000,
    "amount_paid": 150000,
    "payment_status": "on_time"
  }'

Response (201)

{
  "id": "1bedd1b0-aadd-4d0e-8d23-68b2f9d30efb",
  "tradeline_id": "9c843590-8552-4490-a50c-f0cc413d8b69",
  "payment_date": "2026-02-01",
  "period_start": "2026-02-01",
  "period_end": "2026-02-28",
  "amount_due": 150000,
  "amount_paid": 150000,
  "payment_status": "on_time",
  "reported": false,
  "reported_at": null,
  "external_payment_id": null,
  "created_at": "2026-02-16T06:17:02.898846+00:00",
  "tradeline_status": {
    "account_status": "current",
    "current_balance": 0,
    "amount_past_due": 0,
    "payment_history": "0"
  }
}

The tradeline_status shows the auto-updated fields. The payment_history value "0" means “current” for this month.

What’s next?

Check submissions

Track when your data reaches the bureaus.

Set up webhooks

Get notified when bureau submissions are processed.

Enum reference

All payment types, status codes, and Metro 2 mappings.

Error handling

Understand error codes and handle failures gracefully.

Getting Started

Core Concepts

Reference

Migration

Step 1: Set your API key

Step 2: Create a consumer

Step 3: Create a tradeline

Step 4: Report a payment

What’s next?

Check submissions

Set up webhooks

Enum reference

Error handling

​Step 1: Set your API key

​Step 2: Create a consumer

​Step 3: Create a tradeline

​Step 4: Report a payment

​What’s next?

Check submissions

Set up webhooks

Enum reference

Error handling

Step 1: Set your API key

Step 2: Create a consumer

Step 3: Create a tradeline

Step 4: Report a payment

What’s next?