Developer Center›API Reference

    API Reference

    The list below reflects the backend routes currently implemented in the repository. Public `/api/v1` endpoints are listed first, followed by internal dashboard routes that still exist for the web application.

    Base URL and Auth

    • Base URL: https://metro2.switchlabs.dev
    • Public endpoints are versioned under /api/v1.
    • Most public endpoints accept either Authorization: Bearer ... or x-api-key.
    • Test vs live behavior is controlled by the API key's environment value while using the same public host.

    Public API-Key Endpoints

    POST /api/v1/submit-metro2-data

    Auth: API key

    Accepts an array of records or `{ records: [...] }`. Returns `202` when fully accepted and `207` when partially accepted.

    GET /api/v1/batch-status/{id}

    Auth: API key

    Returns the stored ingest batch for the authenticated company.

    POST /api/v1/files/upload-url

    Auth: API key

    Creates a `file_uploads` row and returns a signed upload URL for direct storage upload.

    POST /api/v1/files/{id}/process

    Auth: API key

    Runs the CSV/XLSX processing pipeline with optional mappings, defaults, and validation controls.

    GET /api/v1/files/{id}/status

    Auth: API key

    Returns processing counters, timestamps, and stored processing errors.

    POST /api/v1/data-deletion

    Auth: x-api-key header

    Deletes records by `consumer_account_number` for the authenticated company. Maximum 100 account numbers per request.

    POST /api/v1/integrations/rentvine/sync

    Auth: API key

    Runs the implemented RentVine pull connector for a company with an active `integration_connections` row.

    POST /api/v1/integrations/rentvine/ingest

    Auth: API key

    Accepts RentVine tenant payloads, transforms them to Metro 2, validates, and upserts records.

    GET/POST /api/v1/webhooks

    Auth: API key

    List webhook endpoints with recent deliveries, or create a new endpoint with subscribed events.

    GET/PATCH/DELETE /api/v1/webhooks/{id}

    Auth: API key

    Fetch one webhook, update URL/events/enabled state, rotate its secret, or delete it.

    GET /api/v1/webhooks/{id}/deliveries

    Auth: API key

    Returns recent delivery attempts for a single webhook endpoint.

    POST /api/v1/webhooks/{id}/test

    Auth: API key

    Queues a test delivery to the selected webhook endpoint.

    POST /api/v1/webhooks/{id}/deliveries/{deliveryId}/replay

    Auth: API key

    Queues a replay of a stored webhook delivery payload.

    GET/POST /api/v1/disputes

    Auth: API key

    List disputes for the authenticated company or create a new dispute intake record.

    GET/PATCH /api/v1/disputes/{id}

    Auth: API key

    Fetch a dispute with notes, or update dispute state, reason, assignment, and resolution fields.

    POST /api/v1/disputes/{id}/notes

    Auth: API key

    Append a note to an existing dispute.

    POST /api/v1/disputes/{id}/resolve

    Auth: API key

    Resolve a dispute as verified, updated, deleted, or in_dispute and fire the matching webhook event.

    GET /api/v1/cra-responses

    Auth: API key

    Lists parsed CRA response files for the authenticated company.

    POST /api/v1/cra-responses/upload

    Auth: API key

    Uploads and parses a CRA response file using multipart form data with `file`, `bureau`, and optional `transmission_id`.

    GET /api/v1/cra-responses/{id}

    Auth: API key

    Returns one CRA response plus its parsed item rows.

    GET/POST /api/v1/schedules

    Auth: API key

    List schedules for the authenticated company or create/upsert a per-bureau schedule.

    GET/PATCH/DELETE /api/v1/schedules/{id}

    Auth: API key

    Fetch, update, or delete a saved schedule by ID.

    GET /api/v1/records/{id}/history

    Auth: API key

    Returns record-scoped audit history, including user-name enrichment when profile data is available.

    GET /api/v1/audit/export

    Auth: API key

    Exports company-scoped audit rows as CSV or JSON, with optional `record_id`, `action`, and `source` filters.

    Internal Dashboard Routes

    These endpoints still exist in the backend and are used by the web application. They are not the primary external contract now that the matching public routes exist under /api/v1.

    /api/v1/api-keys

    GET, POST, and PATCH exist, but they require an authenticated admin dashboard session rather than API-key auth.

    /api/webhooks

    Legacy dashboard route still used by the web app. The public equivalent is `/api/v1/webhooks`.

    /api/disputes

    Legacy dashboard routes still used by the web app. The public equivalents live under `/api/v1/disputes/*`.

    /api/cra-responses

    Legacy dashboard routes still used by the web app. The public equivalents live under `/api/v1/cra-responses/*`.

    /api/submission-schedules

    Legacy dashboard routes still used by the web app. The public equivalent is `/api/v1/schedules`.

    /api/audit-log

    Legacy dashboard retrieval route. Public equivalents are `/api/v1/records/{id}/history` and `/api/v1/audit/export`.

    Request Notes

    • Public ingest examples in this repo use ISO dates such as 2025-03-01 and integer monetary values.
    • POST /api/v1/submit-metro2-data supports both flat record payloads and the older nested account_data + primary_consumer shape.
    • Supplemental segments can be sent directly as j1_segments, j2_segments, l1_segments, k_segments, and n1_segments, or by the documented friendly aliases in the external ingest normalizer.

    Machine-Readable Spec

    The maintained OpenAPI document for the public API lives at /openapi-external-v1.yaml.