Industry Templates & Onboarding

What it is

Metro 2 reporting has a long ramp. The CDIA Credit Reporting Resource Guide (CRRG) is ~440 pages, the field-by-field rules differ for every product type, and the wrong default in your first file is the kind of mistake that takes a bureau rejection (or worse, a quiet downstream dispute) to surface. Most new furnishers spend two to six weeks reading the CRRG, building a mapping spreadsheet by hand, and arguing with a sample file before they trust their generator output.

Industry Templates & the Onboarding Wizard compress that ramp into a five-step flow that takes about ten minutes. You pick the vertical you operate in, answer two or three vertical-specific questions, and Metro2 seeds:

• A field mapping template that already knows the column names common CSV exports use for that vertical (account number, balance, date opened, status, etc.).
• A validation profile — a curated subset of the system's 56 Metro 2 rules — that allows the codes your vertical actually uses, forbids the ones that would get you flagged, requires the fields your vertical can't omit, and silences the warnings that don't apply to your product.
• An in-app vertical guide (an MDX page at /metro2/industry/{slug}/guide) with the operational notes you actually need: how to handle repossessions, what the K3 segment expects, when DA is wrong (almost always), how IDR plans work, etc.

You can leave the preset as-is and start importing files immediately, or customize it after the fact from Settings → Industry and Settings → Validation Profiles. The wizard's job is to make the first file you generate work; the per-account customization comes later.

This guide covers five Phase 1 verticals — BNPL, debt collection, auto finance, mortgage servicing, and student loans. HOA and CDFI/nonprofit verticals ship as Wave 3 Tier C; see HOA & CDFI verticals for those.

Supported verticals

Each vertical maps to a preset bundle: an industry slug (industries.slug), a system validation profile slug (validation_profiles.slug, prefixed industry-), and a default field mapping template. The table below is the quick reference; deeper sections follow for each vertical.

The slugs are stable identifiers — they show up in API responses, generated files (via metadata), audit logs, and the URL of every per-vertical in-repo guide. Don't rename them on your side; rely on the slug, not the display name.

The onboarding wizard

New companies land on /onboarding automatically after the first sign-in. You can also revisit it at any time — answering the questions again won't replace your existing data, it'll just re-seed the preset recommendations. The wizard tracks progress in the onboarding_progress table so closing the tab and coming back the next day picks up where you left off.

There are five steps. Each step has a back button so you can iterate — none of the answers commit anything to your company until step 5.

Step 1 — Pick your industry

A grid of seven cards: BNPL, debt collection, auto finance, mortgage servicing, student loans, HOA management, and CDFI / nonprofit. Pick the one that best describes your primary product. If you span multiple verticals (e.g., you offer both BNPL Pay-in-4 and longer-term installment loans), pick the one that represents the majority of your file volume — you can add a second portfolio later via multi-portfolio routing.

Picking an industry sets companies.industry_slug as your in-progress choice (not committed until step 5) and pulls the matching preset bundle from GET /api/industries/{slug}/preset.

Step 2 — Vertical-tuned Q&A

Two or three multiple-choice questions specific to the vertical you picked. The questions are short, the answers are radio buttons, and most fields default to the most-common choice (Pay-in-4 for BNPL, original creditor for debt collection, etc.). Hints under each option explain what the answer changes downstream.

A few examples of what step 2 asks:

• BNPL — “What type of BNPL do you offer?” (Pay-in-4 / 3–24 month / hybrid) and “Route to Equifax BNPL specialty file?”
• Debt collection — “Who owns the debt you're reporting?” (original creditor / third-party collector / debt buyer) and “Do you report medical collections?”
• Auto finance — “What's your auto-lending model?” (indirect / direct / BHPH) and “Do you finance GAP / warranty / service contracts?”
• Mortgage servicing — “What lien position(s) do you service?” and “Which K3 agency identifier applies to most loans?”
• Student loans — “Federal or private?” and “How do you flag in-school deferment?”

Answers are stored in onboarding_progress.answers as JSON keyed by the question key (bnpl_mode, collection_type, etc.). They feed back into the preview step so you can see exactly what changes based on your answers.

Step 3 — Preset preview

A read-only preview of the preset Metro2 is about to seed for you. It shows:

• The validation profile — its name, description, allowed account types, required fields, and a count of rules disabled relative to the system default profile.
• The field mapping template — the column-name heuristics it'll use to auto-map your CSV (e.g., for auto finance: vin, year_make_model, down_payment in addition to the standard Metro 2 fields).
• The operational notes from the vertical spec — short bullets like “Voluntary surrender => status 96; involuntary repossession => status 97.”

Nothing is committed yet. If something looks wrong, hit back and re-answer.

Step 4 — Sample CSV preview

Optional but recommended. Drop a small CSV in (10–20 rows is plenty) and the wizard runs your file through the mapping template to show you exactly which columns it'll pick up and which ones it'll skip. This is your last chance to notice that your column is called borrower_ssn and the template expects consumer_ssn before you commit.

Files dropped at step 4 are processed in-memory for the preview only — nothing is uploaded to your account, nothing is persisted, nothing leaves the browser tab. If you want to do a more thorough column-name audit, open the file in the Metro 2 File Viewer first (also browser-only).

Step 5 — Finish & redirect to dashboard

Hit Finish and Metro2 commits the preset:

• Sets companies.industry_slug to your chosen vertical.
• Clones the system validation profile into a company-scoped copy (so customizing it later doesn't affect anyone else on the same vertical).
• Clones the system field mapping template into a company-scoped copy and sets it as your default.
• Marks onboarding_progress.completed_at with the current timestamp via POST /api/onboarding/complete.
• Redirects you to the dashboard with a one-time toast that links to the in-repo vertical guide.

From here, importing a file works the same way as it does for any account — the only difference is that the validator now uses your vertical profile by default, and the importer auto- maps a wider set of common column names.

What each vertical preset includes

The preset is three artifacts bundled together. They're installed atomically at step 5; you can't pick only one.

1. Field mapping template

A row in field_mapping_templates that the importer consults when it parses a CSV. The template lists the column-name variants the vertical commonly uses and the Metro 2 field each one maps to. For example, the auto-finance template auto-detects vin, year_make_model, collateral_description, down_payment, trade_in_amount, and a dozen other auto-specific column names in addition to the base Metro 2 fields.

The template is a starting point. After import you can edit it from Settings → Field Mappings, save your edits as the company default, and they'll be used on subsequent imports.

2. Validation profile

A row in validation_profiles whose rules JSONB column lists which of the 56 system rules are enabled, which are disabled, which are downgraded from error to warning, plus the allowed account-type list, required-field list, and forbidden-code map. Records that fail rules marked “error” block file generation; records that fail rules marked “warning” surface in the UI but don't block.

The vertical profile is a delta against the global default profile, not a replacement. See the inheritance section below for how that works.

3. MDX vertical guide

A markdown-with-JSX guide at /metro2/industry/{slug}/guide rendered from src/content/metro2/guides/. The guide goes deeper than the operational-notes bullets in the wizard preview — it covers the most common compliance gotchas, worked examples of representative records, and links to the authoritative CRRG section per topic.

The guide is the same content for everyone on a given vertical — it isn't per-account. Linking to it is encouraged; bookmark the URL for your team's onboarding docs.

Validation profiles & base inheritance

Every validation profile in Metro2 declares which other profile it extends, via the extends_system_profile_slug column. The vertical profiles all extend the system default profile (system-default), which contains the 56 baseline Metro 2 rules.

The vertical profile only stores the differences: which baseline rules it disables, which fields it elevates to required, which account-type codes it allows, and which codes it forbids per field. When the validator runs, it walks the inheritance chain from the company-scoped profile up to the vertical profile up to the system default, layering deltas as it goes.

The DB trigger

A Postgres trigger on validation_profiles enforces this — you can't insert a company-scoped profile that doesn't set base_profile_id to a system or vertical profile. The trigger exists specifically to prevent a customer (or an over-eager engineer) from shipping a broken-from-zero config that omits a required rule the bureaus care about.

What this means in practice:

• You can disable a rule your vertical profile inherits from the system default.
• You can add new required fields, new forbidden codes, new allowed account types.
• You cannot create a company-scoped profile with no base — the trigger rejects the insert.
• You cannot bypass a rule the system default marks as “always-on” (a small set of structural rules — RDW length, segment count consistency, base-record field-position invariants).

Pro+ gate on customization

Free and Starter accounts inherit the vertical profile as-is and can't customize it. Pro+ accounts unlock the per-rule customization UI at Settings → Validation Profiles and can:

• Disable any rule that isn't marked structural.
• Downgrade an error to a warning (or vice versa) per rule.
• Add company-specific required fields and forbidden codes.
• Clone a vertical profile into a second company-scoped profile and switch between them per portfolio.

The Pro+ gate exists because misconfigured validation rules are the most common cause of bureau rejections, and a wrong rule change is harder to debug than a wrong record. If you need a one-off rule change and don't have Pro+, contact support and we'll walk through whether the change is actually needed.

Vertical profile = profile slug + extends

For reference, the vertical profile rows look like this in the DB (system-scoped, no company_id):

-- One row per vertical, seeded by 20260520000002_seed_industry_templates.sql
{
  slug: "industry-mortgage",
  name: "Mortgage Servicing",
  extends_system_profile_slug: "system-default",
  company_id: null,                 // system profile, visible to all
  is_system: true,
  rules: {
    disabled: [],
    required_fields: [
      "portfolio_type",
      "account_type",
      "agency_identifier",
      "mortgage_id_number"
    ],
    allowed_account_types: ["26", "27", "29"],
    forbidden_codes: {}
  }
}

When you finish onboarding, Metro2 clones this row into a company-scoped copy where company_id is set to your account, is_system is false, and base_profile_id points back at the system row. Your customizations live on the clone; the system row stays pristine.

BNPL specifics

BNPL (Buy Now, Pay Later) covers Pay-in-4 products (Affirm Pay-in-4, Klarna, Afterpay, Sezzle) and longer-term installment financing (Affirm Plus, Klarna Financing). Both modes use theindustry-bnpl profile; the wizard's bnpl_mode answer just changes the default term length and frequency.

Configuration defaults

• Portfolio Type — I (Installment).
• Account Type — 07 (Charge account) is the most common; 19 (Line of credit), 9A (Charged-off BNPL), and 9B (BNPL-rebranded sub-code) are also allowed.
• Terms Frequency — B (biweekly) for Pay-in-4; M (monthly) for longer installment. The wizard sets this based on your bnpl_mode answer.
• Terms Duration — 004 for Pay-in-4 (four biweekly payments).
• Business Industry Code — required. The preset sets require_business_industry_code = true; file generation refuses to run if your portfolio doesn't have a BIC.

Disabled rule: DOFD on short-cycle loans

The BNPL profile disables M2_DELINQUENT_MISSING_DATE__fcra_date_of_first_delinquency. Pay-in-4 loans live 6–8 weeks total; a fresh loan with no missed payments has no formal Date of First Delinquency yet, and the global rule would error on every record. The vertical profile silences it. Once the loan crosses the 30-day bucket, DOFD becomes required again at the record level via the standard delinquent-status rules.

Forbidden: status DA

The BNPL profile forbids status code DA (Account Deleted by Mistake) on account_status. DA is for error corrections only — BNPL accounts past the FCRA 7-year obsolescence boundary must be omitted from the file entirely, not flagged DA. See FCRA obsolescence for the omission rules.

Equifax BNPL specialty file flag

Equifax operates a separate BNPL specialty file alongside its legacy core file. Step 2 of the wizard asks whether you want to route there. In Phase 1 this is a flag only — answering “yes” sets is_specialty_file=true on the file_uploads row and gates the requirement of business_industry_code. The actual specialty-file routing pipeline (separate bureau submission lane, specialty-file-specific BIC validation, separate file naming convention) ships with the multi-portfolio + BNPL-translation plans.

If you need full specialty-file support today, see multi-portfolio routing and BNPL translation. The vertical preset gets you the field-level configuration; those two plans cover the file-level routing.

Debt collection specifics

Collections reporting has the most rejected files of any vertical Metro2 supports, mostly because three things — DOFD tracking, FCRA obsolescence, and the misuse of status DA — are easy to get wrong and bureaus enforce them strictly.

Configuration defaults

• Account Type — 06 (original creditor), 92 (collection account — original creditor unknown), 93 (collection account — original creditor known), 95 (factored account).
• K1 segment (Original Creditor) — required. Both original_creditor_name and creditor_classification_code are elevated to required fields in the profile.
• DOFD — fcra_date_of_first_delinquency is required and must be ≤ 83 months old. Records past 83 months are omitted from the generated file per CDIA / FCRA 7-year rule.

DOFD handling — the most important field

Date of First Delinquency is the field bureaus use to compute when a collection account ages off. It does not reset when you (or a prior collector) place the account; it tracks back to the original 30-day delinquency on the original tradeline. If you bought a portfolio, the DOFD column on your placement file should be the original creditor's DOFD, not your placement date.

Metro2's obsolescence engine omits records where DOFD is more than 83 months old. We omit rather than flag DA because DA is specifically reserved for “account deleted by mistake” — see FCRA obsolescence for the full explanation.

Forbidden: status DA

Same as BNPL — the profile forbids DA on account_status. Use DA only when you previously reported an account in error and need to retract it; never as a way to mark an obsolete debt.

Junk-debt buyers — K1 seller chain

If you bought the portfolio from another buyer who bought it from the original creditor (a common pattern), the K1 segment on your first reporting cycle must show the chain: original creditor name, plus seller information for each transfer. After the first cycle the K1 stabilizes to the immediate predecessor. The profile flags missing K1 data as an error.

Medical collections

Per the March 2023 bureau policy:

• Medical collections under $500 must not be reported at all.
• Medical collections ≥ $500 may be reported, but only after 365 days of delinquency.
• Paid medical collections must be deleted, not reported as paid.

The wizard asks whether you report medical collections so we can surface these rules in the in-repo guide; the validation profile doesn't hard-block on amount + date because the creditor_classification_code for medical varies and false-positives on non-medical accounts would be worse than the policy signal.

Auto finance specifics

Auto-finance is one of the more straightforward verticals to report — the Account Type list is short, the Portfolio Type is fixed, and the bureau validators are forgiving on column-name variation. The hard parts are repossession reporting and add-on financing (GAP, extended warranty, service contracts).

Configuration defaults

• Portfolio Type — I (Installment).
• Account Type — 00 (auto loan); 01 (unsecured auto) is allowed for no-collateral edge cases (very rare).
• Required fields — portfolio_type, account_type, terms_duration. Auto terms are highly variable (24, 36, 48, 60, 72, 84 months) so the profile insists you populate the field per-loan.

The three lending models

Step 2 of the wizard asks which model you use:

• Indirect (dealer-funded) — you buy contracts from a dealer network. The dealer is the original creditor; you're the assignee. K1 segment is needed on the first reporting cycle (similar to debt-buyer behaviour above).
• Direct (consumer-facing) — you originate loans directly. No K1 needed.
• Buy Here Pay Here — single-store dealer + lender combined. Treated as direct origination for Metro 2 purposes.

Repossession reporting

Two status codes apply:

• Status 96 — Voluntary surrender. The consumer voluntarily returned the vehicle.
• Status 97 — Involuntary repossession. The lender (or its agent) took the vehicle.

Both require a non-zero original_charge_off_amount. The wholesale auction sale price hits amount_paid_to_date; the deficiency balance hits current_balance. The profile's in-repo guide has worked examples for repo + deficiency + bankruptcy interaction.

GAP, warranty, and service contracts

If you finance add-ons (GAP insurance, extended warranty, service contracts), include them in highest_credit_or_original_loan_amount — that's the total amount financed at origination, including the add-ons. Step 2 of the wizard asks; if you answer yes, the in-repo guide surfaces a worked example.

Add-on refunds (e.g., the consumer cancels the warranty mid-loan) adjust original_charge_off_amount on charge-off accounts, not current_balance. Bureau validators flag the wrong field with a structural-balance error.

Co-buyers and the J2 segment

Auto loans frequently have co-buyers (spouse, parent, business partner). The J2 segment carries the second consumer's PII; ecoa_code on the base record should be 2 (joint contractual liability) for any record that emits a J2 segment.

Mortgage servicing specifics

Mortgage is the heaviest vertical Metro 2 supports — the K3 segment is mandatory, lien position dictates account type, servicemember-related fields have their own compliance rules, and forbearance/modification reporting has historically been a moving target. The vertical profile handles the field-level requirements; the operational notes call out the gotchas.

Configuration defaults

• Portfolio Type — M (Mortgage).
• Account Type — 26 (first lien), 27 (junior lien), or 29 (HELOC). The wizard's lien_position answer determines the default for new portfolios; multi-lien shops can keep all three allowed.
• Required fields — portfolio_type, account_type, agency_identifier, mortgage_id_number. The last two drive the K3 segment.

The K3 segment

K3 is the Mortgage Information segment. Every mortgage record must carry it; the validator errors on records that omit it. K3 contains:

• Agency Identifier — two-character code identifying the loan's federal agency relationship: 00 (none / proprietary), 01 (Freddie Mac), 02 (Fannie Mae), 03 (FHA), 04 (VA), 05 (USDA), 06 (Other federal program). Step 2 of the wizard asks which value applies to most of your portfolio so the in-repo guide can be specific.
• Mortgage Identification Number — your internal loan ID, up to 18 bytes US / 22 bytes CA.

K3 generator parity verified. The mortgage K3 emitter has been regression-tested against the existing Canadian-jurisdiction test suite — the same suite that guarantees correct byte counts for J1/J2/K1/K2/K4/L1/N1 across US and CA file dialects. Specifically:

• US K3 emits at exactly 40 bytes (segment identifier “K3” + agency identifier 2 bytes + mortgage ID 18 bytes + filler).
• CA K3 emits at exactly 48 bytes (same shape with the wider mortgage ID column).
• The segment-count field in the trailer correctly increments for every K3 the file emits.
• Round-tripping through the Metro 2 file viewer reproduces the K3 fields byte-for-byte.

The parity tests live alongside the existing CA-jurisdiction test suite; the mortgage profile doesn't need a separate gate.

SCRA and the Military Lending Act

Servicemembers Civil Relief Act caps interest at 6% on obligations the consumer entered before active duty. When that cap applies, report via compliance_condition_code on the affected records. Don't alter scheduled_payment_amount to reflect the capped rate — keep that as the contractual payment and use the compliance code to signal the cap.

Military Lending Act protections (servicemember + 36% MAPR cap on certain loan types) are separate. If you originate under the MLA umbrella, see your compliance counsel — the vertical profile doesn't encode MLA-specific assumptions since most servicers don't originate under it.

Forbearance, modification, and escrow

• CARES Act forbearance — status 11 (current with forbearance) + Special Comment CP for accounts that were current at the time forbearance began.
• Loan modification — Special Comment AC; the modified terms become the new contractual baseline.
• Escrow shortage / advance — does not generally affect Metro 2 reporting; the escrow ledger is separate from the credit-reporting payment status. If escrow non-payment triggers contractual default, then it does flow through.

Student loans specifics

Student loans split cleanly between federal and private, and the two have meaningfully different reporting patterns — mostly around deferment, forbearance, and the income-driven repayment (IDR) plans that are exclusive to federal loans. One profile covers both because the field-level requirements are similar; the in-repo guide bifurcates the operational advice.

Configuration defaults

• Portfolio Type — I (Installment).
• Account Type — 12 (Education); 15 (Open-end student) is also allowed for the rare open-end products.
• Terms Frequency — required. Accepts D (deferred) without warning — see the IDR note below.

Disabled rules

The student-loan profile disables two global rules that would fire spuriously on legitimate student-loan records:

• M2_STUDENT_LOAN_TERMS_DURATION__terms_duration — student loan terms routinely run 120 to 300 months, well past the global warning threshold. The profile silences the warning since long terms are normal for the vertical.
• M2_PAYMENT_VARIANCE__actual_payment_amount — IDR-enrolled loans frequently report scheduled_payment_amount = 0 when the borrower's calculated payment is zero (low income). The global rule would warn on payment-vs-scheduled variance; the profile silences it because $0 is the correct IDR value, not a data-quality problem.

Federal vs private — what differs

Deferment and forbearance codes

• In-school deferment — status 11 + Special Comment D. The wizard asks how you want to flag this; Special Comment D is the bureau-preferred convention.
• Forbearance — status 11 + Special Comment CP (consumer agreement / hardship).
• IDR with $0 scheduled — leave status as the normal current status (11 or whatever applies); the $0 scheduled payment is the correct value, not a special comment. The validator profile doesn't flag $0 here.

Transfer scenarios

Federal student-loan servicing transfers between servicers frequently (Nelnet, MOHELA, EdFinancial, etc.). When you lose a portfolio:

• Report the outgoing record with status DF (transfer) and close the tradeline.
• The receiving servicer opens a fresh tradeline at the same DOFD, same originated balance, same first-payment date — no data should disappear from the consumer's credit file across the transfer.

The vertical profile's in-repo guide has a worked example of a Nelnet → MOHELA transfer to make this concrete.

Swapping your industry

If you picked the wrong vertical in onboarding (or your business has changed since), you can swap from Settings → Industry. The page shows your current vertical, the same seven cards from step 1 of the wizard, and a confirmation gate before any change commits.

What changes when you swap

• companies.industry_slug updates to the new slug.
• Your company's default validation profile flips to the new vertical's clone. If you didn't have a company-scoped clone yet, one is created on swap.
• Your default field mapping template flips to the new vertical's clone. New imports auto-detect using the new template.
• The dashboard's in-app help links and the “learn more” CTAs surface the new vertical's in-repo guide.

What does not change

• Existing records keep their assignments. Records you already imported retain their assigned validation profile and mapping template. Swapping the industry doesn't retro-validate or re-classify historical data.
• In-flight files keep their pipeline. A file currently importing or validating finishes with the profile it started with.
• Custom profiles you created stay. If you cloned the original vertical profile and added customizations, the clone persists and you can still apply it per portfolio. The default just switches to the new vertical's clone.

If you serve more than one vertical

Swapping is for “I picked wrong, please change my default.” If you genuinely operate in two verticals (e.g., you offer both Pay-in-4 BNPL and longer-term auto loans), don't swap back and forth — use multi-portfolio routing to assign different default profiles per portfolio and generate separate files per bureau lane.

API reference

Every wizard step is also available as a REST endpoint, so you can drive onboarding from your own provisioning code. All routes require an API key in the Authorization header (see API keys).

GET /api/industries

Returns the list of supported industries with their slugs, display names, and a short description. Free / public — no auth required.

curl https://metro2.switchlabs.dev/api/industries

[
  {
    "slug": "bnpl-providers",
    "name": "BNPL — Pay-in-4 / Installment",
    "description": "BNPL specialty: requires BIC + portfolio_type=I…"
  },
  { "slug": "debt-collectors",    "name": "Debt Collection", … },
  { "slug": "auto-lenders",       "name": "Auto Finance", … },
  { "slug": "mortgage-lenders",   "name": "Mortgage Servicing", … },
  { "slug": "student-loans",      "name": "Student Loans", … },
  { "slug": "hoa-management",     "name": "HOA Dues / Assessments", … },
  { "slug": "cdfi-nonprofit",     "name": "CDFI / Nonprofit Lending", … }
]

GET /api/industries/{slug}/preset

Returns the full preset bundle for a single industry — the validation profile spec, the mapping template, the vertical questions for step 2, and the operational notes. Used by the wizard preview step.

curl https://metro2.switchlabs.dev/api/industries/mortgage-lenders/preset

{
  "industry": {
    "slug": "mortgage-lenders",
    "name": "Mortgage Servicing"
  },
  "profile": {
    "slug": "industry-mortgage",
    "name": "Mortgage Servicing",
    "extends_system_profile_slug": "system-default",
    "allowed_account_types": ["26", "27", "29"],
    "required_fields": [
      "portfolio_type",
      "account_type",
      "agency_identifier",
      "mortgage_id_number"
    ],
    "disabled_rule_ids": [],
    "forbidden_codes": {}
  },
  "mapping_template": {
    "id": "tpl_mortgage_default",
    "name": "Mortgage Servicing — default"
  },
  "questions": [
    { "key": "lien_position", "prompt": "What lien position(s) do you service?", … },
    { "key": "k3_agency",     "prompt": "Which K3 agency identifier applies?", … }
  ],
  "operational_notes": [
    "K3 segment is mandatory (agency_identifier + mortgage_id_number); generator emits 40 bytes US / 48 bytes CA.",
    "SCRA rate cap (6% on pre-service obligations) reports via compliance_condition_code.",
    "Forbearance: status 11 + Special Comment CP for accounts current at entry."
  ]
}

POST /api/field-mapping-templates/clone

Clones a system mapping template into a company-scoped copy. The wizard calls this at step 5; you can call it directly to add a second company-scoped template (e.g., for a second portfolio).

curl -X POST https://metro2.switchlabs.dev/api/field-mapping-templates/clone \
  -H "Authorization: Bearer $METRO2_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_template_id": "tpl_mortgage_default",
    "name": "Mortgage Servicing — Q3 2026"
  }'

{
  "id": "tpl_abc123…",
  "name": "Mortgage Servicing — Q3 2026",
  "company_id": "co_…",
  "base_template_id": "tpl_mortgage_default"
}

GET /api/onboarding

Returns the current company's onboarding progress — which step you're on, what answers you've given so far, and whether you've completed it.

curl https://metro2.switchlabs.dev/api/onboarding \
  -H "Authorization: Bearer $METRO2_API_KEY"

{
  "company_id": "co_…",
  "industry_slug": "auto-lenders",
  "current_step": "preview-preset",
  "answers": {
    "auto_funding_model": "indirect",
    "auto_addons": "yes"
  },
  "started_at": "2026-05-17T13:22:01Z",
  "completed_at": null
}

PATCH /api/onboarding

Update the current step or merge an answer into answers. Idempotent — sending the same payload twice has no extra effect.

curl -X PATCH https://metro2.switchlabs.dev/api/onboarding \
  -H "Authorization: Bearer $METRO2_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "current_step": "upload-sample",
    "answers": {
      "auto_funding_model": "direct"
    }
  }'

POST /api/onboarding/complete

Commits the chosen industry as the company default. Clones the system validation profile and mapping template, sets completed_at, and returns the IDs of the cloned resources so you can reference them in subsequent imports.

curl -X POST https://metro2.switchlabs.dev/api/onboarding/complete \
  -H "Authorization: Bearer $METRO2_API_KEY"

{
  "company_id": "co_…",
  "industry_slug": "auto-lenders",
  "default_validation_profile_id": "vp_…",
  "default_mapping_template_id": "tpl_…",
  "completed_at": "2026-05-17T13:34:55Z"
}

POST /api/validation-profiles

Create a new company-scoped validation profile. base_profile_id is required for any company-scoped profile — the DB trigger described above will reject inserts that omit it. Pass the ID of the system or vertical profile you want to extend.

curl -X POST https://metro2.switchlabs.dev/api/validation-profiles \
  -H "Authorization: Bearer $METRO2_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Auto — repo-heavy Q3 portfolio",
    "base_profile_id": "vp_industry_auto_finance",
    "rules": {
      "disabled": [],
      "required_fields": [
        "portfolio_type",
        "account_type",
        "terms_duration",
        "original_charge_off_amount"
      ],
      "allowed_account_types": ["00"],
      "forbidden_codes": {
        "account_status": ["DA"]
      }
    }
  }'

{
  "id": "vp_…",
  "name": "Auto — repo-heavy Q3 portfolio",
  "company_id": "co_…",
  "base_profile_id": "vp_industry_auto_finance",
  "extends_system_profile_slug": "industry-auto-finance"
}

Available on Pro+ accounts only. Free / Starter accounts get a 403 with error: "validation_profile_customization_requires_pro".

Common questions

What if my product spans multiple verticals?

Don't try to pick the “most representative” one and hope the validator is forgiving — the vertical profiles have different required-fields, different account-type allowlists, and different disabled rules. Records from the wrong vertical will trip false errors.

Use multi-portfolio routing to define a portfolio per vertical, attach a default validation profile and mapping template to each, and let the file generator emit a separate Metro 2 file per portfolio. The wizard's primary-vertical choice becomes the default; portfolios override it for their slice of the data.

Can I create a custom validation profile?

Yes, on Pro+ accounts. Free and Starter accounts inherit the vertical profile as-is. The Pro+ gate exists because misconfigured rules are the most common cause of bureau rejections, not because the feature is hard to build.

Custom profiles must extend a base profile — the DB trigger enforces this. You can extend the system default profile directly (for a truly bespoke setup) or extend a vertical profile (to keep the vertical's smart defaults and add your own deltas on top).

Will applying a vertical preset break existing records?

No. The preset attaches to the company's default profile and template, which only affects future imports. Records already in your account keep the profile and template they were imported with, including their validation results.

If you want to re-validate historical records under the new profile (e.g., to see how a freshly-swapped vertical changes your error counts), use the bulk re-validate action in the dashboard — it doesn't modify the records, it just re- runs validation and updates the badge counts.

Can I customize the wizard questions?

Not in v1. The vertical-tuned questions live in src/lib/industry-templates/questions.ts as TypeScript constants and the answers are stored under known keys (bnpl_mode, collection_type, etc.) that the wizard hard-codes against. Adding a vertical or a question requires a release.

If you have a question we should add (e.g., for a new product variant within your vertical), reach out via contact support — the question set is intentionally small but we accept curated additions.

What if my CSV column names don't match the template?

Step 4 of the wizard surfaces this — you'll see exactly which columns the template recognised and which it skipped. You can either rename your columns to match (one-time edit in your export pipeline) or edit the mapping template under Settings → Field Mappings to add your column names as aliases. Aliases persist for the company; subsequent imports use them automatically.

Does the wizard support uploading a real production file in step 4?

You can, and we won't stop you, but the step is designed for a sample — 10 to 20 rows is plenty to confirm the column mapping. Files at step 4 are processed in-memory and never persisted to your account, so dropping a production file there means you'll have to re-upload it through the normal import flow afterwards to actually use it.

Can I skip the wizard?

Yes — pick an industry on step 1, click “finish setup now” on any subsequent step, and Metro2 will commit the preset using the defaults for unanswered questions. You can revisit any answer later from Settings → Industry. That said, the questions only take a minute and the answers materially improve the in-repo guide you get afterwards.

Troubleshooting

I picked the wrong vertical in onboarding

Go to Settings → Industry, pick the correct vertical, and confirm the swap. Existing records keep their original profile and mapping; only future imports use the new defaults. See “Swapping your industry” above for the full list of what changes and what doesn't.

I'm on Free / Starter and the “customize profile” button is grayed out

Per-rule customization is gated to Pro+ accounts. The vertical profile you got from onboarding is fully usable as-is — every field, allowed code, and disabled rule is already tuned for your vertical. If you've confirmed a specific rule change is genuinely needed for your business, contact support and we'll help work through whether to upgrade or whether a different fix applies.

My CSV imported but most columns came in as “unmapped”

The mapping template didn't recognise your column names. Three steps:

1. Open the file in the Metro 2 File Viewer to see the actual column names your export uses.
2. Compare them to the template's expected names at Settings → Field Mappings.
3. Either rename the columns in your export, or add your column names as aliases on the template. The template change persists and applies to future imports.

Validation profile rejects records I think are correct

First, confirm you're looking at validation errors from the vertical profile and not from the global default — Settings → Validation Profiles shows which profile is active. If the right vertical profile is selected and you still think a rule is wrong:

• Check the rule against the CRRG. Most vertical-profile rules trace to a specific CRRG section; the rule ID and description link directly to it.
• Check whether the rule should be silenced for your sub- segment. Some rules apply only to specific product variants (e.g., the BNPL DOFD rule is silenced for short-cycle loans).
• If the rule is genuinely wrong, file via contact support with the record CSV and the expected behaviour. System profiles get patched in releases; we don't ask customers to work around them.

I called POST /api/validation-profiles and got a 400 about base_profile_id

The DB trigger requires base_profile_id on any company-scoped insert. Pass the ID of the system or vertical profile you want to extend — usually the vertical profile (e.g., vp_industry_auto_finance). The error is intentional; it prevents broken-from-zero profiles from shipping.

The wizard says “onboarding incomplete” on the dashboard even though I clicked finish

Check whether POST /api/onboarding/complete succeeded — if the request failed (network error, expired session), the wizard's local state shows finished but the server-side completed_at is still null. Revisit /onboarding; it resumes from the last persisted step and a single “finish” click commits cleanly.

Related guides

• Multi-portfolio routing — for furnishers who operate in more than one vertical or need to emit separate Metro 2 files per portfolio / bureau lane. The vertical preset is the per-company default; multi-portfolio routing is how you override it per slice of the data.
• BNPL translation — full coverage of the Equifax BNPL specialty file pipeline: specialty-file routing, separate bureau submission lane, specialty-file-specific BIC validation, file naming conventions. The vertical preset gives you the flag; the translation plan covers the full routing.
• HOA & CDFI verticals — Wave 3 Tier C vertical presets for HOA dues / assessments and CDFI / nonprofit lending. Same wizard, same preset shape; covered separately because they have meaningfully different compliance gates (CC&R disclosure attestation for HOA, CDFI Fund certification verification for CDFI).
• Metro 2 File Viewer — browser-only tool for inspecting CSV and .dat files. Useful at wizard step 4 if your column names aren't auto-mapping, and useful any time you need to confirm what an exported file actually contains.
• FCRA obsolescence — why the BNPL and debt-collection profiles forbid status DA, and how the omission engine handles records past the 7- year (83-month) boundary.