Skip to content

API

Jump to bottom
Betsy Lorton edited this page Oct 14, 2026 · 12 revisions

This documentation describes the API that the Django application provides for querying all Metro2 related data.

Authentication

Users authenticate through SSO to access the Metro2 application. After a successful login, a cookie is stored in the browser session. All API requests will need to include that cookie in the header to successfully authenticate with the Django backend.

Example header: Cookie: csrftoken=08px9D0G8M0CSbpupDmXzm1i8zcFL6u6; sessionid=pwnfvjvonnpmvyrl732rzt6w3gszijjt

API endpoints

Quick links:

Exporting evaluator metadata CSV

/api/all-evaluator-metadata/

GET - returns a CSV of all evaluator metadata.

Use this endpoint to export the full set of evaluators, in order to preserve a snapshot or copy the metadata to another Metro2 instance.

For each EvaluatorMetadata object in the system, the CSV contains the following fields: ID, category, description, long description, fields used, fields display, CRRG reference, potential harm, rationale, alternate explanation, additional notes, and last modified dates. Fields that are saved as rich text in the admin view are exported as raw HTML.

Example response: File name: evaluator-metadata-2026-09-22.csv

Exporting evaluator results CSV

/api/events/{event_id}/evaluator/{evaluator_id}/csv/

GET - returns a CSV of evaluator results for a single evaluator (whose ID matches evaluator_id) for a single event (with the ID event_id).

Users can import this CSV into Excel in order to sort, filter, and analyze the results. The CSV contains one row for each EvaluatorResult for the given event + evaluator combo. The CSV includes all available data about the account, but excludes personal information about the account holder.

Example response: File name: MyEvent2024_Portfolio-Type-1.csv

Evaluator results view

/api/events/{event_id}/evaluator/{evaluator_id}/?view={sample, all}&page={x}&page_size={y}&{additional field filters}

GET - returns a JSON with a hits field composed of a list that contains one object per EvaluatorResult for a single event (with the id event_id) and evaluator (whose ID matches evaluator_id) combo, and a count field that lists the count of results when paginating.

It takes a parameter, view parameter which can be either sample or all. If sample is given then a sampling of the results that is one page long is returned. If all is given, then the first page of results is returned unless page is given with a page number. If page_size is given it will set the number of results per page, otherwise the number of results per page will be the default sample size.

The following additional field filters can be added to the end of the query string, with either a single value to match exactly or a comma-separated list of values to match exactly. The special value blank represents an empty string to filter.

For example, the value of acct_type to filter for might be given in the query string as ?acct_stat=11&view=all or as ?acct_stat=11,13,61,62&view=all.

  • acct_stat
  • compl_cond_cd
  • php1
  • pmt_rating
  • spc_com_cd
  • terms_freq
  • account_holder__cons_info_ind
  • account_holder__cons_info_ind_assoc
  • l1__change_ind

The following field filters can be added as either a boolean true or false.

For example, the value of dofd to filter for might be given in the query string as ?dofd=true&view=all or as ?dofd=false&view=all.

  • dofd
  • date_closed

The following field filters accept value ranges.

For example, the range of of values of amt_past_due to filter for might be given in the query string as ?amt_past_due_max=500&amt_past_due_min=400&view=all.

  • amt_past_due as amt_past_due_max/amt_past_due_min
  • current_bal as current_bal_max/current_bal_min
  • smpa as smpa_max/smpa_min

If a sort parameter is given the results will be sorted by the given field(s) either ascending (using the field name without decoration) or descending (prefixing the field name with -). Fields the results can be sorted on are:

  • activity_date
  • cons_acct_num
  • port_type
  • acct_type
  • date_open
  • credit_limit
  • hcola
  • id_num
  • terms_dur
  • terms_freq
  • smpa
  • actual_pmt_amt
  • acct_stat
  • pmt_rating
  • php
  • php1
  • spc_com_cd
  • compl_cond_cd
  • current_bal
  • amt_past_due
  • orig_chg_off_amt
  • doai
  • dofd
  • date_closed
  • dolp
  • int_type_ind
  • account_holder__cons_info_ind
  • account_holder__ecoa
  • account_holder__cons_info_ind_assoc
  • account_holder__ecoa_assoc
  • k2__purch_sold_ind
  • k2__purch_sold_name
  • k4__balloon_pmt_amt
  • l1__change_ind
  • l1__new_id_num
  • l1__new_acc_num

Multiple fields can be sorted by comma-separating them. For example, ?view=all&sort=-activity_date,current_bal will sort by activity date descending (newest first) and by current balance ascending (lowest first).

Example response:

{
    "count": 1032,
    "hits": [
        {
            "activity_date": "2025-12-05",
            "cons_acct_num": "0123456789012",
            "port_type": "I",
            "acct_type": "00",
            "date_open": "2014-02-13",
            "credit_limit": 0,
            "hcola": 654544,
            "id_num": "",
            "terms_dur": "REV",
            "terms_freq": "M",
            "smpa": 0,
            "actual_pmt_amt": 0,
            "acct_stat": "11",
            "pmt_rating": "",
            "php": "021001100000321101100000",
            "php1": "0",
            "spc_com_cd": "",
            "compl_cond_cd": "",
            "current_bal": 23535,
            "amt_past_due": 0,
            "orig_chg_off_amt": 0,
            "doai": "2025-11-30",
            "dofd": "2025-04-12",
            "date_closed": null,
            "dolp": "2025-11-18",
            "int_type_ind": "F",
            "surname": "Claus",
            "first_name": "Santa",
            "middle_name": "T",
            "gen_code": "",
            "ssn": "000000000",
            "dob": "1900-12-25",
            "phone_num": "8008008080",
            "ecoa": "1",
            "ecoa_assoc": [],
            "cons_info_ind": "",
            "cons_info_ind_assoc": [],
            "addr_line_1": "12 Santa's Workshop Way",
            "addr_line_2": "",
            "city": "North Pole",
            "state": "AK",
            "zip": "99000",
            "addr_ind": "Y",
            "res_cd": "O",
            "k2__purch_sold_ind": null,
            "k2__purch_sold_name": null,
            "k4__spc_pmt_ind": null,
            "k4__deferred_pmt_st_dt": null,
            "k4__balloon_pmt_due_dt": null,
            "k4__balloon_pmt_amt": null,
            "l1__change_ind": null,
            "l1__new_acc_num": null,
            "l1__new_id_num": null,
            "previous_values__activity_date": null,
            "previous_values__port_type": null,
            "previous_values__acct_type": null,
            "previous_values__date_open": null,
            "previous_values__id_num": null,
            "previous_values__acct_stat": null,
            "previous_values__pmt_rating": null,
            "previous_values__current_bal": null,
            "previous_values__orig_chg_off_amt": null,
            "previous_values__dofd": null,
            "previous_values__date_closed": null,
            "previous_values__surname": null,
            "previous_values__first_name": null,
            "previous_values__ecoa": null,
            "previous_values__ecoa_assoc": null,
            "previous_values__cons_info_ind": null,
            "previous_values__cons_info_ind_assoc": null,
            "previous_values__l1__change_ind": null,
            "previous_values__l1__new_acc_num": null,
            "previous_values__l1__new_id_num": null
        }, { ... }
    ]
}

Evaluator results facet view

/api/events/{event_id}/evaluator/{evaluator_id}/facets/

Returns a JSON with a facets field containing the count of results for each value for every AnyCharFilter. This excludes the range filters, boolean filters, and cons_info_ind_assoc which is a JSON field filter. The endpoint takes the same filter parameters as the evaluator results view, so the facet counts can be updated based on those filter parameters.

Example response:

{
    "count": 3765,
    "facets": {
        "acct_stat": {
            "13": 3445,
            "64": 320
        },
        "compl_cond_cd": {
            "blank": 3765
        },
        "php1": {
            "0": 3415,
            "1": 15,
            "3": 5,
            "B": 5,
            "D": 10,
            "K": 10,
            "L": 305
        },
        "pmt_rating": {
            "blank": 320,
            "0": 3420,
            "1": 20,
            "3": 5
        },
        "spc_com_cd": {
            "blank": 3725,
            "AU": 40
        },
        "terms_freq": {
            "M": 3765
        },
        "cons_info_ind": {
            "blank": 3750,
            "D": 5,
            "R": 10
        },
        "l1__change_ind": {
            "blank": 3765
        }
    }
}

Account list view

/api/events/{event_id}/accounts/?cons_acct_num={comma separated list of account numbers}

GET - takes a comma-separated list of account numbers and returns a JSON array of those accounts with their portfolio type, account type, and the total number of evaluator hits and total number of records of data, for a given event.

For example, a query of /api/events/1/accounts/?cons_acct_num=1234567890,2345678901 should return JSON like:

[
    {
        "cons_acct_num": "1234567890",
        "port_type": "I",
        "acct_type": "00"
        "total_hits": 1,
        "total_records": 5,
    },
    {
        "cons_acct_num": "2345678901",
        "port_type": "I",
        "acct_type": "00"
        "total_hits": 1,
        "total_records": 5,
    },
]

Account summary view

/api/events/{event_id}/accounts/{account_number}/

GET - returns a JSON with three fields -cons_acct_num,inconsistencies, and account_activity. The cons_acct_num field contains the account number, inconsistencies is composed of a list of inconsistencies found for the account, and account_activity is composed of a list of activity records with this cons_acct_num.

Example response:

{
    "cons_acct_num": "1234567890",
    "inconsistencies": [
        "SCC-Balance-8",
        "PROG-Bankruptcy-1",
        "Type-APD-2",
        "Balloon-Balance-1",
    ],
    "account_activity": [
        {
            "id": 3,
            "inconsistencies": [
                "SCC-Balance-8",
                "Type-APD-2",
            ],
            "activity_date": "11/30/2023",
            "account_holder__surname": "",
            "account_holder__first_name": "",
            "port_type": "I",
            "acct_type": "00",
            "date_open": "1/30/2018",
            "credit_limit": 0,
            "hcola": 24294,
            "terms_dur": "072",
            "terms_freq": "",
            "smpa": "",
            "actual_pmt_amt": "",
            "acct_stat": "",
            "pmt_rating": "",
            "php": "",
            "php1": "",
            "spc_com_cd": "",
            "compl_cond_cd": "",
            "current_bal": "",
            "amt_past_due": "",
            "orig_chg_off_amt": "",
            "doai": "",
            "dofd": "",
            "date_closed": "",
            "dolp": "",
            "int_type_ind": "",
            "account_holder__cons_info_ind": "",
            "account_holder__ecoa": "2",
            "account_holder__cons_info_ind_assoc": ["1A", "B"],
            "account_holder__ecoa_assoc": ["2", "2", "2", "2"],
            "k2__purch_sold_ind": null,
            "k2__purch_sold_name": "",
            "k4__balloon_pmt_amt": 11854,
            "l1__change_ind": "2",
            "l1__new_id_num": "0032",
            "l1__new_acc_num": "32",
        },
        # ...etc.
    ]
}

Account PII view

/api/events/{event_id}/accounts/{account_number}/account_holder/

GET - returns a JSON for the latest account holder information for a specified account_number and event_id.

Example response:

{
    "id": 1,
    "cons_acct_num": "1234567890",
    "surname": "Claus",
    "first_name": "Santa",
    "middle_name": "H",
    "gen_code": "",
    "ssn": "333224444",
    "dob": "12/25/1900",
    "phone_num": "5552220000",
    "ecoa": "",
    "cons_info_ind": "",
    "country_cd": "",
    "addr_line_1": "12 Santa's Workshop Way",
    "addr_line_2": "",
    "city": "North Pole",
    "state": "AK",
    "zip": "99000",
    "addr_ind": "",
    "res_cd": ""
}

Events view

/api/events/{event_id}/

GET - returns a JSON information about an event, including its name and all evaluators that have results for the specified event_id.

Example response:

{
  "id": 1,
  "name": "Sample-Dataset-007",
  "portfolio": "",
  "eid_or_matter_num": "",
  "other_descriptor": "",
  "directory": "/src/metro2/django/sample_data",
  "date_range_start": "2021-07-30",
  "date_range_end": "2022-11-30",
  "total_tradelines": 15860,
  "total_accounts": 5104,
  "evaluators": [
    {
      "hits": 12395,
      "accounts_affected": 7657,
      "inconsistency_start": "2022-01-01",
      "inconsistency_end": "2022-05-01",
      "id": "Portfolio-Type-1",
      "category": "Inconsistencies in account characteristics",
      "description": "Account type does not match the portfolio type, Line of Credit",
      "long_description": "Account type does not match the portfolio type, Line of Credit.\n\nPortfolio type: C (Credit)\nAccount type≠ 15 (Line of credit), 43 (Debit card), 47 (Credit Line Secured), 89 (Home equity line of credit), 7A (Commercial Line of Credit ), 9B (Business Line Personally Guaranteed)",
      "fields_used": [
        "port_type",
        "acct_type"
      ],
      "fields_display": [],
      "crrg_reference": "",
      "potential_harm": "",
      "rationale": "",
      "alternate_explanation": "",
      "interpret_fields_last_modified": null,
      "additional_notes": "",
      "additional_notes_last_modified": null
    }
  ]
}

Users view

If SSO is enabled: /api/users/

If SSO is not enabled: /api/users/{user_id}/

GET - returns a JSON that includes a list of all events that the user has permission to view, as well as their username and admin status

Example response:

{
    "is_admin": true,
    "username": "jane.doe",
    "assigned_events": [
        {
            "id": 1,
            "name": "Hyundai2024",
            "portfolio": "credit cards",
            "eid_or_matter_num": "456-1123445",
            "other_descriptor": "",
            "date_range_start": "2023-11-30",
            "date_range_end": "2023-12-31"
        },
        # ... etc.
    ]
}

Version view

/api/version/

GET - returns the application version.

The version is set by passing the VERSION argument to the container image build. The compose file in this repository will set this to the current git SHA by default.

Example response:

{
    "version": "d4121f0950b392382949cbde230511ccbb03256d"
}

Clone this wiki locally