Developer Center›Guides›Your First Submission

    Your First Metro 2® API Submission

    This guide walks you through making your first Metro 2® credit reporting submission, from authentication to generating a bureau-ready file.

    1. Prerequisites

    Before you begin, make sure you have the following:

    • 1.
      A Metro 2® API account — Sign up at metro2.switchlabs.dev if you haven't already.
    • 2.
      Your API key — Found in your dashboard under Settings → API Keys. You'll have both a sandbox key (prefixed with test_) and a live key (prefixed with live_).
    • 3.
      Your data furnisher information — Your company name, address, and the bureau program identifier assigned during onboarding.

    Tip

    Use your sandbox API key for testing. Sandbox submissions are fully validated but never reach the credit bureaus. See the Sandbox Environment guide for details.

    2. Authentication

    All API requests require an API key passed via the Authorization header using the Bearer scheme.

    // Every request must include this header
Authorization: Bearer YOUR_API_KEY

// Example using curl
curl -X GET https://api.metro2.switchlabs.dev/v1/records \
  -H "Authorization: Bearer test_sk_abc123def456" \
  -H "Content-Type: application/json"

    If authentication fails, the API returns a 401 Unauthorized response. Double-check that your key is correct and that you are using the right environment (sandbox vs. production).

    3. Create a Record

    A record represents one tradeline (account) for one consumer. Send a POST request with the consumer and account details in JSON format.

    POST /v1/records
Content-Type: application/json
Authorization: Bearer test_sk_abc123def456

{
  "accountNumber": "ACCT-10042",
  "portfolioType": "I",
  "accountType": "01",
  "accountStatus": "11",
  "dateOpened": "2024-03-15",
  "currentBalance": 12500,
  "creditLimit": 25000,
  "highestCredit": 25000,
  "scheduledPaymentAmount": 350,
  "actualPaymentAmount": 350,
  "paymentHistoryProfile": "000000000000000000000000",
  "consumer": {
    "name": {
      "firstName": "JOHN",
      "lastName": "DOE"
    },
    "ssn": "123456789",
    "dateOfBirth": "1985-06-15",
    "address": {
      "street": "123 MAIN ST",
      "city": "ANYTOWN",
      "state": "CA",
      "zip": "90210"
    }
  }
}

    Key Fields

    • portfolioType — I (Installment), R (Revolving), M (Mortgage), O (Open)
    • accountStatus — 11 (Current), 71 (30 days late), 78 (60 days), etc.
    • paymentHistoryProfile — 24-character string tracking monthly payment status

    4. Validate the Record

    Before generating a file, validate your record to catch errors early. The validation endpoint checks all Metro 2® format rules without creating a permanent record.

    POST /v1/records/validate
Content-Type: application/json
Authorization: Bearer test_sk_abc123def456

// Same JSON body as the create request

// Success Response (200 OK)
{
  "valid": true,
  "warnings": [],
  "errors": []
}

// Failure Response (422 Unprocessable Entity)
{
  "valid": false,
  "warnings": [
    "Payment History Profile should start with current month status"
  ],
  "errors": [
    "Account Status '99' is not a valid Metro 2 status code",
    "SSN must be exactly 9 digits"
  ]
}

    Fix any errors before proceeding. Warnings are informational and won't block submission, but should be reviewed.

    5. Generate a File

    Once your records are created and validated, generate a bureau-ready Metro 2® file. This file contains all records for the reporting period, packaged in the correct fixed-width format.

    POST /v1/files/generate
Content-Type: application/json
Authorization: Bearer test_sk_abc123def456

{
  "reportingPeriod": "2025-01",
  "format": "fixed",
  "includeRecordIds": ["rec_abc123", "rec_def456"]
}

// Response (202 Accepted)
{
  "fileId": "file_xyz789",
  "status": "processing",
  "recordCount": 2,
  "createdAt": "2025-01-15T10:30:00Z"
}

    File generation is asynchronous. The API returns a fileId that you can poll for completion status.

    6. Check File Status

    Poll the file endpoint to check when your file is ready for download or delivery.

    GET /v1/files/file_xyz789
Authorization: Bearer test_sk_abc123def456

// Response when complete (200 OK)
{
  "fileId": "file_xyz789",
  "status": "completed",
  "recordCount": 2,
  "errorCount": 0,
  "downloadUrl": "https://api.metro2.switchlabs.dev/v1/files/file_xyz789/download",
  "createdAt": "2025-01-15T10:30:00Z",
  "completedAt": "2025-01-15T10:30:12Z"
}

// Possible statuses: "processing", "completed", "failed"

    File Status Values

    • processing — File is being generated (typically 5-30 seconds)
    • completed — Ready for download or SFTP delivery
    • failed — Generation failed; check the errors array for details

    Related Resources