Migrating from v2

If you report your loan book to Sivo v2 (DaaS), moving that integration to v3 is mostly a change of paths and a handful of field names. The flow is the same three steps, with more general names, because v3 covers any receivable and not only loans:

Everything else carries over: amounts are still integers in the currency's smallest denomination (Money), dates and durations like "1 month" keep their format (Dates and Times), and every write is still an upsert keyed by an id you assign. Keep the ids you use in v2.

Endpoints

A few things also change around the requests:

• Base URL. All v3 requests go to https://core.sivo.com, with no version prefix. Sandbox and live share this URL; the API key you send picks the environment (see Testing).
• Authentication. v3 replaces the OAuth2 refresh/access token exchange with an API key from the developer dashboard, sent as the Authorization header on every request (Authorization: sk_live_...; see Authentication). There is no access token to fetch or refresh.
• Partial updates. When you upsert an id that already exists, you only need to send the fields that changed (see Updating Data).
• Retries. POST requests accept an IdempotencyKey header so you can retry safely (see Idempotent Requests).

Borrowers → accounts

Consumer and business borrowers become one account resource, told apart by type.

For example, this v2 business borrower:

{
  "id": "brw-1001",
  "company": "Acme Logistics LLC",
  "entity_document_id": "12-3456789",
  "date_of_incorporation": "2019-04-01",
  "address": { "street": "100 Main St", "city": "Austin", "state": "TX", "postal_code": "78701", "country": "US" },
  "country_code": "1",
  "phone": "5125550100",
  "email": "[email protected]",
  "website": "https://acme.com",
  "industry": "restaurants"
}

becomes this v3 account:

{
  "id": "brw-1001",
  "type": "business",
  "name": "Acme Logistics LLC",
  "legal_entity_id": "ein:123456789",
  "address": { "street_address": "100 Main St", "locality": "Austin", "region": "TX", "postal_code": "78701", "country": "US" },
  "phone": "+15125550100",
  "email": "[email protected]",
  "website": "https://acme.com",
  "industry": "722511"
}

Industry codes

Use this table to translate the v2 industry categories to NAICS codes. The codes are a reasonable default for each category; if you know a more precise code for a borrower, send that instead (NAICS search).

Loans → receivables

v3 checks a few rules that v2 did not enforce, so a loan v2 accepted can be rejected with 400 Bad Request:

• fund_name is required when funded_by is other, and must be omitted for sivo and balance_sheet.
• delinquent_times must be greater than zero when delinquent_amount is.
• delinquent_since is required when delinquent_amount is greater than zero, and must be empty otherwise. v2 accepted delinquent_days on its own; in v3, report how much is overdue along with when it became overdue.
• payment_frequency cannot be longer than term.

When a receivable comes out of delinquency, set delinquent_since to null and delinquent_amount to 0. Send the null explicitly: an omitted field is left unchanged (see Updating Data).

Reports → receivable entries

The loan id moves from the body into the path, and the status field is renamed. Entry types keep the same values and meaning.

A v2 report:

curl -X POST https://dev.sivo.com/v1/reports \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "rep-0001",
    "loan_id": "loan-1001",
    "date": "2026-08-01",
    "type": "disbursement",
    "amount": 250000,
    "balance": 250000,
    "loan_status": "active"
  }'

becomes this v3 receivable entry:

curl -X POST https://core.sivo.com/receivables/loan-1001/entries \
  -H "Authorization: $SIVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "rep-0001",
    "date": "2026-08-01",
    "type": "disbursement",
    "amount": 250000,
    "balance": 250000,
    "receivable_status": "active"
  }'

You can now also remove an entry reported by mistake with DELETE /receivables/{id}/entries/{entry_id}. For the complete account → receivable → entry flow in v3, see the Submit receivables recipe.

Moving your history

v3 calculates your portfolio metrics from the full history of every receivable, just like v2. You don't need to resend the borrowers, loans and reports you already reported in v2: Sivo will help migrate that history to v3. Coordinate the cutover with your Sivo contact so the history is in place before you start sending new activity to v3, and keep the same ids so your new entries line up with the migrated receivables. The history is copied from a snapshot of v2, so once it is in v3, send new activity to v3 only: anything you keep reporting to v2 afterwards has to be migrated again.