# Attributes
Source: https://docs.methodfi.com/2026-03-30/guides/additional-products/attributes

Structured financial metrics for insights and recommendations.

Attributes provide structured financial metrics derived from an Entity's linked accounts. Rather than giving you raw account data, Attributes distill the information into actionable categories that your product can use to generate insights, recommendations, and personalized guidance.

## Entity vs Account Attributes

Attributes are available at two levels:

* **Entity Attributes:** Aggregated across all of an Entity's connected accounts. Use `POST /entities/{ent_id}/attributes` to compute them. Available as a Product (on-demand) or Subscription (continuous updates via webhooks).
* **Account Attributes:** Per-account metrics for a single Account. Use `POST /accounts/{acc_id}/attributes`. Available as a Product (on-demand) or Subscription (continuous updates via webhooks).

This means you can show a user their overall credit utilization AND the utilization on each individual credit card.

## How It Works

Attribute requests are asynchronous. When you create an Attributes request, you'll receive an immediate response with `status: "in_progress"` and `attributes: null`. Once processing completes, the status updates to `completed` and the `attributes` object is populated. Use webhooks or poll the retrieve endpoint to get the final result.

Each attribute in the response is an object with a `value` field and an `error` field. If an attribute couldn't be computed (for example, insufficient historical data for a 60-day trend), `value` will be `null` and `error` will contain details about why.

```json theme={null}
{
  "credit_card_utilization": {
    "value": 11.96,
    "error": null,
    "metadata": null
  },
  "revolving_credit_card_balance_change_60d": {
    "value": null,
    "error": {
      "type": "ENTITY_ATTRIBUTE_INSUFFICIENT_DATA",
      "code": 27001,
      "message": "Insufficient data to compute this entity attribute."
    },
    "metadata": null
  }
}
```

## Available Categories

Entity Attributes span six categories:

* **Revolving Credit Card:** Balances, credit limits, utilization, weighted average APR, usage patterns, minimum payments, delinquency flags, and 30/60/90-day balance and utilization trends.
* **Personal Loan:** Balances, original loan amounts, estimated monthly installments, utilization, weighted average APR, and 30/60/90-day trends.
* **Mortgage:** Balances, original loan amounts, weighted average APR, and 30/60/90-day trends.
* **Overall:** Cross-category totals for original loan amounts, overall utilization, and 30/60/90-day utilization trends.
* **Installment:** Total installment balance and 30/60/90-day balance changes.
* **Other:** Balances and trends for account types not covered above.

Account Attributes vary by the account's liability type (credit card, personal loan, mortgage, auto loan, or student loan). Requesting attributes for an unsupported account type returns a `400` error.

## Quick Start

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/attributes \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const attribute = await method
    .entities('ent_au22b1fbFJbp8')
    .attributes
    .create();
  ```

  ```python Python theme={null}
  attribute = method
    .entities('ent_au22b1fbFJbp8')
    .attributes
    .create()
  ```
</CodeGroup>

## Error Handling

Request-level errors (the Attributes request itself fails):

* `PRODUCT_UNAVAILABLE`: The Entity doesn't support Attributes.
* `TEAM_CAPABILITY_RESTRICTED`: Your team doesn't have access to Attributes.
* `PRODUCT_VERIFICATION_MISSING`: Entity must be verified first.
* `PRODUCT_RESTRICTED_CONNECT_REQUIRED`: Entity must have a completed Connect record.

Attribute-level errors (individual attributes within a successful response):

* `ENTITY_ATTRIBUTE_INSUFFICIENT_DATA`: Not enough historical data to compute this attribute.
* `ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA`: Same, for Account-level attributes.

For your product, Attributes enable features like credit health dashboards, personalized recommendations ("Your credit card utilization is high, consider paying down Card X first"), progress tracking over time, and educational content tied to the user's actual situation.

<Card title="Attributes API Reference" icon="chart-pie" href="/2026-03-30/reference/entities/attributes/overview">
  Full API documentation for Entity and Account Attributes.
</Card>


# Application, Qualification & Repricing
Source: https://docs.methodfi.com/2026-03-30/guides/use-cases/lending/application-prefill

Prefill loan applications with verified liability data, pre-qualify borrowers before the long form, and run CLI / repricing on real-time liability data.

## Application Prefill

*Replaces manual debt entry in loan applications.*

From the applicant's name and phone, Method discovers their full liability picture via soft credit pull, fetches real-time balances, and feeds them straight into the application form wherever you ask the user to type their debts. For auto refi flows, Vehicle enrichment adds make, model, year, and VIN alongside the auto loan balance.

### How it works

The applicant enters name and phone, IDV verifies identity, Connect performs a soft credit pull to discover all liabilities, Account-Update fetches current balances, and (for auto refi) Vehicles enriches each auto loan. The application form arrives pre-populated wherever debts would be typed. All monetary values are in **cents** (`320000` = \$3,200.00).

<Steps>
  <Step title="Create the Entity">
    `POST /entities`. Providing `ssn_4` and `dob` significantly improves match rates during account discovery.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/entities \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{
          "type": "individual",
          "individual": {
            "first_name": "James",
            "last_name": "Rodriguez",
            "phone": "+12125550456",
            "email": "james.rodriguez@email.com",
            "dob": "1989-03-22",
            "ssn_4": "5678"
          },
          "address": {
            "line1": "456 Oak Ave",
            "city": "Brooklyn",
            "state": "NY",
            "zip": "11201"
          }
        }'
      ```
    </Expandable>
  </Step>

  <Step title="Verify the phone with BYO SMS">
    `POST /entities/{ent_id}/verification_sessions`. Assert a phone number you already verified in your own onboarding by passing the ISO 8601 timestamp of when you verified it. BYO SMS requires your team to be pre-authorized, so contact your Method CSM to enable it.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/verification_sessions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "type": "phone", "method": "byo_sms", "byo_sms": { "timestamp": "2026-03-30T12:00:00.000Z" } }'
      ```
    </Expandable>
  </Step>

  <Step title="Soft-pull credit report via Connect">
    `POST /entities/{ent_id}/connect`. Discovers every liability on the bureau file in a single call. No score impact.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/connect \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "cxn_4ewMmBbjYDMR4",
        "entity_id": "ent_qKNBB68bfHGNA",
        "status": "completed",
        "accounts": [
          "acc_WqNhMRNVZjbKg",
          "acc_TmGPLxkz7Nrh6",
          "acc_RkFqVbD8HjQxP",
          "acc_YXDrjADGjC76U",
          "acc_KpLnWzFt9Mjd3"
        ]
      }
      ```
    </Expandable>
  </Step>

  <Step title="Pull real-time data for each account">
    `POST /accounts/{acc_id}/updates`. Current balance, APR, due dates, and minimum payment direct from the FI.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_WqNhMRNVZjbKg/updates \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "upt_FKr8mV4hQzTpN",
        "status": "completed",
        "account_id": "acc_WqNhMRNVZjbKg",
        "type": "credit_card",
        "credit_card": {
          "available_credit": 480000,
          "balance": 320000,
          "credit_limit": 800000,
          "interest_rate_percentage_max": 24.99,
          "next_payment_due_date": "2025-10-01",
          "next_payment_minimum_amount": 8900,
          "usage_pattern": "revolver"
        }
      }
      ```
    </Expandable>
  </Step>

  <Step title="(Auto refi) Enrich auto loans with vehicle details">
    `POST /entities/{ent_id}/vehicles`. Returns VIN, year, make, model, style alongside the loan balance.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/vehicles \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "evhl_QnT4mKxBfVpJ8",
        "entity_id": "ent_qKNBB68bfHGNA",
        "vehicles": [{
          "vin": "7FARW2H83ME012345",
          "year": "2021",
          "make": "honda",
          "model": "cr-v",
          "style": "sport_utility_vehicle"
        }],
        "status": "completed"
      }
      ```
    </Expandable>
  </Step>
</Steps>

## Pre-qualification

Give borrowers an instant "yes, you qualify" before they invest time in the full application. Method facilitates the soft pull, your decisioning logic returns a qualify or not-yet, and only qualified applicants advance to the long form.

### How it works

Same upstream flow as Prefill (Entity → verify phone → Connect), with credit-health attributes feeding the eligibility decision. Applicants who pass drop into a Prefill-populated long form. Applicants who don't qualify never enter it.

<Steps>
  <Step title="Create and verify the Entity, then run Connect">
    Same calls as Prefill above. Connect returns the discovered accounts and, importantly, signals that the soft pull completed without a score impact.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/connect \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```
    </Expandable>
  </Step>

  <Step title="Pull credit-health attributes for the decision">
    `POST /entities/{ent_id}/attributes`. Method computes the full attribute set (utilization, balances, APRs, trends, payment behavior, delinquency flags) automatically, no selector needed in v2. The endpoint is asynchronous: the initial response is `in_progress` with `attributes: null`. Subscribe to webhooks (`entity_attribute.create`) or poll the retrieve endpoint for the completed result.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/attributes \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "attr_dADraNgLBrhgL",
        "entity_id": "ent_qKNBB68bfHGNA",
        "status": "completed",
        "attributes": {
          "credit_card_utilization":          { "value": 38.0, "error": null, "metadata": null },
          "overall_utilization":              { "value": 70.5, "error": null, "metadata": null },
          "usage_pattern":                    { "value": "revolver", "error": null, "metadata": null },
          "weighted_average_apr_credit_card": { "value": 24.99, "error": null, "metadata": null },
          "payment_to_minimum_ratio_avg_credit_cards": { "value": 1.92, "error": null, "metadata": null },
          "delinquency_flag_credit_cards":    { "value": "on_time", "error": null, "metadata": null }
        }
      }
      ```
    </Expandable>
  </Step>
</Steps>

Your decision engine evaluates these (plus any model features layered on top) and returns qualify / not-yet. Qualified applicants drop into the Prefill flow.

## Credit Limit Increase (CLI) / Repricing

*Better terms or higher lines for approved customers, on Method liability data.*

For approved customers only. Use Method's real-time liability data to offer better terms or a higher credit line. It works two ways:

1. In real-time, second look: if Method data shows significant divergence from bureau data (e.g. the borrower's real-time utilization is 10% lower) then you can leverage this data to offer improved rates and terms.
2. On-demand: if a borrower requests a line extension, you can check Method's real-time data to determine eligibility.

### How it works

Two flows share the same underlying data. In the real-time flow, funded loans are enrolled in Update + Credit Score Subscriptions, and improvement signals fire as webhook events. In the on-demand flow, the customer requests a CLI and the lender pulls the current liability picture in real time.

**Real-time flow**

<Steps>
  <Step title="Enroll funded-loan accounts in Update Subscriptions">
    `POST /accounts/{acc_id}/subscriptions` with `enroll: update`. Delivers near-real-time balance and payment data as the FI reports changes.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_TmGPLxkz7Nrh6/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "update" }'
      ```
    </Expandable>
  </Step>

  <Step title="Enroll the entity in Credit Score Subscriptions">
    `POST /entities/{ent_id}/subscriptions` with `enroll: credit_score`. Fires when the score crosses thresholds you care about. When Method detects new update data, you receive a webhook pointing at the new update.

    <Expandable title="request & webhook">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "credit_score" }'
      ```

      ```json theme={null}
      {
        "id": "whk_Rm4nPqTx8LjWv",
        "type": "update.update",
        "path": "/accounts/acc_TmGPLxkz7Nrh6/updates/upt_Hx9mRnKw3PfTq"
      }
      ```
    </Expandable>
  </Step>
</Steps>

**On-demand flow**

<Steps>
  <Step title="Pull a fresh update when the customer requests a CLI">
    `POST /accounts/{acc_id}/updates`. Size the upgrade against verified, real-time data rather than bureau lag.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_WqNhMRNVZjbKg/updates \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```
    </Expandable>
  </Step>
</Steps>

## What's Next

<CardGroup>
  <Card title="Direct Pay" icon="money-bill-transfer" href="/2026-03-30/guides/use-cases/lending/debt-consolidation">
    Disburse loan proceeds straight to creditors and turn direct payoff into a pricing lever.
  </Card>

  <Card title="Portfolio Intelligence" icon="chart-line" href="/2026-03-30/guides/use-cases/lending/portfolio-monitoring">
    Monitor borrower liability, utilization, and delinquency signals continuously after origination.
  </Card>
</CardGroup>


# Direct Pay
Source: https://docs.methodfi.com/2026-03-30/guides/use-cases/lending/debt-consolidation

Disburse loan proceeds straight to creditors at funding, and turn direct payoff into a top-of-funnel pricing lever.

## Direct Pay

*Consolidate or transfer at funding.*

Send the money straight to the creditor. Borrowers can't redirect, fraud goes down, loan performance goes up, and your consolidation product actually does what it says. Method handles the full payment lifecycle: submission, processing, delivery to the creditor, confirmation.

### How it works

After Connect discovers the borrower's debts, your underwriting selects which to pay off, fresh balances confirm the disbursement amount, and Payments route directly to each creditor from your corporate funding account. Amounts are in **cents** (`320000` = \$3,200.00).

<Steps>
  <Step title="Confirm the destination supports payments">
    `GET /accounts/{acc_id}`. Only accounts with `payment` in their `products` array can receive a Method-routed payment. Accounts where `payment` appears only in `restricted_products` (e.g., FedLoan, Rocket Mortgage) provide data via `balance` and `update`, but disbursement to those servicers needs to happen through other rails.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_WqNhMRNVZjbKg \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "acc_WqNhMRNVZjbKg",
        "type": "liability",
        "liability": { "type": "credit_card", "name": "Chase Freedom Flex Credit Card" },
        "products": ["balance", "update", "payment"],
        "restricted_products": ["sensitive"]
      }
      ```
    </Expandable>
  </Step>

  <Step title="Pull a fresh balance just before disbursing">
    `POST /accounts/{acc_id}/updates`. Balances can shift daily between application and funding.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_WqNhMRNVZjbKg/updates \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```
    </Expandable>
  </Step>

  <Step title="Disburse loan proceeds directly to the creditor">
    `POST /payments`. The source is your corporate funding account; the destination is the borrower's liability account. The `description` field is limited to **10 characters**: use labels like `Payoff`, `Paydown`, `Consolidat`, `EDP Payoff`. Method fires webhooks as the payment moves through `pending → processing → sent → posted`. After posting, an Update on the destination account verifies the balance decreased as expected.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/payments \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{
          "amount": 320000,
          "source": "acc_hmap9mbgfLcf9",
          "destination": "acc_WqNhMRNVZjbKg",
          "description": "Payoff"
        }'
      ```

      ```json theme={null}
      {
        "id": "pmt_Qm4RnKx8Wb",
        "source": "acc_hmap9mbgfLcf9",
        "destination": "acc_WqNhMRNVZjbKg",
        "amount": 320000,
        "description": "Payoff",
        "status": "pending",
        "estimated_completion_date": "2025-09-22",
        "source_settlement_date": "2025-09-16",
        "destination_settlement_date": "2025-09-22",
        "destination_payment_method": "electronic"
      }
      ```
    </Expandable>
  </Step>
</Steps>

## Direct Pay rate discount

*Offer a better rate before the borrower commits, backed by a payoff you control.*

When a borrower chooses to have their consolidation loan sent straight to their creditors, the loan is materially safer, and that risk reduction funds a lower APR you can surface at the very top of the funnel. Method turns direct payoff into a pricing lever at the top of the funnel. The pattern has three parts, and Method powers each one:

* During the no-impact **rate check**, Method discovers the borrower's real, payable debt, so you know there is genuine debt to retire and what rate they're actually paying on it.
* That lets you confidently **offer an enhanced rate** to borrowers who opt to have funds disbursed directly to their creditors, rather than taken as cash.
* At funding, **Direct Pay executes the payoff**, so the discount you promised upfront is backed by an action you control, not by the borrower's intent to pay their balances down themselves.

This is already a visible market pattern. One large personal-loan originator presents two products on its rate-check screen (a debt-consolidation loan and a general-purpose cash loan) and advertises an APR discount of up to 5% on the consolidation product, available specifically when the borrower lets the lender pay their existing creditors directly. The same screen reassures the borrower that checking their rate will not affect their credit score. Method powers both halves of that experience: the soft-pull rate check, and the verified payoff that earns the discount.

### Why direct payoff earns a better rate

A traditional consolidation loan disburses cash to the borrower and trusts them to retire their balances. Many don't, or they pay down some and re-spend the rest, leaving the lender with a borrower who now carries both the new loan and the old revolving debt. Routing proceeds straight to each creditor removes that leakage: the targeted debt is actually retired, the borrower can't redirect the funds, and downstream delinquency falls. Consolidated payoffs sent directly to the creditor reduce delinquency by up to \~50% versus cash-to-borrower disbursement. That loss reduction is what you price into the upfront discount.

There's a structural reason this can't be priced off bureau data alone. Traditional bureau files cannot confirm a borrower's live revolving balance, the rate they're actually paying today, or that loan proceeds reached the creditor. A discount priced on a weeks-old snapshot carries uncertainty on all three. Method removes it by reading current balances and APRs directly from each institution and by settling the payoff itself.

All examples use `Method-Version: 2026-03-30`. Monetary values are in **cents** (`1840000` = \$18,400.00); APRs and utilization are percentages.

### How it works

Run a no-impact rate check that discovers the borrower's real, payable debt, size and price the direct-payoff discount against it, confirm each creditor account can receive a payment, then execute the payoff at funding.

<Steps>
  <Step title="Create the Entity">
    `POST /entities`. Start with the borrower record. In this environment you only need `first_name`, `last_name`, and `phone`. Passing `dob` and `ssn_4` when available improves match rates during discovery.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{
          "type": "individual",
          "individual": {
            "first_name": "Maya",
            "last_name": "Chen",
            "phone": "+13105550147"
          }
        }'
      ```

      ```json theme={null}
      { "id": "ent_BzirqpLEm3BW7", "type": "individual", "status": "incomplete" }
      ```
    </Expandable>
  </Step>

  <Step title="Run the soft-pull rate check">
    `POST /entities/{ent_id}/connect`. This is the "won't impact your credit score" promise: Connect performs a soft credit pull (no score impact) and discovers every liability on the borrower's file, returning an account ID for each. List the accounts (`GET /accounts?holder_id={ent_id}&type=liability&status=active`) to see the borrower's live revolving and installment debt, the raw material for the consolidation offer.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/connect \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "cxn_4ewMmBbjYDMR4",
        "entity_id": "ent_BzirqpLEm3BW7",
        "status": "completed",
        "accounts": ["acc_WqNhMRNVZjbKg", "acc_TmGPLxkz7Nrh6", "acc_YXDrjADGjC76U"],
        "error": null
      }
      ```
    </Expandable>
  </Step>

  <Step title="Size the opportunity and price the discount">
    `POST /entities/{ent_id}/attributes`. Pull the entity attribute set to quantify the consolidation opportunity. The blended APR and revolving balance tell you how much the borrower stands to save. That, combined with the risk reduction direct payoff delivers, is what you price the enhanced offer against. This borrower carries \$18,400 in revolving balances at a 23.4% blended APR. A standard consolidation offer at, say, 14% already cuts their monthly interest sharply. Layering the direct-payoff discount on top (an additional reduction of up to 5% APR) both deepens their savings and lowers your expected loss, because the payoff will actually happen.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/attributes \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "attr_Qk9nPmRw3LjTx",
        "entity_id": "ent_BzirqpLEm3BW7",
        "status": "completed",
        "attributes": {
          "revolving_credit_card_balance_total":       { "value": 1840000, "error": null, "metadata": null },
          "weighted_average_apr_credit_card":          { "value": 23.4, "error": null, "metadata": null },
          "credit_card_utilization":                   { "value": 63.0, "error": null, "metadata": null },
          "usage_pattern":                             { "value": "revolver", "error": null, "metadata": null },
          "payment_to_minimum_ratio_avg_credit_cards": { "value": 1.6, "error": null, "metadata": null }
        }
      }
      ```
    </Expandable>

    *Key attributes:* `weighted_average_apr_credit_card`, `revolving_credit_card_balance_total`, `credit_card_utilization`, `usage_pattern`, `payment_to_minimum_ratio_avg_credit_cards`.
  </Step>

  <Step title="Confirm payable destinations">
    `GET /accounts/{acc_id}`. Before you promise to pay a balance directly, confirm the creditor account can receive a Method-routed payment. Only accounts with `payment` in their `products` array are payable. Some servicers expose data via `balance` and `update` but must be paid through other rails.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_WqNhMRNVZjbKg \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "acc_WqNhMRNVZjbKg",
        "type": "liability",
        "liability": { "type": "credit_card", "name": "Chase Freedom Flex Credit Card" },
        "products": ["balance", "update", "payment"],
        "restricted_products": ["sensitive"]
      }
      ```
    </Expandable>
  </Step>

  <Step title="Execute the direct payoff at funding">
    `POST /payments`. When the borrower accepts the direct-payoff option and the loan funds, route proceeds straight to each creditor. The source is your corporate funding account; the destination is the borrower's creditor account. Pull a fresh `POST /accounts/{acc_id}/updates` first so you disburse the exact current balance. The `description` field is limited to **10 characters**: use labels like `Payoff`, `Paydown`, `Consolidat`. Repeat the call once per creditor being retired. Method fires webhooks as each payment moves through `pending → processing → sent → posted`. An Update on the destination afterward confirms the balance dropped as expected.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/payments \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{
          "amount": 1840000,
          "source": "acc_hmap9mbgfLcf9",
          "destination": "acc_WqNhMRNVZjbKg",
          "description": "Payoff"
        }'
      ```

      ```json theme={null}
      {
        "id": "pmt_Qm4RnKx8Wb",
        "source": "acc_hmap9mbgfLcf9",
        "destination": "acc_WqNhMRNVZjbKg",
        "amount": 1840000,
        "description": "Payoff",
        "status": "pending",
        "estimated_completion_date": "2026-06-12",
        "source_settlement_date": "2026-06-06",
        "destination_settlement_date": "2026-06-12"
      }
      ```
    </Expandable>
  </Step>
</Steps>

### Structuring the offer

A few principles that keep the discount defensible and the experience clean:

* **Tier the discount to the verified opportunity.** The enhanced rate is funded by real loss reduction, so size it against the debt that will actually be retired, not a flat promotional number.
* **Make the discount conditional on direct payoff.** Present the standard rate and the enhanced rate side by side; the borrower unlocks the better APR by choosing to have you pay their creditors. This mirrors the market example: a consolidation product carries the discount, a general cash loan does not.
* **Support the "extra cash" case.** Borrowers who want to consolidate and take additional cash still qualify: route the payoff portion through Direct Pay and disburse the remainder as cash. The discount applies to the consolidated portion, since that's the part whose risk you've removed.
* **Back the promise at funding.** The upfront rate is credible precisely because Direct Pay settles the payoff for you. Wire the payoff call to fire automatically on funding so the discount and the disbursement stay in lockstep.


# Getting Started
Source: https://docs.methodfi.com/2026-03-30/guides/use-cases/lending/getting-started

Create an entity, verify identity, and discover all liabilities for a loan applicant.

Every lending integration follows the same three-step setup: represent your applicant as an Entity, verify their identity, and discover their complete liability picture. This guide walks through each step with full API calls for a loan applicant named James Rodriguez.

As a lender, the goal of this flow is to go from a name and phone number to a complete view of everything the applicant owes (credit cards, auto loans, student loans, personal loans, and mortgages) in a single session. This is the foundation for DTI calculations, underwriting decisions, and eventual loan disbursement.

<Steps>
  <Step title="Create the Entity">
    Start by creating an Entity with the applicant's PII. For lending use cases, providing more identity data (SSN last 4, date of birth, address) significantly improves match rates during account discovery.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{
          "type": "individual",
          "individual": {
            "first_name": "James",
            "last_name": "Rodriguez",
            "phone": "+12125550456",
            "email": "james.rodriguez@email.com",
            "dob": "1989-03-22",
            "ssn_4": "5678"
          },
          "address": {
            "line1": "456 Oak Ave",
            "line2": null,
            "city": "Brooklyn",
            "state": "NY",
            "zip": "11201"
          }
        }'
      ```

      ```json theme={null}
      {
        "id": "ent_qKNBB68bfHGNA",
        "type": "individual",
        "individual": {
          "first_name": "James",
          "last_name": "Rodriguez",
          "phone": "+12125550456",
          "dob": "1989-03-22",
          "email": "james.rodriguez@email.com",
          "ssn_4": "5678",
          "ssn": null
        },
        "error": null,
        "address": {
          "line1": "456 Oak Ave",
          "line2": null,
          "city": "Brooklyn",
          "state": "NY",
          "zip": "11201"
        },
        "status": "incomplete",
        "verification": {
          "identity": {
            "verified": false,
            "matched": false,
            "latest_verification_session": null,
            "methods": [
              "element",
              "byo_kyc"
            ]
          },
          "phone": {
            "verified": false,
            "latest_verification_session": null,
            "methods": [
              "sna",
              "byo_sms"
            ]
          }
        },
        "connect": null,
        "credit_score": null,
        "products": [
          "identity"
        ],
        "restricted_products": [
          "connect",
          "credit_score",
          "attribute"
        ],
        "subscriptions": [],
        "available_subscriptions": [
          "connect",
          "credit_score"
        ],
        "restricted_subscriptions": [],
        "metadata": null,
        "created_at": "2025-09-15T14:22:31.424Z",
        "updated_at": "2025-09-15T14:22:31.424Z"
      }
      ```
    </Expandable>

    The Entity is created with `status: "incomplete"`. The applicant still needs to verify their identity before Method can discover their accounts.

    <Note>
      Including `ssn_4` and `dob` at entity creation gives Method more data points to match against credit bureau records during Connect, which improves account discovery rates.
    </Note>
  </Step>

  <Step title="Verify Identity">
    Before Method can pull the applicant's credit data, you need to verify their identity. This is a [two-step process](/guides/identity-verification/overview): first verify the phone number, then verify the person's identity.

    <Note>
      For lending flows where you already verify the applicant in your own onboarding, BYO SMS and BYO KYC let you assert those results to Method in a single call each. Both require your team to be pre-authorized, so contact your Method CSM to enable them.
    </Note>

    **Step 1 - Phone verification (BYO SMS):**

    If you already verify phone numbers in your own onboarding, use BYO SMS to assert that result to Method. Pass the ISO 8601 timestamp of when you verified the number.

    <Expandable title="phone verification request">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/verification_sessions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{
          "type": "phone",
          "method": "byo_sms",
          "byo_sms": {
            "timestamp": "2026-03-30T12:00:00.000Z"
          }
        }'
      ```
    </Expandable>

    **Step 2 - Identity verification (BYO KYC):**

    With the phone verified, assert your own KYC result with BYO KYC. By creating this session you're confirming that your external KYC process passed for this applicant. Method trusts your KYC result, with no constraints on which vendor you use.

    <Expandable title="identity verification request">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/verification_sessions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{
          "type": "identity",
          "method": "byo_kyc",
          "byo_kyc": {}
        }'
      ```
    </Expandable>

    The response includes `byo_kyc: { authenticated: true }`, confirming the verification was recorded.

    **After both steps, the Entity is active:**

    <Expandable title="active entity response">
      ```json theme={null}
      {
        "id": "ent_qKNBB68bfHGNA",
        "type": "individual",
        "individual": {
          "first_name": "James",
          "last_name": "Rodriguez",
          "phone": "+12125550456",
          "dob": "1989-03-22",
          "email": "james.rodriguez@email.com",
          "ssn_4": "5678",
          "ssn": null
        },
        "error": null,
        "address": {
          "line1": "456 Oak Ave",
          "line2": null,
          "city": "Brooklyn",
          "state": "NY",
          "zip": "11201"
        },
        "status": "active",
        "verification": {
          "identity": {
            "verified": true,
            "matched": true,
            "latest_verification_session": "evf_Rm7kLnXw4PjTq",
            "methods": []
          },
          "phone": {
            "verified": true,
            "latest_verification_session": "evf_P4QXNj93Y9J8L",
            "methods": []
          }
        },
        "connect": null,
        "credit_score": null,
        "products": [
          "identity",
          "connect",
          "credit_score",
          "attribute"
        ],
        "restricted_products": [],
        "subscriptions": [],
        "available_subscriptions": [
          "connect",
          "credit_score"
        ],
        "restricted_subscriptions": [],
        "metadata": null,
        "created_at": "2025-09-15T14:22:31.424Z",
        "updated_at": "2025-09-15T14:23:48.106Z"
      }
      ```
    </Expandable>

    Notice that `connect`, `credit_score`, and `attribute` have moved from `restricted_products` to `products`. The applicant is now eligible for account discovery.

    The Entity's `products` and `restricted_products` arrays indicate which platform capabilities are unlocked based on the entity's verification status. Before verification, most products are restricted. After verification, they unlock. You'll see a similar pattern at the account level: each discovered account has its own `products` array that reflects what Method can do with that specific liability, based on Method's coverage of the creditor.
  </Step>

  <Step title="Connect Liabilities">
    With the Entity verified, call Connect to discover all of the applicant's liability accounts via a soft credit pull (no impact to their credit score).

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/connect \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "cxn_4ewMmBbjYDMR4",
        "entity_id": "ent_qKNBB68bfHGNA",
        "status": "completed",
        "accounts": [
          "acc_WqNhMRNVZjbKg",
          "acc_nPvJM9KXRwQE4",
          "acc_TmGPLxkz7Nrh6",
          "acc_RkFqVbD8HjQxP",
          "acc_YXDrjADGjC76U",
          "acc_KpLnWzFt9Mjd3"
        ],
        "requested_products": [],
        "requested_subscriptions": [],
        "error": null,
        "created_at": "2025-09-15T14:24:12.339Z",
        "updated_at": "2025-09-15T14:24:12.339Z"
      }
      ```
    </Expandable>

    Method discovered 6 liability accounts across multiple creditors. Each account ID maps to a specific debt obligation. You can retrieve any account to see its liability details:

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_WqNhMRNVZjbKg \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "acc_WqNhMRNVZjbKg",
        "holder_id": "ent_qKNBB68bfHGNA",
        "status": "active",
        "type": "liability",
        "liability": {
          "mch_id": "mch_183",
          "mask": "4021",
          "ownership": "primary",
          "fingerprint": "8a3c91f2b7e4d6a0c5f1e8b3d9a7c4f2e6b0d8a1",
          "type": "credit_card",
          "sub_type": "flexible_spending",
          "name": "Chase Freedom Flex Credit Card"
        },
        "latest_verification_session": null,
        "update": null,
        "balance": null,
        "card_brand": null,
        "payment_instrument": null,
        "products": ["balance", "update", "payment"],
        "restricted_products": ["sensitive"],
        "subscriptions": [],
        "available_subscriptions": ["update", "update.snapshot"],
        "restricted_subscriptions": [],
        "error": null,
        "metadata": null,
        "created_at": "2025-09-15T14:24:12.339Z",
        "updated_at": "2025-09-15T14:24:12.542Z"
      }
      ```
    </Expandable>

    **Understanding Account Products**

    The `products` array tells you what Method can do with this account. Each discovered account comes with a `products` list and a `restricted_products` list based on the account type and Method's coverage for that merchant:

    | Product     | What it means                                                                                                   |
    | ----------- | --------------------------------------------------------------------------------------------------------------- |
    | `balance`   | Retrieve the current balance for this account (from credit report data).                                        |
    | `update`    | Pull real-time data (current balance, APR, due dates, payment amounts) directly from the financial institution. |
    | `payment`   | Send payments to this account through Method. Method has a payment rail to this creditor.                       |
    | `sensitive` | Access full account numbers. Gated, requires additional account verification.                                   |

    If `payment` is in `products`, Method has payment coverage for this merchant and you can route funds to this account. If it's in `restricted_products` or absent entirely, payments aren't available for this account.

    This distinction matters most for lending workflows. If your product involves paying off a borrower's existing debts (debt consolidation, enforced paydown), you need `payment` in the account's `products` array for each target account. Accounts without `payment` coverage can still provide data for underwriting and DTI calculations via `balance` and `update`, but disbursement to those creditors would need to happen through your own payment rails.

    Compare the Chase card above with the FedLoan student loan, which has different product availability:

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_RkFqVbD8HjQxP \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "acc_RkFqVbD8HjQxP",
        "holder_id": "ent_qKNBB68bfHGNA",
        "status": "active",
        "type": "liability",
        "liability": {
          "mch_id": "mch_302451",
          "mask": "7892",
          "ownership": "primary",
          "fingerprint": "d4f2a8c1e6b0d9a3c7f5e2b8d1a4c6f0e3b9d7a2",
          "type": "student_loan",
          "sub_type": "federal",
          "name": "FedLoan Student Loan"
        },
        "latest_verification_session": null,
        "update": null,
        "balance": null,
        "card_brand": null,
        "payment_instrument": null,
        "products": ["balance", "update"],
        "restricted_products": ["payment", "sensitive"],
        "subscriptions": [],
        "available_subscriptions": ["update", "update.snapshot"],
        "restricted_subscriptions": [],
        "error": null,
        "metadata": null,
        "created_at": "2025-09-15T14:24:12.339Z",
        "updated_at": "2025-09-15T14:24:12.542Z"
      }
      ```
    </Expandable>

    This account's `products` array contains `balance` and `update` but not `payment`. Method can pull real-time data from FedLoan, but payment routing to this servicer isn't currently available.

    The applicant's discovered accounts represent the following debts:

    | Account ID          | Creditor            | Type          | Estimated Balance | Available Products       |
    | ------------------- | ------------------- | ------------- | ----------------- | ------------------------ |
    | `acc_WqNhMRNVZjbKg` | Chase Freedom Flex  | Credit Card   | \$3,200           | balance, update, payment |
    | `acc_nPvJM9KXRwQE4` | Discover it         | Credit Card   | \$1,800           | balance, update, payment |
    | `acc_TmGPLxkz7Nrh6` | Toyota Motor Credit | Auto Loan     | \$18,450          | balance, update, payment |
    | `acc_RkFqVbD8HjQxP` | FedLoan             | Student Loan  | \$34,200          | balance, update          |
    | `acc_YXDrjADGjC76U` | Upstart             | Personal Loan | \$12,000          | balance, update, payment |
    | `acc_KpLnWzFt9Mjd3` | Rocket Mortgage     | Mortgage      | \$245,000         | balance, update          |

    This is the complete liability picture you need for DTI calculations and underwriting. Four of the six accounts support `payment`, meaning Method can route funds directly to those creditors. The remaining two (FedLoan and Rocket Mortgage) provide data through `balance` and `update` but don't currently support payment disbursement through Method.

    In the next guides, you'll see how to pull real-time balances via `update` and initiate payments to accounts that support it.
  </Step>
</Steps>

## What's Next

<CardGroup>
  <Card title="Application & Qualification" icon="clipboard-check" href="/2026-03-30/guides/use-cases/lending/application-prefill">
    Pull real-time account data and assess credit risk with Attributes.
  </Card>

  <Card title="Debt Consolidation" icon="money-bill-transfer" href="/2026-03-30/guides/use-cases/lending/debt-consolidation">
    Request payoff quotes and disburse funds directly to creditors.
  </Card>
</CardGroup>


# Lending
Source: https://docs.methodfi.com/2026-03-30/guides/use-cases/lending/overview

Full lifecycle from lead generation to portfolio monitoring.

Full lifecycle from lead generation to portfolio monitoring. Pre-screen, pre-fill, underwrite, disburse directly to creditors, and monitor the portfolio in real time.

## What this section covers

Method provides the infrastructure layer that digital lenders need to move from application intake through underwriting, loan funding, debt payoff, and post-funding monitoring, all through a single API layer. Instead of stitching together credit bureau pulls, payment rails, and account aggregation vendors, lending teams can use Method to power the entire lifecycle with real-time liability data and embedded payments.

This spans both unsecured and secured products (personal loans, credit cards, mortgages, HELOCs, and auto) across two motions on the same data fabric: origination (pre-qualification, offer sizing, and direct payoff at funding) and portfolio intelligence (continuous monitoring to surface refinance, HELOC, CLI, and cross-sell opportunities before borrowers shop elsewhere).

### The borrower journey

| Stage        | Use cases                                                     | Core endpoints                                                                                       |
| ------------ | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| Marketing    | Portfolio Intelligence                                        | Attributes                                                                                           |
| Application  | Prefill, Pre-qualification                                    | IDV, Entity-Connect, Account-Update, Vehicles, Attributes, Snapshot                                  |
| Underwriting | CLI / repricing                                               | IDV, Entity-Connect, Snapshot, Credit Score, Account-Update, Attributes, Subscriptions               |
| Disbursement | Direct Pay                                                    | Entity-Connect, Account-Update, Payments, Sensitive, Snapshot                                        |
| Servicing    | Portfolio Intelligence: Grow, Portfolio Intelligence: Protect | Account-Update, Update Subscriptions, Credit Score, Credit Score Subscriptions, Attributes, Snapshot |

## Where to go next

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="/2026-03-30/guides/use-cases/lending/getting-started">
    Create an entity, verify identity, and discover all liabilities for a loan applicant.
  </Card>

  <Card title="Application & Qualification" icon="clipboard-check" href="/2026-03-30/guides/use-cases/lending/application-prefill">
    Prefill applications, pre-qualify borrowers, and run CLI / repricing on real-time liability data.
  </Card>

  <Card title="Direct Pay" icon="money-bill-transfer" href="/2026-03-30/guides/use-cases/lending/debt-consolidation">
    Disburse loan proceeds straight to creditors and turn direct payoff into a pricing lever.
  </Card>

  <Card title="Portfolio Intelligence" icon="chart-line" href="/2026-03-30/guides/use-cases/lending/portfolio-monitoring">
    Monitor borrower liability, utilization, and delinquency signals continuously after origination.
  </Card>

  <Card title="Mortgage & HELOC" icon="house-chimney" href="/guides/use-cases/lending/mortgage-heloc">
    Qualify, size HELOC and refi offers, and target secured-lending customers on real-time data.
  </Card>
</CardGroup>


# Portfolio Intelligence
Source: https://docs.methodfi.com/2026-03-30/guides/use-cases/lending/portfolio-monitoring

Continuously monitor a borrower's liability profile after origination — balance trends, utilization shifts, and delinquency signals delivered via attributes and webhooks.

Portfolio Intelligence (PI) gives lenders a continuous, real-time view of a borrower's full liability profile after origination. When you enroll an Entity in Portfolio Intelligence, Method directly pulls data from the entity's linked financial institutions and makes the full attribute set available — both at the entity level (aggregated across all accounts) and at the individual account level.

This is distinct from on-demand attribute pulls. PI enrollment establishes an ongoing relationship: as balances change, payments post, and utilization shifts, those signals are captured and surfaced through the [Attributes](/2026-03-30/guides/additional-products/attributes) endpoint without requiring re-enrollment or repeat triggering.

<Note>
  Portfolio Intelligence is a separately enabled product. Contact your Method CSM to enable `portfolio_intelligence` on your environment.
</Note>

## How It Works

<Steps>
  <Step title="Enroll an Entity">
    Enrolling an entity in Portfolio Intelligence is a single API call: subscribe the entity to the `attribute` subscription and pass the `portfolio_intelligence` bundle name. The bundle expands to the full Portfolio Intelligence attribute set on the server — you don't need to list each attribute individually. Once enrolled, all accounts associated with that entity become eligible for attribute generation, so you don't need to enroll accounts separately.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{
          "enroll": "attribute",
          "payload": {
            "attributes": {
              "bundles": ["portfolio_intelligence"]
            }
          }
        }'
      ```
    </Expandable>

    For the full list of attributes the bundle expands to, see [Portfolio Intelligence](/2026-03-30/reference/entities/attributes/overview#portfolio-intelligence) in the reference. To enroll in the bundle plus additional individual attributes, combine `bundles` with `requested_attributes` in the same payload.

    <Expandable title="response">
      ```json theme={null}
      {
        "id": "sub_Tm8qNnLx5RjWk",
        "name": "attribute",
        "status": "active",
        "payload": null,
        "latest_request_id": null,
        "created_at": "2026-04-09T17:00:12.218Z",
        "updated_at": "2026-04-09T17:00:12.218Z"
      }
      ```
    </Expandable>

    Once `status` is `active`, Method begins pulling data directly from the entity's financial institutions and attribute generation begins.
  </Step>

  <Step title="Receive Entity-Level Attributes">
    Entity-level attributes aggregate signals across all of the entity's accounts — a holistic view of the borrower's total debt burden, payment behavior, and utilization trajectory. As of `2026-03-30`, the Attributes endpoint is asynchronous and automatically computes all available attributes (no request body needed). Trigger a fresh computation with:

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/attributes \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```
    </Expandable>

    The request returns immediately with `status: "in_progress"`:

    <Expandable title="initial response">
      ```json theme={null}
      {
        "id": "attr_Qk9nPmRw3LjTx",
        "entity_id": "ent_qKNBB68bfHGNA",
        "status": "in_progress",
        "attributes": null,
        "error": null,
        "created_at": "2026-04-09T17:02:47.910Z",
        "updated_at": "2026-04-09T17:02:47.910Z"
      }
      ```
    </Expandable>

    When processing completes, Method fires an `entity_attribute.update` webhook. Retrieve the completed attribute object via [GET /entities/\{ent\_id}/attributes/\{attr\_id}](/2026-03-30/reference/entities/attributes/retrieve). A completed response includes every attribute enrolled via `requested_attributes`. Attributes that could not be computed return `value: null` with an `error` object (e.g. `ENTITY_ATTRIBUTE_INSUFFICIENT_DATA`):

    <Expandable title="completed response">
      ```json theme={null}
      {
        "id": "attr_Qk9nPmRw3LjTx",
        "entity_id": "ent_qKNBB68bfHGNA",
        "status": "completed",
        "attributes": {
          "revolving_credit_card_balance_total": { "value": 1420000, "error": null, "metadata": null },
          "credit_limit_total": { "value": 3800000, "error": null, "metadata": null },
          "credit_card_utilization": { "value": 37.4, "error": null, "metadata": null },
          "weighted_average_apr_credit_card": { "value": 22.1, "error": null, "metadata": null },
          "usage_pattern": { "value": "revolver", "error": null, "metadata": null },
          "next_payment_minimum_total_credit_cards": { "value": 35000, "error": null, "metadata": null },
          "payment_to_minimum_ratio_avg_credit_cards": { "value": 1.4, "error": null, "metadata": null },
          "revolving_credit_card_balance_change_30d": { "value": -185000, "error": null, "metadata": null },
          "revolving_credit_card_balance_change_60d": {
            "value": null,
            "error": {
              "type": "ENTITY_ATTRIBUTE_INSUFFICIENT_DATA",
              "sub_type": "ENTITY_ATTRIBUTE_INSUFFICIENT_DATA",
              "code": 27001,
              "message": "Insufficient data to compute this entity attribute."
            },
            "metadata": null
          },
          "revolving_credit_card_utilization_trend_30d": { "value": "down", "error": null, "metadata": null },
          "revolving_credit_card_utilization_delta_30d": { "value": -1.2, "error": null, "metadata": null },
          "delinquency_flag_credit_cards": { "value": false, "error": null, "metadata": null },
          "mortgage_balance_total": { "value": 15586300, "error": null, "metadata": null },
          "installment_balance_total": { "value": 23605200, "error": null, "metadata": null },
          "overall_loan_amount_total": { "value": 32000000, "error": null, "metadata": null },
          "overall_utilization": { "value": 45.3, "error": null, "metadata": null }
        },
        "error": null,
        "created_at": "2026-04-09T17:02:47.910Z",
        "updated_at": "2026-04-09T17:04:35.220Z"
      }
      ```
    </Expandable>

    A representative subset is shown above. Balance values are in cents; utilization is a percentage (`37.4` = 37.4%); deltas are percentage points; trends are enums (`up`, `down`, `flat`).

    In this example, the borrower is a revolver carrying \$14,200 in credit card debt against a \$38,000 limit — but the 30-day balance change of −\$1,850 and a declining utilization trend indicate active paydown. The `payment_to_minimum_ratio` of 1.4 confirms they are paying above the minimum, a positive behavioral signal.
  </Step>

  <Step title="Receive Account-Level Attributes">
    For drill-down analysis on a specific account, use the account-level attributes endpoint. This is useful for account-specific risk flags, targeted cross-sell logic, or when you need per-card detail rather than an aggregated entity view. Account-level attribute names are simplified (no type prefix) because the attributes returned depend on the account's liability type.

    <Expandable title="request & initial response">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_4m9amk4KFiaQX/attributes \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "acc_attr_Lp2mXwKn9RjTv",
        "account_id": "acc_4m9amk4KFiaQX",
        "status": "in_progress",
        "attributes": null,
        "error": null,
        "created_at": "2026-04-09T17:03:15.334Z",
        "updated_at": "2026-04-09T17:03:15.334Z"
      }
      ```
    </Expandable>

    Method fires an `account_attribute.update` webhook on completion. Retrieve the completed object via [GET /accounts/\{acc\_id}/attributes/\{acc\_attr\_id}](/2026-03-30/reference/accounts/attributes/retrieve). For a credit card account, the response includes the full set of credit-card-eligible attributes — attributes that can't be computed (e.g. trends/deltas with insufficient history) return `value: null` with an `ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA` error:

    <Expandable title="completed response">
      ```json theme={null}
      {
        "id": "acc_attr_Lp2mXwKn9RjTv",
        "account_id": "acc_4m9amk4KFiaQX",
        "status": "completed",
        "attributes": {
          "type": { "value": "credit_card", "error": null, "metadata": null },
          "usage_pattern": { "value": "revolver", "error": null, "metadata": null },
          "delinquency_flag": { "value": false, "error": null, "metadata": null },
          "utilization": { "value": 61, "error": null, "metadata": null },
          "utilization_trend_30d": { "value": "up", "error": null, "metadata": null },
          "utilization_trend_90d": {
            "value": null,
            "error": {
              "type": "ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA",
              "sub_type": "ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA",
              "code": 28001,
              "message": "Insufficient data to compute this account attribute."
            },
            "metadata": null
          },
          "utilization_delta_30d": { "value": 9, "error": null, "metadata": null },
          "utilization_delta_60d": {
            "value": null,
            "error": {
              "type": "ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA",
              "sub_type": "ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA",
              "code": 28001,
              "message": "Insufficient data to compute this account attribute."
            },
            "metadata": null
          },
          "utilization_delta_90d": {
            "value": null,
            "error": {
              "type": "ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA",
              "sub_type": "ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA",
              "code": 28001,
              "message": "Insufficient data to compute this account attribute."
            },
            "metadata": null
          }
        },
        "error": null,
        "created_at": "2026-04-09T17:03:15.334Z",
        "updated_at": "2026-04-09T17:05:10.220Z"
      }
      ```
    </Expandable>

    Even if the entity's aggregate utilization looks healthy, this account is at 61% and climbing (`utilization_delta_30d` of +9 percentage points) — a risk signal that would be masked by entity-level aggregation alone. Personal loan and mortgage accounts return a different attribute set — see the [reference](/2026-03-30/reference/accounts/attributes/overview) for the per-liability-type breakdown.
  </Step>
</Steps>

## Monitoring Use Cases

### Delinquency Early Warning

Portfolio Intelligence detects delinquency signals 30–45 days faster than bureau-only approaches, because direct sync reflects the account state within roughly one week of the missed payment event — before the lender reports to the bureau.

Watch for:

* `delinquency_flag_credit_cards` → `true` (entity) or `delinquency_flag` → `true` (account)
* `revolving_credit_card_utilization_delta_30d` > +30 (30+ pp rapid accumulation)
* `payment_to_minimum_ratio_avg_credit_cards` approaching 1.0 (paying only minimums)
* `usage_pattern` shifting from `transactor` to `revolver`

### Credit Line Increase Eligibility

A borrower demonstrating sustained paydown is a CLI candidate. Trigger a review when:

* `revolving_credit_card_balance_change_90d` is negative (consistent paydown)
* `revolving_credit_card_utilization_delta_90d` \< −20 (20+ pp improvement)
* `credit_card_utilization` drops below your threshold (e.g., \< 30)
* `payment_to_minimum_ratio_avg_credit_cards` > 2.0

### Refinance & Consolidation Retargeting

When a borrower's debt profile improves post-origination, use PI attributes to surface them for a new offer:

* `weighted_average_apr_credit_card` reveals the blended rate on outstanding revolving debt
* `monthly_installments_estimate_personal_loans` calculates real-dollar savings at your offered rate
* `revolving_credit_card_balance_change_30d` confirms they're actively managing their debt

For example, a borrower with \$18,400 in credit card debt at a weighted APR of 22.1% has a `monthly_installments_estimate` of \~\$340/month. Your 9.5% personal loan offer reduces that to \~\$190 — a \$150/month savings you can surface in a targeted campaign.

## Attribute Availability by Level

Some attributes are only meaningful in aggregate and are available at the entity level only. Others can be computed per-account.

| Category         | Attribute                                      | Entity | Account |
| ---------------- | ---------------------------------------------- | :----: | :-----: |
| Core Balances    | `revolving_credit_card_balance_total`          |    ✓   |    —    |
|                  | `personal_loan_balance_total`                  |    ✓   |    —    |
|                  | `mortgage_balance_total`                       |    ✓   |    —    |
|                  | `installment_balance_total`                    |    ✓   |    —    |
|                  | `revolving_credit_card_balance_change_30d`     |    ✓   |    —    |
|                  | `revolving_credit_card_balance_change_60d`     |    ✓   |    —    |
|                  | `revolving_credit_card_balance_change_90d`     |    ✓   |    —    |
| Utilization      | `credit_card_utilization`                      |    ✓   |    ✓    |
|                  | `personal_loan_utilization`                    |    ✓   |    ✓    |
|                  | `overall_utilization`                          |    ✓   |    —    |
|                  | `revolving_credit_card_utilization_trend_30d`  |    ✓   |    ✓    |
|                  | `revolving_credit_card_utilization_trend_90d`  |    ✓   |    ✓    |
|                  | `revolving_credit_card_utilization_delta_30d`  |    ✓   |    ✓    |
|                  | `revolving_credit_card_utilization_delta_60d`  |    ✓   |    ✓    |
|                  | `revolving_credit_card_utilization_delta_90d`  |    ✓   |    ✓    |
|                  | `overall_utilization_trend_30d`                |    ✓   |    —    |
|                  | `overall_utilization_delta_30d`                |    ✓   |    —    |
|                  | `credit_limit_total`                           |    ✓   |    —    |
| Payment Behavior | `usage_pattern`                                |    ✓   |    ✓    |
|                  | `payment_to_minimum_ratio_avg_credit_cards`    |    ✓   |    —    |
|                  | `next_payment_minimum_total_credit_cards`      |    ✓   |    —    |
| Delinquency      | `delinquency_flag_credit_cards`                |    ✓   |    ✓    |
| APR              | `weighted_average_apr_credit_card`             |    ✓   |    —    |
|                  | `weighted_average_apr_personal_loan`           |    ✓   |    —    |
|                  | `weighted_average_apr_mortgage`                |    ✓   |    —    |
| Opportunity      | `monthly_installments_estimate_personal_loans` |    ✓   |    ✓    |

<Note>
  Attributes marked entity-only require cross-account aggregation and cannot be computed for a single account in isolation.
</Note>

## Webhooks

Method fires a webhook when an Attribute request completes or updated data is available for a PI-enrolled entity or account. Use these to trigger monitoring workflows without polling.

**Entity Attribute Webhook:**

```json theme={null}
{
  "id": "whk_Rm4nPqTx8LjWv",
  "type": "entity_attribute.update",
  "path": "/entities/ent_qKNBB68bfHGNA/attributes/attr_Qk9nPmRw3LjTx"
}
```

**Account Attribute Webhook:**

```json theme={null}
{
  "id": "whk_Wn5qPmRx6KjTv",
  "type": "account_attribute.update",
  "path": "/accounts/acc_4m9amk4KFiaQX/attributes/acc_attr_Lp2mXwKn9RjTv"
}
```

The `.create` variants (`entity_attribute.create`, `account_attribute.create`) fire once on initial computation, and `.update` fires thereafter whenever PI surfaces new values for a PI-enrolled entity or account.

## Putting It All Together

| Monitoring goal          | Endpoint           | Key attributes                                                                               |
| ------------------------ | ------------------ | -------------------------------------------------------------------------------------------- |
| Total debt exposure      | Entity attributes  | `revolving_credit_card_balance_total`, `installment_balance_total`, `mortgage_balance_total` |
| Debt trajectory          | Entity attributes  | `revolving_credit_card_balance_change_30d/60d/90d`                                           |
| Utilization health       | Entity + Account   | `credit_card_utilization`, `revolving_credit_card_utilization_trend_30d`                     |
| Payment behavior         | Entity attributes  | `usage_pattern`, `payment_to_minimum_ratio_avg_credit_cards`                                 |
| Delinquency detection    | Entity + Account   | `delinquency_flag_credit_cards` (entity), `delinquency_flag` (account)                       |
| Refinance opportunity    | Entity attributes  | `weighted_average_apr_credit_card`, `monthly_installments_estimate_personal_loans`           |
| Account-level drill-down | Account attributes | Any account-eligible attribute from the table above                                          |

<CardGroup>
  <Card title="Attributes Guide" icon="chart-pie" href="/2026-03-30/guides/additional-products/attributes">
    Full list of available attributes, how they're computed, and endpoint details.
  </Card>

  <Card title="Subscriptions Guide" icon="bell" href="/guides/updates/subscriptions">
    Deep dive into subscription types and webhook payloads.
  </Card>

  <Card title="Entity Attributes API" icon="code" href="/2026-03-30/reference/entities/attributes/create">
    API reference for pulling entity-level attributes.
  </Card>

  <Card title="Lending Overview" icon="arrow-left" href="/2026-03-30/guides/use-cases/lending/overview">
    Return to the lending use case overview.
  </Card>
</CardGroup>


# Authentication
Source: https://docs.methodfi.com/2026-03-30/reference/authentication



Method supports two ways to authenticate requests: **API keys** and **OAuth 2.0 client
credentials**. Both are sent as a Bearer token in the `Authorization` header of every request, and
both resolve to the same team, so the rest of the API behaves identically.

|            | API keys                         | OAuth                                                                                |
| ---------- | -------------------------------- | ------------------------------------------------------------------------------------ |
| Credential | A long-lived secret key (`sk_…`) | A `client_id` and `client_secret` exchanged for a short-lived access token (`oat_…`) |
| Expiry     | Never expires                    | Access tokens expire after 1 hour                                                    |
| Access     | Full access to your team         | Constrained to the scopes granted to your client                                     |
| Setup      | Copy the key from the Dashboard  | Create a client, then implement the token exchange                                   |

Use an API key to get started quickly, or where a single trusted service calls Method. Use OAuth
when you want short-lived credentials that expire on their own, or when you want to restrict an
integration to a subset of the API.

## API keys

An API key identifies your team. Secret API keys have the prefix `sk_`, and your team has a separate
key for each [environment](/2026-03-30/reference/environments). Keys are available under the Keys section in the
[Method Dashboard](https://dashboard.methodfi.com), where you can also rotate them.

API keys do not expire and carry full access to your team, so treat them as sensitive credentials:
store them in a secrets manager, never in client-side code or version control.

Get started by creating your account in the [Method Dashboard](https://dashboard.methodfi.com) or
[connect](https://methodfi.com/contact-us) with our team.

## OAuth

Method supports [OAuth 2.0 Client Credentials](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4)
as an alternative to API keys. You exchange a `client_id` and `client_secret` for a short-lived
access token, then use that token on API requests in place of an API key.

1. Create an OAuth client in the [Method Dashboard](https://dashboard.methodfi.com) to get a `client_id` and `client_secret`.
2. Exchange them at `POST /oauth/token` for an access token, valid for 1 hour.
3. Call the Method API with `Authorization: Bearer <access_token>`.
4. When the token expires, request a new one the same way.

### Credentials

| Credential      | Format  | Notes                                                                                     |
| --------------- | ------- | ----------------------------------------------------------------------------------------- |
| `client_id`     | `ocl_…` | Identifies your integration. Not a secret. Safe to log and reference in support requests. |
| `client_secret` | `ocs_…` | Shown exactly once at issuance. Store it in a secrets manager. Method cannot retrieve it. |

Clients and secrets are managed under the OAuth section in the
[Method Dashboard](https://dashboard.methodfi.com), where you can mint new
secrets and disable existing ones. Each environment has its own clients and secrets.

<Warning>
  If you lose a `client_secret`, mint a new one from the Dashboard. Method cannot recover the original value.
</Warning>

### Getting an access token

Send a `POST` request to `/oauth/token` with a `application/x-www-form-urlencoded` body containing
`grant_type=client_credentials`. Authenticate with your client credentials using either HTTP Basic
auth or the request body.

<CodeGroup>
  ```bash HTTP Basic auth theme={null}
  curl https://production.methodfi.com/oauth/token \
    -u "ocl_AbC123:ocs_XYZ456" \
    -d "grant_type=client_credentials"
  ```

  ```bash Credentials in body theme={null}
  curl https://production.methodfi.com/oauth/token \
    -d "grant_type=client_credentials" \
    -d "client_id=ocl_AbC123" \
    -d "client_secret=ocs_XYZ456"
  ```
</CodeGroup>

HTTP Basic auth is recommended, and is the default for most OAuth client libraries. Use the base
URL for your [environment](/2026-03-30/reference/environments).

```json theme={null}
{
  "access_token": "oat_7Hk94r83482csdcK2mQx9vTz",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "entities:read entities:write accounts:read"
}
```

| Field          | Description                                       |
| -------------- | ------------------------------------------------- |
| `access_token` | The bearer token (`oat_…`). Treat it as a secret. |
| `token_type`   | Always `Bearer`.                                  |
| `expires_in`   | Lifetime in seconds (3600 = 1 hour).              |
| `scope`        | Space-delimited scopes this token carries.        |

### Token endpoint errors

The token endpoint uses the standard OAuth error format rather than the Method error envelope.

```json theme={null}
{ "error": "invalid_client", "error_description": "Client authentication failed." }
```

| HTTP | `error`                  | Cause                                                            |
| ---- | ------------------------ | ---------------------------------------------------------------- |
| 400  | `invalid_request`        | Missing or malformed parameters, such as an absent `grant_type`. |
| 400  | `unsupported_grant_type` | A `grant_type` other than `client_credentials`.                  |
| 400  | `invalid_scope`          | Requested scope not granted to your client.                      |
| 401  | `invalid_client`         | Client authentication failed.                                    |
| 429  | `too_many_requests`      | Rate limit exceeded. Retry after the `Retry-After` header.       |

### Scopes

Scopes follow `<resource>:<action>`, where the action maps to the HTTP method:

| HTTP method                      | Action  |
| -------------------------------- | ------- |
| `GET`                            | `read`  |
| `POST`, `PUT`, `PATCH`, `DELETE` | `write` |

For example, `entities:read` allows `GET /entities/…` and `entities:write` allows `POST /entities`.

Your client is granted a set of scopes by Method. By default a token carries all of them. To
request a token with fewer scopes, pass a space-delimited `scope` parameter:

```bash theme={null}
curl https://production.methodfi.com/oauth/token \
  -u "ocl_AbC123:ocs_XYZ456" \
  -d "grant_type=client_credentials" \
  -d "scope=entities:read accounts:read"
```

Requesting a scope your client has not been granted returns `400 invalid_scope`.

### Calling the API with an access token

Send the access token in the `Authorization` header. Everything else about the API is unchanged.

```bash theme={null}
curl https://production.methodfi.com/entities \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer oat_7Hk94r83482csdcK2mQx9vTz"
```

Two errors are specific to token-based requests:

* **401** — the token is missing, invalid, expired, or revoked. Request a new token and retry.
* **403** with `sub_type: INSUFFICIENT_SCOPE` — the token does not carry the scope this endpoint requires.

```json theme={null}
{
  "success": false,
  "data": {
    "error": {
      "type": "INVALID_REQUEST",
      "code": 403,
      "sub_type": "INSUFFICIENT_SCOPE",
      "message": "Your access token is missing the required scope 'entities:write' for POST /entities."
    }
  },
  "message": "Your access token is missing the required scope 'entities:write' for POST /entities."
}
```

### Token lifecycle

* **Cache the token** and reuse it for its full lifetime. Do not request a new token per API call.
* **Renew shortly before expiry**, for example 60 seconds early, to avoid a `401` at the boundary.
  On an unexpected `401`, request a new token once and retry.
* **There are no refresh tokens.** This is by design for the client credentials grant
  ([RFC 6749 §4.4.3](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4.3)). Renewal is the
  same `POST /oauth/token` call again.

<Note>
  The token endpoint is [rate limited](/2026-03-30/reference/rate-limiting).
</Note>

### Secret rotation

Rotate your `client_secret` from the [Method Dashboard](https://dashboard.methodfi.com) for
routine rotation or suspected exposure. Your `client_id` never changes.

1. Mint a new secret. Both the new and existing secrets remain valid.
2. Deploy the new secret on your own schedule, with no downtime.
3. Disable the old secret once you have confirmed cutover.

If a secret is compromised, disable it immediately.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const { Method, Environments } = require('method-node');

  const method = new Method({
    apiKey: 'sk_WyZEWVfTcH7GqmPzUPk65Vjc',
    env: Environments.production,
  });

  const accounts = await method.accounts.list();
  ```

  ```python Python theme={null}
  from method import Method

  method = Method(env='production', api_key='sk_WyZEWVfTcH7GqmPzUPk65Vjc')

  accounts = method.accounts.list()
  ```
</RequestExample>


# Create a Corporation
Source: https://docs.methodfi.com/2026-03-30/reference/entities/create-corporation

POST /entities

Creates a new corporation Entity. An Entity can be created with an empty object and progressively updated with more information from your end user.

<Note>Entities are not checked for existing duplicate Entities.</Note>

## Body

<ParamList />

## Returns

Returns the newly created Entity.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "corporation",
      "corporation": {
        "name": "Alphabet Inc.",
        "dba": "Google",
        "ein": "641234567",
        "owners": [
          {
            "first_name": "Sergey",
            "last_name": "Brin",
            "phone": "+16505555555",
            "email": "sergey@google.com",
            "dob": "1973-08-21",
            "address": {
              "line1": "600 Amphitheatre Parkway",
              "line2": null,
              "city": "Mountain View",
              "state": "CA",
              "zip": "94043"
            }
          }
        ]
      },
      "address": {
        "line1": "1600 Amphitheatre Parkway",
        "line2": null,
        "city": "Mountain View",
        "state": "CA",
        "zip": "94043"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const entity = await method.entities.create({
    type: 'corporation',
    corporation: {
      name: 'Alphabet Inc.',
      dba: 'Google',
      ein: '641234567',
      owners: [
        {
          first_name: 'Sergey',
          last_name: 'Brin',
          phone: '+16505555555',
          email: 'sergey@google.com',
          dob: '1973-08-21',
          address: {
            line1: '600 Amphitheatre Parkway',
            line2: null,
            city: 'Mountain View',
            state: 'CA',
            zip: '94043',
          },
        },
      ],
    },
    address: {
      line1: '1600 Amphitheatre Parkway',
      line2: null,
      city: 'Mountain View',
      state: 'CA',
      zip: '94043',
    },
  });
  ```

  ```python Python theme={null}
  entity = method.entities.create({
    'type': 'corporation',
    'corporation': {
      'name': 'Alphabet Inc.',
      'dba': 'Google',
      'ein': '641234567',
      'owners': [
        {
          'first_name': 'Sergey',
          'last_name': 'Brin',
          'phone': '+16505555555',
          'email': 'sergey@google.com',
          'dob': '1973-08-21',
          'address': {
            'line1': '600 Amphitheatre Parkway',
            'line2': None,
            'city': 'Mountain View',
            'state': 'CA',
            'zip': '94043'
          }
        }
      ]
    },
    'address': {
      'line1': '1600 Amphitheatre Parkway',
      'line2': None,
      'city': 'Mountain View',
      'state': 'CA',
      'zip': '94043'
    }
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "ent_A6bmTtFmxQhGQ",
    "type": "corporation",
    "corporation": {
      "name": "Alphabet Inc.",
      "dba": "Google",
      "ein": "641234567",
      "owners": [
        {
          "first_name": "Sergey",
          "last_name": "Brin",
          "phone": "+16505555555",
          "email": "sergey@google.com",
          "dob": "1973-08-21",
          "address": {
            "line1": "600 Amphitheatre Parkway",
            "line2": null,
            "city": "Mountain View",
            "state": "CA",
            "zip": "94043"
          }
        }
      ]
    },
    "error": null,
    "address": {
      "line1": "1600 Amphitheatre Parkway",
      "line2": null,
      "city": "Mountain View",
      "state": "CA",
      "zip": "94043"
    },
    "status": "active",
    "metadata": null,
    "created_at": "2023-10-24T21:26:17.225Z",
    "updated_at": "2023-10-24T21:26:17.225Z"
  }
  ```
</ResponseExample>


# Create an Individual
Source: https://docs.methodfi.com/2026-03-30/reference/entities/create-individual

POST /entities

Creates a new individual Entity. An Entity can be created with an empty object
and progressively updated with more information from your end user.

<Note>Entities are not checked for existing duplicate Entities.</Note>

## Body

<ParamList />

## Returns

Returns the newly created Entity.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "individual",
      "individual": {
        "first_name": "Kevin",
        "last_name": "Doyle",
        "phone": "+15121231113",
        "email": "kevin.doyle@gmail.com",
        "dob": "1997-03-18"
      },
      "address": {
        "line1": "3300 N Interstate 35",
        "line2": null,
        "city": "Austin",
        "state": "TX",
        "zip": "78705"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const entity = await method.entities.create({
    type: "individual",
    individual: {
      first_name: "Kevin",
      last_name: "Doyle",
      phone: "+15121231113",
      email: "kevin.doyle@gmail.com",
      dob: "1997-03-18",
    },
    address: {
      line1: "3300 N Interstate 35",
      line2: null,
      city: "Austin",
      state: "TX",
      zip: "78705",
    },
  });
  ```

  ```python Python theme={null}
  entity = method.entities.create({
    'type': 'individual',
    'individual': {
      'first_name': 'Kevin',
      'last_name': 'Doyle',
      'phone': '+15121231113',
      'email': 'kevin.doyle@gmail.com',
      'dob': '1997-03-18',
    },
    'address': {
      'line1': '3300 N Interstate 35',
      'line2': None,
      'city': 'Austin',
      'state': 'TX',
      'zip': '78705'
    }
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "ent_BzirqpLEm3BW7",
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15121231113",
      "dob": "1997-03-18",
      "email": "kevin.doyle@gmail.com",
      "ssn_4": null,
      "ssn": null
    },
    "error": null,
    "address": {
      "line1": "3300 N Interstate 35",
      "line2": null,
      "city": "Austin",
      "state": "TX",
      "zip": "78705"
    },
    "status": "incomplete",
    "verification": {
      "identity": {
        "verified": false,
        "matched": false,
        "latest_verification_session": null,
        "methods": [
          "element",
          "kba"
        ]
      },
      "phone": {
        "verified": true,
        "latest_verification_session": "evf_P4QXNj93Y9J8L",
        "methods": []
      }
    },
    "connect": null,
    "credit_score": null,
    "products": [
      "identity"
    ],
    "restricted_products": [
      "connect",
      "credit_score",
      "attribute"
    ],
    "subscriptions": [],
    "available_subscriptions": [
      "connect",
      "credit_score"
    ],
    "restricted_subscriptions": [],
    "metadata": null,
    "created_at": "2023-10-24T21:50:53.024Z",
    "updated_at": "2023-10-24T21:50:53.024Z"
  }
  ```
</ResponseExample>


# The entity endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/entities/overview



Entities are a representation of your application's end-users (individuals or corporations). Throughout
Method's ecosystem, an `Entity` is the legal owner of an [Account](/2026-03-30/reference/accounts/overview), and is the primary object for many of Method's API endpoints.

<Note>
  Entities should be persisted with a 1:1 relationship throughout the lifecycle
  of your end-user.
</Note>

#### PII Requirements

`Entity` PII requirements are pre-defined during onboarding based on your team's specific use case. Entities require at a minimum name + phone number for most services.
Some `Products` and `Subscriptions` may require additional information to be provided to Method to enable certain features. Contact your Method CSM for more information.

## Entity Objects

<Tabs>
  <Tab title="Individual">
    <ParamList />

    <ExpandableFieldsList />

    <ParamList />
  </Tab>

  <Tab title="Corporation">
    <ParamList />
  </Tab>
</Tabs>

## Webhook Payload

The [Webhook](/2026-03-30/reference/webhooks/overview) payload will contain the following information:

```json theme={null}
{
  "id": "string",
  "type": "entity.create" | "entity.update",
  "path": "/entities/<ent_id>",
  "event": "<evt_id>"
}
```

<RequestExample>
  ```json Individual theme={null}
  {
    "id": "ent_BzirqpLEm3BW7",
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15121231113",
      "dob": "1997-03-18",
      "email": "kevin.doyle@gmail.com",
      "ssn_4": "xxxx",
      "ssn": "xxxxxxxxx"
    },
    "error": null,
    "address": {
      "line1": "3300 N Interstate 35",
      "line2": null,
      "city": "Austin",
      "state": "TX",
      "zip": "78705"
    },
    "status": "incomplete",
    "verification": {
      "identity": {
        "verified": false,
        "matched": false,
        "latest_verification_session": null,
        "methods": [
          "element",
          "kba"
        ]
      },
      "phone": {
        "verified": true,
        "latest_verification_session": "evf_P4QXNj93Y9J8L",
        "methods": []
      }
    },
    "connect": null,
    "credit_score": null,
    "attribute": null,
    "vehicle": null,
    "products": [
      "identity"
    ],
    "restricted_products": [
      "credit_score",
      "connect",
      "attribute",
      "vehicle"
    ],
    "subscriptions": [],
    "available_subscriptions": [],
    "restricted_subscriptions": [
      "connect",
      "credit_score"
    ],
    "metadata": null,
    "created_at": "2023-10-24T21:50:53.024Z",
    "updated_at": "2023-10-24T21:50:53.024Z"
  }
  ```

  ```json Corporation theme={null}
  {
    "id": "ent_A6bmTtFmxQhGQ",
    "type": "corporation",
    "corporation": {
      "name": "Alphabet Inc.",
      "dba": "Google",
      "ein": "641234567",
      "owners": [
        {
          "first_name": "Sergey",
          "last_name": "Brin",
          "phone": "+16505555555",
          "email": "sergey@google.com",
          "dob": "1973-08-21",
          "address": {
            "line1": "600 Amphitheatre Parkway",
            "line2": null,
            "city": "Mountain View",
            "state": "CA",
            "zip": "94043"
          }
        }
      ]
    },
    "error": null,
    "address": {
      "line1": "1600 Amphitheatre Parkway",
      "line2": null,
      "city": "Mountain View",
      "state": "CA",
      "zip": "94043"
    },
    "status": "active",
    "metadata": null,
    "created_at": "2023-10-24T21:26:17.225Z",
    "updated_at": "2023-10-24T21:26:17.225Z"
  }
  ```
</RequestExample>


# Environments
Source: https://docs.methodfi.com/2026-03-30/reference/environments



Method has three primary API environments. Development, Sandbox, and Production share similar functionality
with minor differences. All building should be done in the Development and Sandbox environments.
All activity in Production will be billed. Your team will have separate API keys for each Method
environment. Keys are available under the Keys section in
the [Method Dashboard](https://dashboard.methodfi.com).

Development, Sandbox, and Production share similar functionality with minor differences
listed below. All merchant data is the same across all environments.

#### Development

We recommend building your integration in the `Development` environment. All data and payments are mocked.

#### Sandbox

We recommend switching to `Sandbox` once you are ready to test your integration with live data.

* Entities: Limited to a pre-defined whitelist. Contact your Method CSM to set up / modify your sandbox whitelist.
* Payments: 20 transactions / month (\$1 limit / transaction)
* Products / Subscriptions: Limited to your contracted products and subscriptions. All endpoints are live and will perform real data and money movement.

#### Production

Go live with your Method integration with unlimited live payments; all requests are billed.

<RequestExample>
  ```bash API Hosts theme={null}
  https://dev.methodfi.com (Development)
  https://sandbox.methodfi.com (Sandbox)
  https://production.methodfi.com (Production)
  ```
</RequestExample>


# Account Attribute Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/account-attribute-errors



## Request Errors

The request to the `/accounts/{acc_id}/attributes` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `PRODUCT_UNAVAILABLE`

This Account does not support retrieving Account's attributes.

### `PRODUCT_UNAVAILABLE_ACCOUNT_NOT_ACTIVE`

The Account is not active, so Attributes cannot be retrieved.

### `PRODUCT_UNAVAILABLE_INVALID_LIABILITY_TYPE`

Attributes are not supported for this liability type.

### `TEAM_CAPABILITY_RESTRICTED`

Your organization does not have access to Attributes endpoint.

***

## Resource Errors

### `24001 – PRODUCT_EXECUTION_FAILED`

The Attributes request failed to execute.

```json theme={null}
{
  "type": "PRODUCT_EXECUTION_FAILED",
  "code": 24001,
  "sub_type": "PRODUCT_EXECUTION_FAILED",
  "message": "Product execution failed."
}
```

## Attribute Value Errors

Errors set on an individual attribute's `error` field when a value cannot be computed.

### `28001 – ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA`

There is insufficient data to compute this attribute (for example, not enough history for a trend attribute). The attribute's `value` will be `null`.

```json theme={null}
{
  "type": "ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA",
  "code": 28001,
  "sub_type": "ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA",
  "message": "Insufficient data to compute this account attribute."
}
```


# Account Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/account-errors



## Request Errors

The request to the `/accounts/{acc_id}` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `INVALID_HOLDER_ID`

The provided `holder_id` does not match an existing entity.

### `ACCOUNT_CONSENT_ALREADY_WITHDRAWN`

Consent for this account has already been withdrawn.

### `ACCOUNT_CONSENT_ALREADY_GRANTED`

Consent for this account has already been granted.

### `ACCOUNT_HAS_PAYMENT_IN_PROGRESS`

Consent for this account cannot be withdrawn as it has one or more associated payments in progress.

### `ENTITY_CANNOT_PERFORM_ACTION`

The holder Entity is disabled and cannot perform the requested action.

### `INVALID_ACCOUNT_DETAILS`

The liability details provided are invalid.

### `INVALID_PRODUCTS_OR_SUBSCRIPTIONS`

The request references products or subscriptions that are invalid for this Account.

### `INVALID_ROUTING_NUMBER`

The routing number provided is invalid.

### `ACCOUNT_DATA_SYNC_UNAVAILABLE`

The Account is missing the `data:sync` capability.

### `ACCOUNT_HOLDER_MISSING_CAPABILITY`

The Account's holder Entity must have the `data:sync` capability.

### `CARD_FIELDS_INVALID_FOR_SENSITIVE`

The fields provided are not valid for card sensitive data.

### `CARD_TYPE_NOT_SUPPORTED`

The card type is not supported for this operation.

### `CARD_UNSUPPORTED_FOR_ACCOUNT_TYPE`

Cards are not supported for this account type.

### `CLOSED_ACCOUNT_CANNOT_BE_REACTIVATED`

Closed accounts cannot be reactivated, except for student loans.

### `EXISTING_ACCOUNT_DISABLED`

An existing account with the same information has been disabled. Contact Method support to resolve this issue.

### `INVALID_ACH_ACCOUNT_NUMBER`

The ACH account number is invalid. Account numbers should only contain digits.

### `INVALID_ACH_ACCOUNT_ROUTING`

The ACH routing number is invalid. Routing numbers should only contain digits.

### `INVALID_ACH_ACCOUNT_TYPE`

The ACH account type is invalid. Valid types are `checking` and `savings`.

### `INVALID_HOLDER_TYPE`

Only `individual` Entities can hold liability accounts.

### `INVALID_TEAM_FBO`

The `team_fbo_account_id` provided is not an open FBO account for your team.

### `INVALID_TEST_ACCOUNT`

The account details provided belong to a fake test account. Only use real accounts in live environments (sandbox / production).

### `MAX_ACCOUNT_METADATA_SIZE_EXCEEDED`

The maximum metadata object size of 1KB was exceeded.

***

## Resource Errors

Errors set on an Account's `error` property for processes that are unsuccessful.

### `11001 – ACCOUNT_INVALID_DETAILS`

The details on the Account are invalid as reported by the FI.

#### Causes

* Incorrect Account information - the account number or routing number is incorrect.
* The Account could not be located.

```json theme={null}
{
  "type": "ACCOUNT_DISABLED",
  "code": 11001,
  "sub_type": "ACCOUNT_INVALID_DETAILS",
  "message": "Account was disabled due to invalid information reported by the financial institution."
}
```

#### Resolution

The Account will be disabled and all its capabilities will be removed.

***

### `11002 – ACCOUNT_UNAUTHORIZED_PAYMENT`

The holder of the Account did not authorize a payment.

#### Causes

* A payment was stopped by the Account holder because they didn't authorize the payment.

```json theme={null}
{
  "type": "ACCOUNT_DISABLED",
  "code": 11002,
  "sub_type": "ACCOUNT_UNAUTHORIZED_PAYMENT",
  "message": "Account was disabled due to a payment reported as unauthorized by the financial institution."
}
```

#### Resolution

The account will be disabled and all its capabilities will be removed.

***

### `11003 – ACCOUNT_CLOSED`

The Account has been closed.

#### Causes

* Account is closed.

```json theme={null}
{
  "type": "ACCOUNT_DISABLED",
  "code": 11003,
  "sub_type": "ACCOUNT_CLOSED",
  "message": "Account was disabled due to a closure in the underlying bank account."
}
```

#### Resolution

The account will be disabled and all its capabilities will be removed.

***

### `11004 – ACCOUNT_CONSENT_WITHDRAWN`

The holder of the Account withdrew consent.

#### Causes

* Account consent was withdrawn.

```json theme={null}
{
  "type": "ACCOUNT_DISABLED",
  "code": 11004,
  "sub_type": "ACCOUNT_CONSENT_WITHDRAWN",
  "message": "Account was disabled due to consent withdrawal."
}
```

#### Resolution

The account will be disabled and all its capabilities will be removed.

***

### `11005 – ACCOUNT_DISABLED_INVALID_STATE`

The underlying liability is in an invalid state.

#### Causes

* The underlying liability is in an unexpected state.

```json theme={null}
{
  "type": "ACCOUNT_DISABLED",
  "code": 11005,
  "sub_type": "ACCOUNT_DISABLED_INVALID_STATE",
  "message": "Account was disabled due to an invalid state in the underlying liability."
}
```

#### Resolution

The account will be disabled and all its capabilities will be removed.

***

### `11006 – ACCOUNT_DISABLED_HOLDER_ENTITY_DISABLED`

The Account was disabled because its holder Entity was disabled.

#### Causes

* The Entity that holds this Account was disabled (for example, due to consent withdrawal or a failed verification).

```json theme={null}
{
  "type": "ACCOUNT_DISABLED",
  "code": 11006,
  "sub_type": "ACCOUNT_DISABLED_HOLDER_ENTITY_DISABLED",
  "message": "Account was disabled due to the holder entity being disabled."
}
```

#### Resolution

The Account will be disabled and all its capabilities will be removed. Resolve the holder Entity's status before reactivating the Account.


# Account Verification Session Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/account-verification-session-errors



## Request Errors

The request to the `/accounts/{acc_id}/verification_sessions` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `EXISTING_VERIFIED_SESSION`

The Account has already been verified.

### `EXISTING_VERIFICATION_SESSION`

The Account has an existing verification session.

### `VERIFICATION_SESSION_ATTEMPT_LIMIT_REACHED`

The verification session attempt limit has been reached.

***

### `VERIFICATION_MAX_LIMIT_BY_TYPE_REACHED`

The maximum number of attempts for this verification type has been reached.

### `VERIFICATION_MAX_TOTAL_LIMIT_REACHED`

The maximum number of attempts across all verification types has been reached.

### Legacy verification request errors

The following `sub_type` values are returned by the legacy `/accounts/{acc_id}/verification` endpoints.

### `EXISTING_VERIFICATION`

A verification already exists for this account.

### `INVALID_ACCOUNT_TYPE`

The Account must be of type `ach`.

### `INVALID_VERIFICATION_AMOUNTS`

The verification amounts provided are invalid.

### `INVALID_VERIFICATION_STATUS`

The verification must be in `pending` status.

### `INVALID_VERIFICATION_TYPE`

The verification type provided is invalid.

### `VERIFICATION_DISABLED`

Verification for this account has been disabled. You can no longer verify this account.

## Resource Errors

Errors set on an AccountVerificationSession's `error` property for processes that are unsuccessful.

### `16001 – VERIFICATION_TYPE_NOT_SUPPORTED`

The AccountVerificationSession has failed.

#### Causes

* The inputted verification type is not supported for the merchant.

```json theme={null}
{
  "type": "ACCOUNT_VERIFICATION_SESSION_FAILED",
  "code": 16001,
  "sub_type": "VERIFICATION_TYPE_NOT_SUPPORTED",
  "message": "The verification type provided is not supported for the merchant."
}
```

#### Resolution

* Initiate a new AccountVerificationSession with a supported type.

***

### `16002 – INVALID_DETAILS`

The AccountVerificationSession has failed due to incorrect details.

#### Causes

* The details required to pass verification was incorrect.

```json theme={null}
{
  "type": "ACCOUNT_VERIFICATION_SESSION_FAILED",
  "code": 16002,
  "sub_type": "INVALID_DETAILS",
  "message": "The provided details are invalid for the account."
}
```

#### Resolution

* Initiate a new AccountVerificationSession and verify the correct details is provided.

***

### `16003 – VERIFICATION_SESSION_ATTEMPT_LIMIT_REACHED`

The AccountVerificationSession has failed due to reaching maximum number of attempts for this session.

#### Causes

* Too many failed verification attempts for this session.

```json theme={null}
{
  "type": "ACCOUNT_VERIFICATION_SESSION_FAILED",
  "code": 16003,
  "sub_type": "VERIFICATION_SESSION_ATTEMPT_LIMIT_REACHED",
  "message": "The maximum number of attempts has been reached for this account verification session."
}
```

#### Resolution

* Initiate a new AccountVerificationSession.

***

### `16004 – MICRO_DEPOSITS_FAILED`

The AccountVerificationSession has failed due to invalid account information.

#### Causes

* Incorrect Account information - the account number or routing number is incorrect.
* The Account could not be located.

```json theme={null}
{
  "type": "ACCOUNT_VERIFICATION_SESSION_FAILED",
  "code": 16004,
  "sub_type": "MICRO_DEPOSITS_FAILED",
  "message": "The micro-deposits failed to verify due to invalid account information."
}
```

#### Resolution

* The verification session has failed and the Account will be disabled.

***

## Legacy Verification Resource Errors

Errors set on the legacy `/accounts/{acc_id}/verification` resource's `error` property.

### `13001 – ACCOUNT_VERIFICATION_ATTEMPT_LIMIT_REACHED`

The legacy account verification was disabled after reaching the maximum number of attempts.

```json theme={null}
{
  "type": "ACCOUNT_VERIFICATION_DISABLED",
  "code": 13001,
  "sub_type": "ACCOUNT_VERIFICATION_ATTEMPT_LIMIT_REACHED",
  "message": "Account verification was disabled due to the maximum verification limit (5) being reached."
}
```

### `13002 – ACCOUNT_VERIFICATION_DEPOSITS_FAILED`

The legacy account verification was disabled because micro-deposits failed.

```json theme={null}
{
  "type": "ACCOUNT_VERIFICATION_DISABLED",
  "code": 13002,
  "sub_type": "ACCOUNT_VERIFICATION_DEPOSITS_FAILED",
  "message": "Account verification was disabled due to the failure of micro-deposits to an invalid account."
}
```


# Balance Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/balance-errors



## Request Errors

The request to the `/accounts/{acc_id}/balances` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `PRODUCT_UNAVAILABLE`

This Account does not support Balance. This could be due to the Account's status
or Method currently doesn't support Balance for the Account's Financial Institution.

### `PRODUCT_UNAVAILABLE_ACCOUNT_NOT_ACTIVE`

The Account is not active, so a Balance cannot be retrieved.

### `TEAM_CAPABILITY_RESTRICTED`

Your organization does not have access to Balance endpoint.

### `PRODUCT_VERIFICATION_MISSING`

Account must be verified before it can access `/accounts/{acc_id}/balances` endpoint.

***

## Resource Errors

Errors set on a Balance's `error` property for processes that are unsuccessful.

### `20001 – BALANCE_TEMPORARILY_UNAVAILABLE`

There was an issue with connecting with the Account's Financial Institution and the request could not be completed.

```json theme={null}
{
  "type": "BALANCE_FAILED",
  "code": 20001,
  "sub_type": "BALANCE_TEMPORARILY_UNAVAILABLE",
  "message": "Balance is temporarily unavailable for this account."
}
```

***


# Card Brand Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/card-brand-errors



## Request Errors

The request to the `/accounts/{acc_id}/card_brands` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `PRODUCT_UNAVAILABLE`

This Account's liability type isn't a credit card or the credit card network isn't Visa, Mastercard, or Discover.

### `PRODUCT_UNAVAILABLE_ACCOUNT_NOT_ACTIVE`

The Account is not active, so a CardBrand cannot be retrieved.

### `TEAM_CAPABILITY_RESTRICTED`

Your organization does not have access to CardBrand endpoint.

***

***

## Resource Errors

Errors set on a CardBrand's `error` property when the asynchronous request is unsuccessful.

### `CARD_BRANDS_NOT_FOUND`

The card's brand could not be found or does not exist.


# Connect Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/connect-errors



## Request Errors

The request to the `/entities/{ent_id}/connect` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `PRODUCT_UNAVAILABLE_ENTITY_DISABLED`

The Entity is disabled, so Connect cannot be accessed.

### `TEAM_CAPABILITY_RESTRICTED`

Your organization does not have access to Connect endpoint.

### `ACCOUNT_CONSENT_UNAVAILABLE`

Account consent for your organization is unavailable.

### `ENTITY_VERIFICATION_MISSING`

Entity must be fully verified before they can access `/entities/{ent_id}/connect` endpoint.

### `CONNECT_BUREAU_REQUIRED_FOR_ARTIFACTS`

A `bureau` must be specified when requesting `artifacts`.

### `CONNECT_BUREAU_NOT_CONFIGURED`

No bureaus have been configured for your team. Contact Method to configure bureau access.

### `CONNECT_BUREAU_NOT_ENABLED`

The requested `bureau` is not enabled for your team.

### `CONNECT_RAW_REPORT_NOT_ENABLED`

The `raw_credit_report` artifact is not enabled for your team.

### `CONNECT_CREDIT_REPORT_PDF_NOT_ENABLED`

The `credit_report_pdf` artifact is not enabled for your team.

## Async Connect Errors

### `26001 – CONNECT_FAILED_THIN_CREDIT_FILE`

No tradelines were found for the entity due to thin credit file.

```json theme={null}
{
  "type": "CONNECT_FAILED",
  "code": 26001,
  "sub_type": "CONNECT_FAILED_THIN_CREDIT_FILE",
  "message": "Entity has a thin credit file."
}
```

### `26002 – CONNECT_FAILED_CREDIT_FREEZE`

The Entity has a credit freeze.

```json theme={null}
{
  "type": "CONNECT_FAILED",
  "code": 26002,
  "sub_type": "CONNECT_FAILED_CREDIT_FREEZE",
  "message": "Entity has a credit freeze."
}
```

### `24001 – PRODUCT_EXECUTION_FAILED`

The Connect job failed to execute.

```json theme={null}
{
  "type": "PRODUCT_EXECUTION_FAILED",
  "code": 24001,
  "sub_type": "PRODUCT_EXECUTION_FAILED",
  "message": "Product execution failed."
}
```

***


# Credit Score Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/credit-score-errors



## Request Errors

The request to the `/entities/{ent_id}/credit_scores` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `ENTITY_VERIFICATION_MISSING`

Entity must be fully verified before they can access `/entities/{ent_id}/credit_scores` endpoint.

### `PRODUCT_UNAVAILABLE_ENTITY_DISABLED`

The Entity is disabled, so a CreditScore cannot be retrieved.

### `TEAM_CAPABILITY_RESTRICTED`

Your organization does not have access to the Credit Score endpoint.

***

## Resource Errors

Errors set on a Credit Score's `error` property for processes that are unsuccessful.

### `23001 – CREDIT_SCORE_FAILED_TEMPORARILY_UNAVAILABLE`

There was an issue with the credit score provider and the request could not be completed.

```json theme={null}
{
  "type": "CREDIT_SCORE_FAILED",
  "code": 23001,
  "sub_type": "CREDIT_SCORE_FAILED_TEMPORARILY_UNAVAILABLE",
  "message": "Credit Score is temporarily unavailable for this entity."
}
```

***


# Entity Attribute Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/entity-attribute-errors



## Request Errors

The request to the `/entities/{entity_id}/attributes` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `PRODUCT_UNAVAILABLE_ENTITY_DISABLED`

The Entity is disabled, so Attributes cannot be retrieved.

### `TEAM_CAPABILITY_RESTRICTED`

Your organization does not have access to Attributes endpoint.

### `PRODUCT_RESTRICTED_CONNECT_REQUIRED`

Entity must have a completed Connect record to access this product.

### `PRODUCT_ATTRIBUTE_REQUIRED`

At least one valid attribute in the request body is required.

## Resource Errors

### `24001 – PRODUCT_EXECUTION_FAILED`

The Attributes request failed to execute.

```json theme={null}
{
  "type": "PRODUCT_EXECUTION_FAILED",
  "code": 24001,
  "sub_type": "PRODUCT_EXECUTION_FAILED",
  "message": "Product execution failed."
}
```

## Attribute Value Errors

Errors set on an individual attribute's `error` field when a value cannot be computed.

### `27001 – ENTITY_ATTRIBUTE_INSUFFICIENT_DATA`

There is insufficient data to compute this attribute (for example, not enough history for a trend attribute). The attribute's `value` will be `null`.

```json theme={null}
{
  "type": "ENTITY_ATTRIBUTE_INSUFFICIENT_DATA",
  "code": 27001,
  "sub_type": "ENTITY_ATTRIBUTE_INSUFFICIENT_DATA",
  "message": "Insufficient data to compute this entity attribute."
}
```


# Entity Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/entity-errors



## Request Errors

The request to the `/entities/{ent_id}` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `RESTRICTED_ENTITY_DETAILS`

The Entity's information does not match the restrictions set for your organization.

### `ENTITY_CONSENT_ALREADY_WITHDRAWN`

Consent for this Entity has already been withdrawn.

### `ENTITY_CONSENT_ALREADY_GRANTED`

Consent for this entity has already been granted.

### `ENTITY_HAS_PAYMENTS_IN_PROGRESS`

Consent for this entity cannot be withdrawn as it has one or more associated payments in progress.

### `ENTITY_INVALID_SSN`

The provided SSN is invalid. Verify your request and try again.

### `ENTITY_INVALID_SSN4`

The provided SSN4 is invalid. Verify your request and try again.

### `ENTITY_CREDIT_SCORE_NOT_FOUND`

The credit score for this entity could not be found.

### `MAX_ENTITY_METADATA_SIZE_EXCEEDED`

The max metadata object size of 1KB was exceeded.

### `ENTITY_UPDATE_DISABLED`

Disabled Entities cannot be updated.

### `ENTITY_UPDATE_INVALID`

Cannot update an Entity's field that has already been set.

***

### `ENTITY_CAPABILITY_UNAVAILABLE`

The Entity must have `data:retrieve` as an available capability.

### `ENTITY_PHONE_VERIFICATION_INVALID_CODE`

The phone verification code provided is invalid.

### `ENTITY_UPDATE_METADATA_SIZE_EXCEEDED`

The maximum metadata object size of 1KB was exceeded.

### `INVALID_ENTITY_DOB`

The date of birth is invalid. Date of birth cannot be in the future.

### `INVALID_ENTITY_STATUS_FOR_REFRESH_CAPABILITY`

The Entity must be in `active` status.

### Auth session request errors

The following `sub_type` values are returned by the `/entities/{ent_id}/auth_session` endpoints.

### `ENTITY_AUTH_SESSION_COMPLETED`

This Entity already has a completed auth session.

### `ENTITY_AUTH_SESSION_CREDIT_FREEZE`

The Entity is not available for non-KBA authentication due to a credit freeze. Re-attempt the auth session using the KBA authentication flow.

### `ENTITY_AUTH_SESSION_FRAUD`

The Entity is not available for non-KBA authentication. Re-attempt the auth session using the KBA authentication flow.

### `ENTITY_AUTH_SESSION_INVALID_ATTEMPT`

The authentication attempt is invalid. One more invalid attempt locks the session.

### `ENTITY_AUTH_SESSION_LOCKED`

The auth session is locked due to invalid attempts.

### `ENTITY_AUTH_SESSION_MISSING`

This Entity has not initiated an auth session.

### `ENTITY_AUTH_SESSION_NOT_FOUND`

The Entity is not available due to an unsuccessful match with the information provided.

### `INVALID_ENTITY_AUTH_ANSWERS`

An auth session answer is missing or invalid.

### `INVALID_ENTITY_AUTH_QUESTIONS`

An auth session question is missing or invalid.

## Resource Errors

Errors set on an Entity's `error` property for processes that are unsuccessful.

### `12001 – ENTITY_UNAUTHORIZED_PAYMENT`

The Entity was disabled due to unauthorized payments which was reported by the FI.

#### Causes

* [Customer Revoked Authorization](https://www.moderntreasury.com/ach-return-codes/r07)
* [Originator not known and/or not authorized to Debit Receiver’s Account](https://www.moderntreasury.com/ach-return-codes/r10)
* [Representative Payee Deceased or Unable to Continue in That Capacity](https://www.moderntreasury.com/ach-return-codes/r14)
* [Corporate Customer Advises Not Authorized](https://www.moderntreasury.com/ach-return-codes/r29)

```json theme={null}
{
  "type": "ENTITY_DISABLED",
  "code": 12001,
  "sub_type": "ENTITY_UNAUTHORIZED_PAYMENT",
  "message": "Entity was disabled due to a payment reported as unauthorized by the financial institution."
}
```

#### Resolution

The Entity will be disabled and all its capabilities will be removed.

***

### `12002 – ENTITY_INVALID_DETAILS`

The Entity was disabled due to the information provided being invalid.

#### Causes

* One or more PIIs provided were invalid.

```json theme={null}
{
  "type": "ENTITY_DISABLED",
  "code": 12002,
  "sub_type": "ENTITY_INVALID_DETAILS",
  "message": "Entity was disabled due to invalid information."
}
```

#### Resolution

The Entity will be disabled and no capabilities will be granted.

***

### `12003 – ENTITY_SSN_MISMATCH`

The Entity was disabled due to the PII provided not matching the identity the SSN belongs to.

#### Causes

* SSN provided does not match the Entity's identity.

```json theme={null}
{
  "type": "ENTITY_DISABLED",
  "code": 12003,
  "sub_type": "ENTITY_SSN_MISMATCH",
  "message": "Entity was disabled due to a mismatch in the provided and retrieved social security number."
}
```

#### Resolution

The Entity will be disabled and no capabilities will be granted.

***

### `12004 – ENTITY_CONSENT_WITHDRAWN`

The Entity was disabled due to consent being withdrawn.

#### Causes

* The Entity has withdrawn consent.

```json theme={null}
{
  "type": "ENTITY_DISABLED",
  "code": 12004,
  "sub_type": "ENTITY_CONSENT_WITHDRAWN",
  "message": "Entity was disabled due to consent withdrawal."
}
```

#### Resolution

The Entity will be disabled and all its capabilities will be removed.

***

### `12005 – ENTITY_PENDING_KYC_REVIEW`

The Entity was disabled due Method's provider needing to review the Entity's KYC information.

#### Causes

* The Entity has been flagged for requiring a KYC review.

```json theme={null}
{
  "type": "ENTITY_DISABLED",
  "code": 12005,
  "sub_type": "ENTITY_PENDING_KYC_REVIEW",
  "message": "Entity was disabled due to pending KYC review."
}
```

#### Resolution

The Entity will be disabled and no capabilities will be granted.


# Entity Verification Session Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/entity-verification-session-errors



## Request Errors

The request to the `/entities/{ent_id}/verification_sessions` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `ENTITY_PHONE_VERIFICATION_MAX_ATTEMPTS`

The Entity has reached the maximum number of phone verification attempts.

### `EXISTING_VERIFIED_SESSION`

The Entity has already completed the verification for that EntityVerificationSession `type`.

### `MISSING_IDENTITY_MATCH`

The Entity's identity couldn't be found. Update the Entity's PII to improve the chances of finding the identity.

### `MISSING_PHONE_VERIFICATION`

The Entity's phone number has not been verified yet.

### `UNAUTHORIZED_VERIFICATION_METHOD`

The Entity is unauthorized to use the verification method provided.

### `INVALID_ENTITY_TYPE`

The Entity must be of type `individual` to use the EntityVerificationSession endpoint.

### `VERIFICATION_SESSION_EXPIRED`

A response back to Method took too long and the EntityVerificationSession has expired.

### `VERIFICATION_SESSION_INCORRECT_SMS_CODE`

The Entity's phone number couldn't be verified through the SMS code provided.

### `VERIFICATION_SESSION_FAILED_SNA`

The verification process failed to verify the entity's phone number through SNA.

### `VERIFICATION_SESSION_FAILED_INVALID_ANSWER`

The Entity's identity couldn't be verified through the answer provided.

***

## Resource Errors

Errors set on an EntityVerificationSession's `error` property for processes that are unsuccessful.

### `19001 – VERIFICATION_SESSION_EXPIRED`

The EntityVerificationSession has expired. The verification process must be re-initiated.

#### Causes

* The EntityVerificationSession was not completed in the allotted time.

```json theme={null}
{
  "type": "VERIFICATION_SESSION_FAILED",
  "code": 19001,
  "sub_type": "VERIFICATION_SESSION_EXPIRED",
  "message": "The verification session has expired. Please re-initiate the verification process."
}
```

#### Resolution

* Initiate a new EntityVerificationSession.

***

### `19002 – VERIFICATION_SESSION_INCORRECT_SMS_CODE`

The Entity's phone number couldn't be verified through the SMS code provided.

#### Causes

* The individual inputted an incorrect SMS code.

```json theme={null}
{
  "type": "VERIFICATION_SESSION_FAILED",
  "code": 19002,
  "sub_type": "VERIFICATION_SESSION_INCORRECT_SMS_CODE",
  "message": "The SMS code inputted is invalid. Please re-initiate the verification process."
}
```

#### Resolution

* Initiate a new EntityVerificationSession and make sure the individual is inputting the correct SMS code.

***

### `19003 – VERIFICATION_SESSION_FAILED_SNA`

The verification process failed to verify the Entity's phone number through SNA.

#### Causes

* The individual is not on a mobile device.
* The individual is not on a network that supports SNA.

```json theme={null}
{
  "type": "VERIFICATION_SESSION_FAILED",
  "code": 19003,
  "sub_type": "VERIFICATION_SESSION_FAILED_SNA",
  "message": "The entity's phone couldn't be verified through SNA. Please re-initiate the verification process."
}
```

#### Resolution

* Confirm the individual is on a mobile device.
* Attempt a different verification method.

***

### `19004 – VERIFICATION_SESSION_FAILED_INVALID_ANSWER`

The Entity's identity couldn't be verified through the answer provided.

#### Causes

* The individual answered one or more questions incorrectly.
* One or more questions was missing in the request.

```json theme={null}
{
  "type": "VERIFICATION_SESSION_FAILED",
  "code": 19004,
  "sub_type": "VERIFICATION_SESSION_FAILED_INVALID_ANSWER",
  "message": "Invalid entity identity answer. An answer is either missing or invalid. Please re-initiate the verification process."
}
```

#### Resolution

* Initiate a new EntityVerificationSession and confirm that the individual is answering the questions correctly.

***


# File Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/file-errors



## Request Errors

The request to the `/files/{file_id}` or `/files/{file_id}/download` endpoint failed. These are the `sub_type` that can be returned.

### `NOT_FOUND`

The requested File does not exist.

## File Content Errors

These `sub_type` can be returned by both [Retrieve a File](/2026-03-30/reference/files/retrieve) and [Download a File](/2026-03-30/reference/files/download), since both resolve the File's contents.

### `FILE_SOURCE_URL_MISSING`

The File has no downloadable contents. This can occur if the artifact upload never completed. Contact Method if this persists.

### `FILE_SOURCE_URL_INVALID`

The File's contents could not be resolved. Contact Method if this persists.

### `FILE_DOWNLOAD_URL_FAILED`

A temporary failure occurred while generating the download URL or streaming the File's contents. Retry the request.

***


# Forwarding Request Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/forwarding-request-errors



## Request Errors

The request to the `POST /forwarding_requests` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `URL_NOT_ALLOWED`

The URL is not whitelisted for forwarding requests.

### `INVALID_TEMPLATE`

Template expression is invalid.

### `TEMPLATE_IN_KEYS_NOT_ALLOWED`

Template expressions are not allowed in JSON keys.

### `BINDING_NAME_MISSING`

Binding name was referenced in a template but not provided in the bindings object.

### `BINDING_NAME_NOT_REFERENCED`

Binding name was provided in the bindings object but not referenced in any templates.

### `BINDING_NOT_FOUND`

Resource ID associated with the binding name was not found. Verify the resource id and try again.

### `UNSUPPORTED_BINDING_VALUE`

Resource type associated with the binding name is not supported.

### `DISALLOWED_TEMPLATE_PATH`

Path referenced in the template is not allowed for this destination.

### `REFERENCED_VALUE_IS_NULL`

Referenced value at the path is null or missing.

### `INVALID_METHOD`

The HTTP method is not allowed for this destination.

### `BODY_JSON_INVALID`

Request body must be valid stringified JSON.

### `INVALID_CONTENT_TYPE`

The provided content type is not allowed for this destination.

***

## Resource Errors

When the outbound (forwarded) request fails, the API still responds with HTTP `200` and `success: true`; the failure is recorded on the returned ForwardingRequest resource's `error` property.

### `FORWARDED_REQUEST_TIMEOUT`

The forwarded request timed out. The timeout is 10 seconds.

```json theme={null}
{
  "type": "API_ERROR",
  "sub_type": "FORWARDED_REQUEST_TIMEOUT",
  "message": "Forwarded request timed out."
}
```

### `FORWARDED_REQUEST_NETWORK_ERROR`

The forwarded request failed due to a network error. The message includes the network error code (for example, `ECONNREFUSED`).

```json theme={null}
{
  "type": "API_ERROR",
  "sub_type": "FORWARDED_REQUEST_NETWORK_ERROR",
  "message": "Forwarded request failed due to a network error (ECONNREFUSED)."
}
```


# Identity Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/identity-errors



## Request Errors

The request to the `/entities/{ent_id}/identities` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `PRODUCT_UNAVAILABLE_ENTITY_DISABLED`

The Entity is disabled, so an Identity cannot be retrieved.

### `TEAM_CAPABILITY_RESTRICTED`

The organization does not have access to Identity endpoint.

### `PRODUCT_RESTRICTED`

The entity requires a phone number to access Identity endpoint.

### `NO_IDENTITIES_FOUND`

No identities were found for the entity.

***


# mTLS Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/mtls-errors



## Request Errors

The request failed client-certificate validation. These errors occur only for teams provisioned for [mTLS](/2026-03-30/reference/mtls).

These are returned before the request reaches Method's core API, using the standard error envelope.

### `UNAUTHORIZED`

No client certificate was presented, or the presented certificate failed verification. Returned with HTTP status `401`.

```json theme={null}
{
  "success": false,
  "data": {
    "error": {
      "type": "INVALID_REQUEST",
      "code": 401,
      "sub_type": "UNAUTHORIZED",
      "message": "A valid client certificate is required to access this resource. Contact your account administrator about mTLS provisioning."
    }
  },
  "message": null
}
```

***

### `FORBIDDEN`

The certificate is valid but its Subject DN is not authorized for the resolved team. Returned with HTTP status `403`. Confirm the Subject DN registered with Method matches the one on your certificate.

```json theme={null}
{
  "success": false,
  "data": {
    "error": {
      "type": "INVALID_REQUEST",
      "code": 403,
      "sub_type": "FORBIDDEN",
      "message": "The presented client certificate is not authorized for this team. Contact your account administrator."
    }
  },
  "message": null
}
```


# Payment Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/payment-errors



## Request Errors

The request to the `/payments` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `INVALID_AMOUNT_TYPE`

Amount type should be integers expressed as decimals.

### `INVALID_AMOUNT`

The minimum amount for a payment is 100 cents `($1.00)`. The maximum amount for a payment is 100,000,000 cents `($1,000,000.00)`.

### `INVALID_ACH_DESCRIPTION`

The ACH description should be a string with a maximum of 10 characters.

### `INVALID_SOURCE`

Source Account provided is invalid. Account either doesn't exist or is not active.

### `INVALID_SOURCE_HOLDER_CAPABILITIES`

Source Account holder is not allowed to send funds.

### `INVALID_SOURCE_HOLDER_LIMITED`

Source Account holder is limited to sending funds from Accounts linked using Method Link (Plaid / MX).

### `INVALID_SOURCE_LIABILITY`

Source Account cannot be of type `liability`.

### `INVALID_DESTINATION`

Destination Account provided is invalid. Account either doesn't exist or is not active.

### `INVALID_DESTINATION_HOLDER`

Destination Account holder is not allowed to receive funds.

### `INVALID_ACH_DESTINATION_NOT_ALLOWED`

Payments to an ACH destination account are not enabled. Contact support to enable this capability.

### `INVALID_TEST_DESTINATION`

Destination Account was created before live mode was enabled.

### `INVALID_TEST_SOURCE`

Source Account was created before live mode was enabled.

### `INVALID_TRANSFER`

Cannot transfer funds between the same Account.

### `MAX_AMOUNT_EXCEEDED`

The organization's max one-time transfer amount exceeded.

### `MAX_DAILY_VOLUME_EXCEEDED`

The organization's max 24-hour total transfer volume has been exceeded. Contact support to extend this limit.

### `MAX_DAILY_ACH_DESTINATION_VOLUME_EXCEEDED`

The organization's max 24-hour total transfer volume to ACH destination accounts has been exceeded. Contact support to extend this limit.

### `MAX_DAILY_ACH_INDI_SOURCE_VOLUME_EXCEEDED`

The organization's max 24-hour total transfer volume from ACH source accounts held by an individual has been exceeded. Contact support to extend this limit.

### `MAX_REQUEST_LIMIT`

The organization's monthly payment request limit has been reached. Contact support to extend this limit.

### `MAX_PAYMENT_METADATA_SIZE_EXCEEDED`

Max metadata object size of 1KB exceeded.

### `INVALID_SOURCE_CAPABILITIES`

Source Account is not verified to send payments.

### `INVALID_DESTINATION_CAPABILITIES`

Destination Account is not verified to receive payments.

### `INVALID_DESTINATION_BALANCE`

Destination Account has a balance of \$0.

### `INVALID_SOURCE_SINGLE_USE_CLEARING`

Source Account is a single-use clearing account, and has already been used for a payment.

***

### `INTERNAL_ERROR_DESTINATION`

The payment could not be deleted due to an unexpected error on the destination side. Retry the request; contact support if it persists.

### `INTERNAL_ERROR_SOURCE`

The payment could not be deleted due to an unexpected error on the source side. Retry the request; contact support if it persists.

### `INVALID_DESTINATION_CONNECTION`

The payment connection for this destination account is currently unavailable.

### `INVALID_DESTINATION_HOLDER_KYC_STATUS`

The destination account holder failed KYC status evaluation and the Entity has been disabled.

### `INVALID_REVERSAL_ACCOUNT`

The reversal account provided is invalid.

### `INVALID_REVERSAL_ACCOUNT_CAPABILITIES`

The reversal account is not verified to receive funds. Select another reversal account.

### `INVALID_REVERSAL_ACCOUNT_HOLDER`

The reversal account holder is not allowed to receive funds. Verify that the Entity is complete.

### `INVALID_REVERSAL_ACCOUNT_HOLDER_KYC_STATUS`

The reversal account holder failed KYC status evaluation and the Entity has been disabled.

### `INVALID_REVERSAL_ACCOUNT_LIABILITY`

Liability accounts cannot be used as a reversal account; use an ACH or wire account.

### `INVALID_SOURCE_HOLDER_KYC_STATUS`

The source account holder failed KYC status evaluation and the Entity has been disabled.

### `INVALID_SOURCE_NOT_ALLOWED`

The source account is not an allowed payment source.

### `INVALID_SOURCE_WIRE`

Wire accounts cannot be used as a payment source. Only ACH accounts can be used as a source.

### `INVALID_STATUS`

The payment cannot be deleted. Payments can be canceled only while pending, or stopped and reversed only when sent by paper check and not yet cashed.

## Resource Errors

Errors set on a Payment's `error` property for processes that are unsuccessful.

### `10001 – PAYMENT_INSUFFICIENT_FUNDS`

Payment failed due to insufficient funds from the source Account.

```json theme={null}
{
  "type": "PAYMENT_FAILED",
  "code": 10001,
  "sub_type": "PAYMENT_INSUFFICIENT_FUNDS",
  "message": "Payment failed due to insufficient funds from the source account."
}
```

***

### `10002 – PAYMENT_UNAUTHORIZED`

The Payment was unauthorized by the source or destination Account holder.

```json theme={null}
{
  "type": "PAYMENT_FAILED",
  "code": 10002,
  "sub_type": "PAYMENT_UNAUTHORIZED",
  "message": "Payment failed due to a report by the source or destination account holder as unauthorized."
}
```

***

### `10003 – PAYMENT_INVALID_ACCOUNT`

The Payment failed due to an invalid source or destination Account. The Account is either inactive or does not exist.

```json theme={null}
{
  "type": "PAYMENT_FAILED",
  "code": 10003,
  "sub_type": "PAYMENT_INVALID_ACCOUNT",
  "message": "Payment failed due to an invalid source or destination account."
}
```

***

### `10004 – PAYMENT_INSUFFICIENT_FUNDS`

Payment was canceled due to insufficient funds from the source Account.

```json theme={null}
{
  "type": "PAYMENT_CANCELED",
  "code": 10004,
  "sub_type": "PAYMENT_INSUFFICIENT_FUNDS",
  "message": "Payment was canceled due to insufficient funds from the source account."
}
```

***

### `10005 – PAYMENT_UNAUTHORIZED_SOURCE`

The Payment failed due to a report by the source Account holder as unauthorized.

```json theme={null}
{
  "type": "PAYMENT_FAILED",
  "code": 10005,
  "sub_type": "PAYMENT_UNAUTHORIZED_SOURCE",
  "message": "Payment failed due to a report by the source account holder as unauthorized."
}
```

***

### `10006 – PAYMENT_UNAUTHORIZED_DESTINATION`

The Payment failed due to a report by the destination Account holder as unauthorized.

```json theme={null}
{
  "type": "PAYMENT_FAILED",
  "code": 10006,
  "sub_type": "PAYMENT_UNAUTHORIZED_DESTINATION",
  "message": "Payment failed due to a report by the destination account holder as unauthorized."
}
```

***

### `10007 – PAYMENT_INVALID_SOURCE_ACCOUNT`

The source Account is invalid. The Account is either inactive or does not exist.

```json theme={null}
{
  "type": "PAYMENT_FAILED",
  "code": 10007,
  "sub_type": "PAYMENT_INVALID_SOURCE_ACCOUNT",
  "message": "Payment failed due to an invalid source account."
}
```

***

### `10008 – PAYMENT_INVALID_DESTINATION_ACCOUNT`

The destination Account is invalid. The Account is either inactive or does not exist.

```json theme={null}
{
  "type": "PAYMENT_FAILED",
  "code": 10008,
  "sub_type": "PAYMENT_INVALID_DESTINATION_ACCOUNT",
  "message": "Payment failed due to an invalid destination account."
}
```

***

### `10009 – PAYMENT_REJECTED_BY_DESTINATION_INSTITUTION`

The Payment was rejected by the destination Account's FI.

```json theme={null}
{
  "type": "PAYMENT_FAILED",
  "code": 10009,
  "sub_type": "PAYMENT_REJECTED_BY_DESTINATION_INSTITUTION",
  "message": "Payment failed due to a rejection by the destination account's financial institution."
}
```

***

### `10010 – PAYMENT_REJECTED_INVALID_AMOUNT`

The payment failed due to a rejection by the destination account's financial institution to accept the payment amount.

```json theme={null}
{
  "type": "PAYMENT_FAILED",
  "code": 10010,
  "sub_type": "PAYMENT_REJECTED_INVALID_AMOUNT",
  "message": "Payment failed due to a rejection by the destination account's financial institution to accept the payment amount."
}
```

***

### `10011 – PAYMENT_STOPPED_BY_REQUEST`

The payment failed as it was stopped by request before completion.

```json theme={null}
{
  "type": "PAYMENT_FAILED",
  "code": 10011,
  "sub_type": "PAYMENT_STOPPED_BY_REQUEST",
  "message": "Payment failed as it was stopped by request before completion."
}
```

***


# Payment Instrument Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/payment-instrument-errors



## Request Errors

The request to the `/accounts/{acc_id}/payment_instruments` endpoints failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `INVALID_DESTINATION`

The destination Account is invalid. The Account either does not exist or is not active.

### `INVALID_DESTINATION_BALANCE`

The destination Account has a balance of \$0. Select another destination Account and try again.

### `INVALID_DESTINATION_CAPABILITIES`

The destination Account is not verified to receive funds.

### `INVALID_DESTINATION_CONNECTION`

The payment connection for the destination Account is currently unavailable.

### `INVALID_REVERSAL_ACCOUNT`

The reversal account provided is invalid.

### `INVALID_REVERSAL_ACCOUNT_CAPABILITIES`

The reversal account is not verified to receive funds. Select another reversal account.

### `INVALID_REVERSAL_ACCOUNT_HOLDER`

The reversal account holder is not allowed to receive funds. Verify that the Entity is complete.

### `INVALID_REVERSAL_ACCOUNT_HOLDER_KYC_STATUS`

The reversal account holder failed KYC status evaluation and the Entity has been disabled.

### `INVALID_REVERSAL_ACCOUNT_LIABILITY`

Liability accounts cannot be used as a reversal account; use an ACH or wire account.

### `PRODUCT_RESTRICTED_MISSING_REVERSAL_ACCOUNT`

The preferred reversal account is not set. Reach out to the Method team to learn more.

### `PRODUCT_UNAVAILABLE_ACCOUNT_CANNOT_RECEIVE_FUNDS`

The Account cannot receive funds, so an inbound PaymentInstrument cannot be created.

### `PRODUCT_UNAVAILABLE_INVALID_ACCOUNT_TYPE`

PaymentInstruments are not supported for this account type.

### `PRODUCT_UNAVAILABLE_ACCOUNT_NOT_ACTIVE`

The Account is not active, so a PaymentInstrument cannot be created.

### `PRODUCT_UNAVAILABLE_UNSUPPORTED_NETWORK`

PaymentInstruments are not available for this card network.

### `PRODUCT_VERIFICATION_MISSING`

The Account must be verified before a PaymentInstrument can be created.

### `TEAM_RESTRICTED_MISSING_PRODUCT_CONFIGURATION`

Your team is missing configuration for this Product. Reach out to the Method team to learn more.

### `TEAM_CAPABILITY_RESTRICTED`

Your organization does not have access to PaymentInstruments.

### `PAYMENT_INSTRUMENT_ALREADY_CLOSED`

The PaymentInstrument is already closed.

### `PAYMENT_INSTRUMENT_ALREADY_EXISTS`

A chargeable PaymentInstrument of this type already exists for this Account.

### `PAYMENT_INSTRUMENT_CLOSE_NOT_SUPPORTED_FOR_TYPE`

Close is only supported for PaymentInstruments of type `inbound_achwire_payment`.


# Payment Reversal Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/payment-reversal-errors



## Request Errors

The request to the `/payments/{pmt_id}/reversals` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `INVALID_REVERSAL_STATUS`

Cannot update Reversal if status is not `pending_approval`.

***

## Resource Errors

Errors set on a Reversal's `error` property for processes that are unsuccessful.

### `14001 – PAYMENT_REVERSAL_INSUFFICIENT_FUNDS`

The Reversal failed due to Account having insufficient funds.

```json theme={null}
{
  "type": "PAYMENT_REVERSAL_FAILED",
  "code": 14001,
  "sub_type": "PAYMENT_REVERSAL_INSUFFICIENT_FUNDS",
  "message": "Payment reversal failed due to insufficient funds from the account."
}
```

***

### `14002 – PAYMENT_REVERSAL_UNAUTHORIZED`

The Reversal failed due to a report by the Account holder as unauthorized.

```json theme={null}
{
  "type": "PAYMENT_REVERSAL_FAILED",
  "code": 14002,
  "sub_type": "PAYMENT_REVERSAL_UNAUTHORIZED",
  "message": "Payment reversal failed due to a report by the account holder as unauthorized."
}
```

***

### `14003 – PAYMENT_REVERSAL_INVALID_ACCOUNT`

The Reversal failed due to an invalid Account. The Account is either inactive or does not exist.

```json theme={null}
{
  "type": "PAYMENT_REVERSAL_FAILED",
  "code": 14003,
  "sub_type": "PAYMENT_REVERSAL_INVALID_ACCOUNT",
  "message": "Payment reversal failed due to an invalid account."
}
```

***


# Payoff Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/payoff-errors



## Request Errors

The request to the `/accounts/{acc_id}/payoffs` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `PRODUCT_UNAVAILABLE`

This Account does not support Payoffs. This could be due to the Account's status, the Account's liability type
or Method currently doesn't support Payoffs for the Account's Financial Institution.

### `PRODUCT_UNAVAILABLE_ACCOUNT_NOT_ACTIVE`

The Account is not active, so a Payoff cannot be retrieved.

### `PRODUCT_UNAVAILABLE_INVALID_LIABILITY_TYPE`

Payoffs are not supported for this liability type.

### `TEAM_CAPABILITY_RESTRICTED`

Your organization does not have access to Payoff endpoint.

### `PRODUCT_VERIFICATION_MISSING`

Account must be verified before it can access `/accounts/{acc_id}/payoffs` endpoint.

***

## Resource Errors

Errors set on a Payoff's `error` property for processes that are unsuccessful.

### `18001 – PAYOFF_TEMPORARILY_UNAVAILABLE`

There was an issue with connecting with the Account's Financial Institution and the request could not be completed.

```json theme={null}
{
  "type": "PAYOFF_FAILED",
  "code": 18001,
  "sub_type": "PAYOFF_TEMPORARILY_UNAVAILABLE",
  "message": "Payoff is temporarily unavailable for this account."
}
```

***


# Product Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/product-errors



## Status Errors

Product's status represents the current access state of the Product. The following errors are related to the status of the Product.

### `ACCOUNT_CONSENT_UNAVAILABLE`

Account consent for your organization is unavailable.

### `PRODUCT_RESTRICTED`

This Product is currently not available for this Entity or Account due to missing information or verification. Please update your information to gain access to this Product.

### `PRODUCT_UNAVAILABLE`

This Product is not supported for this Entity or Account.

### `PRODUCT_VERIFICATION_MISSING`

Account is missing verification for the Product.

### `TEAM_CAPABILITY_RESTRICTED`

Your organization does not have access to this Product.

### `PRODUCT_UNAVAILABLE_INVALID_ACCOUNT_TYPE`

This Product is not supported for this Account type.

### `PRODUCT_UNAVAILABLE_INVALID_LIABILITY_TYPE`

This Product is not supported for this Liability type.

***

### `PRODUCT_AVAILABILITY_ERROR`

The Product is not available for an unknown reason. Reach out to the Method team to learn more.

### `PRODUCT_RESTRICTED_MISSING_REVERSAL_ACCOUNT`

The preferred reversal account is not set. Reach out to the Method team to learn more.

### `PRODUCT_UNAVAILABLE_ACCOUNT_CANNOT_RECEIVE_FUNDS`

The Account cannot receive funds, so this Product cannot be accessed.

### `PRODUCT_UNAVAILABLE_ACCOUNT_NOT_ACTIVE`

The Account is not active, so this Product cannot be accessed.

### `PRODUCT_UNAVAILABLE_ACCOUNT_NOT_CONSENTED`

The Account is not consented, so this Product cannot be accessed.

### `PRODUCT_UNAVAILABLE_ENTITY_DISABLED`

The Entity is disabled, so this Product cannot be accessed.

### `PRODUCT_UNAVAILABLE_UNSUPPORTED_NETWORK`

The Product is not available for this card network.

### `TEAM_RESTRICTED_MISSING_PRODUCT_CONFIGURATION`

Your team is missing configuration for this Product. Reach out to the Method team to learn more.

### `ENTITY_VERIFICATION_MISSING`

The Entity must be fully verified before it can access the requested Product.

### `PRODUCT_RESTRICTED_CONNECT_REQUIRED`

The Entity must have a completed Connect record to access this Product.

## Resource Errors

Errors set on a Product resource's `error` property when execution is unsuccessful.

### `24001 – PRODUCT_EXECUTION_FAILED`

The Product request failed to execute.

```json theme={null}
{
  "type": "PRODUCT_EXECUTION_FAILED",
  "code": 24001,
  "sub_type": "PRODUCT_EXECUTION_FAILED",
  "message": "Product execution failed."
}
```

Retry the request. If the issue persists, contact Method support.


# Request Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/request-errors



Method uses conventional HTTP response codes to indicate the success or failure of an API request.
In general: Codes in the `2xx` range indicate success. Codes in the `4xx` range indicate an error occurred
with the information provided (e.g., a required parameter was omitted, a resource was not found, etc.).
Codes in the `5xx` range indicate an error occurred within Method's servers.

## Attributes

<ParamList />

#### HTTP STATUS CODE SUMMARY

| code  | function            | Description                                                                                                                                                |
| ----- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `2xx` | `OK`                | Everything worked as expected.                                                                                                                             |
| `400` | `Bad Request`       | The request was unacceptable, often due to missing a required parameter.                                                                                   |
| `401` | `Unauthorized`      | No valid API key provided.                                                                                                                                 |
| `403` | `Forbidden`         | The API key doesn't have permissions to perform the request.                                                                                               |
| `404` | `Not Found`         | The requested resource doesn't exist.                                                                                                                      |
| `409` | `Conflict`          | The request conflicts with the current state of the resource.                                                                                              |
| `429` | `Too Many Requests` | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. See [Rate Limiting](/2026-03-30/reference/rate-limiting). |
| `500` | `Server Errors`     | Something went wrong on Method's end.                                                                                                                      |

<RequestExample>
  ```javascript THE ERROR OBJECT theme={null}
  {
    "type": "INVALID_REQUEST",
    "code": 400,
    "sub_type": "INVALID_SOURCE_LIABILITY",
    "message": "Invalid source account received. Only ACH accounts can be used as a source."
  }
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": false,
    "data": {
      "error": {
        "type": "INVALID_REQUEST",
        "code": 400,
        "sub_type": "INVALID_SOURCE_LIABILITY",
        "message": "Invalid source account received. Only ACH accounts can be used as a source."
      }
    },
    "message": "Invalid source account received. Only ACH accounts can be used as a source."
  }
  ```
</ResponseExample>


# Resource Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/resource-errors



These types of errors occur after a resource has been created. The information
regarding these errors is provided in the resource object's `error` property.

### Error Codes

A resource error's `code` is unique across all resources. This code specifically indicates
exactly what error occurred for what type of resource. Here is how the error codes
are partitioned for each resource:

| Code Range | Resource                                                                                                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `10XXX`    | [Payments](/2026-03-30/reference/errors/payment-errors#resource-errors)                                                                                            |
| `11XXX`    | [Accounts](/2026-03-30/reference/errors/account-errors#resource-errors)                                                                                            |
| `12XXX`    | [Entities](/2026-03-30/reference/errors/entity-errors#resource-errors)                                                                                             |
| `13XXX`    | Legacy account verifications ([AccountVerificationSessions](/2026-03-30/reference/errors/account-verification-session-errors#legacy-verification-resource-errors)) |
| `14XXX`    | [PaymentReversals](/2026-03-30/reference/errors/payment-reversal-errors#resource-errors)                                                                           |
| `16XXX`    | [AccountVerificationSessions](/2026-03-30/reference/errors/account-verification-session-errors#resource-errors)                                                    |
| `18XXX`    | [Payoffs](/2026-03-30/reference/errors/payoff-errors#resource-errors)                                                                                              |
| `19XXX`    | [EntityVerificationSessions](/2026-03-30/reference/errors/entity-verification-session-errors#resource-errors)                                                      |
| `20XXX`    | [Balances](/2026-03-30/reference/errors/balance-errors#resource-errors)                                                                                            |
| `21XXX`    | [Updates](/2026-03-30/reference/errors/update-errors#resource-errors)                                                                                              |
| `23XXX`    | [CreditScores](/2026-03-30/reference/errors/credit-score-errors#resource-errors)                                                                                   |
| `24XXX`    | [Products](/2026-03-30/reference/errors/product-errors#resource-errors)                                                                                            |
| `25XXX`    | [Webhooks](/2026-03-30/reference/errors/webhook-errors#resource-errors)                                                                                            |
| `26XXX`    | [Connect](/2026-03-30/reference/errors/connect-errors#async-connect-errors)                                                                                        |
| `27XXX`    | [EntityAttributes](/2026-03-30/reference/errors/entity-attribute-errors#attribute-value-errors)                                                                    |
| `28XXX`    | [AccountAttributes](/2026-03-30/reference/errors/account-attribute-errors#attribute-value-errors)                                                                  |

<RequestExample>
  ```json ERROR OBJECT theme={null}
  {
    "type": "PAYMENT_FAILED",
    "code": 10001,
    "sub_type": "PAYMENT_INSUFFICIENT_FUNDS",
    "message": "Payment failed due to insufficient funds from the source account."
  }
  ```
</RequestExample>

<ResponseExample>
  ```json ERROR ON RESOURCE theme={null}
  {
    "id": "pmt_rPrDPEwyCVUcm",
    "reversal_id": null,
    "source_trace_id": null,
    "destination_trace_id": null,
    "source": "acc_JMJZT6r7iHi8e",
    "destination": "acc_AXthnzpBnxxWP",
    "amount": 5000,
    "description": "Loan Pmt",
    "status": "failed",
    "error": {
      "type": "PAYMENT_FAILED",
      "code": 10001,
      "sub_type": "PAYMENT_INSUFFICIENT_FUNDS",
      "message": "Payment failed due to insufficient funds from the source account."
    },
    "metadata": null,
    "estimated_completion_date": "2020-12-11",
    "source_settlement_date": "2020-12-09",
    "destination_settlement_date": "2020-12-11",
    "created_at": "2020-12-09T00:42:31.209Z",
    "updated_at": "2020-12-09T00:43:30.996Z"
  }
  ```
</ResponseExample>


# Sensitive Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/sensitive-errors



## Request Errors

The request to the `/accounts/{acc_id}/sensitive` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `PRODUCT_UNAVAILABLE`

This Account does not support retrieving Account's sensitive information.

### `TEAM_CAPABILITY_RESTRICTED`

Your organization does not have access to Sensitive endpoint.

### `PRODUCT_VERIFICATION_MISSING`

Account must be verified before it can access `/accounts/{acc_id}/sensitive` endpoint.

### `ACCOUNT_SENSITIVE_FAILED_VERIFICATION_REQUIRED`

The Account is missing the verification required to retrieve sensitive data. Returned as an HTTP 400; a Sensitive resource is not persisted for this failure.


# Simulation Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/simulate-errors



## Request Errors

The request to a `/simulate/...` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `TOO_MANY_REQUESTS`

Too many requests hit the API too quickly. Retry with exponential backoff.

### `SIMULATION_RESTRICTED_MISSING_PRODUCT_REQUEST`

Resource must have a completed request for this product in order to configure simulations.

### `SIMULATION_RESTRICTED_MISSING_SUBSCRIPTION`

Resource must have an active subscription for this product in order to simulate this behavior.

***


# Subscription Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/subscription-errors



## Request Errors

The response will contain either a Subscription object or an Error object.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `PRODUCT_CAPABILITY_RESTRICTED`

The status of the Product that this Subscription is associated with is restricted to this Entity or Account.

### `PRODUCT_UNAVAILABLE`

The status of the Product that this Subscription is associated with is unavailable to this Entity or Account.

### `SUBSCRIPTION_DUPLICATE`

There was an attempt to enroll in an already active Subscription

### `SUBSCRIPTION_INVALID_PAYLOAD_ATTRIBUTES`

The subscription payload contains restricted or unsupported attributes.

### `SUBSCRIPTION_NOT_FOUND`

The requested Subscription is not available for this resource. Unrecognized subscription names are usually rejected by request validation with a generic `INVALID_REQUEST` error before reaching this check.

### `SUBSCRIPTION_OPAL_REQUIRED`

This Subscription can only be created through Opal. `transaction` enrollment requires the user to grant consent through Opal unless API enrollment is enabled for your team.

### `SUBSCRIPTION_RESTRICTED_ACCOUNT_ALREADY_ENROLLED`

The Account is already enrolled in a related Subscription. For example, an Account can have either an `update` or an `update.snapshot` subscription, not both.

### `SUBSCRIPTION_RESTRICTED_MISSING_PRODUCT_REQUEST`

The Account must have a completed request for the related Product before it can be enrolled. See [Enrollment requirements](/2026-03-30/reference/accounts/subscriptions/overview#enrollment-requirements).

### `PRODUCT_UNAVAILABLE_ACCOUNT_NOT_ACTIVE`

The Account is not active, so this Subscription cannot be enrolled.

### `PRODUCT_VERIFICATION_MISSING`

The Account must be verified before it can be enrolled in this Subscription.

### `TEAM_RESTRICTED_MISSING_PRODUCT_CONFIGURATION`

Your team is missing configuration for the related Product. Reach out to the Method team to learn more.

### `TEAM_CAPABILITY_RESTRICTED`

Your organization does not have access to this Subscription.

***


# Update Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/update-errors



## Request Errors

The request to the `/accounts/{acc_id}/updates` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `PRODUCT_UNAVAILABLE`

This Account does not support Update. This could be due to the Account's status
or Method currently doesn't support Updates for the Account's Financial Institution.

### `ACCOUNT_DATA_SYNC_UNAVAILABLE`

The Account is missing the `data:sync` capability.

### `ACCOUNT_HOLDER_MISSING_CAPABILITY`

The Account's holder Entity must have the `data:sync` capability.

### `PRODUCT_UNAVAILABLE_ACCOUNT_NOT_ACTIVE`

The Account is not active, so an Update cannot be created.

### `PRODUCT_UNAVAILABLE_ACCOUNT_NOT_CONSENTED`

The Account is not consented, so an Update cannot be created.

### `PRODUCT_UNAVAILABLE_INVALID_ACCOUNT_TYPE`

Updates are not supported for this account type.

### `PRODUCT_UNAVAILABLE_INVALID_LIABILITY_TYPE`

Updates are not supported for this liability type.

### `TEAM_CAPABILITY_RESTRICTED`

Your organization does not have access to Update endpoint.

### `PRODUCT_VERIFICATION_MISSING`

Account must be verified before it can access `/accounts/{acc_id}/updates` endpoint.

***

## Resource Errors

Errors set on an Update's `error` property for processes that are unsuccessful.

### `21001 – UPDATE_TEMPORARILY_UNAVAILABLE`

There was an issue with connecting with the Account's Financial Institution and the request could not be completed.

```json theme={null}
{
  "type": "UPDATE_FAILED",
  "code": 21001,
  "sub_type": "UPDATE_TEMPORARILY_UNAVAILABLE",
  "message": "Update is temporarily unavailable for this account."
}
```

***


# Vehicle Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/vehicle-errors



## Request Errors

The request to the `/entities/{entity_id}/vehicles` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `PRODUCT_UNAVAILABLE_ENTITY_DISABLED`

This Entity does not support retrieving Entity's vehicles.

### `TEAM_CAPABILITY_RESTRICTED`

Your organization does not have access to Vehicles endpoint.

### `ENTITY_VERIFICATION_MISSING`

Entity must be verified before it can access `/entities/{entity_id}/vehicles` endpoint.

### `TOO_MANY_REQUESTS`

The maximum request limit for this time has been exceeded. Please try again later.

***

## Resource Errors

Errors set on a Vehicle's `error` property for processes that are unsuccessful.

### `NO_VEHICLES_FOUND`

No vehicles found for this entity.

```json theme={null}
{
  "type": "INVALID_REQUEST",
  "sub_type": "NO_VEHICLES_FOUND",
  "message": "No vehicles found for this Entity."
}
```

***


# Webhook Errors
Source: https://docs.methodfi.com/2026-03-30/reference/errors/webhook-errors



## Request Errors

The request to the `/webhooks/{webhook_id}` endpoint failed. These are the `sub_type` that can be returned.

### `INVALID_REQUEST`

The request body failed basic validation for the specific API endpoint.

### `NOT_FOUND`

The requested resource does not exist.

### `INVALID_WEBHOOK_STATUS`

The webhook status is invalid. Valid statuses are `active` and `disabled`.

### `INVALID_WEBHOOK_URL`

The webhook `url` must be a valid HTTPS URL that does not point to internal or private addresses.

### `MAX_ACTIVE_WEBHOOKS_EXCEEDED`

The maximum number of active webhooks for this event type has been reached.

### `MAX_WEBHOOK_METADATA_SIZE_EXCEEDED`

The maximum metadata object size of 1KB was exceeded.

### `WEBHOOK_ALREADY_EXISTS`

An active webhook already exists for this `url` and `type` combination.

### `WEBHOOK_AUTH_TOKEN_AND_HMAC_SECRET_SAME`

The `auth_token` and `hmac_secret` cannot have the same value.

### `WEBHOOK_PERMANENTLY_DELETED`

The status of a permanently deleted webhook cannot be updated.

***

## Resource Errors

Method changes a Webhook's status automatically when a delivery fails 5 times (the initial attempt and all retries) and more than 40% of the Webhook's delivery attempts within the rolling 24-hour window have failed. Within a team-configured grace period the status becomes `requires_attention` (codes `25006`–`25009`) and delivery continues; outside it, the Webhook is `disabled` (codes `25001`–`25004`).

Errors set on a webhook's `error` property for processes that are unsuccessful.

### `25001 – WEBHOOK_DISABLED_FAILED_OTHER`

There were 5 consecutive failures when posting to the webhook url provided where error was not a 4XX, 5XX error, or a timeout.

#### Causes

* This could happen for a variety of reason types, please reach out to the team for more specific information.

```json theme={null}
{
  "type": "WEBHOOK_DISABLED",
  "code": 25001,
  "sub_type": "WEBHOOK_DISABLED_FAILED_OTHER",
  "message": "Webhook automatically disabled after failing 5 times to connect. Error was not 4XX or 5XX type."
}
```

#### Resolution

The webhook will be disabled and will not proceed in posting again to the provided url.

### `25002 – WEBHOOK_DISABLED_RECEIVED_4XX_ERROR`

The webhook specifically received 4XX type errors when posting.

#### Causes

* Invalid resource URL
* Permission denied
* Forbidden

```json theme={null}
{
  "type": "WEBHOOK_DISABLED",
  "code": 25002,
  "sub_type": "WEBHOOK_DISABLED_RECEIVED_4XX_ERROR",
  "message": "Webhook failed 5 times with a client error (4XX type)."
}
```

#### Resolution

The webhook will be disabled and will not proceed in posting again to the provided url.

***

### `25003 – WEBHOOK_DISABLED_RECEIVED_5XX_ERROR`

The webhook specifically received 5XX type errors when posting.

#### Causes

* Internal server error (from webhook url)
* Not implemented
* Bad Gateway
* Server unavailable
* Gateway timeout

```json theme={null}
{
  "type": "WEBHOOK_DISABLED",
  "code": 25003,
  "sub_type": "WEBHOOK_DISABLED_RECEIVED_5XX_ERROR",
  "message": "Webhook failed 5 times with a server error (5XX type)."
}
```

#### Resolution

The webhook will be disabled and will not proceed in posting again to the provided url.

***

### `25004 – WEBHOOK_DISABLED_TIMEOUT_ON_RESPONSE`

When posting a information to a webhook url, our API did not receive a valid response in the 5 second period.

#### Causes

The timeout could happen for a variety of reasons:

* Bad network or firewall config
* Long processing time on webhook receiver side

```json theme={null}
{
  "type": "WEBHOOK_DISABLED",
  "code": 25004,
  "sub_type": "WEBHOOK_DISABLED_TIMEOUT_ON_RESPONSE",
  "message": "Webhook failed 5 times in receiving a response back from the webhook url provided. Expected response time is 5 seconds."
}
```

#### Resolution

The webhook will be disabled and will not proceed in posting again to the provided url.

If you've timed out, check network configs to allow method servers to hit your webhook endpoint.

Also confirm that after a payload has been posted to the webhook receiving url that successful responses are able to respond back in under 5 seconds. Typically this can be achieved by queuing the webhook data on your side and then immediately sending a 2xx response back, then processing the webhook information asynchronously.

***

### `25005 – WEBHOOK_DISABLED_BY_USER`

The Webhook was manually disabled.

#### Causes

* The Webhook's `status` was set to `disabled` through the [Update a Webhook](/2026-03-30/reference/webhooks/update) endpoint.

```json theme={null}
{
  "type": "WEBHOOK_DISABLED",
  "code": 25005,
  "sub_type": "WEBHOOK_DISABLED_BY_USER",
  "message": "Webhook was manually disabled by the user."
}
```

#### Resolution

Set the Webhook's `status` back to `active` when you want to resume deliveries.

***

### `25006 – WEBHOOK_REQUIRES_ATTENTION_FAILED_OTHER`

The Webhook entered `requires_attention` after failing 5 times with an error that was not a 4XX or 5XX response.

```json theme={null}
{
  "type": "WEBHOOK_REQUIRES_ATTENTION",
  "code": 25006,
  "sub_type": "WEBHOOK_REQUIRES_ATTENTION_FAILED_OTHER",
  "message": "Webhook requires attention after failing 5 times to connect. Error was not 4XX or 5XX type."
}
```

#### Resolution

The Webhook continues to receive events while in `requires_attention`. Investigate and fix the endpoint to avoid the Webhook being disabled.

***

### `25007 – WEBHOOK_REQUIRES_ATTENTION_RECEIVED_4XX_ERROR`

The Webhook entered `requires_attention` after failing 5 times with a client error (4XX type).

```json theme={null}
{
  "type": "WEBHOOK_REQUIRES_ATTENTION",
  "code": 25007,
  "sub_type": "WEBHOOK_REQUIRES_ATTENTION_RECEIVED_4XX_ERROR",
  "message": "Webhook requires attention after failing 5 times with a client error (4XX type)."
}
```

#### Resolution

The Webhook continues to receive events while in `requires_attention`. Investigate and fix the endpoint to avoid the Webhook being disabled.

***

### `25008 – WEBHOOK_REQUIRES_ATTENTION_RECEIVED_5XX_ERROR`

The Webhook entered `requires_attention` after failing 5 times with a server error (5XX type).

```json theme={null}
{
  "type": "WEBHOOK_REQUIRES_ATTENTION",
  "code": 25008,
  "sub_type": "WEBHOOK_REQUIRES_ATTENTION_RECEIVED_5XX_ERROR",
  "message": "Webhook requires attention after failing 5 times with a server error (5XX type)."
}
```

#### Resolution

The Webhook continues to receive events while in `requires_attention`. Investigate and fix the endpoint to avoid the Webhook being disabled.

***

### `25009 – WEBHOOK_REQUIRES_ATTENTION_TIMEOUT_ON_RESPONSE`

The Webhook entered `requires_attention` after failing 5 times to respond within the 5-second window.

```json theme={null}
{
  "type": "WEBHOOK_REQUIRES_ATTENTION",
  "code": 25009,
  "sub_type": "WEBHOOK_REQUIRES_ATTENTION_TIMEOUT_ON_RESPONSE",
  "message": "Webhook requires attention after failing 5 times in receiving a response back from the webhook url provided. Expected response time is 5 seconds."
}
```

#### Resolution

The Webhook continues to receive events while in `requires_attention`. Respond with a `2xx` status code within 5 seconds, processing webhook data asynchronously.


# Expanding Resources
Source: https://docs.methodfi.com/2026-03-30/reference/expanding



Many objects allow you to request additional information as an expanded response by using the expand query parameter.
This parameter is available for `entities`, `accounts`, and `Connect` and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response attributes. For example, an `Entity` might have an associated `CreditScore` ID.
You can expand these objects in line with the expand query parameter. The expandable label in this documentation indicates ID fields that you can expand into objects.

You can expand multiple objects at the same time by identifying multiple items in the expand array. Performing expansions on list requests might result in increased response times.

In the case of `Connect`, recursive expansion up to 2 levels is supported. The first level expands the returned `accounts`.
The second level allows expansion of any account-level properties using the notation `accounts.expandable_field`, such as `accounts.update`.
For more information, see <a href="/2026-03-30/reference/entities/connect/create#possible-enum-values">Connect Expand Enum</a>

## Props

<ParamList />

## Returns

Returns a list of the requested resource with the requested attributes expanded.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/entities/ent_BzirqpLEm3BW7?expand[]=connect" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const entity = await method
    .entities
    .retrieve("ent_BzirqpLEm3BW7", {
      expand: ["connect"],
    });
  ```

  ```python Python theme={null}
  entity = method
    .entities
    .retrieve('ent_BzirqpLEm3BW7', {
      'expand': ['connect'],
    })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
    {
      "id": "ent_BzirqpLEm3BW7",
      "type": "individual",
      "individual": {
        "first_name": "Kevin",
        "last_name": "Doyle",
        "phone": "+15121231113",
        "dob": "1997-03-18",
        "email": "kevin.doyle@gmail.com",
        "ssn_4": null,
        "ssn": null
      },
      "error": null,
      "address": {
        "line1": "3300 N Interstate 35",
        "line2": null,
        "city": "Austin",
        "state": "TX",
        "zip": "78705"
      },
      "status": "active",
      "verification": {
        "identity": {
          "verified": true,
          "matched": true,
          "latest_verification_session": "evf_mQ6yr6VVJLNEb",
          "methods": []
        },
        "phone": {
          "verified": true,
          "latest_verification_session": "evf_P4QXNj93Y9J8L",
          "methods": []
        }
      },
      "connect": {
        "id": "cxn_4ewMmBbjYDMR4",
        "entity_id": "ent_qKNBB68bfHGNA",
        "status": "completed",
        "accounts": [
          "acc_eKKmrXDpJBKgw",
          "acc_GV8WbmJW7KGRy",
          "acc_MLPKh9gQDDbT8",
          "acc_LbXE8wVYJLrKt",
          "acc_J3P9fayDFjpAy",
          "acc_eFFRV9zmpLREK"
        ],
        "error": null,
        "created_at": "2024-04-12T14:56:46.645Z",
        "updated_at": "2024-04-12T14:56:46.786Z"
      },
      "credit_score": "crs_pn4ca33GXFaCE",
      "identity": null,
      "products": [
        "connect",
        "credit_score"
      ],
      "restricted_products": [
        "identity",
        "attribute"
      ],
      "subscriptions": [],
      "available_subscriptions": [],
      "restricted_subscriptions": [
        "connect",
        "credit_score"
      ],
      "metadata": null,
      "created_at": "2024-04-12T14:56:34.710Z",
      "updated_at": "2024-04-12T14:56:34.744Z"

  }
  ```
</ResponseExample>


# Idempotency
Source: https://docs.methodfi.com/2026-03-30/reference/idempotency



Method's API supports idempotency for safely retrying requests without accidentally performing the
same operation twice. This helps avoid unwanted duplication in case of failures and retries. For
example, in the case of a timeout error, it is possible to safely retry sending the same API payment
call multiple times with the guarantee that the payment will only be created once.

Method's idempotency works by saving the resulting status code and body of the first request
made for any given idempotency key. Subsequent requests with the same key return the same
saved result. If the first request fails with a transient error (e.g. a network disruption
or a `500`), Method automatically reconciles the state of the request so that a retry with
the same key is safely reprocessed instead of replaying the error.

#### Enable idempotency

To submit a request for idempotent processing, send a request with
the `Idempotency-Key: <key>` header. The `<key>` can be any unique string
up to 255 characters long. (We recommend using V4 UUIDs). All `POST` requests accept
idempotency keys.

#### Recovering from errors

If a request submitted with an idempotency key fails with a transient error, such as a `500`,
a timeout, or a dropped connection, retry the request with the same parameters and the
same `Idempotency-Key`. Method automatically reconciles interrupted requests, so retrying
eventually returns a successful response, with the guarantee that the operation is performed
at most once.

Avoid switching to a new idempotency key without first confirming the request's status
with Method; this approach risks duplicating the operation. Retrying with the original key
is always safe.

In rare cases, a request cannot be automatically reconciled and its saved error will
continue to be returned. Method's team is automatically alerted when this happens and will
proactively reach out with the status of the affected requests. If you continue to receive
the same replayed error for a key, contact support to confirm the request's status. Once we
confirm that the operation was not performed, we can either clear the key so your retries
with the original key succeed, or you can safely retry with a new idempotency key.

#### Idempotency error

In the unlikely event that the idempotent data store is unavailable, the API returns
a `503` error status with a sub type of `IDEMPOTENCY_UNAVAILABLE`. If idempotency
is required, we recommend retrying your request later, otherwise, fall back to non-idempotent processing by
not submitting the `Idempotency-Key` header.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/payments \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Idempotency-Key: 24c47283-0cc8-43a0-8b4a-ce16d002de97" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 5000,
      "source": "acc_JMJZT6r7iHi8e",
      "destination": "acc_AXthnzpBnxxWP",
      "description": "Loan Pmt"
    }'
  ```

  ```javascript Node.js theme={null}
  const payment = await method.payments.create({
    amount: 5000,
    source: 'acc_JMJZT6r7iHi8e',
    destination: 'acc_AXthnzpBnxxWP',
    description: 'Loan Pmt',
  }, {
    idempotency_key: '24c47283-0cc8-43a0-8b4a-ce16d002de97',
  });
  ```

  ```python Python theme={null}
  payment = method.payments.create({
    'amount': 5000,
    'source': 'acc_JMJZT6r7iHi8e',
    'destination': 'acc_AXthnzpBnxxWP',
    'description': 'Loan Pmt',
  }, {
    'idempotency_key': '24c47283-0cc8-43a0-8b4a-ce16d002de97'
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "error": {
      "type": "API_ERROR",
      "code": 503,
      "sub_type": "IDEMPOTENCY_UNAVAILABLE",
      "message": "Idempotent requests are temporarily unavailable. To ensure idempotency try your request later, or fall back to a non-idempotent request."
    }
  }
  ```
</ResponseExample>


# Introduction
Source: https://docs.methodfi.com/2026-03-30/reference/introduction



Welcome to Method. Method's API enables financial connectivity to any consumer liability account, providing real-time, permissioned read/write access at every major financial institution.

Here you will find everything you need to get started with the Method API. If you have any questions, please email us at [team@methodfi.com](mailto:team@methodfi.com) or reach out via your shared Slack channel.


# Message-Level-Encryption (MLE)
Source: https://docs.methodfi.com/2026-03-30/reference/message-level-encryption

End-to-end encryption for sensitive data transmission

## What is Message Level Encryption?

Message Level Encryption (MLE) provides end-to-end encryption for sensitive data transmitted between your application and Method's API. Using a hybrid encryption approach, MLE ensures your data remains protected even if network traffic is intercepted.

MLE uses two layers of encryption:

* **Symmetric encryption** (AES-GCM) encrypts your actual data payload using a Content Encryption Key (CEK)
* **Asymmetric encryption** (RSA-OAEP-256) encrypts the CEK using Method's public key

This approach combines the efficiency of symmetric encryption with the security of public-key cryptography.

## Prerequisites

To use MLE with Method's API, you'll need:

* An RSA key pair for RSA-OAEP-256
* Ability to create and parse JWE (JSON Web Encryption) in compact serialization format

MLE requests require:

* Header: `Method-MLE: jwe`
* Content-Type: `application/json`
* Request body: `{"encrypted": "<compact dot separated JWE string>"}`

## Setup Guide

### Step 1: Generate Your RSA Key Pair

Generate an RSA key pair that will be used to receive encrypted responses from Method.

<CodeGroup>
  ```javascript Node.js theme={null}
  import { generateKeyPair, exportJWK } from 'jose';

  // Generate RSA key pair
  const { publicKey, privateKey } = await generateKeyPair('RSA-OAEP-256', {
    modulusLength: 2048,
  });

  // Export as JWK format
  const publicJwk = await exportJWK(publicKey);
  const privateJwk = await exportJWK(privateKey);

  // Add required fields to your public JWK
  publicJwk.alg = 'RSA-OAEP-256';
  publicJwk.use = 'enc';
  publicJwk.kid = 'your-unique-key-id'; // Choose a unique identifier

  // Store privateJwk securely (e.g., in your key management system)
  console.log('Public JWK:', publicJwk);
  ```

  ```python Python theme={null}
  from jwcrypto import jwk
  import json

  # Generate RSA key pair
  key = jwk.JWK.generate(kty='RSA', size=2048, alg='RSA-OAEP-256', use='enc')

  # Add a unique key ID
  key.kid = 'your-unique-key-id'

  # Export public and private keys
  public_jwk = json.loads(key.export_public())
  private_jwk = json.loads(key.export_private())

  # Store private_jwk securely
  print('Public JWK:', public_jwk)
  ```
</CodeGroup>

### Step 2: Register Your Public Key with Method

You can register your public key using either a well-known endpoint (recommended) or direct registration.

<Note>
  **Important**: Each key ID (`kid`) can only be registered once using either method. If you have a public key available through your well-known endpoint, you should not register the same public key through direct registration, even if you change the `kid`.
</Note>

#### Option A: Well-Known Endpoint (Recommended)

Host your public JWK at a well-known URL and register it with Method:

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch('https://production.methodfi.com/teams/mle/public_keys', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_your_token',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      type: 'well_known',
      contact: 'security@yourcompany.com',
      well_known_endpoint: 'https://api.yourcompany.com/.well-known/jwks.json'
    })
  });

  const result = await response.json();
  console.log('Registration result:', result);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://production.methodfi.com/teams/mle/public_keys',
      headers={
          'Authorization': 'Bearer sk_your_token',
          'Content-Type': 'application/json',
      },
      json={
          'type': 'well_known',
          'contact': 'security@yourcompany.com',
          'well_known_endpoint': 'https://api.yourcompany.com/.well-known/jwks.json'
      }
  )

  print('Registration result:', response.json())
  ```
</CodeGroup>

Your well-known endpoint should return:

```json theme={null}
{
  "keys": [
    {
      "kty": "RSA",
      "kid": "your-unique-key-id",
      "use": "enc",
      "alg": "RSA-OAEP-256",
      "n": "...",
      "e": "AQAB"
    }
  ]
}
```

### Requirements for keys on `.well-known` endpoint

1. Must have a top-level field named `keys` that has a list as its value.
2. For a JWK (an item in list of `keys`) to be valid the following must be met:
   1. JWK must be an object
   2. JWK must have a field named `kty` and it must be equal to `RSA`
   3. JWK must have a field `n` and it must be a string that is valid `n` for a JWK in accordance to the RFC
   4. JWK must have a field `e` and it must be a string that is valid `e` for a JWK in accordance to the RFC
   5. JWK can optionally have a field named `alg` but if it is provided the value must be `RSA-OAEP-256`
   6. JWK must have a field `kid` and it must be a string that is a valid `id` which will be passed as `cid` when making requests to Method

#### Option B: Direct Registration

Alternatively, register your public key directly:

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch('https://production.methodfi.com/teams/mle/public_keys', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_your_token',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      type: 'direct',
      contact: 'security@yourcompany.com',
      jwk: publicJwk // Your public JWK from Step 1
    })
  });
  ```

  ```python Python theme={null}
  response = requests.post(
      'https://production.methodfi.com/teams/mle/public_keys',
      headers={
          'Authorization': 'Bearer sk_your_token',
          'Content-Type': 'application/json',
      },
      json={
          'type': 'direct',
          'contact': 'security@yourcompany.com',
          'jwk': public_jwk  # Your public JWK from Step 1
      }
  )
  ```
</CodeGroup>

### Step 3: Retrieve Method's Public Key

Fetch Method's public key for encrypting your requests:

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch('https://production.methodfi.com/.well-known/jwks.json', {
    headers: {
      'Authorization': 'Bearer sk_your_token'
    }
  });

  const { keys } = await response.json();
  // Select an active key
  const methodPublicKey = keys.find(k => k.status === 'active');
  console.log('Method public key:', methodPublicKey);
  ```

  ```python Python theme={null}
  response = requests.get(
      'https://production.methodfi.com/.well-known/jwks.json',
      headers={'Authorization': 'Bearer sk_your_token'}
  )

  keys = response.json()['keys']
  # Select an active key
  method_public_key = next(k for k in keys if k['status'] == 'active')
  print('Method public key:', method_public_key)
  ```
</CodeGroup>

<Note>
  Method's public keys are environment-specific:

  * Production: `https://production.methodfi.com/.well-known/jwks.json`
  * Sandbox: `https://sandbox.methodfi.com/.well-known/jwks.json`
  * Development: `https://dev.methodfi.com/.well-known/jwks.json`
</Note>

## Making Encrypted Requests

### Step 1: Encrypt Your Request Payload

<CodeGroup>
  ```javascript Node.js theme={null}
  import { CompactEncrypt, importJWK } from 'jose';

  async function encryptForMethod(payload, methodPublicJwk, yourKeyId) {
    // Convert payload to bytes
    const encoder = new TextEncoder();
    const data = encoder.encode(JSON.stringify(payload));

    // Import Method's public key
    const methodPublicKey = await importJWK(methodPublicJwk, 'RSA-OAEP-256');

    // Create JWE
    const jwe = await new CompactEncrypt(data)
      .setProtectedHeader({
        alg: 'RSA-OAEP-256',
        enc: 'A256GCM',
        kid: methodPublicJwk.kid,  // Method's key ID
        cid: yourKeyId,            // Your key ID for response encryption
        typ: 'JWE'
      })
      .encrypt(methodPublicKey);

    return jwe;
  }

  // Example: Encrypt entity data
  const entityData = {
    type: 'individual',
    individual: {
      first_name: 'Kevin',
      last_name: 'Doyle',
      phone: '+16505551234',
      dob: '1997-03-18',
      ssn_4: '1111',
      address: {
        line1: '3300 N Interstate 35',
        city: 'Austin',
        state: 'TX',
        zip: '78705'
      }
    }
  };

  const encryptedJwe = await encryptForMethod(entityData, methodPublicKey, 'your-unique-key-id');
  ```

  ```python Python theme={null}
  from jwcrypto import jwe, jwk
  import json

  def encrypt_for_method(payload, method_public_jwk, your_key_id):
      # Import Method's public key
      method_key = jwk.JWK(**method_public_jwk)

      # Create JWE
      jwe_token = jwe.JWE(
          json.dumps(payload),
          recipient=method_key,
          protected=json.dumps({
              'alg': 'RSA-OAEP-256',
              'enc': 'A256GCM',
              'kid': method_public_jwk['kid'],  # Method's key ID
              'cid': your_key_id,               # Your key ID
              'typ': 'JWE'
          })
      )

      # Return compact serialization
      return jwe_token.serialize(compact=True)

  # Example: Encrypt entity data
  entity_data = {
      'type': 'individual',
      'individual': {
          'first_name': 'Kevin',
          'last_name': 'Doyle',
          'phone': '+16505551234',
          'dob': '1997-03-18',
          'ssn': '111223333',
          'address': {
              'line1': '3300 N Interstate 35',
              'city': 'Austin',
              'state': 'TX',
              'zip': '78705'
          }
      }
  }

  encrypted_jwe = encrypt_for_method(entity_data, method_public_key, 'your-unique-key-id')
  ```
</CodeGroup>

### Step 2: Send the Encrypted Request

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch('https://production.methodfi.com/entities', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_your_token',
      'Content-Type': 'application/json',
      'Method-MLE': 'jwe'  // Required for MLE
    },
    body: JSON.stringify({
      encrypted: encryptedJwe
    })
  });

  // Response will also be encrypted
  const encryptedResponse = await response.json();
  ```

  ```python Python theme={null}
  response = requests.post(
      'https://production.methodfi.com/entities',
      headers={
          'Authorization': 'Bearer sk_your_token',
          'Content-Type': 'application/json',
          'Method-MLE': 'jwe'  # Required for MLE
      },
      json={
          'encrypted': encrypted_jwe
      }
  )

  # Response will also be encrypted
  encrypted_response = response.json()
  ```
</CodeGroup>

### Step 3: Decrypt the Response

<CodeGroup>
  ```javascript Node.js theme={null}
  import { compactDecrypt, importJWK } from 'jose';

  async function decryptFromMethod(encryptedJwe, yourPrivateJwk, expectedCid) {
    // Import your private key
    const privateKey = await importJWK(yourPrivateJwk, 'RSA-OAEP-256');

    // Decrypt the JWE
    const { plaintext, protectedHeader } = await compactDecrypt(
      encryptedJwe,
      privateKey
    );

    // Verify the response is encrypted with your key
    if (protectedHeader.kid !== expectedCid) {
      throw new Error(`Unexpected key ID: ${protectedHeader.kid}`);
    }

    // Parse and return the decrypted data
    const decoder = new TextDecoder();
    return JSON.parse(decoder.decode(plaintext));
  }

  // Decrypt the response
  const decryptedData = await decryptFromMethod(
    encryptedResponse.encrypted,
    yourPrivateJwk,
    'your-unique-key-id'
  );
  console.log('Decrypted response:', decryptedData);
  ```

  ```python Python theme={null}
  from jwcrypto import jwe, jwk
  import json

  def decrypt_from_method(encrypted_jwe, your_private_jwk, expected_cid):
      # Import your private key
      private_key = jwk.JWK(**your_private_jwk)

      # Parse and decrypt the JWE
      jwe_token = jwe.JWE()
      jwe_token.deserialize(encrypted_jwe)
      jwe_token.decrypt(private_key)

      # Verify the response is encrypted with your key
      protected_header = json.loads(jwe_token.jose_header)
      if protected_header['kid'] != expected_cid:
          raise ValueError(f"Unexpected key ID: {protected_header['kid']}")

      # Return the decrypted data
      return json.loads(jwe_token.payload)

  # Decrypt the response
  decrypted_data = decrypt_from_method(
      encrypted_response['encrypted'],
      private_jwk,
      'your-unique-key-id'
  )
  print('Decrypted response:', decrypted_data)
  ```
</CodeGroup>

## Complete Example

Here's a complete example showing the full MLE flow:

<CodeGroup>
  ```javascript Node.js theme={null}
  import { generateKeyPair, exportJWK, CompactEncrypt, compactDecrypt, importJWK } from 'jose';

  async function mleExample() {
    // 1. Generate your key pair (one-time setup)
    const { publicKey, privateKey } = await generateKeyPair('RSA-OAEP-256');
    const publicJwk = await exportJWK(publicKey);
    const privateJwk = await exportJWK(privateKey);

    publicJwk.alg = 'RSA-OAEP-256';
    publicJwk.use = 'enc';
    publicJwk.kid = 'my-key-2024';

    // 2. Register your public key with Method
    await fetch('https://production.methodfi.com/teams/mle/public_keys', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sk_your_token',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        type: 'direct',
        contact: 'security@example.com',
        jwk: publicJwk
      })
    });

    // 3. Get Method's public key
    const methodKeysResponse = await fetch('https://production.methodfi.com/.well-known/jwks.json', {
      headers: { 'Authorization': 'Bearer sk_your_token' }
    });
    const { keys } = await methodKeysResponse.json();
    const methodPublicKey = keys.find(k => k.status === 'active');

    // 4. Encrypt your request
    const payload = {
      type: 'individual',
      individual: {
        first_name: 'Kevin',
        last_name: 'Doyle',
        ssn: '111223333'
      }
    };

    const methodKey = await importJWK(methodPublicKey, 'RSA-OAEP-256');
    const encryptedJwe = await new CompactEncrypt(
      new TextEncoder().encode(JSON.stringify(payload))
    )
      .setProtectedHeader({
        alg: 'RSA-OAEP-256',
        enc: 'A256GCM',
        kid: methodPublicKey.kid,
        cid: 'my-key-2024',
        typ: 'JWE'
      })
      .encrypt(methodKey);

    // 5. Send encrypted request
    const response = await fetch('https://production.methodfi.com/entities', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sk_your_token',
        'Content-Type': 'application/json',
        'Method-MLE': 'jwe'
      },
      body: JSON.stringify({ encrypted: encryptedJwe })
    });

    // 6. Decrypt response
    const { encrypted } = await response.json();
    const { plaintext } = await compactDecrypt(encrypted, await importJWK(privateJwk));
    const result = JSON.parse(new TextDecoder().decode(plaintext));

    console.log('Created entity:', result);
  }
  ```

  ```python Python theme={null}
  from jwcrypto import jwk, jwe
  import json
  import requests

  def mle_example():
      # 1. Generate your key pair (one-time setup)
      key = jwk.JWK.generate(kty='RSA', size=2048, alg='RSA-OAEP-256', use='enc')
      key.kid = 'my-key-2024'

      public_jwk = json.loads(key.export_public())
      private_jwk = json.loads(key.export_private())

      # 2. Register your public key with Method
      requests.post(
          'https://production.methodfi.com/teams/mle/public_keys',
          headers={
              'Authorization': 'Bearer sk_your_token',
              'Content-Type': 'application/json',
          },
          json={
              'type': 'direct',
              'contact': 'security@example.com',
              'jwk': public_jwk
          }
      )

      # 3. Get Method's public key
      response = requests.get(
          'https://production.methodfi.com/.well-known/jwks.json',
          headers={'Authorization': 'Bearer sk_your_token'}
      )
      keys = response.json()['keys']
      method_public_key = next(k for k in keys if k['status'] == 'active')

      # 4. Encrypt your request
      payload = {
          'type': 'individual',
          'individual': {
              'first_name': 'Kevin',
              'last_name': 'Doyle',
              'ssn': '111223333'
          }
      }

      method_key = jwk.JWK(**method_public_key)
      jwe_token = jwe.JWE(
          json.dumps(payload),
          recipient=method_key,
          protected=json.dumps({
              'alg': 'RSA-OAEP-256',
              'enc': 'A256GCM',
              'kid': method_public_key['kid'],
              'cid': 'my-key-2024',
              'typ': 'JWE'
          })
      )
      encrypted_jwe = jwe_token.serialize(compact=True)

      # 5. Send encrypted request
      response = requests.post(
          'https://production.methodfi.com/entities',
          headers={
              'Authorization': 'Bearer sk_your_token',
              'Content-Type': 'application/json',
              'Method-MLE': 'jwe'
          },
          json={'encrypted': encrypted_jwe}
      )

      # 6. Decrypt response
      encrypted_response = response.json()['encrypted']
      response_jwe = jwe.JWE()
      response_jwe.deserialize(encrypted_response)
      response_jwe.decrypt(key)

      result = json.loads(response_jwe.payload)
      print('Created entity:', result)
  ```
</CodeGroup>

## Error Handling

When using MLE, you may encounter these specific error codes:

| **Error Type Code** | **Error Subtype Code**                     | **HTTP Status** | **Description**                                                                                                                               |
| ------------------- | ------------------------------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `api_error`         | `MLE_DECRYPTION_FAILED`                    | 500             | Message level encryption (MLE) requests are temporarily unavailable. To ensure MLE try your request later, or fall back to a non-MLE request. |
| `api_error`         | `MLE_ENCRYPTION_FAILED`                    | 500             | Message level encryption (MLE) requests are temporarily unavailable. To ensure MLE try your request later, or fall back to a non-MLE request. |
| `api_error`         | `PAYLOAD_INVALID_JSON`                     | 400             | The request body is not valid JSON.                                                                                                           |
| `invalid_request`   | `MLE_INVALID_HEADER`                       | 400             | When using message level encryption the header 'Method-MLE' must be set to 'jwe'.                                                             |
| `invalid_request`   | `MLE_MISSING_ENCRYPTED_PAYLOAD`            | 400             | When using message level encryption the payload must contain field 'encrypted'                                                                |
| `invalid_request`   | `MLE_UNSUPPORTED_KEY_MANAGEMENT_ALGORITHM` | 400             | Key management algorithm provided is not supported. Must use 'RSA-OAEP-256'                                                                   |
| `invalid_request`   | `MLE_INVALID_ENCRYPTION_ALGORITHM`         | 400             | Unsupported or missing "enc" in protected header. Expected one of: 'A256GCM' or 'A128GCM'.                                                    |
| `invalid_request`   | `MLE_MUST_INCLUDE_KID`                     | 400             | Must include 'KID' in protected header.                                                                                                       |
| `invalid_request`   | `MLE_MUST_INCLUDE_CID`                     | 400             | Must include 'CID' in protected header.                                                                                                       |
| `invalid_request`   | `MLE_INVALID_KID`                          | 400             | The JWK KID is either disabled or does not exist.                                                                                             |
| `invalid_request`   | `MLE_INVALID_CID`                          | 400             | The JWK CID is either disabled or does not exist.                                                                                             |
| `invalid_request`   | `MLE_INVALID_JWE_FORMAT`                   | 400             | The MLE "encrypted" payload must be in the RFC compatible compact format.                                                                     |
| `invalid_request`   | `WELL_KNOWN_ENDPOINT_ALREADY_EXISTS`       | 400             | An active well-known endpoint already exist. Must delete already existing well-known endpoint to post a new one.                              |
| `invalid_request`   | `JWK_KID_ALREADY_EXISTS`                   | 400             | The specified JWK KID already exists.                                                                                                         |
| `invalid_request`   | `JWK_ALREADY_DISABLED`                     | 400             | The specified JWK is already disabled.                                                                                                        |
| `invalid_request`   | `JWK_ALREADY_EXISTS`                       | 400             | The specified JWK's public content matches another key you have posted. Based on thumbprint from `n` , `e` , `kty` .                          |

## Performance Considerations

* MLE requests have increased latency due to encryption/decryption operations
* Consider implementing request timeouts appropriately
* Cache Method's public keys (respect the `Cache-Control` header)

## Key Lifecycle and Management

### Method's Key Status

Method's public keys have two possible statuses:

* **Active**: Current keys that should be used for encryption
* **Deprecated**: Keys that are being phased out and will be disabled in 90 days

Always use keys with `status: "active"` when fetching Method's public keys. Deprecated keys remain functional for 90 days before being completely disabled.

### Your Key Management

When you successfully register a key with Method, you'll receive a response like this:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "team_jwk_12345",
    "type": "well_known",
    "jwk": "",
    "well_known_endpoint": "https://your-svc/.well-known/jwks.json",
    "status": "active",
    "contact": "",
    "created_at": "",
    "updated_at": ""
  },
  "message": null
}
```

### MLE Public Keys API

For complete CRUD operations on your MLE public keys, see the dedicated API documentation:

* **[Create MLE Public Key](/2026-03-30/reference/teams/mle/create)** - Register a new public key
* **[List MLE Public Keys](/2026-03-30/reference/teams/mle/list)** - Get all your registered keys
* **[Retrieve MLE Public Key](/2026-03-30/reference/teams/mle/retrieve)** - Get a specific key by ID
* **[Delete MLE Public Key](/2026-03-30/reference/teams/mle/delete)** - Delete (disable) a specific key

### Quick Key Deletion Example

You can delete your registered keys using the `id` returned when you created the key:

<CodeGroup>
  ```javascript Node.js theme={null}
  const response = await fetch('https://production.methodfi.com/teams/mle/public_keys/team_jwk_12345', {
    method: 'DELETE',
    headers: {
      'Authorization': 'Bearer sk_your_token'
    }
  });

  const result = await response.json();
  console.log('Deletion result:', result);
  ```

  ```python Python theme={null}
  response = requests.delete(
      'https://production.methodfi.com/teams/mle/public_keys/team_jwk_12345',
      headers={
          'Authorization': 'Bearer sk_your_token'
      }
  )

  print('Deletion result:', response.json())
  ```
</CodeGroup>

### Key Rotation Best Practices

* Method recommends rotating your keys every 90 days
* Always check for keys with `status: "active"` when fetching Method's keys
* Plan your key rotation to avoid service interruptions

### Webhook Notifications

You can subscribe to webhook events to be notified when Method's public keys change:

| Event Type          | Description                                                     |
| ------------------- | --------------------------------------------------------------- |
| `method_jwk.create` | Triggered when a new Method JWK (public key) is created         |
| `method_jwk.update` | Triggered when a Method JWK is updated (deprecated or disabled) |

These webhooks help you stay informed about Method's key lifecycle changes, allowing you to:

* Automatically fetch new active keys when they're created
* Update your cached keys when Method rotates or deprecates keys
* Implement proactive key management in your application

When a webhook is triggered, the event payload includes a `path` field pointing to the specific key that changed. You can use this path to retrieve the updated key information via the [Retrieve Method Public Key](/2026-03-30/reference/teams/mle/retrieve-method-key) endpoint.

Example webhook event:

```json theme={null}
{
  "id": "mthd_jwk_12",
  "type": "method_jwk.update",
  "path": "/auth/mthd_jwk_12",
  "event": "evt_knqJgxKUnqDVJ"
}
```

To subscribe to these events, create a webhook using the [Webhooks API](/2026-03-30/reference/webhooks/create) with the desired event type.

## Fallback Strategy

If MLE is temporarily unavailable (indicated by `MLE_DECRYPTION_FAILED` or `MLE_ENCRYPTION_FAILED` errors), you can fall back to standard non-encrypted requests by:

1. Remove the `Method-MLE: jwe` header
2. Send your payload directly (not wrapped in `encrypted`)
3. Process the plain response normally

This ensures your integration remains functional even during MLE service interruptions.


# Metadata
Source: https://docs.methodfi.com/2026-03-30/reference/metadata



Method allows you to provide arbitrary data upon creation of any Core API resource. This
data is referred to as **metadata** and will be returned as the `metadata` attribute
on any Core API resource.

Adding metadata to Core API resources is useful if you want to provide additional identifiers
that reference specific records or rows in your own database.

## Props

<ParamField type="object">
  A valid JSON object that must be less than 1KB in size when serialized.
</ParamField>

## Returns

Returns the created resource with the provided metadata object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "individual",
      "individual": {
        "first_name": "Kevin",
        "last_name": "Doyle",
        "phone": "+16505555555",
        "email": "kevin.doyle@gmail.com",
        "dob": "1997-03-18"
      },
      "metadata": {
        "user_id": "usr_jVFNtdlhDQnd92",
        "username": "kdoyle"
      }
    }'
  ```

  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "individual",
      "individual": {
        "first_name": "Kevin",
        "last_name": "Doyle",
        "phone": "+16505555555",
        "email": "kevin.doyle@gmail.com",
        "dob": "1997-03-18"
      },
      "metadata": {
        "user_id": "usr_jVFNtdlhDQnd92",
        "username": "kdoyle"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const entity = await method.entities.create({
    type: 'individual',
    individual: {
      first_name: 'Kevin',
      last_name: 'Doyle',
      phone: '+16505555555',
      email: 'kevin.doyle@gmail.com',
      dob: '1997-03-18',
    },
    metadata: {
      user_id: 'usr_jVFNtdlhDQnd92',
      username: 'kdoyle',
    }
  });
  ```

  ```python Python theme={null}
  entity = method.entities.create({
    'type': 'individual',
    'individual': {
      'first_name': 'Kevin',
      'last_name': 'Doyle',
      'phone': '+16505555555',
      'email': 'kevin.doyle@gmail.com',
      'dob': '1997-03-18'
    },
    'metadata': {
      'user_id': 'usr_jVFNtdlhDQnd92',
      'username': 'kdoyle'
    }
  })
  ```
</RequestExample>


# Mutual TLS (mTLS)
Source: https://docs.methodfi.com/2026-03-30/reference/mtls

Optional client-certificate authentication for teams that require it

## What is mTLS?

Mutual TLS (mTLS) adds an optional second layer of authentication to your Method integration. In addition to your API key, your application presents a client certificate on every request, and Method verifies that certificate before processing the call.

mTLS is **optional and opt-in**. It is available for teams that require it and must be provisioned per team and per environment before it takes effect. Teams that are not provisioned for mTLS continue to authenticate with their API key alone and are unaffected.

If you are interested in mTLS, contact your Method representative to have your team provisioned.

## What changes with mTLS

You continue to call the standard Method hostnames. The hostnames are the same whether or not your team uses mTLS.

```
dev.methodfi.com
sandbox.methodfi.com
production.methodfi.com
```

Once your team is provisioned for mTLS, **both** of the following are required on every request:

1. A valid client certificate
2. Your normal Method credential (an API key or OAuth access token)

After provisioning, requests without a valid client certificate are rejected, and your API key alone is no longer sufficient. Until your team is provisioned, mTLS is not enforced and your existing requests continue to work unchanged.

## Getting a client certificate

You generate a private key and a certificate signing request (CSR). You send Method the CSR, and Method returns a signed client certificate.

1. Generate your private key and CSR (see below).
2. Send Method the CSR.
3. Method returns `client.pem`, and on first issuance the CA `chain.pem` if you need it for your trust store.

<Note>
  Exchange files with Method over email or another secure channel. Your Method representative will coordinate the exchange and confirm the approved Subject DN before you generate the CSR.
</Note>

## Generate a private key and CSR

Run the following, replacing the placeholders in `-subj` with your approved values:

```bash theme={null}
openssl req -new \
  -newkey rsa:2048 \
  -nodes \
  -keyout client.key \
  -out client.csr \
  -subj "/C=US/O=<Your Organization>/OU=<Org Unit>/CN=<Approved Client Identity>"
```

This produces two files, `client.key` and `client.csr`. `client.csr` is your certificate signing request and should be sent to Method.

<Warning>
  Never send anyone your private key (`client.key`).
</Warning>

## Making authenticated requests

Present your client certificate and private key alongside your API key on every request:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities \
    --cert client.pem \
    --key client.key \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Method-Version: 2026-03-30"
  ```
</CodeGroup>

If you received a CA chain from Method for your trust store, pass it as the trusted CA (`--cacert chain.pem` with cURL, or the equivalent in your HTTP client).

## Error handling

When mTLS is enforced for your team, requests that fail certificate validation return a `401` or `403`. See [mTLS Errors](/2026-03-30/reference/errors/mtls-errors) for the full list and response bodies.

## Certificate rotation

Renew your certificate before it expires:

1. Generate a new private key and CSR.
2. Send Method the new CSR.
3. Method registers the new certificate.
4. Deploy the new certificate. Both the old and new certificates remain valid during an agreed overlap window.
5. Method removes authorization for the old certificate once you confirm the switch.

<Note>
  If your Subject DN does not change between renewals, no configuration change is needed on Method's side.
</Note>


# Pagination
Source: https://docs.methodfi.com/2026-03-30/reference/pagination



Core API endpoints that list records are returned in chronological order, with the earliest created
resource showing up first. You may optionally provide the following pagination parameters to limit the
returned records.

## Props

<ParamField type="string">
  ISO 8601 formatted date (YYYY-MM-DD) to filter for records created on or after the date provided.
</ParamField>

<ParamField type="string">
  ISO 8601 formatted date (YYYY-MM-DD) to filter for records created on or before the date provided.
</ParamField>

<ParamField type="string">
  The page number to return.
</ParamField>

<ParamField type="string">
  The ID of a resource from which a page should start or end. Mutually exclusive with `page`.
</ParamField>

<ParamField type="string">
  The number of records to return per page. Default and maximum is 100.
</ParamField>

## Returns

Returns a list of the requested resource with the applied pagination. Additionally, the following headers are returned with the response:

#### Response pagination headers

| Key                           | Description                                       |
| ----------------------------- | ------------------------------------------------- |
| `Pagination-Page`             | The current page.                                 |
| `Pagination-Page-Count`       | The total number of pages available.              |
| `Pagination-Page-Limit`       | The number of records to return per page.         |
| `Pagination-Total-Count`      | The total number of records matching the request. |
| `Pagination-Page-Cursor-Prev` | The previous page cursor.                         |
| `Pagination-Page-Cursor-Next` | The next page cursor.                             |

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/payments?page_limit=1&to_date=2020-12-10" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const payments = await method.payments.list({
    page_limit: 1,
    to_date: '2020-12-10',
  });
  ```

  ```python Python theme={null}
  payments = method.payments.list({
    'page_limit': 1,
    'to_date': '2020-12-10'
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "id": "pmt_rPrDPEwyCVUcm",
        "reversal_id": null,
        "source_trace_id": null,
        "destination_trace_id": null,
        "source": "acc_JMJZT6r7iHi8e",
        "destination": "acc_AXthnzpBnxxWP",
        "amount": 5000,
        "description": "Loan Pmt",
        "status": "pending",
        "error": null,
        "metadata": null,
        "estimated_completion_date": "2020-12-11",
        "source_settlement_date": "2020-12-09",
        "destination_settlement_date": "2020-12-11",
        "created_at": "2020-12-09T00:42:31.209Z",
        "updated_at": "2020-12-09T00:43:30.996Z"
      }
    ]
  }
  ```
</ResponseExample>


# Rate Limiting
Source: https://docs.methodfi.com/2026-03-30/reference/rate-limiting



Method enforces rate limits on all API requests to protect platform stability and ensure
fair usage across all customers. Rate limits apply to all environments (Development, Sandbox,
and Production) and all API versions.

## How rate limits work

Rate limits are applied **per API key** within a **60-second rolling window**. Limits are
organized into tiers based on operation type — more sensitive operations (such as payment
creation) have stricter limits, while high-volume read and write operations have more
generous allowances.

Each tier tracks its own counter independently, so usage against one tier does not affect
your capacity in another.

When a rate limit is exceeded, requests matching that tier are blocked for 60 seconds,
after which requests are automatically accepted again.

<Note>
  The same rate limits apply across all environments (Development, Sandbox, and Production).
  Rate limits encountered during testing in Development or Sandbox reflect the same thresholds
  your integration will experience in Production.
</Note>

## Rate limit tiers

| Tier                | Limit (requests per minute) | Description                                                            |
| ------------------- | --------------------------- | ---------------------------------------------------------------------- |
| Payment creation    | 120                         | `POST /payments`                                                       |
| Critical operations | 60                          | Payment deletion and report generation                                 |
| Standard writes     | 6,000                       | Entity and Account operations (create, update, connect, subscriptions) |
| Other writes        | 1,800                       | All other write operations                                             |
| Reads               | 6,000                       | All `GET` requests                                                     |
| Unauthenticated     | 60                          | Per IP address, requests without an API key                            |

Standard write operations are further divided into independent buckets by resource and
operation type — for example, account creation and entity creation each have their own
6,000 rpm allowance and do not compete with each other.

## Rate limit response

When rate limited, the API returns an HTTP `429` status code with the following response body:

```json theme={null}
{
  "success": false,
  "data": {
    "error": {
      "type": "INVALID_REQUEST",
      "code": 429,
      "sub_type": "TOO_MANY_REQUESTS",
      "message": "The maximum request limit for this time has been exceeded. Please re-try your request at a later time."
    }
  },
  "message": "The maximum request limit for this time has been exceeded. Please re-try your request at a later time."
}
```

## Handling rate limits

When you receive a `429` response, the block lasts for 60 seconds. Retrying immediately
will not succeed. We recommend the following approach:

1. **Wait at least 60 seconds** before retrying the request.
2. **Use exponential backoff with jitter** if subsequent attempts are still rate limited.
   Add randomness to retry intervals to prevent multiple clients from retrying in sync.
3. **Combine with [idempotency keys](/2026-03-30/reference/idempotency)** on `POST` requests to ensure
   retried requests are not processed more than once.

<Note>
  If your integration regularly approaches rate limits, consider spreading requests over time
  rather than sending them in bursts. Smoothing traffic reduces the chance of hitting tier
  limits during peak operations.
</Note>

## Enterprise rate limits

Customers with high-volume integrations can request custom rate limits tailored to their usage patterns. Contact your customer success manager or reach out to our team to discuss enterprise rate limit overrides.


# Request IDs
Source: https://docs.methodfi.com/2026-03-30/reference/request-id



All API requests are identified by a request ID designed to ensure that every request and response is traceable and logged efficiently.
This ID is returned in the `Request-Id` header of the response. The request ID is useful for facilitating easy tracking and debugging of requests.

We highly recommend logging the request ID for every API request you make. If you need to contact support, providing the request ID will help us resolve your issue more quickly.

<RequestExample>
  ```bash cURL theme={null}
  curl -i "https://production.methodfi.com/ping" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  import { Method } from 'method-node';

  const method_client = new Method({ apiKey, env });

  const health_check = await method_client.ping();

  console.log(health_check.last_response.request_id);
  ```

  ```python Python theme={null}
  from method import Method

  method_client = Method(api_key=api_key, env=env)

  health_check = method_client.ping()

  print(health_check.last_response.request_id)
  ```
</RequestExample>


# Versioning
Source: https://docs.methodfi.com/2026-03-30/reference/versioning



#### API Versioning

When updates are incompatible with previous versions (backwards-incompatible), a new, dated version of the API is released. The current version is: `2026-03-30`

API versions are specified using the `Method-Version` header, and while you may continue using older versions, you will not have access to the latest features.

You can upgrade to the latest or a specific version through the [Dashboard](https://dashboard.methodfi.com), or by specifying the version in request headers. Note that once upgraded manually, it's not possible to revert to older versions.

#### Backwards Compatible Changes

Method defines the following changes as backwards-compatible:

* Adding new API resources.
* Adding new properties to existing API responses.
* Adding new values to enum fields in API responses.
* Adding new properties to webhook payloads.
* Changes to the length, format, or content of human-readable strings (error messages, etc.).
* Adding new event types.
  * Make sure that your webhook logic can gracefully handle unfamiliar event types.

#### Library Versioning

For Method Libraries, the version is locked to the dated version of the API.

* `method-node v0.x.x` and `method-python v0.x.x` are locked to `2020-12-06`
* `method-node v1.x.x` and `method-python v1.x.x` are locked to `2024-04-04`
* `method-node v2.0.x` and `method-python v2.0.x` are locked to `2025-07-04`
* `method-node v2.1.0+` and `method-python v2.1.0+` are locked to `2025-12-01`

Use the version dropdown in the navigation bar to view documentation for your API version.

For detailed version histories, refer to our [Changelog](/changelog).

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/payments?page_limit=1&to_date=2020-12-10" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```
</RequestExample>


# Handling Account Edge Cases
Source: https://docs.methodfi.com/guides/accounts/edge-cases

How to handle verification requirements, product limitations, and status changes.

## Handling Account Edge Cases

### 1. Accounts Requiring Verification

Some liability accounts discovered through [Connect](/guides/connect/overview) may appear in `restricted_products` with capabilities that require elevated verification (e.g., an account verification session). This is common for payment-capable accounts where Method needs additional confirmation. Create an [Account Verification Session](/reference/accounts/verification-sessions/create) to unlock these products.

### 2. Product Limitations by Account Type

Not all accounts support all products. Credit cards support [Card Brand](/reference/accounts/card-brands/overview) and [Payment Instruments](/reference/accounts/payment-instruments/overview); auto loans support [Payoffs](/reference/accounts/payoffs/overview); most liability types support [Updates](/guides/updates/overview) and [Balances](/reference/accounts/balances/overview). Always check the `products` array. See the [Liability Types](/guides/accounts/liability-types) page for a breakdown.

### 3. Status Changes Mid-Operation

If an account transitions to `disabled` or `closed` while you have in-flight operations (a pending payment, an in-progress update), those operations may fail. Design your flows to:

* Check account status before initiating operations
* Handle `account.disabled` and `account.closed` [webhooks](/reference/webhooks/overview) gracefully
* Show appropriate UI messages when an account is no longer available

See the [Account Lifecycle](/guides/accounts/lifecycle) guide for status transitions and webhook details.

### 4. Duplicate Accounts

[Connect](/guides/connect/overview) may discover the same underlying account multiple times if the user has accounts reported under slightly different names or through different credit bureaus. Method does attempt to de-duplicate these liability accounts, however instances do occur. Reach out to your CSM if this uncommon event occurs for one of your users.

### 5. Authorized User Accounts

Connect discovers all accounts on a user's credit report, including accounts where they are an authorized user (not the primary holder). The `liability.ownership` field indicates the relationship: `primary`, `authorized`, `joint`, or `unknown`. Consider whether your product should treat authorized-user accounts differently (e.g., payments on authorized-user cards may not be appropriate for [debt consolidation flows](/guides/use-cases/lending/debt-consolidation)).

### 6. Closed / Paid-Off Accounts

Accounts with zero balance or closed status at the financial institution may still appear in Connect results (they remain on the credit report). These accounts will have `status: closed` and limited [product](/reference/accounts/products/overview) availability. Filter them in your UI if they're not relevant to your use case.

### 7. Consent and Data Retention

When an Entity's consent is withdrawn (via the [Consent endpoint](/reference/accounts/consent/withdraw)), their accounts are disabled and data access is revoked. Your application should handle this gracefully — remove the accounts from active views and inform the user.

***

The key principle: design your application to check account status and product availability dynamically, and listen for [webhook notifications](/reference/webhooks/overview) about status changes. Accounts are living objects, and your application should respond to their state changes in real time rather than assuming a static state.

For the full Accounts API, see the [Accounts reference](/reference/accounts/overview).


# Funding Accounts
Source: https://docs.methodfi.com/guides/accounts/funding

Setting up and verifying your corporate payment source.

## Funding Accounts — Setting Up Payment Sources

Before payments can flow through Method, your platform needs a verified funding source — an ACH account that serves as the origin for all outbound payments. This is typically your company's corporate checking account, not an account belonging to your end users.

Your platform creates the funding account by [calling the Accounts API](/reference/accounts/create) with the routing number and account number for your corporate bank account:

```bash theme={null}
curl https://production.methodfi.com/accounts \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "holder_id": "ent_y1a9e1fbnJ1f3",
    "ach": {
      "routing": "021000021",
      "number": "1234567890",
      "type": "checking"
    }
  }'
```

The account must then be verified to confirm your organization controls it. Once verified, this single funding account can serve as the payment source across all of your users' liability payments.

<Note>
  Funding accounts are set up by your team (the platform integrating with Method), not by your end users. End users interact with liability accounts discovered through Connect — your corporate funding account is the source that powers payments to those liabilities.
</Note>

Method supports several verification approaches for funding accounts:

<CardGroup>
  <Card title="Micro-Deposits" icon="coins">
    The traditional verification method. Method sends two small deposits (typically a few cents each) to your corporate bank account. Your team confirms the deposit amounts, proving control of the account. This is universally supported but introduces a 1–2 business day delay while deposits settle.
  </Card>

  <Card title="Plaid" icon="bolt">
    Instant verification through Plaid's bank linking flow. If your platform already uses Plaid, this is a natural fit — authenticate with your bank through Plaid, and the verified account details are passed to Method. No waiting for micro-deposits.
  </Card>

  <Card title="MX" icon="bolt">
    Similar instant verification through MX's bank connectivity platform. Choose this if your platform uses MX for bank account linking.
  </Card>

  <Card title="Teller" icon="bolt">
    Another instant verification path through Teller's banking API. Like Plaid and MX, this eliminates the micro-deposit delay by verifying the account through direct bank authentication.
  </Card>
</CardGroup>

<Note>
  For most teams, instant verification (via Plaid, MX, or Teller) is strongly preferred because it eliminates the multi-day delay of micro-deposits and simplifies initial setup. If you don't have an existing relationship with any of these providers, Plaid is the most widely adopted option.
</Note>

## Verification Flow

1. Create the funding account ([`POST /accounts`](/reference/accounts/create))
2. Create a verification session ([`POST /accounts/{id}/verification_sessions`](/reference/accounts/verification-sessions/create)) specifying your preferred method
3. Complete the verification:
   * **Micro-deposits**: Wait 1–2 business days, then [update the session](/reference/accounts/verification-sessions/update-microdeposits) with the deposit amounts
   * **Plaid / MX / Teller**: Pass the processor token from your aggregator to the update endpoint ([Plaid](/reference/accounts/verification-sessions/update-plaid), [MX](/reference/accounts/verification-sessions/update-mx), [Teller](/reference/accounts/verification-sessions/update-teller))
4. Listen for the `account.active` [webhook](/reference/webhooks/overview) — the account is now ready for payments

See the [Account Verification Sessions reference](/reference/accounts/verification-sessions/overview) for full API details.

<Warning>
  If verification fails (wrong micro-deposit amounts, invalid aggregator token), the verification session moves to a `failed` status. You can create a new verification session to retry. After 3 failed micro-deposit attempts, the account may require a fresh set of deposits.
</Warning>

<Note>
  Your team can have multiple verified funding accounts. When [creating a payment](/reference/payments/create), you specify which funding account to use as the source. Most teams use a single corporate checking account, but you can set up additional funding accounts if your business requires separate payment sources.
</Note>


# Supported Liability Types
Source: https://docs.methodfi.com/guides/accounts/liability-types

The full range of consumer debt types Method supports.

## The Breadth of Supported Liability Types

Method supports an extensive range of liability types, reflecting the diversity of consumer debt in the real world. Supported types include:

* Credit cards — `credit_card` (from major national issuers to regional and community banks)
* Auto loans — `auto_loan` (from captive lenders like GM Financial and Toyota Motor Credit to banks and credit unions)
* Federal and private student loans — `student_loans`
* Personal and installment loans — `personal_loan`
* Mortgages and home equity lines of credit (HELOCs) — `mortgage`
* Collections accounts — `collection`
* Medical debt — `medical`
* Insurance premium obligations — `insurance`
* Utility accounts — `utility`
* Buy Now Pay Later (BNPL) accounts — `bnpl`
* Credit builder accounts — `credit_builder`
* Fintech-originated loans — `fintech`
* Other loan types — `loan`

The values above are the possible `liability.type` enum values on an Account. The `liability.sub_type` field provides additional granularity (e.g., `federal` vs. `private` for student loans, `heloc` for home equity lines). See the [Account reference](/reference/accounts/overview) for the complete list.

## How Liability Type Affects the Data Model

Each liability type also determines what enrichment data is available:

* **Credit cards**: Card brand name and visual art (via [Card Brands](/reference/accounts/card-brands/overview)), tokenized card credentials (via [Payment Instruments](/reference/accounts/payment-instruments/overview))
* **Auto loans**: Payoff quotes (via [Payoffs](/reference/accounts/payoffs/overview)), vehicle details including VIN, make, model (via [Vehicles](/reference/entities/vehicles/overview) on the Entity)
* **Student loans**: Federal vs. private distinction, servicer information
* **All types**: Credit health attributes (via [Attributes](/reference/accounts/attributes/overview)) where credit bureau data exists

<Note>
  Not every liability type supports every Method product. For example, Payments may be available for credit cards and auto loans but not for certain utility or collections accounts. Card Brand data is only relevant for credit cards. Payoff quotes are specific to auto loans. Each account carries a list of available [products](/reference/accounts/products/overview) so your application can adapt its UI and functionality based on what's supported for each specific account.
</Note>


# Account Lifecycle
Source: https://docs.methodfi.com/guides/accounts/lifecycle

Account statuses, available products, and state transitions.

## Account Lifecycle and Status

Accounts move through a defined set of statuses that reflect their current state:

| Status         | Description                                                                                                                                                                                                                                                 |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Active**     | The account is fully connected, verified (if applicable), and ready for use. All supported products are available. This is the normal operating state for most accounts.                                                                                    |
| **Processing** | The account is being set up or verified. For liability accounts, this may be a brief transitional state during discovery. For funding accounts, this typically means verification is in progress (e.g., waiting for micro-deposit confirmation).            |
| **Disabled**   | The account has been deactivated within Method. The account may still be active at the financial institution, but Method will not perform new operations on it. This can happen if the account is flagged for an issue or explicitly disabled by your team. |
| **Closed**     | Method has detected that the account is closed at the financial institution. The debt may have been paid off, the card may have been canceled, or the loan may have been settled. No new operations are available, but historical data remains accessible.  |

<Warning>
  **Common causes of Disabled status:** the Entity's [consent](/reference/accounts/consent/withdraw) was withdrawn, the Entity's verification expired or was revoked, the account was flagged by Method's risk monitoring, or your team explicitly disabled it via the API. Check the account's `error` field for the specific reason.
</Warning>

## State Transitions

* **Processing → Active**: Account setup or verification completes successfully
* **Active → Disabled**: Account is flagged for an issue or explicitly disabled. May be reversible — listen for `account.active` webhooks
* **Active → Closed**: Method detects the account is closed at the financial institution (debt paid off, card canceled, loan settled)
* **Disabled → Active**: The issue is resolved and the account is re-enabled
* **Closed** is terminal — closed accounts do not reopen

<Note>
  **Webhook tip:** Subscribe to `account.active`, `account.disabled`, and `account.closed` [webhook events](/reference/webhooks/overview) to handle transitions in real time rather than polling.
</Note>

### Key Webhooks

* `account.active`: Account transitioned to Active
* `account.disabled`: Account was disabled
* `account.closed`: Account was closed
* `account.update.completed`: An [Update](/guides/updates/overview) finished (balance/data refreshed)

## Subscriptions: Automatic Data Refresh

Instead of manually requesting [Updates](/guides/updates/overview) or [Balances](/reference/accounts/balances/overview), you can subscribe an account to automatic refresh. When subscribed, Method periodically fetches fresh data and notifies you via webhook. See [Update Subscriptions](/guides/updates/subscriptions) for details.

The `subscriptions` and `available_subscriptions` arrays on each Account show what's currently active and what can be enabled.

## Products and the Lifecycle

Each account carries a `products` array — the list of Method capabilities currently available for that account. Products include: `update` (refresh balances/data), `balance` (real-time balance), `payment` (send funds to creditor), `card_brand` (card art and product name), `payoff` (auto loan payoff quotes), `sensitive` (full account numbers), `attribute` (credit health metrics), and `payment_instrument` (card tokenization).

Product availability depends on three factors:

1. **Account type**: `card_brand` only applies to credit cards, `payoff` only to auto loans (see [Liability Types](/guides/accounts/liability-types))
2. **Account status**: Disabled and Closed accounts lose most products
3. **Team configuration**: Some products require team-level enablement (check `restricted_products`)

Always check the `products` array before attempting an operation. Attempting an operation not in `products` will return an error. See the [Products reference](/reference/accounts/products/overview) for the full list.


# Accounts
Source: https://docs.methodfi.com/guides/accounts/overview

Liability and funding accounts — the financial objects at the heart of your product.

<Note>
  **Using Opal?** If you're using [Opal](/guides/opal), Method's embedded UI, liability account discovery is handled for you — users complete a soft credit pull and see their accounts inside Opal's Connect flow. You'll still work with the resulting `Account` objects in your backend for payments, monitoring, and ongoing display in your app. Funding accounts are always configured by your team via the API. The rest of this section is most relevant if you're building a custom integration or want to understand the underlying data model.
</Note>

## What a Method Account Represents

An Account in Method is a connected financial account that belongs to one of your users ([Entities](/guides/entities/overview)). Accounts are the objects your product primarily interacts with. You pull data from accounts, monitor accounts for changes, make payments to accounts, and build your user-facing displays around account information.

Every Account belongs to an [Entity](/guides/entities/overview), the person whose financial life you're working with. An Entity can have many Accounts (a typical consumer has 5–15 liability accounts). You'll interact with Accounts through the Entity that owns them: create an Entity, verify their identity, run [Connect](/guides/connect/overview) to discover their liabilities, then work with the resulting Account objects.

Every account in Method falls into one of two categories, and understanding this distinction is essential for designing your product's payment and data flows:

<Tabs>
  <Tab title="Liability Accounts">
    Represent debts and financial obligations. These are the credit cards, auto loans, other obligations that your users owe money on. Liability accounts are typically discovered automatically through [Connect](/guides/connect/overview) and serve as the destination for payments, this is where money goes when your user pays down debt.
  </Tab>

  <Tab title="Funding Accounts">
    Represent the bank account your platform pays from. This is typically your corporate checking or savings account linked via ACH that serves as the source of funds for all payments. Funding accounts are created by your team by providing routing and account number details, and must be verified before they can be used.
  </Tab>
</Tabs>

In payment flows, the model is simple: money flows from your platform's funding account (source) to a liability account (destination). Your corporate bank account funds the payment; the end user's creditor receives it.

## How Accounts Are Created

Liability accounts are typically discovered automatically through [Connect](/guides/connect/overview). When you run Connect for an Entity, Method pulls their credit report and creates `Account` objects for every discovered liability. You can also [create liability accounts manually via the API](/reference/accounts/create) if you have the account details.

Funding accounts are created by your team through the API by providing a routing number and account number. See [Funding Accounts](/guides/accounts/funding) for setup and verification details.

## Account Products: What You Can Do With an Account

Every Account carries two arrays that control what operations are available:

* `products`: Capabilities currently available (e.g., `balance`, `payment`, `update`, `card_brand`, `payoff`, `sensitive`, `payment_instrument`)
* `restricted_products`: Capabilities the account could support but require additional steps (like elevated verification or team-level enablement), or capabilities the account does not currently support

Always check `products` before attempting an operation. For example, not all liability types support `payment` — attempting to create a payment on an account without `payment` in its `products` list will fail. See the [Products reference](/reference/accounts/products/overview) for the full list.

***

For the full Accounts API, including all fields, endpoints, and expandable resources, see the [Accounts reference](/reference/accounts/overview).


# Card Brand
Source: https://docs.methodfi.com/guides/additional-products/card-brand

Card product names, visual card art, and card details for trust and engagement.

For credit card accounts, Method can retrieve the specific card product name, visual card art, and structured card details, including APRs, fees, rewards, and promotional offers. Instead of displaying a generic "Visa credit card" line item, your product can show "Chase Sapphire Reserve" with the actual card image and card details.

<Frame>
  <img alt="Card Brand enrichment" />
</Frame>

This seemingly small detail has an outsized impact on user trust and engagement. When users see their actual card names and artwork in your product, it signals accuracy and builds confidence that the data is real and current.

<Warning>
  Card Brand is available only to partners processing payments using the PaymentInstrument endpoint. Contact your Method CSM for more information.
</Warning>

## How It Works

Card Brand is available as a Product (on-demand) or Subscription (continuous updates). Create a Card Brand request for a credit card account, and Method returns a `brands` array containing:

* **name:** The card product name (e.g., "Chase Sapphire Reserve")
* **network:** The card network (e.g., `visa`, `mastercard`)
* **network\_tier:** The network tier (e.g., `infinite`, `signature`)
* **url:** A hosted URL for the card art image
* **type:** Brand match quality: `specific` (exact match with card art), `generic` (general metadata, no specific FI offering), or `in_review` (undergoing verification)
* **details:** Structured card details: `card_category`, purchase & cash-advance APRs, annual & late fees, `rewards` (type, program, and earn categories), and `promotions` (with the sign-up bonus). Available on version `2025-07-04` and later; see the [Card Brand reference](/reference/accounts/card-brands/overview).

The `source` field on the response indicates where the data came from (`method` or `network`).

## Quick Start

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/card_brands \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const cardBrand = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .cardBrands
    .create();
  ```

  ```python Python theme={null}
  card_brand = method
    .accounts('acc_yVf3mkzbhz9tj')
    .card_brands
    .create()
  ```
</CodeGroup>

## Supported Cards

Card Brand is available for credit card accounts on Visa and Mastercard networks. Requesting Card Brand for a non-credit-card account or an unsupported network returns a `PRODUCT_UNAVAILABLE` error.

## Error Handling

* `PRODUCT_UNAVAILABLE`: Account isn't a credit card, or the network isn't Visa/Mastercard.
* `TEAM_CAPABILITY_RESTRICTED`: Your team doesn't have access to Card Brand.
* `CARD_BRANDS_NOT_FOUND`: The card's brand could not be found or doesn't exist.

<Card title="Card Brand API Reference" icon="credit-card" href="/reference/accounts/card-brands/overview">
  Full API documentation for Card Brand.
</Card>


# Credit Scores
Source: https://docs.methodfi.com/guides/additional-products/credit-scores

Credit score retrieval and monitoring for financial wellness products.

For financial wellness products, few data points are as universally understood and valued as the credit score. Method can retrieve credit scores for verified Entities, giving your product the ability to show users their score, track changes over time, and alert them to increases or decreases.

## How It Works

Credit Scores are available as a Product (on-demand) or Subscription (continuous updates via webhooks). Requests are asynchronous: you'll get an immediate response with `status: "pending"` and `scores: null`, then a webhook when the score is ready.

The response includes a `scores` array. Each score object contains:

* **score:** The numeric credit score
* **source:** The credit bureau (`equifax`, `experian`, or `transunion`)
* **model:** The scoring model (`vantage_3` for VantageScore 3.0 or `vantage_4` for VantageScore 4.0)
* **factors:** An array of factor objects (each with `code` and `description`) explaining what's influencing the score, e.g., "Total of all balances on bankcard or revolving accounts is too high"

## Quick Start

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/credit_scores \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const creditScore = await method
    .entities('ent_au22b1fbFJbp8')
    .creditScores
    .create();
  ```

  ```python Python theme={null}
  credit_score = method
    .entities('ent_au22b1fbFJbp8')
    .credit_scores
    .create()
  ```
</CodeGroup>

## Subscriptions

Scores can be retrieved on-demand (pull the current score when the user opens your app) or monitored via subscriptions (get notified automatically when the score changes). Webhook events (`credit_score.create`, `credit_score.update`, `credit_score.available`) tell you when a score becomes available or changes, enabling features like "Your credit score went up 12 points this month!" notifications that drive engagement and retention.

## Prerequisites

The Entity must be fully verified before you can request credit scores. Attempting to request scores for an unverified Entity returns an `ENTITY_VERIFICATION_MISSING` error.

## Error Handling

Request errors:

* `ENTITY_VERIFICATION_MISSING`: Entity must be fully verified first.
* `TEAM_CAPABILITY_RESTRICTED`: Your team doesn't have access to Credit Scores.

Resource errors (set on the Credit Score's `error` property):

* `CREDIT_SCORE_FAILED_TEMPORARILY_UNAVAILABLE`: Issue with the credit score provider, request could not be completed.

<Card title="Credit Scores API Reference" icon="chart-line" href="/reference/entities/credit-scores/overview">
  Full API documentation for Credit Scores.
</Card>


# Sensitive
Source: https://docs.methodfi.com/guides/additional-products/sensitive

Gated access to full account numbers and sensitive account data.

Sensitive is a specially gated product that provides access to full account numbers and other sensitive account data. This is not enabled by default; access requires explicit approval from Method.

<Warning>
  Sensitive data requires explicit enablement for your team. Access may require additional review, agreements, and approval from Method. Not all accounts or account types support Sensitive data retrieval.
</Warning>

## How It Works

Unlike most Method products, Sensitive requests are *synchronous*. You'll get the data back immediately in the response.

When creating a Sensitive request, you must specify an `expand` array indicating which fields you want. Available fields depend on the account's liability type:

**Credit Cards:**

* `credit_card.number`: Full card number (PAN)
* `credit_card.exp_month`: Expiration month
* `credit_card.exp_year`: Expiration year
* `credit_card.cvv`: Card CVV
* `credit_card.billing_zip_code`: Billing zip code

**All other liability types** (auto loan, mortgage, personal loan, collection, student loans, credit builder, BNPL, fintech, loan):

* `{type}.number`: Full account number (e.g., `auto_loan.number`, `mortgage.number`)

## Supported Account Types

Sensitive supports: credit card, auto loan, mortgage, personal loan, collection, student loans, credit builder, BNPL, fintech, and loan accounts.

## Quick Start

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/sensitive \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "expand": [
        "credit_card.number",
        "credit_card.exp_month",
        "credit_card.exp_year",
        "credit_card.cvv"
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const sensitive = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .sensitive
    .create({
      expand: [
        'credit_card.number',
        'credit_card.exp_month',
        'credit_card.exp_year',
        'credit_card.cvv'
      ],
    });
  ```

  ```python Python theme={null}
  sensitive = method
    .accounts('acc_yVf3mkzbhz9tj')
    .sensitive
    .create({
      'expand': [
        'credit_card.number',
        'credit_card.exp_month',
        'credit_card.exp_year',
        'credit_card.cvv'
      ]
    })
  ```
</CodeGroup>

## Security Requirements

If your use case requires full account numbers (for example, to initiate payments through external systems or to populate forms on behalf of users), you'll need to request Sensitive access from Method. If approved, you're expected to follow strict security practices:

* Apply the principle of least privilege, only request sensitive data when needed
* Store secrets and sensitive data securely using encryption at rest and in transit
* Maintain audit logging on your side for all access to sensitive data
* PCI compliance is required

<Card title="Sensitive API Reference" icon="lock" href="/reference/accounts/sensitive/overview">
  Full API documentation for Sensitive.
</Card>


# Vehicles
Source: https://docs.methodfi.com/guides/additional-products/vehicles

Auto loan enrichment with VIN, make, model, and vehicle details.

For applications that deal with auto loans, whether that's auto refinancing, insurance, fleet management, or vehicle valuation, Method can enrich an Entity's profile with detailed vehicle information.

## How It Works

Vehicles is an Entity-level product: you request it against an Entity, not an individual Account. This means a single request returns all vehicles associated with that person. The response is synchronous, you'll get the data back immediately.

The `vehicles` array in the response contains one object per vehicle, each with:

* **vin:** Vehicle Identification Number
* **year:** Make year (e.g., "2021")
* **make:** Manufacturer (e.g., "honda")
* **model:** Model (e.g., "accord")
* **series:** Series/Trim/Category (e.g., "lx", "ex"), may be `null`
* **major\_color:** Primary color (e.g., "black")
* **style:** Body style (e.g., "sedan/saloon", "crew\_pickup", "sport\_utility\_vehicle")

This transforms an abstract "auto loan" line item into a concrete vehicle identity. Instead of showing "Auto Loan: \$18,450 balance," your product can display "2022 Honda Civic LX: \$18,450 remaining." This enrichment dramatically improves the user experience and enables vehicle-specific features like valuation estimates, equity calculations, and insurance comparisons.

## Quick Start

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/vehicles \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const vehicles = await method
    .entities('ent_au22b1fbFJbp8')
    .vehicles
    .create();
  ```

  ```python Python theme={null}
  vehicles = method
    .entities('ent_au22b1fbFJbp8')
    .vehicles
    .create()
  ```
</CodeGroup>

## Multiple Vehicles

An Entity can have multiple vehicles. The response `vehicles` array will contain all of them. This is useful for presenting a vehicle selector in your UI or for fleet management use cases.

<Card title="Vehicles API Reference" icon="car" href="/reference/entities/vehicles/overview">
  Full API documentation for Vehicles.
</Card>


# Core Concepts
Source: https://docs.methodfi.com/guides/concepts

The mental model for Method's platform — objects, relationships, and data flow.

This section provides a bird's-eye view of Method's core concepts and how they relate to each other. Think of it as the mental model you'll carry throughout the rest of this guide, every section that follows goes deeper on one of these concepts.

## The Core Platform Objects

<CardGroup>
  <Card title="Entity" icon="user" href="/guides/entities/overview">
    A user's identity in Method. An Entity represents one individual (or business) and serves as the root object for all accounts, verifications, and transactions. Each user in your application maps to exactly one Entity.
  </Card>

  <Card title="Identity Verification (IDV)" icon="shield-check" href="/guides/identity-verification/overview">
    Verifies that a user is who they claim to be before Method can access credit data or process payments. IDV includes phone verification and identity verification and acts as a one-time gate that unlocks downstream products.
  </Card>

  <Card title="Connect" icon="link" href="/guides/connect/overview">
    Discovers what a user owes. Using a verified Entity, Connect performs a soft credit pull to automatically identify liabilities across financial institutions, giving your application visibility into a user's full debt profile.
  </Card>

  <Card title="Accounts" icon="building-columns" href="/guides/accounts/overview">
    The financial objects your application interacts with. Accounts include discovered liabilities (credit cards, loans, etc.) and funding sources used for payments. They are the objects you monitor, update, and pay against.
  </Card>

  <Card title="Updates" icon="arrows-rotate" href="/guides/updates/overview">
    Provides fresh data about accounts. Updates deliver the latest balances, due dates, minimum payments, interest rates, and more through credit report snapshots or direct institutional connections.
  </Card>

  <Card title="Payments" icon="money-bill-transfer" href="/guides/payments/overview">
    Moves money to pay down liabilities. You initiate a payment from a verified funding source, and Method handles the full lifecycle: submission, processing, delivery to the creditor, and confirmation.
  </Card>
</CardGroup>

## The Dependency Chain

These concepts build on each other in a natural progression. Not every integration uses every product, a monitoring-only product might skip Payments entirely, while a paydown-focused product might use all of them. But the dependency chain means you always start with an Entity, verify their identity, and connect their accounts before you can take action.

### Typical End-to-End Flows

| Flow               | Path                                                         |
| ------------------ | ------------------------------------------------------------ |
| **Debt discovery** | Entity → IDV → Connect → Accounts → Updates                  |
| **Debt paydown**   | Entity → IDV → Connect → Accounts → Payments → Updates       |
| **Monitoring**     | Entity → IDV → Connect → Accounts → Subscriptions → Webhooks |

<Note>
  **Using Opal?** Opal handles Entity creation, identity verification, and account discovery in a single embedded flow. If you're using Opal, you don't build the first three steps yourself — Opal orchestrates them for you, and your integration picks up at the Accounts stage.
</Note>

## Additional Products

Beyond the six core concepts, Method offers specialized products that enrich the data and capabilities available on connected accounts.

### Commonly Used

<CardGroup>
  <Card title="Credit Score" icon="chart-line" href="/guides/additional-products/credit-scores">
    Credit score retrieval and monitoring, essential for financial wellness products that want to show users their score alongside their debt profile.
  </Card>

  <Card title="Attributes" icon="chart-pie" href="/guides/additional-products/attributes">
    Delivers structured credit health metrics (e.g., credit card usage, payment history), useful for building personalized insights, recommendations, or risk assessments.
  </Card>

  <Card title="Card Brand" icon="credit-card" href="/guides/additional-products/card-brand">
    Retrieves the specific card product name and card art (e.g., "Chase Sapphire Preferred" with the actual card image), great for building visually rich account displays.
  </Card>
</CardGroup>

### Specialized

<CardGroup>
  <Card title="Vehicles" icon="car" href="/guides/additional-products/vehicles">
    Enriches auto loan accounts with vehicle details (make, model, VIN), valuable for auto-focused lending or insurance products.
  </Card>

  <Card title="Sensitive" icon="lock" href="/guides/additional-products/sensitive">
    Provides gated access to full account numbers and other sensitive data, available by approval only, for use cases that require raw account credentials.
  </Card>

  <Card title="Payment Instruments" icon="wallet" href="/guides/payments/instruments">
    Creates reusable payment configurations (card credentials, ACH details, network tokens), enables repeated payment scenarios without re-collecting credentials each time.
  </Card>
</CardGroup>

Most integrations use a subset of these products. A basic debt discovery app needs only Entities, IDV, Connect, and Updates. A payment-focused product adds Payments and a Funding Account. Start with what your use case requires — you can enable additional products as your product evolves.

<CardGroup>
  <Card title="API Reference" icon="code" href="/reference/introduction">
    Full endpoint documentation for every object described above.
  </Card>
</CardGroup>


# Errors and Edge Cases
Source: https://docs.methodfi.com/guides/connect/errors

Common Connect errors and how to handle them.

## Common Connect Errors

### Request errors (returned immediately)

* **`ENTITY_VERIFICATION_MISSING`**: Entity must be fully verified before Connect. Complete both phone and identity verification first. See [Identity Verification](/guides/identity-verification/overview).
* **`TEAM_CAPABILITY_RESTRICTED`**: Your team doesn't have access to Connect. Contact your CSM.
* **`ACCOUNT_CONSENT_UNAVAILABLE`**: Account consent isn't available for your organization.

### Async errors (returned after processing)

* **`THIN_CREDIT_FILE`**: No tradelines found. The user has no credit history reportable to bureaus.
* **`CREDIT_FREEZE`**: The user has a credit freeze in place. The user must lift their freeze before discovery can complete.
* **`PRODUCT_EXECUTION_FAILED`**: A downstream product (balance, update, etc.) failed to execute on connected accounts. The Connect itself succeeded, but some product data may be missing.

<Warning>
  **Credit freeze messaging.** If a user hits `CREDIT_FREEZE`, surface a clear message explaining they need to lift their credit freeze.
</Warning>

For the full list of Connect error codes, see the [Connect Errors reference](/reference/errors/connect-errors).


# How Connect Works
Source: https://docs.methodfi.com/guides/connect/how-it-works

Soft-pull credit reports, auto vs manual discovery, and coverage.

## How Discovery Works

Connect uses the verified Entity's personally identifying information and the user's consent to perform a soft-pull credit report. A soft pull is fundamentally different from a hard credit inquiry — it has zero impact on the user's credit score and leaves no visible mark on their credit report. This is important messaging for your users, who may be hesitant about anything that touches their credit.

The credit report reveals the user's open liabilities across financial institutions. Method parses this data, matches it against its network of 15,000+ supported institutions, and creates account objects for each discovered liability. These accounts are immediately available in your application for data retrieval, monitoring, and (where supported) payment processing.

<Tip>
  **Processing time.** Connect typically completes within seconds for most users. Users with extensive credit histories (many open accounts) may take slightly longer.
</Tip>

<Tip>
  **Account matching.** Method matches each tradeline on the credit report against its network of 15,000+ financial institutions. When a match is found, Method creates an Account object with the appropriate `products` array based on what's supported for that merchant and liability type. Unmatched tradelines (institutions not in Method's network) are not returned.
</Tip>

## Complete Connect Flow

### Step 1: Create a Connect

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "products": ["balance", "update"],
    "subscriptions": ["update"]
  }'
```

### Step 2: Wait for completion

Connect processes asynchronously when products or subscriptions are specified, or when the `Prefer: respond-async` header is set. Listen for the `connect.update` webhook to know when discovery is complete:

```json theme={null}
{
  "id": "cxn_4ewMmBbjYDMR4",
  "type": "connect.update",
  "path": "/entities/ent_au22b1fbFJbp8/connect/cxn_4ewMmBbjYDMR4"
}
```

### Step 3: Retrieve results

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect/cxn_4ewMmBbjYDMR4 \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

<Tip>
  **Expand for efficiency.** Use the `expand` query parameter to include full Account objects, balances, card brands, or other data in the Connect response, avoiding additional API calls: `?expand=accounts,accounts.balance,accounts.card_brand`
</Tip>

## Synchronous vs Asynchronous Processing

A bare Connect request (no products, no subscriptions, no `Prefer: respond-async` header) processes synchronously — the response includes the completed results immediately.

When you include `products`, `subscriptions`, or the `Prefer: respond-async` header, Connect processes asynchronously. The response returns immediately with `status: pending` or `status: in_progress`, and you'll receive a `connect.update` webhook when processing completes.

<Note>
  **Recommendation:** Always set up webhooks for Connect. Even synchronous requests can take several seconds for users with many liabilities, and products/subscriptions always trigger async processing.
</Note>

## Requesting Products and Subscriptions at Connect Time

Connect can automatically execute products and set up subscriptions on all discovered accounts in a single call. This eliminates the need to iterate over accounts and make individual product requests after discovery.

**Available products:**

* `balance`: Retrieve balances for all discovered accounts
* `update`: Pull real-time data from source institutions
* `card_brand`: Retrieve card brand art and product names
* `attribute`: Pull structured credit health metrics
* `payoff`: Get payoff quotes (auto loans)

**Available subscriptions:**

* `update`: Subscribe to real-time data refreshes
* `update.snapshot`: Subscribe to periodic snapshot updates
* `card_brand`: Subscribe to card brand changes
* `transaction`: Subscribe to new transaction events

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "products": ["balance", "card_brand"],
    "subscriptions": ["update"]
  }'
```

<Note>
  Products and subscriptions are only executed on accounts where they're available. If an account doesn't support a product, requesting it won't cause an error — it simply won't apply to that account.
</Note>

## Connect Statuses

* `pending`: The Connect request is queued for processing
* `in_progress`: Discovery is actively running (soft pull being performed, accounts being matched)
* `completed`: Discovery finished successfully, accounts are available
* `failed`: Discovery failed (see error object for details)

Poll the Connect status or listen for `connect.update` webhooks to track progress.

## Connect vs. Manual Connect

Connect is the automatic discovery path — Method finds the accounts for you. But there are scenarios where you already have account data from another source (a prior data pull, user input, a partner integration) and want to register those accounts in Method without re-discovering them. That's what Manual Connect is for.

Manual Connect creates account objects from data you provide, bypassing the credit report discovery step. This is useful for: migrating existing users from a legacy system, supplementing discovered accounts with additional accounts the user provides manually, or connecting accounts that aren't reported to credit bureaus (and therefore wouldn't be discovered through Connect).

<Tabs>
  <Tab title="Connect (Auto Discovery)">
    Method performs a soft-pull credit report and automatically discovers the user's liabilities.

    **Use when:**

    * Onboarding new users
    * You want the broadest possible account discovery
    * Users don't know all their account details

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```
  </Tab>

  <Tab title="Manual Connect">
    You provide raw credit report tradeline data and Method creates account objects from it, bypassing the soft-pull step.

    **Use when:**

    * Migrating existing users from a legacy system where you already have their bureau data
    * Ingesting tradelines pulled directly from Equifax or TransUnion via your own bureau relationship
    * Backfilling historical tradeline data for an Entity

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/manual_connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "bureau": "transunion",
        "tradelines": [
          {
            "type_code": "18",
            "portfolio_type_code": "revolving",
            "designator_code": "individual",
            "number": "5555555555555555",
            "creditor_name": "CAPITAL ONE",
            "creditor_code": "01DTV001",
            "balance": 500000,
            "highest_balance": 750000,
            "credit_limit": 1000000,
            "term": null,
            "next_payment_minimum_amount": 15000,
            "last_payment_amount": 20000,
            "payment_history": ["1", "1", "1"],
            "past_due_amount": 0,
            "delinquency_charge_off_amount": 0,
            "opened_at": "2016-11-25",
            "last_activity_date": "2024-05-01",
            "reported_date": "2024-05-01",
            "next_payment_due_date": "2024-06-01",
            "last_payment_date": "2024-05-01",
            "delinquency_first_start_date": null,
            "narrative_codes": [
              { "code": "FE", "description": "CREDIT CARD" }
            ]
          }
        ]
      }'
    ```

    <Note>
      Manual Connect ingests **raw bureau tradelines** — it expects the full schema your bureau returns (creditor codes, payment history, delinquency dates, narrative codes, etc.). It is not a lightweight "user enters a missing account" flow. See the [Manual Connect reference](/reference/entities/manual-connect/create) for the full tradeline schema.
    </Note>
  </Tab>
</Tabs>

## Coverage — What Gets Discovered

Connect's coverage spans the broad spectrum of consumer liabilities, including:

<Accordion title="Supported liability types">
  * Credit cards from major issuers and regional banks
  * Auto loans from captive lenders and financial institutions
  * Federal and private student loans
  * Personal and installment loans
  * Mortgages and home equity lines of credit (HELOCs)
  * Collections accounts
  * Medical debt
  * Insurance payment obligations
  * Utility accounts
  * Buy Now Pay Later (BNPL) obligations
  * Credit builder accounts
  * Fintech-originated loans
</Accordion>

<Note>
  **Coverage notes:**

  * Credit cards, auto loans, and student loans have the broadest coverage across issuers
  * Collections accounts are reported inconsistently across bureaus — some may not appear
  * BNPL and utility accounts have growing but variable coverage
  * Closed accounts are included in the first Connect call but may have limited product availability
  * Coverage varies by specific institution, not just liability type. A major bank's credit cards will have broader product support than a small regional lender's
</Note>

## Expanding Connect Results

Use the `expand` query parameter to include full Account objects and their sub-resources directly in the Connect response, eliminating additional API calls:

```
POST /entities/{ent_id}/connect?expand=accounts,accounts.balance,accounts.card_brand
```

Available expansions: `accounts`, `accounts.balance`, `accounts.card_brand`, `accounts.attribute`, `accounts.update`, `accounts.payment_instrument`, `accounts.latest_verification_session`. If you expand a sub-field, the parent `accounts` expansion is applied automatically.


# Connect — Account Discovery
Source: https://docs.methodfi.com/guides/connect/overview

How Method discovers your users' complete liability picture.

<Frame>
  <img alt="Connect" />
</Frame>

<Note>
  **Using Opal?** If you're using Method's embedded UI, Opal handles account discovery as part of its managed flow — you don't need to call the Connect API directly. See the [Opal guide](/opal/overview) for details. The rest of this section is for custom API integrations.
</Note>

## What Connect Does

Connect discovers and links all of a user's financial liabilities in a single API call. Using the Entity's verified identity, Connect performs a soft-pull credit report and matches the results against Method's network of 15,000+ supported financial institutions. Each discovered liability becomes an Account object in your application, immediately available for data retrieval, monitoring, and payments where applicable.

## When to Use Connect

Connect is the standard path for any product that needs a comprehensive view of a user's debts: debt management, financial wellness, lending (pre-qualification, consolidation, portfolio monitoring), and bill pay. If your product involves consumer liabilities, Connect is almost certainly how you'll discover them.

## Prerequisites

Before calling Connect, the Entity must be fully verified (both phone and identity verification completed). Attempting Connect on an unverified Entity returns `ENTITY_VERIFICATION_MISSING`. See [Identity Verification](/guides/identity-verification/overview) for details.

## What Comes Back

A successful Connect returns a list of Account IDs representing the user's discovered liabilities. Each Account includes the merchant (who the debt is owed to), the liability type (credit card, auto loan, mortgage, etc.), and the `products` array indicating what Method can do with that account (balance retrieval, real-time updates, payments).

```json theme={null}
{
  "id": "cxn_4ewMmBbjYDMR4",
  "entity_id": "ent_qKNBB68bfHGNA",
  "status": "completed",
  "accounts": [
    "acc_eKKmrXDpJBKgw",
    "acc_GV8WbmJW7KGRy",
    "acc_MLPKh9gQDDbT8"
  ],
  "requested_products": [],
  "requested_subscriptions": [],
  "error": null,
  "created_at": "2024-04-12T14:56:46.645Z",
  "updated_at": "2024-04-12T14:56:46.645Z"
}
```

<Tip>
  **First Connect vs. subsequent calls.** The first Connect for an Entity returns all discovered liabilities (active and closed). Subsequent Connect calls for the same Entity only return *new* accounts that weren't in previous results. This is important for re-discovery flows — you won't get duplicates.
</Tip>

## Understanding Account Products

Each Account returned from Connect has a `products` array indicating what Method supports for that merchant:

* `balance`: retrieve the current balance
* `update`: pull real-time data (balances, rates, due dates) directly from the institution
* `payment`: send payments to this account through Method
* `sensitive`: access full account numbers (gated, requires approval)

Not every account supports every product. A credit card from a major issuer will likely have `balance`, `update`, and `payment`. A collections account may only have `balance`. Check `products` before building flows that assume full coverage.

## Next Steps

* [How Connect Works](/guides/connect/how-it-works): Soft pulls, auto vs manual discovery, coverage details
* [Handling Partial Results](/guides/connect/partial-results): Designing for incomplete discovery
* [Connect Subscriptions](/guides/connect/subscriptions): Monitoring for new liabilities over time
* [Connect API Reference](/reference/entities/connect/overview): Full endpoint documentation


# Handling Partial Results
Source: https://docs.methodfi.com/guides/connect/partial-results

Designing for incomplete discovery results.

# Handling Partial Results

<Note>
  Connect may not discover every liability a user has. Design your product to treat partial results as the normal case.
</Note>

## Why Results May Be Incomplete

**Not all liabilities appear on credit reports.** Some debts (private loans between individuals, certain employer-provided benefits, some BNPL arrangements) are never reported to credit bureaus and won't be found by Connect.

**Reporting delays.** New accounts may not appear on a credit report for 30–60 days after opening. A user who just opened a credit card last week won't see it in Connect results yet.

**Unmatched institutions.** Method's network covers 15,000+ institutions, but some smaller or newer creditors may not yet be supported. The tradeline exists on the credit report, but Method can't create an actionable Account from it because the institution isn't in Method's network.

**Closed accounts.** The first Connect returns both open and closed accounts. Closed accounts may have limited product availability (e.g., no payments, no updates).

## Recommended Patterns

### Show what was found, supplement where possible

After Connect completes, display the discovered accounts. If you have access to additional bureau data the user, you can supplement the discovered set by ingesting raw credit report tradelines via [Manual Connect](/reference/entities/manual-connect/create):

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/manual_connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "bureau": "transunion",
    "tradelines": [
      {
        "type_code": "18",
        "portfolio_type_code": "revolving",
        "designator_code": "individual",
        "number": "5555555555555555",
        "creditor_name": "CAPITAL ONE",
        "creditor_code": "01DTV001",
        "balance": 500000,
        "highest_balance": 750000,
        "credit_limit": 1000000,
        "term": null,
        "next_payment_minimum_amount": 15000,
        "last_payment_amount": 20000,
        "payment_history": ["1", "1", "1"],
        "past_due_amount": 0,
        "delinquency_charge_off_amount": 0,
        "opened_at": "2016-11-25",
        "last_activity_date": "2024-05-01",
        "reported_date": "2024-05-01",
        "next_payment_due_date": "2024-06-01",
        "last_payment_date": "2024-05-01",
        "delinquency_first_start_date": null,
        "narrative_codes": [
          { "code": "FE", "description": "CREDIT CARD" }
        ]
      }
    ]
  }'
```

<Note>
  Manual Connect requires the full bureau tradeline schema (creditor codes, payment history, delinquency dates, narrative codes, etc.) — it is not a lightweight "user enters a missing account" flow. If you need that pattern, talk to your CSM about the right approach for your use case.
</Note>

### Enable Connect subscriptions for ongoing discovery

New liabilities that appear on future credit reports will be automatically discovered. See [Connect Subscriptions](/guides/connect/subscriptions).

### Handle zero results gracefully

If Connect returns zero accounts (thin credit file), don't show an empty state. Explain that the credit report didn't contain tradelines and offer Manual Connect as the path forward.

### Account-level product gaps

Even when an account is discovered, it may not support all products. Always check the `products` array before making assumptions:

```javascript theme={null}
const account = await method.accounts.retrieve('acc_eKKmrXDpJBKgw');

if (account.products.includes('payment')) {
  // Safe to initiate payments
} else {
  // Data-only — can retrieve balances but can't send money
}
```

For the full Connect API, see the [Connect reference](/reference/entities/connect/overview).


# Raw Credit Reports
Source: https://docs.methodfi.com/guides/connect/raw-credit-reports

Receive the raw bureau credit report behind a Connect as downloadable files.

Connect discovers liabilities using the user's credit report. Teams with raw credit report access enabled can also receive that underlying bureau report itself, as a downloadable raw credit report JSON and/or credit report PDF returned as [Files](/reference/files/overview). Files give you a durable copy of the report (e.g. for compliance archives or underwriting reviews) that can be re-downloaded at any time.

## Prerequisites

* Raw credit report features are enabled on a case-by-case basis. Contact Method to enable these.
* The Entity must be verified and must not have [withdrawn consent](/reference/entities/consent/withdraw).

## Requesting the raw report

<Steps>
  <Step title="Create a Connect with artifacts">
    Pass `bureau` and `artifacts` when [creating a Connect](/reference/entities/connect/create):

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "bureau": "transunion",
        "artifacts": ["raw_credit_report", "credit_report_pdf"]
      }'
    ```

    | Field       | Type    | Notes                                                                                                                              |
    | ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
    | `bureau`    | enum    | `transunion` or `equifax`. Required whenever `artifacts` is set. Method will work with your team to set which bureaus are allowed. |
    | `artifacts` | enum\[] | Any of `raw_credit_report`, `credit_report_pdf`. Each becomes a downloadable File on the Connect.                                  |

    <Note>
      Each Connect pulls from a single bureau. To receive credit reports from both bureaus, you will need to make 2 separate Connect calls.
    </Note>
  </Step>

  <Step title="Read the response">
    The Connect response includes the requested artifacts in `files`:

    ```json theme={null}
    {
      "id": "cxn_4ewMmBbjYDMR4",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "completed",
      "accounts": ["acc_eKKmrXDpJBKgw", "acc_GV8WbmJW7KGRy"],
      "requested_products": [],
      "requested_subscriptions": [],
      "files": [
        {
          "id": "file_jZWkPMhXPeYAn",
          "type": "raw_credit_report",
          "bureau": "transunion",
          "mime_type": "application/json"
        },
        {
          "id": "file_qTnUv7DdKcRW2",
          "type": "credit_report_pdf",
          "bureau": "transunion",
          "mime_type": "application/pdf"
        }
      ],
      "error": null,
      "created_at": "2026-07-06T18:00:00.000Z",
      "updated_at": "2026-07-06T18:00:12.000Z"
    }
    ```
  </Step>

  <Step title="Download the file artifacts">
    Note the `file_id`s in the above response and use [Retrieve a File](/reference/files/retrieve) to get the File's metadata, including a temporary `download_url` to its contents:

    ```bash theme={null}
    curl https://production.methodfi.com/files/file_jZWkPMhXPeYAn \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    Fetch the `download_url`. A new URL is generated on every retrieve and expires at `download_expires_at`.

    Additionally, you can stream a File's contents directly with [Download a File](/reference/files/download):

    ```bash theme={null}
    curl https://production.methodfi.com/files/file_jZWkPMhXPeYAn/download \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -o raw_credit_report.json
    ```
  </Step>
</Steps>

## Retrieving the raw report later

Files persist after the Connect completes. [Retrieve the Connect](/reference/entities/connect/retrieve) at any time to read its `files` array, then download the contents via the [Files API](/reference/files/overview).

## Webhooks

Connects with products or subscriptions (or the `Prefer: respond-async` header) process asynchronously. Listen for `connect.available` to know when an async Connect (including its artifacts) is ready, and `connect.create` for synchronous completions. See [Connect webhooks](/guides/connect/subscriptions).

## Errors

| `sub_type`                              | Cause                                                         |
| --------------------------------------- | ------------------------------------------------------------- |
| `CONNECT_BUREAU_REQUIRED_FOR_ARTIFACTS` | `artifacts` sent without `bureau`                             |
| `CONNECT_BUREAU_NOT_CONFIGURED`         | No bureaus have been configured for your team                 |
| `CONNECT_BUREAU_NOT_ENABLED`            | The requested bureau is not in your team's allowed bureaus    |
| `CONNECT_RAW_REPORT_NOT_ENABLED`        | The `raw_credit_report` artifact is not enabled for your team |
| `CONNECT_CREDIT_REPORT_PDF_NOT_ENABLED` | The `credit_report_pdf` artifact is not enabled for your team |

See [Connect errors](/reference/errors/connect-errors) and [File errors](/reference/errors/file-errors) for the full list.

<Note>
  **Handling sensitive data.** The raw credit report contains the consumer's full bureau file. Treat it as highly sensitive: store it encrypted, restrict access, and only retain it as long as your compliance obligations require.
</Note>

For the full API surface, see the [Connect reference](/reference/entities/connect/overview) and the [Files reference](/reference/files/overview).


# Connect Subscriptions
Source: https://docs.methodfi.com/guides/connect/subscriptions

Monitoring for new liabilities over time.

## Connect Subscriptions — Monitoring for New Liabilities

A user's liability profile isn't static. They open new credit cards, take out new loans, and accumulate new obligations over time. Connect Subscriptions monitor for these changes by periodically checking the Entity's credit report for new liabilities.

When a new account is discovered, Method creates it and notifies you via webhook. This enables your product to surface new debts automatically, keep the user's liability picture complete without requiring them to re-run discovery, and trigger workflows when new accounts appear (e.g., automatically requesting updates for newly discovered accounts).

The typical pattern is to enable a Connect subscription after the initial Connect completes, creating a continuous discovery pipeline that keeps your application's view of the user's liabilities current over time.

## Creating a Connect Subscription

Use the [Entity Subscriptions endpoint](/reference/entities/subscriptions/create) to enroll an Entity in ongoing Connect monitoring:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{ "enroll": "connect" }'
```

<Note>
  The Connect endpoint's `subscriptions` body parameter is for *account-level* subscriptions (`update`, `card_brand`, etc.) that apply to discovered accounts. To subscribe to ongoing *discovery* of new liabilities, use the Entity Subscriptions endpoint with `"enroll": "connect"` as shown above.
</Note>

<Tip>
  **Subscription frequency.** Connect subscriptions periodically perform soft-pull credit checks to detect new tradelines.
</Tip>

## Webhooks

Connect fires the following webhook events:

* `connect.create`: Connect request was created
* `connect.update`: Connect status changed (use this to detect completion)
* `connect.available`: New accounts are available (fired by Connect subscriptions when new liabilities are detected)

```json theme={null}
{
  "id": "cxn_4ewMmBbjYDMR4",
  "type": "connect.update",
  "path": "/entities/ent_au22b1fbFJbp8/connect/cxn_4ewMmBbjYDMR4"
}
```

Set up webhooks via the [Webhooks API](/reference/webhooks/overview) to receive real-time notifications.

## Receiving New Account Notifications

When a Connect subscription discovers new liabilities, Method fires a `connect.available` webhook:

```json theme={null}
{
  "id": "cxn_new123",
  "type": "connect.available",
  "path": "/entities/ent_au22b1fbFJbp8/connect/cxn_new123"
}
```

Retrieve the Connect object to see the newly discovered Account IDs. Only new accounts are included — previously discovered accounts are not repeated.

## Managing Subscriptions

To unsubscribe from Connect monitoring:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/subscriptions/sub_abc123 \
  -X DELETE \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

See [Entity Subscriptions](/reference/entities/subscriptions/overview) for the full subscription management API.

## When to Use Connect Subscriptions

<Tip>
  **When to use Connect subscriptions:**

  * Debt management / financial wellness apps where the user's liability picture must stay current
  * Portfolio monitoring where new liabilities impact risk assessment
  * Lending products that need to detect new debts after origination

  **When you may not need them:**

  * One-time Connect for a loan application (discovery is a point-in-time event)
</Tip>


# Testing Connect
Source: https://docs.methodfi.com/guides/connect/testing

How to test Connect in development.

## Testing Connect in Development

Use the simulation endpoint to queue Connect behaviors in your development environment:

```bash theme={null}
curl https://dev.methodfi.com/simulate/entities/{entity_id}/connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "behaviors": ["new_credit_card_account", "new_auto_loan_account"] }'
```

Each behavior is consumed the next time Connect runs for that Entity. Maximum 5 behaviors per Entity.

**Available behaviors:** `new_credit_card_account`, `new_auto_loan_account`, `new_mortgage_account`, `new_student_loan_account`, `new_personal_loan_account`.

<Note>
  **Simulation limitations.** Simulated accounts won't have real institution data. Use them to test your integration flow (webhooks, UI rendering, product execution), not data accuracy.
</Note>

For the full simulation API, see the [Simulate Connect reference](/reference/simulations/connect/create).


# Entity Errors — What Can Go Wrong and How to Handle It
Source: https://docs.methodfi.com/guides/entities/errors

What can go wrong during Entity creation and how to handle it.

## Entity Errors and Edge Cases

The most common issues during Entity creation stem from missing or incorrectly formatted user information. Understanding these helps you design an onboarding flow that minimizes friction and handles errors gracefully.

* **Missing required fields**: Entity creation requires certain identifying information (at minimum, a name and phone number for individuals). If required fields are omitted, the creation will fail. In your user experience, this typically means your onboarding form should collect all necessary fields upfront and validate completeness before submission. If you're collecting information across multiple screens, ensure the full set is available when you create the Entity.
* **Invalid formats**: PII fields must meet specific format requirements, phone numbers must be valid US numbers, dates of birth must be real dates, and so on. Customer-side validation catches most of these issues before they reach Method's API. Design your input fields with appropriate format masks, validation rules, and helpful error messages so users can correct issues immediately rather than encountering failures downstream.

### Immutable PII Fields

Once a PII field has been set to a non-null value on an Entity (name, phone, DOB, SSN), it **cannot be changed**. If a user enters incorrect information and it gets submitted to Method, you cannot correct it via the API.

**How to handle it:**

* For fields that are still `null`, you can update them at any time via the [Update endpoint](/reference/entities/update-entity)
* For genuine corrections (e.g., legal name change), contact Method support
* You may need to create a new Entity for that user

### Operations on Disabled Entities

If an Entity transitions to `disabled` (via consent withdrawal or a compliance event), any attempt to initiate new operations — connecting accounts, creating payments, requesting products — will fail. Existing data remains readable.

**How to handle it:** Check the Entity's `status` before initiating operations. If `disabled`, display a clear message and prevent actions that would fail. See [Entity Lifecycle](/guides/entities/lifecycle) for more on state transitions.

### Phone Number Formatting

Phone numbers must be in **E.164 format** (e.g., `+15121234567`). Common issues:

* Missing country code (`5121234567` instead of `+15121234567`)
* Including formatting characters (`(512) 123-4567` instead of `+15121234567`)
* Non-US numbers (Method currently supports US numbers only)

Validate and normalize phone numbers on your end before submitting to Method.

### Common Error Responses

When Entity creation or updates fail, Method returns structured error responses. Here are the most common:

**Missing required field:**

```json theme={null}
{
  "error": {
    "type": "INVALID_REQUEST",
    "sub_type": "INVALID_REQUEST",
    "message": "Field \"individual\" is required. Verify your request and try again."
  }
}
```

**Invalid phone format:**

```json theme={null}
{
  "error": {
    "type": "INVALID_REQUEST",
    "sub_type": "INVALID_REQUEST",
    "message": "Field \"individual.phone\" is in an invalid format. Verify your request and try again."
  }
}
```

**Attempting to update an immutable field:**

```json theme={null}
{
  "error": {
    "type": "INVALID_REQUEST",
    "sub_type": "ENTITY_UPDATE_INVALID",
    "message": "Updates are only allowed on fields that have not been set. Verify your request and try again."
  }
}
```

For the complete list of Entity error codes, see [Entity Errors](/reference/errors/entity-errors) in the API Reference.

### When Issues Persist

If Entity creation consistently fails, first check the `error` field on the API response — it contains structured details about what went wrong. Most issues can be resolved by fixing input data and retrying.

If the error is unclear or you believe it's incorrect, contact Method support with:

* The Entity ID (`ent_...`) if one was created
* The full error response
* The request payload that triggered the error

<Note>
  Entity errors should be handled as a normal part of your onboarding flow,
  not as exceptional failures. Validate input early, provide clear error
  messaging, and allow users to correct and retry without starting over.
  For engineering teams: see the full error codes and response formats in the
  <a href="/reference/errors/entity-errors">Entity Errors reference</a>.
</Note>

<CardGroup>
  <Card title="Identity Verification Guide" icon="shield-check" href="/guides/identity-verification/overview">
    Next: verify your user's identity to unlock products.
  </Card>

  <Card title="Entity Errors Reference" icon="code" href="/reference/errors/entity-errors">
    Full list of error codes, types, and sub-types.
  </Card>
</CardGroup>


# Entity Lifecycle — From Creation to Active Use
Source: https://docs.methodfi.com/guides/entities/lifecycle

From creation to active use — understanding Entity states and transitions.

## Entity Lifecycle — From Creation to Active Use

### Lifecycle States

Every Entity in Method exists in one of three states, and understanding these states helps you design the right user experience at each stage of your onboarding flow:

* **Incomplete:** The Entity has been created in Method, but the user hasn't completed all required steps to unlock the platform's capabilities. This is the starting state for every new Entity. In practical terms, your application knows who this person is, but Method hasn't yet verified their identity or connected their accounts. Most products are unavailable in this state. Your application should guide the user through the remaining setup steps (typically identity verification) and clearly indicate that setup isn't finished.
* **Active:** The Entity is fully set up and ready for use. Identity verification is complete, and the full range of eligible products is available. This is the steady state for most of your users. Your application can connect accounts, request updates, initiate payments, and enable monitoring. The user should experience the full value of your product.
* **Disabled:** The Entity has been deactivated and can no longer be used for new operations. This may happen because your team withdrew consent via the [Consent endpoint](/reference/entities/consent/withdraw), because Method disabled the Entity for compliance reasons, or because the user requested account closure through your application.
  No new operations can be initiated, but existing data, accounts, payment history, updates — remains accessible for reference and reporting.

### Common Lifecycle Transitions

**incomplete → active**
Triggered when the Entity completes all verification requirements configured for your team. For most teams, this means both phone and identity verification. The transition happens automatically — once the final verification session succeeds, the Entity's status updates and products become available.

**active → disabled**
Can be triggered by:

* Your team withdrawing consent via the [Consent endpoint](/reference/entities/consent/withdraw)
* A compliance event (e.g., a payment reversal triggers a policy review)
* Method disabling the Entity for policy reasons

This transition is permanent — disabled Entities cannot be reactivated. To re-onboard the user, create a new Entity.

**What about abandoned onboarding?**
Entities that stay in `incomplete` (the user never finished verification) don't expire. Build a resume flow that picks up where the user left off rather than creating a new Entity on their next visit.

Entities must be `active` before they can be `disabled`. An `incomplete` Entity that's no longer needed can simply be left in place — it doesn't incur cost or require cleanup.

### Reacting to State Changes

Entity state changes trigger `entity.update` webhooks. Subscribe to these to react in real time — for example, unlocking features when an Entity transitions to `active`, or displaying a deactivation notice when it becomes `disabled`. See [Webhooks](/reference/webhooks/overview).

### Designing Around Lifecycle States

Your user experiences should reflect the Entity's state:

* For incomplete Entities, show a clear onboarding progress indicator. Let the user know what steps remain (e.g., "Verify your identity to see your accounts"). Avoid showing empty states that suggest the product is broken — the user is mid-setup, not experiencing an error.
* For active Entities, provide full access to your product's features. This is your core experience.
* For disabled Entities, display a clear, non-alarming message explaining that the account is no longer active. Allow the user to view historical data if appropriate, but prevent any actions that would fail (payment initiation, account connection, etc.)

<CardGroup>
  <Card title="Errors & Edge Cases" icon="triangle-exclamation" href="/guides/entities/errors">
    What can go wrong during Entity creation and how to handle it.
  </Card>

  <Card title="Entity API Reference" icon="code" href="/reference/entities/overview">
    See the full Entity object including status, verification, products, and subscriptions.
  </Card>
</CardGroup>


# Entities — The Foundation of Every Integration
Source: https://docs.methodfi.com/guides/entities/overview

What an Entity represents, why it matters, and how it maps to your users.

## Entities — The Foundation of Every Integration

### The Entity Model

An Entity is Method's representation of a person or business in your system — a persistent profile that anchors everything Method knows about your user. Their verified identity, discovered accounts, payment history, and active subscriptions all connect through a single Entity. Every operation your application performs through Method — identity verification, account discovery, payments, monitoring — flows through the user's Entity.

### Why the Entity Model Matters

* **Persistent verification:** Once verified, the Entity carries that status forward. You don't re-verify for every operation.
* **Single reference point:** All accounts, payments, and updates for a user are scoped to their Entity. This also enforces authorization boundaries — one Entity's operations can't affect another.
* **Lifecycle management:** The Entity's status tracks the user's journey from onboarding through active use to potential deactivation, enforcing appropriate constraints at each stage.

### Entity vs End User

Your application has users; Method has Entities. These map one-to-one. Each end user in your application corresponds to exactly one Entity in Method, and that relationship persists throughout the user's lifecycle. You'll typically store the Method Entity ID alongside your internal user ID so you can bridge between the two systems seamlessly.

<Warning>
  Method does not automatically deduplicate Entities. If your application
  creates two Entities for the same person, both will exist independently
  with separate accounts and data. Your application should enforce uniqueness
  (typically by phone number) before creating new Entities.
</Warning>

### Individual vs Corporation Entities

Method supports two types of Entities, corresponding to the two types of financial actors:

<Tabs>
  <Tab title="Individual">
    Individual Entities represent people. To create one, you provide identifying information,  typically at minimum a name and phone number, with additional fields (date of birth, address, SSN) required for identity verification and access to downstream products. Individual Entities are by far the most common type and support the full range of Method's products.

    ```bash theme={null}
    curl https://production.methodfi.com/entities \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "individual",
        "individual": {
          "first_name": "John",
          "last_name": "Doe",
          "phone": "+15121234567"
        }
      }'
    ```
  </Tab>

  <Tab title="Corporation">
    Corporation Entity represents any business, regardless of its legal structure. Corporation Entities go through a business-specific verification process (KYB) and have their own product eligibility path.

    Corporation Entities support a different subset of capabilities than Individuals. They are primarily used for payment origination scenarios and do not have the same product catalog (no credit scores, Connect, or individual-specific features). If your use case involves both consumers and businesses, your architecture will need to account for this difference.

    ```bash theme={null}
    curl https://production.methodfi.com/entities \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "corporation",
        "corporation": {
          "name": "Acme Inc.",
          "ein": "123456789"
        }
      }'
    ```
  </Tab>
</Tabs>

### What Information Do You Need to Collect?

At minimum, most teams need a user's **name and phone number** to create an Individual Entity. However, additional PII (date of birth, SSN or last 4 of SSN, email, address) is typically required to complete identity verification and unlock products like Connect and Credit Score.

Your specific PII requirements are configured during onboarding. A common pattern is to create the Entity early with minimal information, then progressively update it as you collect more data during your onboarding flow. Contact your Method CSM if you're unsure about your team's requirements.

<CardGroup>
  <Card title="Entity Lifecycle" icon="arrows-spin" href="/guides/entities/lifecycle">
    Understand Entity states and how users transition from onboarding to active use.
  </Card>

  <Card title="Errors & Edge Cases" icon="triangle-exclamation" href="/guides/entities/errors">
    What can go wrong during Entity creation and how to design around it.
  </Card>

  <Card title="Identity Verification" icon="shield-check" href="/guides/identity-verification/overview">
    The next step after Entity creation — verifying your user's identity.
  </Card>

  <Card title="Entity API Reference" icon="code" href="/reference/entities/overview">
    Full Entity object schema, CRUD endpoints, and field details.
  </Card>
</CardGroup>


# IDV Errors & Edge Cases
Source: https://docs.methodfi.com/guides/identity-verification/errors

Common verification errors, failure modes, and how to handle edge cases.

## IDV Errors & Edge Cases

### Phone Verification Failures

| Error                                                    | Cause                                                             | Resolution                                                                                                                           |
| -------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `VERIFICATION_SESSION_EXPIRED` (19001)                   | Session not completed within the 10-minute window                 | Create a new verification session. Consider adding a timer or progress indicator to your UX.                                         |
| `VERIFICATION_SESSION_FAILED_INCORRECT_SMS_CODE` (19002) | User entered the wrong SMS code                                   | Create a new verification session. Confirm the user is entering the code from the most recent SMS.                                   |
| `VERIFICATION_SESSION_FAILED_SNA` (19003)                | User not on a mobile device, or on an unsupported carrier/network | Fall back to SMS verification. SNA access attempts are limited to 5 per session.                                                     |
| `ENTITY_PHONE_VERIFICATION_MAX_ATTEMPTS`                 | Too many verification attempts for this Entity's phone number     | The underlying SMS provider has rate-limited this phone number. Wait before retrying, and surface appropriate messaging to the user. |

### Identity Verification Failures

| Error                                                | Cause                                                                                           | Resolution                                                                                                                                                                               |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MISSING_IDENTITY_MATCH`                             | Method couldn't correlate the Entity's PII to a known identity — insufficient or incorrect PII  | [Update the Entity](/reference/entities/update-entity) with additional fields (DOB, SSN, address) and retry. See [Maximizing Success](/guides/identity-verification/maximizing-success). |
| `VERIFICATION_SESSION_FAILED_INVALID_ANSWER` (19004) | User answered one or more KBA questions incorrectly, or a question was missing from the request | Create a new verification session — a fresh set of questions will be generated. Confirm the user is answering carefully.                                                                 |
| `VERIFICATION_SESSION_EXPIRED` (19001)               | Session not completed within the 10-minute window                                               | Create a new verification session.                                                                                                                                                       |

### Request Errors

| Error                              | Cause                                                                                        | Resolution                                                                        |
| ---------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `MISSING_PHONE_VERIFICATION`       | Attempted to create an identity verification session before phone verification was completed | Complete phone verification first, then create the identity verification session. |
| `EXISTING_VERIFIED_SESSION`        | The Entity has already completed verification for that type (phone or identity)              | No action needed — the Entity is already verified for that step.                  |
| `INVALID_ENTITY_TYPE`              | Attempted to create a verification session on a corporation Entity                           | Verification sessions are only available for Entities of type `individual`.       |
| `UNAUTHORIZED_VERIFICATION_METHOD` | The team is not authorized to use the requested verification method                          | Contact your Method CSM to enable the method (e.g., `byo_sms`, `byo_kyc`).        |

### Edge Cases

<Accordion title="User needs a different phone number mid-flow">
  An Entity's phone number cannot be changed once it has been set. If the user entered the wrong phone number, you'll need to create a new Entity with the correct phone number and start the verification process from the beginning.
</Accordion>

<Accordion title="Same phone number across multiple Entities">
  Multiple Entities can share the same phone number, but each Entity must complete its own verification independently.
</Accordion>

<Accordion title="Re-verification after Entity was previously verified">
  Attempting to create a verification session for an already-verified type will return `EXISTING_VERIFIED_SESSION`. Verification is persistent and does not need to be repeated.
</Accordion>

<Accordion title="Attempting verification on a disabled Entity">
  Verification sessions cannot be created for Entities that have been disabled. Ensure the Entity is in an active state before initiating verification.
</Accordion>

<Accordion title="Corporation Entity">
  Verification sessions are only available for individual Entities. Attempting to create a session on a corporation Entity will return `INVALID_ENTITY_TYPE`.
</Accordion>

### Error Code Reference

For the full list of error codes with response bodies, see the [Entity Verification Session Errors](/reference/errors/entity-verification-session-errors) reference.


# Maximizing Verification Success
Source: https://docs.methodfi.com/guides/identity-verification/maximizing-success

How to improve match rates and verification success through better data collection.

## Maximizing Verification Success

Not all PII fields are required for every verification method, but providing more data significantly improves match rates and verification success. At minimum, you need a name and phone number, but including date of birth, address, and SSN (last 4 or full) dramatically increases the likelihood of a successful match. Design your onboarding flow to collect as much PII as practical without creating excessive friction.

| Field                | Impact   | Why it matters                                            |
| -------------------- | -------- | --------------------------------------------------------- |
| First + Last name    | Required | Baseline identity anchor                                  |
| Phone number         | Required | Links to carrier records and Method's network             |
| Date of birth        | High     | Disambiguates common names, strong identity signal        |
| Address              | High     | Confirms geographic identity, helps with thin files       |
| Email                | Moderate | Secondary signal, helps when primary fields are ambiguous |
| SSN (last 4 or full) | Highest  | Strongest single identity signal, near-guaranteed match   |

### Common Pitfalls

* **Phone number without country code** — Method only accepts US phone numbers at this time, and they must include the `+1` country code (e.g., `+15551234567`)
* **Abbreviated names vs. legal names** — use the name on their credit file, not nicknames (e.g., "William" not "Bill")
* **PO Box instead of physical address** — physical addresses match better against identity records
* **Stale or outdated address** — use the user's current address, not a previous one

<Note>
  For platform availability details, see the [IDV Overview](/guides/identity-verification/overview).
</Note>

<CardGroup>
  <Card title="Verification Outcomes" icon="circle-check" href="/guides/identity-verification/outcomes">
    When data collection is maximized but matching still fails.
  </Card>

  <Card title="Verification Sessions API" icon="code" href="/reference/entities/verification-sessions/overview">
    Full API reference for verification session endpoints.
  </Card>
</CardGroup>


# Verification Methods
Source: https://docs.methodfi.com/guides/identity-verification/methods

Choosing the right phone and identity verification approach for your integration.

## Verification Methods

<Warning>
  All verification sessions expire **10 minutes** after creation. If the user doesn't complete verification within that window, you'll need to create a new session. Design your UX to guide users through verification promptly and handle the expired session error gracefully. See [Errors & Edge Cases](/guides/identity-verification/errors) for details.
</Warning>

Phone verification must be completed before identity verification can begin. Choose one method from each step below. Most teams use the same approach (Opal, API-driven, or BYO) for both steps, but you can mix — for example, SNA for phone and KBA for identity.

### Choosing Your Phone Verification Method

<Tabs>
  <Tab title="Opal (Recommended)">
    Phone verification is handled entirely within the Opal embedded UI. The user enters their phone number, receives a verification code, and enters it — all within a polished, pre-built interface. This is the fastest path to implementation and provides the most consistent user experience.
  </Tab>

  <Tab title="SMS Verification">
    Method sends a verification code to the user's phone, and your application collects and submits the code. Choose this if you want to integrate phone verification into your own custom UI while still having Method handle the SMS delivery.

    ```bash theme={null}
    # 1. Create SMS verification session
    curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "sms",
        "sms": {}
      }'

    # 2. Submit the code the user received
    curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "sms",
        "sms": {
          "sms_code": "123456"
        }
      }'
    ```
  </Tab>

  <Tab title="Silent Network Auth (SNA)">
    The phone is verified in the background using carrier-level network signals, with no user interaction required. This provides the best user experience (the user doesn't have to do anything), but availability depends on the user's carrier and network conditions. Consider SNA as a primary method with SMS as a fallback.

    <Warning>
      SNA requires the user to be on a mobile device connected to a supported carrier's network. It does not work on landlines, VoIP numbers, or most prepaid/MVNO carriers. The returned URLs must be opened via background request or the device's mobile browser. Always implement SMS as a fallback — SNA failures may be silent and your application needs to detect them (via session status polling or webhook) and offer an alternative. SNA access attempts are limited to 5 per session before the session fails.
    </Warning>
  </Tab>

  <Tab title="BYO SMS">
    You handle SMS delivery and verification entirely on your side and report the result to Method. Choose this if you already have a robust SMS verification system and want to maintain a single verification flow across your application.

    <Note>
      BYO SMS requires your team to be pre-authorized during onboarding. You'll create a verification session with method `byo_sms` and provide the `byo_sms.timestamp` field — the ISO 8601 timestamp of when you verified the phone number. Contact your Method CSM to enable this method.
    </Note>

    ```bash theme={null}
    curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "byo_sms",
        "byo_sms": {
          "timestamp": "2026-04-10T12:00:00.000Z"
        }
      }'
    ```
  </Tab>
</Tabs>

#### Choosing a Phone Method

| Method      | User Experience            | Implementation                | Reliability                  | Best For                                 |
| ----------- | -------------------------- | ----------------------------- | ---------------------------- | ---------------------------------------- |
| **Opal**    | Polished, pre-built        | Minimal (embed SDK)           | High                         | Most teams                               |
| **SMS**     | Standard (enter code)      | Medium (collect + submit)     | High                         | Custom UI with Method SMS delivery       |
| **SNA**     | Invisible (no user action) | Medium (background URL calls) | Variable (carrier-dependent) | Mobile-first products, with SMS fallback |
| **BYO SMS** | Your existing flow         | Low (report result)           | Depends on your provider     | Teams with existing SMS verification     |

**Recommended pattern:** Use SNA as primary with SMS as automatic fallback. This gives the best conversion rate while ensuring every user can complete verification.

<Note>
  Phone verification has a maximum attempt limit enforced by the underlying SMS provider. If the limit is reached, the error `ENTITY_PHONE_VERIFICATION_MAX_ATTEMPTS` is returned and you'll need to wait before retrying. Design your flow to inform users of the limit and avoid excessive retries.
</Note>

### Choosing Your Identity Verification Method

<Tabs>
  <Tab title="Opal (Recommended)">
    Identity verification is handled within the Opal embedded UI. The user is guided through the KYC process in a managed, tested flow. This is the simplest path and ensures the verification experience is optimized for completion.
  </Tab>

  <Tab title="KBA">
    The user answers a set of identity questions generated from their credit and public record history (e.g., "Which of these addresses have you lived at?"). Your application presents the questions and collects answers. KBA is widely supported but can be frustrating for users if questions are obscure or ambiguous.

    ```bash theme={null}
    # 1. Create KBA verification session (returns questions)
    curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "identity",
        "method": "kba",
        "kba": {}
      }'

    # 2. Submit answers to the questions
    curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "identity",
        "method": "kba",
        "kba": {
          "answers": [
            { "question_id": "qtn_xxx", "answer_id": "ans_xxx" },
            { "question_id": "qtn_yyy", "answer_id": "ans_yyy" }
          ]
        }
      }'
    ```
  </Tab>

  <Tab title="BYO KYC">
    You perform identity verification on your side using your own KYC provider and report the outcome to Method. Choose this if you already have a KYC integration and want to consolidate verification into a single flow, or if you need to meet specific compliance requirements that require a particular KYC vendor.

    <Note>
      BYO KYC requires your team to be pre-authorized during onboarding. By creating this session, you're asserting that your external KYC process has passed for this user. Method trusts your KYC result — there are no constraints on which KYC vendor you use. Contact your Method CSM to enable this method.
    </Note>

    ```bash theme={null}
    curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "identity",
        "method": "byo_kyc",
        "byo_kyc": {}
      }'
    ```

    The response will include `byo_kyc: { authenticated: true }` confirming the verification was recorded.
  </Tab>
</Tabs>

#### Choosing an Identity Method

| Method      | User Experience     | Implementation                              | Best For                                   |
| ----------- | ------------------- | ------------------------------------------- | ------------------------------------------ |
| **Opal**    | Guided, pre-built   | Minimal                                     | Most teams                                 |
| **KBA**     | Multi-question quiz | Medium (present questions, collect answers) | API-only integrations without existing KYC |
| **BYO KYC** | Your existing flow  | Low (report result)                         | Teams with existing KYC provider           |

<Note>
  **About `element` and `method_verified` methods:** The API also lists `element` and `method_verified` as valid verification methods. `element` is the predecessor to Opal — new integrations should use Opal instead. `method_verified` is an internal method used by Method and is not available for external use.
</Note>


# Verification Outcomes
Source: https://docs.methodfi.com/guides/identity-verification/outcomes

Understanding the difference between Matched and Verified states.

## Verification Outcomes

### Understanding Verification Outcomes: Matched vs. Verified

Method distinguishes between two verification states, and understanding the difference matters:

| State                        | Meaning                                                        | Unlocks products? |
| ---------------------------- | -------------------------------------------------------------- | ----------------- |
| Neither matched nor verified | Entity created, not yet verified                               | No                |
| Matched only                 | Method identified the person, but they haven't proven identity | No                |
| Matched + Verified           | Full identity confirmation complete                            | Yes               |

An Entity cannot reach Verified status without first being Matched. If matching fails, verification cannot proceed.

In practical terms: matched means "we know who you are," and verified means "you've proven you're that person." Both are required.

### How Matching Works

When you create or update an Entity with PII (name, DOB, SSN, address, phone), Method attempts to correlate that information against its identity records. If the PII matches a known identity, the Entity becomes `matched`. This happens automatically when the Entity's PII is processed — you don't call a separate endpoint for matching.

The Entity's `matched` status is then checked when you create an identity verification session. If the Entity is not yet matched, the session creation will fail with `MISSING_IDENTITY_MATCH`.

Matching can fail if:

* The PII is incomplete (name + phone only, no DOB or SSN)
* The PII has typos or formatting issues
* The person has a thin file (limited credit/identity history)

See [Maximizing Verification Success](/guides/identity-verification/maximizing-success) for how to improve match rates.

### When Matching Fails

If Method cannot match the Entity's PII to a known identity, creating an identity verification session will return a `MISSING_IDENTITY_MATCH` error. Your options:

1. **Collect more PII:** Update the Entity with additional fields (DOB, SSN, address) and retry. More PII dramatically improves match rates.
2. **Verify the data:** Check for typos, name variations (maiden names, Jr/Sr suffixes), or incorrect phone numbers.

<Warning>
  Match failures are not the same as verification failures. A match failure means Method couldn't identify the person at all. A verification failure (KBA wrong answers, SMS wrong code) means the person was identified but couldn't prove they're that person.

  You will need to create a new Entity if a user fails identity verification (e.g., incorrect KBA answers). The failed Entity cannot be reused for identity verification.
</Warning>

### Checking Verification Status

The Entity object includes a `verification` field that reflects the current state:

```json theme={null}
"verification": {
  "identity": {
    "verified": true,
    "matched": true,
    "latest_verification_session": "evf_xxx",
    "methods": []
  },
  "phone": {
    "verified": true,
    "latest_verification_session": "evf_yyy",
    "methods": []
  }
}
```

When verification is incomplete, the `methods` arrays will contain the available verification methods for that step (e.g., `["sms", "sna"]` for phone, `["kba"]` for identity). Once a step is completed, its `methods` array becomes empty.

Use these fields to determine what actions are available for the Entity. See the [Entity API Reference](/reference/entities/overview) for full field documentation.

<CardGroup>
  <Card title="Maximizing Success" icon="chart-line" href="/guides/identity-verification/maximizing-success">
    Improve match rates through better data collection.
  </Card>

  <Card title="Verification Sessions API" icon="code" href="/reference/entities/verification-sessions/overview">
    Full API reference for verification session endpoints.
  </Card>
</CardGroup>


# Identity Verification (IDV)
Source: https://docs.methodfi.com/guides/identity-verification/overview

Why identity verification matters and how the two-step process works.

<Frame>
  <img alt="Identity Verification" />
</Frame>

## Proving Your Users Are Who They Claim to Be

<Warning>
  Method currently supports identity verification for US-based individuals only. Users without a US credit history or US phone number cannot complete verification.
</Warning>

### Why IDV Matters

Identity verification is the gateway to Method's platform. Before Method will discover a user's accounts, retrieve their credit data, or process payments on their behalf, the user must prove they are who they claim to be. It's a fundamental fraud prevention and compliance requirement that protects both your users and your platform.

For your product, IDV is typically the first meaningful interaction a user has after signing up. The verification experience directly impacts your onboarding conversion rate: a smooth, fast verification flow keeps users engaged, while a clunky or confusing one creates drop-off. Choosing the right verification approach is one of the most impactful product decisions you'll make in your Method integration.

IDV gates access to every downstream product: [Connect](/guides/connect/overview) (account discovery), [Updates](/guides/updates/overview) (fresh balances), [Payments](/guides/payments/overview), [Credit Scores](/guides/additional-products/credit-scores), [Attributes](/guides/additional-products/attributes), and more. An Entity that hasn't completed IDV stays in `incomplete` status with no product access. For most integrations, IDV is the single highest-impact step to optimize — every percentage point of verification conversion translates directly to users who can access your product's core features.

<Info>
  **Using Opal?** If you're using Method's embedded UI, Opal handles both phone verification and identity verification in a single, managed flow. You don't need to build verification screens or manage session state — Opal orchestrates the entire process. The rest of this section is relevant if you're building a custom integration or want to understand what Opal is doing under the hood. See the [Opal guide](/opal/identity/overview) for details.
</Info>

### The Two-Step Process

IDV consists of two sequential steps, each serving a distinct purpose:

<Steps>
  <Step title="Phone Verification">
    Confirms that the user controls the phone number associated with their identity. This is the "something you have" factor — it proves the person filling out your form actually possesses the phone number they provided.

    <Warning>
      Phone verification must be completed before identity verification can begin. Attempting to create an identity verification session for an Entity without phone verification will fail with `MISSING_PHONE_VERIFICATION`.
    </Warning>
  </Step>

  <Step title="Identity Verification">
    Confirms that the user's provided information matches a real person's identity through a KYC (Know Your Customer) process — it proves they are who they claim to be, not just someone who has access to a phone number.
  </Step>
</Steps>

Both steps must be completed for an Entity to be fully verified and gain access to downstream products.

### What Happens After Verification

Once both steps are complete, the Entity's status updates to `active` and the Entity becomes both `matched` and `verified`, unlocking downstream products: [Connect](/guides/connect/overview) (account discovery), [Credit Scores](/guides/additional-products/credit-scores), [Payments](/guides/payments/overview), and more. The verification is persistent — you don't need to re-verify for subsequent operations. See [Entity Lifecycle](/guides/entities/lifecycle) for how verification status affects what you can do.

<CardGroup>
  <Card title="Verification Methods" icon="list-check" href="/guides/identity-verification/methods">
    Choose the right phone and identity verification approach.
  </Card>

  <Card title="Verification Outcomes" icon="circle-check" href="/guides/identity-verification/outcomes">
    Understand the difference between Matched and Verified.
  </Card>

  <Card title="Maximizing Success" icon="chart-line" href="/guides/identity-verification/maximizing-success">
    Improve match rates through better data collection.
  </Card>

  <Card title="Verification Sessions API" icon="code" href="/reference/entities/verification-sessions/overview">
    Full API reference for verification session endpoints.
  </Card>
</CardGroup>


# The Verification Flow
Source: https://docs.methodfi.com/guides/identity-verification/verification-flow

Step-by-step verification sequence, state transitions, webhooks, and code walkthroughs.

## The Verification Flow

### Step-by-Step Sequence

<Steps>
  <Step title="Create Entity with PII">
    Create an Entity with at minimum a name and phone number. If you're using the API-driven flow (not Opal), providing more PII (DOB, SSN, address) significantly improves match rates. Opal collects PII directly from the user during its flow, so upfront PII is less critical when using Opal. See [Maximizing Success](/guides/identity-verification/maximizing-success).
  </Step>

  <Step title="Check available verification methods">
    Inspect `entity.verification.phone.methods` and `entity.verification.identity.methods` to see which verification methods are available for this Entity.
  </Step>

  <Step title="Create phone verification session">
    Choose a phone verification method (SMS, SNA, or BYO SMS) and create a verification session.
  </Step>

  <Step title="Complete phone verification">
    Complete the phone verification using the method-specific flow (submit SMS code, process SNA URLs, or report BYO result).
  </Step>

  <Step title="Create identity verification session">
    Once phone is verified, create an identity verification session (KBA or BYO KYC). This will fail with `MISSING_PHONE_VERIFICATION` if phone verification is not complete, or `MISSING_IDENTITY_MATCH` if Method couldn't match the Entity's PII.
  </Step>

  <Step title="Complete identity verification">
    Complete the identity verification using the method-specific flow (submit KBA answers or report BYO KYC result).
  </Step>

  <Step title="Entity is verified">
    Entity is now matched + verified. Proceed to [Connect](/guides/connect/overview), [Payments](/guides/payments/overview), or other products.
  </Step>
</Steps>

### State Diagram

```
[Entity created] → [Phone: unverified] → [Phone: verified] → [Identity: unverified] → [Identity: matched + verified] → [Products unlocked]
```

Each verification session goes through its own lifecycle:

```
pending → in_progress → verified (success)
                       → failed (expired, incorrect code/answer, SNA failure)
```

### Webhooks

Subscribe to verification session events to track progress:

* **`entity_verification_session.create`** — Fired when a new verification session is created.
* **`entity_verification_session.update`** — Fired when a session's status changes (e.g., `pending` → `verified`, `pending` → `failed`).

These events allow you to build reactive flows — for example, unlocking the next step of your onboarding when phone verification completes.

### Code Walkthroughs

#### SMS + KBA (most common API-driven path)

```bash theme={null}
# 1. Create an Entity
curl -X POST https://production.methodfi.com/entities \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "individual": {
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+15551234567",
      "dob": "1990-01-15"
    }
  }'

# 2. Create SMS phone verification session
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sms",
    "sms": {}
  }'

# 3. User receives SMS code, submit it
curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sms",
    "sms": { "sms_code": "123456" }
  }'

# 4. Create KBA identity verification session (returns questions)
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity",
    "method": "kba",
    "kba": {}
  }'

# 5. Present questions to user, then submit answers
curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_yyy \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity",
    "method": "kba",
    "kba": {
      "answers": [
        { "question_id": "qtn_aaa", "answer_id": "ans_bbb" },
        { "question_id": "qtn_ccc", "answer_id": "ans_ddd" }
      ]
    }
  }'

# Entity is now verified — proceed to Connect or other products
```

#### SNA + KBA (best UX path)

```bash theme={null}
# 1. Create Entity (same as above)

# 2. Create SNA phone verification session
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sna",
    "sna": {}
  }'
# Response includes SNA URLs — open them via background request on the user's device

# 3. Update SNA session to check verification status
curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sna",
    "sna": {}
  }'
# If SNA fails, fall back to SMS (create a new session with method "sms")

# 4-5. Proceed with KBA identity verification (same as above)
```

#### BYO SMS + BYO KYC (existing infrastructure path)

```bash theme={null}
# 1. Create Entity (same as above)

# 2. Report BYO SMS phone verification
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "byo_sms",
    "byo_sms": {
      "timestamp": "2026-04-10T12:00:00.000Z"
    }
  }'

# 3. Report BYO KYC identity verification
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity",
    "method": "byo_kyc",
    "byo_kyc": {}
  }'

# Entity is now verified
```


# Opal
Source: https://docs.methodfi.com/guides/opal

Method's embedded UI for identity verification, account discovery, and more.

## What Opal Is and Why It Matters

Opal is Method's embedded UI, a set of pre-built, white-labeled screens and flows that you drop into your application to handle the complex, multi-step processes of identity verification, account discovery, and more. Instead of designing, building, testing, and maintaining these flows yourself, you launch Opal and let it guide your users through the process in a polished, tested experience.

Opal represents a significant acceleration of your roadmap. Building identity verification and account linking flows from scratch typically takes weeks of engineering time, plus ongoing maintenance as edge cases, error states, and accessibility requirements emerge. Opal compresses this to days, your engineering team creates a session token, launches the component, and listens for completion events. Everything in between is handled by Method.

Opal is also designed for conversion. The flows are optimized for completion rates, with clear progress indicators, helpful error messaging, and the ability for users to resume interrupted sessions without starting over. When a user's phone dies mid-verification or they need to step away, their progress is saved.

## Opal Modes — What Your Users Experience

Opal operates in distinct modes, each handling a specific part of the user journey. You can launch these independently depending on where the user is in your flow:

<CardGroup>
  <Card title="Identity Verification" icon="shield-check" href="/opal/identity/overview">
    Guides the user through Method's two-step verification process. First, the user confirms their phone number (via SMS code, silent network auth, or other methods). Then, they complete identity verification through a KYC process. From the user's perspective, this feels like a simple onboarding step, enter some information, confirm a code, answer a few questions, and they're verified. Behind the scenes, Opal is orchestrating phone verification, identity matching, and KYC compliance.
  </Card>

  <Card title="Connect" icon="link" href="/opal/connect/overview">
    After verification, the user consents to a soft credit pull, and Opal displays the discovered liability accounts, credit cards, loans, mortgages, and more, in a clear, organized interface. The user can see what was found and proceed to the next step in your flow. This is often the "wow moment" in a debt management product: the user sees their complete liability picture for the first time, surfaced automatically without manual entry.
  </Card>

  <Card title="Card Connect" icon="credit-card" href="/opal/card_connect/overview">
    Handles the specific case where a user needs to verify and connect a particular card for payment flows. This is useful when your product needs to work with a specific card rather than discovering all liabilities.
  </Card>

  <Card title="Account Verification" icon="building-columns" href="/opal/account_verification/overview">
    Confirms ownership of a specific account. This is used when you need to verify that a user controls a particular financial account before enabling certain operations.
  </Card>
</CardGroup>

Each mode can be launched independently depending on where the user is in your flow.

## How Opal Integrates Into Your Flow

<Steps>
  <Step title="Request a session token">
    Your backend requests a session token from Method, scoped to a specific user (Entity) and a specific mode
  </Step>

  <Step title="Load the SDK">
    Your frontend application loads Opal using one of Method's client SDKs (available for web, React, and React Native)
  </Step>

  <Step title="User interacts with Opal">
    The user interacts with Opal directly, filling in information, confirming codes, reviewing discovered accounts
  </Step>

  <Step title="Receive webhook events">
    Your backend listens for webhook events that signal progress and completion, triggering whatever comes next in your application flow
  </Step>
</Steps>

Sessions are persistent, meaning users can leave and return without losing progress. This is particularly important for mobile users who may be interrupted by notifications, phone calls, or simply needing to come back later.

## Customization and Branding

Opal is designed to feel like a native part of your application, not a third-party widget. Customization options include:

* Brand colors and accent colors
* Typography and font choices
* Logo placement and branding elements
* Light/dark mode support

The goal is that your users never feel like they've been handed off to a different product. Refer to the [Opal documentation](/opal/overview) for the full range of theming options and accessibility compliance details.

## When to Consider API-Only

Opal covers the vast majority of integration scenarios, but there are cases where building directly against Method's APIs may be a better fit:

* Your product has an existing onboarding flow that users are already familiar with, and you need the verification steps to feel native to that flow's design language
* Your compliance or security requirements demand that PII collection happens entirely within your own infrastructure
* You need fine-grained control over the verification step ordering or conditional logic that Opal's session model doesn't support

If you're unsure, start with Opal. You can always migrate specific steps to API-only later without rebuilding everything.

<Warning>
  Elements was Method's previous embedded UI, deprecated on December 31, 2025. All new integrations should use Opal. If your team is still using Elements, plan your migration using the [Opal migration guide](/opal/migration_guide).
</Warning>

## What's Next

<CardGroup>
  <Card title="Opal Quickstart" icon="rocket" href="/opal/quickstart">
    Get Opal running in your application in minutes.
  </Card>

  <Card title="Opal Libraries" icon="book" href="/opal/libraries">
    SDK installation and setup for web, React, and React Native.
  </Card>

  <Card title="Opal Sessions" icon="key" href="/opal/sessions">
    Session management, token creation, and lifecycle.
  </Card>

  <Card title="Opal Events" icon="bell" href="/opal/events">
    Event handling and completion callbacks.
  </Card>

  <Card title="Opal API Reference" icon="code" href="/reference/opal/overview">
    Token creation, session management, and event types.
  </Card>
</CardGroup>


# What is Method
Source: https://docs.methodfi.com/guides/overview

Method is the infrastructure layer for consumer liability data and payments.

In a financial ecosystem where liability information is fragmented across thousands of institutions, reported inconsistently, and often weeks out of date, Method provides a single, unified platform that brings structure and reliability to this fragmented landscape.

<Note>
  These Guides cover concepts and product decisions. For implementation details and code, see the [API Reference](/reference/introduction).
</Note>

## How Method Works

Unlike aggregators that require users to share their bank login credentials, Method uses a fundamentally different approach. When a user verifies their identity, Method performs a soft credit pull (no impact to the user's credit score) to automatically discover all of their liabilities, without any manual account entry or credential sharing.

Once accounts are discovered, Method can retrieve real-time data directly from financial institutions for supported accounts, giving you current balances, due dates, interest rates, and payment amounts. For accounts where direct connections aren't available, Method falls back to credit report data as a reliable baseline.

This two-source model, credit report discovery paired with direct institutional access, means your product gets both breadth (visibility into virtually every liability) and depth (real-time data where it matters most).

## What Method Does

<CardGroup>
  <Card title="Discover and connect consumer liabilities at scale" icon="magnifying-glass">
    Method connects to 15,000+ financial institutions, from major banks to regional lenders. When a user links their identity, you gain visibility into their full liability picture — credit cards, auto loans, student loans, mortgages, personal loans, and more.
  </Card>

  <Card title="Keep liability data fresh and normalized" icon="arrows-rotate">
    Liability data arrives from institutions in inconsistent formats and update cycles. Method standardizes balances, due dates, interest rates, payment amounts, and limits into a clean, consistent data model accessible through a single API.
  </Card>

  <Card title="Move money to pay down debts" icon="money-bill-transfer">
    Method enables payments directly to connected liability accounts. Initiate paydowns from a verified funding source while Method handles submission, processing, delivery to the creditor, and confirmation.
  </Card>

  <Card title="Monitor changes over time for your users" icon="bell">
    Financial accounts constantly change — balances update, payments post, and accounts open or close. Method's subscription system keeps your application synced with these updates through near-real-time notifications.
  </Card>
</CardGroup>

## Who Method Is Built For

### Commerce

Commerce and card-linked platforms that need to connect to consumers' card accounts for transaction data, card-on-file verification, or payment instrument provisioning to power checkout, rewards, and card-linked offer experiences.

<CardGroup>
  <Card title="Wallet Onboarding" icon="wallet" href="/guides/use-cases/commerce/wallet-onboarding">
    Connect every credit card a customer owns in a single flow, then enrich and tokenize for checkout.
  </Card>

  <Card title="Preauth Signals" icon="signal" href="/guides/use-cases/commerce/preauth-signals">
    Evaluate payment readiness before authorization and retry failed payments at the optimal time.
  </Card>
</CardGroup>

### Lending

Lenders and underwriters that need verified, up-to-date liability data to make credit decisions, calculate debt-to-income ratios, verify existing obligations, and enable debt consolidation through structured plans, lump-sum payments, or automated recurring transfers.

<CardGroup>
  <Card title="Application & Qualification" icon="clipboard-check" href="/guides/use-cases/lending/application-prefill">
    Pre-fill loan applications with verified liability data and assess risk with credit health attributes.
  </Card>

  <Card title="Debt Consolidation" icon="money-bill-transfer" href="/guides/use-cases/lending/debt-consolidation">
    Discover eligible accounts, verify current balances, and disburse funds directly to creditors.
  </Card>

  <Card title="Portfolio Intelligence" icon="chart-line" href="/guides/use-cases/lending/portfolio-monitoring">
    Monitor borrower liability, utilization, and delinquency signals continuously after origination.
  </Card>
</CardGroup>

### Personal Finance & Financial Wellness

Personal finance and financial wellness applications that want to give users a comprehensive view of their liabilities alongside their assets, track progress over time, and provide actionable insights about credit health.

<CardGroup>
  <Card title="Onboarding & Discovery" icon="magnifying-glass" href="/guides/use-cases/pfm/onboarding-discovery">
    Identity verification options, liability discovery via Connect, and vehicle enrichment for auto loans.
  </Card>

  <Card title="Dashboard & Insights" icon="chart-mixed" href="/guides/use-cases/pfm/monitoring-insights">
    Build real-time debt dashboards with account updates, card brand art, credit scores, and financial health attributes.
  </Card>

  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Stream credit card transactions for spend management and initiate bill payments to your users' creditors.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/guides/quickstart">
    Most integrations follow this four-step pattern, though the exact flow may vary depending on your product and use case.
  </Card>

  <Card title="Core Concepts" icon="diagram-project" href="/guides/concepts">
    Understand Method's object model and how everything connects.
  </Card>

  <Card title="Opal" icon="window" href="/guides/opal">
    Drop-in embedded UI that handles identity verification, account discovery, and more — get to value in days, not weeks.
  </Card>

  <Card title="API Reference" icon="code" href="/reference/introduction">
    Dive into the full API documentation.
  </Card>
</CardGroup>


# Payment Errors and Constraints
Source: https://docs.methodfi.com/guides/payments/errors

Processing windows, posting timing, return codes, and idempotency.

## Payment Errors and Constraints

* Payments submitted outside of processing windows will be held until the next window.
* Posting timing depends on the creditor and is outside Method's control.
* Return codes may be provided when a payment fails or is returned.
* Duplicate payments can be prevented using [idempotency keys](/reference/idempotency).


# Payment Instruments
Source: https://docs.methodfi.com/guides/payments/instruments

Reusable payment configurations for recurring and repeated payments.

## Payment Instruments — Reusable Payment Configurations

For products that involve recurring or repeated payments (e.g., a monthly debt paydown plan), Payment Instruments provide a convenience layer. Instead of collecting and submitting payment details for every transaction, you create a Payment Instrument once, capturing the card credentials, ACH details, or network token, and reference it for subsequent payments.

Think of a Payment Instrument as a saved payment method. The user sets it up once, and your product can initiate payments against it repeatedly without re-collecting credentials. Instruments remain valid until explicitly closed or the underlying account changes.

Method supports three types of Payment Instruments:

| Type                 | Description                                                         |
| -------------------- | ------------------------------------------------------------------- |
| **Card**             | Card credentials for payment                                        |
| **Inbound ACH/Wire** | Routing and account details for ACH or wire payments to a liability |
| **Network Token**    | Tokenized card credentials for secure, network-level transactions   |

<Note>
  Not all accounts support all instrument types, check the account's available products before attempting to create an instrument. And listen for webhook events about instrument status changes, as instruments may become invalid if the underlying account is closed or credentials expire.
</Note>

For the full Payments API, see the [Payments reference](/reference/payments/overview). For Payment Instruments, see the [Payment Instruments reference](/reference/accounts/payment-instruments/overview).


# Payment Lifecycle
Source: https://docs.methodfi.com/guides/payments/lifecycle

What your users should see as payments move through the system.

## Payment Lifecycle — What Your Users Should See

Every payment moves through a defined lifecycle, and each stage should map to a clear user-facing status in your product:

| Method Status           | User-Facing Copy                        | Description                                                                 |
| ----------------------- | --------------------------------------- | --------------------------------------------------------------------------- |
| **Pending**             | "Payment scheduled" or "Payment queued" | The payment has been created and is waiting for the next processing window. |
| **Canceled**            | "Payment canceled"                      | The payment was canceled before it was processed.                           |
| **Processing**          | "Payment in progress"                   | The payment is actively being processed through the banking system.         |
| **Sent**                | "Payment sent to your creditor"         | Funds have been initiated and sent to the creditor.                         |
| **Posted**              | "Payment complete"                      | The creditor has confirmed the payment has been applied to the account.     |
| **Failed**              | "Payment couldn't be processed"         | An error occurred — see failure details.                                    |
| **Reversal Processing** | "Reversal in progress"                  | A reversal has been approved and is being processed.                        |
| **Reversed**            | "Payment returned"                      | A previously sent payment was returned.                                     |

Design your product to show clear status transitions as webhook events arrive. Users should feel confident that their money is moving and that the system is working, ambiguity about payment status is one of the fastest ways to erode trust.

### Handling Reversals and Failures

Payments can fail or be reversed, and your product should be able to handle these scenarios gracefully:

**Failed Payments**

Failed payments can occur at various stages due to insufficient funds in the funding account, invalid or closed account details, or creditor rejection. When a payment fails, Method emits a webhook event with the failure details. Your product should notify the user clearly, explain what happened in plain language, and provide a path to retry if applicable.

**Reversed Payments**

Reversals occur when a payment that was already sent is returned, for example, if the funding account has insufficient funds after the payment was initiated, or if the creditor returns the payment for any reason. Reversals are tracked as separate objects with their own lifecycle and webhook events. Your product should notify the user, explain the reversal, and update any progress displays that reflected the original payment.

<Warning>
  In both cases, avoid technical jargon. Users don't need to know about ACH return codes or processing windows, they need to know what happened, why, and what to do next.
</Warning>

### Settlement Timing

Settlement and posting timing varies by creditor and payment rail. Do not make hard assumptions about when a payment will post.


# Payments
Source: https://docs.methodfi.com/guides/payments/overview

How Method moves money to pay down debt.

## Payments — Moving Money to Pay Down Debt

### What Payments Enable

Payments are where Method's platform closes the loop from data to action. After discovering a user's liabilities and retrieving their current account data, Payments enable your application to actually move money — initiating paydowns from your platform's corporate funding account to your users' creditors.

This is the capability that transforms Method from a data platform into a complete debt management infrastructure. Without Payments, you can show users what they owe. With Payments, you can help them do something about it.

### What's Required Before a Payment Can Be Made

<Steps>
  <Step title="A verified Entity">
    The user must have completed [identity verification](/guides/identity-verification/overview). This is a non-negotiable compliance and fraud prevention requirement.
  </Step>

  <Step title="A destination liability account">
    The credit card, loan, or other debt being paid down, typically discovered through [Connect](/guides/connect/overview). This is where the money goes.
  </Step>

  <Step title="A verified funding source">
    Your platform's corporate bank account (checking or savings), linked via ACH and [verified](/guides/accounts/funding) through micro-deposits, Plaid, MX, or Teller. This is where the money comes from.
  </Step>

  <Step title="Webhook handling">
    Because payment processing is asynchronous (it takes time for money to move through the banking system), your application must listen for [webhook](/guides/platform-fundamentals#real-time-notifications-via-webhooks) notifications to track the payment's progress through its lifecycle.
  </Step>
</Steps>

### Payment Processing and Timing

Method supports electronic push payments to liability accounts. When a payment is submitted, funds are initiated from your platform's verified funding account and delivered to the creditor.

Processing typically takes 2–3 business days, though the exact timing varies by institution. Payments are processed in defined windows throughout the business day, so the time you submit a payment relative to the next processing window affects when it begins moving. Payments submitted outside of processing windows are held until the next window.

Settlement and posting times are ultimately controlled by the receiving creditor, not by Method. Some creditors apply payments same-day upon receipt; others may take additional time. This means your product should set user expectations appropriately: "Your payment has been sent and will be applied by your creditor, typically within a few business days." Avoid making hard promises about exact posting dates.


# Platform Fundamentals
Source: https://docs.methodfi.com/guides/platform-fundamentals

Environments, authentication, data flow patterns, and webhooks.

## Environments

Method provides three isolated environments, each serving a distinct purpose in your integration lifecycle:

<CardGroup>
  <Card title="Development" icon="wrench">
    Mocked responses. No real institutions contacted, no payments processed.
  </Card>

  <Card title="Sandbox" icon="flask-vial">
    Simulated flows with test data. Mimics real account discovery, payment timelines, and error states.
  </Card>

  <Card title="Production" icon="rocket">
    Live environment. Real institutions, real data, real money.
  </Card>
</CardGroup>

<Warning>
  Each environment uses separate API credentials and data does not cross environments. This allows you to test safely in Development and Sandbox without affecting Production users or data.
</Warning>

## Authentication and API Keys

Method uses API keys for authentication. Include your key in the `Authorization` header of every request. Each environment under each team has its own unique API key.

```bash theme={null}
curl https://production.methodfi.com/entities \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Method-Version: 2026-03-30"
```

The `Method-Version` header pins your requests to a specific API version, ensuring your integration behaves consistently even as Method's API evolves. When a new version is released, you can migrate on your own timeline. If the header is omitted, your team's default version is used. See [Versioning](/reference/versioning) in the API Reference for details.

See the [Authentication](/reference/authentication) reference for details.

## How Data Flows: On-Demand vs Subscriptions

Method offers two complementary models for accessing data, and understanding when to use each is important for designing your product experience.

<Tabs>
  <Tab title="On-Demand">
    On-demand access means you request data when you need it. For example, when a user opens their dashboard, you might request a fresh balance update for their accounts at that moment. On-demand is best for user-initiated actions, one-time data pulls, or situations where you need specific data at a specific time.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates \
      -X POST \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Method-Version: 2026-03-30" \
      -H "Content-Type: application/json" \
      -d '{"type": "direct"}'
    ```
  </Tab>

  <Tab title="Subscriptions">
    Subscription-based access means Method continuously monitors for changes and delivers new data to you automatically. For example, you might subscribe to balance updates for all of a user's accounts, and Method will notify you whenever new data is available, whether that's daily, weekly, or whenever the financial institution reports. Subscriptions are best for keeping dashboards current, triggering automated workflows, and monitoring for changes without requiring user action.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions \
      -X POST \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Method-Version: 2026-03-30" \
      -H "Content-Type: application/json" \
      -d '{"enroll": "update"}'
    ```
  </Tab>
</Tabs>

<Note>
  Not all products support both modes. Refer to each product's documentation for availability.
</Note>

## Real-Time Notifications via Webhook Events

Method's platform is fundamentally asynchronous, when you request an account update or initiate a payment, the result isn't always available immediately. Instead, Method notifies your system when something happens through webhook events: real-time HTTP notifications sent to an endpoint you configure.

For your product team, the key implication is this: your application should be designed around event-driven updates rather than polling or refresh buttons. When a payment posts, when new account data is available, when a user's credit score changes, Method tells you. This event-driven model enables responsive, real-time user experiences without the complexity and cost of constant polling.

The typical webhook handling pattern looks like this:

1. Method sends an HTTP POST to your configured endpoint with event details
2. Your backend acknowledges receipt (return a 2xx response promptly)
3. Your backend fetches the updated resource using the IDs in the event payload
4. Your application updates its local state and, if needed, refreshes the user's UI

This pattern applies to virtually every webhook: payment status changes, new account data, completed discovery, credit score updates, and more.

<Warning>
  Return your 2xx response before processing the event. If your endpoint takes too long to respond, Method will retry the delivery, which can cause duplicate processing. Deduplicate deliveries using the `method-webhook-delivery-id` request header and make your processing idempotent; see [Handling duplicate deliveries](/reference/webhooks/overview#handling-duplicate-deliveries).
</Warning>

Nearly every product creates and updates events, so webhooks are the primary mechanism for keeping your system in sync with Method.

Common webhook events include:

| Event                 | Description                             |
| --------------------- | --------------------------------------- |
| `payment.update`      | A payment's status has changed          |
| `account.create`      | A new account was discovered or created |
| `connect.completed`   | Account discovery finished              |
| `update.completed`    | Fresh account data is available         |
| `credit_score.update` | A credit score has changed              |

See the [Webhooks](/reference/webhooks/overview) reference for setup instructions and the [Events](/reference/events/overview) reference for the full list of event types.

## Reliability and Safety

Method's platform includes built-in mechanisms to ensure reliability. Your engineering team will handle implementation details, but at a product level the key guarantees are:

* **Idempotency keys:** Duplicate operations are prevented automatically (so a network hiccup doesn't create two payments). See [Idempotency](/reference/idempotency).
* **Rate limits:** Requests are rate-limited to maintain platform stability, and operations can be safely retried without unintended side effects. See [Rate Limiting](/reference/rate-limiting) in the API Reference for details.
* **Versioned APIs:** Method maintains versioned APIs so integrations remain stable as the platform evolves. New capabilities are introduced without breaking existing implementations.
* **Paginated list endpoints:** All list endpoints return paginated results, ensuring predictable performance regardless of data volume. See [Pagination](/reference/pagination) in the API Reference for details.
* **Reliable updates:** Changes to liabilities and payments are delivered through subscriptions and webhooks, ensuring your application stays in sync with real account activity.

These aren't features you need to design around, they're guardrails Method provides out of the box.

<CardGroup>
  <Card title="Authentication Reference" icon="key" href="/reference/authentication">
    API keys, headers, and request setup.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.methodfi.com/guides/quickstart

Get up and running with Method's four-step integration process.

Getting up and running with Method follows a predictable path, whether you're building a debt repayment app, a financial wellness dashboard, or an embedded lending experience.

## The Four-Step Integration Process

Most integrations follow the same high-level pattern, regardless of your specific use case:

<Steps>
  <Step title="Represent your user">
    Every end user in your application maps to an [Entity](/guides/entities/overview) in Method. This is the foundational object that everything else, verification, accounts, payments, attaches to. You provide basic identifying information (name, phone number, and optionally additional PII), and Method creates a persistent identity that follows the user throughout their lifecycle in your product.
  </Step>

  <Step title="Verify their identity">
    Before Method can discover a user's accounts or process payments on their behalf, the user must complete [identity verification](/guides/identity-verification/overview). This is a two-part process: first confirming they control their phone number, then verifying their identity through a KYC process.

    Method supports multiple verification approaches (SMS, silent network auth, KBA, and BYO options). Method will partner with your team to help determine which methods are best suited for your use case and user demographics.
  </Step>

  <Step title="Discover their accounts">
    Once verified, Method can discover the user's financial liabilities using a soft-pull credit report (no impact to their credit score). This is the moment where your product goes from knowing who a user is to knowing what they owe — and to whom. [Accounts](/guides/accounts/overview) are automatically created in Method as they're discovered, giving you immediate access to liability data across credit cards, loans, mortgages, and more.

    Each discovered account comes with the data reported to the credit bureau, including balance, credit limit, payment status, account type, and the financial institution that holds the account. From there, you can request real-time [Updates](/guides/updates/overview) to get current balances, due dates, minimum payments, interest rates, and more directly from the institution.
  </Step>

  <Step title="Take action">
    With accounts connected, you can now do the things that make your product valuable: pull fresh balance and payment data ([Updates](/guides/updates/overview)), initiate paydowns and bill pay ([Payments](/guides/payments/overview)), monitor for changes over time, and present your users with a clear, actionable picture of their financial obligations.

    Updates return structured, normalized fields — balances, due dates, minimum payments, interest rates, credit limits, and more — in a consistent format regardless of the underlying financial institution.
  </Step>
</Steps>

## Choosing Your Integration Approach

Method offers two primary integration approaches, and understanding the tradeoff early saves significant time:

<Tabs>
  <Tab title="Opal (Embedded UI)">
    **Best for most teams.** [Opal](/guides/opal) is Method's pre-built, white-labeled UI that handles identity verification, account discovery, and more. It's designed to drop into your application with minimal frontend work while providing a polished, tested user experience.

    *Choose Opal if you want to move fast, minimize custom UI development, and leverage Method's UX expertise. Most teams start here.*
  </Tab>

  <Tab title="API-Only">
    **Best for teams with specific UX requirements.** If you have an existing in-app flow, a highly customized user experience, or specific design requirements that Opal can't accommodate, you can integrate directly with Method's APIs.

    *This gives you complete control over the user experience but requires more frontend development and ongoing maintenance.*
  </Tab>
</Tabs>

## Example Integration Paths

To make the integration journey concrete, here are three common paths mapped to real product scenarios:

<AccordionGroup>
  <Accordion title="Debt Discovery (e.g., a financial wellness dashboard)">
    Your user signs up → you create an Entity and verify their identity → Method discovers all their liabilities → you display a comprehensive debt overview with balances, interest rates, and payment schedules → you subscribe to updates to keep the dashboard current.

    *Timeline to first value: the user sees their complete debt picture within minutes of completing verification.*
  </Accordion>

  <Accordion title="Debt Paydown (e.g., a debt repayment lender)">
    Your user signs up → identity verification → account discovery → you link your corporate account as a funding source → your user flow presents a paydown strategy → payments are initiated through Method → you track each payment from submission to posting and update the user's progress.

    *This is the full end-to-end loop that turns data into action.*
  </Accordion>

  <Accordion title="Ongoing Monitoring (e.g., a credit health tool)">
    Your user completes the initial setup → you subscribe to account updates and credit score monitoring → Method notifies you when balances change, payments post, credit scores shift, or new accounts appear → your app surfaces these changes as alerts, insights, or progress updates.

    *The user gets continuous value without ever repeating the setup process.*
  </Accordion>

  <Accordion title="Card Linking (e.g., a card-linked offers platform)">
    Your user signs up → you create an Entity and verify their identity → Method discovers their credit card accounts → you retrieve card brand details (card art, product name) and tokenize card credentials via Payment Instruments → your platform uses these tokens for checkout, rewards enrollment, or transaction monitoring.

    *This flow connects your product to the user's existing cards without manual entry or credential sharing.*
  </Accordion>
</AccordionGroup>

## What's Next

<CardGroup>
  <Card title="Platform Fundamentals" icon="gear" href="/guides/platform-fundamentals">
    Environments, authentication, webhooks, and data flow patterns.
  </Card>

  <Card title="Core Concepts" icon="diagram-project" href="/guides/concepts">
    Understand Method's object model and dependency chain.
  </Card>

  <Card title="Opal" icon="window" href="/guides/opal">
    Drop-in embedded UI for identity verification and account discovery.
  </Card>

  <Card title="API Reference" icon="code" href="/reference/introduction">
    Dive into the full API documentation.
  </Card>
</CardGroup>


# Billing Lifecycle and Data Availability
Source: https://docs.methodfi.com/guides/updates/billing-lifecycle

How a cardholder's billing stage determines which fields come back in an Update.

## Billing Lifecycle and Data Availability

Financial institutions determine which data fields are returned for Updates based on the cardholder's billing lifecycle stage. The four common cardholder states:

* **Bill Created**: A new statement has been generated. All billing fields are available.
* **Bill Due**: A payment is owed. Balance, minimum payment, and due date are present, but no last payment information has been reported yet.
* **Bill Paid**: A payment has been made. Last payment amount and date are available, but the next due date has not yet been generated.
* **Dormant**: The account is open but shows minimal activity. Typically only balance (and sometimes available credit) is returned.

| Field                          | Created | Due | Paid | Dormant |
| ------------------------------ | :-----: | :-: | :--: | :-----: |
| available\_credit              |    ✓    |  ✓  |   ✓  |    ✓    |
| balance                        |    ✓    |  ✓  |   ✓  |    ✓    |
| last\_payment\_amount          |    ✓    |     |   ✓  |         |
| last\_payment\_date            |    ✓    |     |   ✓  |         |
| next\_payment\_minimum\_amount |    ✓    |  ✓  |   ✓  |         |
| next\_payment\_due\_date       |    ✓    |  ✓  |      |         |

*Approximate distribution across states: Bill Created 28%, Bill Due 10%, Bill Paid 31%, Dormant 10%, Other 20%.*

The distribution across these states varies significantly by issuer. Each financial institution presents data differently, resulting in different extraction profiles.


# Handling Update Failures
Source: https://docs.methodfi.com/guides/updates/failures

Recommended patterns for handling stale data and failed refreshes.

## Common Failure Modes

Direct Updates can fail for several reasons. In the Update response, direct retrieval failures currently surface through a canonical `error` object:

| Failure Mode                                           | Where it surfaces                                                                      | Recommended Action                                                                                          |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Institution unreachable or temporarily unavailable     | Update `error.code: 21001`; account `data_status_error` is usually `15004` or `15006`. | Retry after a delay. These are usually transient.                                                           |
| Account not supported                                  | Account `data_status_error: 15009`.                                                    | Check the account's `products` array, then rely on snapshot Updates from an `update.snapshot` subscription. |
| Account closed, paid off, transferred, or consolidated | Account `data_status_error` is `15001`, `15002`, `15003`, or `15010`.                  | Update your local records. Re-discover via Connect when appropriate.                                        |
| Authentication or account detail mismatch              | Account `data_status_error` is `15005` or `15007`.                                     | Refresh identity or account details, then re-enroll or re-discover the account.                             |
| Delinquent or disabled liability                       | Account `data_status_error` is `15008` or `15011`.                                     | Surface the state to the user or contact support if unexpected.                                             |

```json theme={null}
{
  "id": "upt_NYV5kfjskTTCJ",
  "status": "failed",
  "error": {
    "type": "UPDATE_FAILED",
    "sub_type": "UPDATE_TEMPORARILY_UNAVAILABLE",
    "code": 21001,
    "message": "Update is temporarily unavailable for this account."
  }
}
```

For the granular reason, read the underlying account liability's `data_status_error`. These are the codes exposed by the API:

| Code    | Reason                     | What it means                                                                                                                                                | Recommended action                                                        |
| ------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `15001` | Closed                     | The account has been closed at the institution.                                                                                                              | Update your local records. Don't retry.                                   |
| `15002` | Paid in full               | The liability has been paid off.                                                                                                                             | Update your local records. Don't retry.                                   |
| `15003` | No longer serviced         | The institution no longer services this account (e.g. transferred or sold).                                                                                  | Update your local records. Don't retry.                                   |
| `15004` | Unauthorized / sync failed | Catch-all for transient and connection-level failures (institution timeouts, technical issues, outside-hours, internal errors, repeated failure throttling). | Retry after a delay. If persistent, contact support.                      |
| `15005` | Invalid holder details     | The institution rejected the holder details Method has on file (e.g., DOB, postal code, KYC).                                                                | Refresh the entity's identity data and re-enroll.                         |
| `15006` | Temporarily unavailable    | Generic temporary failure.                                                                                                                                   | Retry after a delay.                                                      |
| `15007` | Invalid account number     | The account number Method has is no longer valid at the institution.                                                                                         | Re-discover the account via Connect.                                      |
| `15008` | Delinquent                 | The account is in a delinquent state at the institution.                                                                                                     | Surface this to the user. Don't retry until resolved.                     |
| `15009` | Unsupported merchant       | The institution doesn't support real-time data connections for this account type.                                                                            | Rely on snapshot Updates delivered via an `update.snapshot` subscription. |
| `15010` | Consolidated loan          | The student loan has been consolidated into a different loan.                                                                                                | Re-discover via Connect.                                                  |
| `15011` | Liability disabled         | Updates have been disabled for this liability.                                                                                                               | Don't retry. Contact support if unexpected.                               |

<Note>
  Rate limiting is not currently exposed as a distinct Update failure code. Repeated failure throttling may appear under the catch-all sync failed reason (`15004`).
</Note>

## Retry Strategy

```
1. First retry: wait 5 minutes
2. Second retry: wait 30 minutes
3. Third retry: wait 2 hours
4. After 3 failures: display the most recent snapshot data and alert your CSM
```

Use [idempotency keys](/reference/idempotency) when retrying to avoid duplicate requests.

## Fallback Pattern: Direct to Snapshot

When direct Updates aren't available or keep failing, snapshot data provides a reliable baseline. Note that `POST /accounts/{acc_id}/updates` always creates a direct Update; you cannot request a snapshot Update on demand. Snapshot Updates are produced by `update.snapshot` [subscriptions](/guides/updates/subscriptions) and delivered via webhook.

To fall back to snapshot data, list the account's existing Updates and use the most recent one whose `source` is `snapshot`:

```bash theme={null}
curl "https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates?source=snapshot" \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

If no snapshot Update exists yet, create an `update.snapshot` subscription so future bureau refreshes are delivered automatically:

```bash theme={null}
curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{"enroll": "update.snapshot"}'
```

## UX Recommendations

* **Always show the most recent known data**, even if it's stale. A balance from last week is better than a blank screen.
* **Indicate freshness.** Show the `data_as_of` timestamp so users know how current the data is: "Balance as of March 20, 2024."
* **Show refresh state.** When an Update is in progress, show a loading indicator alongside the existing data.
* **Don't block on failures.** If a direct Update fails, display the last snapshot data and retry in the background.

## Subscription Failures

For failed subscription executions, Method requeues the subscription execution for retry. The subscription queue retries failed executions daily up to three times, then schedules the next run according to the subscription's normal cadence.

Monitor `update.update` webhooks for failed Updates to detect persistent issues with specific accounts or institutions and to drive your own fallback (e.g., showing snapshot data, prompting the user to reconnect for `15005`/`15007`).

## Fields by Liability Type

The data returned in an Update depends on the account type. Common patterns:

| Liability Type | Key Fields                                                                                          |
| -------------- | --------------------------------------------------------------------------------------------------- |
| Credit Card    | balance, available\_credit, credit\_limit, interest\_rate (min/max/type), payment info, opened\_at  |
| Auto Loan      | balance, interest\_rate, original\_loan\_amount, term\_length, expected\_payoff\_date, payment info |
| Student Loan   | balance, original\_loan\_amount, term\_length, payment info                                         |
| Mortgage       | balance, interest\_rate, original\_loan\_amount, term\_length, expected\_payoff\_date, payment info |
| Personal Loan  | balance, available\_credit, interest\_rate, original\_loan\_amount, term\_length, payment info      |

All types share: `balance`, `last_payment_amount`, `last_payment_date`, `next_payment_due_date`, `next_payment_minimum_amount`, `opened_at`, `closed_at`.

For the full Updates API, see the [Updates reference](/reference/accounts/updates/overview).


# Update Lifecycle
Source: https://docs.methodfi.com/guides/updates/lifecycle

The stages of an Update request and how to track them.

## Update Lifecycle

### Status Transitions

```
Created -> Processing -> Completed -> Failed
```

| Status       | Description                                                                      | What to do                                                                                      |
| ------------ | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `pending`    | Request submitted, queued for processing.                                        | Wait for webhook or poll.                                                                       |
| `processing` | Method is actively retrieving data from the source.                              | Wait. Direct Updates typically complete within seconds to minutes depending on the institution. |
| `completed`  | Data is available. The liability-type object (e.g., `credit_card`) is populated. | Read the data, update your local store, display to user.                                        |
| `failed`     | Retrieval was unsuccessful. The `error` object is populated with details.        | See [Handling Failures](/guides/updates/failures).                                              |

### Timing Expectations

* **Snapshot Updates:** Return synchronously in the POST response. No lifecycle to track. The response is immediately `completed` (or `failed`).
* **Direct Updates:** Asynchronous. Typical completion time varies by institution. Most complete within seconds, some may take up to a few minutes. Design your UI to show a loading state and handle the webhook.

### Webhook Events

| Event           | When it fires                                                                                 |
| --------------- | --------------------------------------------------------------------------------------------- |
| `update.create` | An Update has been created (status: `pending`).                                               |
| `update.update` | An Update's status has changed (typically `pending` to `completed` or `pending` to `failed`). |

Subscribe to `update.update` to react when data is ready. The webhook payload includes the path to retrieve the full Update object.

### Idempotency

If you need to retry a failed Update, use [idempotency keys](/reference/idempotency) to avoid creating duplicate requests.


# Updates
Source: https://docs.methodfi.com/guides/updates/overview

How Method keeps account data fresh, snapshot vs direct sources.

## Keeping Account Data Fresh and Accurate

### What an Update Is

An Update is the mechanism through which Method delivers the latest state of a connected account: current balance, payment due date, minimum payment amount, interest rate, credit limit, and other relevant fields depending on the account type. If [Connect](/guides/connect/overview) is how you discover accounts, Updates are how you keep those accounts' data current over time.

The freshness and accuracy of your account data directly impacts the quality of your product experience. A debt repayment app that shows last month's balance feels broken. A payment scheduler that uses stale due dates risks missed payments. Updates are how you ensure your product reflects financial reality, not an outdated snapshot.

### Two Sources of Truth: Snapshot vs. Direct

Updates come from two fundamentally different data sources, and choosing between them is an important product decision:

## Checking Update Availability

Before requesting an Update, check the account's `products` array:

* `update` in `products` means direct Updates are available (real-time data from the institution).

If `update` is in `restricted_products` instead of `products`, direct Updates require additional steps (e.g., account verification). If `update` does not appear, data retrieval isn't currently available for this account.

<Tabs>
  <Tab title="Snapshot">
    Pull data from the user's credit report. Credit reports are compiled by the major bureaus and updated when creditors submit their reporting data, typically on a monthly cycle. Snapshot data is available for the broadest range of accounts, but it's only as fresh as the most recent creditor report.

    | Attribute     | Detail                                                                  |
    | ------------- | ----------------------------------------------------------------------- |
    | **Freshness** | Monthly (credit report cycle)                                           |
    | **Delivery**  | Produced by an `update.snapshot` subscription and delivered via webhook |
    | **Coverage**  | Broadest, works for virtually every account                             |

    **Best for:** Building account overview screens, displaying general balance trends, monitoring credit health over time, showing account summaries where approximate data is acceptable, or when you need data for account types where direct connections aren't available. Snapshot Updates are your reliable baseline. They work for virtually every discovered account and provide a good-enough picture for many use cases.

    Snapshot Updates cannot be created on demand. Subscribe to `update.snapshot` so Method delivers a fresh snapshot whenever the bureau reports new data, then retrieve the most recent snapshot from the list endpoint:

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{"enroll": "update.snapshot"}'

    curl "https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates?source=snapshot" \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```
  </Tab>

  <Tab title="Direct">
    Pull data directly from the financial institution in real time. This means the data reflects the account's current state as of the moment the institution responds, including very recent payments, daily interest accrual, and same-day balance changes. Direct Updates are asynchronous (you submit a request and receive the result via webhook when it completes) and take longer, but the data is significantly more current.

    | Attribute     | Detail                                   |
    | ------------- | ---------------------------------------- |
    | **Freshness** | Real-time (as of institution response)   |
    | **Response**  | Async (webhook delivery)                 |
    | **Coverage**  | Narrower, depends on institution support |

    **Best for:** Confirming a balance before initiating a payment, displaying exact payment due dates or minimum payment amounts, current interest rate or APR information, verifying that a recent payment has posted, or when accuracy is critical to your product's core value proposition.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{"type": "direct"}'
    ```
  </Tab>
</Tabs>

<Note>
  Many products use both: snapshot data as the default display, with direct Updates triggered when the user takes an action that requires current data (like preparing to make a payment).
</Note>

## The Update Flow

<Accordion title="On-demand direct Update walkthrough">
  ### On-Demand (Direct) Update

  **Step 1: Request a direct Update**

  ```bash theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{"type": "direct"}'
  ```

  The response returns immediately with `status: pending`:

  ```json theme={null}
  {
    "id": "upt_NYV5kfjskTTCJ",
    "status": "pending",
    "account_id": "acc_yVf3mkzbhz9tj",
    "source": "direct",
    "type": "credit_card",
    "credit_card": null,
    "error": null,
    "created_at": "2024-03-20T04:43:21.434Z",
    "updated_at": "2024-03-20T04:43:21.655Z"
  }
  ```

  ### Step 2: Wait for completion

  Listen for the `update.update` webhook:

  ```json theme={null}
  {
    "type": "update.update",
    "path": "/accounts/acc_yVf3mkzbhz9tj/updates/upt_NYV5kfjskTTCJ"
  }
  ```

  ### Step 3: Retrieve the completed Update

  ```bash theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates/upt_NYV5kfjskTTCJ \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  The completed Update contains the account's current data:

  ```json theme={null}
  {
    "id": "upt_NYV5kfjskTTCJ",
    "status": "completed",
    "account_id": "acc_yVf3mkzbhz9tj",
    "source": "direct",
    "type": "credit_card",
    "data_as_of": "2024-03-20T04:43:21.434Z",
    "credit_card": {
      "available_credit": 120000,
      "balance": 80000,
      "credit_limit": 200000,
      "interest_rate_percentage_max": 23.5,
      "interest_rate_percentage_min": 12.0,
      "interest_rate_type": "variable",
      "last_payment_amount": 5000,
      "last_payment_date": "2024-04-05",
      "next_payment_due_date": "2024-05-01",
      "next_payment_minimum_amount": 4000,
      "opened_at": "2018-10-30"
    },
    "error": null,
    "created_at": "2024-03-20T04:43:21.434Z",
    "updated_at": "2024-03-20T04:43:21.655Z"
  }
  ```
</Accordion>

## Reading the Update Response

The Update response wraps the account data inside a liability-type object. The key fields:

| Field              | Description                                                                                                                                                             |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source`           | `snapshot` or `direct`, which data source this Update used.                                                                                                             |
| `type`             | The liability type: `credit_card`, `auto_loan`, `student_loans`, `mortgage`, `personal_loan`, etc.                                                                      |
| `data_as_of`       | Timestamp of when this data was current. For direct, this is the moment the institution responded. For snapshot, this is when the creditor last reported to the bureau. |
| `[liability_type]` | The data object (e.g., `credit_card`, `auto_loan`). Contains the balance, rates, payment info, and dates specific to that account type.                                 |
| `status`           | `pending`, `processing`, `completed`, or `failed`. See [Update Lifecycle](/guides/updates/lifecycle).                                                                   |
| `error`            | Populated if the Update failed. See [Handling Failures](/guides/updates/failures).                                                                                      |

<Note>
  **All monetary amounts are in cents.** A `balance` of `80000` means \$800.00. A `last_payment_amount` of `5000` means \$50.00.
</Note>

## Next Steps

<CardGroup>
  <Card title="Update Subscriptions" icon="arrows-rotate" href="/guides/updates/subscriptions">
    Set up automatic data refreshes without manual requests.
  </Card>

  <Card title="Update Lifecycle" icon="arrows-spin" href="/guides/updates/lifecycle">
    Understand the stages of an Update request.
  </Card>

  <Card title="Handling Failures" icon="triangle-exclamation" href="/guides/updates/failures">
    Design resilient UX around failed or stale data.
  </Card>

  <Card title="Updates API Reference" icon="code" href="/reference/accounts/updates/overview">
    Full endpoint documentation, fields, and error codes.
  </Card>
</CardGroup>


# Update Subscriptions
Source: https://docs.methodfi.com/guides/updates/subscriptions

Set-and-forget monitoring to keep account data current.

## What Update Subscriptions Do

For products that need to keep data current without requiring users to manually refresh, Update Subscriptions provide a set-and-forget monitoring capability.

* A direct Update subscription tells Method to periodically pull fresh data from the financial institution and deliver it to you via webhook as it becomes available. The refresh cadence depends on the institution and account type.
* A snapshot-only subscription delivers new data whenever the credit report refreshes (typically monthly), ensuring your baseline data stays current without manual intervention.

Subscriptions are essential for: dashboards and account overview screens that should always show reasonably current data, alerting systems that detect changes (missed payments, balance spikes, rate changes), progress tracking features that show debt paydown over time, and any feature where the user expects data to be fresh without taking action.

The combination of on-demand Updates for user-initiated actions and subscription-based Updates for background freshness gives you a complete data strategy.

## Creating a Subscription

You can set up subscriptions either at Connect time (recommended for new accounts) or individually on existing accounts.

### At Connect Time (Recommended)

Include `subscriptions` in your Connect request to automatically subscribe all discovered accounts:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptions": ["update"]
  }'
```

### On an Existing Account

```bash theme={null}
curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{"enroll": "update"}'
```

## Subscription Types

| Type              | What it does                                                                                                                                                     |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `update`          | Periodically pulls real-time data directly from the financial institution and delivers via webhook. Refresh cadence depends on the institution and account type. |
| `update.snapshot` | Delivers new credit report data whenever the bureau refreshes (typically monthly). Lower cost, broader coverage.                                                 |

<Note>
  Check the account's `available_subscriptions` array before creating a subscription. If `update` isn't listed, direct subscriptions aren't available for that account.
</Note>

### Refresh Cadence

<Note>
  The frequency of updates for direct subscriptions depends on the liability type and the individual account. Credit cards generally update more frequently (every 1 to 3 days), while personal loans and mortgages typically refresh every \~30 days, aligning with billing cycles and account activity. Snapshot subscriptions refresh whenever the credit bureau receives updated data from the creditor, usually on a monthly basis.
</Note>

## Receiving Updates via Webhook

When a subscription triggers a refresh, Method sends an `update.create` webhook when the Update is created, followed by an `update.update` webhook when its status changes (typically to `completed` or `failed`):

```json theme={null}
{
  "type": "update.update",
  "path": "/accounts/acc_yVf3mkzbhz9tj/updates/upt_NYV5kfjskTTCJ"
}
```

Retrieve the Update from the path to get the fresh data. Your application should process these webhooks to update its local data store or cache.

## Managing Subscriptions

* **List active subscriptions:** `GET /accounts/{acc_id}/subscriptions`
* **Delete a subscription:** `DELETE /accounts/{acc_id}/subscriptions/{sub_id}`

Subscriptions remain active until explicitly deleted or the account is disabled/closed.

## When to Use Subscriptions vs On-Demand Updates

| Scenario                                      | Approach                          |
| --------------------------------------------- | --------------------------------- |
| Dashboard showing current balances            | Subscription (background refresh) |
| Pre-payment balance confirmation              | On-demand direct Update           |
| Debt paydown progress tracking                | Subscription                      |
| One-time underwriting check                   | On-demand direct Update           |
| Alerting on missed payments or balance spikes | Subscription                      |


# Getting Started
Source: https://docs.methodfi.com/guides/use-cases/commerce/getting-started

Create an entity, verify identity, and connect credit cards — the foundational 3-step flow for every commerce integration.

Every commerce integration begins the same way: represent your customer, verify their identity, and discover their credit cards. This 3-step flow is the shared foundation for [Wallet Onboarding](/guides/use-cases/commerce/wallet-onboarding), [Preauth Signals](/guides/use-cases/commerce/preauth-signals), and [Wallet Intelligence](/guides/use-cases/commerce/wallet-intelligence).

<Steps>
  <Step title="Create an Entity">
    Every end user maps to an [Entity](/guides/entities/overview) in Method. Create one with the user's full name and phone number, and provide additional identity information such as date of birth, email address, or SSN when available to improve match rates. This is the foundational object that verification, card discovery, and all downstream products attach to.

    ```bash theme={null}
    curl https://production.methodfi.com/entities \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "individual",
        "individual": {
          "first_name": "Emily",
          "last_name": "Park",
          "phone": "+13105550789",
          "email": "emily.park@email.com",
          "dob": "1995-11-08"
        },
        "address": {
          "line1": "789 Sunset Blvd",
          "line2": null,
          "city": "Los Angeles",
          "state": "CA",
          "zip": "90028"
        }
      }'
    ```

    ```json theme={null}
    {
      "id": "ent_BzirqpLEm3BW7",
      "type": "individual",
      "individual": {
        "first_name": "Emily",
        "last_name": "Park",
        "phone": "+13105550789",
        "dob": "1995-11-08",
        "email": "emily.park@email.com",
        "ssn_4": null,
        "ssn": null
      },
      "error": null,
      "address": {
        "line1": "789 Sunset Blvd",
        "line2": null,
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90028"
      },
      "status": "incomplete",
      "verification": {
        "identity": {
          "verified": false,
          "matched": false,
          "latest_verification_session": null,
          "methods": [
            "element",
            "kba"
          ]
        },
        "phone": {
          "verified": false,
          "latest_verification_session": null,
          "methods": [
            "sms",
            "sna",
            "byo_sms"
          ]
        }
      },
      "connect": null,
      "credit_score": null,
      "products": [
        "identity"
      ],
      "restricted_products": [
        "connect",
        "credit_score",
        "attribute"
      ],
      "subscriptions": [],
      "available_subscriptions": [
        "connect",
        "credit_score"
      ],
      "restricted_subscriptions": [],
      "metadata": null,
      "created_at": "2025-12-10T14:22:31.024Z",
      "updated_at": "2025-12-10T14:22:31.024Z"
    }
    ```

    The Entity is created in `incomplete` status. Before you can discover Emily's credit cards, you need to verify her identity.
  </Step>

  <Step title="Verify Identity">
    Method requires phone verification before card discovery. Verify the customer's phone number using either **Method OTP** (Method sends and verifies the one-time passcode) or **Bring Your Own OTP** (you verify the phone number yourself and provide the verification result to Method). The example below initiates a Method-sent SMS verification session, which sends a one-time code to Emily's phone number on record.

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/verification_sessions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "sms",
        "sms": {}
      }'
    ```

    ```json theme={null}
    {
      "id": "evf_nKLp7WzQdR4mF",
      "entity_id": "ent_BzirqpLEm3BW7",
      "status": "in_progress",
      "type": "phone",
      "method": "sms",
      "sms": {},
      "error": null,
      "created_at": "2025-12-10T14:23:12.271Z",
      "updated_at": "2025-12-10T14:23:12.271Z"
    }
    ```

    After Emily receives and submits the SMS code, the verification session transitions to `verified`. Once both phone and identity verification are complete, the Entity status updates to `active` and Connect becomes available.

    <Note>
      For a complete overview of all verification methods (SMS, SNA, BYO-SMS, KBA), see the [Identity Verification](/guides/identity-verification/overview) guide.
    </Note>
  </Step>

  <Step title="Connect Credit Cards">
    With verification complete, call Connect to discover Emily's credit cards via a soft-pull credit report. This has no impact on the user's credit score.

    For commerce use cases, the key discovery is **credit cards**: these are the accounts you'll use for wallet onboarding, preauth signals, and wallet intelligence.

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    ```json theme={null}
    {
      "id": "cxn_7hTmRvXkYpN3w",
      "entity_id": "ent_BzirqpLEm3BW7",
      "status": "completed",
      "accounts": [
        "acc_LxwEqNicr66yP",
        "acc_4m9amk4KFiaQX",
        "acc_XtKTpHLGhD9Qn",
        "acc_GAzrD99cUqGEN"
      ],
      "requested_products": [],
      "requested_subscriptions": [],
      "error": null,
      "created_at": "2025-12-10T14:24:45.645Z",
      "updated_at": "2025-12-10T14:24:45.645Z"
    }
    ```

    Method discovered 4 credit card accounts for Emily:

    | Account ID          | Card                            |
    | ------------------- | ------------------------------- |
    | `acc_LxwEqNicr66yP` | Chase Sapphire Preferred (Visa) |
    | `acc_4m9amk4KFiaQX` | Amex Gold (Amex)                |
    | `acc_XtKTpHLGhD9Qn` | Citi Double Cash (Mastercard)   |
    | `acc_GAzrD99cUqGEN` | Capital One Venture X (Visa)    |

    These accounts are now ready for every Commerce use case.
  </Step>
</Steps>

## What's Next

<CardGroup>
  <Card title="Wallet Onboarding" icon="wallet" href="/guides/use-cases/commerce/wallet-onboarding">
    Enrich cards with brand art and retrieve payment credentials to render a complete wallet.
  </Card>

  <Card title="Preauth Signals" icon="signal" href="/guides/use-cases/commerce/preauth-signals">
    Evaluate payment readiness before authorization and optimize payment retries.
  </Card>

  <Card title="Wallet Intelligence" icon="lightbulb" href="/guides/use-cases/commerce/wallet-intelligence">
    Retrieve wallet-level insights to personalize customer experiences.
  </Card>
</CardGroup>


# Commerce
Source: https://docs.methodfi.com/guides/use-cases/commerce/overview

Connect customers' credit cards, reduce failed payments, and personalize customer experiences with Method's Commerce APIs.

## What This Section Covers

Learn how to use Method's Commerce APIs to:

* **Connect every credit card** a customer owns in a single flow.
* **Evaluate payment readiness** before authorizing a transaction.
* **Retry failed payments at the optimal time** to improve recovery.
* **Personalize customer experiences** using wallet intelligence.

Whether you're building a wallet, improving payment success, or personalizing customer experiences, every Commerce integration follows the same core workflow.

```mermaid theme={null}
flowchart TD
    A[Create Entity] --> B[Verify Identity]
    B --> C[Connect Credit Cards]
    C --> D[Wallet Onboarding]
    C --> E[Preauth Signals]
    C --> F[Wallet Intelligence]
    style C fill:#00B29D,color:#fff
```

## Commerce Use Cases

| Use case                                                                  | Core endpoints                                  | Use when you want to                                                                                                           |
| ------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| [**Wallet Onboarding**](/guides/use-cases/commerce/wallet-onboarding)     | Entity-Connect, Card Brand, Payment Instruments | Reduce onboarding friction by letting customers connect all their credit cards in one flow                                     |
| [**Preauth Signals**](/guides/use-cases/commerce/preauth-signals)         | Entity-Connect, Preauth Signals                 | Increase payment success by evaluating payment readiness before authorization and retrying failed payments at the optimal time |
| [**Wallet Intelligence**](/guides/use-cases/commerce/wallet-intelligence) | Entity-Connect, Attributes                      | Personalize offers and product experiences based on customers' credit cards                                                    |

## Two Integration Paths

<Tabs>
  <Tab title="API-Only">
    Integrate directly with Method's APIs for entity creation, identity verification, Connect, and all downstream card operations. You build the user-facing flow and have full control over the UX.

    PCI compliance is not required: by default, tokenization returns network tokens that don't expose raw card credentials.
  </Tab>

  <Tab title="Embedded UI (Opal)">
    Use [Opal Card Connect](/opal/card_connect/overview) as a drop-in UI for identity verification and card discovery. Opal handles the user-facing flow while you use the API for card brand enrichment, payment instruments, and wallet attributes.
  </Tab>
</Tabs>

## Get Started

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="/guides/use-cases/commerce/getting-started">
    The 3-step setup: create an entity, verify identity, and connect credit cards.
  </Card>

  <Card title="Wallet Onboarding" icon="wallet" href="/guides/use-cases/commerce/wallet-onboarding">
    Connect every credit card without manual entry, then enrich and tokenize for checkout.
  </Card>

  <Card title="Preauth Signals" icon="signal" href="/guides/use-cases/commerce/preauth-signals">
    Evaluate payment readiness before authorization and optimize payment retries.
  </Card>

  <Card title="Wallet Intelligence" icon="lightbulb" href="/guides/use-cases/commerce/wallet-intelligence">
    Retrieve wallet-level insights to personalize customer experiences.
  </Card>
</CardGroup>


# Preauth Signals
Source: https://docs.methodfi.com/guides/use-cases/commerce/preauth-signals

Evaluate payment readiness before authorization and retry failed payments at the optimal time.

Evaluate payment readiness before authorization and optimize payment retries. After your customer has connected their credit cards, evaluate each card before attempting a payment. Method returns behavioral signals used to estimate payment readiness and recommends when to retry failed payments.

<Note>
  **Public preview.** Preauth Signals is in public preview. Contact your Method CSM to request access.
</Note>

## Prerequisites

Before using Preauth Signals, complete the [Getting Started](/guides/use-cases/commerce/getting-started) flow:

* Entity created
* Identity verified
* Credit cards connected

## Why Use It?

* **Reduce involuntary churn:** Identify the best time to retry failed payments.
* **Increase authorization rates:** Know a payment's likelihood of success before sending it to the network.

## How It Works

Before attempting a payment, create a Preauth Signals assessment for the card, then retrieve the result to decide whether to authorize now or retry later.

```mermaid theme={null}
flowchart TD
    A["Create Preauth Signals<br/>POST /preauth"] --> B["Retrieve Preauth Signals<br/>GET /preauth/{preauth_id}"]
    B --> C[Authorize now]
    B --> D[Retry later]
    style C fill:#00B29D,color:#fff
```

<Steps>
  <Step title="Create Preauth Signals">
    Create a Preauth Signals assessment with `POST /preauth`. Provide either an authenticated Method `account_id` or a `card` object to identify the payment method. You can also include `purchase` context, such as the transaction amount or merchant category code (MCC), to improve the assessment.

    ```bash theme={null}
    curl https://production.methodfi.com/preauth \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "account_id": "acc_4m9amk4KFiaQX",
        "purchase": {
          "amount": 9999,
          "mcc": "4511"
        }
      }'
    ```
  </Step>

  <Step title="Retrieve Preauth Signals">
    Retrieve the completed assessment with `GET /preauth/{preauth_id}` to determine whether to authorize the payment immediately or retry later.

    ```bash theme={null}
    curl https://production.methodfi.com/preauth/preauth_qV7kRaFm4JNxw \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    ```json theme={null}
    {
      "id": "preauth_qV7kRaFm4JNxw",
      "account_id": "acc_4m9amk4KFiaQX",
      "status": "completed",
      "verified_ownership": "match",
      "card_standing": "open",
      "success_likelihood": 0.87,
      "optimal_retry_date": "2026-06-02",
      "error": null,
      "metadata": null,
      "created_at": "2026-05-28T14:00:00.000Z",
      "updated_at": "2026-05-28T14:00:00.180Z"
    }
    ```

    | Field                | Description                                               |
    | -------------------- | --------------------------------------------------------- |
    | `success_likelihood` | Estimated likelihood that the payment will authorize.     |
    | `optimal_retry_date` | Recommended retry date if the payment does not authorize. |

    Use `success_likelihood` to choose the best card for a payment, and `optimal_retry_date` to schedule retries for failed payments.
  </Step>
</Steps>

## What's Next

<CardGroup>
  <Card title="Wallet Intelligence" icon="lightbulb" href="/guides/use-cases/commerce/wallet-intelligence">
    Retrieve wallet-level insights to personalize customer experiences.
  </Card>

  <Card title="Preauth Signals API Reference" icon="signal" href="/reference/preauth/overview">
    Full API documentation for Preauth Signals.
  </Card>
</CardGroup>


# Wallet Intelligence
Source: https://docs.methodfi.com/guides/use-cases/commerce/wallet-intelligence

Retrieve wallet-level behavioral attributes to power recommendations, segmentation, and personalized product experiences.

Retrieve wallet-level insights to personalize customer experiences. After connecting a customer's credit cards, retrieve wallet-level behavioral attributes to power recommendations, segmentation, and personalized product experiences.

## Prerequisites

Before using Wallet Intelligence, complete the [Getting Started](/guides/use-cases/commerce/getting-started) flow:

* Entity created
* Identity verified
* Credit cards connected

## Why Use It?

* **Reach the right audience:** Identify the customers most likely to benefit from every offer.
* **Power partner offers:** Deliver issuer and partner offers only to eligible customers.
* **Design better experiences:** Understand wallet trends and customer behavior to inform product decisions.
* **Complete customer profiles:** Enrich the customer data you already have.

## How It Works

Retrieve the attributes of the customer's wallet with a single request: `POST /entities/{ent_id}/attributes`. Method returns behavioral attributes computed across every connected credit card in the customer's wallet, including:

* Overall utilization
* Credit card utilization
* Usage patterns
* Payment behavior
* Balance trends

```bash theme={null}
curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/attributes \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

This endpoint is asynchronous. The initial response returns `status: in_progress`. Retrieve the completed attributes by subscribing to the `entity_attribute.create` webhook or polling the [retrieve endpoint](/reference/entities/attributes/retrieve).

Below is an example of a completed response:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "attr_dADraNgLBrhgL",
    "entity_id": "ent_BzirqpLEm3BW7",
    "status": "completed",
    "attributes": {
      "usage_pattern":           { "value": "transactor", "error": null, "metadata": null },
      "credit_card_utilization": { "value": 11.96, "error": null, "metadata": null },
      "overall_utilization":     { "value": 18.4, "error": null, "metadata": null }
    },
    "error": null,
    "created_at": "2026-04-09T17:02:47.910Z",
    "updated_at": "2026-04-09T17:04:35.220Z"
  }
}
```

Each attribute returns `{ value, error }`. When data is insufficient (for example, not enough history for a 60-day delta), `value` is `null` and `error` is populated with details.

Use these attributes to build better experiences, personalize offers, segment customers, and improve targeting.

## What's Next

<CardGroup>
  <Card title="Attributes API Reference" icon="chart-line" href="/reference/entities/attributes/overview">
    Full API documentation for Entity Attributes.
  </Card>

  <Card title="Wallet Onboarding" icon="wallet" href="/guides/use-cases/commerce/wallet-onboarding">
    Connect every credit card without manual entry.
  </Card>
</CardGroup>


# Wallet Onboarding
Source: https://docs.methodfi.com/guides/use-cases/commerce/wallet-onboarding

Connect every credit card a customer owns without manual entry, then enrich and tokenize the cards to render a complete wallet.

Connect every credit card without manual entry. Using a customer's name and phone number, Method discovers the credit cards they own, verifies ownership, and returns the metadata needed to render a complete wallet.

## Why Use It?

* **Faster onboarding:** Connect every credit card in one simple and seamless flow.
* **Frictionless checkout:** Let customers pay instantly with any of their credit cards, with no manual entry.
* **Rewards activation:** Enable customers to connect all their credit cards and start earning rewards across every eligible purchase.
* **Payment resilience:** Keep multiple credit cards on file to automatically recover failed payments and reduce churn.

## How It Works

```mermaid theme={null}
flowchart TD
    A["Create Entity<br/>POST /entities"] --> B["Verify Identity<br/>POST /verification_sessions"]
    B --> C["Discover Credit Cards<br/>POST /connect"]
    C --> D["Enrich Cards<br/>POST /card_brands"]
    D --> E["Retrieve Payment Cards<br/>POST /payment_instruments"]
    E --> F[Complete Wallet]
    style F fill:#00B29D,color:#fff
```

<Steps>
  <Step title="Create an Entity">
    Create an [Entity](/guides/entities/overview) to represent your customer. Include their full name and phone number, and provide additional identity information such as date of birth, email address, or SSN when available to improve match rates.
  </Step>

  <Step title="Verify the Customer's Identity">
    Verify the customer's phone number using either **Method OTP** (Method sends and verifies the one-time passcode) or **Bring Your Own OTP** (you verify the phone number yourself and provide the verification result to Method). See the [Identity Verification](/guides/identity-verification/overview) guide for all supported methods.
  </Step>

  <Step title="Discover the Customer's Credit Cards">
    Call [Connect](/guides/connect/overview) to discover the credit card accounts your customer holds via a soft-pull credit report, with no impact on their credit score.

    <Note>
      Steps 1-3 are the same foundational flow used by every Commerce use case. See [Getting Started](/guides/use-cases/commerce/getting-started) for full request and response examples.
    </Note>
  </Step>

  <Step title="Enrich the Discovered Cards">
    For each account returned by Connect, call [Card Brand](/guides/additional-products/card-brand) to retrieve enriched card metadata, including the issuer, card network, card product, card artwork, and rewards program. Use this metadata to render your customer's wallet with recognizable card visuals.

    Here's a card brand request for Emily's Chase Sapphire Preferred (`acc_LxwEqNicr66yP`):

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_LxwEqNicr66yP/card_brands \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    ```json theme={null}
    {
      "id": "cbrd_Accm7P6t6mYQP",
      "account_id": "acc_LxwEqNicr66yP",
      "brands": [
        {
          "id": "pdt_27_brd_1",
          "card_product_id": "pdt_27",
          "description": "Chase Sapphire Preferred",
          "name": "Chase Sapphire Preferred",
          "issuer": "Chase",
          "network": "visa",
          "network_tier": "signature",
          "type": "specific",
          "url": "https://static.methodfi.com/card_brands/7d2f8a1bc3e5f094a6d831e5c7b29f04.png"
        }
      ],
      "status": "completed",
      "source": "method",
      "error": null,
      "created_at": "2025-12-10T14:30:12.139Z",
      "updated_at": "2025-12-10T14:30:12.139Z"
    }
    ```

    The `brands` array contains the card product details. Use `name` for display, `url` for the card art image, `issuer` for the bank name, and `network` / `network_tier` for routing decisions.

    <Note>
      Card Brand is an asynchronous operation. The response above shows a completed request; in practice, subscribe to the `card_brand.completed` webhook to know when brand data is ready.
    </Note>
  </Step>

  <Step title="Retrieve Available Payment Cards">
    For each account returned by Connect, create a [Payment Instrument](/reference/accounts/payment-instruments/overview) to retrieve the card credentials required for checkout.

    Request a `network_token` Payment Instrument to receive a network-provisioned token instead of the raw card number. No raw card credentials are exposed to your systems, so you don't need PCI compliance, and network tokens typically yield better authorization rates.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_GAzrD99cUqGEN/payment_instruments \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "network_token"
      }'
    ```

    If your processor requires raw card data, request a `card` Payment Instrument instead to receive the full credentials: number, expiration date, CVV, and billing zip code. This approach exposes PAN data to your systems and requires PCI compliance.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_GAzrD99cUqGEN/payment_instruments \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "card"
      }'
    ```

    ```json theme={null}
    {
      "success": true,
      "data": {
        "id": "pmt_inst_pd788hPVhLT37",
        "account_id": "acc_GAzrD99cUqGEN",
        "type": "card",
        "card": {
          "number": "4000120000001154",
          "exp_month": "09",
          "exp_year": "2028",
          "cvv": "878",
          "billing_zip_code": "90028"
        },
        "network_token": null,
        "inbound_achwire_payment": null,
        "chargeable": true,
        "status": "completed",
        "error": null,
        "created_at": "2025-12-10T14:35:22.039Z",
        "updated_at": "2025-12-10T14:35:22.039Z"
      },
      "message": null
    }
    ```

    <Warning>
      Payment Instruments is a gated product that requires approval. Contact your Method representative to enable access.
    </Warning>
  </Step>
</Steps>

<Note>
  **Alternative path:** If you don't need complete control over the onboarding experience, [Opal](/opal/overview) provides an embedded flow that handles identity verification and card discovery for you.
</Note>

## What's Next

<CardGroup>
  <Card title="Preauth Signals" icon="signal" href="/guides/use-cases/commerce/preauth-signals">
    Evaluate payment readiness before authorizing a transaction.
  </Card>

  <Card title="Card Brand API Reference" icon="credit-card" href="/reference/accounts/card-brands/overview">
    Full API documentation for Card Brand.
  </Card>

  <Card title="Payment Instruments API Reference" icon="key" href="/reference/accounts/payment-instruments/overview">
    Full API documentation for Payment Instruments.
  </Card>
</CardGroup>


# Mortgage & HELOC
Source: https://docs.methodfi.com/guides/use-cases/lending/mortgage-heloc

Top-of-funnel qualification through portfolio targeting for secured-lending teams.

*Top-of-funnel qualification through portfolio targeting for secured-lending teams.*

Pull a borrower's full liability picture before pre-approval, size HELOC and refi offers against real-time balances and APRs, and continuously surface existing customers who are in the market for a HELOC or new mortgage. From nothing more than a name and phone, Method discovers every liability a borrower holds (mortgages, HELOCs, credit cards, auto, student, and personal loans), pulls current balances, APRs, and payment behavior directly from each financial institution, and keeps that picture refreshed after the borrower is in the book. The same data fabric powers two motions: origination (pre-qualification and HELOC/refi sizing) and portfolio intelligence (continuous monitoring to surface HELOC- and mortgage-ready customers before they shop elsewhere).

## How it works

Create the borrower Entity, verify them, run Connect to discover their liabilities, then subscribe to the v2 attribute set for a continuous, real-time view. All examples use `Method-Version: 2026-03-30`. Monetary values are in **cents** (`1420000` = \$14,200.00); utilization is a percentage (`37.4` = 37.4%); deltas are percentage points.

<Steps>
  <Step title="Create the Entity">
    `POST /entities`. You only need `first_name`, `last_name`, and `phone`. An Entity can be created minimally and enriched later; passing `dob` and `ssn_4` when you have them measurably improves match rates during account discovery, so include them in production where available. The Entity returns `status: "incomplete"` with `connect`, `credit_score`, and `attribute` in `restricted_products` until verification completes.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{
          "type": "individual",
          "individual": {
            "first_name": "Maya",
            "last_name": "Chen",
            "phone": "+13105550147"
          }
        }'
      ```

      ```json theme={null}
      {
        "id": "ent_BzirqpLEm3BW7",
        "type": "individual",
        "individual": {
          "first_name": "Maya",
          "last_name": "Chen",
          "phone": "+13105550147"
        },
        "status": "incomplete",
        "products": ["identity"],
        "restricted_products": ["connect", "credit_score", "attribute"],
        "available_subscriptions": ["connect", "credit_score"]
      }
      ```
    </Expandable>
  </Step>

  <Step title="Verify the borrower (BYO SMS + BYO KYC)">
    Verification must complete before Connect, credit, and attribute products unlock. The lending flows in these guides use BYO SMS and BYO KYC, which let you assert results you already captured in your own onboarding. Both require your team to be pre-authorized, so contact your Method CSM to enable them. For other verification methods, see [Verification Methods](/guides/identity-verification/methods). Once both sessions complete, the Entity moves to `status: "active"` and `connect`, `credit_score`, and `attribute` move from `restricted_products` into `products`. For the full walkthrough, see the [Getting Started](/guides/use-cases/lending/getting-started) guide.

    <Expandable title="phone and identity requests">
      Verify the phone with BYO SMS, passing the ISO 8601 timestamp of when you verified the number:

      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/verification_sessions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "type": "phone", "method": "byo_sms", "byo_sms": { "timestamp": "2026-03-30T12:00:00.000Z" } }'
      ```

      Then assert identity with BYO KYC (you're confirming your external KYC process passed for this borrower):

      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/verification_sessions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "type": "identity", "method": "byo_kyc", "byo_kyc": {} }'
      ```
    </Expandable>
  </Step>

  <Step title="Run Connect">
    `POST /entities/{ent_id}/connect`. Connect performs a soft credit pull (no score impact) and returns the account IDs Method created for each liability. The first Connect returns all liability accounts, both active and closed; subsequent calls return only newly discovered accounts.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/connect \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "cxn_4ewMmBbjYDMR4",
        "entity_id": "ent_BzirqpLEm3BW7",
        "status": "completed",
        "accounts": [
          "acc_RGACQH7XdfYhC",
          "acc_TmGPLxkz7Nrh6",
          "acc_WqNhMRNVZjbKg",
          "acc_YXDrjADGjC76U"
        ],
        "error": null
      }
      ```
    </Expandable>
  </Step>

  <Step title="List the discovered accounts">
    `GET /accounts`. Filter to `type=liability` and `status=active` to work with live debt only. Narrow with `liability.type` (e.g. `mortgage`, `credit_card`) to isolate the secured-debt picture that matters for a HELOC decision. For decision-time accuracy, pull a fresh `POST /accounts/{acc_id}/updates` on the accounts that drive the decision (balances on revolving and mortgage debt shift daily).

    <Expandable title="request & response">
      ```bash theme={null}
      curl "https://production.methodfi.com/accounts?holder_id=ent_BzirqpLEm3BW7&type=liability&status=active" \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "data": [
          {
            "id": "acc_RGACQH7XdfYhC",
            "holder_id": "ent_BzirqpLEm3BW7",
            "status": "active",
            "type": "liability",
            "liability": {
              "mch_id": "mch_300012",
              "mask": "8842",
              "ownership": "primary",
              "type": "mortgage",
              "name": "Rocket Mortgage Home Loan"
            },
            "products": ["balance", "update"],
            "restricted_products": ["attribute", "sensitive"]
          },
          {
            "id": "acc_WqNhMRNVZjbKg",
            "holder_id": "ent_BzirqpLEm3BW7",
            "status": "active",
            "type": "liability",
            "liability": {
              "mch_id": "mch_302086",
              "mask": "1580",
              "ownership": "primary",
              "type": "credit_card",
              "name": "Chase Sapphire Reserve Credit Card"
            },
            "products": ["balance", "update", "card_brand"],
            "restricted_products": ["attribute", "sensitive"]
          }
        ]
      }
      ```
    </Expandable>
  </Step>

  <Step title="Enroll the entity in the attribute subscription">
    `POST /entities/{ent_id}/subscriptions` with `enroll: attribute`. Method computes credit-health attributes (utilization, balances, APRs, trends, payment behavior, delinquency flags) at both the entity level and the account level. Pass the `portfolio_intelligence` bundle to onboard the full PI attribute set in one call, plus any HELOC/mortgage-specific attributes you want explicitly. Once enrolled, every account on the entity is eligible for attribute generation; you do not enroll accounts individually. Portfolio Intelligence (`portfolio_intelligence`) is separately enabled, so ask your Method CSM to turn it on first.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{
          "enroll": "attribute",
          "payload": {
            "attributes": {
              "bundles": ["portfolio_intelligence"],
              "requested_attributes": [
                "mortgage_balance_total",
                "heloc_balance_total",
                "heloc_utilization",
                "overall_utilization",
                "revolving_credit_card_balance_total",
                "weighted_average_apr_credit_card",
                "delinquency_flag_credit_cards"
              ]
            }
          }
        }'
      ```

      ```json theme={null}
      {
        "id": "sub_Tm8qNnLx5RjWk",
        "name": "attribute",
        "status": "active",
        "latest_request_id": null,
        "created_at": "2026-04-09T17:00:12.218Z",
        "updated_at": "2026-04-09T17:00:12.218Z"
      }
      ```
    </Expandable>

    Once `status` is `active`, Method begins pulling directly from the borrower's institutions and attribute generation starts.
  </Step>

  <Step title="(Optional) Enroll accounts in Update subscriptions">
    `POST /accounts/{acc_id}/subscriptions` with `enroll: update`. Adds a near-real-time balance/payment event stream on a specific account, on top of the entity attribute layer, useful when you want a webhook the moment a tracked mortgage or card balance moves.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_WqNhMRNVZjbKg/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "update" }'
      ```
    </Expandable>
  </Step>

  <Step title="Pull the entity attribute set">
    `POST /entities/{ent_id}/attributes`. Asynchronous: it returns immediately with `status: "in_progress"` and `attributes: null`, then fires an `entity_attribute.create` webhook when computation completes. Retrieve the finished object via `GET /entities/{ent_id}/attributes/{attr_id}`. Attributes that can't be computed (e.g. a trend with insufficient history, or HELOC attributes for a borrower with no HELOC) return `value: null` with an `error` object rather than failing the whole response.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/attributes \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "attr_Qk9nPmRw3LjTx",
        "entity_id": "ent_BzirqpLEm3BW7",
        "status": "completed",
        "attributes": {
          "mortgage_balance_total":               { "value": 31200000, "error": null, "metadata": null },
          "heloc_balance_total":                  { "value": 0, "error": null, "metadata": null },
          "heloc_utilization":                    { "value": null, "error": { "type": "ENTITY_ATTRIBUTE_INSUFFICIENT_DATA", "code": 27001, "message": "Insufficient data to compute this entity attribute." }, "metadata": null },
          "overall_utilization":                  { "value": 41.8, "error": null, "metadata": null },
          "revolving_credit_card_balance_total":  { "value": 1840000, "error": null, "metadata": null },
          "credit_card_utilization":              { "value": 63.0, "error": null, "metadata": null },
          "weighted_average_apr_credit_card":     { "value": 23.4, "error": null, "metadata": null },
          "usage_pattern":                        { "value": "revolver", "error": null, "metadata": null },
          "payment_to_minimum_ratio_avg_credit_cards": { "value": 1.6, "error": null, "metadata": null },
          "delinquency_flag_credit_cards":        { "value": "on_time", "error": null, "metadata": null }
        }
      }
      ```
    </Expandable>
  </Step>
</Steps>

**Webhooks.** A PI-enrolled entity fires `entity_attribute.create` on the first computation and `entity_attribute.update` thereafter whenever new values are surfaced; account-level signals fire `account_attribute.create` / `account_attribute.update`. Subscribe to these to drive monitoring workflows without polling.

A primer on the full attribute set, entity-vs-account availability, and webhook payloads lives in the [Portfolio Intelligence guide](/guides/use-cases/lending/portfolio-monitoring).

## Pre-qualification

Run the create-and-Connect flow at intake, then read the entity attribute set to qualify before the borrower invests in a full application. Because the data comes straight from each institution rather than a weeks-old bureau snapshot, the pre-approval decision rests on what the borrower actually owes today.

*Key attributes:* `overall_utilization`, `credit_card_utilization`, `usage_pattern`, `delinquency_flag_credit_cards`, `payment_to_minimum_ratio_avg_credit_cards`.

## HELOC expansion

For a HELOC offer, the secured picture and the borrower's revolving leverage drive both eligibility and sizing. Method surfaces the existing mortgage and HELOC balances directly, alongside the unsecured debt that informs capacity.

*Key attributes:* `mortgage_balance_total`, `heloc_balance_total`, `heloc_utilization`, `overall_utilization`, `revolving_credit_card_balance_total`.

## Debt consolidation / refi

A borrower carrying high-APR revolving balances is a consolidation candidate. Method shows the blended rate they're actually paying, so the savings you quote are priced against real debt, not an estimated rate band. The example borrower above carries \$18,400 in revolving balances at a 23.4% blended APR, a clear consolidation target a HELOC or refi will retire. When the borrower accepts, Direct Pay (the Payments API) routes the verified payoff straight to the incumbent creditor.

*Key attributes:* `weighted_average_apr_credit_card`, `revolving_credit_card_balance_total`, `credit_card_utilization`, `personal_loan_monthly_installments_estimate`.

## Portfolio Intelligence: HELOC / mortgage targeting

Enroll existing customers in the attribute subscription and let the continuous attribute stream surface who is in the market. Watch for the signals that indicate HELOC or new-mortgage intent (sustained revolving paydown that frees capacity, rising high-APR balances that a HELOC will consolidate, or an improving overall profile) and trigger a targeted offer before they shop a competitor.

*Key attributes:* `revolving_credit_card_balance_change_30d/60d/90d`, `overall_utilization_delta_90d`, `overall_utilization_trend_90d`, `weighted_average_apr_credit_card`, `mortgage_balance_total`.


# Portfolio Intelligence: Grow
Source: https://docs.methodfi.com/guides/use-cases/lending/portfolio-monitoring-grow

Post-origination monitoring for refi, 2nd loan, CLI, and cross-sell.

*Post-origination monitoring for refi, 2nd loan, CLI, cross-sell.*

After a loan funds, most lenders lose visibility into their borrowers. Method's Portfolio Intelligence monitors the full liability picture continuously after origination, surfacing 91 real-time signals across 8 categories, so growth, retention, risk, and servicing teams reach their best borrowers before competitors do.

## How it works

Funded loans are enrolled in Attributes v2 + Update + Credit Score Subscriptions, Method continuously monitors the borrower's full liability picture across 15,000+ institutions, improvement signals trigger CLI / 2nd-loan / refi workflows, and Direct Pay retires competitor balances when the borrower accepts.

<Steps>
  <Step title="Enroll the entity in the Attributes v2 subscription">
    `POST /entities/{ent_id}/subscriptions` with `enroll: attribute`. Pass the `portfolio_intelligence` bundle to onboard the full PI attribute set in one call. Every account on the entity then becomes eligible for attribute generation, and Method pushes recomputed values as the underlying data changes. Portfolio Intelligence (`portfolio_intelligence`) is a separately enabled product, so ask your Method CSM to turn it on first.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "attribute", "payload": { "attributes": { "bundles": ["portfolio_intelligence"] } } }'
      ```
    </Expandable>
  </Step>

  <Step title="Enroll the borrower's accounts in Update Subscriptions">
    `POST /accounts/{acc_id}/subscriptions` with `enroll: update`.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_TmGPLxkz7Nrh6/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "update" }'
      ```
    </Expandable>
  </Step>

  <Step title="Enroll the entity in Credit Score Subscriptions">
    `POST /entities/{ent_id}/subscriptions` with `enroll: credit_score`.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "credit_score" }'
      ```
    </Expandable>
  </Step>
</Steps>

For Portfolio Intelligence: Grow workflows, the readiness, offer-targeting, consolidation, and LTV sub-flows below pull from this same v2 attribute set.

## Identify readiness

Score every borrower against their live liability picture: who's revolving, who's approaching payoff, who has a balance worth consolidating. Bureau snapshots are already weeks old at the moment of intent.

*Key v2 attributes:* `usage_pattern`, `overall_utilization`, `credit_card_utilization`, `revolving_credit_card_balance_total`, `revolving_credit_card_balance_change_30d`.

## Target with the right offer

Method surfaces APR ranges and live balances. Offers are priced against the rate the borrower is actually paying, not a bureau-estimated rate band.

*Key v2 attributes:* `weighted_average_apr_credit_card`, `revolving_credit_card_balance_total`, `next_payment_minimum_total_credit_cards`, `credit_limit_total`.

## Execute the consolidation

When the borrower accepts, Direct Pay routes a verified payoff directly to the incumbent issuer. Consolidated payoffs cut delinquency up to \~50% vs. cash-to-borrower disbursement.

*Driven by Direct Pay (Payments API) rather than the Attributes endpoint. See the [Direct Pay](/guides/use-cases/lending/debt-consolidation) use case for the payment-initiation flow.*

## Post-origination LTV: 2nd loan and CLI

\~33% of personal-loan customers take a second loan within 6 to 12 months. Continuous monitoring surfaces who's a renewal candidate, and detects when a borrower's external profile improves enough to support a proactive CLI before they shop competitors.

*Key v2 attributes:* `revolving_credit_card_balance_change_90d`, `overall_utilization_delta_90d`, `overall_utilization_trend_90d`, `revolving_credit_card_utilization_delta_90d`, `revolving_credit_card_utilization_trend_90d`.


# Portfolio Intelligence: Protect
Source: https://docs.methodfi.com/guides/use-cases/lending/portfolio-monitoring-protect

Early warning, line decreases, and real-time delinquency and autopay signals.

*Early warning, line decreases, real-time delinquency and autopay signals.*

Bureau won't tell you a borrower just turned off autopay, opened a balance transfer card, or stacked debt, until it's already on your balance sheet. Method catches all three weeks earlier, with direct evidence from the FI. Same data fabric as PI: Grow, applied to loss prevention.

## How it works

Same subscription setup as PI: Grow, with the attribute bundle tuned to distress signals. Distress events (autopay off, DPD progression, balance stacking) fire as webhooks; risk and servicing teams trigger early intervention.

<Steps>
  <Step title="Enroll funded-loan accounts in Update Subscriptions">
    Enroll with `enroll: update` (`POST /accounts/{acc_id}/subscriptions`).

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_TmGPLxkz7Nrh6/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "update" }'
      ```
    </Expandable>
  </Step>

  <Step title="Pull the v2 attribute set tuned for distress signals">
    `POST /entities/{ent_id}/attributes`. Method computes the full set automatically. Consume the delinquency flags, the balance-change deltas, and the payment-to-minimum ratio for distress detection. For continuous monitoring, enroll in the Entity Attributes subscription (`entity_attribute.create` webhook); Method pushes recomputed attributes as the underlying account data changes.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/attributes \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "attr_dADraNgLBrhgL",
        "entity_id": "ent_qKNBB68bfHGNA",
        "status": "completed",
        "attributes": {
          "delinquency_flag_credit_cards":              { "value": "overdue", "error": null, "metadata": null },
          "any_delinquent_flag":                        { "value": true, "error": null, "metadata": null },
          "serious_delinquent_flag":                    { "value": false, "error": null, "metadata": null },
          "delinquency_worst_dpd_bucket":               { "value": "30_dpd", "error": null, "metadata": null },
          "delinquency_accounts_count":                 { "value": 2, "error": null, "metadata": null },
          "delinquent_balance_total":                   { "value": 41200, "error": null, "metadata": { "partial": true, "accounts_with_data": 1, "accounts_total": 2 } },
          "delinquency_progression_flag":               { "value": true, "error": null, "metadata": null },
          "delinquency_recently_cured_flag":            { "value": false, "error": null, "metadata": null },
          "delinquent_outcome":                         { "value": "current", "error": null, "metadata": null },
          "payment_to_minimum_ratio_avg_credit_cards":  { "value": 0.85, "error": null, "metadata": null },
          "revolving_credit_card_balance_change_30d":   { "value": 381700, "error": null, "metadata": null },
          "revolving_credit_card_utilization_delta_30d":{ "value": 8.4, "error": null, "metadata": null },
          "revolving_credit_card_utilization_trend_30d":{ "value": "increasing", "error": null, "metadata": null },
          "credit_card_utilization":                    { "value": 74.2, "error": null, "metadata": null },
          "installment_balance_change_30d":             { "value": 250000, "error": null, "metadata": null }
        }
      }
      ```
    </Expandable>
  </Step>
</Steps>

## Early delinquency detection

Flag delinquency progression weeks before bureau refresh; act on early-cure or workout opportunities while the borrower still has capacity.

*Key v2 attributes:* `delinquency_flag_credit_cards`, `any_delinquent_flag`, `serious_delinquent_flag`, `delinquency_worst_dpd_bucket`, `delinquency_progression_flag`, `delinquent_outcome`, `delinquency_recently_cured_flag`, `delinquency_accounts_count`, `delinquent_balance_total`, `payment_to_minimum_ratio_avg_credit_cards`, `next_payment_minimum_total_credit_cards`.

## Payment-behavior leading indicators

A declining payment-to-minimum ratio flags borrowers before the first missed payment. (Autopay-specific signals such as autopay disablement detection and autopay-enabled counts surface through Account Updates and account-level attributes rather than entity attributes today.)

*Key v2 attributes:* `payment_to_minimum_ratio_avg_credit_cards`.

## Line decreases on stress signals

Detect borrower distress: utilization spikes, balance stacking, rising aggregate utilization. Act on lines before losses materialize.

*Key v2 attributes:* `revolving_credit_card_balance_change_30d`, `revolving_credit_card_utilization_delta_30d`, `revolving_credit_card_utilization_trend_30d`, `credit_card_utilization`, `overall_utilization_delta_30d`.

## Debt stacking and settlement detection

Surface borrowers taking on new debt across institutions before bureau catches up. Use change-over-time attributes across credit cards and installment accounts to detect stacking patterns through the cross-account view.

*Key v2 attributes:* `delinquency_flag_credit_cards`, `installment_balance_change_30d`, `installment_balance_change_60d`, `revolving_credit_card_balance_change_30d`, `revolving_credit_card_balance_change_60d`.


# Getting Started
Source: https://docs.methodfi.com/guides/use-cases/pfm/getting-started

The universal 3-step flow for PFM integrations: create an entity, verify identity, and connect liabilities.

Every PFM integration begins with the same three steps: represent your user as an Entity, verify their identity, and discover their liabilities through Connect. Once these steps are complete, every product in Method's platform becomes available.

This guide walks through the full API flow using a single user, Sarah Chen, whose data threads through the rest of the PFM guides.

<Steps>
  <Step title="Create an Entity">
    An [Entity](/guides/entities/overview) is Method's representation of your end user. You provide their PII, and Method creates a persistent identity that everything else — verification, accounts, payments — attaches to.

    ```bash theme={null}
    curl https://production.methodfi.com/entities \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "individual",
        "individual": {
          "first_name": "Sarah",
          "last_name": "Chen",
          "phone": "+14155550123",
          "email": "sarah.chen@email.com",
          "dob": "1992-07-15"
        },
        "address": {
          "line1": "123 Main St",
          "line2": null,
          "city": "San Francisco",
          "state": "CA",
          "zip": "94102"
        }
      }'
    ```

    The Entity is created with `status: "incomplete"` because identity verification hasn't happened yet. Products like Connect and Credit Scores remain in `restricted_products` until verification is complete.

    ```json theme={null}
    {
      "id": "ent_au22b1fbFJbp8",
      "type": "individual",
      "individual": {
        "first_name": "Sarah",
        "last_name": "Chen",
        "phone": "+14155550123",
        "dob": "1992-07-15",
        "email": "sarah.chen@email.com",
        "ssn_4": null,
        "ssn": null
      },
      "error": null,
      "address": {
        "line1": "123 Main St",
        "line2": null,
        "city": "San Francisco",
        "state": "CA",
        "zip": "94102"
      },
      "status": "incomplete",
      "verification": {
        "identity": {
          "verified": false,
          "matched": false,
          "latest_verification_session": null,
          "methods": [
            "element",
            "kba"
          ]
        },
        "phone": {
          "verified": false,
          "latest_verification_session": null,
          "methods": [
            "sms",
            "sna"
          ]
        }
      },
      "connect": null,
      "credit_score": null,
      "products": [
        "identity"
      ],
      "restricted_products": [
        "connect",
        "credit_score",
        "attribute"
      ],
      "subscriptions": [],
      "available_subscriptions": [
        "connect",
        "credit_score"
      ],
      "restricted_subscriptions": [],
      "metadata": null,
      "created_at": "2025-09-15T14:30:00.000Z",
      "updated_at": "2025-09-15T14:30:00.000Z"
    }
    ```
  </Step>

  <Step title="Verify the User">
    Before Method can discover Sarah's accounts, she must complete [identity verification](/guides/identity-verification/overview). This is a two-part process: first confirming she controls her phone number, then verifying her identity.

    ### Phone Verification (SMS)

    Start by verifying Sarah's phone number. This sends an SMS code to `+14155550123`.

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/verification_sessions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "sms",
        "sms": {}
      }'
    ```

    ```json theme={null}
    {
      "id": "evf_3VT3bHTCnPbrm",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "in_progress",
      "type": "phone",
      "method": "sms",
      "sms": {},
      "error": null,
      "created_at": "2025-09-15T14:31:00.000Z",
      "updated_at": "2025-09-15T14:31:00.000Z"
    }
    ```

    After the user provides the SMS code and completes identity verification (via [KBA](/reference/entities/verification-sessions/create-kba) or [Opal](/guides/opal)), the Entity transitions to `status: "active"` and products are unlocked.

    <Note>
      **Recommended: Use [Opal](/guides/opal)** for identity verification. Opal is Method's pre-built, white-labeled UI that handles both phone verification and identity verification in a single drop-in component. Most teams start here.
    </Note>

    ### After Verification

    Once verified, the Entity's `products` array expands and `restricted_products` clears:

    ```json theme={null}
    {
      "id": "ent_au22b1fbFJbp8",
      "status": "active",
      "verification": {
        "identity": {
          "verified": true,
          "matched": true,
          "latest_verification_session": "evf_9kR2fGhLmNpQ4",
          "methods": []
        },
        "phone": {
          "verified": true,
          "latest_verification_session": "evf_3VT3bHTCnPbrm",
          "methods": []
        }
      },
      "products": [
        "identity",
        "connect",
        "credit_score",
        "attribute"
      ],
      "restricted_products": [],
      "available_subscriptions": [
        "connect",
        "credit_score"
      ],
      "restricted_subscriptions": []
    }
    ```
  </Step>

  <Step title="Connect Liabilities">
    With Sarah verified, you can now discover her complete liability picture using [Connect](/guides/connect/overview). This performs a soft-pull credit report (no impact to her credit score) and returns all discovered accounts.

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```

    Connect discovers all of Sarah's open liabilities and returns them as account IDs:

    ```json theme={null}
    {
      "id": "cxn_iYGhvTRDnE4y7",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "completed",
      "accounts": [
        "acc_eKKmrXDpJBKgw",
        "acc_GV8WbmJW7KGRy",
        "acc_MLPKh9gQDDbT8",
        "acc_LbXE8wVYJLrKt",
        "acc_J3P9fayDFjpAy",
        "acc_eFFRV9zmpLREK"
      ],
      "requested_products": [],
      "requested_subscriptions": [],
      "error": null,
      "created_at": "2025-09-15T14:35:00.000Z",
      "updated_at": "2025-09-15T14:35:00.000Z"
    }
    ```

    ### What Was Discovered

    Each account ID maps to a liability that Method found on Sarah's credit report. You can retrieve any account to see its details:

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    ```json theme={null}
    {
      "id": "acc_eKKmrXDpJBKgw",
      "holder_id": "ent_au22b1fbFJbp8",
      "type": "liability",
      "liability": {
        "mch_id": "mch_302086",
        "type": "credit_card",
        "name": "Chase Sapphire Reserve"
      },
      "status": "active",
      "products": [
        "update",
        "payment",
        "card_brand",
        "transaction"
      ],
      "created_at": "2025-09-15T14:35:00.000Z",
      "updated_at": "2025-09-15T14:35:00.000Z"
    }
    ```

    Here's what Sarah's full liability picture looks like:

    | Account ID          | Creditor               | Type          |
    | ------------------- | ---------------------- | ------------- |
    | `acc_eKKmrXDpJBKgw` | Chase Sapphire Reserve | Credit Card   |
    | `acc_GV8WbmJW7KGRy` | Citi Double Cash       | Credit Card   |
    | `acc_MLPKh9gQDDbT8` | Capital One            | Auto Loan     |
    | `acc_LbXE8wVYJLrKt` | Navient                | Student Loan  |
    | `acc_J3P9fayDFjpAy` | SoFi                   | Personal Loan |
    | `acc_eFFRV9zmpLREK` | Wells Fargo            | Mortgage      |
  </Step>
</Steps>

## What's Next

With Sarah's entity created, verified, and her liabilities discovered, you're ready to build the core PFM experience. Each of the following guides picks up where this setup leaves off.

<CardGroup>
  <Card title="Onboarding & Discovery" icon="magnifying-glass" href="/guides/use-cases/pfm/onboarding-discovery">
    Deep dive into identity verification options, connect subscriptions for ongoing discovery, and vehicle enrichment for auto loans.
  </Card>

  <Card title="Dashboard & Insights" icon="chart-mixed" href="/guides/use-cases/pfm/monitoring-insights">
    Pull real-time balances, credit scores, card brand art, and entity-level financial health attributes.
  </Card>

  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Stream credit card transactions and initiate bill payments to your users' creditors.
  </Card>
</CardGroup>


# Debt Dashboard & Credit Insights
Source: https://docs.methodfi.com/guides/use-cases/pfm/monitoring-insights

Build real-time debt dashboards with account updates, card brand art, credit scores, and financial health attributes.

Once a user's liabilities are connected, the next step is turning that raw data into a useful dashboard. This guide covers pulling real-time account data, enriching cards with brand art, monitoring balances over time, and surfacing credit health insights.

All examples use Sarah Chen's accounts from the [Getting Started](/guides/use-cases/pfm/getting-started) guide.

## Debt Dashboard & Real-Time Monitoring

### Requesting an Account Update

[Updates](/guides/updates/overview) pull real-time data — balance, credit limit, APR, due dates, payment history — directly from the financial institution. This is the core data feed for any debt dashboard.

Request an update for Sarah's Chase Sapphire Reserve card:

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/updates \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "upt_NYV5kfjskTTCJ",
      "status": "completed",
      "account_id": "acc_eKKmrXDpJBKgw",
      "source": "direct",
      "type": "credit_card",
      "credit_card": {
        "available_credit": 1920000,
        "balance": 80000,
        "closed_at": null,
        "credit_limit": 2000000,
        "interest_rate_percentage_max": 22.49,
        "interest_rate_percentage_min": 22.49,
        "interest_rate_type": "variable",
        "last_payment_amount": 15000,
        "last_payment_date": "2025-08-28",
        "next_payment_due_date": "2025-10-01",
        "next_payment_minimum_amount": 2500,
        "opened_at": "2022-03-15",
        "sub_type": "flexible_spending",
        "usage_pattern": "transactor"
      },
      "data_as_of": "2025-09-15T14:45:00.000Z",
      "error": null,
      "created_at": "2025-09-15T14:45:00.000Z",
      "updated_at": "2025-09-15T14:45:00.312Z"
    }
    ```
  </Tab>
</Tabs>

Sarah's Chase card has an \$800.00 balance on a \$20,000.00 limit (4% utilization), with a minimum payment of \$25.00 due on October 1st. Her last payment of \$150.00 was made on August 28th, and her `usage_pattern` is `transactor` — she pays in full each month.

### Subscribing to Continuous Updates

Rather than polling for updates, subscribe to receive them automatically. When the financial institution reports new data, Method delivers it via webhook.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/subscriptions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "enroll": "update"
      }'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "sub_xM4VcfRWcJP8D",
      "name": "update",
      "status": "active",
      "payload": null,
      "latest_request_id": "upt_NYV5kfjskTTCJ",
      "created_at": "2025-09-15T15:10:00.000Z",
      "updated_at": "2025-09-15T15:10:00.000Z"
    }
    ```
  </Tab>
</Tabs>

With the subscription active, Method will fire `update.create` and `update.update` webhook events whenever new data is available. Your app can refresh the dashboard in real time without the user taking any action.

### Card Brand Art

For credit card accounts, [Card Brand](/guides/additional-products/card-brand) retrieves the card's product name, issuer, network, and card art image. This lets your wallet UI display the actual card visual instead of a generic placeholder.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/card_brands \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "cbrd_Accm7P6t6mYQP",
      "account_id": "acc_eKKmrXDpJBKgw",
      "brands": [
        {
          "id": "pdt_15_brd_1",
          "card_product_id": "pdt_15",
          "description": "Chase Sapphire Reserve",
          "name": "Chase Sapphire Reserve",
          "issuer": "Chase",
          "network": "visa",
          "network_tier": "infinite",
          "type": "specific",
          "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
        }
      ],
      "status": "completed",
      "source": "method",
      "error": null,
      "created_at": "2025-09-15T15:15:00.000Z",
      "updated_at": "2025-09-15T15:15:00.000Z"
    }
    ```
  </Tab>
</Tabs>

The `url` field provides a direct link to the card's art image, which you can render in your wallet or dashboard UI.

### Entity-Level Attributes

[Attributes](/guides/additional-products/attributes) provide entity-level financial health metrics aggregated across all of a user's accounts. These power features like credit health dashboards, utilization alerts, and financial wellness scores.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/attributes \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    <Note>
      Attribute requests are asynchronous and compute all available attributes automatically. The initial response will have `status: "in_progress"` and `attributes: null`. You'll receive a webhook when the attributes are ready.
    </Note>
  </Tab>

  <Tab title="Response (completed)">
    ```json theme={null}
    {
      "id": "attr_nrPjaahMX4yRA",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "completed",
      "attributes": {
        "revolving_credit_card_balance_total": {
          "value": 550000,
          "error": null,
          "metadata": null
        },
        "credit_limit_total": {
          "value": 2500000,
          "error": null,
          "metadata": null
        },
        "credit_card_utilization": {
          "value": 22.0,
          "error": null,
          "metadata": null
        },
        "weighted_average_apr_credit_card": {
          "value": 21.24,
          "error": null,
          "metadata": null
        },
        "usage_pattern": {
          "value": "transactor",
          "error": null,
          "metadata": null
        },
        "overall_utilization": {
          "value": 22.0,
          "error": null,
          "metadata": null
        }
      },
      "error": null,
      "created_at": "2025-09-15T15:20:00.000Z",
      "updated_at": "2025-09-15T15:20:30.000Z"
    }
    ```
  </Tab>
</Tabs>

Sarah's attributes show 22% aggregate credit card utilization ($5,500.00 in revolving balances against $25,000.00 in combined limits), a weighted average card APR of 21.24%, and a `transactor` usage pattern (she pays in full each month). These data points map directly to the factors that credit scoring models weigh most heavily. Each attribute is returned as an object with `value`, `error`, and `metadata` fields; if an attribute cannot be computed, `value` is `null` and `error` explains why.

***

## Credit Building & Score Insights

### Retrieving Credit Scores

[Credit Scores](/guides/additional-products/credit-scores) retrieve the user's credit score sourced from Equifax using the VantageScore 4.0 model. The response includes contributing factors that explain what's helping or hurting the score.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/credit_scores \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    <Note>
      Credit score requests are asynchronous. The initial response will have `status: "pending"` and `scores: null`. You'll receive a webhook when the score is ready.
    </Note>
  </Tab>

  <Tab title="Response (completed)">
    ```json theme={null}
    {
      "id": "crs_pn4ca33GXFaCE",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "completed",
      "scores": [
        {
          "score": 734,
          "source": "equifax",
          "model": "vantage_4",
          "factors": [
            "Length of time accounts have been established",
            "Too few accounts currently paid as agreed",
            "Lack of recent installment loan information",
            "Proportion of balances to credit limits is too high on bank revolving or other revolving accounts"
          ],
          "created_at": "2025-09-15T15:25:00.000Z"
        }
      ],
      "error": null,
      "created_at": "2025-09-15T15:25:00.000Z",
      "updated_at": "2025-09-15T15:25:30.000Z"
    }
    ```
  </Tab>
</Tabs>

Sarah's VantageScore 4.0 is 734 ("Good" tier). The factors array explains what's influencing her score — you can surface these directly in your app to help users understand what actions would improve their score.

### Credit Score Subscriptions

To monitor Sarah's credit score over time, enroll her in a credit score subscription. Method will automatically check for score changes and send webhook events when her score increases or decreases.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/subscriptions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "enroll": "credit_score"
      }'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "sub_c3a7hVjHCJzF3",
      "name": "credit_score",
      "status": "active",
      "payload": null,
      "latest_request_id": null,
      "created_at": "2025-09-15T15:30:00.000Z",
      "updated_at": "2025-09-15T15:30:00.000Z"
    }
    ```
  </Tab>
</Tabs>

With the subscription active, your app can power features like monthly score reports, trend charts, and push notifications ("Your credit score went up 12 points this month!") that drive engagement and retention.

### Combining Scores and Attributes

The most effective credit building experiences combine credit scores with attributes. The score tells users *where they stand*, while attributes tell them *why* and *what to do about it*:

| Attribute                             | Sarah's Value | What to Surface                                                             |
| ------------------------------------- | ------------- | --------------------------------------------------------------------------- |
| `credit_card_utilization`             | 22%           | "Your utilization is healthy. Keep it under 30%"                            |
| `usage_pattern`                       | `transactor`  | "You pay your cards in full each month. Keep it up!"                        |
| `weighted_average_apr_credit_card`    | 21.24%        | "Your average card APR is 21.24%. A balance transfer could reduce interest" |
| `revolving_credit_card_balance_total` | \$5,500.00    | "Your total card balances across all accounts"                              |

<Card title="Attributes API Reference" icon="chart-bar" href="/reference/entities/attributes/create">
  Full documentation for all available attribute types and their value, error, and metadata fields.
</Card>

## What's Next

<CardGroup>
  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Stream credit card transactions for spend management and initiate bill payments.
  </Card>

  <Card title="Update Subscriptions Guide" icon="rotate" href="/guides/updates/subscriptions">
    Deep dive into update subscription types, frequencies, and webhook payloads.
  </Card>
</CardGroup>


# Onboarding & Liability Discovery
Source: https://docs.methodfi.com/guides/use-cases/pfm/onboarding-discovery

Identity verification options, liability discovery via Connect, ongoing connect subscriptions, and vehicle enrichment for auto loans.

This guide covers the onboarding layer of a PFM integration: how users get verified, how their liabilities are discovered, how to detect new liabilities over time, and how to enrich auto loan accounts with vehicle details.

If you haven't completed the [Getting Started](/guides/use-cases/pfm/getting-started) steps (creating and verifying Sarah Chen's Entity, and running Connect), start there first.

## Identity Verification with Opal

[Opal](/guides/opal) is Method's pre-built, white-labeled UI component that handles the entire verification flow — phone verification and identity verification — in a single drop-in experience. It's the fastest path to getting users verified and is recommended for most integrations.

<Tabs>
  <Tab title="Opal (Recommended)">
    Opal handles phone verification (SMS or SNA) and identity verification (KBA) in a single embedded flow. Your user completes the process in your app, and you receive a webhook when verification is complete.

    **Advantages:**

    * Minimal frontend development
    * Tested, optimized UX for conversion
    * Handles edge cases (retries, fallbacks, error states)
    * White-labeled to match your brand

    <Card title="Opal Integration Guide" icon="window" href="/guides/opal">
      Full guide for embedding Opal in your application.
    </Card>
  </Tab>

  <Tab title="BYO Identity Verification">
    If you have an existing identity verification flow or need complete control over the UX, you can use Method's API directly. This involves separate calls for [phone verification](/reference/entities/verification-sessions/create-sms) and [identity verification](/reference/entities/verification-sessions/create-kba).

    **When to use BYO:**

    * You already have a KYC/IDV provider and want to pass results to Method
    * Your UX requires a custom verification flow
    * You need to integrate verification into an existing onboarding funnel

    <Card title="Identity Verification Methods" icon="shield-check" href="/guides/identity-verification/methods">
      All available verification methods and when to use each.
    </Card>
  </Tab>
</Tabs>

## Liability Discovery via Connect

Once Sarah is verified, [Connect](/guides/connect/overview) performs a soft-pull credit report to discover her liabilities. The [Getting Started](/guides/use-cases/pfm/getting-started) guide showed the Connect call that discovered all 6 of her accounts.

Here's what Connect found for Sarah:

| Account ID          | Creditor               | Type          | What Your App Shows            |
| ------------------- | ---------------------- | ------------- | ------------------------------ |
| `acc_eKKmrXDpJBKgw` | Chase Sapphire Reserve | Credit Card   | Card balance, APR, due date    |
| `acc_GV8WbmJW7KGRy` | Citi Double Cash       | Credit Card   | Card balance, APR, due date    |
| `acc_MLPKh9gQDDbT8` | Capital One            | Auto Loan     | Loan balance, payment schedule |
| `acc_LbXE8wVYJLrKt` | Navient                | Student Loan  | Loan balance, disbursements    |
| `acc_J3P9fayDFjpAy` | SoFi                   | Personal Loan | Balance, term, rate            |
| `acc_eFFRV9zmpLREK` | Wells Fargo            | Mortgage      | Balance, rate, payoff date     |

<Note>
  Connect discovers both open and closed liabilities on the first call. Subsequent Connect calls for the same Entity only return newly opened accounts.
</Note>

## Connect Subscriptions

A user's liability picture changes over time — they open new credit cards, take out loans, or consolidate debt. Connect subscriptions automatically re-run discovery on a recurring basis and notify you via webhook when new accounts are found.

Enroll the Entity in a connect subscription:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "enroll": "connect"
  }'
```

```json theme={null}
{
  "id": "sub_Wm3FJkqV8hpDR",
  "name": "connect",
  "status": "active",
  "payload": null,
  "latest_request_id": null,
  "created_at": "2025-09-15T15:00:00.000Z",
  "updated_at": "2025-09-15T15:00:00.000Z"
}
```

When Method detects a new liability for Sarah, you'll receive a webhook event with the new Connect result containing the newly discovered account IDs. Your app can then automatically add these to her dashboard without any user action.

## Vehicle Enrichment

For auto loan accounts like Sarah's Capital One loan (`acc_MLPKh9gQDDbT8`), Method can retrieve the associated vehicle details — VIN, year, make, model, and style. This transforms a generic "Auto Loan: \$18,450 balance" into "2021 Honda CR-V EX: \$18,450 remaining."

Request vehicle data for Sarah's Entity:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/vehicles \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

```json theme={null}
{
  "id": "evhl_QnT4mKxBfVpJ8",
  "entity_id": "ent_au22b1fbFJbp8",
  "vehicles": [
    {
      "vin": "7FARW2H83ME012345",
      "year": "2021",
      "make": "honda",
      "model": "cr-v",
      "series": null,
      "major_color": "blue",
      "style": "sport_utility_vehicle"
    }
  ],
  "status": "completed",
  "error": null,
  "created_at": "2025-09-15T15:05:00.000Z",
  "updated_at": "2025-09-15T15:05:00.000Z"
}
```

With vehicle data, your PFM app can display rich auto loan details, enable equity calculations (comparing vehicle value against remaining balance), and power features like insurance comparison or refinancing recommendations.

<Card title="Vehicles API Reference" icon="car" href="/reference/entities/vehicles/create">
  Full API documentation for the Vehicles endpoint.
</Card>

## What's Next

<CardGroup>
  <Card title="Dashboard & Insights" icon="chart-mixed" href="/guides/use-cases/pfm/monitoring-insights">
    Pull real-time balances, credit scores, card brand art, and financial health attributes.
  </Card>

  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Stream credit card transactions and initiate bill payments.
  </Card>
</CardGroup>


# Digital Engagement & PFM
Source: https://docs.methodfi.com/guides/use-cases/pfm/overview

Build comprehensive personal financial management experiences with Method's liability data, credit insights, and payment infrastructure.

## What This Section Covers

Products and APIs that enable comprehensive personal financial management experiences — from discovering a user's complete debt picture to monitoring changes in real time, surfacing credit insights, and enabling bill pay directly from your app.

If you're building any product that helps consumers understand, manage, or pay down their financial obligations, this is where to start.

### Example Use Cases

* **Digital wallets** that display card balances, brand art, and recent transactions
* **Spend management apps** that categorize liability transactions and track spending patterns
* **Financial wellness platforms** that surface credit scores, debt-to-income insights, and payoff strategies
* **Neobanks** that embed bill pay and debt repayment into the core banking experience

## How Method Enables End-to-End PFM

Every PFM integration follows the same high-level journey: discover the user's liabilities, enrich them with real-time data, surface insights, and enable action.

| Stage        | What Happens                                                               | Method Products                                                                                                                           |
| ------------ | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Connect**  | Discover the user's complete liability picture via soft-pull credit report | [Entity](/guides/entities/overview), [Identity Verification](/guides/identity-verification/overview), [Connect](/guides/connect/overview) |
| **Data**     | Pull real-time balances, APRs, due dates, card art, and transactions       | [Updates](/guides/updates/overview), [Card Brand](/guides/additional-products/card-brand)                                                 |
| **Insights** | Surface credit scores, payment history, utilization, and attributes        | [Credit Scores](/guides/additional-products/credit-scores), [Attributes](/guides/additional-products/attributes)                          |
| **Pay**      | Initiate payments from your platform's funding account to users' creditors | [Payments](/guides/payments/overview)                                                                                                     |

## Get Started

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="/guides/use-cases/pfm/getting-started">
    The universal 3-step setup: create an entity, verify identity, and connect liabilities.
  </Card>

  <Card title="Onboarding & Discovery" icon="magnifying-glass" href="/guides/use-cases/pfm/onboarding-discovery">
    Identity verification, liability discovery, connect subscriptions, and vehicle enrichment.
  </Card>

  <Card title="Dashboard & Insights" icon="chart-mixed" href="/guides/use-cases/pfm/monitoring-insights">
    Real-time balances, credit scores, card brands, and entity-level attributes.
  </Card>

  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Transaction streaming, spend management, bill pay, and debt repayment.
  </Card>
</CardGroup>


# Transactions & Bill Pay
Source: https://docs.methodfi.com/guides/use-cases/pfm/transactions-payments

Stream credit card transactions for spend management and initiate bill payments to your users' creditors.

This guide covers the action layer of a PFM integration: streaming transaction data for spend management, and initiating payments from your platform's corporate funding account to pay down user liabilities.

All examples use Sarah Chen's accounts from the [Getting Started](/guides/use-cases/pfm/getting-started) guide.

## Transaction Stream & Spend Management

### Listing Transactions

Transactions provide transaction-level detail for connected Visa and Mastercard credit card accounts. Once subscribed, you can query historical transactions and receive new ones in real time via webhooks.

Retrieve recent transactions for Sarah's Chase Sapphire Reserve card:

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl "https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/transactions?from_date=2025-09-01&to_date=2025-09-15" \
      -X GET \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "data": [
        {
          "id": "txn_t73AdHRFYwhT9",
          "account_id": "acc_eKKmrXDpJBKgw",
          "status": "posted",
          "descriptor": "SQ *BLUE BOTTLE COFF",
          "merchant": {
            "name": "Blue Bottle Coffee",
            "logo": null
          },
          "merchant_category_code": "5814",
          "amount": 675,
          "auth_amount": 675,
          "currency_code": "USD",
          "transaction_amount": 675,
          "transaction_auth_amount": 675,
          "transaction_currency_code": "USD",
          "transacted_at": "2025-09-14T08:22:00.000Z",
          "posted_at": "2025-09-15T05:00:00.000Z",
          "voided_at": null,
          "original_txn_id": null,
          "created_at": "2025-09-14T08:22:00.000Z",
          "updated_at": "2025-09-15T05:00:00.000Z"
        },
        {
          "id": "txn_kP4mRvTnBcWx2",
          "account_id": "acc_eKKmrXDpJBKgw",
          "status": "posted",
          "descriptor": "WHOLE FOODS MKT #1042",
          "merchant": {
            "name": "Whole Foods Market",
            "logo": null
          },
          "merchant_category_code": "5411",
          "amount": 8743,
          "auth_amount": 8743,
          "currency_code": "USD",
          "transaction_amount": 8743,
          "transaction_auth_amount": 8743,
          "transaction_currency_code": "USD",
          "transacted_at": "2025-09-12T18:45:00.000Z",
          "posted_at": "2025-09-13T05:00:00.000Z",
          "voided_at": null,
          "original_txn_id": null,
          "created_at": "2025-09-12T18:45:00.000Z",
          "updated_at": "2025-09-13T05:00:00.000Z"
        },
        {
          "id": "txn_qN7jWvHmDfRa5",
          "account_id": "acc_eKKmrXDpJBKgw",
          "status": "posted",
          "descriptor": "SHELL OIL 57442",
          "merchant": {
            "name": "Shell",
            "logo": null
          },
          "merchant_category_code": "5541",
          "amount": 5218,
          "auth_amount": 5218,
          "currency_code": "USD",
          "transaction_amount": 5218,
          "transaction_auth_amount": 5218,
          "transaction_currency_code": "USD",
          "transacted_at": "2025-09-10T14:30:00.000Z",
          "posted_at": "2025-09-11T05:00:00.000Z",
          "voided_at": null,
          "original_txn_id": null,
          "created_at": "2025-09-10T14:30:00.000Z",
          "updated_at": "2025-09-11T05:00:00.000Z"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

Sarah's recent transactions show \$6.75 at Blue Bottle Coffee, \$87.43 at Whole Foods, and \$52.18 at Shell. All amounts are in cents. The `merchant_category_code` enables spend categorization (5814 = restaurants, 5411 = grocery, 5541 = gas stations).

### Subscribing to Transactions

Transaction data requires an active subscription. Enroll Sarah's Chase card to receive transaction events in real time:

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/subscriptions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "enroll": "transaction"
      }'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "sub_P8c4bjj6xajxF",
      "name": "transaction",
      "status": "active",
      "payload": null,
      "latest_request_id": null,
      "created_at": "2025-09-15T15:40:00.000Z",
      "updated_at": "2025-09-15T15:40:00.000Z"
    }
    ```
  </Tab>
</Tabs>

With the subscription active, Method fires webhook events for both authorization events (when Sarah swipes her card) and settlement events (when the transaction clears). This enables real-time spend alerts, budget tracking, and transaction feeds.

<Warning>
  Transaction streaming is available for Visa and Mastercard credit cards. Not all card accounts will support transactions — check the account's `products` array to confirm `transaction` is available.
</Warning>

***

## Bill Pay & Debt Repayment

### Getting a Fresh Balance Before Payment

Before initiating a payment, pull the latest balance to ensure accuracy. If you've already subscribed to updates (covered in the [Dashboard & Insights](/guides/use-cases/pfm/monitoring-insights) guide), you'll have recent data. Otherwise, request an on-demand update:

```bash theme={null}
curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/updates \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

The completed update confirms Sarah's Chase card balance is \$800.00 (`80000` cents) with a minimum payment of \$25.00 due on October 1st. She decides to pay \$500.00 toward the balance.

### Creating a Payment

[Payments](/guides/payments/overview) move money from your platform's verified funding account (ACH) to a liability account. Your corporate funding account `acc_hmap9mbgfLcf9` serves as the payment source for all user payments.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/payments \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 50000,
        "source": "acc_hmap9mbgfLcf9",
        "destination": "acc_eKKmrXDpJBKgw",
        "description": "Chase Pmt"
      }'
    ```
  </Tab>

  <Tab title="Response (pending)">
    ```json theme={null}
    {
      "id": "pmt_VeCfmkwGKb",
      "source": "acc_hmap9mbgfLcf9",
      "destination": "acc_eKKmrXDpJBKgw",
      "amount": 50000,
      "description": "Chase Pmt",
      "status": "pending",
      "estimated_completion_date": "2025-09-18",
      "source_trace_id": null,
      "source_settlement_date": "2025-09-16",
      "source_status": "pending",
      "destination_trace_id": null,
      "destination_settlement_date": "2025-09-18",
      "destination_payment_method": "paper",
      "destination_status": "pending",
      "reversal_id": null,
      "error": null,
      "metadata": null,
      "created_at": "2025-09-15T16:00:00.000Z",
      "updated_at": "2025-09-15T16:00:00.000Z"
    }
    ```
  </Tab>
</Tabs>

The payment is created with `status: "pending"` and an estimated completion date of September 18th. The `description` field (max 10 characters) appears on the user's bank statement.

<Note>
  All amounts are in **cents**. `50000` = \$500.00. The `description` field has a maximum length of 10 characters.
</Note>

### Payment Lifecycle

Payments move through a lifecycle from creation to settlement. Track progress via webhook events:

Once the payment settles, the status transitions to `posted`:

```json theme={null}
{
  "id": "pmt_VeCfmkwGKb",
  "source": "acc_hmap9mbgfLcf9",
  "destination": "acc_eKKmrXDpJBKgw",
  "amount": 50000,
  "description": "Chase Pmt",
  "status": "posted",
  "estimated_completion_date": "2025-09-18",
  "source_trace_id": "203942084920",
  "source_settlement_date": "2025-09-16",
  "source_status": "posted",
  "destination_trace_id": "304820184832",
  "destination_settlement_date": "2025-09-18",
  "destination_payment_method": "paper",
  "destination_status": "posted",
  "reversal_id": null,
  "error": null,
  "metadata": null,
  "created_at": "2025-09-15T16:00:00.000Z",
  "updated_at": "2025-09-18T12:00:00.000Z"
}
```

## Putting It All Together

With transactions and payments, Sarah's PFM experience is complete:

| Capability         | Product                                                    | Example                                           |
| ------------------ | ---------------------------------------------------------- | ------------------------------------------------- |
| View all debts     | [Connect](/guides/connect/overview)                        | 6 liabilities discovered automatically            |
| Real-time balances | [Updates](/guides/updates/overview)                        | Chase card: \$800.00 balance, \$25.00 minimum due |
| Card visuals       | [Card Brand](/guides/additional-products/card-brand)       | Chase Sapphire Reserve card art                   |
| Credit score       | [Credit Scores](/guides/additional-products/credit-scores) | VantageScore 4.0: 734                             |
| Financial health   | [Attributes](/guides/additional-products/attributes)       | 22% utilization, 100% payment history             |
| Spending activity  | Transactions                                               | Coffee, groceries, gas — categorized in real time |
| Bill pay           | [Payments](/guides/payments/overview)                      | \$500 payment to Chase, settled in 3 days         |

<CardGroup>
  <Card title="Payments Lifecycle" icon="arrows-spin" href="/guides/payments/lifecycle">
    Deep dive into payment states, timing, and error handling.
  </Card>

  <Card title="Payment Errors" icon="triangle-exclamation" href="/guides/payments/errors">
    Understanding and handling payment failures and reversals.
  </Card>
</CardGroup>


# Create Attributes
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/attributes/create

POST /accounts/{acc_id}/attributes

Creates a new Attribute request to compute the Account's attributes.
The attributes returned depend on the account's liability type.

Operation Type: <Tooltip>🔄 Asynchronous</Tooltip>

## Path Parameters

<ParamList />

## Body

Both fields are optional. A request with no body computes the full set of attributes
for the account type. Provide `requested_attributes`, `bundles`, or both to scope the
response's `attributes` object to just the requested attributes.

<ParamList />

## Returns

Returns an Account's Attributes object with `status: "in_progress"` and `attributes: null`.
Once processing completes, the status will update to `completed` and the `attributes` object
will be populated. Subscribe to [webhooks](/2026-03-30/reference/webhooks/overview) or poll the
[retrieve endpoint](/2026-03-30/reference/accounts/attributes/retrieve) to get the final result.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_4m9amk4KFiaQX/attributes \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "bundles": ["statement"]
    }'
  ```

  ```javascript Node.js theme={null}
  const attribute = await method
    .accounts('acc_4m9amk4KFiaQX')
    .attributes
    .create();
  ```

  ```python Python theme={null}
  attribute = method
    .accounts('acc_4m9amk4KFiaQX')
    .attributes
    .create()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "acc_attr_cWBKqwVP87kim",
      "account_id": "acc_4m9amk4KFiaQX",
      "status": "in_progress",
      "attributes": null,
      "error": null,
      "created_at": "2026-04-09T17:02:47.910Z",
      "updated_at": "2026-04-09T17:02:47.910Z"
    },
    "message": null
  }
  ```
</ResponseExample>


# List all Attributes
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/attributes/list

GET /accounts/{acc_id}/attributes

Retrieves a list of Attributes for an Account.

## Path Parameters

<ParamList />

## Query Parameters

<ParamList />

## Returns

Returns a list of Attributes.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/accounts/acc_4m9amk4KFiaQX/attributes" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_4m9amk4KFiaQX')
    .attributes
    .list();
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_4m9amk4KFiaQX')
    .attributes
    .list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "acc_attr_cWBKqwVP87kim",
        "account_id": "acc_4m9amk4KFiaQX",
        "status": "completed",
        "attributes": {
          "type": {
            "value": "credit_card",
            "error": null,
            "metadata": null
          },
          "usage_pattern": {
            "value": "revolver",
            "error": null,
            "metadata": null
          },
          "utilization": {
            "value": 11.96,
            "error": null,
            "metadata": null
          }
        },
        "error": null,
        "created_at": "2026-04-09T17:02:47.910Z",
        "updated_at": "2026-04-09T17:04:35.220Z"
      },
      {...}
    ],
    "message": null
  }
  ```
</ResponseExample>


# The account attributes endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/attributes/overview



The Account Attributes endpoint provides financial attributes for an individual Account.
The attributes returned depend on the account's liability type (credit card, personal loan, mortgage, auto loan, or student loan).

**The Account Attributes endpoint is available as a:**

| Type           | Use-Case                                                                                                                    |
| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `Product`      | On-Demand view of an Account's financial attributes.                                                                        |
| `Subscription` | Continuous monitoring of an Account's financial attributes with near real-time updates. [Webhook Payload](#webhook-payload) |

<Note>
  To enroll an Account, create an `attribute` subscription via
  [Create a Subscription](/2026-03-30/reference/accounts/subscriptions/create).
  The subscription is available for credit card, personal loan, mortgage, auto loan, and student loan accounts.
</Note>

## Attribute Objects

<ParamList />

## Attribute Bundles

A **bundle** is a named group of attributes you can request together instead of
listing each attribute individually. Request one or more bundles with the `bundles`
field on [Create Attributes](/2026-03-30/reference/accounts/attributes/create) or when enrolling
an `attribute` [Subscription](/2026-03-30/reference/accounts/subscriptions/create). When you
request a bundle, the response's `attributes` object is scoped to that bundle's members.

### The `statement` bundle

The `statement` bundle returns the upcoming-statement attributes for an Account — the
borrower's next payment due date and the minimum amount due. It is available for all
supported account types (credit card, personal loan, mortgage, auto loan, and student loan).

| Attribute                     | Value Type | Description                                                                                                                                                              |
| ----------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `next_payment_due_date`       | string     | The Account's next payment due date, as `YYYY-MM-DD`. If the reported due date has already passed, it is rolled forward to the next occurrence of that day of the month. |
| `next_payment_minimum_amount` | number     | The minimum amount due for the upcoming statement, in cents. Returns `0` when the reported balance is zero or less.                                                      |

<Note>
  Values sourced from credit report data — or carried forward from a prior statement —
  are estimates and are flagged with `metadata.estimated` set to `true`.
</Note>

## Available Attributes by Account Type

The attributes returned depend on the account's liability type.
Requesting attributes for an unsupported account type will return a `400` error.

### Credit Card Accounts

| Attribute                         | Value Type | Description                                                                                                                                                                                                      |
| --------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                            | string     | The liability type of the account.                                                                                                                                                                               |
| `usage_pattern`                   | string     | The usage pattern of the account (e.g., revolver, transactor, dormant).                                                                                                                                          |
| `delinquency_flag`                | string     | Credit card delinquency status. Possible values are `on_time` and `overdue`.                                                                                                                                     |
| `utilization`                     | number     | The utilization percentage of the account.                                                                                                                                                                       |
| `utilization_trend_30d`           | string     | Direction of utilization change over the last 30 days.                                                                                                                                                           |
| `utilization_trend_90d`           | string     | Direction of utilization change over the last 90 days.                                                                                                                                                           |
| `utilization_delta_30d`           | number     | Percentage point change in utilization over the last 30 days.                                                                                                                                                    |
| `utilization_delta_60d`           | number     | Percentage point change in utilization over the last 60 days.                                                                                                                                                    |
| `utilization_delta_90d`           | number     | Percentage point change in utilization over the last 90 days.                                                                                                                                                    |
| `available_credit_limit`          | number     | Available credit for the credit card account, in cents. Uses source-backed available credit when present and falls back to credit limit minus balance.                                                           |
| `any_delinquent_flag`             | boolean    | Whether the account has a usable delinquency signal. Returns `false` only when Method has usable non-delinquent data.                                                                                            |
| `serious_delinquent_flag`         | boolean    | Whether the account has a serious delinquency signal, such as major delinquency, charge-off, or collection.                                                                                                      |
| `delinquency_recently_cured_flag` | boolean    | Whether bureau data indicates delinquency while a recent sync update indicates the account is on time.                                                                                                           |
| `delinquency_worst_dpd_bucket`    | string     | Worst delinquent period bucket for the account. Possible values are `30_dpd`, `60_dpd`, `90_dpd`, and `120_plus_dpd`.                                                                                            |
| `delinquency_progression_flag`    | boolean    | Whether the account's delinquent period worsened compared with a previous non-null period at least 7 days older, within a 90-day lookback.                                                                       |
| `delinquent_outcome`              | string     | Account delinquent outcome. Possible values include `current`, `collections`, `charge_off`, `payment_agreement`, `chapter_13`, `chapter_7`, `bankruptcy`, `repossession`, `foreclosure`, and `wage_garnishment`. |
| `estimated_apr`                   | number     | Estimated purchase APR for the account, as a percentage.                                                                                                                                                         |

### Personal Loan Accounts

| Attribute                         | Value Type | Description                                                                                                                                                                                                      |
| --------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                            | string     | The liability type of the account.                                                                                                                                                                               |
| `utilization`                     | number     | The utilization percentage of the account.                                                                                                                                                                       |
| `utilization_trend_30d`           | string     | Direction of utilization change over the last 30 days.                                                                                                                                                           |
| `utilization_trend_90d`           | string     | Direction of utilization change over the last 90 days.                                                                                                                                                           |
| `utilization_delta_30d`           | number     | Percentage point change in utilization over the last 30 days.                                                                                                                                                    |
| `utilization_delta_60d`           | number     | Percentage point change in utilization over the last 60 days.                                                                                                                                                    |
| `utilization_delta_90d`           | number     | Percentage point change in utilization over the last 90 days.                                                                                                                                                    |
| `monthly_installments_estimate`   | number     | Estimated monthly installment payment, in cents.                                                                                                                                                                 |
| `heloc_utilization`               | number     | Utilization percentage for HELOC personal loans. Returns insufficient data when the personal loan is not a HELOC.                                                                                                |
| `available_loan_amount`           | number     | Source-backed available loan amount for the personal loan, in cents.                                                                                                                                             |
| `any_delinquent_flag`             | boolean    | Whether the account has a usable delinquency signal. Returns `false` only when Method has usable non-delinquent data.                                                                                            |
| `serious_delinquent_flag`         | boolean    | Whether the account has a serious delinquency signal, such as major delinquency, charge-off, or collection.                                                                                                      |
| `delinquency_recently_cured_flag` | boolean    | Whether bureau data indicates delinquency while a recent sync update indicates the account is on time.                                                                                                           |
| `delinquency_worst_dpd_bucket`    | string     | Worst delinquent period bucket for the account. Possible values are `30_dpd`, `60_dpd`, `90_dpd`, and `120_plus_dpd`.                                                                                            |
| `delinquency_progression_flag`    | boolean    | Whether the account's delinquent period worsened compared with a previous non-null period at least 7 days older, within a 90-day lookback.                                                                       |
| `delinquent_outcome`              | string     | Account delinquent outcome. Possible values include `current`, `collections`, `charge_off`, `payment_agreement`, `chapter_13`, `chapter_7`, `bankruptcy`, `repossession`, `foreclosure`, and `wage_garnishment`. |

### Mortgage Accounts

| Attribute                         | Value Type | Description                                                                                                                                                                                                      |
| --------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                            | string     | The liability type of the account.                                                                                                                                                                               |
| `utilization_trend_30d`           | string     | Direction of utilization change over the last 30 days.                                                                                                                                                           |
| `utilization_trend_90d`           | string     | Direction of utilization change over the last 90 days.                                                                                                                                                           |
| `utilization_delta_30d`           | number     | Percentage point change in utilization over the last 30 days.                                                                                                                                                    |
| `utilization_delta_60d`           | number     | Percentage point change in utilization over the last 60 days.                                                                                                                                                    |
| `utilization_delta_90d`           | number     | Percentage point change in utilization over the last 90 days.                                                                                                                                                    |
| `heloc_utilization`               | number     | Utilization percentage for HELOC mortgages. Returns insufficient data when the mortgage is not a HELOC.                                                                                                          |
| `any_delinquent_flag`             | boolean    | Whether the account has a usable delinquency signal. Returns `false` only when Method has usable non-delinquent data.                                                                                            |
| `serious_delinquent_flag`         | boolean    | Whether the account has a serious delinquency signal, such as major delinquency, charge-off, or collection.                                                                                                      |
| `delinquency_recently_cured_flag` | boolean    | Whether bureau data indicates delinquency while a recent sync update indicates the account is on time.                                                                                                           |
| `delinquency_worst_dpd_bucket`    | string     | Worst delinquent period bucket for the account. Possible values are `30_dpd`, `60_dpd`, `90_dpd`, and `120_plus_dpd`.                                                                                            |
| `delinquency_progression_flag`    | boolean    | Whether the account's delinquent period worsened compared with a previous non-null period at least 7 days older, within a 90-day lookback.                                                                       |
| `delinquent_outcome`              | string     | Account delinquent outcome. Possible values include `current`, `collections`, `charge_off`, `payment_agreement`, `chapter_13`, `chapter_7`, `bankruptcy`, `repossession`, `foreclosure`, and `wage_garnishment`. |

### Auto Loan & Student Loan Accounts

Auto loans and student loans return the same set of attributes.

| Attribute                         | Value Type | Description                                                                                                                                                                                                      |
| --------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`                            | string     | The liability type of the account.                                                                                                                                                                               |
| `utilization`                     | number     | The utilization percentage of the account.                                                                                                                                                                       |
| `utilization_trend_30d`           | string     | Direction of utilization change over the last 30 days.                                                                                                                                                           |
| `utilization_trend_90d`           | string     | Direction of utilization change over the last 90 days.                                                                                                                                                           |
| `utilization_delta_30d`           | number     | Percentage point change in utilization over the last 30 days.                                                                                                                                                    |
| `utilization_delta_60d`           | number     | Percentage point change in utilization over the last 60 days.                                                                                                                                                    |
| `utilization_delta_90d`           | number     | Percentage point change in utilization over the last 90 days.                                                                                                                                                    |
| `monthly_installments_estimate`   | number     | Estimated monthly installment payment, in cents.                                                                                                                                                                 |
| `any_delinquent_flag`             | boolean    | Whether the account has a usable delinquency signal. Returns `false` only when Method has usable non-delinquent data.                                                                                            |
| `serious_delinquent_flag`         | boolean    | Whether the account has a serious delinquency signal, such as major delinquency, charge-off, or collection.                                                                                                      |
| `delinquency_recently_cured_flag` | boolean    | Whether bureau data indicates delinquency while a recent sync update indicates the account is on time.                                                                                                           |
| `delinquency_worst_dpd_bucket`    | string     | Worst delinquent period bucket for the account. Possible values are `30_dpd`, `60_dpd`, `90_dpd`, and `120_plus_dpd`.                                                                                            |
| `delinquency_progression_flag`    | boolean    | Whether the account's delinquent period worsened compared with a previous non-null period at least 7 days older, within a 90-day lookback.                                                                       |
| `delinquent_outcome`              | string     | Account delinquent outcome. Possible values include `current`, `collections`, `charge_off`, `payment_agreement`, `chapter_13`, `chapter_7`, `bankruptcy`, `repossession`, `foreclosure`, and `wage_garnishment`. |

### Direct Pay Attributes

Direct Pay attributes are added to completed Account Attribute responses. They are
not supported in v2 subscription `requested_attributes`.

| Attribute                           | Value Type | Description                                                                         |
| ----------------------------------- | ---------- | ----------------------------------------------------------------------------------- |
| `enrolled_in_direct_pay_previously` | boolean    | Whether Method has completed at least one Direct Pay payment to the same liability. |
| `last_direct_pay_date`              | string     | ISO timestamp for the most recent completed Direct Pay activity.                    |
| `last_direct_pay_amount`            | number     | Amount of the most recent completed Direct Pay payment, in cents.                   |
| `number_of_direct_pay_in_12_months` | number     | Number of completed Direct Pay payments in the trailing 365 days.                   |

## Attribute Value Notes

* Attribute values are returned in cents when the description says "in cents".
* `usage_pattern` returns `revolver`, `transactor`, `dormant`, or `closed`. Unknown or unavailable source values return `insufficient_data`.
* `delinquency_flag` returns `on_time` or `overdue`. Unknown or unavailable source values return `insufficient_data`.
* Boolean delinquency flags return `false` only when Method has usable non-delinquent data. If there is no usable signal, the attribute returns `null` with an insufficient data error.
* `delinquency_worst_dpd_bucket` maps `less_than_30` and `30` to `30_dpd`, `60` to `60_dpd`, `90` to `90_dpd`, and `120` or `over_120` to `120_plus_dpd`.
* `estimated_apr` is a percentage, not cents. It is computed for credit card accounts at supported issuers, and only for accounts that revolve a balance.
* Direct Pay attributes count Method payments with a completed status of `sent`, `posted`, `cashed`, or `settled`. If no completed Direct Pay payment exists, `enrolled_in_direct_pay_previously` is `false`, `number_of_direct_pay_in_12_months` is `0`, and the last payment date and amount return insufficient data.

## Webhook Payload

The [Webhook](/2026-03-30/reference/webhooks/overview) payload will contain the following information:

```json theme={null}
{
  "id": "string",
  "type": "account_attribute.create",
  "path": "/accounts/<acc_id>/attributes/<acc_attr_id>"
}
```

<RequestExample>
  ```json THE ATTRIBUTE OBJECT theme={null}
  {
    "id": "acc_attr_cWBKqwVP87kim",
    "account_id": "acc_4m9amk4KFiaQX",
    "status": "completed",
    "attributes": {
      "type": {
        "value": "credit_card",
        "error": null,
        "metadata": null
      },
      "usage_pattern": {
        "value": "revolver",
        "error": null,
        "metadata": null
      },
      "delinquency_flag": {
        "value": "on_time",
        "error": null,
        "metadata": null
      },
      "utilization": {
        "value": 11.96,
        "error": null,
        "metadata": null
      },
      "available_credit_limit": {
        "value": 7131600,
        "error": null,
        "metadata": null
      },
      "any_delinquent_flag": {
        "value": false,
        "error": null,
        "metadata": null
      },
      "delinquency_worst_dpd_bucket": {
        "value": null,
        "error": {
          "type": "ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA",
          "sub_type": "ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA",
          "code": 28001,
          "message": "Insufficient data to compute this account attribute."
        },
        "metadata": null
      },
      "enrolled_in_direct_pay_previously": {
        "value": true,
        "error": null,
        "metadata": null
      },
      "last_direct_pay_date": {
        "value": "2026-04-15T17:02:47.910Z",
        "error": null,
        "metadata": null
      },
      "last_direct_pay_amount": {
        "value": 12500,
        "error": null,
        "metadata": null
      },
      "number_of_direct_pay_in_12_months": {
        "value": 3,
        "error": null,
        "metadata": null
      },
      "next_payment_due_date": {
        "value": "2026-05-01",
        "error": null,
        "metadata": {
          "estimated": true
        }
      },
      "next_payment_minimum_amount": {
        "value": 3500,
        "error": null,
        "metadata": null
      },
      "estimated_apr": {
        "value": 21.5,
        "error": null,
        "metadata": {
          "estimated": true,
          "confidence": "high"
        }
      },
      "utilization_trend_30d": {
        "value": null,
        "error": {
          "type": "ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA",
          "sub_type": "ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA",
          "code": 28001,
          "message": "Insufficient data to compute this account attribute."
        },
        "metadata": null
      },
      "utilization_trend_90d": {
        "value": null,
        "error": {
          "type": "ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA",
          "sub_type": "ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA",
          "code": 28001,
          "message": "Insufficient data to compute this account attribute."
        },
        "metadata": null
      },
      "utilization_delta_30d": {
        "value": -3.28,
        "error": null,
        "metadata": null
      },
      "utilization_delta_60d": {
        "value": null,
        "error": {
          "type": "ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA",
          "sub_type": "ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA",
          "code": 28001,
          "message": "Insufficient data to compute this account attribute."
        },
        "metadata": null
      },
      "utilization_delta_90d": {
        "value": null,
        "error": {
          "type": "ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA",
          "sub_type": "ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA",
          "code": 28001,
          "message": "Insufficient data to compute this account attribute."
        },
        "metadata": null
      }
    },
    "error": null,
    "created_at": "2026-04-09T17:02:47.910Z",
    "updated_at": "2026-04-09T17:04:35.220Z"
  }
  ```
</RequestExample>


# Retrieve Attributes
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/attributes/retrieve

GET /accounts/{acc_id}/attributes/{acc_attr_id}

Retrieves an Attributes record for an Account.

## Path Parameters

<ParamList />

## Returns

Returns an Account's Attributes object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_4m9amk4KFiaQX/attributes/acc_attr_cWBKqwVP87kim \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const attribute = await method
    .accounts('acc_4m9amk4KFiaQX')
    .attributes
    .retrieve('acc_attr_cWBKqwVP87kim');
  ```

  ```python Python theme={null}
  attribute = method
    .accounts('acc_4m9amk4KFiaQX')
    .attributes
    .retrieve('acc_attr_cWBKqwVP87kim')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "acc_attr_cWBKqwVP87kim",
      "account_id": "acc_4m9amk4KFiaQX",
      "status": "completed",
      "attributes": {
        "type": {
          "value": "credit_card",
          "error": null,
          "metadata": null
        },
        "usage_pattern": {
          "value": "revolver",
          "error": null,
          "metadata": null
        },
        "delinquency_flag": {
          "value": "on_time",
          "error": null,
          "metadata": null
        },
        "utilization": {
          "value": 11.96,
          "error": null,
          "metadata": null
        },
        "utilization_delta_30d": {
          "value": -3.28,
          "error": null,
          "metadata": null
        }
      },
      "error": null,
      "created_at": "2026-04-09T17:02:47.910Z",
      "updated_at": "2026-04-09T17:04:35.220Z"
    },
    "message": null
  }
  ```
</ResponseExample>


# Create a Balance
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/balances/create

POST /accounts/{acc_id}/balances

Creates a new Balance request to retrieve the Account's balance from the financial institution.

Operation Type: <Tooltip>⏳ Asynchronous</Tooltip> | [Webhook Payload](overview#webhook-payload).

## Path Parameters

<ParamList />

## Returns

Returns a Balance object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/balances \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .balances
    .create();
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .balances
    .create()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "bal_dGCCNWHMQYRay",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "in_progress",
    "amount": null,
    "error": null,
    "created_at": "2024-03-14T01:41:28.434Z",
    "updated_at": "2024-03-14T01:41:28.434Z"
  }
  ```
</ResponseExample>


# List all Balances
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/balances/list

GET /accounts/{acc_id}/balances

Retrieve a list of Balances requests for a specific Account.

## Path Parameters

<ParamList />

## Query Parameters

<ParamList />

## Returns

Returns a list of Balances.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/balances" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .balances
    .list();
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .balances
    .list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "id": "bal_ebzh8KaR9HCBG",
        "account_id": "acc_mBxKxAEUmVd6X",
        "status": "completed",
        "amount": 30000,
        "error": null,
        "created_at": "2024-03-28T15:25:44.763Z",
        "updated_at": "2024-03-28T15:26:04.082Z"
      },
      {...}
    ]
  }
  ```
</ResponseExample>


# The balances endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/balances/overview



The Balance endpoint retrieves the real-time balance from the Account’s financial institution.

**The Balance endpoint is available as a:**

| Type      | Use-Case                                                             |
| --------- | -------------------------------------------------------------------- |
| `Product` | On-Demand real-time balance from the Account’s financial institution |

## Balances Objects

<ParamList />

## Webhook Payload

The [Webhook](/2026-03-30/reference/webhooks/overview) payload will contain the following information:

```json theme={null}
{
  "id": "string",
  "type": "balance.create" | "balance.update",
  "path": "/accounts/<acc_id>/balances/<bal_id>",
}
```

<RequestExample>
  ```json THE BALANCE OBJECT theme={null}
  {
    "id": "bal_ebzh8KaR9HCBG",
    "account_id": "acc_mBxKxAEUmVd6X",
    "status": "completed",
    "amount": 30000,
    "error": null,
    "created_at": "2024-03-14T01:41:28.434Z",
    "updated_at": "2024-03-14T01:41:28.655Z"
  }
  ```
</RequestExample>


# Retrieve a Balance
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/balances/retrieve

GET /accounts/{acc_id}/balances/{bal_id}

Retrieve a Balance record for an Account.

## Path Parameters

<ParamList />

## Returns

Returns a Balance object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/balances/bal_ebzh8KaR9HCBG \
    -X GET \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .balances
    .retrieve('bal_ebzh8KaR9HCBG');
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .balances
    .retrieve('bal_ebzh8KaR9HCBG')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "bal_ebzh8KaR9HCBG",
    "account_id": "acc_mBxKxAEUmVd6X",
    "status": "completed",
    "amount": 30000,
    "error": null,
    "created_at": "2024-03-28T15:25:44.763Z",
    "updated_at": "2024-03-28T15:26:04.082Z"
  }
  ```
</ResponseExample>


# Create a Card Brand
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/card-brands/create

POST /accounts/{acc_id}/card_brands

Creates a new CardBrand request to retrieve the Account's card brand.

Operation Type: <Tooltip>⏳ Asynchronous</Tooltip>

## Path Parameters

<ParamList />

## Returns

Returns a CardBrand object. On version `2025-07-04` and later, each resolved brand in `brands[]` includes a `details` object with card details (APRs, fees, rewards, and promotions).

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/card_brands \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .cardBrands
    .create();
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .card_brands
    .create()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "cbrd_Accm7P6t6mYQP",
    "account_id": "acc_LxwEqNicr66yP",
    "brands": [
      {
        "id": "pdt_15_brd_1",
        "card_product_id": "pdt_15",
        "description": "Chase Sapphire Reserve",
        "name": "Chase Sapphire Reserve",
        "issuer": "Chase",
        "network": "visa",
        "network_tier": "infinite",
        "type": "specific",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png",
        "details": {
          "card_category": "travel",
          "purchase_apr_min": 21.24,
          "purchase_apr_max": 28.24,
          "cash_advance_apr_min": 29.99,
          "cash_advance_apr_max": 29.99,
          "annual_fee": 55000,
          "late_payment_fee": 4000,
          "rewards": {
            "type": "points",
            "program": "Chase Ultimate Rewards",
            "categories": [
              { "category": "travel", "category_presentable": "Travel booked through Chase Travel", "rate": 5, "unit": "points_per_dollar", "cap": null },
              { "category": "dining", "category_presentable": "Dining", "rate": 3, "unit": "points_per_dollar", "cap": null },
              { "category": "base_rate", "category_presentable": "All other purchases", "rate": 1, "unit": "points_per_dollar", "cap": null }
            ]
          },
          "promotions": [
            {
              "type": "sign_up_bonus",
              "title": "60,000 bonus points",
              "description": "Earn 60,000 bonus points after you spend $4,000 on purchases in the first 3 months from account opening.",
              "value": 60000,
              "unit": "points",
              "spend_requirement": 400000,
              "qualifying_period": { "value": 3, "unit": "months", "relative_to": "account_opening" },
              "expiration": null
            }
          ],
          "data_as_of": "2026-06-03"
        }
      }
    ],
    "status": "completed",
    "source": "method",
    "error": null,
    "created_at": "2025-08-12T00:56:50.139Z",
    "updated_at": "2025-08-12T00:56:50.139Z"
  }
  ```
</ResponseExample>


# The card brand endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/card-brands/overview



The CardBrand endpoint retrieves the associated credit card metadata (Product / Brand Name, Art, etc) directly from the card issuer,
allowing partners to display this information within their wallet experience. On version `2025-07-04` and later, each brand also includes a `details` object with structured card details, including APRs, fees, rewards, and promotional offers.

<Warning>
  The CardBrand endpoint is available only to partners processing payments using the
  <a href="/2026-03-30/reference/accounts/payment-instruments/overview">PaymentInstrument endpoint</a>. Contact your Method CSM for more information.
</Warning>

**The CardBrand endpoint is available as a:**

| Type           | Use-Case                                                                                                      |
| -------------- | ------------------------------------------------------------------------------------------------------------- |
| `Product`      | On-Demand retrieval of credit card metadata (Product / Brand Name, Art, etc) directly from the card issuer    |
| `Subscription` | Near real-time updates on credit card metadata (Product / Brand Name, Art, etc) directly from the card issuer |

## CardBrand Objects

<ParamList />

## Webhook Payload

The [Webhook](/2026-03-30/reference/webhooks/overview) payload will contain the following information:

```json theme={null}
{
  "id": "string",
  "type": "card_brand.create" | "card_brand.update" | "card_brand.available",
  "path": "/accounts/<acc_id>/card_brands/<cbrd_id>",
}
```

<RequestExample>
  ```json THE CARD BRAND OBJECT theme={null}
  {
    "id": "cbrd_Accm7P6t6mYQP",
    "account_id": "acc_LxwEqNicr66yP",
    "brands": [
      {
        "id": "pdt_15_brd_1",
        "card_product_id": "pdt_15",
        "description": "Chase Sapphire Reserve",
        "name": "Chase Sapphire Reserve",
        "issuer": "Chase",
        "network": "visa",
        "network_tier": "infinite",
        "type": "specific",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png",
        "details": {
          "card_category": "travel",
          "purchase_apr_min": 21.24,
          "purchase_apr_max": 28.24,
          "cash_advance_apr_min": 29.99,
          "cash_advance_apr_max": 29.99,
          "annual_fee": 55000,
          "late_payment_fee": 4000,
          "rewards": {
            "type": "points",
            "program": "Chase Ultimate Rewards",
            "categories": [
              { "category": "travel", "category_presentable": "Travel booked through Chase Travel", "rate": 5, "unit": "points_per_dollar", "cap": null },
              { "category": "dining", "category_presentable": "Dining", "rate": 3, "unit": "points_per_dollar", "cap": null },
              { "category": "base_rate", "category_presentable": "All other purchases", "rate": 1, "unit": "points_per_dollar", "cap": null }
            ]
          },
          "promotions": [
            {
              "type": "sign_up_bonus",
              "title": "60,000 bonus points",
              "description": "Earn 60,000 bonus points after you spend $4,000 on purchases in the first 3 months from account opening.",
              "value": 60000,
              "unit": "points",
              "spend_requirement": 400000,
              "qualifying_period": { "value": 3, "unit": "months", "relative_to": "account_opening" },
              "expiration": null
            }
          ],
          "data_as_of": "2026-06-03"
        }
      }
    ],
    "status": "completed",
    "source": "method",
    "error": null,
    "created_at": "2025-08-12T00:56:50.139Z",
    "updated_at": "2025-08-12T00:56:50.139Z"
  }
  ```
</RequestExample>


# Retrieve a Card Brand
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/card-brands/retrieve

GET /accounts/{acc_id}/card_brands/{cbrd_id}

Retrieves a CardBrand record for an Account.

## Path Parameters

<ParamList />

## Returns

Returns a CardBrand object. On version `2025-07-04` and later, each brand in `brands[]` includes a `details` object with card details (APRs, fees, rewards, and promotions).

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/card_brands/cbrd_eVMDNUPfrFk3e \
    -X GET \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .cardBrands
    .retrieve('cbrd_eVMDNUPfrFk3e');
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .card_brands
    .retrieve('cbrd_eVMDNUPfrFk3e')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "cbrd_Accm7P6t6mYQP",
    "account_id": "acc_LxwEqNicr66yP",
    "brands": [
      {
        "id": "pdt_15_brd_1",
        "card_product_id": "pdt_15",
        "description": "Chase Sapphire Reserve",
        "name": "Chase Sapphire Reserve",
        "issuer": "Chase",
        "network": "visa",
        "network_tier": "infinite",
        "type": "specific",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png",
        "details": {
          "card_category": "travel",
          "purchase_apr_min": 21.24,
          "purchase_apr_max": 28.24,
          "cash_advance_apr_min": 29.99,
          "cash_advance_apr_max": 29.99,
          "annual_fee": 55000,
          "late_payment_fee": 4000,
          "rewards": {
            "type": "points",
            "program": "Chase Ultimate Rewards",
            "categories": [
              { "category": "travel", "category_presentable": "Travel booked through Chase Travel", "rate": 5, "unit": "points_per_dollar", "cap": null },
              { "category": "dining", "category_presentable": "Dining", "rate": 3, "unit": "points_per_dollar", "cap": null },
              { "category": "base_rate", "category_presentable": "All other purchases", "rate": 1, "unit": "points_per_dollar", "cap": null }
            ]
          },
          "promotions": [
            {
              "type": "sign_up_bonus",
              "title": "60,000 bonus points",
              "description": "Earn 60,000 bonus points after you spend $4,000 on purchases in the first 3 months from account opening.",
              "value": 60000,
              "unit": "points",
              "spend_requirement": 400000,
              "qualifying_period": { "value": 3, "unit": "months", "relative_to": "account_opening" },
              "expiration": null
            }
          ],
          "data_as_of": "2026-06-03"
        }
      }
    ],
    "status": "completed",
    "source": "method",
    "error": null,
    "created_at": "2025-08-12T00:56:50.139Z",
    "updated_at": "2025-08-12T00:56:50.139Z"
  }
  ```
</ResponseExample>


# Withdraw an Account's Consent
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/consent/withdraw

POST /accounts/{acc_id}/consent

Withdraws an Account's consent. This endpoint deletes information
on the account, sets its status to `disabled`, and removes all active Products or Subscriptions for the account.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns the Account with `status` set to `disabled`.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/consent \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "withdraw",
      "reason": "holder_withdrew_consent"
  }'
  ```

  ```javascript Node.js theme={null}
  const account = await method.accounts.withdrawConsent('acc_yVf3mkzbhz9tj');
  ```

  ```python Python theme={null}
  account = method.accounts.withdraw_consent('acc_yVf3mkzbhz9tj', {
    'type': 'withdraw',
    'reason': 'holder_withdrew_consent'
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "acc_JmfdTzg9hp3QQ",
    "holder_id": "ent_4hBGhBAmgBDWt",
    "status": "disabled",
    "type": null,
    "ach": null,
    "liability": null,
    "capabilities": [],
    "available_capabilities": [],
    "error": {
      "type": "ACCOUNT_DISABLED",
      "sub_type": "ACCOUNT_CONSENT_WITHDRAWN",
      "code": 11004,
      "message": "Account was disabled due to consent withdrawal."
    },
    "metadata": null,
    "created_at": "2024-04-01T18:48:39.634Z",
    "updated_at": "2024-04-01T18:48:39.695Z"
  }
  ```
</ResponseExample>


# Create an Account
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/create

POST /accounts

Creates a new Account for an Entity, either `ach` or `liability`, based on
the parameters provided. An account is a unique
representation of an [ACH](/2026-03-30/reference/accounts/overview#ach)
or [Liability](/2026-03-30/reference/accounts/overview#liability) account.

<Warning>
  Creating Liability Accounts directly is only supported on a case-by-case basis.
  If you need to create a Liability Account, contact your Method CSM.
</Warning>

## Body

<ParamList />

## Returns

Returns an Account object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "holder_id": "ent_y1a9e1fbnJ1f3",
      "ach": {
        "routing": "367537407",
        "number": "57838927",
        "type": "checking"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const account = await method
    .accounts
    .create({
      holder_id: 'ent_y1a9e1fbnJ1f3',
      ach: {
        routing: '367537407',
        number: '57838927',
        type: 'checking',
      },
    });
  ```

  ```python Python theme={null}
  account = method
    .accounts
    .create({
      'holder_id': 'ent_y1a9e1fbnJ1f3',
      'ach': {
        'routing': '367537407',
        'number': '57838927',
        'type': 'checking'
      }
    })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "acc_BcRdHNjb9TYKV",
    "holder_id": "ent_wUzi83DJdx99e",
    "status": "active",
    "type": "ach",
    "ach": {
      "routing": "367537407",
      "number": "57838927",
      "type": "checking"
    },
    "latest_verification_session": "avf_7WGUjnFLcipRm",
    "products": [
      "payment"
    ],
    "restricted_products": [],
    "error": null,
    "metadata": null,
    "created_at": "2023-10-23T06:25:56.500Z",
    "updated_at": "2023-10-23T06:25:56.500Z"
  }
  ```
</ResponseExample>


# List all Accounts
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/list

GET /accounts

Returns a list of Accounts.

## Query Parameters

<ParamList />

## Returns

Returns a list of Accounts.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/accounts?holder_id=ent_y1a9e1fbnJ1f3&type=liability&status=active" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const accounts = await method
    .accounts
    .list({
      holder_id: 'ent_y1a9e1fbnJ1f3',
      type: 'liability',
      status: 'active',
    });
  ```

  ```python Python theme={null}
  accounts = method
    .accounts
    .list({
      'holder_id': 'ent_y1a9e1fbnJ1f3',
      'type': 'liability',
      'status': 'active'
    })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "id": "acc_RGACQH7XdfYhC",
        "holder_id": "ent_y1a9e1fbnJ1f3",
        "status": "active",
        "type": "liability",
        "liability": {
          "mch_id": "mch_302086",
          "mask": "1580",
          "ownership": "primary",
          "fingerprint": "27d5c0ea28338619192076d150eb7b56c288f9a1",
          "type": "credit_card",
          "name": "Chase Sapphire Reserve Credit Card"
        },
        "latest_verification_session": "avf_tB9mpmew8FLit",
        "update": "upt_TXDTR7Amyz7Az",
        "balance": "bal_dGCCNWHMQYRay",
        "card_brand": "crd_eVMDNUPfrFk3e",
        "payment_instrument": "pmt_inst_pd788hPVhLT37",
        "products": ["balance", "card_brand", "update", "payment", "payment_instrument.card", "payment_instrument.network_token", "payment_instrument.inbound_achwire_payment"],
        "restricted_products": ["attribute", "sensitive"],
        "subscriptions": [],
        "available_subscriptions": ["update.snapshot", "update"],
        "restricted_subscriptions": ["transaction"],
        "error": null,
        "metadata": null,
        "created_at": "2024-04-12T18:57:57.857Z",
        "updated_at": "2024-04-12T18:57:58.430Z"
      }
    ]
  }
  ```
</ResponseExample>


# The account endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/overview



Accounts are a representation of an Entity's financial accounts. An Account
can be a checking or savings account (ACH) or a credit card, student loan,
mortgage, personal loan, etc. (Liability).

## Account Objects

<Tabs>
  <Tab title="Liability">
    <ParamList />

    ## Additional Properties based on liability type

    <Tabs>
      <Tab title="Auto Loan">
        <ParamList />
      </Tab>

      <Tab title="Collection">
        <ParamList />
      </Tab>

      <Tab title="Credit Builder">
        <ParamList />
      </Tab>

      <Tab title="Credit Card">
        <ParamList />
      </Tab>

      <Tab title="Insurance">
        <ParamList />
      </Tab>

      <Tab title="Loan">
        <ParamList />
      </Tab>

      <Tab title="Medical">
        <ParamList />
      </Tab>

      <Tab title="Mortgage">
        <ParamList />
      </Tab>

      <Tab title="Personal Loan">
        <ParamList />
      </Tab>

      <Tab title="Student Loans">
        <ParamList />
      </Tab>

      <Tab title="Utility">
        <ParamList />
      </Tab>

      <Tab title="BNPL">
        <ParamList />
      </Tab>

      <Tab title="Fintech">
        <ParamList />
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="ACH">
    <ParamList />
  </Tab>
</Tabs>

## Account Liability Types

| Type             | Description                                                                                                                                             |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auto_loan`      | A financial obligation incurred when borrowing funds to purchase a vehicle, usually secured by the vehicle itself.                                      |
| `collection`     | An account that reflects debts not paid on time, now handled by a third-party collection agency to recover the funds.                                   |
| `credit_builder` | A type of financial arrangement, typically a small loan or secured credit card, designed to help individuals establish or improve their credit history. |
| `credit_card`    | A revolving line of credit that allows the holder to make purchases or cash advances up to a certain limit, requiring regular payments.                 |
| `insurance`      | Financial protection against specific losses in exchange for premiums paid, not typically a liability unless premiums are unpaid.                       |
| `loan`           | Money borrowed that must be repaid with interest, can include various types such as personal, auto, or business loans.                                  |
| `medical`        | Accounts representing charges for healthcare services, often resulting from treatments or procedures not fully covered by insurance.                    |
| `mortgage`       | A long-term loan secured by real estate property, used to purchase or refinance that property.                                                          |
| `personal_loan`  | A secured or unsecured loan taken out by individuals from a bank or other financial institution for personal use.                                       |
| `student_loans`  | Loans issued for the purpose of financing postsecondary education, payable under terms agreed upon completion of study.                                 |
| `utility`        | Bills owed for basic services such as electricity, water, and gas, which if unpaid, can become delinquent liabilities.                                  |
| `bnpl`           | Buy Now, Pay Later — a type of loan that lets the borrower make a purchase immediately and pay for it over time in installments.                        |
| `fintech`        | An account facilitated by a financial technology (fintech) company acting as an intermediary between the borrower and a partner bank or lender.         |

## Account Liability Sub-Types

| Type             | Subtypes                                                                       |
| ---------------- | ------------------------------------------------------------------------------ |
| `loan`           | `business`, `unsecured`                                                        |
| `auto_loan`      | `lease`, `loan`                                                                |
| `collection`     | -                                                                              |
| `mortgage`       | `heloc`                                                                        |
| `credit_card`    | `business`, `charge`, `flexible_spending`, `secured`                           |
| `personal_loan`  | `line_of_credit`, `heloc`, `purchase`, `lease`, `note`, `secured`, `unsecured` |
| `student_loans`  | `private`, `federal`                                                           |
| `credit_builder` | `rent`                                                                         |

## Webhook Payload

The [Webhook](/2026-03-30/reference/webhooks/overview) payload will contain the following information:

```json theme={null}
{
  "id": "string",
  "type": "account.create" | "account.update" | "account.number.update",
  "path": "/accounts/<acc_id>",
  "event": "<evt_id>"
}
```

<RequestExample>
  ```json Liability theme={null}
  {
    "id": "acc_RGACQH7XdfYhC",
    "holder_id": "ent_HYmQrVrcJQBBQ",
    "status": "active",
    "type": "liability",
    "liability": {
      "mch_id": "mch_302086",
      "mask": "1580",
      "ownership": "primary",
      "fingerprint": "27d5c0ea28338619192076d150eb7b56c288f9a1",
      "type": "credit_card",
      "name": "Chase Sapphire Reserve Credit Card"
    },
    "latest_verification_session": "avf_tB9mpmew8FLit",
    "update": "upt_NYV5kfjskTTCJ",
    "balance": "bal_dGCCNWHMQYRay",
    "card_brand": "crd_eVRdjn4jsfk3e",
    "payment_instrument": "pmt_inst_pd788hPVhLT37",
    "attribute": "acc_attr_cWBKqwVP87kim",
    "products": ["balance", "card_brand", "update", "payment", "payment_instrument.card", "payment_instrument.network_token", "payment_instrument.inbound_achwire_payment"],
    "restricted_products": ["attribute", "sensitive"],
    "subscriptions": [],
    "available_subscriptions": ["update.snapshot", "update"],
    "restricted_subscriptions": ["transaction"],
    "error": null,
    "metadata": null,
    "created_at": "2024-02-12T18:57:57.857Z",
    "updated_at": "2024-03-20T04:43:21.655Z"
  }
  ```

  ```json ACH theme={null}
  {
    "id": "acc_BcRdHNjb9TYKV",
    "holder_id": "ent_wUzi83DJdx99e",
    "status": "active",
    "type": "ach",
    "ach": {
      "routing": "367537407",
      "number": "57838927",
      "type": "checking"
    },
    "latest_verification_session": "avf_7WGUjnFLcipRm",
    "products": [
      "payment"
    ],
    "restricted_products": [],
    "error": null,
    "metadata": null,
    "created_at": "2023-10-23T06:25:56.500Z",
    "updated_at": "2023-10-23T06:25:56.500Z"
  }
  ```
</RequestExample>


# Create Payment Instruments
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/payment-instruments/create

POST /accounts/{acc_id}/payment_instruments

Enables creation of a PaymentInstrument linked to an account, returning card credentials (e.g., card number, expiration, or network token) for use in checkout, or account and routing details for receiving inbound ACH / wire payments.

Operation Type: <Tooltip>⚡ Synchronous</Tooltip>

## Path Parameters

<ParamList />

## Request Body Parameters

<ParamList />

## Returns

Returns a PaymentInstrument object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_4m9amk4KFiaQX/payment_instruments \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "card"
    }'
  ```

  ```javascript Node.js theme={null}
  const paymentInstrument = await method
    .accounts('acc_4m9amk4KFiaQX')
    .paymentInstruments
    .create({
      type: 'card'
    });
  ```

  ```python Python theme={null}
  payment_instrument = method
    .accounts('acc_4m9amk4KFiaQX')
    .payment_instruments
    .create({
      "type": "card"
    })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "pmt_inst_pd788hPVhLT37",
      "account_id": "acc_GAzrD99cUqGEN",
      "type": "card",
      "card": {
        "number": "5555555555551580",
        "exp_month": "04",
        "exp_year": "2027",
        "cvv": "878",
        "billing_zip_code": "12345"
      },
      "network_token": null,
      "inbound_achwire_payment": null,
      "chargeable": true,
      "status": "completed",
      "error": null,
      "created_at": "2025-12-03T19:30:56.039Z",
      "updated_at": "2025-12-03T19:30:56.039Z"
    },
    "message": null
  }
  ```
</ResponseExample>


# Delete Payment Instrument
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/payment-instruments/delete

DELETE /accounts/{acc_id}/payment_instruments/{pmt_inst_id}

Closes a PaymentInstrument that is no longer needed, for example after a refinance completes or when a funding relationship ends. Supported only for PaymentInstruments of type `inbound_achwire_payment`.

Closing a PaymentInstrument updates its status to `closed` and sets `chargeable` to `false`.

Operation Type: <Tooltip>⚡ Synchronous</Tooltip>

## Path Parameters

<ParamList />

## Returns

Returns the closed PaymentInstrument object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_GAzrD99cUqGEN/payment_instruments/pmt_inst_cLbaArHhfDBDf \
    -X DELETE \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "pmt_inst_cLbaArHhfDBDf",
      "account_id": "acc_GAzrD99cUqGEN",
      "type": "inbound_achwire_payment",
      "card": null,
      "network_token": null,
      "inbound_achwire_payment": {
        "account_number": "2517228863",
        "routing_number": "026015244",
        "reversal_account": "acc_BcRdHNjb9TYKY"
      },
      "chargeable": false,
      "status": "closed",
      "error": null,
      "created_at": "2025-12-11T00:12:58.639Z",
      "updated_at": "2026-01-15T00:12:58.639Z"
    },
    "message": null
  }
  ```
</ResponseExample>


# List Payment Instruments
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/payment-instruments/list

GET /accounts/{acc_id}/payment_instruments

Retrieves a list of PaymentInstrument objects for an Account.

## Path Parameters

<ParamList />

## Query Parameters

<ParamList />

## Returns

Returns a list of PaymentInstrument objects.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/accounts/acc_4m9amk4KFiaQX/payment_instruments" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_4m9amk4KFiaQX')
    .paymentInstruments
    .list();
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_4m9amk4KFiaQX')
    .payment_instruments
    .list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "pmt_inst_pd788hPVhLT37",
        "account_id": "acc_GAzrD99cUqGEN",
        "type": "card",
        "card": {
          "number": "5555555555551580",
          "exp_month": "04",
          "exp_year": "2027",
          "cvv": "878",
          "billing_zip_code": "12345"
        },
        "network_token": null,
        "inbound_achwire_payment": null,
        "chargeable": true,
        "status": "completed",
        "error": null,
        "created_at": "2025-12-03T19:30:56.039Z",
        "updated_at": "2025-12-03T19:30:56.039Z"
      },
      {
        "id": "pmt_inst_vk423jTNmSR82",
        "account_id": "acc_GAzrD99cUqGEN",
        "type": "network_token",
        "card": null,
        "network_token": {
          "token": "1234567890123456"
        },
        "inbound_achwire_payment": null,
        "chargeable": true,
        "status": "completed",
        "error": null,
        "created_at": "2025-12-03T19:30:56.039Z",
        "updated_at": "2025-12-03T19:30:56.039Z"
      }
    ],
    "message": null
  }
  ```
</ResponseExample>


# The payment instrument endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/payment-instruments/overview



The PaymentInstrument endpoint allows the creation and retrieval of card credentials for checkout, such as card account details or a network token, as well as inbound ACH / wire payment instruments for receiving payments.

**The PaymentInstrument endpoint is available as a:**

| Type      | Use-Case                                            |
| --------- | --------------------------------------------------- |
| `Product` | On-Demand view of an Account's payment instruments. |

## Payment Instrument Objects

<ParamList />

<RequestExample>
  ```json Card Payment PaymentInstrument theme={null}
  {
    "id": "pmt_inst_pd788hPVhLT37",
    "account_id": "acc_GAzrD99cUqGEN",
    "type": "card",
    "card": {
      "number": "5555555555551580",
      "exp_month": "04",
      "exp_year": "2027",
      "cvv": "878",
      "billing_zip_code": "12345"
    },
    "network_token": null,
    "inbound_achwire_payment": null,
    "chargeable": true,
    "status": "completed",
    "error": null,
    "created_at": "2025-04-03T19:30:56.039Z",
    "updated_at": "2025-04-03T19:30:56.039Z"
  }
  ```

  ```json Network Token PaymentInstrument theme={null}
  {
    "id": "pmt_inst_pd788hPVhLT37",
    "account_id": "acc_GAzrD99cUqGEN",
    "type": "network_token",
    "card": null,
    "network_token": {
      "token": "1234567890123456"
    },
    "inbound_achwire_payment": null,
    "chargeable": true,
    "status": "completed",
    "error": null,
    "created_at": "2025-04-03T19:30:56.039Z",
    "updated_at": "2025-04-03T19:30:56.039Z"
  }
  ```

  ```json Inbound Achwire Payment Token PaymentInstrument theme={null}
  {
    "id": "pmt_inst_cLbaArHhfDBDf",
    "account_id": "acc_GAzrD99cUqGEN",
    "type": "inbound_achwire_payment",
    "card": null,
    "network_token": null,
    "inbound_achwire_payment": {
      "account_number": "2517228863",
      "routing_number": "026015244",
      "reversal_account": "acc_BcRdHNjb9TYKY"
    },
    "chargeable": true,
    "status": "completed",
    "error": null,
    "created_at": "2025-12-11T00:12:58.639Z",
    "updated_at": "2025-12-11T00:12:58.639Z"
  }
  ```
</RequestExample>


# Retrieve Payment Instrument
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/payment-instruments/retrieve

GET /accounts/{acc_id}/payment_instruments/{pmt_inst_id}

Retrieves a specific PaymentInstrument for an Account.

## Path Parameters

<ParamList />

## Returns

Returns a PaymentInstrument object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_GAzrD99cUqGEN/payment_instruments/pmt_inst_pd788hPVhLT37 \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const paymentInstrument = await method
    .accounts('acc_GAzrD99cUqGEN')
    .paymentInstruments
    .retrieve('pmt_inst_pd788hPVhLT37');
  ```

  ```python Python theme={null}
  payment_instrument = method
    .accounts('acc_GAzrD99cUqGEN')
    .payment_instruments
    .retrieve('pmt_inst_pd788hPVhLT37')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "pmt_inst_pd788hPVhLT37",
      "account_id": "acc_GAzrD99cUqGEN",
      "type": "card",
      "card": {
        "number": "5555555555551580",
        "exp_month": "04",
        "exp_year": "2027",
        "cvv": "878",
        "billing_zip_code": "12345"
      },
      "network_token": null,
      "inbound_achwire_payment": null,
      "chargeable": true,
      "status": "completed",
      "error": null,
      "created_at": "2025-12-03T19:30:56.039Z",
      "updated_at": "2025-12-03T19:30:56.039Z"
    },
    "message": null
  }
  ```
</ResponseExample>


# Create a Payoff
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/payoffs/create

POST /accounts/{acc_id}/payoffs

Creates a new Payoff request to retrieve a payoff quote from the Account’s financial institution / lender.

Operation Type: <Tooltip>⏳ Asynchronous</Tooltip> | [Webhook Payload](overview#webhook-payload).

## Path Parameters

<ParamList />

## Returns

Returns a Payoff object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/payoffs \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .payoffs
    .create();
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .payoffs
    .create()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "pyf_ELGT4hfikTTCJ",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "in_progress",
    "amount": null,
    "term": null,
    "per_diem_amount": null,
    "error": null,
    "created_at": "2024-03-14T01:41:28.434Z",
    "updated_at": "2024-03-14T01:41:28.434Z"
  }
  ```
</ResponseExample>


# List all Payoffs
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/payoffs/list

GET /accounts/{acc_id}/payoffs

Retrieve a list of Payoff requests for a specific Account.

## Path Parameters

<ParamList />

## Query Parameters

<ParamList />

## Returns

Returns a list of Payoffs.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/payoffs" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .payoffs
    .list();
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .payoffs
    .list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "id": "pyf_vWrK2f6mLrGvA",
        "status": "in_progress",
        "amount": null,
        "term": null,
        "per_diem_amount": null,
        "error": null,
        "created_at": "2024-03-14T01:41:28.434Z",
        "updated_at": "2024-03-14T01:41:28.655Z"
      },
      {
        "id": "pyf_ELGT4hfikTTCJ",
        "status": "completed",
        "amount": 6083988,
        "term": 15,
        "per_diem_amount": null,
        "error": null,
        "created_at": "2024-02-14T01:41:28.434Z",
        "updated_at": "2024-02-14T01:41:28.655Z"
      }
    ]
  }
  ```
</ResponseExample>


# The payoffs endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/payoffs/overview



The Payoffs endpoint retrieves a payoff quote in real-time from the Account’s financial institution / lender.

<Info>Payoffs are currently only available for Auto Loan and Mortgage accounts</Info>

**The Payoff endpoint is available as a:**

| Type      | Use-Case                                                                                                 |
| --------- | -------------------------------------------------------------------------------------------------------- |
| `Product` | On-Demand retrieval of auto loan payoff (amount, per diem, etc) from the Account’s financial institution |

## Payoff Objects

<ParamList />

## Webhook Payload

The [Webhook](/2026-03-30/reference/webhooks/overview) payload will contain the following information:

```json theme={null}
{
  "id": "string",
  "type": "payoff.create" | "payoff.update",
  "path": "/accounts/<acc_id>/payoffs/<pyf_id>",
}
```

<RequestExample>
  ```json THE PAYOFF OBJECT theme={null}
  {
    "id": "pyf_ELGT4hfikTTCJ",
    "status": "completed",
    "amount": 6083988,
    "term": 15,
    "per_diem_amount": null,
    "error": null,
    "created_at": "2024-03-14T01:41:28.434Z",
    "updated_at": "2024-03-14T01:41:28.655Z"
  }
  ```
</RequestExample>


# Retrieve a Payoff
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/payoffs/retrieve

GET /accounts/{acc_id}/payoffs/{pyf_id}

Retrieve a Payoff record for an Account.

## Path Parameters

<ParamList />

## Returns

Returns a Payoff object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/payoffs/pyf_ELGT4hfikTTCJ \
    -X GET \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .payoffs
    .retrieve('pyf_ELGT4hfikTTCJ');
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .payoffs
    .retrieve('pyf_ELGT4hfikTTCJ')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "pyf_ELGT4hfikTTCJ",
    "status": "completed",
    "amount": 6083988,
    "term": 15,
    "per_diem_amount": null,
    "error": null,
    "created_at": "2024-03-14T01:41:28.434Z",
    "updated_at": "2024-03-14T01:41:28.655Z"
  }
  ```
</ResponseExample>


# List all Products
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/products/list

GET /accounts/{acc_id}/products

Returns a map of Product names to Product objects for an Account.

## Path Parameters

<ParamList />

## Returns

Returns a map of Product names to Product objects.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/products" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .products
    .list();
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .products
    .list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "sensitive": {
      "name": "sensitive",
      "status": "available",
      "status_error": null,
      "latest_request_id": null,
      "latest_successful_request_id": null,
      "is_subscribable": false,
      "created_at": "2024-03-26T20:25:27.261Z",
      "updated_at": "2024-03-26T20:25:27.317Z"
    },
    "balance": {
      "name": "balance",
      "status": "available",
      "status_error": null,
      "latest_request_id": null,
      "latest_successful_request_id": null,
      "is_subscribable": false,
      "created_at": "2024-03-26T20:25:27.261Z",
      "updated_at": "2024-03-26T20:25:27.316Z"
    },
    "card_brand": {
      "name": "card_brand",
      "status": "available",
      "status_error": null,
      "latest_request_id": null,
      "latest_successful_request_id": null,
      "is_subscribable": false,
      "created_at": "2024-03-26T20:25:27.261Z",
      "updated_at": "2024-03-26T20:25:27.316Z"
    },
    "attribute": {
      "name": "attribute",
      "status": "unavailable",
      "status_error": {
        "type": "INVALID_REQUEST",
        "sub_type": "PRODUCT_UNAVAILABLE",
        "message": "Product is unavailable or is not in a fixable state."
      },
      "latest_request_id": null,
      "latest_successful_request_id": null,
      "is_subscribable": false,
      "created_at": "2025-01-31T15:35:07.310Z",
      "updated_at": "2025-01-31T15:35:29.233Z"
    },
    "payoff": {
      "name": "payoff",
      "status": "unavailable",
      "status_error": {
        "type": "INVALID_REQUEST",
        "sub_type": "PRODUCT_UNAVAILABLE",
        "message": "Product is unavailable or is not in a fixable state."
      },
      "latest_request_id": null,
      "latest_successful_request_id": null,
      "is_subscribable": false,
      "created_at": "2024-03-26T20:25:27.261Z",
      "updated_at": "2024-03-26T20:25:27.317Z"
    },
    "update": {
      "name": "update",
      "status": "available",
      "status_error": null,
      "latest_request_id": null,
      "latest_successful_request_id": null,
      "is_subscribable": true,
      "created_at": "2024-03-26T20:25:27.261Z",
      "updated_at": "2024-03-26T20:25:27.317Z"
    },
    "payment_instrument.card": {
      "name": "payment_instrument.card",
      "status": "available",
      "status_error": null,
      "latest_request_id": null,
      "latest_successful_request_id": null,
      "is_subscribable": false,
      "created_at": "2024-03-26T20:25:27.261Z",
      "updated_at": "2024-03-26T20:25:27.317Z"
    },
    "payment_instrument.network_token": {
      "name": "payment_instrument.network_token",
      "status": "available",
      "status_error": null,
      "latest_request_id": null,
      "latest_successful_request_id": null,
      "is_subscribable": false,
      "created_at": "2024-03-26T20:25:27.261Z",
      "updated_at": "2024-03-26T20:25:27.317Z"
    },
    "payment_instrument.inbound_achwire_payment": {
      "name": "payment_instrument.inbound_achwire_payment",
      "status": "available",
      "status_error": null,
      "latest_request_id": null,
      "latest_successful_request_id": null,
      "is_subscribable": false,
      "created_at": "2024-03-26T20:25:27.261Z",
      "updated_at": "2024-03-26T20:25:27.317Z"
    }
  }
  ```
</ResponseExample>


# The products endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/products/overview



The Account Products endpoint outlines the Products (*capabilities*) an Account has access to, and provides an overview of the status of all the Products.

<Info>Most products are accessible by default. However, some products have restricted access requiring team-by-team enablement and elevated account verification.</Info>

### Product Names

Products that an Account can have access to:

| Name                                         | Use-Case                                                                                                   | Supported Types                                                        | Resource Doc                                                                       |
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `update`                                     | On-Demand real-time account update (balance, due dates, etc) from the Account's financial institution      | All liabilities                                                        | [Updates](/2026-03-30/reference/accounts/updates/overview)                         |
| `balance`                                    | On-Demand real-time balance from the Account's financial institution                                       | All liabilities                                                        | [Balances](/2026-03-30/reference/accounts/balances/overview)                       |
| `card_brand`                                 | On-Demand retrieval of credit card metadata (Product / Brand Name, Art, etc) directly from the card issuer | Credit Cards                                                           | [Card Brand](/2026-03-30/reference/accounts/card-brands/overview)                  |
| `attribute`                                  | On-Demand retrieval of account attributes from the Account's credit reporting                              | All liabilities                                                        | [Attributes](/2026-03-30/reference/accounts/attributes/overview)                   |
| `payoff`                                     | On-Demand retrieval of auto loan payoff (amount, per diem, etc) from the Account's financial institution   | Auto Loans                                                             | [Payoffs](/2026-03-30/reference/accounts/payoffs/overview)                         |
| `payment`                                    | Next day electronic push payments to the Account's financial institution                                   | All liabilities                                                        | [Payments](/2026-03-30/reference/payments/overview)                                |
| `sensitive`                                  | On-Demand retrieval of underlying sensitive account information (PAN, CVV, account number)                 | All liabilities                                                        | [Sensitive](/2026-03-30/reference/accounts/sensitive/overview)                     |
| `payment_instrument.card`                    | On-Demand retrieval of card payment instruments from the Account's financial institution                   | Credit Cards                                                           | [Payment Instruments](/2026-03-30/reference/accounts/payment-instruments/overview) |
| `payment_instrument.network_token`           | On-Demand retrieval of network token payment instruments from the Account's financial institution          | Credit Cards                                                           | [Payment Instruments](/2026-03-30/reference/accounts/payment-instruments/overview) |
| `payment_instrument.inbound_achwire_payment` | On-Demand retrieval of inbound ACH/wire payment instruments from the Account's financial institution       | All liabilities and debit cards with the `payments:receive` capability | [Payment Instruments](/2026-03-30/reference/accounts/payment-instruments/overview) |

## Product Objects

<ParamList />

## Webhook Payload

The [Webhook](/2026-03-30/reference/webhooks/overview) payload will contain the following information:

```json theme={null}
{
  "id": "string",
  "type": "product.create" | "product.update",
  "path": "/accounts/<acc_id>/products/<prd_id>",
}
```

<RequestExample>
  ```json THE PRODUCT OBJECT theme={null}
  {
    "name": "balance",
    "status": "available",
    "status_error": null,
    "latest_request_id": "bal_ELGT4hfikTTCJ",
    "latest_successful_request_id": "bal_ELGT4hfikTTCJ",
    "is_subscribable": false,
    "created_at": "2024-03-26T20:25:27.261Z",
    "updated_at": "2024-03-26T20:25:27.316Z"
  }
  ```
</RequestExample>


# Retrieve an Account
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/retrieve

GET /accounts/{acc_id}

Returns the Account associated with the ID.

## Path Parameters

<ParamList />

## Query Parameters

<ParamList />

## Returns

Returns the Account associated with the ID.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_Zc4F2aTLt8CBt \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const account = await method
    .accounts
    .retrieve('acc_Zc4F2aTLt8CBt');
  ```

  ```python Python theme={null}
  account = method
    .accounts
    .retrieve('acc_Zc4F2aTLt8CBt')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "acc_Zc4F2aTLt8CBt",
    "holder_id": "ent_y1a9e1fbnJ1f3",
    "status": "active",
    "type": "liability",
    "liability": {
      "mch_id": "mch_302086",
      "mask": "1580",
      "ownership": "primary",
      "fingerprint": "27d5c0ea28338619192076d150eb7b56c288f9a1",
      "type": "credit_card",
      "sub_type": "secured",
      "name": "Chase Sapphire Reserve Credit Card"
    },
    "latest_verification_session": "avf_tB9mpmew8FLit",
    "update": "upt_TXDTR7Amyz7Az",
    "balance": "bal_dGCCNWHMQYRay",
    "card_brand": "crd_eVMDNUPfrFk3e",
    "payment_instrument": "pmt_inst_pd788hPVhLT37",
    "products": ["balance", "card_brand", "update", "payment", "payment_instrument.card", "payment_instrument.network_token", "payment_instrument.inbound_achwire_payment"],
    "restricted_products": ["attribute", "sensitive"],
    "subscriptions": [],
    "available_subscriptions": ["update.snapshot", "update"],
    "restricted_subscriptions": ["transaction"],
    "error": null,
    "metadata": null,
    "created_at": "2024-04-12T18:57:57.857Z",
    "updated_at": "2024-04-12T18:57:58.430Z"
  }
  ```
</ResponseExample>


# Create a Sensitive
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/sensitive/create

POST /accounts/{acc_id}/sensitive

Creates a new Sensitive request to retrieve sensitive Account information.

Operation Type: <Tooltip>⚡ Synchronous</Tooltip>

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns a Sensitive object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/sensitive \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "expand": [
        "credit_card.number",
        "credit_card.exp_month",
        "credit_card.exp_year",
        "credit_card.cvv"
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .sensitive
    .create({
      expand: [
        'credit_card.number',
        'credit_card.exp_month',
        'credit_card.exp_year',
        'credit_card.cvv'
      ],
    });
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .sensitive
    .create({
      'expand': [
        'credit_card.number',
        'credit_card.exp_month',
        'credit_card.exp_year',
        'credit_card.cvv'
      ]
    })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "astv_9WBBA6TH7n7iX",
    "account_id": "acc_yVf3mkzbhz9tj",
    "type": "credit_card",
    "credit_card": {
      "number": "5555555555551580",
      "exp_month": "09",
      "exp_year": "2030",
      "cvv": "878",
      "billing_zip_code": null
    },
    "status": "completed",
    "error": null,
    "created_at": "2024-04-26T22:50:24.857Z",
    "updated_at": "2024-04-26T22:50:24.857Z"
  }
  ```
</ResponseExample>


# List all Sensitives
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/sensitive/list

GET /accounts/{acc_id}/sensitive

Retrieve a list of Sensitives for a specific Account.

## Path Parameters

<ParamList />

## Query Parameters

<ParamList />

## Returns

Returns a list of Sensitives.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/sensitive" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .sensitive
    .list();
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .sensitive
    .list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "astv_9WBBA6TH7n7iX",
        "account_id": "acc_yVf3mkzbhz9tj",
        "type": "credit_card",
        "credit_card": {
          "number": "5555555555551580",
          "exp_month": "09",
          "exp_year": "2030",
          "cvv": "878",
          "billing_zip_code": null
        },
        "status": "completed",
        "error": null,
        "created_at": "2024-04-26T22:50:24.857Z",
        "updated_at": "2024-04-26T22:50:24.857Z"
      },
      {...}
    ],
    "message": null
  }
  ```
</ResponseExample>


# The sensitive endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/sensitive/overview



The Sensitive endpoint returns underlying sensitive Account information (e.g. PAN, CVV, account number). This product is only available for Liabilities.

<Warning>The Sensitive endpoint is restricted to most teams, and requires PCI compliance to access. Contact your Method CSM for more information.</Warning>

## Sensitive Objects

<ParamList />

## Additional Properties based on type

<Tabs>
  <Tab title="Credit Card">
    <ParamList />
  </Tab>

  <Tab title="Auto Loan">
    <ParamList />
  </Tab>

  <Tab title="Mortgage">
    <ParamList />
  </Tab>

  <Tab title="Personal Loan">
    <ParamList />
  </Tab>

  <Tab title="Collection">
    <ParamList />
  </Tab>

  <Tab title="Student Loans">
    <ParamList />
  </Tab>

  <Tab title="Credit Builder">
    <ParamList />
  </Tab>

  <Tab title="BNPL">
    <ParamList />
  </Tab>

  <Tab title="Fintech">
    <ParamList />
  </Tab>

  <Tab title="Loan">
    <ParamList />
  </Tab>
</Tabs>

## Webhook Payload

The [Webhook](/2026-03-30/reference/webhooks/overview) payload will contain the following information:

```json theme={null}
{
  "id": "string",
  "type": "sensitive.create" | "sensitive.update",
  "path": "/accounts/<acc_id>/sensitive/<astv_id>",
}
```

<RequestExample>
  ```json Credit Card theme={null}
  {
    "id": "astv_9WBBA6TH7n7iX",
    "account_id": "acc_yVf3mkzbhz9tj",
    "type": "credit_card",
    "credit_card": {
      "number": "5555555555551580",
      "exp_month": "09",
      "exp_year": "2030",
      "cvv": "878",
      "billing_zip_code": null
    },
    "status": "completed",
    "error": null,
    "created_at": "2024-04-26T22:50:24.857Z",
    "updated_at": "2024-04-26T22:50:24.857Z"
  }
  ```

  ```json Auto Loan theme={null}
  {
    "id": "astv_BkdLEqDV4hyrR",
    "account_id": "acc_zcAbRXrEqVAFr",
    "type": "auto_loan",
    "auto_loan": { "number": "2719668732" },
    "status": "completed",
    "error": null,
    "created_at": "2024-04-26T22:50:24.724Z",
    "updated_at": "2024-04-26T22:50:24.724Z"
  }
  ```

  ```json Mortgage theme={null}
  {
    "id": "astv_tB9mpmew8FLit",
    "account_id": "acc_RGACQH7XdfYhC",
    "type": "mortgage",
    "mortgage": { "number": "5123564678934" },
    "status": "completed",
    "error": null,
    "created_at": "2024-04-26T22:50:24.724Z",
    "updated_at": "2024-04-26T22:50:24.724Z"
  }
  ```

  ```json Personal Loan theme={null}
  {
    "id": "astv_A8grUi7rzwi9g",
    "account_id": "acc_uHDiQGxiR8bqc",
    "type": "personal_loan",
    "personal_loan": { "number": "87234091345" },
    "status": "completed",
    "error": null,
    "created_at": "2024-04-26T22:50:24.724Z",
    "updated_at": "2024-04-26T22:50:24.724Z"
  }
  ```

  ```json Collection theme={null}
  {
    "id": "astv_N8qBq4Xi6hnMn",
    "account_id": "acc_KgNMfWHcBtycK",
    "type": "collection",
    "collection": { "number": "304576234" },
    "status": "completed",
    "error": null,
    "created_at": "2024-04-26T22:50:24.724Z",
    "updated_at": "2024-04-26T22:50:24.724Z"
  }
  ```

  ```json Student Loans theme={null}
  {
    "id": "astv_eL2oUu7v1qGw",
    "account_id": "acc_R5eT2YzGgQ4k",
    "type": "student_loans",
    "student_loans": { "number": "399745627183" },
    "status": "completed",
    "error": null,
    "created_at": "2024-04-26T22:50:24.724Z",
    "updated_at": "2024-04-26T22:50:24.724Z"
  }
  ```

  ```json Credit Builder theme={null}
  {
    "id": "astv_k2SqV9Tp0xFc",
    "account_id": "acc_f9zN3vxr05sL",
    "type": "credit_builder",
    "credit_builder": { "number": "593874621059" },
    "status": "completed",
    "error": null,
    "created_at": "2024-04-26T22:50:24.724Z",
    "updated_at": "2024-04-26T22:50:24.724Z"
  }
  ```

  ```json BNPL theme={null}
  {
    "id": "astv_x8RqU2sm0zPd",
    "account_id": "acc_w4Lk2mBn90tE",
    "type": "bnpl",
    "bnpl": { "number": "287364519087" },
    "status": "completed",
    "error": null,
    "created_at": "2024-04-26T22:50:24.724Z",
    "updated_at": "2024-04-26T22:50:24.724Z"
  }
  ```

  ```json Fintech theme={null}
  {
    "id": "astv_n3WqP7sl4vHy",
    "account_id": "acc_d6Pk1sQr84mX",
    "type": "fintech",
    "fintech": { "number": "540987312654" },
    "status": "completed",
    "error": null,
    "created_at": "2024-04-26T22:50:24.724Z",
    "updated_at": "2024-04-26T22:50:24.724Z"
  }
  ```

  ```json Loan theme={null}
  {
    "id": "astv_b4HqT6vn2cWp",
    "account_id": "acc_t7Vm4zQc51dP",
    "type": "loan",
    "loan": { "number": "170298364517" },
    "status": "completed",
    "error": null,
    "created_at": "2024-04-26T22:50:24.724Z",
    "updated_at": "2024-04-26T22:50:24.724Z"
  }
  ```
</RequestExample>


# Retrieve a Sensitive
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/sensitive/retrieve

GET /accounts/{acc_id}/sensitive/{astv_id}

Retrieve a Sensitive record for an Account.

## Path Parameters

<ParamList />

## Returns

Returns a Sensitive object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/sensitive/astv_9WBBA6TH7n7iX \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .sensitive
    .retrieve('astv_9WBBA6TH7n7iX');
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .sensitive
    .retrieve('astv_9WBBA6TH7n7iX')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "astv_9WBBA6TH7n7iX",
    "account_id": "acc_yVf3mkzbhz9tj",
    "type": "credit_card",
    "credit_card": {
      "number": "5555555555551580",
      "exp_month": "09",
      "exp_year": "2030",
      "cvv": "878",
      "billing_zip_code": null
    },
    "status": "completed",
    "error": null,
    "created_at": "2024-04-26T22:50:24.857Z",
    "updated_at": "2024-04-26T22:50:24.857Z"
  }
  ```
</ResponseExample>


# Create a Subscription
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/subscriptions/create

POST /accounts/{acc_id}/subscriptions

Enrolls an Account to a Subscription. Once
enrolled, the Subscription name and details will be present
on the response object.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns a Subscription object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "enroll": "update"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .subscriptions
    .create('update');
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .subscriptions
    .create('update')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
  "id": "sub_P8c4bjj6xajxF",
  "name": "update",
  "status": "active",
  "payload": null,
  "latest_request_id": "upt_TXDTR7Amyz7Az",
  "created_at": "2024-04-10T22:14:21.951Z",
  "updated_at": "2024-04-10T22:14:21.951Z"
  }
  ```
</ResponseExample>


# Delete a Subscription
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/subscriptions/delete

DELETE /accounts/{acc_id}/subscriptions/{sub_id}

Deleting a Subscription means to unsubscribe or unenroll an Entity from automatically
receiving new Product resources.

## Path Parameters

<ParamList />

## Returns

Returns a Subscription object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions/sub_xM4VcfRWcJP8D \
    -X DELETE \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .subscriptions
    .delete('sub_xM4VcfRWcJP8D');
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .subscriptions
    .delete('sub_xM4VcfRWcJP8D')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "sub_xM4VcfRWcJP8D",
    "name": "update",
    "status": "inactive",
    "payload": null,
    "latest_request_id": "upt_ELGT4hfikTTCJ",
    "created_at": "2024-03-27T19:05:34.417Z",
    "updated_at": "2024-03-27T19:05:34.417Z"
  }
  ```
</ResponseExample>


# List all Subscriptions
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/subscriptions/list

GET /accounts/{acc_id}/subscriptions

Returns a map of Subscription names to Subscription objects associated with an Account, or an empty object if none have been created.

## Path Parameters

<ParamList />

## Returns

Returns a map of Subscription names to Subscription objects.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .subscriptions
    .list();
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .subscriptions
    .list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "transactions": {
      "id": "sub_P8c4bjj6xajxF",
      "name": "transaction",
      "status": "active",
      "payload": null,
      "latest_request_id": "txn_GBCW694AEgfAh",
      "created_at": "2024-04-10T22:14:22.420Z",
      "updated_at": "2024-04-10T22:14:22.420Z"
    },
    "update": {
      "id": "sub_xM4VcfRWcJP8D",
      "name": "update",
      "status": "active",
      "payload": null,
      "latest_request_id": "upt_TXDTR7Amyz7Az",
      "created_at": "2024-04-10T22:14:21.951Z",
      "updated_at": "2024-04-10T22:14:21.951Z"
    },
    "update.snapshot": {
      "id": "sub_Hm8QxhIAtLP2k",
      "name": "update.snapshot",
      "status": "active",
      "payload": null,
      "latest_request_id": "upt_YXZTR7Bnxq3Cw",
      "created_at": "2024-04-10T22:14:20.832Z",
      "updated_at": "2024-04-10T22:14:20.832Z"
    },
    "card_brand": {
      "id": "sub_P8c4bjj6xajxF",
      "name": "card_brand",
      "status": "active",
      "payload": null,
      "latest_request_id": "crbd_GBCW694AEgfAh",
      "created_at": "2024-04-10T22:14:22.420Z",
      "updated_at": "2024-04-10T22:14:22.420Z"
    },
    "payment_instrument": {
      "id": "sub_P8c4bjj6xajxF",
      "name": "payment_instrument",
      "status": "active",
      "payload": null,
      "latest_request_id": "pmt_inst_GBCW694AEgfAh",
      "created_at": "2024-04-10T22:14:22.420Z",
      "updated_at": "2024-04-10T22:14:22.420Z"
    },
    "attribute": {
      "id": "sub_NgRfNvCbBkqWm",
      "name": "attribute",
      "status": "active",
      "payload": null,
      "latest_request_id": null,
      "created_at": "2026-04-09T17:02:47.910Z",
      "updated_at": "2026-04-09T17:02:47.910Z"
    }
  }
  ```
</ResponseExample>


# The subscriptions endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/subscriptions/overview



The Account Subscriptions endpoint controls the state of all Subscriptions for an Account.

Subscriptions are Products that can provide continuous updates via Webhooks. (e.g. Transaction Subscription provides real-time updates on a Credit Card's transactions)

<Info>Most subscriptions are accessible by default. However, some subscriptions have restricted access requiring team-by-team enablement and elevated account verification.</Info>

### Subscription Names

Subscriptions that an Account can be enrolled in:

| Name                               | Use-Case                                                                                                                              | Supported Types                         | Resource Doc                                                                       |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------- |
| `transaction`                      | Near real-time transaction notifications for Credit / Debit Card Accounts.                                                            | Credit Cards                            | [Transactions](/2026-03-30/reference/accounts/transactions/overview)               |
| `update`                           | Near real-time account update (balance, due dates, etc) from the Account's financial institution. Includes `update.snapshot` updates. | All liabilities                         | [Updates](/2026-03-30/reference/accounts/updates/overview)                         |
| `update.snapshot`                  | Monthly account snapshot update (balance, due dates, etc) from the credit bureau.                                                     | All liabilities                         | [Updates](/2026-03-30/reference/accounts/updates/overview)                         |
| `card_brand`                       | Near real-time information regarding credit card metadata (Product / Brand Name, Art, etc).                                           | Credit Cards                            | [Card Brands](/2026-03-30/reference/accounts/card-brands/overview)                 |
| `payment_instrument.card`          | Near real-time notifications for card credential updates (e.g., PAN or expiration changes).                                           | Credit Cards                            | [Payment Instruments](/2026-03-30/reference/accounts/payment-instruments/overview) |
| `payment_instrument.network_token` | Near real-time notifications for network token updates (e.g., token provisioned or status changed).                                   | Credit Cards                            | [Payment Instruments](/2026-03-30/reference/accounts/payment-instruments/overview) |
| `attribute`                        | Continuous monitoring of an Account's financial attributes (utilization, delinquency signals, usage patterns, etc).                   | Credit Cards, Personal Loans, Mortgages | [Account Attributes](/2026-03-30/reference/accounts/attributes/overview)           |

<Note>Update subscriptions will attempt to deliver both `direct` and `snapshot` updates when available.</Note>
<Warning>An account can either have an `update` or `update.snapshot` subscription at any given time, not both.</Warning>

### Enrollment requirements

Some subscriptions have prerequisites the Account must meet before it can be enrolled:

| Name                               | Requirements                                                                                                                                                                                                                                                                                                                                                         |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `transaction`                      | The Account must be active and the card on a supported network. Your team must have transaction configuration in place, and enrollment happens through Opal unless API enrollment is enabled for your team. Verification may be required: a `network` Account Verification Session when your team requires it, and whenever the full card number is not yet on file. |
| `card_brand`                       | The Account must be active and have at least one completed [Card Brand](/2026-03-30/reference/accounts/card-brands/overview) request, and a network token must be available for the card.                                                                                                                                                                            |
| `payment_instrument.card`          | The Account must be active and have a completed `network` [Account Verification Session](/2026-03-30/reference/accounts/verification-sessions/overview).                                                                                                                                                                                                             |
| `payment_instrument.network_token` | Same as `payment_instrument.card`, plus the Account must have a completed `network_token` [Payment Instrument](/2026-03-30/reference/accounts/payment-instruments/overview) and a network token must be available for the card.                                                                                                                                      |
| `update`                           | The Account must be an active, consented liability of a supported type with the Update product available to your team. Verification may be required when the liability's data is unavailable but recoverable.                                                                                                                                                        |
| `update.snapshot`                  | The Account must have the `data:retrieve` capability.                                                                                                                                                                                                                                                                                                                |

Enrollment requests that do not meet a requirement fail with an `INVALID_REQUEST` error whose sub-type describes the missing requirement (for example, `SUBSCRIPTION_RESTRICTED_MISSING_PRODUCT_REQUEST`). See [Subscription Errors](/2026-03-30/reference/errors/subscription-errors) for the full list.

## Subscriptions Objects

<ParamList />

## Webhook Payload

The [Webhook](/2026-03-30/reference/webhooks/overview) payload will contain the following information:

```json theme={null}
{
  "id": "string",
  "type": "subscription.create" | "subscription.update",
  "path": "/accounts/<acc_id>/subscriptions/<sub_id>",
}
```

<RequestExample>
  ```json THE SUBSCRIPTION OBJECT theme={null}
  {
    "transaction": {
      "id": "sub_P8c4bjj6xajxF",
      "name": "transaction",
      "status": "active",
      "payload": null,
      "latest_request_id": "txn_GBCW694AEgfAh",
      "created_at": "2024-04-10T22:14:21.951Z",
      "updated_at": "2024-04-10T22:14:21.951Z"
    },
    "update": {
      "id": "sub_P8c4bjj6xajxF",
      "name": "update",
      "status": "active",
      "payload": null,
      "latest_request_id": "upt_TXDTR7Amyz7Az",
      "created_at": "2024-04-10T22:14:21.951Z",
      "updated_at": "2024-04-10T22:14:21.951Z"
    }
  }
  ```
</RequestExample>


# Retrieve a Subscription
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/subscriptions/retrieve

GET /accounts/{acc_id}/subscriptions/{sub_id}

Retrieves a Subscription record for an Account.

## Path Parameters

<ParamList />

## Returns

Returns a Subscription object.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions/sub_P8c4bjj6xajxF" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts("acc_yVf3mkzbhz9tj")
    .subscriptions
    .retrieve("sub_P8c4bjj6xajxF");
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .subscriptions
    .retrieve('sub_P8c4bjj6xajxF')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "sub_P8c4bjj6xajxF",
    "name": "transaction",
    "status": "active",
    "payload": null,
    "latest_request_id": "txn_GBCW694AEgfAh",
    "created_at": "2024-04-10T22:14:21.951Z",
    "updated_at": "2024-04-10T22:14:21.951Z"
  }
  ```
</ResponseExample>


# List all Transactions
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/transactions/list

GET /accounts/{acc_id}/transactions

Retrieve a list of Transactions objects for a specific Account.

## Path Parameters

<ParamList />

## Query Parameters

<ParamList />

## Returns

Returns a list of Transactions for the account.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/transactions?from_date=2024-03-13&to_date=2024-03-15" \
    -X GET \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const transactions = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .transactions
    .list({
      from_date: '2024-03-13',
      to_date: '2024-03-15',
    });
  ```

  ```python Python theme={null}
  transactions = (method
    .accounts('acc_yVf3mkzbhz9tj')
    .transactions
    .list({
      'from_date': '2024-03-13',
      'to_date': '2024-03-15'
    }))
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "id": "txn_t73AdHRFYwhT9",
        "account_id": "acc_XtKTpHLGhD9Qn",
        "status": "posted",
        "descriptor": "SQ *BENNU COFFEE",
        "merchant": {
          "name": "Bennu Coffee",
          "logo": null
        },
        "merchant_category_code": "5441",
        "amount": 3764,
        "auth_amount": 3764,
        "currency_code": "USD",
        "transaction_amount": 3764,
        "transaction_auth_amount": 3764,
        "transaction_currency_code": "USD",
        "transacted_at": "2025-03-05T07:48:06.000Z",
        "posted_at": "2025-03-06T05:00:00.000Z",
        "voided_at": null,
        "original_txn_id": null,
        "created_at": "2025-03-24T03:54:29.283Z",
        "updated_at": "2025-03-24T04:04:39.200Z"
      }
    ]
  }
  ```
</ResponseExample>


# The transactions endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/transactions/overview



The Transactions endpoint retrieves near real-time transaction notifications for Credit Card and Debit Card Accounts directly from the card networks.

<Info>Subscription to Transactions is required before receiving transactional data for an account. Contact your Method CSM for access.</Info>

**The Transactions endpoint is available as a:**

| Type           | Use-Case                                                                  |
| -------------- | ------------------------------------------------------------------------- |
| `Subscription` | Near real-time transaction notifications for Credit / Debit Card Accounts |

## Transaction Objects

<ParamList />

## Webhook Payload

The [Webhook](/2026-03-30/reference/webhooks/overview) payload will contain the following information:

```json theme={null}
{
  "id": "string",
  "type": "transaction.create" | "transaction.update",
  "path": "/accounts/<acc_id>/transactions/<txn_id>",
}
```

<RequestExample>
  ```json THE TRANSACTION OBJECT theme={null}
  {
    "id": "txn_t73AdHRFYwhT9",
    "account_id": "acc_XtKTpHLGhD9Qn",
    "status": "posted",
    "descriptor": "SQ *BENNU COFFEE",
    "merchant": {
      "name": "Bennu Coffee",
      "logo": null
    },
    "merchant_category_code": "5441",
    "amount": 3764,
    "auth_amount": 3764,
    "currency_code": "USD",
    "transaction_amount": 3764,
    "transaction_auth_amount": 3764,
    "transaction_currency_code": "USD",
    "transacted_at": "2025-03-05T07:48:06.000Z",
    "posted_at": "2025-03-06T05:00:00.000Z",
    "voided_at": null,
    "original_txn_id": null,
    "created_at": "2025-03-24T03:54:29.283Z",
    "updated_at": "2025-03-24T04:04:39.200Z"
  }
  ```
</RequestExample>


# Retrieve a Transaction
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/transactions/retrieve

GET /accounts/{acc_id}/transactions/{txn_id}

Retrieve a Transaction object for an Account.

## Path Parameters

<ParamList />

## Returns

Returns a Transaction object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/transactions/txn_aRrDMAmEAtHti \
    -X GET \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .transactions
    .retrieve('txn_aRrDMAmEAtHti');
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .transactions
    .retrieve('txn_aRrDMAmEAtHti')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
    {
      "id": "txn_t73AdHRFYwhT9",
      "account_id": "acc_XtKTpHLGhD9Qn",
      "status": "posted",
      "descriptor": "SQ *BENNU COFFEE",
      "merchant": {
        "name": "Bennu Coffee",
        "logo": null
      },
      "merchant_category_code": "5441",
      "amount": 3764,
      "auth_amount": 3764,
      "currency_code": "USD",
      "transaction_amount": 3764,
      "transaction_auth_amount": 3764,
      "transaction_currency_code": "USD",
      "transacted_at": "2025-03-05T07:48:06.000Z",
      "posted_at": "2025-03-06T05:00:00.000Z",
      "voided_at": null,
      "original_txn_id": null,
      "created_at": "2025-03-24T03:54:29.283Z",
      "updated_at": "2025-03-24T04:04:39.200Z"
    }
  ```
</ResponseExample>


# Create an Update
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/updates/create

POST /accounts/{acc_id}/updates

Creates a new Update request to retrieve the Account's latest details (balance, due dates, apr, etc) in real-time

Operation Type: <Tooltip>⏳ Asynchronous</Tooltip> | [Webhook Payload](overview#webhook-payload).

<ParamList />

## Returns

Returns an Update object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_aEBDiLxiR8bqc/updates \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_aEBDiLxiR8bqc')
    .updates
    .create();
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_aEBDiLxiR8bqc')
    .updates
    .create()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "upt_NYV5kfjskTTCJ",
    "status": "pending",
    "account_id": "acc_aEBDiLxiR8bqc",
    "source": "direct",
    "type": "credit_card",
    "credit_card": null,
    "error": null,
    "created_at": "2024-03-20T04:43:21.434Z",
    "updated_at": "2024-03-20T04:43:21.655Z"
  }
  ```
</ResponseExample>


# List all Updates
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/updates/list

GET /accounts/{acc_id}/updates

Retrieve a list of Update objects for a specific Account.

## Path Parameters

<ParamList />

## Query Parameters

<ParamList />

## Returns

Returns a list of Updates.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .updates
    .list();
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .updates
    .list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "id": "upt_NYV5kfjskTTCJ",
        "status": "completed",
        "account_id": "acc_yVf3mkzbhz9tj",
        "source": "direct",
        "type": "credit_card",
        "data_as_of": "2024-03-20T04:43:21.434Z",
        "credit_card": {
          "available_credit": 120000,
          "balance": 80000,
          "closed_at": null,
          "credit_limit": 200000,
          "interest_rate_percentage_max": 23.5,
          "interest_rate_percentage_min": 12.0,
          "interest_rate_type": "variable",
          "last_payment_amount": 5000,
          "last_payment_date": "2024-04-05",
          "next_payment_due_date": "2024-05-01",
          "next_payment_minimum_amount": 4000,
          "opened_at": "2018-10-30",
          "sub_type": "flexible_spending",
          "usage_pattern": "transactor"
        },
        "error": null,
        "created_at": "2024-03-20T04:43:21.434Z",
        "updated_at": "2024-03-20T04:43:21.655Z"
      },
      {...}
    ]
  }
  ```
</ResponseExample>


# The updates endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/updates/overview



The Updates endpoint retrieves real-time account data including balance, due dates, and APRs directly from the
Account’s financial institution.

<Check>Method's real-time `direct` update coverage expands to 92% of all outstanding debt.</Check>

**The Updates endpoint is available as a:**

| Type           | Use-Case                                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `Product`      | On-Demand real-time account update (balance, due dates, etc) from the Account’s financial institution                                 |
| `Subscription` | Near real-time account update (balance, due dates, etc) from the Account’s financial institution. [Webhook Payload](#webhook-payload) |

## Update Objects

<ParamList />

<Note>
  Updates with `source: "snapshot"` include the fields listed for their liability type below and may also include
  additional delinquency fields derived from credit report tradeline data. Delinquency fields are not included on
  Updates with `source: "direct"`.
</Note>

## Snapshot Update Delinquency Fields

Snapshot Updates for supported liability types, including `credit_card`, `auto_loan`, `mortgage`, and `personal_loan`,
may include the following additional fields on the Update's liability object. For example, `delinquent_status` appears
as `credit_card.delinquent_status` on a credit card Update and `auto_loan.delinquent_status` on an auto loan Update.

<ParamList />

## Properties based on type

<Tabs>
  <Tab title="Credit Card">
    <ParamList />
  </Tab>

  <Tab title="Mortgage">
    <ParamList />
  </Tab>

  <Tab title="Auto Loan">
    <ParamList />
  </Tab>

  <Tab title="Personal Loan">
    <ParamList />
  </Tab>

  <Tab title="Student Loans">
    <ParamList />
  </Tab>

  <Tab title="BNPL">
    <ParamList />
  </Tab>

  <Tab title="Fintech">
    <ParamList />
  </Tab>
</Tabs>

## Webhook Payload

The [Webhook](/2026-03-30/reference/webhooks/overview) payload will contain the following information:

```json theme={null}
{
  "id": "string",
  "type": "update.create" | "update.update",
  "path": "/accounts/<acc_id>/updates/<upt_id>",
}
```

<RequestExample>
  ```json Credit Card theme={null}
  {
    "id": "upt_NYV5kfjskTTCJ",
    "status": "completed",
    "account_id": "acc_bFDiQGxiR8bqc",
    "source": "direct",
    "type": "credit_card",
    "credit_card": {
      "available_credit": 120000,
      "balance": 80000,
      "closed_at": null,
      "credit_limit": 200000,
      "interest_rate_percentage_max": 23.5,
      "interest_rate_percentage_min": 12.0,
      "interest_rate_type": "variable",
      "last_payment_amount": 5000,
      "last_payment_date": "2024-04-05",
      "next_payment_due_date": "2024-05-01",
      "next_payment_minimum_amount": 4000,
      "opened_at": "2018-10-30",
      "sub_type": "flexible_spending",
      "usage_pattern": "transactor"
    },
    "data_as_of": "2024-03-20T04:43:21.434Z",
    "error": null,
    "created_at": "2024-03-20T04:43:21.434Z",
    "updated_at": "2024-03-20T04:43:21.655Z"
  }
  ```

  ```json Auto Loan theme={null}
  {
    "id": "upt_ELGT4hfikTTCJ",
    "status": "completed",
    "account_id": "acc_aEBDiLxiR8bqc",
    "source": "direct",
    "type": "auto_loan",
    "auto_loan": {
      "balance": 1500000,
      "closed_at": null,
      "expected_payoff_date": "2029-04-15",
      "interest_rate_percentage": 3.5,
      "interest_rate_source": "financial_institution",
      "interest_rate_type": "fixed",
      "last_payment_amount": 35000,
      "last_payment_date": "2024-03-15",
      "next_payment_due_date": "2024-05-15",
      "next_payment_minimum_amount": 35000,
      "opened_at": "2019-04-15",
      "original_loan_amount": 2000000,
      "sub_type": "loan",
      "term_length": 120
    },
    "data_as_of": "2024-03-20T04:43:21.434Z",
    "error": null,
    "created_at": "2024-03-20T04:43:21.434Z",
    "updated_at": "2024-03-20T04:43:21.655Z"
  }
  ```

  ```json Mortgage theme={null}
  {
    "id": "upt_ZXJ9hfjskTTCJ",
    "status": "completed",
    "account_id": "acc_xDGiQGxiR8bqc",
    "source": "direct",
    "type": "mortgage",
    "mortgage": {
      "balance": 71250000,
      "closed_at": null,
      "expected_payoff_date": "2044-04-15",
      "interest_rate_percentage": 3.09,
      "interest_rate_source": "financial_institution",
      "interest_rate_type": "fixed",
      "last_payment_amount": 250000,
      "last_payment_date": "2024-03-15",
      "next_payment_due_date": "2024-05-15",
      "next_payment_minimum_amount": 250000,
      "opened_at": "2019-04-15",
      "original_loan_amount": 120000000,
      "sub_type": "heloc",
      "term_length": 300
    },
    "data_as_of": "2024-03-20T04:43:21.434Z",
    "error": null,
    "created_at": "2024-03-20T04:43:21.434Z",
    "updated_at": "2024-03-20T04:43:21.655Z"
  }
  ```

  ```json Personal Loan theme={null}
  {
    "id": "upt_HKJ9kfjskTTCJ",
    "status": "completed",
    "account_id": "acc_zFDiQGxiR8bqc",
    "source": "snapshot",
    "type": "personal_loan",
    "personal_loan": {
      "available_credit": 2700000,
      "balance": 2300000,
      "closed_at": null,
      "interest_rate_percentage": 1.95,
      "interest_rate_source": "financial_institution",
      "interest_rate_type": "fixed",
      "last_payment_amount": 150000,
      "last_payment_date": "2024-03-15",
      "next_payment_due_date": "2024-05-15",
      "next_payment_minimum_amount": 150000,
      "opened_at": "2019-04-15",
      "original_loan_amount": 5000000,
      "sub_type": "unsecured",
      "term_length": 48
    },
    "data_as_of": "2024-03-20T04:43:21.434Z",
    "error": null,
    "created_at": "2024-03-20T04:43:21.434Z",
    "updated_at": "2024-03-20T04:43:21.655Z"
  }
  ```

  ```json Student Loans theme={null}
  {
    "id": "upt_NJK9kfjskTTCJ",
    "status": "completed",
    "account_id": "acc_uHDiQGxiR8bqc",
    "source": "snapshot",
    "type": "student_loans",
    "student_loans": {
      "balance": 12000000,
      "closed_at": null,
      "disbursements": [
        {
          "sequence": 1,
          "balance": 326300,
          "last_payment_amount": 3500,
          "last_payment_date": "2024-04-01",
          "next_payment_due_date": "2024-05-01",
          "next_payment_minimum_amount": 3500,
          "disbursed_at": "2019-08-15",
          "interest_rate_percentage": 4.29,
          "interest_rate_type": "fixed",
          "original_loan_amount": 350000,
          "term_length": 120,
          "closed_at": null,
          "interest_rate_source": "method"
        },
        {...}
      ],
      "last_payment_amount": 250000,
      "last_payment_date": "2024-03-15",
      "next_payment_due_date": "2024-05-15",
      "next_payment_minimum_amount": 250000,
      "opened_at": "2019-08-15",
      "original_loan_amount": 12000000,
      "sub_type": "federal",
      "term_length": 120
    },
    "data_as_of": "2024-03-20T04:43:21.434Z",
    "error": null,
    "created_at": "2024-03-20T04:43:21.434Z",
    "updated_at": "2024-03-20T04:43:21.655Z"
  }
  ```

  ```json Fintech theme={null}
  {
    "id": "upt_NJK9kfjskTTCJ",
    "status": "completed",
    "account_id": "acc_uHDiQGxiR8bqc",
    "source": "snapshot",
    "type": "fintech",
    "fintech": {
      "balance": 100000,
      "opened_at": "2024-03-15",
      "closed_at": null
    },
    "error": null,
    "created_at": "2024-03-20T04:43:21.434Z",
    "updated_at": "2024-03-20T04:43:21.655Z"
  }
  ```

  ```json BNPL theme={null}
  {
    "id": "upt_NJK9kfjskTTCJ",
    "status": "completed",
    "account_id": "acc_uHDiQGxiR8bqc",
    "source": "snapshot",
    "type": "bnpl",
    "bnpl": {
      "balance": 100000,
      "opened_at": "2024-03-15",
      "closed_at": null
    },
    "error": null,
    "created_at": "2024-03-20T04:43:21.434Z",
    "updated_at": "2024-03-20T04:43:21.655Z"
  }
  ```
</RequestExample>


# Retrieve an Update
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/updates/retrieve

GET /accounts/{acc_id}/updates/{upt_id}

Retrieves an Update record for an Account.

## Path Parameters

<ParamList />

## Returns

Returns an Update object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_aEBDiLxiR8bqc/updates/upt_NYV5kfjskTTCJ \
    -X GET \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_aEBDiLxiR8bqc')
    .updates
    .retrieve('upt_NYV5kfjskTTCJ');
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_aEBDiLxiR8bqc')
    .updates
    .retrieve('upt_NYV5kfjskTTCJ')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "upt_NYV5kfjskTTCJ",
    "status": "completed",
    "account_id": "acc_aEBDiLxiR8bqc",
    "source": "direct",
    "type": "credit_card",
    "data_as_of": "2024-03-20T04:43:21.434Z",
    "credit_card": {
      "available_credit": 120000,
      "balance": 80000,
      "closed_at": null,
      "credit_limit": 200000,
      "interest_rate_percentage_max": 23.5,
      "interest_rate_percentage_min": 12.0,
      "interest_rate_type": "variable",
      "last_payment_amount": 5000,
      "last_payment_date": "2024-04-05",
      "next_payment_due_date": "2024-05-01",
      "next_payment_minimum_amount": 4000,
      "opened_at": "2018-10-30",
      "sub_type": "flexible_spending",
      "usage_pattern": "transactor"
    },
    "error": null,
    "created_at": "2024-03-20T04:43:21.434Z",
    "updated_at": "2024-03-20T04:43:21.655Z"
  }
  ```
</ResponseExample>


# Create a Verification
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/verification-sessions/create

POST /accounts/{acc_id}/verification_sessions

Creates an AccountVerificationSession of the provided type.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns an AccountVerificationSession object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/verification_sessions \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "micro_deposits"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .verificationSessions
    .create({
      type: 'micro_deposits'
    });
  ```

  ```python Python theme={null}
  response = method.accounts('acc_yVf3mkzbhz9tj')
    .verification_sessions
    .create({
      'type': 'micro_deposits'
    })
  ```
</RequestExample>

<ResponseExample>
  ```json Micro-deposits theme={null}
  {
    "id": "avf_bxDxWqdnRcrer",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "pending",
    "error": null,
    "type": "micro_deposits",
    "micro_deposits": {
      "amounts": []
    },
    "created_at": "2024-03-29T21:32:54.452Z",
    "updated_at": "2024-03-29T21:32:54.452Z"
  }
  ```

  ```json Plaid theme={null}
  {
    "id": "avf_wYjzrmP6QBzRd",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "pending",
    "error": null,
    "type": "plaid",
    "plaid": {
      "transactions": [],
      "balances": {}
    },
    "created_at": "2024-04-01T18:23:31.744Z",
    "updated_at": "2024-04-01T18:23:31.744Z"
  }
  ```

  ```json MX theme={null}
  {
    "id": "avf_eQCXK6b7L7c3W",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "pending",
    "error": null,
    "type": "mx",
    "mx": {
      "transactions": [],
      "account": {}
    },
    "created_at": "2024-04-01T18:24:27.003Z",
    "updated_at": "2024-04-01T18:24:27.003Z"
  }
  ```

  ```json Teller theme={null}
  {
    "id": "avf_tmhN3L67Qt9N6",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "pending",
    "error": null,
    "type": "teller",
    "teller": {
      "transactions": [],
      "balances": {}
    },
    "created_at": "2024-04-01T18:25:02.770Z",
    "updated_at": "2024-04-01T18:25:02.770Z"
  }
  ```

  ```json Standard theme={null}
  {
    "id": "avf_hCUj4GhnTcekJ",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "pending",
    "error": null,
    "type": "standard",
    "standard": {
      "number": null
    },
    "created_at": "2024-03-14T02:02:24.862Z",
    "updated_at": "2024-03-14T02:02:24.862Z"
  }
  ```

  ```json Instant theme={null}
  {
    "id": "avf_P3abzebLBXLja",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "pending",
    "error": null,
    "type": "instant",
    "instant": {
      "exp_year": null,
      "exp_month": null,
      "exp_check": null,
      "number": "xxxxxxxxxxxxxxxx"
    },
    "created_at": "2024-03-14T02:02:24.862Z",
    "updated_at": "2024-03-14T02:02:24.862Z"
  }
  ```

  ```json Pre-auth theme={null}
  {
    "id": "avf_DjkdemgTQfqRD",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "pending",
    "error": null,
    "type": "pre_auth",
    "pre_auth": {
      "exp_year": "xxxx",
      "exp_month": "xx",
      "exp_check": null,
      "cvv": null,
      "cvv_check": null,
      "billing_zip_code": "xxxxx",
      "billing_zip_code_check": null,
      "number": "xxxxxxxxxxxxxxxx",
      "pre_auth_check": null
    },
    "created_at": "2024-03-14T02:02:24.862Z",
    "updated_at": "2024-03-14T02:02:24.862Z"
  }
  ```
</ResponseExample>


# List all Verifications
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/verification-sessions/list

GET /accounts/{acc_id}/verification_sessions

Retrieve a list of AccountVerificationSessions for a specific Account.

## Path Parameters

<ParamList />

## Query Parameters

<ParamList />

## Returns

Returns a list of AccountVerificationSession.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/verification_sessions" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .verification_sessions
    .list();
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .verification_sessions
    .list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "avf_DjkdemgTQfqRD",
        "status": "pending",
        "error": null,
        "type": "pre_auth",
        "pre_auth": {
            "exp_year": "xxxx",
            "exp_month": "xx",
            "exp_check": null,
            "cvv": null,
            "cvv_check": null,
            "billing_zip_code": "xxxxx",
            "billing_zip_code_check": null,
            "number": "xxxxxxxxxxxxxxxx",
            "pre_auth_check": null
        },
        "created_at": "2024-03-14T02:02:24.862Z",
        "updated_at": "2024-03-14T02:02:24.862Z"
      },
      {...}
    ],
    "message": null
  }
  ```
</ResponseExample>


# The account verification sessions endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/verification-sessions/overview



The account verification manages required verification to enable products for ACH or Liability accounts.

For example, ACH Accounts require a verified AccountVerificationSession before they can be used as a source for Payments.

## AccountVerificationSession Objects

<ParamList />

## Verification Types

| Type                  | Description                                                                                                                                                                                                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `micro_deposits`      | To verify a checking or savings account, two small amounts between <strong>\$0.20 - \$0.99</strong> of money will be deposited into the ACH account, once received (within 1 - 3 business days) the account holder will then verify the amounts (in cents) that were deposited. |
| `plaid`               | The ACH Account is verified by providing [balance](https://plaid.com/products/balance/#balance-data) and [transaction](https://plaid.com/products/transactions) data from Plaid.                                                                                                |
| `teller`              | The ACH Account is verified by providing [balance](https://teller.io/docs/reference/account/balances#properties) and [transaction](https://teller.io/docs/reference/account/transactions#properties) data from Teller.                                                          |
| `mx`                  | The ACH Account is verified by providing [account](https://docs.mx.com/reference/platform-reference/reference/account-fields) and [transaction](https://docs.mx.com/reference/platform-reference/reference/transaction-fields) data from MX.                                    |
| `trusted_provisioner` | The ACH Account is auto verified based on whitelisted routing numbers for the team.                                                                                                                                                                                             |
| `auto_verify`         | The ACH account is verified automatically upon creation, if this configuration is enabled for the team.                                                                                                                                                                         |
| `standard`            | The Liability Account is verified in real-time by the issuer by providing the full account/card number.                                                                                                                                                                         |
| `pre_auth`            | The Credit Card Account is verified in real-time by the issuer and card networks by providing the full card number, expiration date, and cvv.                                                                                                                                   |
| `network`             | The Credit Card Account is verified in real-time by the issuer and card networks by providing the full card number, expiration date, and cvv.                                                                                                                                   |

## Webhook Payload

The [Webhook](/2026-03-30/reference/webhooks/overview) payload will contain the following information:

```json theme={null}
{
  "id": "string",
  "type": "account_verification_session.create" | "account_verification_session.update",
  "path": "/accounts/<acc_id>/verification_sessions/<avf_id>",
}
```

<RequestExample>
  ```json Pre-auth theme={null}
  {
    "id": "avf_DjkdemgTQfqRD",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "pending",
    "error": null,
    "type": "pre_auth",
    "pre_auth": {
      "exp_year": "xxxx",
      "exp_month": "xx",
      "exp_check": null,
      "cvv": null,
      "cvv_check": null,
      "billing_zip_code": "xxxxx",
      "billing_zip_code_check": null,
      "number": "xxxxxxxxxxxxxxxx",
      "pre_auth_check": null
    },
    "created_at": "2024-03-14T02:02:24.862Z",
    "updated_at": "2024-03-14T02:02:24.862Z"
  }
  ```

  ```json Network theme={null}
  {
    "id": "avf_DjkdemgTQfqRD",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "pending",
    "error": null,
    "type": "network",
    "network": {
      "exp_year": "xxxx",
      "exp_month": "xx",
      "exp_check": null,
      "cvv": null,
      "cvv_check": null,
      "billing_zip_code": "xxxxx",
      "billing_zip_code_check": null,
      "number": "xxxxxxxxxxxxxxxx",
      "network_check": null
    },
    "created_at": "2024-03-14T02:02:24.862Z",
    "updated_at": "2024-03-14T02:02:24.862Z"
  }
  ```

  ```json Standard theme={null}
  {
    "id": "avf_hCUj4GhnTcekJ",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "pending",
    "error": null,
    "type": "standard",
    "standard": {
      "number": null
    },
    "created_at": "2024-03-14T02:02:24.862Z",
    "updated_at": "2024-03-14T02:02:24.862Z"
  }
  ```

  ```json Micro-deposits theme={null}
  {
    "id": "avf_bxDxWqdnRcrer",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "pending",
    "error": null,
    "type": "micro_deposits",
    "micro_deposits": {
      "amounts": []
    },
    "created_at": "2024-03-29T21:32:54.452Z",
    "updated_at": "2024-03-29T21:32:54.452Z"
  }
  ```

  ```json Plaid theme={null}
  {
    "id": "avf_wYjzrmP6QBzRd",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "pending",
    "error": null,
    "type": "plaid",
    "plaid": {
      "transactions": [],
      "balances": {}
    },
    "created_at": "2024-04-01T18:23:31.744Z",
    "updated_at": "2024-04-01T18:23:31.744Z"
  }
  ```

  ```json MX theme={null}
  {
    "id": "avf_eQCXK6b7L7c3W",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "pending",
    "error": null,
    "type": "mx",
    "mx": {
      "transactions": [],
      "account": {}
    },
    "created_at": "2024-04-01T18:24:27.003Z",
    "updated_at": "2024-04-01T18:24:27.003Z"
  }
  ```

  ```json Teller theme={null}
  {
    "id": "avf_tmhN3L67Qt9N6",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "pending",
    "error": null,
    "type": "teller",
    "teller": {
      "transactions": [],
      "balances": {}
    },
    "created_at": "2024-04-01T18:25:02.770Z",
    "updated_at": "2024-04-01T18:25:02.770Z"
  }
  ```

  ```json Trusted Provisioner theme={null}
  {
    "id": "avf_zJUNmHXVGpWif",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "pending",
    "error": null,
    "type": "trusted_provisioner",
    "trusted_provisioner": {},
    "created_at": "2024-04-01T18:25:02.770Z",
    "updated_at": "2024-04-01T18:25:02.770Z"
  }
  ```

  ```json Auto Verify theme={null}
  {
    "id": "avf_zJUNmHXVGpWif",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "pending",
    "error": null,
    "type": "auto_verify",
    "auto_verify": {},
    "created_at": "2024-04-01T18:25:02.770Z",
    "updated_at": "2024-04-01T18:25:02.770Z"
  }
  ```
</RequestExample>


# Retrieve a Verification
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/verification-sessions/retrieve

GET /accounts/{acc_id}/verification_sessions/{avf_id}

Retrieve an AccountVerificationSession object by its ID.

## Path Parameters

<ParamList />

## Returns

Returns an AccountVerificationSession object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/verification_sessions/avf_9WBBA6TH7n7iX \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .verificationSessions
    .retrieve('avf_9WBBA6TH7n7iX');
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .verification_sessions
    .retrieve('avf_9WBBA6TH7n7iX')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "avf_DjkdemgTQfqRD",
    "status": "pending",
    "error": null,
    "type": "pre_auth",
    "pre_auth": {
        "exp_year": "xxxx",
        "exp_month": "xx",
        "exp_check": null,
        "cvv": null,
        "cvv_check": null,
        "billing_zip_code": "xxxxx",
        "billing_zip_code_check": null,
        "number": "xxxxxxxxxxxxxxxx",
        "pre_auth_check": null
    },
    "created_at": "2024-03-14T02:02:24.862Z",
    "updated_at": "2024-03-14T02:02:24.862Z"
  }
  ```
</ResponseExample>


# Update a Micro-deposits Verification
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/verification-sessions/update-microdeposits

PUT /accounts/{acc_id}/verification_sessions/{avf_id}

Updates an existing AccountVerificationSession object of type `micro_deposits`.

<Note>
  Amounts should be attempted once the AccountVerificationSession status
  is <code>in\_progress</code>, indicating that the micro-deposit transactions
  have been sent.
</Note>

## Path Parameters

<ParamList />

## Body

<ParamList />

<Note>
  When verifying an ACH account in the development environment,
  you can use the <a href="/2026-03-30/reference/simulations/verification-sessions/get-microdeposit-amounts">Retrieve Micro-deposit Amounts</a> simulation
  endpoint to get the <code>micro\_deposits.amounts</code>.
</Note>

## Returns

Returns an AccountVerificationSession object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/verification_sessions/avf_yBQQNKmjRBTqF \
    -X PUT \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "micro_deposits": {
        "amounts": [10, 34]
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .verificationSessions
    .update('avf_yBQQNKmjRBTqF', {
      micro_deposits: {
        amounts: [10, 34]
      }
    });
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .verification_sessions
    .update('avf_yBQQNKmjRBTqF', {
      'micro_deposits': {
        'amounts': [10, 34]
      }
    })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "avf_yBQQNKmjRBTqF",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "verified",
    "error": null,
    "type": "micro_deposits",
    "micro_deposits": {
        "amounts": [
            10,
            34
        ]
    },
    "created_at": "2024-03-14T02:02:24.862Z",
    "updated_at": "2024-03-14T02:02:24.862Z"
  }
  ```
</ResponseExample>


# Update an MX Verification
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/verification-sessions/update-mx

PUT /accounts/{acc_id}/verification_sessions/{avf_id}

Updates an existing AccountVerificationSession object of type `mx`.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns an AccountVerificationSession object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/verification_sessions/avf_DjkdemgTQfqRD \
    -X PUT \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "mx": {
        "account" : {
          "institution_code": "chase",
          "guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
          "account_number": null,
          "apr": null,
          "apy": null,
          "available_balance": 1000.23,
          "available_credit": null,
          "balance": 1000.23,
          "cash_balance": 1000.32,
          "cash_surrender_value": 1000.23,
          "created_at": "2016-10-13T17:57:37+00:00",
          ...
        },
        "transactions": [
          ...
        ]
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .verificationSessions
    .update('avf_DjkdemgTQfqRD', {
      mx: {
        account: {
          institution_code: 'chase',
          guid: 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
          account_number: null,
          apr: null,
          apy: null,
          available_balance: 1000.23,
          available_credit: null,
          balance: 1000.23,
          cash_balance: 1000.32,
          cash_surrender_value: 1000.23,
          created_at: '2016-10-13T17:57:37+00:00',
          ...
        },
        transactions: [
          ...
        ]
      }
    });
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .verification_sessions
    .update('avf_DjkdemgTQfqRD', {
      'mx': {
        'account': {
          'institution_code': 'chase',
          'guid': 'ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1',
          'account_number': None,
          'apr': None,
          'apy': None,
          'available_balance': 1000.23,
          'available_credit': None,
          'balance': 1000.23,
          'cash_balance': 1000.32,
          'cash_surrender_value': 1000.23,
          'created_at': '2016-10-13T17:57:37+00:00',
          ...
        },
        'transactions': [
          ...
        ]
      }
    })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "avf_DjkdemgTQfqRD",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "verified",
    "error": null,
    "type": "mx",
    "mx": {
      "account": {
        "institution_code": "chase",
        "guid": "ACT-06d7f44b-caae-0f6e-1384-01f52e75dcb1",
        "account_number": null,
        "apr": null,
        "apy": null,
        "available_balance": 1000.23,
        "available_credit": null,
        "balance": 1000.23,
        "cash_balance": 1000.32,
        "cash_surrender_value": 1000.23,
        "created_at": "2016-10-13T17:57:37+00:00",
        ...
      },
      "transactions": [ ... ]
    },
    "created_at": "2024-03-14T02:02:24.862Z",
    "updated_at": "2024-03-14T02:02:24.862Z"
  }
  ```
</ResponseExample>


# Update a Network Verification
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/verification-sessions/update-network

PUT /accounts/{acc_id}/verification_sessions/{avf_id}

Updates an existing AccountVerificationSession object of type `network`.

<Note>
  Only fields for which the value is <code>null</code> or the
  associated <code>\*\_check</code> value is <code>fail</code> should be provided
  in the update request.
</Note>

<Warning>The Network Verification type is restricted to most teams, and requires PCI compliance to access.
Contact your Method CSM for more information.</Warning>

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns an AccountVerificationSession object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/verification_sessions/avf_DjkdemgTQfqRD \
    -X PUT \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "network": {
        "cvv": "031"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .verificationSessions
    .update('avf_DjkdemgTQfqRD', {
      network: {
        cvv: '031'
      }
    });
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .verification_sessions
    .update('avf_DjkdemgTQfqRD', {
      'network': {
        'cvv': '031'
      }
    })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "avf_DjkdemgTQfqRD",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "verified",
    "error": null,
    "type": "network",
    "network": {
      "exp_year": "xxxx",
      "exp_month": "xx",
      "exp_check": "pass",
      "cvv": "xxx",
      "cvv_check": "pass",
      "billing_zip_code": "xxxxx",
      "billing_zip_code_check": "pass",
      "number": "xxxxxxxxxxxxxxxx",
      "network_check": "pass"
    },
    "created_at": "2024-03-14T02:02:24.862Z",
    "updated_at": "2024-03-14T02:02:24.862Z"
  }
  ```
</ResponseExample>


# Update a Plaid Verification
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/verification-sessions/update-plaid

PUT /accounts/{acc_id}/verification_sessions/{avf_id}

Updates an existing AccountVerificationSession object of type `plaid`.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns an AccountVerificationSession object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/verification_sessions/avf_DjkdemgTQfqRD \
    -X PUT \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "plaid": {
        "balances" : {
          "available" : 100,
          "current" : 110,
          "iso_currency_code" : "USD",
          "limit" : null,
          "unofficial_currency_code" : null
        },
        "transactions": [
          ...
        ]
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .verificationSessions
    .update('avf_DjkdemgTQfqRD', {
      plaid: {
        balances: {
          available: 100,
          current: 110,
          iso_currency_code: 'USD',
          limit: null,
          unofficial_currency_code: null
        },
        transactions: [
          ...
        ]
      }
    });
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .verification_sessions
    .update('avf_DjkdemgTQfqRD', {
      'plaid': {
        'balances': {
          'available': 100,
          'current': 110,
          'iso_currency_code': 'USD',
          'limit': None,
          'unofficial_currency_code': None
        },
        'transactions': [
          ...
        ]
      }
    })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "avf_DjkdemgTQfqRD",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "verified",
    "error": null,
    "type": "plaid",
    "plaid": {
      "balances": {
        "available": 100,
        "current": 110,
        "iso_currency_code": "USD",
        "limit": null,
        "unofficial_currency_code": null,
      },
      "transactions": [ ... ]
    },
    "created_at": "2024-03-14T02:02:24.862Z",
    "updated_at": "2024-03-14T02:02:24.862Z"
  }
  ```
</ResponseExample>


# Update a Pre-auth Verification
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/verification-sessions/update-preauth

PUT /accounts/{acc_id}/verification_sessions/{avf_id}

Updates an existing AccountVerificationSession object of type `pre_auth`.

<Note>
  Only fields for which the value is <code>null</code> or the
  associated <code>\*\_check</code> value is <code>fail</code> should be provided
  in the update request.
</Note>

<Warning>The Pre-Auth Verification type is restricted to most teams, and requires PCI compliance to access.
Contact your Method CSM for more information.</Warning>

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns an AccountVerificationSession object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/verification_sessions/avf_DjkdemgTQfqRD \
    -X PUT \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "pre_auth": {
        "cvv": "031"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .verificationSessions
    .update('avf_DjkdemgTQfqRD', {
      pre_auth: {
        cvv: '031'
      }
    });
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .verification_sessions
    .update('avf_DjkdemgTQfqRD', {
      'pre_auth': {
        'cvv': '031'
      }
    })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "avf_DjkdemgTQfqRD",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "verified",
    "error": null,
    "type": "pre_auth",
    "pre_auth": {
      "exp_year": "xxxx",
      "exp_month": "xx",
      "exp_check": "pass",
      "cvv": "xxx",
      "cvv_check": "pass",
      "billing_zip_code": "xxxxx",
      "billing_zip_code_check": "pass",
      "number": "xxxxxxxxxxxxxxxx",
      "pre_auth_check": "pass"
    },
    "created_at": "2024-03-14T02:02:24.862Z",
    "updated_at": "2024-03-14T02:02:24.862Z"
  }
  ```
</ResponseExample>


# Update a Standard Verification
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/verification-sessions/update-standard

PUT /accounts/{acc_id}/verification_sessions/{avf_id}

Updates an existing AccountVerificationSession object of type `standard`.

<Warning>The Standard Verification type is restricted to most teams, and requires PCI compliance to access.
Contact your Method CSM for more information.</Warning>

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns an AccountVerificationSession object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/verification_sessions/avf_DjkdemgTQfqRD \
    -X PUT \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "standard": {
        "number": "4111111111111111"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .verificationSessions
    .update('avf_DjkdemgTQfqRD', {
      standard: {
        number: '4111111111111111',
      }
    });
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .verification_sessions
    .update('avf_DjkdemgTQfqRD', {
      'standard': {
        'number': '4111111111111111',
      }
    })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "avf_DjkdemgTQfqRD",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "verified",
    "error": null,
    "type": "standard",
    "standard": {
      "number": "xxxxxxxxxxxxxxxx"
    },
    "created_at": "2024-03-14T02:02:24.862Z",
    "updated_at": "2024-03-14T02:02:24.862Z"
  }
  ```
</ResponseExample>


# Update a Teller Verification
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/verification-sessions/update-teller

PUT /accounts/{acc_id}/verification_sessions/{avf_id}

Updates an existing AccountVerificationSession object of type `teller`.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns an AccountVerificationSession object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/verification_sessions/avf_DjkdemgTQfqRD \
    -X PUT \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "teller": {
        "balances" : {
          "account_id": "acc_ns9gkibeia6ad0rr6s00q",
          "available": "93011.13",
          "ledger": "93011.13",
          "links": {
            "account": "https://reference.teller.io/accounts/acc_ns9gkibeia6ad0rr6s00q",
            "self": "https://reference.teller.io/accounts/acc_ns9gkibeia6ad0rr6s00q/balances"
          }
        },
        "transactions": [
          ...
        ]
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .verificationSessions
    .update('avf_DjkdemgTQfqRD', {
      teller: {
        balances: {
          account_id: 'acc_ns9gkibeia6ad0rr6s00q',
          available: '93011.13',
          ledger: '93011.13',
          links: {
            account: 'https://reference.teller.io/accounts/acc_ns9gkibeia6ad0rr6s00q',
            self: 'https://reference.teller.io/accounts/acc_ns9gkibeia6ad0rr6s00q/balances'
          }
        },
        transactions: [
          ...
        ]
      }
    });
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .verification_sessions
    .update('avf_DjkdemgTQfqRD', {
      'teller': {
        'balances': {
          'account_id': 'acc_ns9gkibeia6ad0rr6s00q',
          'available': '93011.13',
          'ledger': '93011.13',
          'links': {
            'account': 'https://reference.teller.io/accounts/acc_ns9gkibeia6ad0rr6s00q',
            'self': 'https://reference.teller.io/accounts/acc_ns9gkibeia6ad0rr6s00q/balances'
          }
        },
        'transactions': [
          ...
        ]
      }
    })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "avf_DjkdemgTQfqRD",
    "account_id": "acc_yVf3mkzbhz9tj",
    "status": "verified",
    "error": null,
    "type": "teller",
    "teller": {
      "balances": {
        "account_id": "acc_ns9gkibeia6ad0rr6s00q",
        "available": "93011.13",
        "ledger": "93011.13",
        "links": {
          "account": "https://reference.teller.io/accounts/acc_ns9gkibeia6ad0rr6s00q",
          "self": "https://reference.teller.io/accounts/acc_ns9gkibeia6ad0rr6s00q/balances"
        }
      },
      "transactions": [ ... ]
    },
    "created_at": "2024-03-14T02:02:24.862Z",
    "updated_at": "2024-03-14T02:02:24.862Z"
  }
  ```
</ResponseExample>


# Create Attributes
Source: https://docs.methodfi.com/2026-03-30/reference/entities/attributes/create

POST /entities/{ent_id}/attributes

Creates a new Attribute request to compute the Entity's attributes.
All available attributes are computed automatically.

Operation Type: <Tooltip>🔄 Asynchronous</Tooltip>

## Path Parameters

<ParamList />

## Returns

Returns an Entity's Attributes object with `status: "in_progress"` and `attributes: null`.
Once processing completes, the status will update to `completed` and the `attributes` object
will be populated. Subscribe to [webhooks](/2026-03-30/reference/webhooks/overview) or poll the
[retrieve endpoint](/2026-03-30/reference/entities/attributes/retrieve) to get the final result.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/attributes \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const attribute = await method
    .entities('ent_au22b1fbFJbp8')
    .attributes
    .create();
  ```

  ```python Python theme={null}
  attribute = method
    .entities('ent_au22b1fbFJbp8')
    .attributes
    .create()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "attr_dADraNgLBrhgL",
    "entity_id": "ent_EQ3FCTzDUmmCb",
    "status": "in_progress",
    "attributes": null,
    "error": null,
    "created_at": "2026-04-09T17:02:47.910Z",
    "updated_at": "2026-04-09T17:02:47.910Z"
  }
  ```
</ResponseExample>


# List all Attributes
Source: https://docs.methodfi.com/2026-03-30/reference/entities/attributes/list

GET /entities/{ent_id}/attributes

Retrieve a list of Attributes for a specific Entity.

## Path Parameters

<ParamList />

## Query Parameters

<ParamList />

## Returns

Returns a list of Attributes.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/entities/ent_yVf3mkzbhz9tj/attributes" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities('ent_yVf3mkzbhz9tj')
    .attributes
    .list();
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_yVf3mkzbhz9tj')
    .attributes
    .list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "attr_dADraNgLBrhgL",
        "entity_id": "ent_EQ3FCTzDUmmCb",
        "status": "completed",
        "attributes": {
          "revolving_credit_card_balance_total": {
            "value": 968400,
            "error": null,
            "metadata": null
          },
          "credit_limit_total": {
            "value": 8100000,
            "error": null,
            "metadata": null
          },
          "credit_card_utilization": {
            "value": 11.96,
            "error": null,
            "metadata": null
          },
          "overall_utilization": {
            "value": 70.5,
            "error": null,
            "metadata": null
          }
        },
        "error": null,
        "created_at": "2026-04-09T17:02:47.910Z",
        "updated_at": "2026-04-09T17:04:35.220Z"
      },
      {...}
    ],
    "message": null
  }
  ```
</ResponseExample>


# The entity attributes endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/entities/attributes/overview



The Entity Attributes endpoint provides aggregated financial attributes for an Entity,
computed from the Entity's connected accounts. Attributes are organized by category
(credit card, personal loan, mortgage, HELOC, overall, delinquency, Direct Pay,
installment, and other) and cover utilization, balances, trends, delinquency signals,
and Method Direct Pay activity.

**The Entity Attributes endpoint is available as a:**

| Type           | Use-Case                                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `Product`      | On-Demand view of an Entity's financial attributes.                                                                                   |
| `Subscription` | Comprehensive view of an Entity's attributes and continuous near real-time updates on attributes. [Webhook Payload](#webhook-payload) |

## Attribute Objects

<ParamList />

## Available Attributes

Attributes are grouped by **category** (the kind of liability they describe) and tagged with the **bundles** they belong to. See [Available Bundles](#available-bundles) for the curated groupings you can subscribe to with a single name.

### Revolving Credit Card

| Attribute                                     | Value Type | Bundles                                           | Description                                                                                                                                                  |
| --------------------------------------------- | ---------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `revolving_credit_card_balance_total`         | number     | [Portfolio Intelligence](#portfolio-intelligence) | Total revolving credit card balance across all accounts, in cents.                                                                                           |
| `credit_limit_total`                          | number     | [Portfolio Intelligence](#portfolio-intelligence) | Total credit limit across all credit card accounts, in cents.                                                                                                |
| `available_credit_limit_total`                | number     | [Portfolio Intelligence](#portfolio-intelligence) | Total available credit across credit card accounts, in cents. Uses source-backed available credit when present and falls back to credit limit minus balance. |
| `credit_card_utilization`                     | number     | [Portfolio Intelligence](#portfolio-intelligence) | Credit card utilization percentage across all accounts.                                                                                                      |
| `weighted_average_apr_credit_card`            | number     | [Portfolio Intelligence](#portfolio-intelligence) | Weighted average APR across all credit card accounts.                                                                                                        |
| `usage_pattern`                               | string     | [Portfolio Intelligence](#portfolio-intelligence) | Overall credit card usage pattern across all accounts.                                                                                                       |
| `next_payment_minimum_total_credit_cards`     | number     | [Portfolio Intelligence](#portfolio-intelligence) | Total minimum payment due across all credit card accounts, in cents.                                                                                         |
| `payment_to_minimum_ratio_avg_credit_cards`   | number     | [Portfolio Intelligence](#portfolio-intelligence) | Average ratio of actual payments to minimum payments across credit card accounts.                                                                            |
| `revolving_credit_card_balance_change_30d`    | number     | [Portfolio Intelligence](#portfolio-intelligence) | Change in total revolving credit card balance over the last 30 days, in cents.                                                                               |
| `revolving_credit_card_balance_change_60d`    | number     | [Portfolio Intelligence](#portfolio-intelligence) | Change in total revolving credit card balance over the last 60 days, in cents.                                                                               |
| `revolving_credit_card_balance_change_90d`    | number     | [Portfolio Intelligence](#portfolio-intelligence) | Change in total revolving credit card balance over the last 90 days, in cents.                                                                               |
| `revolving_credit_card_utilization_trend_30d` | string     | [Portfolio Intelligence](#portfolio-intelligence) | Direction of credit card utilization change over the last 30 days.                                                                                           |
| `revolving_credit_card_utilization_trend_90d` | string     | [Portfolio Intelligence](#portfolio-intelligence) | Direction of credit card utilization change over the last 90 days.                                                                                           |
| `revolving_credit_card_utilization_delta_30d` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Percentage point change in credit card utilization over the last 30 days.                                                                                    |
| `revolving_credit_card_utilization_delta_60d` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Percentage point change in credit card utilization over the last 60 days.                                                                                    |
| `revolving_credit_card_utilization_delta_90d` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Percentage point change in credit card utilization over the last 90 days.                                                                                    |
| `delinquency_flag_credit_cards`               | string     | [Portfolio Intelligence](#portfolio-intelligence) | Worst credit card delinquency status. Possible values are `on_time` and `overdue`.                                                                           |

### Personal Loan

| Attribute                                     | Value Type | Bundles                                           | Description                                                                        |
| --------------------------------------------- | ---------- | ------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `personal_loan_balance_total`                 | number     | [Portfolio Intelligence](#portfolio-intelligence) | Total personal loan balance across all accounts, in cents.                         |
| `personal_loan_amount_total`                  | number     | [Portfolio Intelligence](#portfolio-intelligence) | Total original loan amount across all personal loan accounts, in cents.            |
| `available_loan_amount_personal_loans`        | number     | [Portfolio Intelligence](#portfolio-intelligence) | Total source-backed available loan amount across personal loan accounts, in cents. |
| `personal_loan_monthly_installments_estimate` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Estimated total monthly installment payments for personal loans, in cents.         |
| `personal_loan_utilization`                   | number     | [Portfolio Intelligence](#portfolio-intelligence) | Utilization percentage across all personal loan accounts.                          |
| `weighted_average_apr_personal_loan`          | number     | [Portfolio Intelligence](#portfolio-intelligence) | Weighted average APR across all personal loan accounts.                            |
| `personal_loan_balance_change_30d`            | number     | [Portfolio Intelligence](#portfolio-intelligence) | Change in total personal loan balance over the last 30 days, in cents.             |
| `personal_loan_balance_change_60d`            | number     | [Portfolio Intelligence](#portfolio-intelligence) | Change in total personal loan balance over the last 60 days, in cents.             |
| `personal_loan_balance_change_90d`            | number     | [Portfolio Intelligence](#portfolio-intelligence) | Change in total personal loan balance over the last 90 days, in cents.             |
| `personal_loan_utilization_trend_30d`         | string     | [Portfolio Intelligence](#portfolio-intelligence) | Direction of personal loan utilization change over the last 30 days.               |
| `personal_loan_utilization_trend_90d`         | string     | [Portfolio Intelligence](#portfolio-intelligence) | Direction of personal loan utilization change over the last 90 days.               |
| `personal_loan_utilization_delta_30d`         | number     | [Portfolio Intelligence](#portfolio-intelligence) | Percentage point change in personal loan utilization over the last 30 days.        |
| `personal_loan_utilization_delta_60d`         | number     | [Portfolio Intelligence](#portfolio-intelligence) | Percentage point change in personal loan utilization over the last 60 days.        |
| `personal_loan_utilization_delta_90d`         | number     | [Portfolio Intelligence](#portfolio-intelligence) | Percentage point change in personal loan utilization over the last 90 days.        |

### Mortgage

| Attribute                        | Value Type | Bundles                                           | Description                                                            |
| -------------------------------- | ---------- | ------------------------------------------------- | ---------------------------------------------------------------------- |
| `mortgage_balance_total`         | number     | [Portfolio Intelligence](#portfolio-intelligence) | Total mortgage balance across all accounts, in cents.                  |
| `mortgage_loan_amount_total`     | number     | [Portfolio Intelligence](#portfolio-intelligence) | Total original loan amount across all mortgage accounts, in cents.     |
| `weighted_average_apr_mortgage`  | number     | [Portfolio Intelligence](#portfolio-intelligence) | Weighted average APR across all mortgage accounts.                     |
| `mortgage_balance_change_30d`    | number     | [Portfolio Intelligence](#portfolio-intelligence) | Change in total mortgage balance over the last 30 days, in cents.      |
| `mortgage_balance_change_60d`    | number     | [Portfolio Intelligence](#portfolio-intelligence) | Change in total mortgage balance over the last 60 days, in cents.      |
| `mortgage_balance_change_90d`    | number     | [Portfolio Intelligence](#portfolio-intelligence) | Change in total mortgage balance over the last 90 days, in cents.      |
| `mortgage_utilization_trend_30d` | string     | [Portfolio Intelligence](#portfolio-intelligence) | Direction of mortgage utilization change over the last 30 days.        |
| `mortgage_utilization_trend_90d` | string     | [Portfolio Intelligence](#portfolio-intelligence) | Direction of mortgage utilization change over the last 90 days.        |
| `mortgage_utilization_delta_30d` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Percentage point change in mortgage utilization over the last 30 days. |
| `mortgage_utilization_delta_60d` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Percentage point change in mortgage utilization over the last 60 days. |
| `mortgage_utilization_delta_90d` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Percentage point change in mortgage utilization over the last 90 days. |

### HELOC

| Attribute             | Value Type | Bundles                                           | Description                                                                                                            |
| --------------------- | ---------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `heloc_balance_total` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Total balance across HELOC accounts, in cents. HELOCs are identified by mortgage or personal loan `sub_type: "heloc"`. |
| `heloc_utilization`   | number     | [Portfolio Intelligence](#portfolio-intelligence) | Utilization percentage across HELOC accounts. Uses balance divided by original loan amount.                            |

### Overall

| Attribute                       | Value Type | Bundles                                           | Description                                                                                                                                                                                 |
| ------------------------------- | ---------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `overall_loan_amount_total`     | number     | [Portfolio Intelligence](#portfolio-intelligence) | Total original loan amount across all account types, in cents.                                                                                                                              |
| `available_credit_total`        | number     | [Portfolio Intelligence](#portfolio-intelligence) | Total reusable credit available to use now, in cents. Includes credit cards, HELOCs, and personal loan lines of credit. Ordinary mortgages and closed-end personal loans do not contribute. |
| `overall_utilization`           | number     | [Portfolio Intelligence](#portfolio-intelligence) | Overall utilization percentage across all account types.                                                                                                                                    |
| `overall_utilization_trend_30d` | string     | [Portfolio Intelligence](#portfolio-intelligence) | Direction of overall utilization change over the last 30 days.                                                                                                                              |
| `overall_utilization_trend_90d` | string     | [Portfolio Intelligence](#portfolio-intelligence) | Direction of overall utilization change over the last 90 days.                                                                                                                              |
| `overall_utilization_delta_30d` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Percentage point change in overall utilization over the last 30 days.                                                                                                                       |
| `overall_utilization_delta_60d` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Percentage point change in overall utilization over the last 60 days.                                                                                                                       |
| `overall_utilization_delta_90d` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Percentage point change in overall utilization over the last 90 days.                                                                                                                       |

### Delinquency

| Attribute                         | Value Type | Bundles                                           | Description                                                                                                                                                                                                                               |
| --------------------------------- | ---------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `any_delinquent_flag`             | boolean    | [Portfolio Intelligence](#portfolio-intelligence) | Whether any account has a usable delinquency signal. Returns `false` only when at least one account has usable non-delinquent data.                                                                                                       |
| `serious_delinquent_flag`         | boolean    | [Portfolio Intelligence](#portfolio-intelligence) | Whether any account has a serious delinquency signal, such as major delinquency, charge-off, or collection.                                                                                                                               |
| `delinquency_recently_cured_flag` | boolean    | [Portfolio Intelligence](#portfolio-intelligence) | Whether bureau data indicates delinquency while a recent sync update indicates the account is on time.                                                                                                                                    |
| `delinquency_worst_dpd_bucket`    | string     | [Portfolio Intelligence](#portfolio-intelligence) | Worst delinquent period bucket across accounts. Possible values are `30_dpd`, `60_dpd`, `90_dpd`, and `120_plus_dpd`.                                                                                                                     |
| `delinquency_accounts_count`      | number     | [Portfolio Intelligence](#portfolio-intelligence) | Count of accounts with a usable delinquent signal.                                                                                                                                                                                        |
| `delinquent_balance_total`        | number     | [Portfolio Intelligence](#portfolio-intelligence) | Total past-due or delinquent amount across delinquent accounts, in cents. May include `metadata.partial: true` when only part of the delinquent population has amount data.                                                               |
| `delinquency_progression_flag`    | boolean    | [Portfolio Intelligence](#portfolio-intelligence) | Whether any account's delinquent period worsened compared with a previous non-null period at least 7 days older, within a 90-day lookback.                                                                                                |
| `delinquent_outcome`              | string     | [Portfolio Intelligence](#portfolio-intelligence) | Highest-severity delinquent outcome across accounts. Possible values include `current`, `collections`, `charge_off`, `payment_agreement`, `chapter_13`, `chapter_7`, `bankruptcy`, `repossession`, `foreclosure`, and `wage_garnishment`. |

### Direct Pay

Direct Pay attributes are added to completed Entity Attribute responses. They are
not supported in v2 subscription `requested_attributes`.

| Attribute                           | Value Type | Bundles | Description                                                                                                               |
| ----------------------------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `enrolled_in_direct_pay_previously` | boolean    | —       | Whether Method has completed at least one Direct Pay payment to any active or closed account tied to the same individual. |
| `last_direct_pay_date`              | string     | —       | ISO timestamp for the most recent completed Direct Pay activity.                                                          |
| `last_direct_pay_amount`            | number     | —       | Amount of the most recent completed Direct Pay payment, in cents.                                                         |
| `number_of_direct_pay_in_12_months` | number     | —       | Number of completed Direct Pay payments in the trailing 365 days.                                                         |

### Installment

| Attribute                        | Value Type | Bundles                                           | Description                                                          |
| -------------------------------- | ---------- | ------------------------------------------------- | -------------------------------------------------------------------- |
| `installment_balance_total`      | number     | [Portfolio Intelligence](#portfolio-intelligence) | Total installment loan balance across all accounts, in cents.        |
| `installment_balance_change_30d` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Change in total installment balance over the last 30 days, in cents. |
| `installment_balance_change_60d` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Change in total installment balance over the last 60 days, in cents. |
| `installment_balance_change_90d` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Change in total installment balance over the last 90 days, in cents. |

### Other

| Attribute                  | Value Type | Bundles                                           | Description                                                            |
| -------------------------- | ---------- | ------------------------------------------------- | ---------------------------------------------------------------------- |
| `other_balance_total`      | number     | [Portfolio Intelligence](#portfolio-intelligence) | Total balance across all other account types, in cents.                |
| `other_balance_change_30d` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Change in total other account balance over the last 30 days, in cents. |
| `other_balance_change_60d` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Change in total other account balance over the last 60 days, in cents. |
| `other_balance_change_90d` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Change in total other account balance over the last 90 days, in cents. |

### Velocity

| Attribute                       | Value Type | Bundles                                           | Description                                                                                                                         |
| ------------------------------- | ---------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `balance_paydown_velocity`      | number     | [Portfolio Intelligence](#portfolio-intelligence) | Rate of debt reduction in dollars per month, computed over the trailing 90 days. *Coming soon.*                                     |
| `balance_accumulation_velocity` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Rate of debt increase in dollars per month, computed over the trailing 90 days. *Coming soon.*                                      |
| `utilization_volatility_30d`    | number     | [Portfolio Intelligence](#portfolio-intelligence) | Standard deviation of daily utilization over the trailing 30 days — higher values signal unstable spending behavior. *Coming soon.* |

### Cross-Account

| Attribute                       | Value Type | Bundles                                           | Description                                                                                              |
| ------------------------------- | ---------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `single_card_concentration_pct` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Percentage of total credit card debt carried on the entity's single highest-balance card. *Coming soon.* |

### Autopay

| Attribute                            | Value Type | Bundles                                           | Description                                                                                                                           |
| ------------------------------------ | ---------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `autopay_enabled_credit_cards_count` | number     | [Portfolio Intelligence](#portfolio-intelligence) | Count of credit card accounts with autopay active. *Coming soon.*                                                                     |
| `autopay_status_change_detected`     | boolean    | [Portfolio Intelligence](#portfolio-intelligence) | True if autopay has been disabled on a previously-active credit card account — a leading indicator of payment trouble. *Coming soon.* |

### Wallet

These attributes are computed on a per-account basis and surfaced when the parent entity is enrolled in [Ready to Pay](#ready-to-pay).

| Attribute                      | Value Type | Bundles                       | Description                                                                                                                                                                                      |
| ------------------------------ | ---------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `utilization_bucket`           | string     | [Ready to Pay](#ready-to-pay) | Point-in-time utilization bucket: `near_limit`, `high`, `medium`, or `low`. *Coming soon.*                                                                                                       |
| `purchasing_power`             | number     | [Ready to Pay](#ready-to-pay) | Available credit on the card (`credit_limit - balance`), in cents. *Coming soon.*                                                                                                                |
| `utilization_velocity_4_week`  | string     | [Ready to Pay](#ready-to-pay) | 4-week utilization trend bucket: `rapidly_increasing`, `increasing`, `stable`, `decreasing`, `new_account`, or `insufficient_data`. *Coming soon.*                                               |
| `utilization_velocity_8_week`  | string     | [Ready to Pay](#ready-to-pay) | 8-week utilization trend bucket (same enum as 4-week). *Coming soon.*                                                                                                                            |
| `utilization_velocity_12_week` | string     | [Ready to Pay](#ready-to-pay) | 12-week utilization trend bucket (same enum as 4-week). *Coming soon.*                                                                                                                           |
| `spend_concentration_4_week`   | number     | [Ready to Pay](#ready-to-pay) | Card's share of the entity's total balance, averaged over the trailing 4 weeks. *Coming soon.*                                                                                                   |
| `spend_concentration_8_week`   | number     | [Ready to Pay](#ready-to-pay) | Card's share of the entity's total balance, averaged over the trailing 8 weeks. *Coming soon.*                                                                                                   |
| `spend_concentration_12_week`  | number     | [Ready to Pay](#ready-to-pay) | Card's share of the entity's total balance, averaged over the trailing 12 weeks. *Coming soon.*                                                                                                  |
| `current_wallet_rank`          | number     | [Ready to Pay](#ready-to-pay) | This card's rank within the entity's wallet, by recent spend concentration. *Coming soon.*                                                                                                       |
| `optimal_charge_date`          | string     | [Ready to Pay](#ready-to-pay) | Suggested next charge date for the card (`YYYY-MM-DD`). *Coming soon.*                                                                                                                           |
| `account_age`                  | number     | [Ready to Pay](#ready-to-pay) | Months since the card's open date. *Coming soon.*                                                                                                                                                |
| `brand_category`               | string     | [Ready to Pay](#ready-to-pay) | Primary card benefit category: `travel`, `dining`, `groceries`, `cash_back_flat`, `cash_back_varied`, `cobrand_airline`, `cobrand_hotel`, `retail`, `credit_builder`, or `other`. *Coming soon.* |
| `brand_tier`                   | string     | [Ready to Pay](#ready-to-pay) | Card tier within its issuer's lineup: `lux`, `premium`, `plus`, `basic`, `credit_builder`, or `retail`. *Coming soon.*                                                                           |

## Available Bundles

Bundles are curated groupings of attributes you can subscribe to with a single name instead of listing each attribute individually. Pass them via the `bundles` field on the [attribute subscription payload](/2026-03-30/reference/entities/subscriptions/create). At least one of `bundles` or `requested_attributes` must be provided — the two can be combined to subscribe to a bundle plus additional individual attributes.

### Portfolio Intelligence

**Bundle name:** `portfolio_intelligence`

Continuous monitoring of a borrower's liability profile after origination — balance trends, utilization shifts, and delinquency signals across credit cards, personal loans, mortgages, HELOCs, and installment debt. See the [Portfolio Intelligence guide](/guides/use-cases/lending/portfolio-monitoring) for use cases and example workflows.

**Enrollment:**

```json theme={null}
{
  "enroll": "attribute",
  "payload": {
    "attributes": {
      "bundles": ["portfolio_intelligence"]
    }
  }
}
```

**Included attributes:**

<Accordion title="View all attributes">
  * **Core balances:** `revolving_credit_card_balance_total`, `personal_loan_balance_total`, `mortgage_balance_total`, `installment_balance_total`, `other_balance_total`, `heloc_balance_total`
  * **Balance change (30/60/90d):** `revolving_credit_card_balance_change_30d`, `personal_loan_balance_change_30d`, `mortgage_balance_change_30d`, `installment_balance_change_30d`, `other_balance_change_30d`, `revolving_credit_card_balance_change_60d`, `personal_loan_balance_change_60d`, `mortgage_balance_change_60d`, `installment_balance_change_60d`, `other_balance_change_60d`, `revolving_credit_card_balance_change_90d`, `personal_loan_balance_change_90d`, `mortgage_balance_change_90d`, `installment_balance_change_90d`, `other_balance_change_90d`
  * **Weighted APR:** `weighted_average_apr_credit_card`, `weighted_average_apr_personal_loan`, `weighted_average_apr_mortgage`
  * **Utilization:** `credit_card_utilization`, `personal_loan_utilization`, `heloc_utilization`, `overall_utilization`
  * **Utilization trends (30/90d):** `revolving_credit_card_utilization_trend_30d`, `personal_loan_utilization_trend_30d`, `mortgage_utilization_trend_30d`, `overall_utilization_trend_30d`, `revolving_credit_card_utilization_trend_90d`, `personal_loan_utilization_trend_90d`, `mortgage_utilization_trend_90d`, `overall_utilization_trend_90d`
  * **Utilization deltas (30/60/90d):** `revolving_credit_card_utilization_delta_30d`, `personal_loan_utilization_delta_30d`, `mortgage_utilization_delta_30d`, `overall_utilization_delta_30d`, `revolving_credit_card_utilization_delta_60d`, `personal_loan_utilization_delta_60d`, `mortgage_utilization_delta_60d`, `overall_utilization_delta_60d`, `revolving_credit_card_utilization_delta_90d`, `personal_loan_utilization_delta_90d`, `mortgage_utilization_delta_90d`, `overall_utilization_delta_90d`
  * **Credit limits & loan amounts:** `credit_limit_total`, `personal_loan_amount_total`, `mortgage_loan_amount_total`, `overall_loan_amount_total`, `available_credit_limit_total`, `available_loan_amount_personal_loans`, `available_credit_total`
  * **Account counts:** `high_utilization_account_count_credit_cards`, `maxed_out_account_count_credit_cards`, `zero_balance_credit_cards_count`
  * **Cost estimates:** `personal_loan_monthly_installments_estimate`, `interest_estimate_min_credit_cards`, `interest_estimate_max_credit_cards`, `interest_cost_monthly_current_credit_cards`, `interest_cost_annual_current_credit_cards`
  * **Payment behavior:** `usage_pattern`, `payment_to_minimum_ratio_avg_credit_cards`, `next_payment_minimum_total_credit_cards`, `next_payment_due_dates_array_credit_cards`, `days_until_next_payment_min_credit_cards`, `minimum_payment_coverage_ratio_credit_cards`, `last_payment_total_credit_cards`
  * **Delinquency:** `delinquency_flag_credit_cards`, `any_delinquent_flag`, `serious_delinquent_flag`, `delinquency_recently_cured_flag`, `delinquency_worst_dpd_bucket`, `delinquency_accounts_count`, `delinquent_balance_total`, `delinquency_progression_flag`, `delinquent_outcome`
  * **Velocity** *(coming soon)***:** `balance_paydown_velocity`, `balance_accumulation_velocity`, `utilization_volatility_30d`
  * **Cross-account** *(coming soon)***:** `single_card_concentration_pct`
  * **Autopay** *(coming soon)***:** `autopay_enabled_credit_cards_count`, `autopay_status_change_detected`
</Accordion>

<Note>
  Portfolio Intelligence is a separately enabled product. Contact your Method CSM to enable `portfolio_intelligence` on your environment.
</Note>

### Ready to Pay

**Bundle name:** `ready_to_pay`

Per-card intelligence for issuers and wallet apps that need to understand where each credit card sits in a consumer's wallet, how spend is trending, and what the card is best used for. Powers wallet ranking, optimal-card-for-purchase logic, and targeted reactivation offers.

<Note>
  Ready to Pay attributes are computed at the **account** level. Enrolling at the entity level activates computation for every credit card account owned by the entity.
</Note>

**Enrollment:**

```json theme={null}
{
  "enroll": "attribute",
  "payload": {
    "attributes": {
      "bundles": ["ready_to_pay"]
    }
  }
}
```

**Included attributes:**

<Accordion title="View all attributes">
  * **Card state:** `usage_pattern`, `utilization`, `utilization_bucket` *(coming soon)*, `purchasing_power` *(available credit)*
  * **Spend velocity** *(coming soon)***:** `utilization_velocity_4_week`, `utilization_velocity_8_week`, `utilization_velocity_12_week`
  * **Wallet position** *(coming soon)***:** `spend_concentration_4_week`, `spend_concentration_8_week`, `spend_concentration_12_week`, `current_wallet_rank`
  * **Timing & metadata** *(coming soon)***:** `optimal_charge_date`, `account_age`, `brand_category`, `brand_tier`
</Accordion>

<Note>
  Ready to Pay is in active development. Contact your Method CSM for availability and early-access enrollment.
</Note>

## Attribute Value Notes

* Attribute values are returned in cents when the description says "in cents".
* `usage_pattern` returns `revolver`, `transactor`, `dormant`, or `closed`. Unknown or unavailable source values return `insufficient_data`.
* `delinquency_flag_credit_cards` returns `on_time` or `overdue`. Unknown or unavailable source values return `insufficient_data`.
* Boolean delinquency flags return `false` only when Method has at least one usable non-delinquent signal. If there is no usable signal, the attribute returns `null` with an insufficient data error.
* `delinquency_worst_dpd_bucket` maps `less_than_30` and `30` to `30_dpd`, `60` to `60_dpd`, `90` to `90_dpd`, and `120` or `over_120` to `120_plus_dpd`.
* `delinquent_balance_total` may return a partial aggregate. When that happens, the attribute includes `metadata.partial`, `metadata.accounts_with_data`, and `metadata.accounts_total`.
* Direct Pay attributes count Method payments with a completed status of `sent`, `posted`, `cashed`, or `settled`. If no completed Direct Pay payment exists, `enrolled_in_direct_pay_previously` is `false`, `number_of_direct_pay_in_12_months` is `0`, and the last payment date and amount return insufficient data.

## Webhook Payload

The [Webhook](/2026-03-30/reference/webhooks/overview) payload will contain the following information:

```json theme={null}
{
  "id": "string",
  "type": "entity_attribute.create",
  "path": "/entities/<ent_id>/attributes/<attr_id>"
}
```

<RequestExample>
  ```json THE ATTRIBUTE OBJECT theme={null}
  {
    "id": "attr_dADraNgLBrhgL",
    "entity_id": "ent_EQ3FCTzDUmmCb",
    "status": "completed",
    "attributes": {
      "revolving_credit_card_balance_total": {
        "value": 968400,
        "error": null,
        "metadata": null
      },
      "credit_limit_total": {
        "value": 8100000,
        "error": null,
        "metadata": null
      },
      "credit_card_utilization": {
        "value": 11.96,
        "error": null,
        "metadata": null
      },
      "weighted_average_apr_credit_card": {
        "value": 29.09,
        "error": null,
        "metadata": null
      },
      "usage_pattern": {
        "value": "revolver",
        "error": null,
        "metadata": null
      },
      "available_credit_limit_total": {
        "value": 7131600,
        "error": null,
        "metadata": null
      },
      "next_payment_minimum_total_credit_cards": {
        "value": 26600,
        "error": null,
        "metadata": null
      },
      "payment_to_minimum_ratio_avg_credit_cards": {
        "value": 1.92,
        "error": null,
        "metadata": null
      },
      "revolving_credit_card_balance_change_30d": {
        "value": 381700,
        "error": null,
        "metadata": null
      },
      "revolving_credit_card_balance_change_60d": {
        "value": null,
        "error": {
          "type": "ENTITY_ATTRIBUTE_INSUFFICIENT_DATA",
          "sub_type": "ENTITY_ATTRIBUTE_INSUFFICIENT_DATA",
          "code": 27001,
          "message": "Insufficient data to compute this entity attribute."
        },
        "metadata": null
      },
      "revolving_credit_card_utilization_delta_30d": {
        "value": -3.28,
        "error": null,
        "metadata": null
      },
      "mortgage_balance_total": {
        "value": 15586300,
        "error": null,
        "metadata": null
      },
      "heloc_balance_total": {
        "value": 4200000,
        "error": null,
        "metadata": null
      },
      "available_credit_total": {
        "value": 7251600,
        "error": null,
        "metadata": null
      },
      "any_delinquent_flag": {
        "value": true,
        "error": null,
        "metadata": null
      },
      "delinquency_worst_dpd_bucket": {
        "value": "60_dpd",
        "error": null,
        "metadata": null
      },
      "delinquent_balance_total": {
        "value": 18000,
        "error": null,
        "metadata": {
          "partial": true,
          "accounts_with_data": 1,
          "accounts_total": 2
        }
      },
      "delinquent_outcome": {
        "value": "payment_agreement",
        "error": null,
        "metadata": null
      },
      "enrolled_in_direct_pay_previously": {
        "value": true,
        "error": null,
        "metadata": null
      },
      "last_direct_pay_date": {
        "value": "2026-04-15T17:02:47.910Z",
        "error": null,
        "metadata": null
      },
      "last_direct_pay_amount": {
        "value": 12500,
        "error": null,
        "metadata": null
      },
      "number_of_direct_pay_in_12_months": {
        "value": 3,
        "error": null,
        "metadata": null
      },
      "overall_loan_amount_total": {
        "value": 26757400,
        "error": null,
        "metadata": null
      },
      "overall_utilization": {
        "value": 70.5,
        "error": null,
        "metadata": null
      },
      "installment_balance_total": {
        "value": 23605200,
        "error": null,
        "metadata": null
      }
    },
    "error": null,
    "created_at": "2026-04-09T17:02:47.910Z",
    "updated_at": "2026-04-09T17:04:35.220Z"
  }
  ```
</RequestExample>


# Retrieve Attributes
Source: https://docs.methodfi.com/2026-03-30/reference/entities/attributes/retrieve

GET /entities/{ent_id}/attributes/{attr_id}

Retrieves an Attributes record for an Entity.

## Path Parameters

<ParamList />

## Returns

Returns an Entity's Attributes object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/attributes/attr_dADraNgLBrhgL \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const attribute = await method
    .entities('ent_au22b1fbFJbp8')
    .attributes
    .retrieve('attr_dADraNgLBrhgL');
  ```

  ```python Python theme={null}
  attribute = method
    .entities('ent_au22b1fbFJbp8')
    .attributes
    .retrieve('attr_dADraNgLBrhgL')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "attr_dADraNgLBrhgL",
      "entity_id": "ent_EQ3FCTzDUmmCb",
      "status": "completed",
      "attributes": {
        "revolving_credit_card_balance_total": {
          "value": 968400,
          "error": null,
          "metadata": null
        },
        "credit_limit_total": {
          "value": 8100000,
          "error": null,
          "metadata": null
        },
        "credit_card_utilization": {
          "value": 11.96,
          "error": null,
          "metadata": null
        },
        "weighted_average_apr_credit_card": {
          "value": 29.09,
          "error": null,
          "metadata": null
        },
        "usage_pattern": {
          "value": "revolver",
          "error": null,
          "metadata": null
        },
        "mortgage_balance_total": {
          "value": 15586300,
          "error": null,
          "metadata": null
        },
        "overall_utilization": {
          "value": 70.5,
          "error": null,
          "metadata": null
        },
        "installment_balance_total": {
          "value": 23605200,
          "error": null,
          "metadata": null
        }
      },
      "error": null,
      "created_at": "2026-04-09T17:02:47.910Z",
      "updated_at": "2026-04-09T17:04:35.220Z"
    }
  }
  ```
</ResponseExample>


# Create a Connect
Source: https://docs.methodfi.com/2026-03-30/reference/entities/connect/create

POST /entities/{ent_id}/connect

Creates a new Connect request to connect all liability accounts for the Entity.

Operation Type: <Tooltip>⚡ Synchronous</Tooltip> or <Tooltip>Asynchronous  ⏳</Tooltip>

<Warning>
  Your request is processed asynchronously if `Prefer: respond-async` header is set or if products / subscriptions are specified. You'll receive a webhook when it's complete.
</Warning>

<Tip>An initial Connect request will connect all liability accounts (closed and active),
all subsequent Connect requests will only return new accounts for an Entity.</Tip>

## Path Parameters

<ParamList />

## Query Parameters

## Body

<Note>
  Raw credit report access (`bureau`, `artifacts`) is a restricted feature.
  Contact Method to enable it for your team. See
  [File objects](/2026-03-30/reference/files/overview) for downloading generated
  artifacts.
</Note>

## Returns

Returns a  object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/connect \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```bash cURL (Connect w/Raw Credit Report) theme={null}
  curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/connect \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "bureau": "transunion",
      "artifacts": ["raw_credit_report", "credit_report_pdf"]
    }'
  ```

  ```javascript Node.js theme={null}
  const entity = await method
    .entities("ent_qKNBB68bfHGNA")
    .connect
    .create();
  ```

  ```python Python theme={null}
  entity = method
    .entities('ent_qKNBB68bfHGNA')
    .connect
    .create()
  ```
</RequestExample>

<ResponseExample>
  ```json Default theme={null}
  {
    "id": "cxn_4ewMmBbjYDMR4",
    "entity_id": "ent_qKNBB68bfHGNA",
    "status": "completed",
    "accounts": [
      "acc_eKKmrXDpJBKgw",
      "acc_GV8WbmJW7KGRy",
      "acc_MLPKh9gQDDbT8",
      "acc_LbXE8wVYJLrKt",
      "acc_J3P9fayDFjpAy",
      "acc_eFFRV9zmpLREK"
    ],
    "requested_products": [],
    "requested_subscriptions": [],
    "files": [],
    "error": null,
    "created_at": "2024-04-12T14:56:46.645Z",
    "updated_at": "2024-04-12T14:56:46.645Z"
  }
  ```

  ```json Connect with Raw Credit Report theme={null}
  {
    "id": "cxn_4ewMmBbjYDMR4",
    "entity_id": "ent_qKNBB68bfHGNA",
    "status": "completed",
    "accounts": [
      "acc_eKKmrXDpJBKgw",
      "acc_GV8WbmJW7KGRy",
      "acc_MLPKh9gQDDbT8"
    ],
    "requested_products": [],
    "requested_subscriptions": [],
    "files": [
      {
        "id": "file_jZWkPMhXPeYAn",
        "type": "raw_credit_report",
        "bureau": "transunion",
        "mime_type": "application/json"
      },
      {
        "id": "file_qTnUv7DdKcRW2",
        "type": "credit_report_pdf",
        "bureau": "transunion",
        "mime_type": "application/pdf"
      }
    ],
    "error": null,
    "created_at": "2024-04-12T14:56:46.645Z",
    "updated_at": "2024-04-12T14:56:46.645Z"
  }
  ```
</ResponseExample>


# List all Connects
Source: https://docs.methodfi.com/2026-03-30/reference/entities/connect/list

GET /entities/{ent_id}/connect

Retrieve a list of Connects for a specific Entity.

## Path Parameters

<ParamList />

## Query Parameters

<ParamList />

## Returns

Returns a list of Connects.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/entities/ent_yVf3mkzbhz9tj/connect" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities('ent_yVf3mkzbhz9tj')
    .connect
    .list();
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_yVf3mkzbhz9tj')
    .connect
    .list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "cxn_4ewMmBbjYDMR4",
        "entity_id": "ent_qKNBB68bfHGNA",
        "status": "completed",
        "accounts": [
          "acc_eKKmrXDpJBKgw",
          "acc_GV8WbmJW7KGRy",
          "acc_MLPKh9gQDDbT8",
          "acc_LbXE8wVYJLrKt",
          "acc_J3P9fayDFjpAy",
          "acc_eFFRV9zmpLREK"
        ],
        "requested_products": [],
        "requested_subscriptions": [],
        "error": null,
        "created_at": "2024-04-12T14:56:46.645Z",
        "updated_at": "2024-04-12T14:56:46.645Z"
      },
      {...}
    ],
    "message": null
  }
  ```
</ResponseExample>


# The connect endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/entities/connect/overview



The Connect endpoint identifies & connects all the liability accounts (e.g. Credit Card, Mortgage, Auto Loans, Student Loans, etc.)
for an Entity across Method's network of 15,000+ FI / Lenders.

<Check>To further provide a comprehensive view the Connect endpoint
will perform a soft-pull of the Entity's credit report.</Check>

**The Connect endpoint is available as a:**

| Type           | Use-Case                                                                                                                                                |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Product`      | On-Demand comprehensive view of an Entity's outstanding liabilities.                                                                                    |
| `Subscription` | Comprehensive view of an Entity's outstanding liabilities and continuous near real-time updates on new liabilities. [Webhook Payload](#webhook-payload) |

## Connect Objects

<ParamList />

## Credit Report Artifacts

Connect performs its discovery from a soft-pull credit report. Teams with raw
credit report access enabled can receive that underlying report by requesting
`artifacts` (with a `bureau`) on [create](/2026-03-30/reference/entities/connect/create).
The generated Files are returned in the Connect's `files` array and can be
downloaded via the [Files API](/2026-03-30/reference/files/overview).

<Note>
  Raw credit report features are enabled on a case-by-case basis. Contact
  Method to enable them.
</Note>

## Webhook Payload

The [Webhook](/2026-03-30/reference/webhooks/overview) payload will contain the following information:

```json theme={null}
{
  "id": "string",
  "type": "connect.create" | "connect.update" | "connect.available",
  "path": "/entities/<ent_id>/connect/<cxn_id>"
}
```

<RequestExample>
  ```json THE CONNECT OBJECT theme={null}
  {
    "id": "cxn_4ewMmBbjYDMR4",
    "entity_id": "ent_qKNBB68bfHGNA",
    "status": "completed",
    "accounts": [
      "acc_eKKmrXDpJBKgw",
      "acc_GV8WbmJW7KGRy",
      "acc_MLPKh9gQDDbT8",
      "acc_LbXE8wVYJLrKt",
      "acc_J3P9fayDFjpAy",
      "acc_eFFRV9zmpLREK"
    ],
    "requested_products": [
      "card_brand"
    ],
    "requested_subscriptions": [
      "card_brand"
    ],
    "files": [
      {
        "id": "file_jZWkPMhXPeYAn",
        "type": "raw_credit_report",
        "bureau": "transunion",
        "mime_type": "application/json"
      }
    ],
    "error": null,
    "created_at": "2024-04-12T14:56:46.645Z",
    "updated_at": "2024-04-12T14:56:46.645Z"
  }
  ```
</RequestExample>


# Retrieve a Connect
Source: https://docs.methodfi.com/2026-03-30/reference/entities/connect/retrieve

GET /entities/{ent_id}/connect/{cxn_id}

Retrieves a  record for an Entity.

## Path Parameters

<ParamList />

## Query Parameters

## Returns

Returns a  object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/connect/cxn_4ewMmBbjYDMR4 \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const entity = await method
    .entities("ent_qKNBB68bfHGNA")
    .connect
    .retrieve("cxn_4ewMmBbjYDMR4");
  ```

  ```python Python theme={null}
  entity = method
    .entities('ent_qKNBB68bfHGNA')
    .connect
    .retrieve('cxn_4ewMmBbjYDMR4')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "cxn_4ewMmBbjYDMR4",
    "entity_id": "ent_qKNBB68bfHGNA",
    "status": "completed",
    "accounts": [
      "acc_eKKmrXDpJBKgw",
      "acc_GV8WbmJW7KGRy",
      "acc_MLPKh9gQDDbT8",
      "acc_LbXE8wVYJLrKt",
      "acc_J3P9fayDFjpAy",
      "acc_eFFRV9zmpLREK"
    ],
    "requested_products": [],
    "requested_subscriptions": [],
    "files": [],
    "error": null,
    "created_at": "2024-04-12T14:56:46.645Z",
    "updated_at": "2024-04-12T14:56:46.645Z"
  }
  ```
</ResponseExample>


# Withdraw an Entity's Consent
Source: https://docs.methodfi.com/2026-03-30/reference/entities/consent/withdraw

POST /entities/{ent_id}/consent

Withdraws an Entity's consent. This endpoint sets the entity's status to `disabled`, withdraws consent on all the entity's accounts,
and removes all active Products or Subscriptions across all the Entity's accounts.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns the entity with `status` set to `disabled`.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/consent \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "withdraw",
      "reason": "entity_withdrew_consent"
    }'
  ```

  ```javascript Node.js theme={null}
  const entity = await method.entities.withdrawConsent('ent_au22b1fbFJbp8');
  ```

  ```python Python theme={null}
  entity = method.entities.withdraw_consent('ent_au22b1fbFJbp8', {
    'type': 'withdraw',
    'reason': 'entity_withdrew_consent'
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
   {
    "id": "ent_qJk8AJ9grkGHg",
    "type": null,
    "individual": null,
    "corporation": null,
    "receive_only": null,
    "verification": null,
    "error": {
      "type": "ENTITY_DISABLED",
      "sub_type": "ENTITY_CONSENT_WITHDRAWN",
      "code": 12004,
      "message": "Entity was disabled due to consent withdrawal."
    },
    "address": {},
    "status": "disabled",
    "metadata": null,
    "created_at": "2024-05-31T21:27:46.044Z",
    "updated_at": "2024-05-31T21:27:49.468Z"
  }

  ```
</ResponseExample>


# Create Individual Credit Scores
Source: https://docs.methodfi.com/2026-03-30/reference/entities/credit-scores/create

POST /entities/{ent_id}/credit_scores

Creates a new Credit Score request to retrieve the Entity's credit score.

Operation Type: <Tooltip>⏳ Asynchronous</Tooltip> | [Webhook Payload](overview#webhook-payload).

## Path Parameters

<ParamList />

## Returns

Returns an Entity's CreditScore object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/credit_scores \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const entity = await method
    .entities('ent_au22b1fbFJbp8')
    .creditScores
    .create();
  ```

  ```python Python theme={null}
  entity = method
  .entities('ent_au22b1fbFJbp8')
  .credit_scores
  .create()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "crs_pn4ca33GXFaCE",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "pending",
    "scores": null,
    "error": null,
    "created_at": "2024-04-12T00:12:30.228Z",
    "updated_at": "2024-04-12T00:12:30.228Z"
  }
  ```
</ResponseExample>


# List all Credit Scores
Source: https://docs.methodfi.com/2026-03-30/reference/entities/credit-scores/list

GET /entities/{ent_id}/credit_scores

Retrieve a list of Credit Scores for a specific Entity.

## Path Parameters

<ParamList />

## Query Parameters

<ParamList />

## Returns

Returns a list of Credit Scores.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/entities/ent_yVf3mkzbhz9tj/credit_scores" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities('ent_yVf3mkzbhz9tj')
    .credit_scores
    .list();
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_yVf3mkzbhz9tj')
    .credit_scores
    .list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
    {
      "id": "crs_pn4ca33GXFaCE",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "completed",
      "scores": [
        {
          "score": 734,
          "source": "equifax",
          "model": "vantage_4",
          "factors": [
            {
              "code": "00034",
              "description": "Total of all balances on bankcard or revolving accounts is too high"
            },
            {
              "code": "00012",
              "description": "The date that you opened your oldest account is too recent"
            },
            {
              "code": "00063",
              "description": "Lack of sufficient relevant real estate account information"
            },
            {
              "code": "00016",
              "description": "The total of all balances on your open accounts is too high"
            }
          ],
          "created_at": "2024-04-12T00:12:32.768Z"
        }
      ],
      "error": null,
      "created_at": "2024-04-12T00:12:30.228Z",
      "updated_at": "2024-04-12T00:12:41.303Z"
    },
      {...}
    ],
    "message": null
  }
  ```
</ResponseExample>


# The credit score endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/entities/credit-scores/overview



The Credit Score endpoint returns the latest credit score and score factors for an Entity.

<Info>Enterprise customers can customize their credit score bureau and model selections. Contact your Method CSM for more information.</Info>

**The Credit Score endpoint is available as a:**

| Type           | Use-Case                                                                                           |
| -------------- | -------------------------------------------------------------------------------------------------- |
| `Product`      | On-Demand view of an Entity's credit score.                                                        |
| `Subscription` | Continuous near real-time updates on an Entity's credit score. [Webhook Payload](#webhook-payload) |

## CreditScore Objects

<ParamList />

## Webhook Payload

The [Webhook](/2026-03-30/reference/webhooks/overview) payload will contain the following information:

```json theme={null}
{
  "id": "string",
  "type": "credit_score.create" | "credit_score.update" | "credit_score.available",
  "path": "/entities/<entity_id>/credit_scores/<crs_id>",
  "event": "<evt_id>"
}
```

<RequestExample>
  ```json THE CREDIT SCORE OBJECT theme={null}
  {
    "id": "crs_pn4ca33GXFaCE",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "completed",
    "scores": [
      {
        "score": 734,
        "source": "equifax",
        "model": "vantage_4",
        "factors": [
          {
            "code": "00034",
            "description": "Total of all balances on bankcard or revolving accounts is too high"
          },
          {
            "code": "00012",
            "description": "The date that you opened your oldest account is too recent"
          },
          {
            "code": "00063",
            "description": "Lack of sufficient relevant real estate account information"
          },
          {
            "code": "00016",
            "description": "The total of all balances on your open accounts is too high"
          }
        ],
        "created_at": "2024-04-12T00:12:32.768Z"
      }
    ],
    "error": null,
    "created_at": "2024-04-12T00:12:30.228Z",
    "updated_at": "2024-04-12T00:12:41.303Z"
  }
  ```
</RequestExample>


# Retrieve Individual Credit Scores
Source: https://docs.methodfi.com/2026-03-30/reference/entities/credit-scores/retrieve

GET /entities/{ent_id}/credit_scores/{crs_id}

Retrieves a Credit Score record for an Entity.

## Path Parameters

<ParamList />

## Returns

Returns an Entity's CreditScore object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/credit_scores/crs_pn4ca33GXFaCE \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const entity = await method
    .entities('ent_au22b1fbFJbp8')
    .creditScores
    .retrieve('crs_pn4ca33GXFaCE');
  ```

  ```python Python theme={null}
  entity = method
    .entities('ent_au22b1fbFJbp8')
    .credit_scores
    .retrieve('crs_pn4ca33GXFaCE')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "crs_pn4ca33GXFaCE",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "completed",
    "scores": [
      {
        "score": 734,
        "source": "equifax",
        "model": "vantage_4",
        "factors": [
          {
            "code": "00034",
            "description": "Total of all balances on bankcard or revolving accounts is too high"
          },
          {
            "code": "00012",
            "description": "The date that you opened your oldest account is too recent"
          },
          {
            "code": "00063",
            "description": "Lack of sufficient relevant real estate account information"
          },
          {
            "code": "00016",
            "description": "The total of all balances on your open accounts is too high"
          }
        ],
        "created_at": "2024-04-12T00:12:32.768Z"
      }
    ],
    "error": null,
    "created_at": "2024-04-12T00:12:30.228Z",
    "updated_at": "2024-04-12T00:12:41.303Z"
  }
  ```
</ResponseExample>


# Create Identities
Source: https://docs.methodfi.com/2026-03-30/reference/entities/identities/create

POST /entities/{ent_id}/identities

Creates a new Identity request to retrieve the identity of an Entity, based off the PII that has been passed in to Method so far.

Operation Type: <Tooltip>⚡ Synchronous</Tooltip>

## Path Parameters

<ParamList />

## Returns

Returns an  object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/identities \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const entity = await method
    .entities("ent_au22b1fbFJbp8")
    .identities
    .create();
  ```

  ```python Python theme={null}
  entity = method
    .entities('ent_au22b1fbFJbp8')
    .identities
    .create()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "idn_NhTRUVEknYaFM",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "completed",
    "identities": [
      {
        "first_name": "KEVIN",
        "last_name": "DOYLE",
        "dob": "1997-03-18",
        "ssn": "111223333",
        "phone": "+16505551115",
        "address": {
          "address": "3300 N INTERSTATE 35",
          "city": "AUSTIN",
          "postal_code": "78705",
          "state": "TX"
        }
      }
    ],
    "error": null,
    "created_at": "2024-01-16T19:36:08.263Z",
    "updated_at": "2024-01-16T19:36:08.263Z"
  }
  ```
</ResponseExample>


# List all Identities
Source: https://docs.methodfi.com/2026-03-30/reference/entities/identities/list

GET /entities/{ent_id}/identities

Retrieve a list of Identities for a specific Entity.

## Path Parameters

<ParamList />

## Query Parameters

<ParamList />

## Returns

Returns a list of Identities.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/entities/ent_yVf3mkzbhz9tj/identities" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities('ent_yVf3mkzbhz9tj')
    .identities
    .list();
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_yVf3mkzbhz9tj')
    .identities
    .list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
    {
      "id": "idn_NhTRUVEknYaFM",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "completed",
      "identities": [
        {
          "first_name": "KEVIN",
          "last_name": "DOYLE",
          "dob": "1997-03-18",
          "ssn": "111223333",
          "phone": "+16505551115",
          "address": {
            "address": "3300 N INTERSTATE 35",
            "city": "AUSTIN",
            "postal_code": "78705",
            "state": "TX"
          }
        }
      ],
      "error": null,
      "created_at": "2024-01-16T19:36:08.263Z",
      "updated_at": "2024-01-16T19:36:08.263Z"
    },
      {...}
    ],
    "message": null
  }
  ```
</ResponseExample>


# The identities endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/entities/identities/overview



The identities endpoint is used to retrieve the underlying identity (PII) of an Entity. The Identity endpoint requires an Entity to have at least a phone number.

For an active entity or entities with a matched identity (`verification.identity.matched`) the identity endpoint will return a single identity with the PII.

For all other entities the identity endpoint could return multiple identities as the provided PII was not enough to
disambiguate and match a single identity.

<Warning>The Identity endpoint is restricted to most teams. Contact your Method CSM for more information.</Warning>

**The Identity endpoint is available as a:**

| Type      | Use-Case                                        |
| --------- | ----------------------------------------------- |
| `Product` | Retrieve the full Identity (PII) for any Entity |

## Identity Objects

<ParamList />

<RequestExample>
  ```json THE IDENTITY OBJECT theme={null}
  {
    "id": "idn_NhTRUVEknYaFM",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "completed",
    "identities": [
      {
        "first_name": "KEVIN",
        "last_name": "DOYLE",
        "dob": "1997-03-18",
        "ssn": "111223333",
        "phone": "+16505551115",
        "address": {
          "address": "3300 N INTERSTATE 35",
          "city": "AUSTIN",
          "postal_code": "78705",
          "state": "TX"
        }
      },
      {
        "first_name": "JOE",
        "last_name": "DOYLE",
        "dob": "1997-03-18",
        "ssn": "123456789",
        "phone": "+16505551115",
        "address": {
          "address": "3300 N INTERSTATE 35",
          "city": "AUSTIN",
          "postal_code": "78705",
          "state": "TX"
        }
      }
    ],
    "error": null,
    "created_at": "2024-01-16T19:36:08.263Z",
    "updated_at": "2024-01-16T19:36:08.263Z"
  }
  ```
</RequestExample>


# Retrieve Identities
Source: https://docs.methodfi.com/2026-03-30/reference/entities/identities/retrieve

GET /entities/{ent_id}/identities/{idn_id}

Retrieves an  request with the matched identity for an Entity.

## Path Parameters

<ParamList />

## Returns

Returns an  object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/identities/idn_NhTRUVEknYaFM \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const entity = await method
    .entities('ent_au22b1fbFJbp8')
    .identities
    .retrieve('idn_NhTRUVEknYaFM');
  ```

  ```python Python theme={null}
  entity = method
    .entities('ent_au22b1fbFJbp8')
    .identities
    .retrieve('idn_NhTRUVEknYaFM')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "idn_NhTRUVEknYaFM",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "completed",
    "identities": [
      {
        "first_name": "KEVIN",
        "last_name": "DOYLE",
        "dob": "1997-03-18",
        "ssn": "111223333",
        "phone": "+16505551115",
        "address": {
          "address": "3300 N INTERSTATE 35",
          "city": "AUSTIN",
          "postal_code": "78705",
          "state": "TX"
        }
      }
    ],
    "error": null,
    "created_at": "2024-01-16T19:36:08.263Z",
    "updated_at": "2024-01-16T19:36:08.263Z"
  }
  ```
</ResponseExample>


# List all Entities
Source: https://docs.methodfi.com/2026-03-30/reference/entities/list-entities

GET /entities

Returns all the Entities associated with your team, or an empty array if none have been created.

## Query Parameters

<ParamList />

## Returns

Returns a list of Entities.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const entities = await method.entities.list();
  ```

  ```python Python theme={null}
  entities = method.entities.list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "id": "ent_76kPG9mJyyGYL",
        "type": "individual",
        "individual": {
            "first_name": "Kevin",
            "last_name": "Doyle",
            "phone": "+15121231111",
            "dob": "1997-03-18",
            "email": "kevin.doyle@gmail.com",
            "ssn_4": null,
            "ssn": "xxxxxxxxx"
        },
        "error": null,
        "address": {
            "line1": "3300 N Interstate 35",
            "line2": null,
            "city": "Austin",
            "state": "TX",
            "zip": "78705"
        },
        "status": "active",
        "verification": {
          "identity": {
            "verified": true,
            "matched": true,
            "latest_verification_session": "evf_mQ6yr6VVJLNEb",
            "methods": []
          },
          "phone": {
            "verified": true,
            "latest_verification_session": "evf_P4QXNj93Y9J8L",
            "methods": []
          }
        },
        "connect": null,
        "credit_score": null,
        "products": [
          "connect",
          "credit_score",
          "identity"
        ],
        "restricted_products": [
          "attribute"
        ],
        "subscriptions": [
          "connect"
        ],
        "available_subscriptions": [],
        "restricted_subscriptions": [
          "credit_score"
        ],
        "metadata": null,
        "created_at": "2023-10-23T05:46:14.550Z",
        "updated_at": "2023-10-23T05:46:14.550Z"
      },
      {
        "id": "ent_A6bmTtFmxQhGQ",
        "type": "corporation",
        "corporation": {
          "name": "Alphabet Inc.",
          "dba": "Google",
          "ein": "641234567",
          "owners": [
            {
              "first_name": "Sergey",
              "last_name": "Brin",
              "phone": "+16505555555",
              "email": "sergey@google.com",
              "dob": "1973-08-21",
              "address": {
                "line1": "600 Amphitheatre Parkway",
                "line2": null,
                "city": "Mountain View",
                "state": "CA",
                "zip": "94043"
              }
            }
          ]
        },
        "error": null,
        "address": {
          "line1": "1600 Amphitheatre Parkway",
          "line2": null,
          "city": "Mountain View",
          "state": "CA",
          "zip": "94043"
        },
        "status": "active",
        "metadata": null,
        "created_at": "2023-10-24T21:26:17.225Z",
        "updated_at": "2023-10-24T21:26:17.225Z"
      } ,
      {
        "id": "ent_mxp3B3yyKLHTH",
        "type": "individual",
        "individual": {
            "first_name": "Alex",
            "last_name": "Kennedy",
            "phone": "+19565555555",
            "dob": "1985-04-23",
            "email": "alex.kennedy@hey.com",
            "ssn_4": null,
            "ssn": null
        },
        "error": null,
        "address": {
            "line1": "1 Hacker Way",
            "line2": null,
            "city": "Menlo Park",
            "state": "CA",
            "zip": "94025"
        },
        "status": "active",
        "verification": {
          "identity": {
            "verified": true,
            "matched": true,
            "latest_verification_session": "evf_mQ6yr6VVJLNEb",
            "methods": []
          },
          "phone": {
            "verified": true,
            "latest_verification_session": "evf_P4QXNj93Y9J8L",
            "methods": []
          }
        },
        "connect": null,
        "credit_score": null,
        "products": [
          "connect",
          "credit_score"
        ],
        "restricted_products": [
          "identity"
        ],
        "subscriptions": [],
        "available_subscriptions": [
          "connect",
          "credit_score"
        ],
        "restricted_subscriptions": [],
        "metadata": null,
        "created_at": "2023-10-23T05:46:14.550Z",
        "updated_at": "2023-10-23T05:46:14.550Z"
      }
    ]
  }
  ```
</ResponseExample>


# List all Products
Source: https://docs.methodfi.com/2026-03-30/reference/entities/products/list

GET /entities/{ent_id}/products

Returns a map of Product names to Product objects for an Entity.

## Path Parameters

<ParamList />

## Returns

Returns a map of Product names to Product objects.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/entities/ent_TYHMaRJUUeJ7U/products" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities('ent_TYHMaRJUUeJ7U')
    .products
    .list();
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_TYHMaRJUUeJ7U')
    .products
    .list()
  ```
</RequestExample>

<ResponseExample>
  ```json THE PRODUCT OBJECT theme={null}
  {
    "connect": {
      "name": "connect",
      "status": "unavailable",
      "status_error": {
          "type": "INVALID_REQUEST",
          "sub_type": "ACCOUNT_CONSENT_UNAVAILABLE",
          "message": "Account consent for your organization is unavailable."
      },
      "latest_request_id": null,
      "latest_successful_request_id": null,
      "is_subscribable": true,
      "created_at": "2024-04-12T00:09:07.521Z",
      "updated_at": "2024-04-12T00:09:07.532Z"
    },
    "credit_score": {
      "name": "credit_score",
      "status": "available",
      "status_error": null,
      "latest_request_id": null,
      "latest_successful_request_id": null,
      "is_subscribable": true,
      "created_at": "2024-04-12T00:09:07.522Z",
      "updated_at": "2024-04-12T00:09:09.088Z"
    },
    "identity": {
      "name": "identity",
      "status": "restricted",
      "status_error": {
          "type": "INVALID_REQUEST",
          "sub_type": "TEAM_CAPABILITY_RESTRICTED",
          "message": "Team access is not available. Reach out to the Method team to learn more."
      },
      "latest_request_id": null,
      "latest_successful_request_id": null,
      "is_subscribable": true,
      "created_at": "2024-04-12T00:09:07.522Z",
      "updated_at": "2024-04-12T00:09:09.088Z"
    },
    "attribute": {
      "name": "attribute",
      "status": "restricted",
      "status_error": {
          "type": "INVALID_REQUEST",
          "sub_type": "PRODUCT_RESTRICTED_CONNECT_REQUIRED",
          "message": "Entity must have a completed Connect record to access this product."
      },
      "latest_request_id": null,
      "latest_successful_request_id": null,
      "is_subscribable": false,
      "created_at": "2024-09-10T02:18:06.405Z",
      "updated_at": "2024-09-10T02:18:06.430Z"
    },
    "vehicle": {
      "name": "vehicle",
      "status": "restricted",
      "status_error": {
          "type": "INVALID_REQUEST",
          "sub_type": "PRODUCT_RESTRICTED_CONNECT_REQUIRED",
          "message": "Entity must have a completed Connect record to access this product."
      },
      "latest_request_id": null,
      "latest_successful_request_id": null,
      "is_subscribable": false,
      "created_at": "2024-04-12T00:09:07.523Z",
      "updated_at": "2024-04-12T00:09:07.534Z"
    }
  }
  ```
</ResponseExample>


# The products endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/entities/products/overview



The Entity Products endpoint outlines the Products (*capabilities*) an Entity has access to, and provides an overview of the status of all the Products.

<Info>Access to most products requires an Entity to be active. However, some products have restricted access requiring team-by-team enablement.</Info>

### Product Names

Products that an Entity can have access to:

| Name           | Use-Case                                                             | Resource Doc                                                           |
| -------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `connect`      | On-Demand comprehensive view of an Entity’s outstanding liabilities. | [Connect](/2026-03-30/reference/entities/connect/overview)             |
| `credit_score` | On-Demand view of an Entity’s credit score.                          | [Credit Scores](/2026-03-30/reference/entities/credit-scores/overview) |
| `identity`     | On-Demand retrieval of the full Identity (PII) for any Entity        | [Identities](/2026-03-30/reference/entities/identities/overview)       |
| `attribute`    | On-Demand view of an Entity’s credit health attributes.              | [Attributes](/2026-03-30/reference/entities/attributes/overview)       |
| `vehicle`      | On-Demand view of an Entity’s vehicles.                              | [Vehicles](/2026-03-30/reference/entities/vehicles/overview)           |

## Product Objects

<ParamList />

## Webhook Payload

The [Webhook](/2026-03-30/reference/webhooks/overview) payload will contain the following information:

```json theme={null}
{
  "id": "string",
  "type": "product.create" | "product.update",
  "path": "/entities/<ent_id>/products/<prd_id>",
}
```

<RequestExample>
  ```json THE PRODUCT OBJECT theme={null}
  {
    "connect": {
      "name": "connect",
      "status": "unavailable",
      "status_error": {
          "type": "INVALID_REQUEST",
          "sub_type": "ACCOUNT_CONSENT_UNAVAILABLE",
          "message": "Account consent for your organization is unavailable."
      },
      "latest_request_id": null,
      "latest_successful_request_id": null,
      "is_subscribable": true,
      "created_at": "2024-04-12T00:09:07.521Z",
      "updated_at": "2024-04-12T00:09:07.532Z"
    },
    "credit_score": {
      "name": "credit_score",
      "status": "available",
      "status_error": null,
      "latest_request_id": null,
      "latest_successful_request_id": null,
      "is_subscribable": true,
      "created_at": "2024-04-12T00:09:07.522Z",
      "updated_at": "2024-04-12T00:09:09.088Z"
    },
    "identity": {
      "name": "identity",
      "status": "restricted",
      "status_error": {
          "type": "INVALID_REQUEST",
          "sub_type": "TEAM_CAPABILITY_RESTRICTED",
          "message": "Team access is not available. Reach out to the Method team to learn more."
      },
      "latest_request_id": null,
      "latest_successful_request_id": null,
      "is_subscribable": false,
      "created_at": "2024-04-12T00:09:07.523Z",
      "updated_at": "2024-04-12T00:09:07.533Z"
    },
    "attribute": {
      "name": "attribute",
      "status": "restricted",
      "status_error": {
          "type": "INVALID_REQUEST",
          "sub_type": "PRODUCT_RESTRICTED_CONNECT_REQUIRED",
          "message": "Entity must have a completed Connect record to access this product."
      },
      "latest_request_id": null,
      "latest_successful_request_id": null,
      "is_subscribable": false,
      "created_at": "2024-04-12T00:09:07.523Z",
      "updated_at": "2024-04-12T00:09:07.533Z"
    },
    "vehicle": {
      "name": "vehicle",
      "status": "restricted",
      "status_error": {
          "type": "INVALID_REQUEST",
          "sub_type": "PRODUCT_RESTRICTED_CONNECT_REQUIRED",
          "message": "Entity must have a completed Connect record to access this product."
      },
    "latest_request_id": null,
    "latest_successful_request_id": null,
    "is_subscribable": false,
    "created_at": "2024-04-12T00:09:07.523Z",
    "updated_at": "2024-04-12T00:09:07.534Z"
    }
  }
  ```
</RequestExample>


# Retrieve an Entity
Source: https://docs.methodfi.com/2026-03-30/reference/entities/retrieve-entity

GET /entities/{ent_id}

Returns the Entity associated with the ID.

## Path Parameters

<ParamList />

## Query Parameters

<ParamList />

## Returns

Returns the Entity associated with the ID.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8 \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const entity = await method.entities.retrieve("ent_au22b1fbFJbp8");
  ```

  ```python Python theme={null}
  entity = method.entities.retrieve('ent_au22b1fbFJbp8')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "ent_au22b1fbFJbp8",
    "type": "individual",
    "individual": {
        "first_name": "Kevin",
        "last_name": "Doyle",
        "phone": "+15121231111",
        "dob": "1997-03-18",
        "email": "kevin.doyle@gmail.com",
        "ssn_4": "xxxx",
        "ssn": null
    },
    "error": null,
    "address": {
        "line1": "3300 N Interstate 35",
        "line2": null,
        "city": "Austin",
        "state": "TX",
        "zip": "78705"
    },
    "status": "active",
    "verification": {
      "identity": {
        "verified": true,
        "matched": true,
        "latest_verification_session": "evf_mQ6yr6VVJLNEb",
        "methods": []
      },
      "phone": {
        "verified": true,
        "latest_verification_session": "evf_P4QXNj93Y9J8L",
        "methods": []
      }
    },
    "connect": null,
    "credit_score": null,
    "products": [
      "connect",
      "credit_score",
      "vehicle"
    ],
    "restricted_products": [
      "identity", 
      "attribute"
    ],
    "subscriptions": [],
    "available_subscriptions": [
      "connect",
      "credit_score"
    ],
    "restricted_subscriptions": [],
    "metadata": null,
    "created_at": "2023-10-23T05:46:14.550Z",
    "updated_at": "2023-10-23T05:46:14.550Z"
  }
  ```
</ResponseExample>


# Create a Subscription
Source: https://docs.methodfi.com/2026-03-30/reference/entities/subscriptions/create

POST /entities/{ent_id}/subscriptions

Enrolls an Entity to a Subscription. Once
enrolled, the Subscription name and details will be present
on the response object.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns a Subscription object.

<Note>
  When subscribing to `attribute`, you must provide at least one of `requested_attributes` or `bundles`.
  Use `requested_attributes` to specify individual attributes by name (see <a href="/2026-03-30/reference/entities/attributes/overview#available-attributes">Available Attributes</a>),
  or `bundles` to subscribe to a pre-defined grouping of attributes (see <a href="/2026-03-30/reference/entities/attributes/overview#available-bundles">Available Bundles</a>
  for the full list and what each bundle expands to). The two can be combined to enroll in a bundle plus extra individual attributes.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_TYHMaRJUUeJ7U/subscriptions \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "enroll": "attribute",
      "payload": {
        "attributes": {
          "bundles": ["portfolio_intelligence"],
          "requested_attributes": ["credit_card_utilization", "revolving_credit_card_balance_total"]
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities('ent_TYHMaRJUUeJ7U')
    .subscriptions
    .create({
      enroll: 'attribute',
      payload: {
        attributes: {
          bundles: ['portfolio_intelligence'],
          requested_attributes: ['credit_card_utilization', 'revolving_credit_card_balance_total'],
        },
      },
    });
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_TYHMaRJUUeJ7U')
    .subscriptions
    .create({
      'enroll': 'attribute',
      'payload': {
        'attributes': {
          'bundles': ['portfolio_intelligence'],
          'requested_attributes': ['credit_card_utilization', 'revolving_credit_card_balance_total'],
        },
      },
    })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "sub_c3a7hVjHCJzF3",
    "name": "attribute",
    "status": "active",
    "payload": {
      "attributes": {
        "bundles": ["portfolio_intelligence"],
        "requested_attributes": ["credit_card_utilization", "revolving_credit_card_balance_total"]
      }
    },
    "latest_request_id": null,
    "created_at": "2026-04-09T17:02:47.910Z",
    "updated_at": "2026-04-09T17:02:47.910Z"
  }
  ```
</ResponseExample>


# Delete a Subscription
Source: https://docs.methodfi.com/2026-03-30/reference/entities/subscriptions/delete

DELETE /entities/{ent_id}/subscriptions/{sub_id}

Deleting a Subscription means to unsubscribe or unenroll an Entity from automatically
receiving new Product resources.

## Path Parameters

<ParamList />

## Returns

Returns a Subscription object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_TYHMaRJUUeJ7U/subscriptions/sub_6f7XtMLymQx3f \
    -X DELETE \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities('ent_TYHMaRJUUeJ7U')
    .subscriptions
    .delete('sub_6f7XtMLymQx3f');
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_TYHMaRJUUeJ7U')
    .subscriptions
    .delete('sub_6f7XtMLymQx3f')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "sub_6f7XtMLymQx3f",
    "name": "credit_score",
    "status": "inactive",
    "payload": null,
    "latest_request_id": "crs_pn4ca33GXFaCE",
    "created_at": "2026-04-09T17:02:47.910Z",
    "updated_at": "2026-04-09T17:02:47.910Z"
  }
  ```
</ResponseExample>


# List all Subscriptions
Source: https://docs.methodfi.com/2026-03-30/reference/entities/subscriptions/list

GET /entities/{ent_id}/subscriptions

Returns a map of Subscription names to Subscription objects associated with an Entity, or an empty object if none have been created.

## Path Parameters

<ParamList />

## Returns

Returns a map of Subscription names to Subscription objects.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/entities/ent_TYHMaRJUUeJ7U/subscriptions" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities('ent_TYHMaRJUUeJ7U')
    .subscriptions
    .list();
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_TYHMaRJUUeJ7U')
    .subscriptions
    .list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "credit_score": {
      "id": "sub_c3a7hVjHCJzF3",
      "name": "credit_score",
      "status": "active",
      "payload": null,
      "latest_request_id": null,
      "created_at": "2026-04-09T17:02:47.910Z",
      "updated_at": "2026-04-09T17:02:47.910Z"
    },
    "connect": {
      "id": "sub_6f7XtMLymQx3f",
      "name": "connect",
      "status": "active",
      "payload": null,
      "latest_request_id": null,
      "created_at": "2026-04-09T17:02:47.910Z",
      "updated_at": "2026-04-09T17:02:47.910Z"
    },
    "attribute": {
      "id": "sub_6f7XtMLymQx3f",
      "name": "attribute",
      "status": "active",
      "payload": {
        "attributes": {
          "requested_attributes": ["credit_card_utilization", "revolving_credit_card_balance_total"]
        }
      },
      "latest_request_id": null,
      "created_at": "2026-04-09T17:02:47.910Z",
      "updated_at": "2026-04-09T17:02:47.910Z"
    }
  }
  ```
</ResponseExample>


# The subscriptions endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/entities/subscriptions/overview



The Entity Subscriptions endpoint controls the state of all Subscriptions for an Entity.

Subscriptions are Products that can provide continuous updates via Webhooks. (e.g. Credit Score Subscription provides updates on an Entity's credit score)

<Info>Most subscriptions are accessible by default. However, some subscriptions have restricted access requiring team-by-team enablement and elevated account verification.</Info>

### Subscription Names

Subscriptions that an Entity can be enrolled in:

| Name           | Use-Case                                                                                                            | Resource Doc                                                           |
| -------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `connect`      | Comprehensive view of an Entity’s outstanding liabilities and continuous near real-time updates on new liabilities. | [Connect](/2026-03-30/reference/entities/connect/overview)             |
| `credit_score` | Continuous near real-time updates on an Entity’s credit score.                                                      | [Credit Scores](/2026-03-30/reference/entities/credit-scores/overview) |
| `attribute`    | Continuous near real-time updates on an Entity’s attributes.                                                        | [Attributes](/2026-03-30/reference/entities/attributes/overview)       |

## Subscriptions Objects

<ParamList />

## Webhook Payload

The [Webhook](/2026-03-30/reference/webhooks/overview) payload will contain the following information:

```json theme={null}
{
  "id": "string",
  "type": "subscription.create" | "subscription.update",
  "path": "/entities/<ent_id>/subscriptions/<sub_id>",
}
```

<RequestExample>
  ```json THE SUBSCRIPTION OBJECT theme={null}
  {
    "credit_score": {
      "id": "sub_6f7XtMLymQx3f",
      "name": "credit_score",
      "status": "active",
      "payload": null,
      "latest_request_id": "crs_pn4ca33GXFaCE",
      "created_at": "2026-04-09T17:02:47.910Z",
      "updated_at": "2026-04-09T17:02:47.910Z"
    }
  }
  ```
</RequestExample>


# Retrieve a Subscription
Source: https://docs.methodfi.com/2026-03-30/reference/entities/subscriptions/retrieve

GET /entities/{ent_id}/subscriptions/{sub_id}

Retrieves a Subscription record for an Entity.

## Path Parameters

<ParamList />

## Returns

Returns a Subscription object.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/entities/ent_TYHMaRJUUeJ7U/subscriptions/sub_6f7XtMLymQx3f" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities("ent_TYHMaRJUUeJ7U")
    .subscriptions
    .retrieve("sub_6f7XtMLymQx3f");
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_TYHMaRJUUeJ7U')
    .subscriptions
    .retrieve('sub_6f7XtMLymQx3f')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "sub_6f7XtMLymQx3f",
    "name": "credit_score",
    "status": "active",
    "payload": null,
    "latest_request_id": null,
    "created_at": "2026-04-09T17:02:47.910Z",
    "updated_at": "2026-04-09T17:02:47.910Z"
  }
  ```
</ResponseExample>


# Update an Entity
Source: https://docs.methodfi.com/2026-03-30/reference/entities/update-entity

PUT /entities/{ent_id}

Updates an Entity with the parameters sent.

<Warning>
  Once an Entity's property has been set, that property can no longer be
  updated.
</Warning>

## Path Parameters

<ParamList />

## Body

<Tabs>
  <Tab title="Individual">
    <ParamField type="object">
      Individual information of the Entity. See [Individual Entity.](/2026-03-30/reference/entities/overview#entity-objects)
    </ParamField>
  </Tab>

  <Tab title="Corporation">
    <ParamField type="object">
      Corporation information of the Entity. See [Corporation Entity.](/2026-03-30/reference/entities/overview#entity-objects)
    </ParamField>
  </Tab>
</Tabs>

<ParamField type="object">
  The Entity's address. See [Entity address.](/2026-03-30/reference/entities/overview#entity-objects)
</ParamField>

<ParamField type="object">
  The Entity's metadata. See [Entity metadata.](/2026-03-30/reference/entities/overview#entity-objects)
</ParamField>

## Returns

Returns the Entity with the updated fields.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8 \
    -X PUT \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "individual": {
        "first_name": "Kevin",
        "last_name": "Doyle",
        "email": "kevin.doyle@gmail.com",
        "dob": "1997-03-18"
      }
  }'
  ```

  ```javascript Node.js theme={null}
  const entity = await method.entities.update("ent_au22b1fbFJbp8", {
    individual: {
      first_name: "Kevin",
      last_name: "Doyle",
      email: "kevin.doyle@gmail.com",
      dob: "1997-03-18",
    },
  });
  ```

  ```python Python theme={null}
  entity = method.entities.update('ent_au22b1fbFJbp8', {
    'individual': {
      'first_name': 'Kevin',
      'last_name': 'Doyle',
      'email': 'kevin.doyle@gmail.com',
      'dob': '1997-03-18',
    }
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "ent_au22b1fbFJbp8",
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15121231111",
      "dob": "1997-03-18",
      "email": "kevin.doyle@gmail.com",
      "ssn_4": null,
      "ssn": null
    },
    "error": null,
    "address": {
      "line1": "3300 N Interstate 35",
      "line2": null,
      "city": "Austin",
      "state": "TX",
      "zip": "78705"
    },
    "status": "active",
    "verification": {
      "identity": {
        "verified": true,
        "matched": true,
        "latest_verification_session": "evf_mQ6yr6VVJLNEb",
        "methods": []
      },
      "phone": {
        "verified": true,
        "latest_verification_session": "evf_P4QXNj93Y9J8L",
        "methods": []
      }
    },
    "connect": null,
    "credit_score": null,
    "products": [
      "connect",
      "credit_score",
      "vehicle"
    ],
    "restricted_products": [
      "identity",
      "attribute"
    ],
    "subscriptions": [],
    "available_subscriptions": [
      "connect",
      "credit_score"
    ],
    "restricted_subscriptions": [],
    "metadata": null,
    "created_at": "2023-10-23T05:46:14.550Z",
    "updated_at": "2023-10-23T05:46:14.550Z"
  }
  ```
</ResponseExample>


# Create Vehicles
Source: https://docs.methodfi.com/2026-03-30/reference/entities/vehicles/create

POST /entities/{ent_id}/vehicles

Creates a new Vehicle request to retrieve the Entity's vehicles.

Operation Type: <Tooltip>⚡ Synchronous</Tooltip>

## Path Parameters

<ParamList />

## Returns

Returns an Entity's Vehicles object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/vehicles \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const entity = await method
    .entities('ent_au22b1fbFJbp8')
    .vehicles
    .create();
  ```

  ```python Python theme={null}
  entity = method
    .entities('ent_au22b1fbFJbp8')
    .vehicles
    .create()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "evhl_knqJgxKUnqDVJ",
    "entity_id": "ent_zR3nJG3c99P3X",
    "vehicles": [
      {
        "vin": "2G1125S36F9220155",
        "year": "2015",
        "make": "chevrolet",
        "model": "impala",
        "series": null,
        "major_color": "black",
        "style": "sedan/saloon"
      },
      {
        "vin": "JN8AZ2NF0C9518827",
        "year": "2012",
        "make": "infiniti",
        "model": "qx56",
        "series": null,
        "major_color": "black",
        "style": "sport_utility_vehicle"
      }
    ],
    "status": "completed",
    "error": null,
    "updated_at": "2024-08-01T16:08:25.462Z",
    "created_at": "2024-08-01T16:08:25.462Z"
  }
  ```
</ResponseExample>


# List all Vehicles
Source: https://docs.methodfi.com/2026-03-30/reference/entities/vehicles/list

GET /entities/{ent_id}/vehicles

Retrieve a list of Vehicles for a specific Entity.

## Path Parameters

<ParamList />

## Query Parameters

<ParamList />

## Returns

Returns a list of Vehicles.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/entities/ent_yVf3mkzbhz9tj/vehicles" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities('ent_yVf3mkzbhz9tj')
    .vehicles
    .list();
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_yVf3mkzbhz9tj')
    .vehicles
    .list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "evhl_knqJgxKUnqDVJ",
        "entity_id": "ent_zR3nJG3c99P3X",
        "vehicles": [
          {
            "vin": "2G1125S36F9220155",
            "year": "2015",
            "make": "chevrolet",
            "model": "impala",
            "series": null,
            "major_color": "black",
            "style": "sedan/saloon"
          },
          {
            "vin": "JN8AZ2NF0C9518827",
            "year": "2012",
            "make": "infiniti",
            "model": "qx56",
            "series": null,
            "major_color": "black",
            "style": "sport_utility_vehicle"
          },
        ],
        "status": "completed",
        "error": null,
        "updated_at": "2024-08-01T16:08:25.462Z",
        "created_at": "2024-08-01T16:08:25.462Z"
      }
      {...}
    ],
    "message": null
  }
  ```
</ResponseExample>


# The vehicles endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/entities/vehicles/overview



The Vehicles endpoint provides the vehicles for an Entity.

**The Vehicles endpoint is available as a:**

| Type      | Use-Case                                |
| --------- | --------------------------------------- |
| `Product` | On-Demand view of an Entity's vehicles. |

## Vehicle Objects

<ParamList />

<RequestExample>
  ```json THE VEHICLES OBJECT theme={null}
  {
    "id": "evhl_knqJgxKUnqDVJ",
    "entity_id": "ent_zR3nJG3c99P3X",
    "vehicles": [
      {
        "vin": "2G1125S36F9220155",
        "year": "2015",
        "make": "chevrolet",
        "model": "impala",
        "series": null,
        "major_color": "black",
        "style": "sedan/saloon"
      },
      {
        "vin": "JN8AZ2NF0C9518827",
        "year": "2012",
        "make": "infiniti",
        "model": "qx56",
        "series": null,
        "major_color": "black",
        "style": "sport_utility_vehicle"
      }
    ],
    "status": "completed",
    "error": null,
    "updated_at": "2024-08-01T16:08:25.462Z",
    "created_at": "2024-08-01T16:08:25.462Z"
  }
  ```
</RequestExample>


# Retrieve Vehicles
Source: https://docs.methodfi.com/2026-03-30/reference/entities/vehicles/retrieve

GET /entities/{ent_id}/vehicles/{evhl_id}

Retrieves a Vehicle record for an Entity.

## Path Parameters

<ParamList />

## Returns

Returns an Entity's Vehicle object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/vehicles/evhl_knqJgxKUnqDVJ \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const entity = await method
    .entities('ent_au22b1fbFJbp8')
    .vehicles
    .retrieve('evhl_knqJgxKUnqDVJ');
  ```

  ```python Python theme={null}
  entity = method
    .entities('ent_au22b1fbFJbp8')
    .vehicles
    .retrieve('evhl_knqJgxKUnqDVJ')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "evhl_knqJgxKUnqDVJ",
    "entity_id": "ent_zR3nJG3c99P3X",
    "vehicles": [
      {
        "vin": "2G1125S36F9220155",
        "year": "2015",
        "make": "chevrolet",
        "model": "impala",
        "series": null,
        "major_color": "black",
        "style": "sedan/saloon"
      },
      {
        "vin": "JN8AZ2NF0C9518827",
        "year": "2012",
        "make": "infiniti",
        "model": "qx56",
        "series": null,
        "major_color": "black",
        "style": "sport_utility_vehicle"
      }
    ],
    "status": "completed",
    "error": null,
    "updated_at": "2024-08-01T16:08:25.462Z",
    "created_at": "2024-08-01T16:08:25.462Z"
  }
  ```
</ResponseExample>


# Create a BYO KYC Verification
Source: https://docs.methodfi.com/2026-03-30/reference/entities/verification-sessions/create-byo-kyc

POST /entities/{ent_id}/verification_sessions

Bring-Your-Own Know-Your-Consumer (BYO KYC) creates a new  to inform Method that this Entity's identity has already been verified via non-Method verifications skipping the identity verification requirement.

<Note>This Verification type is restricted and require pre-approval. Contact your Method CSM for more information.</Note>

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns an  object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_XgYkTdiHyaz3e/verification_sessions \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "identity",
      "method": "byo_kyc",
      "byo_kyc": {}
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities("ent_XgYkTdiHyaz3e")
    .verificationSessions
    .create({
      type: "identity",
      method: "byo_kyc",
      byo_kyc: {},
    });
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_XgYkTdiHyaz3e')
    .verification_sessions
    .create({
      'type': 'identity',
      'method': 'byo_kyc',
      'byo_kyc': {}
    })
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "evf_3VT3bHTCnPbrm",
    "entity_id": "ent_XgYkTdiHyaz3e",
    "status": "verified",
    "type": "identity",
    "method": "byo_kyc",
    "byo_kyc": {
      "authenticated": true
    },
    "error": null,
    "created_at": "2024-04-10T16:40:16.271Z",
    "updated_at": "2024-04-10T16:40:16.271Z"
  }
  ```
</ResponseExample>


# Create a BYO SMS Verification
Source: https://docs.methodfi.com/2026-03-30/reference/entities/verification-sessions/create-byo-sms

POST /entities/{ent_id}/verification_sessions

Bring-Your-Own SMS (BYO SMS) creates a new  to inform Method that this Entity's phone number has already been verified via non-Method verifications skipping the phone verification requirement.

<Note>This Verification type is restricted and require pre-approval. Contact your Method CSM for more information.</Note>

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns an  object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_XgYkTdiHyaz3e/verification_sessions \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "phone",
      "method": "byo_sms",
      "byo_sms": {
        "timestamp": "2023-12-28T14:35:15.816Z"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities("ent_XgYkTdiHyaz3e")
    .verificationSessions
    .create({
      type: "phone",
      method: "byo_sms",
      byo_sms: {
        timestamp: "2023-12-28T14:35:15.816Z",
      },
    });
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_XgYkTdiHyaz3e')
    .verification_sessions
    .create({
      'type': 'phone',
      'method': 'byo_sms',
      'byo_sms': {
        'timestamp': '2023-12-28T14:35:15.816Z'
      }
    })
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "evf_3VT3bHTCnPbrm",
    "entity_id": "ent_XgYkTdiHyaz3e",
    "status": "verified",
    "type": "phone",
    "method": "byo_sms",
    "byo_sms": {
      "timestamp": "2023-12-28T14:35:15.816Z"
    },
    "error": null,
    "created_at": "2024-04-10T16:40:16.271Z",
    "updated_at": "2024-04-10T16:40:16.271Z"
  }
  ```
</ResponseExample>


# Create a KBA Verification
Source: https://docs.methodfi.com/2026-03-30/reference/entities/verification-sessions/create-kba

POST /entities/{ent_id}/verification_sessions

Knowledge-Based Authentication (KBA) creates a new  for verifying an Entity's identity via Method's KBA verification process.

This starts the verification process by sending a list of security "out-of-wallet" questions in the response for the Entity to answer to verify their identity.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns an  object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_hy3xhPDfWDVxi/verification_sessions \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "identity",
      "method": "kba",
      "kba": {}
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities("ent_hy3xhPDfWDVxi")
    .verificationSessions
    .create({
      type: "identity",
      method: "kba",
      kba: {},
    });
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_hy3xhPDfWDVxi')
    .verification_sessions
    .create({
      'type': 'identity',
      'method': 'kba',
      'kba': {}
    })
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "evf_ywizPrR6WDxDG",
    "entity_id": "ent_hy3xhPDfWDVxi",
    "status": "in_progress",
    "type": "identity",
    "method": "kba",
    "kba": {
      "questions": [
        {
          "id": "qtn_xgP6cGhq34fHW",
          "text": "Which of these street names are you associated with?",
          "answers": [
            {
              "text": "21st (Correct)",
              "id": "ans_dbKCwDGwrrBgi"
            },
            {
              "text": "Majestic (Incorrect)",
              "id": "ans_8mpbq3AYPBt9z"
            },
            {
              "text": "Northland (Incorrect)",
              "id": "ans_bwtghTrmgRwDF"
            },
            {
              "text": "Southbridge (Incorrect)",
              "id": "ans_LjBPkzyVRfMGw"
            },
            {
              "text": "None of the Above (Incorrect)",
              "id": "ans_Cw6VGEwYTNdhD"
            }
          ]
        },
        {
          "id": "qtn_kmfdEftQ9zc6T",
          "text": "What is the monthly payment of your most recent auto loan or lease?",
          "answers": [
            {
              "text": "$201 - $300 (Correct)",
              "id": "ans_LXN83xnJAUNFb"
            },
            {
              "text": "$301 - $400 (Incorrect)",
              "id": "ans_C9RKnNAaxQn4m"
            },
            {
              "text": "$501 - $600 (Incorrect)",
              "id": "ans_9nqVjtNhXykLC"
            },
            {
              "text": "$601 - $700 (Incorrect)",
              "id": "ans_9qBFfNDy7fP4K"
            },
            {
              "text": "None of the Above (Incorrect)",
              "id": "ans_kEQHmaDrYDRF8"
            }
          ]
        },
        {
          "id": "qtn_6mWegPLBpAFxb",
          "text": "Which of the following is a current or previous employer?",
          "answers": [
            {
              "text": "Forward Lending Inc (Correct)",
              "id": "ans_EKi47D8wA6YN3"
            },
            {
              "text": "Network Appliance (Incorrect)",
              "id": "ans_prxEE8KhVkyWt"
            },
            {
              "text": "Northwest Community Healthcare (Incorrect)",
              "id": "ans_EYnd7dPzMbnaN"
            },
            {
              "text": "Russell Investment Group (Incorrect)",
              "id": "ans_7pCJRChVMN4tD"
            },
            {
              "text": "None of the Above (Incorrect)",
              "id": "ans_Mh7MMg7azapNq"
            }
          ]
        }
      ],
      "authenticated": false
    },
    "error": null,
    "created_at": "2024-04-11T19:23:44.727Z",
    "updated_at": "2024-04-11T19:23:44.727Z"
  }
  ```
</ResponseExample>


# Create an SMS Verification
Source: https://docs.methodfi.com/2026-03-30/reference/entities/verification-sessions/create-sms

POST /entities/{ent_id}/verification_sessions

Creates a new  for an entity to verify their phone via Method's SMS verification process.

This starts the verification process by sending a SMS code to the entity's phone number on record.
The entity will then need to provide the SMS code to verify their phone number.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns an  object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/verification_sessions \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "phone",
      "method": "sms",
      "sms": {}
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities("ent_au22b1fbFJbp8")
    .verificationSessions
    .create({
      type: "phone",
      method: "sms",
      sms: {},
    });
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_au22b1fbFJbp8')
    .verification_sessions
    .create({
      'type': 'phone',
      'method': 'sms',
      'sms': {}
    })
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "evf_3VT3bHTCnPbrm",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "in_progress",
    "type": "phone",
    "method": "sms",
    "sms": {},
    "error": null,
    "created_at": "2024-04-10T16:40:16.271Z",
    "updated_at": "2024-04-10T16:40:16.271Z"
  }
  ```
</ResponseExample>


# Create an SNA Verification
Source: https://docs.methodfi.com/2026-03-30/reference/entities/verification-sessions/create-sna

POST /entities/{ent_id}/verification_sessions

Creates a new  for an entity to verify their phone via Method's SNA verification process.

This starts the verification process by sending a list of URLs in the response.
The URLs should be opened (via background XHR or mobile browser) from the Entity's device matching the phone number provided.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns an  object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/verification_sessions \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "phone",
      "method": "sna",
      "sna": {}
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities("ent_au22b1fbFJbp8")
    .verificationSessions
    .create({
      type: "phone",
      method: "sna",
      sna: {},
    });
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_au22b1fbFJbp8')
    .verification_sessions
    .create({
      'type': 'phone',
      'method': 'sna',
      'sna': {}
    })
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "evf_qTNNzCQ63zHJ9",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "in_progress",
    "type": "phone",
    "method": "sna",
    "sna": {
      "urls": [
        "https://production.methodfi.com/sna/evf_qTNNzCQ63zHJ9/sna_vrf_yAJRRk8djWLc8",
        "https://production.methodfi.com/sna/evf_qTNNzCQ63zHJ9/sna_vrf_8AhxN68kpkHmL"
      ]
    },
    "error": null,
    "created_at": "2024-04-10T22:15:56.091Z",
    "updated_at": "2024-04-10T22:15:56.091Z"
  }
  ```
</ResponseExample>


# List all Verification Sessions
Source: https://docs.methodfi.com/2026-03-30/reference/entities/verification-sessions/list

GET /entities/{ent_id}/verification_sessions

Retrieve a list of EntityVerificationSessions for a specific Entity.

## Path Parameters

<ParamList />

## Query Parameters

<ParamList />

## Returns

Returns a list of EntityVerificationSessions.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/entities/ent_yVf3mkzbhz9tj/verification_sessions" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities('ent_yVf3mkzbhz9tj')
    .verification_sessions
    .list();
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_yVf3mkzbhz9tj')
    .verification_sessions
    .list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "evf_qTNNzCQ63zHJ9",
        "entity_id": "ent_yVf3mkzbhz9tj",
        "status": "verified",
        "type": "identity",
        "method": "kba",
          "kba": {
          "questions": [],
          "authenticated": true
        },
        "error": null,
        "created_at": "2024-04-11T19:23:44.742Z",
        "updated_at": "2024-04-11T19:23:44.742Z"
      },
      {
        "id": "evf_3VT3bHTCnPbrm",
        "entity_id": "ent_yVf3mkzbhz9tj",
        "status": "verified",
        "type": "phone",
        "method": "sms",
        "sms": {
          "timestamp": "2024-04-10T16:42:03.751Z"
        },
        "error": null,
        "created_at": "2024-04-10T16:40:16.283Z",
        "updated_at": "2024-04-10T16:40:16.283Z"
      },
      {...}
    ],
    "message": null
  }
  ```
</ResponseExample>


# The entity verification sessions endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/entities/verification-sessions/overview



The Entity Verification Sessions manages phone and identity verification sessions for Entities.
Entities need to verify their identity and/or phone in order for them to be used throughout the Method API.

#### Verification Requirements

Entity verification requirements differ on a team-by-team basis. A team's unique verification process is pre-defined
during onboarding based on your team’s specific use case. Contact your Method CSM for more information.

The `method` key in `entity.verification` object will enumerate the phone & identity verifications available for your Entity.
Refer to the [Entity Object](/2026-03-30/reference/entities/overview).

<Warning>
  Any Entity Verification Session will expire 10 minutes after creation. If the
  verification is not completed within that time limit, another verification
  session will need to be created.
</Warning>

## Entity Verification Session Objects

<ParamList />

## Additional Properties based on method

<Tabs>
  <Tab title="sms">
    <ParamList />
  </Tab>

  <Tab title="sna">
    <ParamList />
  </Tab>

  <Tab title="byo_sms">
    <ParamList />
  </Tab>

  <Tab title="byo_kyc">
    <ParamList />
  </Tab>

  <Tab title="kba">
    <ParamList />
  </Tab>

  <Tab title="element">
    <ParamList />
  </Tab>
</Tabs>

## Verification Methods

| Method            | Description                                                                                                                                                                                                                                                                                           |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sms`             | SMS is used to verify the Entity's phone number by sending a SMS code and expecting to receive that same SMS code back to verify the phone.                                                                                                                                                           |
| `sna`             | [Silent Network Auth (SNA)](https://www.twilio.com/en-us/blog/silent-network-authentication-sna-overview) is an authentication method to confirm an Entity's phone number in the background without requiring the user to wait or leave the app.                                                      |
| `byo_sms`         | Bring-Your-Own SMS (BYO SMS) means the Entity's phone number has already been verified via a non-Method provider. Skipping phone verification requirement.                                                                                                                                            |
| `byo_kyc`         | Bring-Your-Own Know-Your-Consumer (BYO KYC) means the Entity's identity has already been verified via a non-Method provider. Skipping identity verification requirement.                                                                                                                              |
| `kba`             | [Knowledge-Based Authentication (KBA)](https://www.incognia.com/the-authentication-reference/knowledge-based-authentication-kba-meaning-and-examples) is an authentication method which confirms a person's identity by asking a series of knowledge questions which only the true owner should know. |
| `element`         | Verification has been done using a [Method Element](/2026-03-30/reference/elements/overview).                                                                                                                                                                                                         |
| `method_verified` | Method has already verified the PII provided.                                                                                                                                                                                                                                                         |

## Webhook Payload

The [Webhook](/2026-03-30/reference/webhooks/overview) payload will contain the following information:

```json theme={null}
{
  "id": "string",
  "type": "entity_verification_sessions.create" | "entity_verification_sessions.update",
  "path": "/entities/<ent_id>/verification_sessions/<evf_id>"
}
```

<RequestExample>
  ```json SMS theme={null}
  {
    "id": "evf_3VT3bHTCnPbrm",
    "entity_id": "ent_XgYkTdiHyaz3e",
    "status": "verified",
    "type": "phone",
    "method": "sms",
    "sms": {
      "timestamp": "2024-02-25T20:02:09.718Z"
    },
    "error": null,
    "created_at": "2024-04-10T16:40:16.271Z",
    "updated_at": "2024-04-10T16:40:16.271Z"
  }
  ```

  ```json SNA theme={null}
  {
    "id": "evf_qTNNzCQ63zHJ9",
    "entity_id": "ent_BYdNCVApmp7Gx",
    "status": "verified",
    "type": "phone",
    "method": "sna",
    "sna": {
      "urls": [
        "https://production.methodfi.com/sna/evf_qTNNzCQ63zHJ9/sna_vrf_yAJRRk8djWLc8",
        "https://production.methodfi.com/sna/evf_qTNNzCQ63zHJ9/sna_vrf_8AhxN68kpkHmL"
      ]
    },
    "error": null,
    "created_at": "2024-04-10T22:15:57.874Z",
    "updated_at": "2024-04-10T22:15:57.874Z"
  }
  ```

  ```json BYO SMS theme={null}
  {
    "id": "evf_atWDtnMW9rnRA",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "verified",
    "type": "phone",
    "method": "byo_sms",
    "byo_sms": {
      "timestamp": "2024-02-25T20:02:09.718Z"
    },
    "error": null,
    "created_at": "2024-02-27T20:02:09.718Z",
    "updated_at": "2024-02-27T20:02:09.718Z"
  }
  ```

  ```json BYO KYC theme={null}
  {
    "id": "evf_atWDtnMW9rnRA",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "verified",
    "type": "identity",
    "method": "byo_kyc",
    "byo_kyc": {
      "authenticated": true
    },
    "error": null,
    "created_at": "2024-02-27T20:02:09.718Z",
    "updated_at": "2024-02-27T20:02:09.718Z"
  }
  ```

  ```json KBA theme={null}
  {
    "id": "evf_ywizPrR6WDxDG",
    "entity_id": "ent_hy3xhPDfWDVxi",
    "status": "verified",
    "type": "identity",
    "method": "kba",
    "kba": {
      "questions": [],
      "authenticated": true
    },
    "error": null,
    "created_at": "2024-04-11T19:23:44.742Z",
    "updated_at": "2024-04-11T19:23:44.742Z"
  }
  ```

  ```json Method Element (phone) theme={null}
  {
    "id": "evf_atWDtnMW9rnRA",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "verified",
    "type": "phone",
    "method": "element",
    "element": {
      "element_token": "pk_elem_Y7xDijceWHjjpr8aK8bBTynwFDWbRayL",
      "type": "auth",
      "timestamp": "2024-04-11T19:39:54.735Z"
    },
    "error": null,
    "created_at": "2024-04-11T19:39:54.735Z",
    "updated_at": "2024-04-11T19:39:54.735Z"
  }
  ```

  ```json Method Element (identity) theme={null}
  {
    "id": "evf_atWDtnMW9rnRA",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "verified",
    "type": "identity",
    "method": "element",
    "element": {
      "element_token": "pk_elem_twaUUGYVMzUhQ8c7rw7PtDejAh7qQAgR",
      "type": "auth",
      "questions": [],
      "authenticated": true
    },
    "error": null,
    "created_at": "2024-04-11T19:39:54.735Z",
    "updated_at": "2024-04-11T19:39:54.735Z"
  }
  ```

  ```json Method Verified (phone) theme={null}
  {
    "id": "evf_rUPmzpwXmrQGc",
    "entity_id": "ent_cPfexykKCAiiL",
    "status": "verified",
    "type": "phone",
    "method": "method_verified",
    "error": null,
    "created_at": "2024-04-11T19:46:40.931Z",
    "updated_at": "2024-04-11T19:46:40.931Z"
  }
  ```

  ```json Method Verified (identity) theme={null}
  {
    "id": "evf_rUPmzpwXmrQGc",
    "entity_id": "ent_cPfexykKCAiiL",
    "status": "verified",
    "type": "identity",
    "method": "method_verified",
    "error": null,
    "created_at": "2024-04-11T19:46:40.931Z",
    "updated_at": "2024-04-11T19:46:40.931Z"
  }
  ```
</RequestExample>


# Retrieve a Verification Session
Source: https://docs.methodfi.com/2026-03-30/reference/entities/verification-sessions/retrieve

GET /entities/{ent_id}/verification_sessions/{evf_id}

Retrieves an EntityVerificationSession for an Entity.

## Path Parameters

<ParamList />

## Returns

Returns an  object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/verification_sessions/evf_qTNNzCQ63zHJ9 \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities("ent_au22b1fbFJbp8")
    .verificationSessions
    .retrieve("evf_qTNNzCQ63zHJ9");
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_au22b1fbFJbp8')
    .verification_sessions
    .retrieve('evf_qTNNzCQ63zHJ9')
  ```
</RequestExample>

<ResponseExample>
  ```json SMS theme={null}
  {
    "id": "evf_qTNNzCQ63zHJ9",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "verified",
    "type": "phone",
    "method": "sms",
    "sms": {
      "timestamp": "2024-02-25T20:02:09.718Z"
    },
    "error": null,
    "created_at": "2024-04-10T16:40:16.271Z",
    "updated_at": "2024-04-10T16:40:16.271Z"
  }
  ```

  ```json SNA theme={null}
  {
    "id": "evf_qTNNzCQ63zHJ9",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "verified",
    "type": "phone",
    "method": "sna",
    "sna": {
      "urls": [
        "https://production.methodfi.com/sna/evf_qTNNzCQ63zHJ9/sna_vrf_yAJRRk8djWLc8",
        "https://production.methodfi.com/sna/evf_qTNNzCQ63zHJ9/sna_vrf_8AhxN68kpkHmL"
      ]
    },
    "error": null,
    "created_at": "2024-04-10T22:15:57.874Z",
    "updated_at": "2024-04-10T22:15:57.874Z"
  }
  ```

  ```json ByoSMS theme={null}
  {
    "id": "evf_qTNNzCQ63zHJ9",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "verified",
    "type": "phone",
    "method": "byo_sms",
    "byo_sms": {
      "timestamp": "2024-02-25T20:02:09.718Z"
    },
    "error": null,
    "created_at": "2024-02-27T20:02:09.718Z",
    "updated_at": "2024-02-27T20:02:09.718Z"
  }
  ```

  ```json ByoKYC theme={null}
  {
    "id": "evf_qTNNzCQ63zHJ9",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "verified",
    "type": "identity",
    "method": "byo_kyc",
    "byo_kyc": {
      "authenticated": true
    },
    "error": null,
    "created_at": "2024-02-27T20:02:09.718Z",
    "updated_at": "2024-02-27T20:02:09.718Z"
  }
  ```

  ```json KBA theme={null}
  {
    "id": "evf_qTNNzCQ63zHJ9",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "verified",
    "type": "identity",
    "method": "kba",
      "kba": {
      "questions": [],
      "authenticated": true
    },
    "error": null,
    "created_at": "2024-04-11T19:23:44.742Z",
    "updated_at": "2024-04-11T19:23:44.742Z"
  }
  ```

  ```json Element (phone) theme={null}
  {
    "id": "evf_qTNNzCQ63zHJ9",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "verified",
    "type": "phone",
    "method": "element",
    "element": {
      "element_token": "pk_elem_Y7xDijceWHjjpr8aK8bBTynwFDWbRayL",
      "type": "auth",
      "timestamp": "2024-04-11T19:39:54.735Z"
    },
    "error": null,
    "created_at": "2024-04-11T19:39:54.735Z",
    "updated_at": "2024-04-11T19:39:54.735Z"
  }
  ```

  ```json Element (identity) theme={null}
  {
    "id": "evf_qTNNzCQ63zHJ9",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "verified",
    "type": "identity",
    "method": "element",
    "element": {
      "element_token": "pk_elem_twaUUGYVMzUhQ8c7rw7PtDejAh7qQAgR",
      "type": "auth",
      "questions": [],
      "authenticated": true
    },
    "error": null,
    "created_at": "2024-04-11T19:39:54.735Z",
    "updated_at": "2024-04-11T19:39:54.735Z"
  }
  ```

  ```json MethodVerified (phone) theme={null}
  {
    "id": "evf_qTNNzCQ63zHJ9",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "verified",
    "type": "phone",
    "method": "method_verified",
    "error": null,
    "created_at": "2024-04-11T19:46:40.931Z",
    "updated_at": "2024-04-11T19:46:40.931Z"
  }
  ```

  ```json MethodVerified (identity) theme={null}
  {
    "id": "evf_qTNNzCQ63zHJ9",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "verified",
    "type": "identity",
    "method": "method_verified",
    "error": null,
    "created_at": "2024-04-11T19:46:40.931Z",
    "updated_at": "2024-04-11T19:46:40.931Z"
  }
  ```
</ResponseExample>


# Update a KBA Verification
Source: https://docs.methodfi.com/2026-03-30/reference/entities/verification-sessions/update-kba

PUT /entities/{ent_id}/verification_sessions/{evf_id}

Updates an ongoing  for verifying an Entity's identity via Method's KBA verification process.

The Entity will response with a list of answers to the questions that were sent in the response of initializing the verification process.
Based off the results of the answers, this will determine if the Entity's identity has been verified or not.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns an EntityVerificationSession object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_hy3xhPDfWDVxi/verification_sessions/evf_ywizPrR6WDxDG \
    -X PUT \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "identity",
      "method": "kba",
      "kba": {
        "answers": [
          {
            "question_id": "qtn_xgP6cGhq34fHW",
            "answer_id": "ans_dbKCwDGwrrBgi"
          },
          {
            "question_id": "qtn_kmfdEftQ9zc6T",
            "answer_id": "ans_LXN83xnJAUNFb"
          },
          {
            "question_id": "qtn_6mWegPLBpAFxb",
            "answer_id": "ans_EKi47D8wA6YN3"
          }
        ]
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities("ent_hy3xhPDfWDVxi")
    .verificationSessions
    .update("evf_ywizPrR6WDxDG", {
      type: "identity",
      method: "kba",
      kba: {
        answers: [
          {
            question_id: "qtn_xgP6cGhq34fHW",
            answer_id: "ans_dbKCwDGwrrBgi"
          },
          {
            question_id: "qtn_kmfdEftQ9zc6T",
            answer_id: "ans_LXN83xnJAUNFb"
          },
          {
            question_id: "qtn_6mWegPLBpAFxb",
            answer_id: "ans_EKi47D8wA6YN3"
          }
        ]
      }
    });
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_hy3xhPDfWDVxi')
    .verification_sessions
    .update('evf_ywizPrR6WDxDG', {
      'type': 'identity',
      'method': 'kba',
      'kba': {
        'answers': [
          {
            'question_id': 'qtn_xgP6cGhq34fHW',
            'answer_id': 'ans_dbKCwDGwrrBgi'
          },
          {
            'question_id': 'qtn_kmfdEftQ9zc6T',
            'answer_id': 'ans_LXN83xnJAUNFb'
          },
          {
            'question_id': 'qtn_6mWegPLBpAFxb',
            'answer_id': 'ans_EKi47D8wA6YN3'
          }
        ]
      }
    })
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "evf_ywizPrR6WDxDG",
    "entity_id": "ent_hy3xhPDfWDVxi",
    "status": "verified",
    "type": "identity",
    "method": "kba",
      "kba": {
      "questions": [],
      "authenticated": true
    },
    "error": null,
    "created_at": "2024-04-11T19:23:44.742Z",
    "updated_at": "2024-04-11T19:23:44.742Z"
  }
  ```
</ResponseExample>


# Update an SMS Verification
Source: https://docs.methodfi.com/2026-03-30/reference/entities/verification-sessions/update-sms

PUT /entities/{ent_id}/verification_sessions/{evf_id}

Updates an ongoing  for an Entity to verify their phone via Method's SMS verification process.

The Entity will provide the SMS code that was sent to their phone number to complete the verification process.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns an Entity's verification session object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/verification_sessions/evf_3VT3bHTCnPbrm \
    -X PUT \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "phone",
      "method": "sms",
      "sms": {
        "sms_code": "884134"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities("ent_au22b1fbFJbp8")
    .verificationSessions
    .update("evf_3VT3bHTCnPbrm", {
      type: "phone",
      method: "sms",
      sms: { sms_code: "884134" },
    });
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_au22b1fbFJbp8')
    .verification_sessions
    .update('evf_3VT3bHTCnPbrm', {
      'type': 'phone',
      'method': 'sms',
      'sms': { 'sms_code': '884134'}
    })
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "evf_3VT3bHTCnPbrm",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "verified",
    "type": "phone",
    "method": "sms",
    "sms": {
      "timestamp": "2024-04-10T16:42:03.751Z"
    },
    "error": null,
    "created_at": "2024-04-10T16:40:16.283Z",
    "updated_at": "2024-04-10T16:40:16.283Z"
  }
  ```
</ResponseExample>


# Update an SNA Verification
Source: https://docs.methodfi.com/2026-03-30/reference/entities/verification-sessions/update-sna

PUT /entities/{ent_id}/verification_sessions/{evf_id}

Updates an ongoing  for an Entity to verify their phone via Method's SNA verification process.

Method will verify that the at least one of the URLs was accessed from a mobile device matching the Entity's phone number.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns an Entity's verification session object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_BYdNCVApmp7Gx/verification_sessions/evf_qTNNzCQ63zHJ9 \
    -X PUT \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "phone",
      "method": "sna",
      "sna": {}
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .entities("ent_BYdNCVApmp7Gx")
    .verificationSessions
    .update("evf_qTNNzCQ63zHJ9", {
      type: "phone",
      method: "sna",
      sna: {},
    });
  ```

  ```python Python theme={null}
  response = method
    .entities('ent_BYdNCVApmp7Gx')
    .verification_sessions
    .update('evf_qTNNzCQ63zHJ9', {
      'type': 'phone',
      'method': 'sna',
      'sna': {}
    })
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "evf_qTNNzCQ63zHJ9",
    "entity_id": "ent_BYdNCVApmp7Gx",
    "status": "verified",
    "type": "phone",
    "method": "sna",
    "sna": {
      "urls": [
        "https://production.methodfi.com/sna/evf_qTNNzCQ63zHJ9/sna_vrf_yAJRRk8djWLc8",
        "https://production.methodfi.com/sna/evf_qTNNzCQ63zHJ9/sna_vrf_8AhxN68kpkHmL"
      ]
    },
    "error": null,
    "created_at": "2024-04-10T22:15:57.874Z",
    "updated_at": "2024-04-10T22:15:57.874Z"
  }
  ```
</ResponseExample>


# List all Managed Accounts
Source: https://docs.methodfi.com/2026-03-30/reference/managed-accounts/list

GET /managed_accounts

Returns a list of all Managed Accounts provisioned for your team.

## Returns

Returns a list of Managed Account objects.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/managed_accounts \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "macc_123456789",
        "routing": "123456789",
        "number": "0123456789",
        "current_balance": 2000000,
        "available_balance": 2000000
      }
    ],
    "message": null
  }
  ```
</ResponseExample>


# List Managed Account Transactions
Source: https://docs.methodfi.com/2026-03-30/reference/managed-accounts/list-transactions

GET /managed_accounts/{macc_id}/transactions

Returns a list of transactions for a specific Managed Account.

## Path Parameters

<ParamList />

## Query Parameters

<ParamList />

## Returns

Returns a list of Managed Account Transaction objects.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/managed_accounts/macc_123456789/transactions \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "macc_txn_123456789",
        "description": "ELECTRONIC BILL PAY WELLS FARGO FINANC 2116418",
        "date": "2024-02-01",
        "amount": -8229
      },
      {
        "id": "macc_txn_123456788",
        "description": "ELECTRONIC BILL PAY MOUNTAIN AMERICA F 2116418",
        "date": "2024-02-01",
        "amount": -3500
      }
    ],
    "message": null
  }
  ```
</ResponseExample>


# The managed accounts endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/managed-accounts/overview



Managed Accounts are FBO (For Benefit Of) accounts managed and provisioned by Method.
This endpoint allows you to retrieve managed account balance and transaction information.

## Managed Account Object

<ParamList />

## Managed Account Transaction Object

<ParamList />

<RequestExample>
  ```json THE MANAGED ACCOUNT OBJECT theme={null}
  {
    "id": "macc_123456789",
    "routing": "123456789",
    "number": "0123456789",
    "current_balance": 2000000,
    "available_balance": 2000000
  }
  ```
</RequestExample>


# Retrieve a Managed Account
Source: https://docs.methodfi.com/2026-03-30/reference/managed-accounts/retrieve

GET /managed_accounts/{macc_id}

Retrieve details of an existing Managed Account.

## Path Parameters

<ParamList />

## Returns

Returns the corresponding Managed Account if it exists.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/managed_accounts/macc_123456789 \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "macc_123456789",
      "routing": "123456789",
      "number": "0123456789",
      "current_balance": 2000000,
      "available_balance": 2000000
    },
    "message": null
  }
  ```
</ResponseExample>


# List all Card Brands
Source: https://docs.methodfi.com/2026-03-30/reference/accounts/card-brands/list

GET /accounts/{acc_id}/card_brands

Retrieve a list of Card Brands' metadata for a specific Account.

## Path Parameters

<ParamList />

## Query Parameters

<ParamList />

## Returns

Returns a list of Card Brands. On version `2025-07-04` and later, each brand in `brands[]` includes a `details` object with card details (APRs, fees, rewards, and promotions).

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/card_brands \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .card_brands
    .list();
  ```

  ```python Python theme={null}
  response = method
    .accounts('acc_yVf3mkzbhz9tj')
    .card_brands
    .list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "cbrd_Accm7P6t6mYQP",
        "account_id": "acc_LxwEqNicr66yP",
        "brands": [
          {
            "id": "pdt_15_brd_1",
            "card_product_id": "pdt_15",
            "description": "Chase Sapphire Reserve",
            "name": "Chase Sapphire Reserve",
            "issuer": "Chase",
            "network": "visa",
            "network_tier": "infinite",
            "type": "specific",
            "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png",
            "details": {
              "card_category": "travel",
              "purchase_apr_min": 21.24,
              "purchase_apr_max": 28.24,
              "cash_advance_apr_min": 29.99,
              "cash_advance_apr_max": 29.99,
              "annual_fee": 55000,
              "late_payment_fee": 4000,
              "rewards": {
                "type": "points",
                "program": "Chase Ultimate Rewards",
                "categories": [
                  { "category": "travel", "category_presentable": "Travel booked through Chase Travel", "rate": 5, "unit": "points_per_dollar", "cap": null },
                  { "category": "dining", "category_presentable": "Dining", "rate": 3, "unit": "points_per_dollar", "cap": null },
                  { "category": "base_rate", "category_presentable": "All other purchases", "rate": 1, "unit": "points_per_dollar", "cap": null }
                ]
              },
              "promotions": [
                {
                  "type": "sign_up_bonus",
                  "title": "60,000 bonus points",
                  "description": "Earn 60,000 bonus points after you spend $4,000 on purchases in the first 3 months from account opening.",
                  "value": 60000,
                  "unit": "points",
                  "spend_requirement": 400000,
                  "qualifying_period": { "value": 3, "unit": "months", "relative_to": "account_opening" },
                  "expiration": null
                }
              ],
              "data_as_of": "2026-06-03"
            }
          }
        ],
        "status": "completed",
        "source": "method",
        "error": null,
        "created_at": "2025-08-12T00:56:50.139Z",
        "updated_at": "2025-08-12T00:56:50.139Z"
      },
      {...}
    ],
    "message": null
  }
  ```
</ResponseExample>


# The card product endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/card-products/overview



<Info>
  This API is only available on version `2025-07-04`.
</Info>

The CardProduct endpoint retrieves the Card Brands associated with a given Card Product. Each brand includes a `details` object with structured card details, including APRs, fees, rewards, and promotional offers.

## CardProduct Objects

<ParamList />

## Webhook Payload

<RequestExample>
  ```json THE CARD PRODUCT OBJECT theme={null}
  {
    "id": "pdt_17",
    "name": "Chase Freedom",
    "issuer": "Chase",
    "type": "specific",
    "brands": [
      {
          "id": "pdt_17_brd_1",
          "description": "Chase Freedom",
          "network": "visa",
          "network_tier": "signature",
          "default_image": "https://static.methodfi.com/card_brands/fb5fbd6a5d45b942752b9dc641b93d1f.png",
          "details": {
            "card_category": "cash_back",
            "purchase_apr_min": 18.99,
            "purchase_apr_max": 28.49,
            "cash_advance_apr_min": 29.99,
            "cash_advance_apr_max": 29.99,
            "annual_fee": 0,
            "late_payment_fee": 4000,
            "rewards": {
              "type": "cash_back",
              "program": "Chase Ultimate Rewards",
              "categories": [
                { "category": "other", "category_presentable": "Rotating quarterly categories (activation required)", "rate": 5, "unit": "percent", "cap": "$1,500/quarter then 1%" },
                { "category": "base_rate", "category_presentable": "All other purchases", "rate": 1, "unit": "percent", "cap": null }
              ]
            },
            "promotions": [
              {
                "type": "sign_up_bonus",
                "title": "$200 bonus",
                "description": "Earn a $200 bonus after you spend $500 on purchases in the first 3 months from account opening.",
                "value": 20000,
                "unit": "cents",
                "spend_requirement": 50000,
                "qualifying_period": { "value": 3, "unit": "months", "relative_to": "account_opening" },
                "expiration": null
              }
            ],
            "data_as_of": "2026-06-03"
          }
      },
      {
          "id": "pdt_17_brd_2",
          "description": "Chase Freedom",
          "network": "visa",
          "network_tier": "standard",
          "default_image": "https://static.methodfi.com/card_brands/6cb697528b0771f982f7c0e8b8869de3.png"
      }
    ]
  }
  ```
</RequestExample>


# Retrieve a CardProduct
Source: https://docs.methodfi.com/2026-03-30/reference/card-products/retrieve

GET /card_products/{pdt_id}

Returns the CardProduct object associated with the ID.

## Path Parameters

<ParamList />

## Returns

Returns the CardProduct object associated with the ID. Each brand in `brands[]` includes a `details` object with card details (APRs, fees, rewards, and promotions).

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/card_products/pdt_17 \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const card_product = await method.card_products.retrieve('pdt_17');
  ```

  ```python Python theme={null}
  card_product = method.card_products.retrieve('pdt_17')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "pdt_17",
    "name": "Chase Freedom",
    "issuer": "Chase",
    "type": "specific",
    "brands": [
      {
          "id": "pdt_17_brd_1",
          "description": "Chase Freedom",
          "network": "visa",
          "network_tier": "signature",
          "default_image": "https://static.methodfi.com/card_brands/fb5fbd6a5d45b942752b9dc641b93d1f.png",
          "details": {
            "card_category": "cash_back",
            "purchase_apr_min": 18.99,
            "purchase_apr_max": 28.49,
            "cash_advance_apr_min": 29.99,
            "cash_advance_apr_max": 29.99,
            "annual_fee": 0,
            "late_payment_fee": 4000,
            "rewards": {
              "type": "cash_back",
              "program": "Chase Ultimate Rewards",
              "categories": [
                { "category": "other", "category_presentable": "Rotating quarterly categories (activation required)", "rate": 5, "unit": "percent", "cap": "$1,500/quarter then 1%" },
                { "category": "base_rate", "category_presentable": "All other purchases", "rate": 1, "unit": "percent", "cap": null }
              ]
            },
            "promotions": [
              {
                "type": "sign_up_bonus",
                "title": "$200 bonus",
                "description": "Earn a $200 bonus after you spend $500 on purchases in the first 3 months from account opening.",
                "value": 20000,
                "unit": "cents",
                "spend_requirement": 50000,
                "qualifying_period": { "value": 3, "unit": "months", "relative_to": "account_opening" },
                "expiration": null
              }
            ],
            "data_as_of": "2026-06-03"
          }
      },
      {
          "id": "pdt_17_brd_2",
          "description": "Chase Freedom",
          "network": "visa",
          "network_tier": "standard",
          "default_image": "https://static.methodfi.com/card_brands/6cb697528b0771f982f7c0e8b8869de3.png"
      }
    ]
  }
  ```
</ResponseExample>


# The element endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/elements/overview



<Warning>
  Method Elements will no longer be supported or maintained beginning December 31st, 2025.
  We recommend using [Method Opal](/opal/overview) for all new integrations. If you are currently
  using Elements, please reach out to your CSM to discuss your migration options.
</Warning>

Method Elements is a collection of embeddable UI components that make it easy to integrate Method's API into your experience. Using Method Elements, you can securely identify your users, connect their liabilites, and move money across accounts.

For more information about using Elements, see the [Elements Overview](/elements/overview).

<RequestExample>
  ```json ELEMENT RESULTS OBJECT theme={null}
  {
    "authenticated": true,
    "cxn_id": "cxn_xr86xHEcWmpmB",
    "accounts": [
      "acc_jPXLFqd6KzH3N",
      "acc_DALLeLrj3TH8h"
    ],
    "entity_id": "ent_GWKYtnFyE79db",
    "events": [
      {
        "type": "open",
        "metadata": {
          "element_type": "connect",
          "op": "open"
        },
        "timestamp": "2024-04-25T02:35:28.097Z"
      },
      {
        "type": "success",
        "metadata": {
          "entity_id": "ent_GWKYtnFyE79db",
          "accounts": [
            "acc_jPXLFqd6KzH3N",
            "acc_DALLeLrj3TH8h"
          ],
          "element_type": "connect",
          "op": "success"
        },
        "timestamp": "2024-04-25T02:35:57.120Z"
      },
      {
        "type": "exit",
        "metadata": {
          "element_type": "connect",
          "op": "exit"
        },
        "timestamp": "2024-04-25T02:35:57.138Z"
      }
    ]
  }
  ```
</RequestExample>


# Retrieve Element Results
Source: https://docs.methodfi.com/2026-03-30/reference/elements/results

GET /elements/token/{pk_elem_id}/results

Returns results and metadata for a given Element token.

## Path Parameters

<ParamList />

## Returns

Returns information about the Element token and session.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/elements/token/pk_elem_dDe4r9M6X3Ad9zjpbgYpzLNtRCXfhPYR/results \
    -X GET \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .elements
    .token
    .results('pk_elem_dDe4r9M6X3Ad9zjpbgYpzLNtRCXfhPYR');
  ```

  ```python Python theme={null}
  response = method
    .elements
    .token
    .results('pk_elem_dDe4r9M6X3Ad9zjpbgYpzLNtRCXfhPYR')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "authenticated": true,
    "cxn_id": "cxn_xr86xHEcWmpmB",
    "accounts": [
      "acc_jPXLFqd6KzH3N",
      "acc_DALLeLrj3TH8h"
    ],
    "entity_id": "ent_GWKYtnFyE79db",
    "events": [
      {
        "type": "open",
        "metadata": {
          "element_type": "connect",
          "op": "open"
        },
        "timestamp": "2024-04-25T02:35:28.097Z"
      },
      {
        "type": "success",
        "metadata": {
          "entity_id": "ent_GWKYtnFyE79db",
          "accounts": [
            "acc_jPXLFqd6KzH3N",
            "acc_DALLeLrj3TH8h"
          ],
          "element_type": "connect",
          "op": "success"
        },
        "timestamp": "2024-04-25T02:35:57.120Z"
      },
      {
        "type": "exit",
        "metadata": {
          "element_type": "connect",
          "op": "exit"
        },
        "timestamp": "2024-04-25T02:35:57.138Z"
      }
    ]
  }
  ```
</ResponseExample>

#### Auth Events

| Event prefix        | Description                                                                                                       |
| ------------------- | ----------------------------------------------------------------------------------------------------------------- |
| AUTH\_INTRO         | Indicates when the user opens, closes, or continues past the Intro screen                                         |
| AUTH\_NAME          | Indicates when the user opens, closes, or continues past the input name screen                                    |
| AUTH\_PHONE         | Indicates when the user opens, closes, or continues past the input phone screen                                   |
| AUTH\_PHONE\_VERIFY | Indicates when the user opens the phone verification screen, submits a code, resends a code, or closes the screen |
| AUTH\_DOB           | Indicates when the user opens, closes, or continues past the date of birth input screen                           |
| AUTH\_ADDRESS       | Indicates when the user opens, closes, or continues past the address input screen                                 |
| AUTH\_SSN4          | Indicates when the user opens, closes, or continues past the last 4 of SSN input screen                           |
| AUTH\_SECQ          | Indicates when the user opens, closes, incorrectly answers, or continues past the security questions screen       |
| AUTH\_CONSENT       | Indicates when the user opens, closes, or continues past the account consent screen                               |
| AUTH\_SUCCESS       | Indicates when the user successfully completes the Authentication portion of Connect                              |
| AUTH\_FAILURE       | Indicates if the user ran into an error during the Authentication portion of Connect                              |

#### Account Verification Events

| Event prefix         | Description                                                                                                                   |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| AVF\_ACCOUNT\_LIST   | Indicates when the user opens or exits out of the account list                                                                |
| AVF\_LEARN\_MORE     | Indicates when the user opens or exits out of the Learn More modal                                                            |
| AVF\_ACCOUNT\_VERIFY | Indicates when the user opens, submits, or closes the verification modal for a specific account                               |
| AVF\_SUCCESS         | Indicates when the user opens or continues past the verification success screen                                               |
| AVF\_EMPTY\_SUCCESS  | Indicates when the user opens or continues past the success screen shown if there were no accounts that required verification |
| AVF\_SKIP\_ALL       | Indicates when the user skips all account verifications                                                                       |
| AVF\_ERROR           | Indicates when the user is displyed an error screen during account verification                                               |


# Create or Update Session
Source: https://docs.methodfi.com/2026-03-30/reference/elements/sessions/create-or-update-session

POST /elements/token

Creating or updating an Element Session is as simple as creating an Element Token with a supported Session `type`

## Body

<ParamList />

## Additional fields based on session type

<Tabs>
  <Tab title="balance_transfer">
    <ParamList />
  </Tab>
</Tabs>

## Returns

Returns a Session object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/elements/token \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "balance_transfer",
      "entity_id": "ent_4t8ycqn435",
      "balance_transfer": {
        ...
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "element_token": "pk_elem_qEqwrYEUELA6ExqfB4y8jjmpN8yBb38M",
      "element_session_id": "elem_sess_dYJpqRhKNzaqw"
      },
    "message": null
  }
  ```
</ResponseExample>


# Get Session
Source: https://docs.methodfi.com/2026-03-30/reference/elements/sessions/get-session

GET /elements/sessions/{session_id}

## Path Parameters

<ParamList />

## Returns

Returns a Session object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/elements/sessions/elem_sess_bTgeRWQ3qApfJ \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "id": "elem_sess_bTgeRWQ3qApfJ",
      "type": "balance_transfer",
      "status": "active",
      "balance_transfer": {
        "flow_type": "penfed_dpo",
        "remainder_opt_in": null,
        "auth_session_completed": false,
        "is_first_pass": true,
        "payout_status": "pending_accounts",
        "payout_ids": {},
        "payout_accounts": {},
        "payout_residual_amount": null,
        "payout_residual_amount_max": 56000,
        "payout_creditor_amount": null,
        "payout_amount_min": 50000,
        "minimum_loan_amount": 200000,
        "loan_details_requested_amount": 560000,
        "loan_details_requested_rate": 3.6,
        "loan_details_requested_term": 12,
        "loan_details_requested_monthly_payment": 17500,
        "loan_details_approved_amount": null,
        "loan_details_approved_rate": null,
        "loan_details_approved_term": null,
        "loan_details_approved_monthly_payment": null,
        "skip_intro": true
      },
      "created_at": "2024-05-02T18:32:36.457Z",
      "updated_at": "2024-05-02T18:32:36.457Z"
    },
    "message": null
  }
  ```
</ResponseExample>


# The sessions endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/elements/sessions/overview



Sessions are a way for users to interact with Method Elements in a more stateful way.
You will be able to create, update, and retrieve session data each time a user travels through the Element.

<Info>
  Method Session is currently only available for [Method Balance Transfer](/2026-03-30/reference/elements/sessions/release-funds).
</Info>

<Warning>
  Each Element Token will still expire 30 minutes after creation. If the
  element session is not completed within that time limit, another element token
  will need to be generated with the same session in order to resume.
</Warning>

## Session Objects

<ParamList />

<RequestExample>
  ```json THE SESSIONS OBJECT theme={null}
    {
      "id": "elem_sess_bTgeR3QzqApfJ",
      "type": "balance_transfer",
      "status": "active",
      "balance_transfer": {
        "flow_type": "default",
        "remainder_opt_in": null,
        "auth_session_completed": false,
        "is_first_pass": true,
        "payout_status": "pending_accounts",
        "payout_ids": {},
        "payout_accounts": {},
        "payout_residual_amount": null,
        "payout_residual_amount_max": 56000,
        "payout_creditor_amount": null,
        "payout_amount_min": 50000,
        "minimum_loan_amount": 200000,
        "loan_details_requested_amount": 560000,
        "loan_details_requested_rate": 3.6,
        "loan_details_requested_term": 12,
        "loan_details_requested_monthly_payment": 17500,
        "loan_details_approved_amount": null,
        "loan_details_approved_rate": null,
        "loan_details_approved_term": null,
        "loan_details_approved_monthly_payment": null,
        "skip_intro": true
      },
      "created_at": "2024-05-02T18:32:36.457Z",
      "updated_at": "2024-05-02T18:32:36.457Z"
    }
  ```
</RequestExample>


# Release Funds
Source: https://docs.methodfi.com/2026-03-30/reference/elements/sessions/release-funds

PUT /elements/sessions/{session_id}

Release funds for a balance transfer session.

## Body

<ParamList />

## Returns

Returns a Session object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/elements/sessions/elem_sess_bnGnJHX9i4tD3 \
    -X PUT \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "balance_transfer": {
        "payout_status": "released",
        "loan_details_approved_amount": 550000,
        "loan_details_approved_term": 60,
        "loan_details_approved_rate": 11.49,
        "loan_details_approved_monthly_payment": 8795
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data":  {
      "id": "elem_sess_bnGnJHX9i4tD3",
      "type": "balance_transfer",
      "balance_transfer": {
          "flow_type": "default",
          "remainder_opt_in": false,
          "auth_session_completed": true,
          "is_first_pass": true,
          "payout_status": "released",
          "payout_ids": {
              "acc_acd7mNt68hcXJ": "pmt_gKAL7e6mka",
              "acc_eKTJpCtFmhdqi": "pmt_p9RqmMAmmw"
          },
          "payout_accounts": {
              "acc_eKTJpCtFmhdqi": 450000,
              "acc_acd7mNt68hcXJ": 100000
          },
          "payout_residual_amount": 0,
          "payout_residual_amount_max": 55000,
          "payout_creditor_amount": 550000,
          "payout_amount_min": 100,
          "minimum_loan_amount": 60000,
          "loan_details_requested_amount": 550000,
          "loan_details_requested_rate": 11.49,
          "loan_details_requested_term": 60,
          "loan_details_requested_monthly_payment": 8795,
          "loan_details_approved_amount": 550000,
          "loan_details_approved_rate": 11.49,
          "loan_details_approved_term": 60,
          "loan_details_approved_monthly_payment": 8795,
          "skip_intro": true
      },
      "created_at": "2024-10-15T14:53:04.073Z",
      "updated_at": "2024-10-15T14:53:28.055Z"
    },
    "message": null
  }
  ```
</ResponseExample>


# Create an Element Token
Source: https://docs.methodfi.com/2026-03-30/reference/elements/tokens

POST /elements/token

Element tokens are used as the starting point and authentication key to instantiate Method's embeddable UI components within your experience.

<Note>
  For security purposes, element tokens are for one-time use only, and expire after 30 minutes.
</Note>

## Body

The structure of the request body differs slightly depending on the type of Element you are trying to use. See the [Elements Guide](/elements/overview) for more information about specific flows.

<Note>
  Either `entity_id` or `connect.entity` is required.
</Note>

<ParamList />

## Returns

The element token that was created.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/elements/token \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "connect",
      "connect": {
        "products": ["balance"],
        "entity": {
          "type": "individual",
          "individual": {
            "first_name": "Kevin",
            "last_name": "Doyle"
          }
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const token = await method.elements.token.create({
    type: "connect",
    connect: {
      products: ["balance"],
      entity: {
        type: "individual",
        individual: {
          first_name: "Kevin",
          last_name: "Doyle"
        }
      }
    }
  });
  ```

  ```python Python theme={null}
  token = method.elements.token.create({
    'type': 'connect',
    'connect': {
      'products': ['balance'],
      'entity': {
        'type': 'individual',
        'individual': {
          'first_name': 'Kevin',
          'last_name': 'Doyle'
        }
      }
    }
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "element_token": "pk_elem_qPmypE9wwphr3WL3yTj7JhxjrPzAmK8G"
  }
  ```
</ResponseExample>


# List all Events
Source: https://docs.methodfi.com/2026-03-30/reference/events/list

GET /events

Returns a list of Events that satisfy the provided filters.

## Query Parameters

<ParamList />

## Returns

Returns a paginated list of Event objects.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/events?resource_id=pmt_zR3nJG3c99P3X" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const events = await method.events.list({
    resource_id: 'pmt_zR3nJG3c99P3X',
    type: 'payment.update'
  });
  ```

  ```python Python theme={null}
  events = method.events.list({
    'resource_id': 'pmt_zR3nJG3c99P3X',
    'type': 'payment.update'
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "id": "evt_7pPmytbXgWk7C",
        "type": "credit_score.increased",
        "resource_id": "crs_wXVk4MM7QWNnh",
        "resource_type": "credit_score",
        "data": "CreditScore",
        "diff": {
          "before": {
            "id": "crs_pn4ca33GXFaCE",
            "entity_id": "ent_au22b1fbFJbp8",
            "status": "completed",
            "scores": [
              {
                "score": 724,
                "source": "equifax",
                "model": "vantage_4",
                "factors": []
              }
            ]
          },
          "after": {
            "id": "crs_wXVk4MM7QWNnh",
            "entity_id": "ent_au22b1fbFJbp8",
            "status": "completed", 
            "scores": [
              {
                "score": 741,
                "source": "equifax",
                "model": "vantage_4",
                "factors": []
              }
            ]
          }
        },
        "updated_at": "2024-08-01T16:08:25.462Z",
        "created_at": "2024-08-01T16:08:25.462Z"
      },
      ...
    ],
  }
  ```
</ResponseExample>


# The event endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/events/overview



The Events API allows you to track both literal and computed changes to various Method resources, such as Attributes, Accounts, Credit Scores, and more. Events provide detailed insights into how data changes over time, helping teams monitor resource updates and interpret complex changes.

Literal events track specific updates to a resource. For example, if an account's status transitions from `active` to `closed`, an `account.closed` event will be triggered, showing the exact change.

Computed events are triggered when a meaningful interpretation is derived by comparing changes across multiple resources or combining several field changes. For example, the `credit_score.increased` event is triggered when a new credit score record shows an increase compared to the previous record.

## Event Objects

<ParamList />

<RequestExample>
  ```json THE EVENT OBJECT theme={null}
  {
    "id": "evt_7pPmytbXgWk7C",
    "type": "credit_score.increased",
    "resource_id": "crs_wXVk4MM7QWNnh",
    "resource_type": "credit_score",
    "data": "CreditScore",
    "diff": {
      "before": {
        "id": "crs_pn4ca33GXFaCE",
        "entity_id": "ent_au22b1fbFJbp8",
        "status": "completed",
        "scores": [
          {
            "score": 724,
            "source": "equifax",
            "model": "vantage_4",
            "factors": []
          }
        ]
      },
      "after": {
        "id": "crs_wXVk4MM7QWNnh",
        "entity_id": "ent_au22b1fbFJbp8",
        "status": "completed", 
        "scores": [
          {
            "score": 741,
            "source": "equifax",
            "model": "vantage_4",
            "factors": []
          }
        ]
      }
    },
    "updated_at": "2024-08-01T16:08:25.462Z",
    "created_at": "2024-08-01T16:08:25.462Z"
  }
  ```
</RequestExample>


# Retrieve an Event
Source: https://docs.methodfi.com/2026-03-30/reference/events/retrieve

GET /events/{evt_id}

Returns the Event object associated with the ID.

## Path Parameters

<ParamList />

## Returns

Returns the Event object associated with the ID.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/events/evt_knqJgxKUnqDVJ \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const event = await method.events.retrieve('evt_knqJgxKUnqDVJ');
  ```

  ```python Python theme={null}
  event = method.events.retrieve('evt_knqJgxKUnqDVJ')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "evt_7pPmytbXgWk7C",
    "type": "credit_score.increased",
    "resource_id": "crs_wXVk4MM7QWNnh",
    "resource_type": "credit_score",
    "data": "CreditScore",
    "diff": {
      "before": {
        "id": "crs_pn4ca33GXFaCE",
        "entity_id": "ent_au22b1fbFJbp8",
        "status": "completed",
        "scores": [
          {
            "score": 724,
            "source": "equifax",
            "model": "vantage_4",
            "factors": []
          }
        ]
      },
      "after": {
        "id": "crs_wXVk4MM7QWNnh",
        "entity_id": "ent_au22b1fbFJbp8",
        "status": "completed", 
        "scores": [
          {
            "score": 741,
            "source": "equifax",
            "model": "vantage_4",
            "factors": []
          }
        ]
      }
    },
    "updated_at": "2024-08-01T16:08:25.462Z",
    "created_at": "2024-08-01T16:08:25.462Z"
  }
  ```
</ResponseExample>


# Download a File
Source: https://docs.methodfi.com/2026-03-30/reference/files/download

GET /files/{file_id}/download

Streams the File's contents directly.

The response body is the raw file (e.g. the raw credit report JSON or the
credit report PDF), with the File's `mime_type` as the `Content-Type` and a
`Content-Disposition` attachment header containing the file name.

<Tip>
  Use this endpoint to download the file directly. If you just need a
  link to the file, use the `download_url` from
  [Retrieve a File](/2026-03-30/reference/files/retrieve) instead.
</Tip>

## Path Parameters

<ParamList />

## Returns

Returns the File's contents.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/files/file_jZWkPMhXPeYAn/download \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -o raw_credit_report.json
  ```
</RequestExample>


# The file endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/files/overview



Files represent downloadable artifacts generated by Method.

Files cannot be created directly. They are created by Method as a result of
other API requests, and are referenced by the resource that generated them.
For example, a Connect request with `artifacts` returns its generated Files
in the Connect's `files` array.

<Note>
  Contextual metadata about a File, such as its `bureau`, is returned on the
  generating resource, not on the File object itself.
</Note>

## File Objects

<ParamList />

<RequestExample>
  ```json THE FILE OBJECT theme={null}
  {
    "id": "file_jZWkPMhXPeYAn",
    "type": "raw_credit_report",
    "mime_type": "application/json",
    "download_url": "https://s3.us-west-2.amazonaws.com/files.dev.methodfi.tldn/artifacts/team_aBcD1234/connect/ent_qKNBB68bfHGNA/cxn_4ewMmBbjYDMR4/raw_credit_report.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=...",
    "download_expires_at": "2024-04-12T15:56:46.645Z",
    "created_at": "2024-04-12T14:56:46.645Z",
    "updated_at": "2024-04-12T14:56:46.645Z"
  }
  ```
</RequestExample>


# Retrieve a File
Source: https://docs.methodfi.com/2026-03-30/reference/files/retrieve

GET /files/{file_id}

Retrieves a File and its metadata, including a temporary `download_url` to
its contents.

A new `download_url` is generated on every retrieve and expires at
`download_expires_at`. URLs are valid for 60 minutes (3600 seconds) by
default. If a URL expires, retrieve the File again to receive a fresh one.

<Tip>
  To stream the File's contents directly instead of using a temporary URL,
  use [Download a File](/2026-03-30/reference/files/download).
</Tip>

## Path Parameters

<ParamList />

## Returns

Returns a File object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/files/file_jZWkPMhXPeYAn \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "file_jZWkPMhXPeYAn",
    "type": "raw_credit_report",
    "mime_type": "application/json",
    "download_url": "https://s3.us-west-2.amazonaws.com/files.dev.methodfi.tldn/artifacts/team_aBcD1234/connect/ent_qKNBB68bfHGNA/cxn_4ewMmBbjYDMR4/raw_credit_report.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Expires=3600&X-Amz-Signature=...",
    "download_expires_at": "2024-04-12T15:56:46.645Z",
    "created_at": "2024-04-12T14:56:46.645Z",
    "updated_at": "2024-04-12T14:56:46.645Z"
  }
  ```
</ResponseExample>


# Create a Forwarding Request
Source: https://docs.methodfi.com/2026-03-30/reference/forwarding-requests/create

POST /forwarding_requests

Creates a new ForwardingRequest to securely forward sensitive data to an external API.
The request is executed immediately, and the response from the upstream server is returned.

Operation Type: <Tooltip>⚡ Synchronous</Tooltip>

## Body

<ParamList />

## Returns

Returns the ForwardingRequest object with the `request` and `response` fields populated.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/forwarding_requests \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "bindings": {
        "payment_instrument": "pmt_inst_7TNTTRQwQxWc",
        "secret": "sec_au22b1fbFrmfp",
        "entity": "ent_au22b1FBFJbp8"
      },
      "url": "https://sample-url/v1/tokens",
      "method": "POST",
      "headers": {
        "Content-Type": "application/json",
        "Authorization": "Bearer {{secret.value}}"
      },
      "body": "{\"first_name\":\"{{entity.individual.first_name}}\",\"last_name\":\"{{entity.individual.last_name}}\",\"number\":\"{{payment_instrument.card.number}}\",\"month\":\"{{payment_instrument.card.month}}\",\"year\":\"{{payment_instrument.card.year}}\",\"cvv\":\"{{payment_instrument.card.cvv}}\",\"address1\":\"123 Main St\",\"city\":\"San Francisco\",\"state\":\"CA\",\"country\":\"US\",\"postal_code\":\"94110\"}"
    }'
  ```

  ```javascript Node.js theme={null}
  const forwardingRequest = await method.forwardingRequests.create({
    bindings: {
      payment_instrument: 'pmt_inst_7TNTTRQwQxWc',
      secret: 'sec_au22b1fbFrmfp',
      entity: 'ent_au22b1FBFJbp8'
    },
    url: 'https://sample-url/v1/tokens',
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer {{secret.value}}'
    },
    body: JSON.stringify({
      first_name: '{{entity.individual.first_name}}',
      last_name: '{{entity.individual.last_name}}',
      number: '{{payment_instrument.card.number}}',
      month: '{{payment_instrument.card.month}}',
      year: '{{payment_instrument.card.year}}',
      cvv: '{{payment_instrument.card.cvv}}',
      address1: '123 Main St',
      city: 'San Francisco',
      state: 'CA',
      country: 'US',
      postal_code: '94110'
    })
  });
  ```

  ```python Python theme={null}
  import json

  forwarding_request = method.forwarding_requests.create({
    'bindings': {
      'payment_instrument': 'pmt_inst_7TNTTRQwQxWc',
      'secret': 'sec_au22b1fbFrmfp',
      'entity': 'ent_au22b1FBFJbp8'
    },
    'url': 'https://sample-url/v1/tokens',
    'method': 'POST',
    'headers': {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer {{secret.value}}'
    },
    'body': json.dumps({
      'first_name': '{{entity.individual.first_name}}',
      'last_name': '{{entity.individual.last_name}}',
      'number': '{{payment_instrument.card.number}}',
      'month': '{{payment_instrument.card.month}}',
      'year': '{{payment_instrument.card.year}}',
      'cvv': '{{payment_instrument.card.cvv}}',
      'address1': '123 Main St',
      'city': 'San Francisco',
      'state': 'CA',
      'country': 'US',
      'postal_code': '94110'
    })
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "freq_f6xGfRQyQxDc",
    "bindings": {
      "payment_instrument": "pmt_inst_7TNTTRQwQxWc",
      "secret": "sec_au22b1fbFrmfp",
      "entity": "ent_au22b1FBFJbp8"
    },
    "request": {
      "url": "https://sample-url/v1/tokens",
      "method": "POST",
      "headers": {
        "Content-Type": "application/json",
        "Authorization": "Bearer {{secret.value}}"
      },
      "body": "{\"first_name\":\"{{entity.individual.first_name}}\",\"last_name\":\"{{entity.individual.last_name}}\",\"number\":\"{{payment_instrument.card.number}}\",\"month\":\"{{payment_instrument.card.month}}\",\"year\":\"{{payment_instrument.card.year}}\",\"cvv\":\"{{payment_instrument.card.cvv}}\",\"address1\":\"123 Main St\",\"city\":\"San Francisco\",\"state\":\"CA\",\"country\":\"US\",\"postal_code\":\"94110\"}"
    },
    "response": {
      "status_code": 200,
      "headers": {
        "content-type": "application/json; charset=utf-8",
        "x-request-id": "3a92e6c6-7661-4270-bf31-2d4cc25ea911"
      },
      "body": {
        "type": "credit_card",
        "id": "vJlxp8rHhCq9FNCNF6VYeA",
        "card": {
          "brand": "visa",
          "first_six": "411111",
          "last_four": "1111",
          "exp_month": 2,
          "exp_year": 2030,
          "issuing_country": "US",
          "funding_source": "credit"
        }
      }
    },
    "duration_ms": 953,
    "created_at": "2025-12-04T18:50:54.024Z",
    "updated_at": "2025-12-04T18:50:54.024Z",
    "status": "completed"
  }
  ```
</ResponseExample>


# The Forwarding Request endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/forwarding-requests/overview



A ForwardingRequest is a one-time execution that securely forwards sensitive data to
external APIs. It allows you to make outbound requests using templated values from
Method resources (such as payment instruments, secrets, and entities) without exposing the
underlying sensitive data.

Template expressions use the `{{binding_name.path.to.field}}` syntax to reference values
from bound resources.

## ForwardingRequest Objects

<ParamList />

<RequestExample>
  ```json THE FORWARDING REQUEST OBJECT theme={null}
  {
    "id": "freq_f6xGfRQyQxDc",
    "bindings": {
      "payment_instrument": "pmt_inst_7TNTTRQwQxWc",
      "secret": "sec_au22b1fbFrmfp",
      "entity": "ent_au22b1FBFJbp8"
    },
    "request": {
      "url": "https://sample-url/v1/tokens",
      "method": "POST",
      "headers": {
        "Content-Type": "application/json",
        "Authorization": "Bearer {{secret.value}}"
      },
      "body": "{\"first_name\":\"John\",\"last_name\":\"Doe\",\"number\":\"{{payment_instrument.card.number}}\",\"month\":\"{{payment_instrument.card.month}}\",\"year\":\"{{payment_instrument.card.year}}\",\"cvv\":\"{{payment_instrument.card.cvv}}\",\"address1\":\"123 Main St\",\"city\":\"San Francisco\",\"state\":\"CA\",\"country\":\"US\",\"postal_code\":\"94110\"}"
    },
    "response": {
      "status_code": 200,
      "headers": {
        "content-type": "application/json; charset=utf-8",
        "x-request-id": "3a92e6c6-7661-4270-bf31-2d4cc25ea911"
      },
      "body": {
        "type": "credit_card",
        "id": "vJlxp8rHhCq9FNCNF6VYeA",
        "card": {
          "brand": "visa",
          "first_six": "411111",
          "last_four": "1111",
          "exp_month": 2,
          "exp_year": 2030,
          "issuing_country": "US",
          "funding_source": "credit"
        }
      }
    },
    "duration_ms": 953,
    "created_at": "2025-12-04T18:50:54.024Z",
    "updated_at": "2025-12-04T18:50:54.024Z",
    "status": "completed"
  }
  ```
</RequestExample>


# Retrieve a Forwarding Request
Source: https://docs.methodfi.com/2026-03-30/reference/forwarding-requests/retrieve

GET /forwarding_requests/{freq_id}

Returns the ForwardingRequest object associated with the ID.

## Path Parameters

<ParamList />

## Returns

Returns the ForwardingRequest object associated with the ID.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/forwarding_requests/freq_f6xGfRQyQxDc \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const forwardingRequest = await method.forwardingRequests.retrieve('freq_f6xGfRQyQxDc');
  ```

  ```python Python theme={null}
  forwarding_request = method.forwarding_requests.retrieve('freq_f6xGfRQyQxDc')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "freq_f6xGfRQyQxDc",
    "bindings": {
      "payment_instrument": "pmt_inst_7TNTTRQwQxWc",
      "secret": "sec_au22b1fbFrmfp"
    },
    "request": {
      "url": "https://sample-url/v1/tokens",
      "method": "POST",
      "headers": {
        "Content-Type": "application/json",
        "Authorization": "Bearer {{secret.value}}"
      },
      "body": "{\"first_name\":\"John\",\"last_name\":\"Doe\",\"number\":\"{{payment_instrument.card.number}}\",\"month\":\"{{payment_instrument.card.month}}\",\"year\":\"{{payment_instrument.card.year}}\",\"cvv\":\"{{payment_instrument.card.cvv}}\",\"address1\":\"123 Main St\",\"city\":\"San Francisco\",\"state\":\"CA\",\"country\":\"US\",\"postal_code\":\"94110\"}"
    },
    "response": {
      "status_code": 200,
      "headers": {
        "content-type": "application/json; charset=utf-8",
        "x-request-id": "3a92e6c6-7661-4270-bf31-2d4cc25ea911"
      },
      "body": {
        "type": "credit_card",
        "id": "vJlxp8rHhCq9FNCNF6VYeA",
        "card": {
          "brand": "visa",
          "first_six": "411111",
          "last_four": "1111",
          "exp_month": 2,
          "exp_year": 2030,
          "issuing_country": "US",
          "funding_source": "credit"
        }
      }
    },
    "duration_ms": 953,
    "created_at": "2025-12-04T18:50:54.024Z",
    "updated_at": "2025-12-04T18:50:54.024Z",
    "status": "completed"
  }
  ```
</ResponseExample>


# Perform a Health Check
Source: https://docs.methodfi.com/2026-03-30/reference/health-check

GET /ping

A health check may be performed by calling the `/ping` endpoint.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/ping \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  await method.ping();
  ```

  ```python Python theme={null}
  method.ping()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": null,
    "message": "pong"
  }
  ```
</ResponseExample>


# IP Whitelisting
Source: https://docs.methodfi.com/2026-03-30/reference/ip-whitelisting



Method webhooks will only be emitted from the following IP addresses.

In order to provide additional network security to your system when handling Method webhooks, you can whitelist the following IP addresses for each environment.

| Environment | Host                              | IPs                                                                        |
| ----------- | --------------------------------- | -------------------------------------------------------------------------- |
| Development | `https://dev.methodfi.com`        | `35.82.103.24` `54.188.83.35` `104.28.1.162` `104.28.0.19` `104.28.0.18`   |
| Sandbox     | `https://sandbox.methodfi.com`    | `52.11.69.13` `52.12.28.169` `104.28.1.162` `104.28.0.19` `104.28.0.18`    |
| Production  | `https://production.methodfi.com` | `34.213.118.45` `44.235.25.170` `104.28.1.162` `104.28.0.19` `104.28.0.18` |


# List all Merchants
Source: https://docs.methodfi.com/2026-03-30/reference/merchants/list

GET /merchants

Returns a list of Merchants that satisfy the provided filters.

## Query Parameters

<ParamList />

## Returns

Returns a list of Merchants objects.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/merchants?name=Capital One" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const merchants = await method.merchants.list({
    name: 'Capital One',
    type: 'credit_card',
  });
  ```

  ```python Python theme={null}
  merchants = method.merchants.list({
    'name': 'Capital One',
    'type': 'credit_card'
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "id": "mch_301761",
        "parent_name": "Capital One",
        "name": "Capital One Credit Card",
        "logo": "https://static.methodfi.com/mch_logos/mch_301761.png",
        "type": "credit_card",
        "provider_ids": {
          "plaid": [
            "ins_9",
            "ins_128026"
          ],
          "mx": [
            "capital_one"
          ],
          "finicity": [],
          "dpp": [
            "9366979",
            "18372457",
            "18431971",
            "18373255",
            "14444930"
          ],
          "rpps": []
        },
        "is_temp": false,
        "account_number_formats": [
          "################"
        ]
      }
    ]
  }
  ```
</ResponseExample>


# The merchant endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/merchants/overview



Merchants are resources that represent a specific type of liability for a financial
institution. Method supports the majority of the financial institutions in the U.S.

<Note>
  Financial institutions that offer multiple liability products are represented in Method
  as separate Merchants.

  Ex. Capital One Credit Card (<code>mch\_301761</code>) is
  different from Capital One Auto Loan (<code>mch\_301760</code>)
</Note>

## Merchant Objects

<ParamList />

<RequestExample>
  ```json THE MERCHANT OBJECT theme={null}
  {
    "id": "mch_301761",
    "parent_name": "Capital One",
    "name": "Capital One Credit Card",
    "logo": "https://static.methodfi.com/mch_logos/mch_301761.png",
    "type": "credit_card",
    "provider_ids": {
      "plaid": [
        "ins_9",
        "ins_128026"
      ],
      "mx": [
        "capital_one"
      ],
      "finicity": [],
      "dpp": [
        "9366979",
        "18372457",
        "18431971",
        "18373255",
        "14444930"
      ],
      "rpps": []
    },
    "is_temp": false,
    "account_number_formats": [
      "################"
    ]
  }
  ```
</RequestExample>


# Retrieve a Merchant
Source: https://docs.methodfi.com/2026-03-30/reference/merchants/retrieve

GET /merchants/{mch_id}

Returns the Merchant object associated with the ID.

## Path Parameters

<ParamList />

## Returns

Returns the Merchant object associated with the ID.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/merchants/mch_301761 \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const merchant = await method.merchants.retrieve('mch_301761');
  ```

  ```python Python theme={null}
  merchant = method.merchants.retrieve('mch_301761')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "mch_301761",
    "parent_name": "Capital One",
    "name": "Capital One Credit Card",
    "logo": "https://static.methodfi.com/mch_logos/mch_301761.png",
    "type": "credit_card",
    "provider_ids": {
      "plaid": [
        "ins_9",
        "ins_128026"
      ],
      "mx": [
        "capital_one"
      ],
      "finicity": [],
      "dpp": [
        "9366979",
        "18372457",
        "18431971",
        "18373255",
        "14444930"
      ],
      "rpps": []
    },
    "is_temp": false,
    "account_number_formats": [
      "################"
    ]
  }
  ```
</ResponseExample>


# Create Token
Source: https://docs.methodfi.com/2026-03-30/reference/opal/create_token

POST /opal/token

Opal tokens are used as the starting point and authentication key to instantiate
Method's embeddable UI components within your experience.

<Note>
  For security purposes, Opal tokens are for one-time use only, and expire after
  30 minutes.
</Note>

## Body

The structure of the request body differs slightly depending on the Opal mode you are trying to use. See the [Opal Modes](/opal/identity/overview) section for more information about specific modes.

<Note>
  Only `entity_id` or `entity` is required. If both are provided, `entity_id`
  will be ignored.
</Note>

<ParamList />

## Mode parameters

<Tabs>
  <Tab title="Identity Verification">
    <ParamList />
  </Tab>

  <Tab title="Connect">
    <ParamList />
  </Tab>

  <Tab title="Card Connect">
    <ParamList />
  </Tab>

  <Tab title="Account Verification">
    <ParamList />
  </Tab>

  <Tab title="Transactions">
    <ParamList />
  </Tab>
</Tabs>

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/opal/token \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "entity_id": "ent_fc92i43kc34",
      "mode": "identity_verification",
      "identity_verification": {
        "skip_pii": ["name", "dob", "address"]
      }
    }'

  ```

  ```javascript Node.js theme={null}
  const token = await method.opal.token.create({
    entity_id: "ent_fc92i43kc34",
    mode: "identity_verification",
    identity_verification: {
      skip_pii: ["name", "dob", "address"],
    },
  });
  ```

  ```python Python theme={null}
  token = method.opal.token.create({
    'entity_id': 'ent_fc92i43kc34',
    'mode': 'identity_verification',
    'identity_verification': {
      'skip_pii': ['name', 'dob', 'address']
    }
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "token": "otkn_THpBacqVBBrDkfqUf9htjm4QWAEJLY9a",
      "valid_until": "2025-05-08T22:21:40.312Z",
      "session_id": "osess_zde3mW34pEHqV"
    },
    "message": null
  }
  ```
</ResponseExample>


# List Opal Events
Source: https://docs.methodfi.com/2026-03-30/reference/opal/list_events

GET /opal/events

Opal emits a variety of events throughout the user session to indicate progress, completion, errors, and important milestones.
Events are stored in real-time and can be used to update your UI, trigger additional actions, or perform analytics.

<Note>
  Events are on a per-token basis. You must pass in the token that you want to
  retrieve events for. Token expiration does not affect event availability.
</Note>

## All Events

Please see [Opal Events](/opal/events) for a list of all events and when they are typically emitted.

***

<RequestExample>
  ```bash cURL theme={null}
    curl "https://production.methodfi.com/opal/events" \
      -X GET \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer otkn_EAbNWUinQXnwENcqWyGfKAemHGnqtbqh"
  ```

  ```javascript Node.js theme={null}
  const response = await method.opal.events.list(
    "otkn_EAbNWUinQXnwENcqWyGfKAemHGnqtbqh"
  );
  ```

  ```python Python theme={null}
  response = method.opal.events.list(
    "otkn_EAbNWUinQXnwENcqWyGfKAemHGnqtbqh"
  )
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "type": "card_connect.card.verified",
        "mode": "card_connect",
        "object": "card",
        "action": "verified",
        "timestamp": "2025-06-10T22:50:53.024Z",
        "data": {
          "account": "acc_ge9hxMTPGdXmQ"
        }
      },
      {...}
    ]
  }
  ```
</ResponseExample>


# The Opal endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/opal/overview



Method Opal is the single embeddable UI component that provides enhanced financial connectivity and user experience. Opal serves as a modern replacement for [Method Elements](/elements/overview), offering improved performance, better customization, and advanced features for integrating Method's API into your application.

## Authentication

All Opal endpoints require authentication using your Method API key.

```bash theme={null}
curl https://production.methodfi.com/opal/token \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

### Response:

```json theme={null}
{
  "success": true,
  "data": {
    "token": "otkn_THpBacqVBBrDkfqUf9htjm4QWAEJLY9a",
    "valid_until": "2025-05-08T22:21:40.312Z",
    "session_id": "osess_zde3mW34pEHqV"
  },
  "message": null
}
```

Refer to the [Create Token](/2026-03-30/reference/opal/create_token) section for more info on what properties can be passed in and how modes work.

## Sessions

Sessions allow you to resume a user's journey through Opal, while maintaining the user's data and progress. Sessions are long-lived stateful connections that allows a user to leave and resume their journey through Opal while maintaining the user’s data and progress.
Tokens are short-lived identifiers that initialize the Opal flow.

See [Opal Sessions](/opal/sessions) for more information.

## Environments

Opal can be launched from all Method environments:

| Environment | Opal URL                               |
| ----------- | -------------------------------------- |
| Development | `https://opal.dev.methodfi.com`        |
| Sandbox     | `https://opal.sandbox.methodfi.com`    |
| Production  | `https://opal.production.methodfi.com` |

Or, launch Opal from your app using one of our [libraries](/opal/libraries).


# Create a Payment
Source: https://docs.methodfi.com/2026-03-30/reference/payments/create

POST /payments

Creates a new Payment object.

Payments are transmitted electronically by pulling funds from a source Account,
and sending those funds to a destination Account. Payments are posted to the
destination Account (settled) in 1-3 business days but may vary per
FI (Financial Institution).

## Body

<ParamList />

## Returns

Returns a Payment object. The Payment will be sent based on the cutoff
times. The `status` of the Payment will be updated when the Payment is
sent to our banking networks.
For a dry run payment, no actual payment will be sent.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/payments \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 5000,
      "source": "acc_hmap9mbgfLcf9",
      "destination": "acc_YXDrjADGjC76U",
      "description": "Loan Pmt",
      "reversal_account": "acc_3YPBwaEmTAf4K"
    }'
  ```

  ```javascript Node.js theme={null}
  const payment = await method.payments.create({
    amount: 5000,
    source: 'acc_hmap9mbgfLcf9',
    destination: 'acc_YXDrjADGjC76U',
    description: 'Loan Pmt',
    reversal_account: "acc_3YPBwaEmTAf4K"
  });
  ```

  ```python Python theme={null}
  payment = method.payments.create({
    'amount': 5000,
    'source': 'acc_hmap9mbgfLcf9',
    'destination': 'acc_YXDrjADGjC76U',
    'description': 'Loan Pmt',
    'reversal_account': 'acc_3YPBwaEmTAf4K'
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "pmt_VeCfmkwGKb",
    "source": "acc_hmap9mbgfLcf9",
    "destination": "acc_YXDrjADGjC76U",
    "amount": 5000,
    "description": "Loan Pmt",
    "status": "pending",
    "estimated_completion_date": "2024-03-21",
    "source_trace_id": null,
    "source_settlement_date": "2024-03-15",
    "source_status": "pending",
    "destination_trace_id": null,
    "destination_settlement_date": "2024-03-21",
    "destination_posted_date": null,
    "destination_status": "pending",
    "reversal_id": null,
    "reversal_account": "acc_3YPBwaEmTAf4K",
    "payment_instrument": null,
    "fee": null,
    "type": "standard",
    "error": null,
    "metadata": null,
    "created_at": "2024-03-14T16:15:26.074Z",
    "updated_at": "2024-03-14T16:15:26.074Z"
  }
  ```
</ResponseExample>


# Delete a Payment
Source: https://docs.methodfi.com/2026-03-30/reference/payments/delete

DELETE /payments/{pmt_id}

Deleting a Payment means canceling it before any funds
have been moved.

<Warning>
  A Payment can be deleted only if its status is <code>pending</code>.
</Warning>

## Path Parameters

<ParamList />

## Returns

Returns the successfully deleted Payment with its
status set to `canceled`.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/payments/pmt_VeCfmkwGKb \
    -X DELETE \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const payment = await method.payments.delete('pmt_VeCfmkwGKb');
  ```

  ```python Python theme={null}
  payment = method.payments.delete('pmt_VeCfmkwGKb')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "pmt_VeCfmkwGKb",
    "source": "acc_hmap9mbgfLcf9",
    "destination": "acc_YXDrjADGjC76U",
    "amount": 5000,
    "description": "Loan Pmt",
    "status": "canceled",
    "estimated_completion_date": "2024-03-21",
    "source_trace_id": null,
    "source_settlement_date": "2024-03-15",
    "source_status": "canceled",
    "destination_trace_id": null,
    "destination_settlement_date": "2024-03-21",
    "destination_posted_date": null,
    "destination_status": "canceled",
    "reversal_id": null,
    "reversal_account": "acc_hmap9mbgfLcf9",
    "payment_instrument": null,
    "fee": null,
    "type": "standard",
    "error": null,
    "metadata": null,
    "created_at": "2024-03-14T16:15:26.074Z",
    "updated_at": "2024-03-14T16:15:26.074Z"
  }
  ```
</ResponseExample>


# List all Payments
Source: https://docs.methodfi.com/2026-03-30/reference/payments/list

GET /payments

Returns a list of Payment objects.

## Query Parameters

<ParamList />

## Returns

Returns a list of Payment objects.

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/payments?from_date=2024-03-13&to_date=2024-03-15&status=pending" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const payments = await method.payments.list({
    from_date: '2024-03-13',
    to_date: '2024-03-15',
    status: 'pending',
  });
  ```

  ```python Python theme={null}
  payments = method.payments.list({
    'from_date': '2024-03-13',
    'to_date': '2024-03-15',
    'status': 'pending'
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "id": "pmt_VeCfmkwGKb",
        "source": "acc_hmap9mbgfLcf9",
        "destination": "acc_YXDrjADGjC76U",
        "amount": 5000,
        "description": "Loan Pmt",
        "status": "processing",
        "estimated_completion_date": "2024-03-21",
        "source_trace_id": "203942084920",
        "source_settlement_date": "2024-03-15",
        "source_status": "sent",
        "destination_trace_id": "304820184832",
        "destination_settlement_date": "2024-03-21",
        "destination_posted_date": null,
        "destination_status": "processing",
        "destination_payment_method": "electronic",
        "reversal_id": null,
        "reversal_account": "acc_hmap9mbgfLcf9",
        "payment_instrument": null,
        "fee": null,
        "type": "standard",
        "error": null,
        "metadata": null,
        "created_at": "2024-03-14T16:15:26.074Z",
        "updated_at": "2024-03-14T16:15:26.074Z"
      }
    ]
  }
  ```
</ResponseExample>


# The payment endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/payments/overview



A Payment is the transfer of funds from a source checking or savings bank account to a
destination credit card, auto loan, mortgage, student loan, and more.

All Payments are processed electronically between the source and
destination, and take 2-3 business days depending on the
receiving financial institution.

#### Cutoff Times

Payments are processed on business days (Monday - Friday),
excluding US Banking Holidays.

<ul>
  <li>Method Debit Model processing window: 1:30 PM CT</li>
  <li>Prefunded Model processing window: 3:30 PM CT</li>
</ul>

## Payment Objects

<ParamList />

<RequestExample>
  ```json THE PAYMENT OBJECT theme={null}
  {
    "id": "pmt_VeCfmkwGKb",
    "source": "acc_hmap9mbgfLcf9",
    "destination": "acc_YXDrjADGjC76U",
    "amount": 5000,
    "description": "Loan Pmt",
    "status": "posted",
    "estimated_completion_date": "2024-03-21",
    "source_trace_id": "203942084920",
    "source_settlement_date": "2024-03-15",
    "source_status": "sent",
    "destination_trace_id": "304820184832",
    "destination_settlement_date": "2024-03-21",
    "destination_posted_date": "2024-03-21",
    "destination_status": "posted",
    "destination_payment_method": "electronic",
    "reversal_id": null,
    "reversal_account": "acc_hmap9mbgfLcf9",
    "payment_instrument": null,
    "fee": null,
    "type": "standard",
    "fund_status": "posted",
    "error": null,
    "metadata": null,
    "created_at": "2024-03-14T16:15:26.074Z",
    "updated_at": "2024-03-14T16:15:26.074Z"
  }
  ```
</RequestExample>


# Retrieve a Payment
Source: https://docs.methodfi.com/2026-03-30/reference/payments/retrieve

GET /payments/{pmt_id}

Retrieve details of an existing Payment.

## Path Parameters

<ParamList />

## Returns

Returns the corresponding Payment if it exists.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/payments/pmt_VeCfmkwGKb \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const payment = await method.payments.retrieve('pmt_VeCfmkwGKb');
  ```

  ```python Python theme={null}
  payment = method.payments.retrieve('pmt_VeCfmkwGKb')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "pmt_VeCfmkwGKb",
    "source": "acc_hmap9mbgfLcf9",
    "destination": "acc_YXDrjADGjC76U",
    "amount": 5000,
    "description": "Loan Pmt",
    "status": "posted",
    "estimated_completion_date": "2024-03-21",
    "source_trace_id": "203942084920",
    "source_settlement_date": "2024-03-15",
    "source_status": "sent",
    "destination_trace_id": "304820184832",
    "destination_settlement_date": "2024-03-21",
    "destination_posted_date": "2024-03-21",
    "destination_status": "posted",
    "destination_payment_method": "electronic",
    "reversal_id": null,
    "reversal_account": "acc_hmap9mbgfLcf9",
    "payment_instrument": null,
    "fee": null,
    "type": "standard",
    "fund_status": "posted",
    "error": null,
    "metadata": null,
    "created_at": "2024-03-14T16:15:26.074Z",
    "updated_at": "2024-03-21T12:00:00.000Z"
  }
  ```
</ResponseExample>


# Create Preauth Signals
Source: https://docs.methodfi.com/2026-03-30/reference/preauth/create

POST /preauth

Computes a PreauthSignals assessment for a given card or account. Provide either
an `account_id` for an authenticated Method Account, or a `card` object with raw card
identifiers. Optionally include `purchase` context to improve the prediction.

<Note>
  Exactly one of `account_id` or `card` is required. Providing both will return a `400` error.
</Note>

## Body

<ParamList />

## Returns

Returns a PreauthSignals object.

<br />

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/preauth \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "card": {
        "bin6": "411111",
        "last4": "1234",
        "first_name": "Jane",
        "last_name": "Doe",
        "phone": "+15555555555",
        "zip": "10001"
      },
      "purchase": {
        "amount": 9999,
        "mcc": "4511",
        "ip_address": "203.0.113.42",
        "txn_time": "2026-05-28T14:00:00Z"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const preauth = await method
    .preauth
    .create({
      card: {
        bin6: '411111', last4: '1234',
        first_name: 'Jane', last_name: 'Doe',
        phone: '+15555555555',
        zip: '10001',
      },
      purchase: {
        amount: 9999, mcc: '4511',
        ip_address: '203.0.113.42',
        txn_time: '2026-05-28T14:00:00Z',
      },
    });
  ```

  ```python Python theme={null}
  preauth = method.preauth.create({
    'card': {
      'bin6': '411111', 'last4': '1234',
      'first_name': 'Jane', 'last_name': 'Doe',
      'phone': '+15555555555',
      'zip': '10001'
    },
    'purchase': {
      'amount': 9999, 'mcc': '4511',
      'ip_address': '203.0.113.42',
      'txn_time': '2026-05-28T14:00:00Z'
    }
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "preauth_qV7kRaFm4JNxw",
    "account_id": "acc_4m9amk4KFiaQX",
    "status": "completed",
    "verified_ownership": "match",
    "card_standing": "open",
    "success_likelihood": 0.87,
    "optimal_retry_date": "2026-06-02",
    "error": null,
    "metadata": null,
    "created_at": "2026-05-28T14:00:00.000Z",
    "updated_at": "2026-05-28T14:00:00.180Z"
  }
  ```
</ResponseExample>


# List all Preauth Signals records
Source: https://docs.methodfi.com/2026-03-30/reference/preauth/list

GET /preauth

Retrieves a list of PreauthSignals records.

## Query Parameters

<ParamList />

## Returns

Returns a list of PreauthSignals objects.

<br />

<RequestExample>
  ```bash cURL theme={null}
  curl "https://production.methodfi.com/preauth?page_limit=10" \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method.preauth.list({ page_limit: 10 });
  ```

  ```python Python theme={null}
  response = method.preauth.list({ 'page_limit': 10 })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "id": "preauth_qV7kRaFm4JNxw",
        "account_id": "acc_4m9amk4KFiaQX",
        "status": "completed",
        "verified_ownership": "match",
        "card_standing": "open",
        "success_likelihood": 0.87,
        "optimal_retry_date": "2026-06-02",
        "error": null,
        "metadata": null,
        "created_at": "2026-05-28T14:00:00.000Z",
        "updated_at": "2026-05-28T14:00:00.180Z"
      }
    ]
  }
  ```
</ResponseExample>


# The preauth signals endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/preauth/overview



The PreauthSignals endpoint returns the predicted likelihood that a transaction
will succeed, alongside verified ownership of the card and recommended retry timing.
It accepts either an authenticated Method Account or raw card data, with optional
purchase context to improve the prediction.

<Note>
  **Public preview.** PreauthSignals is in public preview. Contact your Method CSM to request access.
</Note>

## Data access

The fields returned by PreauthSignals are split across two tiers:

* **Identifier-based fields** — `verified_ownership` and `card_standing` run entirely on the identifiers passed in the request (an `account_id`, or `card.bin6`, `card.last4`, `card.first_name`, `card.last_name`, and `card.phone`) and return a match result and the card's open/closed status. **Available to all customers by default**, with no additional data access required.
* **Predictive components** — `success_likelihood` and `optimal_retry_date` depend on richer underlying data that not every customer is provisioned for. When the required data is not available, the endpoint returns `null` as the value for both `success_likelihood` and `optimal_retry_date`. This is a normal response state, not an error or a fallback.

**The PreauthSignals endpoint is available as a:**

| Type      | Use-Case                                                                   |
| --------- | -------------------------------------------------------------------------- |
| `Product` | On-Demand assessment of a transaction attempt for a given card or account. |

## PreauthSignals Object

<ParamList />

<RequestExample>
  ```json The PreauthSignals Object theme={null}
  {
    "id": "preauth_qV7kRaFm4JNxw",
    "account_id": "acc_4m9amk4KFiaQX",
    "status": "completed",
    "verified_ownership": "match",
    "card_standing": "open",
    "success_likelihood": 0.87,
    "optimal_retry_date": "2026-06-02",
    "error": null,
    "metadata": null,
    "created_at": "2026-05-28T14:00:00.000Z",
    "updated_at": "2026-05-28T14:00:00.180Z"
  }
  ```
</RequestExample>


# Retrieve Preauth Signals
Source: https://docs.methodfi.com/2026-03-30/reference/preauth/retrieve

GET /preauth/{preauth_id}

Retrieves a PreauthSignals record by ID.

## Path Parameters

<ParamList />

## Returns

Returns a PreauthSignals object.

<br />

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/preauth/preauth_qV7kRaFm4JNxw \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const preauth = await method.preauth.retrieve('preauth_qV7kRaFm4JNxw');
  ```

  ```python Python theme={null}
  preauth = method.preauth.retrieve('preauth_qV7kRaFm4JNxw')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "preauth_qV7kRaFm4JNxw",
    "account_id": "acc_4m9amk4KFiaQX",
    "status": "completed",
    "verified_ownership": "match",
    "card_standing": "open",
    "success_likelihood": 0.87,
    "optimal_retry_date": "2026-06-02",
    "error": null,
    "metadata": null,
    "created_at": "2026-05-28T14:00:00.000Z",
    "updated_at": "2026-05-28T14:00:00.180Z"
  }
  ```
</ResponseExample>


# Create a Report Schedule
Source: https://docs.methodfi.com/2026-03-30/reference/report-schedules/create

POST /report_schedules

Creates a new active Report Schedule for a single supported Report `type`.
Once created, the schedule runs on Method's standard cadence for that type.
See <a href="/2026-03-30/reference/report-schedules/overview#supported-report-types">Supported Report Types.</a>

A team can only have one active schedule per `type` — creating a duplicate
returns an error.

## Body

<ParamList />

## Returns

Returns the newly created Report Schedule object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/report_schedules \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "payments.created.previous_day",
      "email_recipients": ["reports@example.com"]
    }'
  ```

  ```javascript Node.js theme={null}
  const reportSchedule = await method.reportSchedules.create({
    type: 'payments.created.previous_day',
    email_recipients: ['reports@example.com'],
  });
  ```

  ```python Python theme={null}
  report_schedule = method.report_schedules.create({
    'type': 'payments.created.previous_day',
    'email_recipients': ['reports@example.com']
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "rpt_sch_Gqjh8pzeUfzH6",
    "type": "payments.created.previous_day",
    "email_recipients": [
      "reports@example.com"
    ],
    "status": "active",
    "created_at": "2026-06-01T13:21:10.386Z",
    "updated_at": "2026-06-01T13:21:10.386Z"
  }
  ```
</ResponseExample>


# Delete a Report Schedule
Source: https://docs.methodfi.com/2026-03-30/reference/report-schedules/delete

DELETE /report_schedules/{schedule_id}

Deletes a Report Schedule. The schedule's `status` is set to `inactive`
and no further reports will be generated or delivered. This route is
idempotent — deleting a schedule that doesn't exist still returns a
successful, empty response.

## Path Parameters

<ParamList />

## Returns

Returns an empty response.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/report_schedules/rpt_sch_Gqjh8pzeUfzH6 \
    -X DELETE \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  await method.reportSchedules.delete('rpt_sch_Gqjh8pzeUfzH6');
  ```

  ```python Python theme={null}
  method.report_schedules.delete('rpt_sch_Gqjh8pzeUfzH6')
  ```
</RequestExample>


# List all Report Schedules
Source: https://docs.methodfi.com/2026-03-30/reference/report-schedules/list

GET /report_schedules

Returns all the active Report Schedules associated with your team,
or an empty array if none have been created.

## Path Parameters

<ParamList />

## Returns

Returns a list of Report Schedule objects.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/report_schedules \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const reportSchedules = await method.reportSchedules.list();
  ```

  ```python Python theme={null}
  report_schedules = method.report_schedules.list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "id": "rpt_sch_Gqjh8pzeUfzH6",
        "type": "payments.created.previous_day",
        "email_recipients": [
          "reports@example.com"
        ],
        "status": "active",
        "created_at": "2026-06-01T13:21:10.386Z",
        "updated_at": "2026-06-01T13:21:10.386Z"
      }
    ]
  }
  ```
</ResponseExample>


# The report schedules endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/report-schedules/overview



Report schedules automate recurring generation of a single Report `type`. Each scheduled run creates a Report the same way <a href="/2026-03-30/reference/reports/create">Create a Report</a> does, so it follows normal Report persistence and triggers the standard `report.create` webhook. If `email_recipients` are configured, Method also emails the CSV for that generated Report.

Method owns the run cadence for each supported type — the `cron` value is not configurable.

## Report Schedule Objects

<ParamList />

#### Supported Report Types

| Name                                 | Cadence                                 |
| ------------------------------------ | --------------------------------------- |
| `ach.pull.nightly`                   | Business days at 8:00am America/Chicago |
| `ach.reversals.nightly`              | Business days at 8:00am America/Chicago |
| `entities.created.previous_day`      | Business days at 8:00am America/Chicago |
| `payments.created.previous_day`      | Business days at 8:00am America/Chicago |
| `payments.failed.previous_day`       | Business days at 8:00am America/Chicago |
| `reversals.pull_funded.previous_day` | Business days at 8:00am America/Chicago |
| `reversals.push_funded.previous_day` | Business days at 8:00am America/Chicago |

<Note>
  A team can only have one active schedule per `type`. Non-business-day runs are skipped; the next run picks up at the following scheduled business day.
</Note>

<RequestExample>
  ```json THE REPORT SCHEDULE OBJECT theme={null}
  {
    "id": "rpt_sch_Gqjh8pzeUfzH6",
    "type": "payments.created.previous_day",
    "email_recipients": [
      "reports@example.com"
    ],
    "status": "active",
    "created_at": "2026-06-01T13:21:10.386Z",
    "updated_at": "2026-06-01T13:21:10.386Z"
  }
  ```
</RequestExample>


# Retrieve a Report Schedule
Source: https://docs.methodfi.com/2026-03-30/reference/report-schedules/retrieve

GET /report_schedules/{schedule_id}

Returns the Report Schedule object associated with the ID.

## Path Parameters

<ParamList />

## Returns

Returns the Report Schedule object associated with the ID.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/report_schedules/rpt_sch_Gqjh8pzeUfzH6 \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const reportSchedule = await method.reportSchedules.retrieve('rpt_sch_Gqjh8pzeUfzH6');
  ```

  ```python Python theme={null}
  report_schedule = method.report_schedules.retrieve('rpt_sch_Gqjh8pzeUfzH6')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "rpt_sch_Gqjh8pzeUfzH6",
    "type": "payments.created.previous_day",
    "email_recipients": [
      "reports@example.com"
    ],
    "status": "active",
    "created_at": "2026-06-01T13:21:10.386Z",
    "updated_at": "2026-06-01T13:21:10.386Z"
  }
  ```
</ResponseExample>


# Update a Report Schedule
Source: https://docs.methodfi.com/2026-03-30/reference/report-schedules/update

PUT /report_schedules/{schedule_id}

Replaces the `email_recipients` on an existing Report Schedule. The
`type` of a Report Schedule cannot be updated.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns the updated Report Schedule object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/report_schedules/rpt_sch_Gqjh8pzeUfzH6 \
    -X PUT \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "email_recipients": ["ops@example.com", "reports@example.com"]
    }'
  ```

  ```javascript Node.js theme={null}
  const reportSchedule = await method.reportSchedules.update('rpt_sch_Gqjh8pzeUfzH6', {
    email_recipients: ['ops@example.com', 'reports@example.com'],
  });
  ```

  ```python Python theme={null}
  report_schedule = method.report_schedules.update('rpt_sch_Gqjh8pzeUfzH6', {
    'email_recipients': ['ops@example.com', 'reports@example.com']
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "rpt_sch_Gqjh8pzeUfzH6",
    "type": "payments.created.previous_day",
    "email_recipients": [
      "ops@example.com",
      "reports@example.com"
    ],
    "status": "active",
    "created_at": "2026-06-01T13:21:10.386Z",
    "updated_at": "2026-06-01T13:24:42.118Z"
  }
  ```
</ResponseExample>


# Create a Report
Source: https://docs.methodfi.com/2026-03-30/reference/reports/create

POST /reports

Creates a new Report for a specific `type`. Once created, you
can retrieve the Report results from the URL returned.

## Path Parameters

<ParamList />

## Returns

Returns a Report object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/reports \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "payments.created.current"
    }'
  ```

  ```javascript Node.js theme={null}
  const report = await method.reports.create({ type: 'payments.created.current' });
  ```

  ```python Python theme={null}
  report = method.reports.create({ 'type': 'payments.created.current' })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "rpt_cj2mkA3hFyHT5",
    "type": "payments.created.current",
    "url": "https://production.methodfi.com/reports/rpt_cj2mkA3hFyHT5/download",
    "status": "completed",
    "metadata": null,
    "created_at": "2021-08-25T23:18:05.261Z",
    "updated_at": "2021-08-25T23:18:05.261Z"
  }
  ```
</ResponseExample>


# Download a Report
Source: https://docs.methodfi.com/2026-03-30/reference/reports/download

GET /reports/{rpt_id}/download

Returns the results of the Report associated with the ID.

## Path Parameters

<ParamList />

## Returns

Returns the Report's results in CSV format.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/reports/rpt_cj2mkA3hFyHT5/download \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const reportCSV = await method.reports.download('rpt_cj2mkA3hFyHT5');
  ```

  ```python Python theme={null}
  report_csv = method.reports.download('rpt_cj2mkA3hFyHT5')
  ```
</RequestExample>


# The report endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/reports/overview



Reports provide a filtered snapshot view of a specific
resource. Method provides a fixed set of filters (<a href="#report-types">Report Types</a>)
which include the following:

* The resource to filter
* The applied filter
* The snapshot window

## Report Objects

<ParamList />

#### Report Types

| Name                                       |
| ------------------------------------------ |
| `ach.pull.nightly`                         |
| `ach.pull.previous`                        |
| `ach.pull.upcoming`                        |
| `ach.reversals.nightly`                    |
| `entities.created.previous_day`            |
| `payments.created.current`                 |
| `payments.created.previous`                |
| `payments.created.previous_day`            |
| `payments.failed.previous_day`             |
| `payments.outstanding_itemized.daily`      |
| `payments.outstanding_itemized.pull_daily` |
| `payments.outstanding_itemized.pull_total` |
| `payments.outstanding_itemized.push_daily` |
| `payments.outstanding_itemized.push_total` |
| `payments.outstanding_itemized.total`      |
| `payments.outstanding_summary.daily`       |
| `payments.outstanding_summary.pull_daily`  |
| `payments.outstanding_summary.pull_total`  |
| `payments.outstanding_summary.push_daily`  |
| `payments.outstanding_summary.push_total`  |
| `payments.outstanding_summary.total`       |
| `payments.updated.current`                 |
| `payments.updated.previous`                |
| `reserve_fbo_balance.created.previous_day` |
| `reversals.pull_funded.previous_day`       |
| `reversals.push_funded.previous_day`       |
| `team_fbo_balance.created.previous_day`    |
| `team_fbo_bai2.created.previous_day`       |

<RequestExample>
  ```json THE REPORT OBJECT theme={null}
  {
    "id": "rpt_cj2mkA3hFyHT5",
    "type": "payments.created.current",
    "url": "https://production.methodfi.com/reports/rpt_cj2mkA3hFyHT5/download",
    "status": "completed",
    "metadata": null,
    "created_at": "2021-08-25T23:18:05.261Z",
    "updated_at": "2021-08-25T23:18:05.261Z"
  }
  ```
</RequestExample>


# Retrieve a Report
Source: https://docs.methodfi.com/2026-03-30/reference/reports/retrieve

GET /reports/{rpt_id}

Returns the Report object associated with the ID.

## Path Parameters

<ParamList />

## Returns

Returns the Report object associated with the ID.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/reports/rpt_cj2mkA3hFyHT5 \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const report = await method.reports.retrieve('rpt_cj2mkA3hFyHT5');
  ```

  ```python Python theme={null}
  report = method.reports.retrieve('rpt_cj2mkA3hFyHT5')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "rpt_cj2mkA3hFyHT5",
    "type": "payments.created.current",
    "url": "https://production.methodfi.com/reports/rpt_cj2mkA3hFyHT5/download",
    "status": "completed",
    "metadata": null,
    "created_at": "2021-08-25T23:18:05.261Z",
    "updated_at": "2021-08-25T23:18:05.261Z"
  }
  ```
</ResponseExample>


# Create a Secret
Source: https://docs.methodfi.com/2026-03-30/reference/secrets/create

POST /secrets

Creates a new Secret to securely store a sensitive value.

## Body

<ParamList />

## Returns

Returns the newly created Secret object. Note that the `value` field is not returned in the response.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/secrets \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "value": "pk_1234567890",
      "metadata": {
        "environment": "production"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const secret = await method.secrets.create({
    value: 'pk_1234567890',
    metadata: {
      environment: 'production'
    }
  });
  ```

  ```python Python theme={null}
  secret = method.secrets.create({
    'value': 'pk_1234567890',
    'metadata': {
      'environment': 'production'
    }
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "sec_au22b1fbFrmfp",
    "metadata": {
      "environment": "production"
    },
    "created_at": "2025-12-04T18:50:54.024Z",
    "updated_at": "2025-12-04T18:50:54.024Z",
    "status": "active"
  }
  ```
</ResponseExample>


# Delete a Secret
Source: https://docs.methodfi.com/2026-03-30/reference/secrets/delete

DELETE /secrets/{sec_id}

Deletes the Secret associated with the ID. This sets the status to `deleted`
and permanently removes the stored value.

## Path Parameters

<ParamList />

## Returns

Returns `200` with an empty object on success.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/secrets/sec_au22b1fbFrmfp \
    -X DELETE \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const secret = await method.secrets.delete('sec_au22b1fbFrmfp');
  ```

  ```python Python theme={null}
  secret = method.secrets.delete('sec_au22b1fbFrmfp')
  ```
</RequestExample>


# List all Secrets
Source: https://docs.methodfi.com/2026-03-30/reference/secrets/list

GET /secrets

Returns all Secrets associated with your team, or an empty array if none have been created.

## Query Parameters

<ParamList />

## Returns

Returns a list of Secret objects. The `value` field is redacted in the response.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/secrets \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const secrets = await method.secrets.list();
  ```

  ```python Python theme={null}
  secrets = method.secrets.list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "id": "sec_au22b1fbFrmfp",
        "metadata": {},
        "created_at": "2025-12-04T18:50:54.024Z",
        "updated_at": "2025-12-04T18:50:54.024Z",
        "status": "active"
      }
    ]
  }
  ```
</ResponseExample>


# The Secrets endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/secrets/overview



Secrets allow you to securely store sensitive values, such as API keys or tokens,
that can be used within your Method integration. The stored value is encrypted and
never returned in API responses after creation.

## Secret Objects

<ParamList />

<RequestExample>
  ```json THE SECRET OBJECT theme={null}
  {
    "id": "sec_au22b1fbFrmfp",
    "metadata": {
      "environment": "production"
    },
    "created_at": "2025-12-04T18:50:54.024Z",
    "updated_at": "2025-12-04T18:50:54.024Z",
    "status": "active"
  }
  ```
</RequestExample>


# Retrieve a Secret
Source: https://docs.methodfi.com/2026-03-30/reference/secrets/retrieve

GET /secrets/{sec_id}

Returns the Secret object associated with the ID.

## Path Parameters

<ParamList />

## Returns

Returns the Secret object associated with the ID. Note that the `value` field is not returned.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/secrets/sec_au22b1fbFrmfp \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const secret = await method.secrets.retrieve('sec_au22b1fbFrmfp');
  ```

  ```python Python theme={null}
  secret = method.secrets.retrieve('sec_au22b1fbFrmfp')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "sec_au22b1fbFrmfp",
    "metadata": {
      "environment": "production"
    },
    "created_at": "2025-12-04T18:50:54.024Z",
    "updated_at": "2025-12-04T18:50:54.024Z",
    "status": "active"
  }
  ```
</ResponseExample>


# Queue Attribute Behaviors
Source: https://docs.methodfi.com/2026-03-30/reference/simulations/attributes/create

POST https://dev.methodfi.com/simulate/entities/{entity_id}/attributes

Use this simulation to queue attribute behaviors that run the next time you execute the Attributes product for an entity.

<Warning>
  Simulation endpoints are only available in the development environment. Teams with live treasury access cannot use them.
</Warning>

## Path Parameters

<ParamList />

## Body

<ParamList />

<RequestExample>
  ```bash cURL theme={null}
  curl https://dev.methodfi.com/simulate/entities/{entity_id}/attributes \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "behaviors": ["new_soft_inquiry"]
      }'
  ```

  ```javascript Node.js theme={null}
  const attributesSimulationConfiguration = await method
  .simulate
  .entities(entityId)
  .attributes
  .create({
    behaviors: ["new_soft_inquiry"]
  });
  ```

  ```python Python theme={null}
  attributes_simulation_configuration = method.simulate.entities(entity_id).attributes.create({
    "behaviors": ["new_soft_inquiry"]
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": null,
    "message": null
  }
  ```
</ResponseExample>


# Create a Card Brand
Source: https://docs.methodfi.com/2026-03-30/reference/simulations/card-brands/create

POST https://dev.methodfi.com/simulate/accounts/{acc_id}/card_brands

Card Brand simulation is available for Credit Card Accounts that have been verified and are subscribed to the Card Brands product.

Simulating a Card Brand will mimic a new card brand being retrieved for a specific Account.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns the Card Brand object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://dev.methodfi.com/simulate/accounts/{acc_id}/card_brands \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "brand_id": "pdt_15_brd_1"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts(acc_id)
    .simulate
    .cardBrands
    .create({
      brand_id: "pdt_15_brd_1"
    });
  ```

  ```python Python theme={null}
  response = method
    .accounts(acc_id)
    .simulate
    .card_brands
    .create({"brand_id": "pdt_15_brd_1"})
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "cbrd_Accm7P6t6mYQP",
    "account_id": "acc_LxwEqNicr66yP",
    "brands": [
      {
        "id": "pdt_15_brd_1",
        "card_product_id": "pdt_15",
        "description": "Chase Sapphire Reserve",
        "name": "Chase Sapphire Reserve",
        "issuer": "Chase",
        "network": "visa",
        "network_tier": "infinite",
        "type": "specific",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
      }
    ],
    "status": "completed",
    "source": "method",
    "error": null,
    "created_at": "2025-08-12T00:56:50.139Z",
    "updated_at": "2025-08-12T00:56:50.139Z"
  }
  ```
</ResponseExample>


# Queue Connect Behaviors
Source: https://docs.methodfi.com/2026-03-30/reference/simulations/connect/create

POST https://dev.methodfi.com/simulate/entities/{entity_id}/connect

Use this simulation to queue connect behaviors that run the next time you execute the Connect product for an entity.

<Warning>
  Simulation endpoints are only available in the development environment. Teams with live treasury access cannot use them.
</Warning>

<Warning>
  A maximum of 5 connect behaviours can be configured for a given entity.
</Warning>

## Path Parameters

<ParamList />

## Body

<ParamList />

<RequestExample>
  ```bash cURL theme={null}
  curl https://dev.methodfi.com/simulate/entities/{entity_id}/connect \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "Content-Type: application/json" \
    -d '{
      "behaviors": ["new_credit_card_account"]
      }'
  ```

  ```javascript Node.js theme={null}
  const connectSimulationConfiguration = await method
    .simulate
    .entities(entityId)
    .connect
    .create({
      behaviors: ["new_credit_card_account"]
    });
  ```

  ```python Python theme={null}
  connect_simulation_configuration = method.simulate.entities(entity_id).connect.create({
    "behaviors": ["new_credit_card_account"]
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": null,
    "message": null
  }
  ```
</ResponseExample>


# Create a Custom Credit Score
Source: https://docs.methodfi.com/2026-03-30/reference/simulations/credit-scores/create

POST https://dev.methodfi.com/simulate/entities/{entity_id}/credit_scores/{crs_id}

Credit Score simulations allow you to update pending Credit Scores with custom responses for entities in the development environment.

<Warning>If no action is taken within 20 seconds of creating a credit score, it will automatically update with default data.</Warning>

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns the updated Credit Score object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://dev.methodfi.com/simulate/entities/{entity_id}/credit_scores/{crs_id} \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "scores": [
        {
          "score": 800,
          "source": "equifax",
          "model": "vantage_4",
          "factors": [
            {
              "code": "00034",
              "description": "Total of all balances on bankcard or revolving accounts is too high"
            },
            {
              "code": "00012",
              "description": "The date that you opened your oldest account is too recent"
            },
            {
              "code": "00063",
              "description": "Lack of sufficient relevant real estate account information"
            }
          ],
          "created_at": "2024-04-12T00:12:32.768Z"
        }
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const creditScore = await method
    .simulate
    .entities(entityId)
    .creditScores(crsId)
    .create({
      scores: [
        {
          score: 800,
          source: "equifax",
          model: "vantage_4",
          factors: [
            {
              code: "00034",
              description: "Total of all balances on bankcard or revolving accounts is too high"
            },
            {
              code: "00012",
              description: "The date that you opened your oldest account is too recent"
            },
            {
              code: "00063",
              description: "Lack of sufficient relevant real estate account information"
            }
          ],
          created_at: "2024-04-12T00:12:32.768Z"
        }
      ]
    });
  ```

  ```python Python theme={null}
  credit_score = method.simulate.entities(entity_id).credit_scores(crs_id).create({
    "scores": [
      {
        "score": 800,
        "source": "equifax",
        "model": "vantage_4",
        "factors": [
          {
            "code": "00034",
            "description": "Total of all balances on bankcard or revolving accounts is too high"
          },
          {
            "code": "00012",
            "description": "The date that you opened your oldest account is too recent"
          },
          {
            "code": "00063",
            "description": "Lack of sufficient relevant real estate account information"
          }
        ],
        "created_at": "2024-04-12T00:12:32.768Z"
      }
    ]
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "crs_pn4ca33GXFaCE",
    "entity_id": "ent_au22b1fbFJbp8",
    "status": "completed",
    "scores": [
      {
          "score": 800,
          "source": "equifax",
          "model": "vantage_4",
          "factors": [
            {
              "code": "00034",
              "description": "Total of all balances on bankcard or revolving accounts is too high"
            },
            {
              "code": "00012",
              "description": "The date that you opened your oldest account is too recent"
            },
            {
              "code": "00063",
              "description": "Lack of sufficient relevant real estate account information"
            }
          ],
          "created_at": "2024-04-12T00:12:32.768Z"
        }
    ],
    "error": null,
    "created_at": "2024-04-12T00:12:30.228Z",
    "updated_at": "2024-04-12T00:12:41.303Z"
  }
  ```
</ResponseExample>


# Simulate an Event
Source: https://docs.methodfi.com/2026-03-30/reference/simulations/events/create

POST https://dev.methodfi.com/simulate/events

Event simulation is available to test webhook handlers and event processing logic.

## Prerequisites

Some event types require specific endpoints to be called first:

* `attribute.*` events: call `POST /entities/{ent_id}/attributes` first
* `credit_score.*` events: call `POST /entities/{ent_id}/credit_scores` first
* `account.opened` events: call `POST /entities/{ent_id}/connect` first

## Request Body

### Entity Events

<ParamList />

### Account Events

<ParamList />

<RequestExample>
  ```bash cURL theme={null}
  curl https://dev.methodfi.com/simulate/events \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "credit_score.create",
      "entity_id": "ent_au22b1fbFJbp8"
    }'
  ```

  ```javascript Node.js theme={null}
  const event = await method
    .simulate
    .events
    .create({
      type: "credit_score.create",
      entity_id: "ent_au22b1fbFJbp8"
    });
  ```

  ```python Python theme={null}
  event = method.simulate.events.create({
    "type": "credit_score.create",
    "entity_id": "ent_au22b1fbFJbp8"
  })
  ```
</RequestExample>


# The simulate endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/simulations/overview



To provide a seamless integration experience with Method in the
development environment, you can simulate creations or updates for
specific resources on-demand.

This ensures that your application handles all cases for multistep
flows that would naturally occur in live environments (sandbox and production).

<Warning>
  Simulation endpoints are only accessible in the development environment. Attempts
  to access these endpoints in sandbox or production will result in a 403 Forbidden error.
</Warning>

<Note>
  Simulation endpoints are prefixed with <code>/simulate</code> and will
  be in the following format where <code>RESOURCE\_NAME</code> refers any
  resource that supports simulations.
</Note>

<RequestExample>
  ```bash ENDPOINT STRUCTURE theme={null}
  https://dev.methodfi.com/simulate/<RESOURCE_NAME>
  ```
</RequestExample>


# Create a Payment Instrument
Source: https://docs.methodfi.com/2026-03-30/reference/simulations/payment_instruments/create

POST https://dev.methodfi.com/simulate/payments/payment_instruments/{pmt_inst_id}

Simulates sending funds to the `inbound_achwire_payment` Payment Instrument to create a Payment.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns a Payment object that is in `processing` status.

<RequestExample>
  ```bash cURL theme={null}
  curl https://dev.methodfi.com/simulate/payments/payment_instruments/pmt_inst_pd788hPVhLT37 \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 5000,
      "description": "Loan Pmt"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "pmt_rPrDPEwyCVUcm",
    "reversal_id": null,
    "source_trace_id": null,
    "destination_trace_id": null,
    "source": "acc_JMJZT6r7iHi8e",
    "destination": "acc_AXthnzpBnxxWP",
    "amount": 5000,
    "description": "Loan Pmt",
    "status": "processing",
    "error": null,
    "metadata": null,
    "estimated_completion_date": "2025-12-11",
    "source_settlement_date": "2025-12-09",
    "destination_settlement_date": "2025-12-11",
    "created_at": "2025-12-09T00:42:31.209Z",
    "updated_at": "2025-12-09T00:43:30.996Z"
  }
  ```
</ResponseExample>


# Update a Payment's Status
Source: https://docs.methodfi.com/2026-03-30/reference/simulations/payments/update

POST https://dev.methodfi.com/simulate/payments/{pmt_id}

Updates a Payment's status.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns a Payment object with the updated status.

<RequestExample>
  ```bash cURL theme={null}
  curl https://dev.methodfi.com/simulate/payments/pmt_rPrDPEwyCVUcm \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "processing"
    }'
  ```

  ```javascript Node.js theme={null}
  const payment = await method
    .simulate
    .payments
    .update('pmt_rPrDPEwyCVUcm', { status: 'processing' });
  ```

  ```python Python theme={null}
  payment = method
    .simulate
    .payments
    .update('pmt_rPrDPEwyCVUcm', { 'status': 'processing' })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "pmt_rPrDPEwyCVUcm",
    "reversal_id": null,
    "source_trace_id": null,
    "destination_trace_id": null,
    "source": "acc_JMJZT6r7iHi8e",
    "destination": "acc_AXthnzpBnxxWP",
    "amount": 5000,
    "description": "Loan Pmt",
    "status": "processing",
    "error": null,
    "metadata": null,
    "estimated_completion_date": "2020-12-11",
    "source_settlement_date": "2020-12-09",
    "destination_settlement_date": "2020-12-11",
    "created_at": "2020-12-09T00:42:31.209Z",
    "updated_at": "2020-12-09T00:43:30.996Z"
  }
  ```
</ResponseExample>


# Create a Transaction
Source: https://docs.methodfi.com/2026-03-30/reference/simulations/transactions/create

POST https://dev.methodfi.com/simulate/accounts/{acc_id}/transactions

Transaction simulation is available for Credit Card Accounts that have been verified and are subscribed to the Transactions product.

Simulating a Transaction will mimic a new transaction created by the credit card networks for a specific Account.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns the Transaction object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://dev.methodfi.com/simulate/accounts/{acc_id}/transactions \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "purchase"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .accounts(acc_id)
    .simulate
    .transactions
    .create({
      type: "purchase"
    });
  ```

  ```python Python theme={null}
  response = method
    .accounts(acc_id)
    .simulate
    .transactions
    .create({"type": "purchase"})
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "txn_t73AdHRFYwhT9",
    "account_id": "acc_XtKTpHLGhD9Qn",
    "status": "posted",
    "descriptor": "SQ *BENNU COFFEE",
    "merchant": null,
    "merchant_category_code": "5441",
    "amount": 3764,
    "auth_amount": 3764,
    "currency_code": "USD",
    "transaction_amount": 3764,
    "transaction_auth_amount": 3764,
    "transaction_currency_code": "USD",
    "transacted_at": "2025-03-05T07:48:06.000Z",
    "posted_at": "2025-03-06T05:00:00.000Z",
    "voided_at": null,
    "original_txn_id": null,
    "created_at": "2025-03-24T03:54:29.283Z",
    "updated_at": "2025-03-24T04:04:39.200Z"
  }
  ```
</ResponseExample>


# Retrieve Micro-deposit Amounts
Source: https://docs.methodfi.com/2026-03-30/reference/simulations/verification-sessions/get-microdeposit-amounts

GET https://dev.methodfi.com/simulate/accounts/{acc_id}/verification_sessions/{avf_id}/amounts

Retrieves the micro-deposit amounts for an AccountVerificationSession in the development environment.

This endpoint is used to get the exact amounts of micro-deposits sent to an account, which are needed to complete the verification process.

<Warning>
  This endpoint is only accessible in the development environment. Attempts to access this endpoint in sandbox or production will result in a 403 Forbidden error.
</Warning>

## Path Parameters

<ParamList />

## Returns

Returns an object containing the micro-deposit amounts array.

<RequestExample>
  ```bash cURL theme={null}
  curl https://dev.methodfi.com/simulate/accounts/acc_yVf3mkzbhz9tj/verification_sessions/avf_yBQQNKmjRBTqF/amounts \
    -X GET \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const amounts = await method
    .simulate
    .accounts('acc_yVf3mkzbhz9tj')
    .verificationSessions
    .getMicroDepositAmounts('avf_yBQQNKmjRBTqF');
  ```

  ```python Python theme={null}
  amounts = method \
    .simulate \
    .accounts('acc_yVf3mkzbhz9tj') \
    .verification_sessions \
    .get_micro_deposit_amounts('avf_yBQQNKmjRBTqF')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "amounts": [10, 4]
    },
    "message": null
  }
  ```
</ResponseExample>


# Create MLE Public Key
Source: https://docs.methodfi.com/2026-03-30/reference/teams/mle/create

POST /teams/mle/public_keys

Creates a new public key registration for Message Level Encryption. You can register your key using either direct registration (providing the JWK directly) or well-known endpoint registration (providing a URL where Method can fetch your JWKS).

<Note>
  Each key ID (`kid`) can only be registered once. Choose either direct or well-known registration for each unique key.
</Note>

## Body

<ParamList />

## Well-Known Endpoint Requirements

If using `type: "well_known"`, your endpoint must return a JWKS that meets these requirements:

1. Must have a top-level field named `keys` that has a list as its value.
2. For a JWK (an item in list of `keys`) to be valid the following must be met:
   1. JWK must be an object
   2. JWK must have a field named `kty` and it must be equal to `RSA`
   3. JWK must have a field `n` and it must be a string that is valid `n` for a JWK in accordance to the RFC
   4. JWK must have a field `e` and it must be a string that is valid `e` for a JWK in accordance to the RFC
   5. JWK can optionally have a field named `alg` but if it is provided the value must be `RSA-OAEP-256`
   6. JWK must have a field `kid` and it must be a string that is a valid `id` which will be passed as `cid` when making requests to Method

## Returns

Returns the created public key registration object with an assigned ID and active status.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/teams/mle/public_keys \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "direct",
      "contact": "security@yourcompany.com",
      "jwk": {
        "kid": "your-unique-key-id",
        "kty": "RSA",
        "alg": "RSA-OAEP-256",
        "use": "enc",
        "n": "s3C9N7Vz...J7c",
        "e": "AQAB"
      },
      "well_known_endpoint": null
    }'
  ```

  ```javascript Node.js theme={null}
  const key = await method.teams.mle.publicKeys.create({
    type: 'direct',
    contact: 'security@yourcompany.com',
    jwk: {
      kid: 'your-unique-key-id',
      kty: 'RSA',
      alg: 'RSA-OAEP-256',
      use: 'enc',
      n: 's3C9N7Vz...J7c',
      e: 'AQAB'
    },
    well_known_endpoint: null
  });
  ```

  ```python Python theme={null}
  key = method.teams.mle.public_keys.create({
    'type': 'direct',
    'contact': 'security@yourcompany.com',
    'jwk': {
      'kid': 'your-unique-key-id',
      'kty': 'RSA',
      'alg': 'RSA-OAEP-256',
      'use': 'enc',
      'n': 's3C9N7Vz...J7c',
      'e': 'AQAB'
    },
    'well_known_endpoint': None
  })
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "team_jwk_12345", 
      "type": "direct",
      "jwk": {
        "kid": "your-unique-key-id", 
        "kty": "RSA",
        "alg": "RSA-OAEP-256",
        "use": "enc",
        "n": "s3C9N7Vz...J7c",
        "e": "AQAB"
      },
      "well_known_endpoint": null,
      "status": "active",
      "contact": "security@yourcompany.com",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    "message": null
  }
  ```
</ResponseExample>


# Delete MLE Public Key
Source: https://docs.methodfi.com/2026-03-30/reference/teams/mle/delete

DELETE /teams/mle/public_keys/{id}

Deletes (disables) a specific public key registration. Once deleted, the key cannot be used for encryption or decryption operations.

<Warning>
  This action cannot be undone. Once a key is deleted, it will be permanently disabled and cannot be reactivated.
</Warning>

## Path Parameters

<ParamList />

## Returns

Returns the deleted public key registration object with status changed to `disabled`.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/teams/mle/public_keys/team_jwk_12345 \
    -X DELETE \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const key = await method.teams.mle.publicKeys.delete('team_jwk_12345');
  ```

  ```python Python theme={null}
  key = method.teams.mle.public_keys.delete('team_jwk_12345')
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "team_jwk_12345", 
      "type": "direct",
      "jwk": {
        "kid": "team_123", 
        "kty": "RSA",
        "alg": "RSA-OAEP-256",
        "use": "enc",
        "n": "s3C9N7Vz...J7c",
        "e": "AQAB"
      },
      "well_known_endpoint": null,
      "status": "disabled",
      "contact": "security@yourcompany.com",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    "message": null
  }
  ```
</ResponseExample>


# List MLE Public Keys
Source: https://docs.methodfi.com/2026-03-30/reference/teams/mle/list

GET /teams/mle/public_keys

Retrieves a list of all your registered public keys for Message Level Encryption.

## Returns

Returns an array of your registered public key objects, including both active and disabled keys.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/teams/mle/public_keys \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const keys = await method.teams.mle.publicKeys.list();
  ```

  ```python Python theme={null}
  keys = method.teams.mle.public_keys.list()
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "team_jwk_12345", 
        "type": "direct",
        "jwk": {
          "kid": "team_123", 
          "kty": "RSA",
          "alg": "RSA-OAEP-256",
          "use": "enc",
          "n": "s3C9N7Vz...J7c",
          "e": "AQAB"
        },
        "well_known_endpoint": null,
        "status": "active",
        "contact": "security@yourcompany.com", 
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      },
      {
        "id": "team_jwk_67890", 
        "type": "well_known",
        "jwk": null,
        "well_known_endpoint": "https://api.yourcompany.com/.well-known/jwks.json",
        "status": "active",
        "contact": "security@yourcompany.com", 
        "created_at": "2024-01-10T14:20:00Z",
        "updated_at": "2024-01-10T14:20:00Z"
      }
    ],
    "message": null
  }
  ```
</ResponseExample>


# Get Method JWKS
Source: https://docs.methodfi.com/2026-03-30/reference/teams/mle/method-jwks

GET /.well-known/jwks.json

Retrieves Method's complete JSON Web Key Set (JWKS) containing all public keys used for Message Level Encryption. This endpoint returns all of Method's public keys that you can use to encrypt your requests.

<Note>
  This endpoint returns **Method's** public keys (used for encrypting your requests), not your own registered keys. To manage your own keys, use the [Team JWKS API](/2026-03-30/reference/teams/mle/overview).
</Note>

## Caching

This endpoint includes cache control headers to optimize performance:

```
Cache-Control: public, max-age=3600
```

You should respect these cache headers and cache the response for up to 1 hour to reduce unnecessary requests.

## Key Lifecycle

* **Active Keys**: Use keys with `status: "active"` for encryption
* **Deprecated Keys**: Keys with `status: "deprecated"` will be removed after 90 days
* **Key Identification**: Method JWKs always have their `kid` equal to their `id`

<Warning>
  Always use keys with `status: "active"`. Deprecated keys will be removed from the system after 90 days.
</Warning>

## Returns

Returns a JWKS object containing an array of Method's public keys with their current status and metadata.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/.well-known/jwks.json
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://production.methodfi.com/.well-known/jwks.json');

  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get('https://production.methodfi.com/.well-known/jwks.json')

  result = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "keys": [
      {
        "id": "mthd_jwk_12",
        "kid": "mthd_jwk_12",
        "kty": "RSA",
        "use": "enc",
        "alg": "RSA-OAEP-256",
        "n": "s3C9N7Vz...J7c",
        "e": "AQAB",
        "status": "active",
        "created_at": "2024-01-15T10:30:00Z", 
        "updated_at": "2024-01-15T10:30:00Z"
      },
      {
        "id": "mthd_jwk_11",
        "kid": "mthd_jwk_11", 
        "kty": "RSA",
        "use": "enc",
        "alg": "RSA-OAEP-256",
        "n": "x9D2M8Qw...K9f",
        "e": "AQAB",
        "status": "deprecated",
        "created_at": "2024-01-01T08:15:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
  ```
</ResponseExample>

## Best Practices

* **Cache Responses**: Respect the `Cache-Control` header and cache responses for up to 1 hour
* **Use Active Keys**: Always filter for keys with `status: "active"` when selecting keys for encryption
* **Handle Multiple Keys**: Your application should be able to handle multiple active keys
* **Monitor Webhooks**: Subscribe to `method_jwk.create` and `method_jwk.update` webhooks to stay informed of key changes
* **Graceful Degradation**: Implement fallback logic for when preferred keys become deprecated

## Environment-Specific Endpoints

Method's JWKS endpoints are environment-specific:

* **Production**: `https://production.methodfi.com/.well-known/jwks.json`
* **Sandbox**: `https://sandbox.methodfi.com/.well-known/jwks.json`
* **Development**: `https://dev.methodfi.com/.well-known/jwks.json`


# MLE Public Keys Overview
Source: https://docs.methodfi.com/2026-03-30/reference/teams/mle/overview

Manage your public keys for Message Level Encryption

## Overview

The MLE Public Keys API allows you to manage your public keys used for Message Level Encryption (MLE) with Method's API. You can register, retrieve, and delete your public keys through these endpoints.

## Key Management Operations

| Operation    | Endpoint                            | Description                       |
| ------------ | ----------------------------------- | --------------------------------- |
| **Create**   | `POST /teams/mle/public_keys`       | Register a new public key         |
| **List All** | `GET /teams/mle/public_keys`        | Retrieve all your registered keys |
| **Retrieve** | `GET /teams/mle/public_keys/:id`    | Get a specific key by ID          |
| **Delete**   | `DELETE /teams/mle/public_keys/:id` | Delete (disable) a specific key   |

## Key Registration Types

You can register your public key using two methods:

### Direct Registration

Post your public key directly to Method with the JWK fields.

### Well-Known Endpoint

Provide a URL where Method can dynamically fetch your JWKS (JSON Web Key Set).

<Note>
  **Important**: Each key ID (`kid`) can only be registered once using either method. If you have a public key available through your well-known endpoint, you should not register the same public key through direct registration, even if you change the `kid`.
</Note>

## Key Status

Your registered keys can have the following statuses:

* **active**: The key is active and can be used for encryption
* **disabled**: The key has been deleted and cannot be used

## Authentication

All MLE Public Keys API endpoints require authentication using your Method API key:

```
Authorization: Bearer sk_your_token
```


# Retrieve MLE Public Key
Source: https://docs.methodfi.com/2026-03-30/reference/teams/mle/retrieve

GET /teams/mle/public_keys/{id}

Retrieves a specific public key registration by its ID.

## Path Parameters

<ParamList />

## Returns

Returns the specified public key registration object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/teams/mle/public_keys/team_jwk_12345 \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const key = await method.teams.mle.publicKeys.retrieve('team_jwk_12345');
  ```

  ```python Python theme={null}
  key = method.teams.mle.public_keys.retrieve('team_jwk_12345')
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "team_jwk_12345", 
      "type": "direct",
      "jwk": {
        "kid": "team_123", 
        "kty": "RSA",
        "alg": "RSA-OAEP-256",
        "use": "enc",
        "n": "s3C9N7Vz...J7c",
        "e": "AQAB"
      },
      "well_known_endpoint": null,
      "status": "active",
      "contact": "security@yourcompany.com", 
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:30:00Z"
    },
    "message": null
  }
  ```
</ResponseExample>


# Retrieve Method Public Key
Source: https://docs.methodfi.com/2026-03-30/reference/teams/mle/retrieve-method-key

GET /auth/{jwk_id}

Retrieves a specific Method public key by its ID. This endpoint is particularly useful when subscribing to webhook notifications for Method JWK events (`method_jwk.create` and `method_jwk.update`), as the webhook payload includes a `path` field pointing to this endpoint.

<Note>
  This endpoint retrieves **Method's** public keys (used for encrypting your requests), not your own registered keys. To manage your own keys, use the [TEAM JWKS API](/2026-03-30/reference/teams/mle/overview).
</Note>

## Path Parameters

<ParamList />

## Webhook Integration

When you subscribe to `method_jwk.create` or `method_jwk.update` webhook events, the webhook payload will include a `path` field like `/auth/mthd_jwk_12`. You can make a GET request to this path to retrieve the updated key information.

Example webhook event object:

```json theme={null}
{
  "id": "mthd_jwk_12",
  "type": "method_jwk.update",
  "path": "/auth/mthd_jwk_12",
  "event": "evt_knqJgxKUnqDVJ"
}
```

## Returns

Returns the specified Method public key object with its current status and metadata.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/auth/mthd_jwk_12
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://production.methodfi.com/auth/mthd_jwk_12');

  const result = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get('https://production.methodfi.com/auth/mthd_jwk_12')

  result = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "mthd_jwk_12",
      "kid": "mthd_jwk_12",
      "kty": "RSA",
      "alg": "RSA-OAEP-256",
      "use": "enc",
      "n": "s3C9N7Vz...J7c",
      "e": "AQAB",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z", 
      "updated_at": "2024-01-15T10:30:00Z"
    },
    "message": null
  }
  ```
</ResponseExample>

## Use Cases

This endpoint is commonly used for:

* **Webhook Processing**: Automatically fetch updated key information when receiving `method_jwk.create` or `method_jwk.update` webhooks
* **Key Validation**: Verify the current status and details of a specific Method public key
* **Cache Updates**: Refresh your cached Method public keys when notified of changes
* **Key Rotation Handling**: Retrieve new active keys or check the status of deprecated keys


# Create a Webhook
Source: https://docs.methodfi.com/2026-03-30/reference/webhooks/create

POST /webhooks

Creating a new Webhook means registering a URL to receive
updates for a specific event type. Once a resource is
created or updated, your application will be notified
via an HTTPS POST request with the event information.

## Body

<ParamList />

## Returns

Returns the newly created Webhook object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/webhooks \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "payment.update",
      "url": "https://reference.example.app/webhook",
      "auth_token": "md7UqcTSmvXCBzPORDwOkE",
      "hmac_secret": "bd7UscLSmvEXazTOQDwOKW",
      "expand_event": true
    }'
  ```

  ```javascript Node.js theme={null}
  const webhook = await method.webhooks.create({
    type: 'payment.update',
    url: 'https://reference.example.app/webhook',
    auth_token: 'md7UqcTSmvXCBzPORDwOkE',
    hmac_secret: 'bd7UscLSmvEXazTOQDwOKW',
    expand_event: true
  });
  ```

  ```python Python theme={null}
  webhook = method.webhooks.create({
    'type': 'payment.update',
    'url': 'https://reference.example.app/webhook',
    'auth_token': 'md7UqcTSmvXCBzPORDwOkE',
    'hmac_secret': 'bd7UscLSmvEXazTOQDwOKW',
    'expand_event': true
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "whk_cSGjA6d9N8y8R",
    "type": "payment.update",
    "url": "https://reference.example.app/webhook",
    "metadata": null,
    "expand_event": false,
    "status": "active",
    "error": null,
    "created_at": "2020-12-09T00:41:05.647Z",
    "updated_at": "2020-12-09T00:41:05.647Z"
  }
  ```
</ResponseExample>


# Delete a Webhook
Source: https://docs.methodfi.com/2026-03-30/reference/webhooks/delete

DELETE /webhooks/{whk_id}

Deletes the Webhook associated with the ID.

## Path Parameters

<ParamList />

## Returns

Returns `200` with an empty object on success.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/webhooks/whk_cSGjA6d9N8y8R \
    -X DELETE \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const webhook = await method.webhooks.delete('whk_cSGjA6d9N8y8R');
  ```

  ```python Python theme={null}
  webhook = method.webhooks.delete('whk_cSGjA6d9N8y8R')
  ```
</RequestExample>


# List all Webhooks
Source: https://docs.methodfi.com/2026-03-30/reference/webhooks/list

GET /webhooks

Returns all the Webhooks associated with your team,
or an empty array if none have been created.

## Path Parameters

<ParamList />

## Returns

Returns a list of Webhook objects.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/webhooks \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const webhooks = await method.webhooks.list();
  ```

  ```python Python theme={null}
  webhooks = method.webhooks.list()
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "data": [
      {
        "id": "whk_cSGjA6d9N8y8R",
        "type": "payment.update",
        "url": "https://reference.example.app/webhook",
        "metadata": null,
        "expand_event": false,
        "status": "active",
        "error": null,
        "created_at": "2022-03-31T17:56:55.757Z",
        "updated_at": "2022-03-31T17:56:55.757Z"
      }
    ]
  }
  ```
</ResponseExample>


# The webhook endpoint
Source: https://docs.methodfi.com/2026-03-30/reference/webhooks/overview



Webhooks allow the Method API to notify your application
when certain events occur.

To receive Webhook notifications, create a Webhook by registering a
URL pointing to your application where triggered events should be
sent to. This URL is where Method will send event information
in an HTTPS POST request.

#### Handling webhooks

A Webhook event is considered successfully delivered when the
corresponding URL endpoint responds with a `2xx` HTTP status code
within 5 seconds.

If the criteria is not met, Method will reattempt 4 more times
with each new attempt being delayed according to an exponential backoff
algorithm, where the delay period between each attempt exponentially increases.

#### Handling duplicate deliveries

Webhook delivery is at-least-once: the same event can occasionally be delivered more than
once. This happens, for example, when your endpoint processes an event but does not respond
with a `2xx` within 5 seconds (the delivery is retried).

Every delivery includes a `method-webhook-delivery-id` header that uniquely identifies the
delivery. The value stays the same across retry attempts of the same event, so use it as an
idempotency key: record each processed ID and skip any delivery whose ID you have already
seen. As a general rule, we also recommend processing events idempotently: fetch the
resource referenced by the event and upsert your local state, so handling the same change
twice has no effect.

<Note>
  The `id` field in the request body is the ID of the resource that changed, not a unique
  event identifier; two different events for the same resource share it. Deduplicate using
  the `method-webhook-delivery-id` header, not the payload.
</Note>

#### Automatic disabling

Method automatically changes a Webhook's status when a delivery fails 5 times (the
initial attempt and all retries) and more than 40% of the Webhook's delivery attempts
within the rolling 24-hour window have failed. The resulting status depends on your
team's grace period:

* If the Webhook is within a grace period configured for your team (measured from the
  Webhook's creation), its `status` is set to `requires_attention` and it continues to
  receive events.
* Otherwise, its `status` is set to `disabled` and no further events are delivered
  until the Webhook is reactivated.

In both cases an `error` is set on the Webhook object with details about the failure.

<Warning>
  Monitor your Webhook endpoint's health to avoid exceeding the 40% failure threshold.
  Even intermittent failures can accumulate over a 24-hour window and trigger automatic
  disabling. We recommend responding with a `2xx` status code immediately and processing
  webhook data asynchronously.
</Warning>

To reactivate a disabled Webhook, use the [Update a Webhook](/2026-03-30/reference/webhooks/update)
endpoint to set its `status` back to `active`. Before reactivating, ensure the underlying
issue has been resolved to prevent the Webhook from being disabled again.

#### Authentication

<Accordion title="Webhook Request Validation">
  We use the `auth_token` and `hmac_secret` you provide to enable webhook authentication.
  There are 2 ways to authenticate an incoming request.

  <AccordionGroup>
    <Accordion title="1. Authorization Header Verification">
      The token for request validation will be sent as a `base64-encoded` string in the `Authorization` header of the webhook. You can verify the request originated from Method by `base64-encoding` your `auth_token` and comparing it to the incoming header value to ensure the integrity of the event.

      ```ts theme={null}
      const SECRET = 'your-auth-token';
      const expected_auth = Buffer.from(SECRET).toString('base64');
      const incoming_auth = req.headers['authorization'];

      if (incoming_auth !== expected_auth) {
        return res.status(401).send('Invalid Authorization token');
      }
      ```
    </Accordion>

    <Accordion title="2. HMAC Verification">
      If you provide an `hmac_secret` when registering your webhook, Method will include a `method-webhook-signature` header in every request. This is an `HMAC-SHA256` digest created using the `hmac_secret` as the shared secret, and computed over the string `timestamp:payload`, where `timestamp` is the value from the `method-webhook-timestamp` (UNIX timestamp in seconds) header (which is always included, even if no `hmac_secret` is provided) and `payload` is the raw request body.
      Checking for the timestamp freshness (5 min window) is optional, but recommended.

      ```
      ${method-webhook-timestamp}:${raw_payload}
      ```

      The timestamp is always included in the `method-webhook-timestamp` header, even if no `hmac_secret` is provided.

      ```ts theme={null}
      const HMAC_SECRET = 'your-auth-token'; // Replace with the hmac_secret you provided Method
      const ts = req.headers['method-webhook-timestamp'];
      const hmac_sig = req.headers['method-webhook-signature'];
      const msg = `${ts}:${req.rawBody}`;
      const expected_sig = crypto.createHmac('sha256', HMAC_SECRET).update(msg).digest('hex');

      if (!crypto.timingSafeEqual(Buffer.from(hmac_sig), Buffer.from(expected_sig))) {
        return res.status(401).send('Invalid signature');
      }
      ```
    </Accordion>

    <Accordion title="Example: Minimal Express Server for Verifying Webhooks">
      ```ts theme={null}
      import express from 'express';
      import crypto from 'crypto';
      import bodyParser from 'body-parser';

      const app = express();

      const SECRET = 'your-auth-token';
      const HMAC_SECRET = 'your-hmac-secret'; // Replace with the hmac_secret you provided Method
      const expected_auth = Buffer.from(SECRET).toString('base64');

      app.use(bodyParser.json({
        verify: (req, _, buf) => req.rawBody = buf.toString(),
      }));

      app.post('/webhook', (req, res) => {
        const ts = req.headers['method-webhook-timestamp'];
        const hmac_sig = req.headers['method-webhook-signature'];
        const incoming_auth = req.headers['authorization'];

        if (!ts || !hmac_sig || !incoming_auth) return res.status(400).send('Missing headers');
        if (incoming_auth !== expected_auth) return res.status(401).send('Invalid Authorization token');
        // 1. check for freshness of the request
        if (Math.abs(Date.now() / 1000 - ts) > 300) return res.status(400).send('Timestamp expired');

        // 2. message reconstruction
        const msg = `${ts}:${req.rawBody}`;
        // 3. compute HMAC 
        const expected_sig = crypto.createHmac('sha256', HMAC_SECRET).update(msg).digest('hex');

        // 4. constant-time comparison
        if (!crypto.timingSafeEqual(Buffer.from(hmac_sig), Buffer.from(expected_sig))) {
          return res.status(401).send('Invalid signature');
        }

        res.status(200).send('Accepted');
      });

      app.listen(3000, () => console.log('Listening on port 3000'));
      ```
    </Accordion>
  </AccordionGroup>
</Accordion>

## Webhook Objects

<ParamList />

## Webhook event object

<ParamList />

#### Webhook Event Types

| Name                                                               | Description                                                |
| ------------------------------------------------------------------ | ---------------------------------------------------------- |
| `account.create`                                                   | A new Account was successfully created.                    |
| `account.update`                                                   | An Account has been updated.                               |
| `account.opened`                                                   | An Account has been opened.                                |
| `account.closed`                                                   | An Account has been closed.                                |
| `sensitive.create`                                                 | A new Sensitive was successfully created.                  |
| `account.number.update`                                            | An Account's number has been updated.                      |
| `sensitive.update`                                                 | A Sensitive has been updated.                              |
| `account_verification_session.create`                              | A new AccountVerificationSession was successfully created. |
| `account_verification_session.update`                              | An AccountVerificationSession has been updated.            |
| `balance.create`                                                   | A new Balance was successfully created.                    |
| `balance.update`                                                   | A Balance has been updated.                                |
| `card_brand.create`                                                | A new CardBrand was successfully created.                  |
| `card_brand.update`                                                | A CardBrand has been updated.                              |
| `card_brand.available`                                             | A CardBrand has been made available.                       |
| `connect.create`                                                   | A new Connect was successfully created.                    |
| `connect.update`                                                   | A Connect has been updated.                                |
| `connect.available`                                                | An Async Connect has completed.                            |
| `credit_score.create`                                              | A new CreditScore was successfully created.                |
| `credit_score.update`                                              | A CreditScore has been updated.                            |
| `credit_score.available`                                           | A CreditScore has been made available.                     |
| `entity.create`                                                    | A new Entity was successfully created.                     |
| `entity.update`                                                    | An Entity has been updated.                                |
| `entity.new_accounts_pending_consent`                              | An Entity needs to consent new surfaced accounts.          |
| `entity_verification_session.create`                               | A new EntityVerificationSession was successfully created.  |
| `entity_verification_session.update`                               | An EntityVerificationSession has been updated.             |
| `identity.create`                                                  | A new Identity was successfully created.                   |
| `identity.update`                                                  | An Identity has been updated.                              |
| `payment.create`                                                   | A new Payment was successfully created.                    |
| `payment.update`                                                   | A Payment has been updated.                                |
| `payment_instrument.create`                                        | A new PaymentInstrument was successfully created.          |
| `payment_instrument.update`                                        | A PaymentInstrument has been updated.                      |
| `payment_reversal.create`                                          | A new PaymentReversal was successfully created.            |
| `payment_reversal.update`                                          | A PaymentReversal has been updated.                        |
| `payoff.create`                                                    | A new Payoff was successfully created.                     |
| `payoff.update`                                                    | A Payoff has been updated.                                 |
| `product.create`                                                   | A new Product was successfully created.                    |
| `product.update`                                                   | A Product has been updated.                                |
| `report.create`                                                    | A new Report was successfully created.                     |
| `report.update`                                                    | A Report has been updated.                                 |
| `subscription.create`                                              | A new Subscription was successfully created.               |
| `subscription.update`                                              | A Subscription has been updated.                           |
| `transaction.create`                                               | A new Transaction was successfully created.                |
| `transaction.update`                                               | A Transaction has been updated.                            |
| `update.create`                                                    | A new Update was successfully created.                     |
| `update.update`                                                    | An Update has been updated.                                |
| `credit_score.increased`                                           | A user's credit score has increased.                       |
| `credit_score.decreased`                                           | A user's credit score has decreased.                       |
| `entity_attribute.create`                                          | A new Entity Attribute was successfully created.           |
| `entity_attribute.update`                                          | An Entity Attribute has been updated.                      |
| `account_attribute.create`                                         | A new Account Attribute was successfully created.          |
| `account_attribute.update`                                         | An Account Attribute has been updated.                     |
| `entity_attribute.credit_health_credit_card_usage_value.increased` | Credit card usage has increased.                           |
| `entity_attribute.credit_health_credit_card_usage_value.decreased` | Credit card usage has decreased.                           |
| `entity_attribute.credit_health_derogatory_marks_value.increased`  | Number of derogatory marks increased.                      |
| `entity_attribute.credit_health_derogatory_marks_value.decreased`  | Number of derogatory marks decreased.                      |
| `entity_attribute.credit_health_hard_inquiries_value.increased`    | Number of hard inquiries increased.                        |
| `entity_attribute.credit_health_hard_inquiries_value.decreased`    | Number of hard inquiries decreased.                        |
| `entity_attribute.credit_health_total_accounts_value.increased`    | Total number of accounts increased.                        |
| `entity_attribute.credit_health_total_accounts_value.decreased`    | Total number of accounts decreased.                        |
| `entity_attribute.credit_health_credit_age_value.increased`        | Credit age has increased.                                  |
| `entity_attribute.credit_health_credit_age_value.decreased`        | Credit age has decreased.                                  |
| `entity_attribute.credit_health_payment_history_value.increased`   | Payment history score has improved.                        |
| `entity_attribute.credit_health_payment_history_value.decreased`   | Payment history score has decreased.                       |
| `entity_attribute.credit_health_soft_inquiries_value.increased`    | Number of soft inquiries increased.                        |
| `method_jwk.create`                                                | A new Method JWK (public key) was successfully created.    |
| `method_jwk.update`                                                | A Method JWK has been updated (deprecated or disabled).    |

<RequestExample>
  ```json THE WEBHOOK OBJECT theme={null}
  {
    "id": "whk_cSGjA6d9N8y8R",
    "type": "account.update",
    "url": "https://reference.example.app/webhook",
    "metadata": null,
    "expand_event": false,
    "status": "active",
    "error": null,
    "created_at": "2020-12-09T00:41:05.647Z",
    "updated_at": "2020-12-09T00:41:05.647Z"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json WEBHOOK EVENT OBJECT theme={null}
  {
    "webhook_id": "whk_cSGjA6d9N8y8R",
    "id": "acc_BcRdHNjb9TYKV",
    "type": "account.update",
    "op": "update",
    "path": "/accounts/acc_BcRdHNjb9TYKV",
    "event": "evt_knqJgxKUnqDVJ",
    "refs": {
      "account": "acc_BcRdHNjb9TYKV",
      "entity": "ent_qKNBB68bfHGNA"
    }
  }
  ```
</ResponseExample>


# Retrieve a Webhook
Source: https://docs.methodfi.com/2026-03-30/reference/webhooks/retrieve

GET /webhooks/{whk_id}

Returns the Webhook object associated with the ID.

## Path Parameters

<ParamList />

## Returns

Returns the Webhook object associated with the ID.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/webhooks/whk_cSGjA6d9N8y8R \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const webhook = await method.webhooks.retrieve('whk_cSGjA6d9N8y8R');
  ```

  ```python Python theme={null}
  webhook = method.webhooks.retrieve('whk_cSGjA6d9N8y8R')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "whk_cSGjA6d9N8y8R",
    "type": "payment.update",
    "url": "https://reference.example.app/webhook",
    "metadata": null,
    "expand_event": false,
    "status": "active",
    "error": null,
    "created_at": "2020-12-09T00:41:05.647Z",
    "updated_at": "2020-12-09T00:41:05.647Z"
  }
  ```
</ResponseExample>


# Update a Webhook status
Source: https://docs.methodfi.com/2026-03-30/reference/webhooks/update

PATCH /webhooks/{whk_id}

Updating a Webhook status can be used to manually disable a Webhook, or reactivate a Webhook that has been disabled.

Disabling a Webhook is a temporary action, allowing for it to be reactivated later, whereas <a href="/2026-03-30/reference/webhooks/delete">Deleting a Webhook</a> is a permanent action.

## Path Parameters

<ParamList />

## Body

<ParamList />

## Returns

Returns the updated Webhook object.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/webhooks/whk_cSGjA6d9N8y8R \
    -X PATCH \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "status": "active"
    }'
  ```

  ```javascript Node.js theme={null}
  const webhook = await method.webhooks.update('whk_cSGjA6d9N8y8R',{
    status: 'active'
  });
  ```

  ```python Python theme={null}
  webhook = method.webhooks.update('whk_cSGjA6d9N8y8R',{
    'status': 'active'
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "id": "whk_cSGjA6d9N8y8R",
    "type": "payment.update",
    "url": "https://reference.example.app/webhook",
    "metadata": null,
    "expand_event": false,
    "status": "active",
    "error": null,
    "created_at": "2025-09-09T00:41:05.647Z",
    "updated_at": "2025-09-09T00:41:05.647Z"
  }
  ```
</ResponseExample>


# April Updates
Source: https://docs.methodfi.com/changelog/2026/april



## New Features

### Attributes V2: Entity & Account Attributes

A new version of the [Attributes API](/reference/entities/attributes/overview) introduces 50+ new computed attributes across both Entities and Accounts, giving you a more complete, up-to-date picture of a user's financial health:

* **Utilization & Credit Health**: See a user's credit utilization broken out by account type, with 30/60/90-day trend lines and delta calculations that show whether utilization is rising or falling over time. Includes delinquency flags and payment-to-minimum ratios that help identify users who may be falling behind.
* **Balance & Debt Movement**: Track how balances are changing across a user's full liability portfolio with 30/60/90-day balance change attributes. Understand whether a user is paying down debt or accumulating it, across credit cards, personal loans, mortgages, and installment accounts.
* **Cost of Debt**: Weighted average APR calculations across liability types help you understand what a user is actually paying in interest, useful for refinance targeting, rate optimization, and cross-sell opportunities.
* **Payment Behavior**: Monthly installment estimates, minimum payment totals, and autopay detection give visibility into how a user is managing their obligations and whether they're likely to stay current.

V2 attributes are available at both the Entity level (aggregated across all of a user's accounts) and the Account level (per-account metrics). V2 attributes support webhook delivery and subscriptions, and can be simulated in the development environment via the [Simulations API](/reference/simulations/attributes/create).

For more information, visit the [Attributes API](/reference/entities/attributes/overview) documentation.

### Opal Embeddable Mode

[Opal](/opal/overview) now supports a fully embeddable rendering mode for JavaScript and React integrations. The new embeddable mode allows Opal to be rendered inline within your application's DOM rather than in a modal overlay, giving you full control over layout and positioning.

* **React SDK**: The `@methodfi/opal-react` package has been updated to v1.5.0 with embeddable mode support.
* **JavaScript SDK**: Native JavaScript integrations can now pass `mode: "embeddable"` when initializing Opal.

For more information, visit the [Opal Libraries](/opal/libraries) documentation.

### Managed Accounts API

A new [Managed Accounts API](/reference/managed-accounts/overview) provides programmatic access to Method-managed FBO accounts. You can now retrieve managed account balance information and list transactions for reconciliation:

* `GET /managed_accounts` — list all Managed Accounts on your team
* `GET /managed_accounts/{macc_id}` — retrieve a specific Managed Account
* `GET /managed_accounts/{macc_id}/transactions` — list transactions for a Managed Account

For more information, visit the [Managed Accounts API](/reference/managed-accounts/overview) documentation.

## Improvements

### Opal UI

* **CVV Autofill Detection**: Browsers that autofill CVV fields were sometimes causing silent submission failures because Opal didn't detect the autofilled value. This is now handled correctly, so users who rely on password managers or browser autofill won't hit unexpected errors.
* **Input Trimming**: Whitespace is now automatically stripped from user inputs before submission. This catches a common issue where users copy-paste account numbers or card details with trailing spaces, which would previously cause validation failures.

For more information, visit the [Opal](/opal/overview) documentation.

### Webhooks

**Improved Duplicate Detection**

Previously, webhooks with the same endpoint URL and different authentication credentials (for example, separate webhook configs for staging and production that share a URL) were treated as duplicates, delivering to only one of them. Deduplication now accounts for authentication configuration, so each distinct webhook registration receives its own deliveries as expected.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.


# July Updates
Source: https://docs.methodfi.com/changelog/2026/july



## New Features

### Raw Credit Report Artifacts and Files API

Teams with raw credit report access can now request the bureau report underlying a Connect as downloadable JSON or PDF artifacts. This gives lenders the full bureau file behind a Connect, so underwriting, risk, and compliance logic can run against the same source data Method used.

Pass `bureau` and `artifacts` when creating a Connect. Equifax and TransUnion are supported:

```json theme={null}
{
  "bureau": "transunion",
  "artifacts": ["raw_credit_report", "credit_report_pdf"]
}
```

The completed Connect returns each artifact in its `files` array. The new Files API provides two ways to access them:

* `GET /files/{file_id}` returns File metadata and a temporary download URL
* `GET /files/{file_id}/download` streams the original file directly

Files remain available after the Connect completes, allowing lenders to run their existing underwriting and risk logic on the same raw credit report output without maintaining a separate bureau integration. Raw credit report access is enabled per team; contact your Method CSM to get started.

For implementation details, visit the [Raw Credit Reports guide](/guides/connect/raw-credit-reports) and [Files API](/reference/files/overview) documentation.

### Estimated Statement Attribute

Account Attributes can now return the upcoming payment due date and minimum amount due for supported accounts through the new `statement` bundle:

* `next_payment_due_date`: the upcoming payment due date
* `next_payment_minimum_amount`: the upcoming minimum amount due, in cents

Previously this required maintaining an Update subscription and waiting for a refreshed Update to land, and between statement cycles the values were frequently missing altogether. Teams can now schedule autopay and reminders against a real due date, size a payment that reliably clears the minimum, and sequence payments across a user's accounts by what comes due first.

When current statement data is unavailable, Method estimates both values from account history and identifies them with `metadata.estimated: true`. When a value cannot be determined, the attribute returns an `ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA` error rather than a fabricated fallback.

```json theme={null}
{
  "bundles": ["statement"]
}
```

For more information, visit the [Account Attributes](/reference/accounts/attributes/overview) API documentation.

### Estimated Credit Card APR

Account Attributes can now return a single `estimated_apr` for supported credit card accounts with qualifying account history.

Card issuers rarely expose an account-level APR through any programmatic channel, which has left teams either asking the end user for their rate or assuming one. Estimated APR lets teams size interest savings, rank refinance and balance transfer offers, and prioritize outreach to the highest-rate balances in a user's profile, without asking the end user for anything.

Every value is identified with `metadata.estimated: true` and carries a `metadata.confidence` of `medium` or `high` based on the depth of available history, so teams can set their own threshold for acting on it. When an APR cannot be inferred with sufficient confidence, the attribute returns an `ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA` error rather than a fabricated fallback.

```json theme={null}
{
  "estimated_apr": {
    "value": 19.5,
    "error": null,
    "metadata": {
      "estimated": true,
      "confidence": "high"
    }
  }
}
```

For more information, visit the [Account Attributes](/reference/accounts/attributes/overview) API documentation.

## Changes

### Payment Processing Windows

Payment processing windows have been updated. Payments using the Method Debit Model are now processed at 1:30 PM CT, and payments using the Prefunded Model are now processed at 3:30 PM CT. Payments submitted before the applicable cutoff are processed same-day; payments submitted after are queued for next-business-day processing.

For more information, visit the [Payments API](/reference/payments/overview) documentation.

## Improvements

### Idempotency and Stuck-Request Recovery

Improvements to Method's idempotency system eliminated persistent `INTERNAL_BAD_STATE` errors on retried requests. Dropped connections now recover automatically on retry, previously stuck requests self-heal rather than remaining locked, and orphaned in-flight requests are released after a short interval.

End users no longer become locked mid-flow after a dropped connection. Requests already stuck in `INTERNAL_BAD_STATE` also recover automatically the next time the end user retries, and no integration changes are required.

For more information, visit the [API Idempotency](/reference/idempotency) documentation.

### Dashboard Navigation and Search

The [Method Dashboard](https://dashboard.methodfi.com) now includes:

* A responsive, collapsible sidebar with improved mobile support
* Faster global search with a more compact results experience
* Faster switching between development and production environments
* Persistence of the most recently used environment across sessions
* FIS trace IDs on sent and posted payments in the payments view

Users with the Developer role can also create API keys and webhook registrations directly from the Dashboard, consistent with their existing permissions. Together these reduce the time spent locating a request, entity, or payment when responding to a customer question.

### Payability Check at Account Creation

Method now runs a payability check when an account is created, so teams learn whether an account can be paid at the point of creation rather than discovering it at payment time. This prevents users from attempting a payment that was never going to succeed.

### Webhook Reliability

Outbound webhook delivery now includes stronger duplicate-delivery protection and prevents queued deliveries from being sent to disabled webhook registrations. Delivery and replay handling have also been hardened to reduce the risk of events being lost during transient service failures.

This means fewer events to deduplicate on your side and less reconciliation work after a transient failure, with no change to how you consume webhooks.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Development Environment

Manual Connect flows can now be configured dynamically, and payments can be simulated against payment instruments without production dependencies. Teams can therefore test a full Connect-to-payment path, including failure cases, before touching a live account.

For more information, visit the [Development Environment](/reference/environments) documentation.


# June Updates
Source: https://docs.methodfi.com/changelog/2026/june



## New Features

### Card Brand Details

The Card Brands endpoint now returns a structured `details` object on each brand, giving you the full marketing-level terms behind a user's card, including APRs, fees, rewards, and promotional offers.

* **APRs**: Purchase and cash-advance APR ranges via `purchase_apr_min` / `purchase_apr_max` and `cash_advance_apr_min` / `cash_advance_apr_max`.
* **Fees**: `annual_fee` and `late_payment_fee`.
* **Rewards**: A full rewards object with program name, reward type (for example, `cash_back`, `points`, `miles`), and per-category earn rates (dining, travel, groceries, gas, and more), including the base-rate category for all other purchases.
* **Promotions**: A `promotions` array covering sign-up bonuses, intro APR offers, statement credits, and more, each with value, spend requirement, qualifying period, and expiration.
* **Classification and freshness**: `card_category` classifies the card (for example, `travel`, `cash_back`, `store`), and `data_as_of` tells you when the details were last captured.

**Key Use Cases**

* Power balance-transfer and refinance offers with accurate rate and promotion data.
* Enrich PFM experiences by showing users the detailed terms and benefits of the cards they carry.
* Optimize checkout and reward experiences by auto-routing purchases to the top-earning card.

Card Brands is available as both a Product (on-demand) and a Subscription (near real-time updates), and the details object is available on API version `2025-07-04` and later. The endpoint is available to partners processing payments through the Payment Instruments endpoint. Contact your Method CSM to enable it. See the [Card Brands reference](/reference/accounts/card-brands/overview) to get started.

### Dashboard: Check Payment Management

Admins can now manage check payments directly from the payment detail page in the [Method Dashboard](https://dashboard.methodfi.com).

* **Stop payment**: Place a stop on a paper check that has been sent but not yet cashed. The check is stopped and funds are reversed to the source.
* **Check endorsement image**: View the front and back endorsed image of a check once it has been cashed.
* **Source & destination status**: The payment detail page now surfaces source status and destination status alongside the existing payment status for better visibility into where a payment is in its lifecycle.

<Note>Stop payment and check image viewing are available to admin users only.</Note>

For more information, visit the [Method Dashboard](https://dashboard.methodfi.com).

### Preauth Signals

The new Preauth Signals endpoint returns the predicted likelihood that a transaction will succeed, alongside verified ownership of the card and recommended retry timing. Built for merchants and commerce platforms looking to optimize payment performance.

**Key Use Cases**

* Predict whether a card payment will go through before attempting the charge to reduce false declines at checkout.
* Identify the best date to retry a payment for recurring charges.

This endpoint is currently in Public Preview. Reach out to your Method CSM for access and documentation.

### New Attributes: Delinquency, HELOC & Available Credit

New entity-level and account-level attributes give you a more complete, real-time picture of borrower risk and capacity.

* **Delinquency signals**: Aggregate borrower-level risk with the worst days-past-due bucket across accounts, whether delinquency is progressing or recently cured, total delinquent balance, and the highest-severity outcome (charge-off, collections, foreclosure, and more).
* **HELOC-specific attributes**: You can now separate out attributes related to HELOCs from mortgages and personal loans to isolate appetite for a new HELOC, CLI, or refi.
* **Available credit**: Understand a borrower's total credit headroom in near real time to assess their riskiness and eligibility for new products.
* **Direct Pay enrichment**: Completed attribute responses now include Method Direct Pay history (recency, amount, and trailing 12-month count), providing a clearer picture of a borrower's risk profile and appetite for debt consolidation.

For more information, visit the [Entity Attributes](/reference/entities/attributes/overview) and [Account Attributes](/reference/accounts/attributes/overview) API documentation.

### Account Attribute Subscriptions

Method now triggers events whenever an account's attributes change, so you can react to balance, utilization, and delinquency shifts in real time instead of polling. Subscribe to the attributes you care about and Method delivers updates to your configured webhooks as they occur.

* Manage what you listen to through the [Subscriptions endpoint](/reference/accounts/subscriptions/overview).
* Receive changes through [Events](/reference/events/overview) and webhooks.

This pairs naturally with continuous, post-origination portfolio monitoring use cases.

### Team IP Allowlisting

Teams can now restrict API access to a defined set of IP addresses. Once an allowlist is configured, requests from outside the approved ranges are rejected, with enforcement backed by a 24-hour cache for low-latency checks. See [IP Whitelisting](/reference/ip-whitelisting) to configure.

## Improvements

### Payments

* **More accurate estimated completion dates**: The `estimated_completion_date` returned on a payment now always shows the correct date or a slightly conservative estimate, especially for same-day ACH source payments.
* **Destination posted date**: The `destination_posted_date` field is now populated once the destination posts, giving you a precise reconciliation signal that is distinct from the estimated completion date.

For more information, visit the [Payments API](/reference/payments/overview) documentation.

### Payment Limits

To protect platform safety and stability, per-transaction and 24-hour limits are now enforced on payment volumes.

A new Limits tab under Dashboard Settings surfaces your team's money-movement capabilities and associated limits in one place. You can now see at a glance what your team is permitted to send and receive, and where caps apply.

Contact your customer success manager to learn more about your team's limits.


# May Updates
Source: https://docs.methodfi.com/changelog/2026/may



## New Features

### Snapshot Delinquency Data

[Updates](/reference/accounts/updates/overview) with `source: "snapshot"` now include a comprehensive set of delinquency fields sourced from the credit report. These fields give you a full picture of a borrower's delinquency status without pulling a separate credit report for the user.

* **Delinquency Status & Period**: `delinquent_status`, `delinquent_period`, and `delinquent_start_date` indicate the current delinquency state, severity bucket (`less_than_30`, `30`, `60`, `90`, `120`, `over_120`), and when the delinquency began.
* **Delinquent Actions**: `delinquent_action` surfaces servicer-level actions such as `charge_off`, `foreclosure`, `repossession`, `chapter_7`, `chapter_13`, `wage_garnishment`, `payment_agreement`, and `bankruptcy`.
* **Delinquent Amount**: `delinquent_amount` returns the dollar amount currently reported as delinquent.
* **Delinquency History**: `delinquent_history` provides a time-series array of historical delinquency periods, each with `start_date`, `end_date`, `status`, `period`, and `action`, enabling trend analysis across multiple reporting cycles.

Delinquency fields are available on snapshot Updates for `credit_card`, `auto_loan`, `personal_loan`, `mortgage`, and `student_loan` liability types. These fields are not included on Updates with `source: "direct"`.

For more information, visit the [Updates API](/reference/accounts/updates/overview) documentation.

### Receive Reversals via Wire

You can now receive payment reversals via wire. This functionality allows customers to quickly and easily access funds from reversed payments that previously could not run on ACH rails (such as inbound wire transfers via payment instrument).

<Note>These accounts are receive-only and do not support outbound payments.</Note>

For more information, visit the [Accounts API](/reference/accounts/overview) documentation.

### Dashboard: Webhook Management

The [Method Dashboard](https://dashboard.methodfi.com) now supports full webhook lifecycle management. You can create, view, update, and delete webhook endpoints directly from the UI, with no API calls or support requests required.

* Register new webhook endpoints with custom event filters and authentication
* View all active webhooks and their status
* Update endpoint URLs and configuration in place
* Delete webhooks that are no longer needed

For more information, visit the [Method Dashboard](https://dashboard.methodfi.com).

## Improvements

### Rate Limiting

To protect platform stability and ensure consistent performance across all customers, all API requests are now subject to published, tiered rate limits. Documented limits mean your engineering team can design around known thresholds rather than hitting undefined behavior during peak operations.

* Rate limits are applied per API key within a 60-second rolling window, organized into tiers based on operation type.
* Each tier tracks independently, so usage against one tier does not affect capacity in another.
* Customers with high-volume integrations can request custom limits through their customer success manager.

For more information, visit the [Rate Limiting](/reference/rate-limiting) documentation.

### Webhooks

**Delivery Rate Limiting**

Outbound webhook deliveries are now rate-limited to 15 deliveries per second per webhook registration. This smooths delivery during high-volume events (e.g., bulk Connect completions or batch Update subscriptions) and reduces the likelihood of triggering rate-limit responses on your infrastructure.

**Failure Handling**

An individual webhook delivery is now retried up to 5 times before it is marked as failed, rather than remaining in a retry loop indefinitely. After 5 consecutive delivery failures, the webhook `status` is set to `disabled`, consistent with the documented automatic-disabling behavior. You can reactivate a disabled webhook from the Dashboard or via the [Update a Webhook](/reference/webhooks/update) endpoint once the underlying issue is resolved.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Payments API

**Destination Processing Window**

The destination processing window has been updated to 4:00 PM CT (5:00 PM ET). Payments submitted before this cutoff can be processed the same-day; payments submitted after are queued for next-business-day processing.

For more information, visit the [Payments API](/reference/payments/overview) documentation.

### Simulations API

**Account Closed Event**

The `POST /simulate/events` endpoint for `account.closed` events now also triggers the `account.update` webhook as part of the simulation, matching production behavior. This enables more complete end-to-end testing of account lifecycle workflows in the development environment.

```json POST /simulate/events theme={null}
{
  "type": "account.closed",
  "entity_id": "ent_au22b1FBFJbp8",
  "account_id": "acc_Dz3E8r4mJ7xKn"
}
```

When simulating `account.closed`, both webhooks now fire in sequence:

1. `account.update`: the account snapshot is updated with the closed status
2. `account.closed`: the account itself transitions to closed

For more information, visit the [Simulations API](/reference/simulations/events/create) documentation.

### Development Environment

**Mock Credit Reports for Connect**

Mock raw credit reports are now available for [Connect](/opal/connect/overview) flows in the development environment, enabling end-to-end testing of credit report-based account discovery without live bureau data.

<Warning>This feature is available in the development environment only.</Warning>

**Payment Destination Details in Responses**

The development environment `POST /payments` response now includes the `destination_payment_method` field, aligning dev responses with production behavior. This field indicates how the payment is delivered to the recipient, either `electronic` or `paper`.

```json theme={null}
{
  "id": "pmt_rPrDPEwyCVUcm",
  "status": "pending",
  "source": "acc_JMJZT6r7iHi8e",
  "destination": "acc_AXthnzpBnxxWP",
  "destination_payment_method": "electronic"
}
```

For more information, visit the [Payments API](/reference/payments/overview) documentation.


# Create a Connect Element Token
Source: https://docs.methodfi.com/elements/connect/create_connect_token



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

To start using Connect, you will first need to create a [Connect Element Token](/reference/elements/tokens).
There are a few different use cases that will determine what you pass to the endpoint.

### New Entities

If you do not have any identity information about your users, you will likely create a token using a payload similar to this:

```json theme={null}
{
  "type": "connect",
  "connect": {
    "products": ["balance"],
    "entity": {
      "type": "individual",
      "individual": {}
    }
  }
}
```

This will return a token that you can use to create a new entity and connect their accounts. Fill in the `products` array with a list of the different products you want to connect (for example `["balance", "card"]`).

### New Entities with Partial Information

If you have some information already about a given user (such as their name), you can pass that information into the `individual` object:

```json theme={null}
{
  "type": "connect",
  "connect": {
    "products": ["balance"],
    "entity": {
      "type": "individual",
      "individual": {
        "first_name": "Kevin",
        "last_name": "Doyle"
      }
    }
  }
}
```

You can also pass in a user's phone number, address, DOB, or the last 4 digits of their SSN to make the identity verification process faster.

### Using with Existing Entities

You can also pass in an existing entity\_id:

```json theme={null}
{
  "type": "connect",
  "entity_id": "ent_au22b1fbFJbp8",
  "connect": {
    "products": ["balance"]
  }
}
```

### Using with Existing Accounts

If you also have specific accounts you'd like to connect, you can pass the account ids:

```json theme={null}
{
  "type": "connect",
  "entity_id": "ent_au22b1fbFJbp8",
  "connect": {
    "products": ["balance"],
    "accounts": ["acc_k8LAKDnED7kti", "acc_KUaFnxn7eUAeH"]
  }
}
```

<RequestExample>
  ```bash cURL theme={null}
  curl https://dev.methodfi.com/elements/token \
    -X POST \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "connect",
      "connect": {
        "products": ["balance"],
        "entity": {
          "type": "individual",
          "individual": {
            "first_name": "Kevin",
            "last_name": "Doyle"
          }
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const token = await method.elements.token.create({
    type: "connect",
    connect: {
      products: ["balance"],
      entity: {
        type: "individual",
        individual: {
          first_name: "Kevin",
          last_name: "Doyle"
        }
      }
    }
  });
  ```

  ```python Python theme={null}
  token = method.elements.token.create({
    'type': "connect",
    'connect': {
      'products': ["balance"],
      'entity': {
        'type': "individual",
        'individual': {
          'first_name': "Kevin",
          'last_name': "Doyle"
        }
      }
    }
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "element_token": "pk_elem_qPmypE9wwphr3WL3yTj7JhxjrPzAmK8G"
  }
  ```
</ResponseExample>


# Getting Connect Results
Source: https://docs.methodfi.com/elements/connect/get_results



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

In addition to [listening for the success event](/elements/events/overview), the result of the Connect session can also be retrieved by calling the `results` endpoint with the element token for that session.

```bash theme={null}
GET /elements/token/{element_token}/results
```

See [Retrieve Element Results](/reference/elements/results) for more information about this endpoint.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/elements/token/pk_elem_dDe4r9M6X3Ad9zjpbgYpzLNtRCXfhPYR/results \
    -X GET \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .elements
    .token
    .results('pk_elem_dDe4r9M6X3Ad9zjpbgYpzLNtRCXfhPYR');
  ```

  ```python Python theme={null}
  response = method
    .elements
    .token
    .results('pk_elem_dDe4r9M6X3Ad9zjpbgYpzLNtRCXfhPYR')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "authenticated": true,
    "cxn_id": "cxn_xr86xHEcWmpmB",
    "accounts": [
      "acc_jPXLFqd6KzH3N",
      "acc_DALLeLrj3TH8h"
    ],
    "entity_id": "ent_GWKYtnFyE79db",
    "events": [
      {
        "type": "open",
        "metadata": {
          "element_type": "connect",
          "op": "open"
        },
        "timestamp": "2024-04-25T02:35:28.097Z"
      },
      {
        "type": "success",
        "metadata": {
          "entity_id": "ent_GWKYtnFyE79db",
          "accounts": [
            "acc_jPXLFqd6KzH3N",
            "acc_DALLeLrj3TH8h"
          ],
          "element_type": "connect",
          "op": "success"
        },
        "timestamp": "2024-04-25T02:35:57.120Z"
      },
      {
        "type": "exit",
        "metadata": {
          "element_type": "connect",
          "op": "exit"
        },
        "timestamp": "2024-04-25T02:35:57.138Z"
      }
    ]
  }
  ```
</ResponseExample>


# Launching a Connect Session
Source: https://docs.methodfi.com/elements/connect/launch_connect



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

After creating a Connect Element token, you can launch a Connect session in a webview.

## Initializing the Connect Element

The Connect Element is optimized to work within Webviews, including on iOS and Android. Open a webview in your app to your desired environment using the `element_token` you generated.

Example:

Using the [Element SDK](/elements/libraries) (recommended):

```javascript theme={null}
method.open('pk_elem_BtzySdrQGFmLdAPw5gXSQNCxQkhCkT3K');
```

Without SDK:

```bash theme={null}
https://elements.production.methodfi.com/
  ?token=pk_elem_4PpMTPcchb49VBjwP3bREKhMN93hrQHR
```


# Connect Overview
Source: https://docs.methodfi.com/elements/connect/overview



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Connect is the primary way to leverage Method Elements to connect your users' liabilities. Connect allows you to verify a user's identity, gather their consent, and complete any needed verifications to ensure their accounts are connected to the desired Method [Products](/reference/accounts/products/overview).

The Connect element itself consists of two main steps:

<Steps>
  <Step title="Auth">
    Verify the user's identity and connect their accounts. If no entity
    information is provided when creating the Connect element token, the user
    will be asked to provide identity information such as name, phone, last 4
    digits of SSN, DOB, or address.
  </Step>

  <Step title="Account Verification">
    Request any additional information needed from the user to connect their
    accounts and leverage specific products.
  </Step>
</Steps>


# Environments
Source: https://docs.methodfi.com/elements/environments



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Elements are available in each of our three [Environments](/reference/environments):

```
https://elements.dev.methodfi.com (Development)
https://elements.sandbox.methodfi.com (Sandbox)
https://elements.production.methodfi.com (Production)
```

## Considerations for Connect

When using the [Connect Element](/elements/connect/overview), there are a few
things to keep in mind related to the different environments.

### Development Environment

In dev, you can use the following phone numbers to ensure your entity gets verified:

```bash theme={null}
Phone        | Required Fields
------------------------------
+15121231111 | Name, Phone
+15121231112 | Name, Phone, DOB (Date of Birth)
+15121231113 | Name, Phone, DOB (Date of Birth), Address
```

You can either pass in the required fields on token creation or during the Connect session.

**Note**: If you do not use one of the above phone numbers, your dev entities will not be verified.


# General Events
Source: https://docs.methodfi.com/elements/events/general_events



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

## Open

The open event is triggered when an element has successfully launched. No additional data is passed at this time.

```bash theme={null}
methodelements://general
  ?op=open
  &element_type=connect
```

The event payload will have the following form:

<ParamList />

## Error

The error event is sent for any element that encounters any error while it's active.

```bash theme={null}
methodelements://general
  ?op=error
  &element_type=unknown
  &type=INVALID_REQUEST
  &sub_type=EXPIRED_TOKEN
  &message=The public element token is no longer valid. Element tokens are short lived and can only be used once. Request a new element token and try your request again.
  &code=400
```

The event payload will have the following form:

<ParamList />

## Exit

The exit event is the last event in the element flow, at this point your app should no longer present the Method Element. Exit is triggered after an error, a user requested exit or a successful element event.

```bash theme={null}
methodelements://general
  ?op=exit
  &element_type=connect
```

The event payload will have the following form:

<ParamList />


# Events Overview
Source: https://docs.methodfi.com/elements/events/overview



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Communication between the Element and your app can be handled either by PostMessage communication or via HTTP redirects.

## Listening to Events

We strongly recommend using one of the [Element SDKs](/elements/libraries) to make listening to events easy. They provide you with callback functions that are invoked every time a specific type of event occurs (such as `open`, `success`, `exit`, etc).

Each type of Element will emit its own events. See [General Events](/elements/events/general_events) and [Element Specific Events](/elements/events/specific_events) for more information about the events that are emitted.

### PostMessage without SDK

To receive events via PostMessage, pass the query parameter `event_channel=message` to the Elements url. For example:

```bash theme={null}
https://elements.production.methodfi.com
  ?token=pk_elem_4PpMTPcchb49VBjwP3bREKhMN93hrQHR
  &event_channel=message
```

To listen to the emitted events, add an event listener onto the window object:

```javascript theme={null}
window.addEventListener('message', function(event) {
  const { payload, type } = event.data;
  console.log('Received event!', type, payload);
});
```

### Redirects

Redirects are the default way of listening to element events if you are not using one of the SDKs. Your webview / app should intercept the redirects in order to react accordingly to state changes. All redirect URLs will have the scheme ("prefix") `methodelements`. The event source will be the URL host and the payload will be query strings.

HTTP redirects from Method Elements are in the following format:

```bash theme={null}
methodelements://{event_source}?{event_data}
```


# Element Specific Events
Source: https://docs.methodfi.com/elements/events/specific_events



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

## Connect

Connect will emit a `success` event when the user has successfully completed all required authentication and verification:

```bash theme={null}
methodelements://connect
  ?op=success
  &element_type=connect
  &entity_id=ent_WyDmJnQgaxVRH
  &accounts=["acc_PFUNazUbpUpfm","acc_gjWr4Cb8H7TLz"]
```

When parsed, will result in the following JSON

```json theme={null}
{
  "op": "success",
  "element_type": "connect",
  "entity_id": "ent_WyDmJnQgaxVRH",
  "accounts": ["acc_PFUNazUbpUpfm","acc_gjWr4Cb8H7TLz"]
}
```

This will list all of the accounts that were consented and connected to at least one of the products passed into the Element token creation (Note: Some accounts are ineligible for some products).

## Other Events

For more granular information about specific actions a user is taking, `auth` and `account_verification` will emit the following events.

### Auth

Auth will emit a variety of events that describe how the user is progressing through the authentication process. Most events are of the following form:

```bash theme={null}
AUTH_{STEP}_{ACTION}
```

STEP will reference a step during the auth process: `INTRO`, `NAME`, `PHONE`, `PHONE_VERIFY`, `DOB`, `ADDRESS`, `SSN4`, `SECQ`, and `CONSENT`.

ACTION will refer to the action the user took: `OPEN`, `CONTINUE`, `SUBMIT`, and `CLOSE`.

**Note**: Not all steps will have all actions, and that there are a few actions that do not follow this pattern

For example, if the user was prompted for the last 4 of their SSN, then submitted their info and was directed to the DOB page, you would see the following events:

```bash theme={null}
AUTH_SSN4_OPEN
AUTH_SSN4_CONTINUE
AUTH_DOB_OPEN
```

### Account Verification

Account Verification will emit a variety of events using a similar structure to auth:

```bash theme={null}
AVF_{STEP}_{ACTION}
```

STEP will reference a step during the account verification process: `ACCOUNT_LIST`, `LEARN_MORE`, and `ACCOUNT_VERIFY`.

ACTION will refer to the action the user took: `OPEN`, `CONTINUE`, `SUBMIT`, `SKIP`, and `CLOSE`.

For example, if the user was prompted to verify their credit card, then submitted their info and was directed to the success screen, you would see the following events:

```bash theme={null}
AVF_ACCOUNT_VERIFY_OPEN
AVF_ACCOUNT_VERIFY_SUBMIT
AVF_SUCCESS_OPEN
```


# Element SDKs
Source: https://docs.methodfi.com/elements/libraries



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Method offers a variety of libraries for your frontend application to make integrating
with Elements easy and simple. We also offer [backend libraries](TODO:Where_is_link)
to help manage token creation and using the API more broadly.

## Frontend Libraries

Depending on your application, Method offers three different frontend libraries to help you integrate with Element:

1. [method-js](https://docs.methodfi.com/libraries/js-sdk), for vanilla JavaScript applications
2. [react-method-elements](https://github.com/MethodFi/react-method-elements), for React applications
3. [react-native-method-elements](https://github.com/MethodFi/react-native-method-elements), for React Native applications


# Overview
Source: https://docs.methodfi.com/elements/overview



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Method Elements is a collection of embeddable UI components that make it easy to
integrate Method's API into your experience. Using Method Elements, you can
securely identify your users, connect their liabilities, and move money across
accounts.

## Using Method Elements

<Steps>
  <Step title="Create Element Token">
    Your app's backend will generate an `element_token` by hitting the
    [/elements/token](/reference/elements/tokens) endpoint.
  </Step>

  <Step title="Initialize Element">
    Using the `element_token`, Method Elements will be
    [initialized](/elements/libraries) with the intended Element for your user.
  </Step>

  <Step title="Handling Element Events">
    While your user interacts with an Element,
    [events](/elements/events/overview) will be triggered for your app to
    handle.
  </Step>
</Steps>

### Authentication

Ensure you have an [API key created](/reference/authentication) for your organization in order to request an Element token.


# Overview
Source: https://docs.methodfi.com/libraries/overview



Method offers a list of official libraries that help developers easily
interact and build on top of the Method services.

## API client Libraries

Below is a list of libraries for each supported programming language. These
libraries are updated frequently to provide the best developer experience
when interacting with the Method API.

<CardGroup>
  <Card title="Node.js" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/nodejs-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=57e4626e40345a82da3e7effb6ab274a" />} href="https://github.com/MethodFi/method-node" />

  <Card title="Python" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/python-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=2e67dd38fef1f2c7d80ce0e422f6943c" />} href="https://github.com/MethodFi/method-python" />

  <Card title="OpenAPI" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/openapi-logo.svg?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=96448d2076f343383dd60886f7eebc20" />} href="https://github.com/MethodFi/openapi" />
</CardGroup>

## Element client libraries

Method supports a list of frontend libraries to make integrating Element
into your applications more seamless.

<CardGroup>
  <Card title="Javascript" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/js-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=ea0213b8187f61bcb5c5ecb75abd29f8" />} href="/libraries/js-sdk" />

  <Card title="React" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/react-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=9c683655cfe19c265ac9f077575b7a9e" />} href="https://github.com/MethodFi/react-method-elements" />

  <Card title="React Native" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/react-native-logo.svg?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=a3157c02adfdff112505e4c6ed5d91b0" />} href="https://github.com/MethodFi/react-native-method-elements" />
</CardGroup>

## Quickstart and examples

We've built a couple of quickstart applications to help you get started with
seamlessly building on top of Method.

<CardGroup>
  <Card title="Postman" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/postman-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=e23ad5829a5ea39ac00b25fcc1a34b4d" />} href="https://www.postman.com/methodfi/method-api/collection/8d5j00b/method-api-v2" />
</CardGroup>


# Account Verification
Source: https://docs.methodfi.com/opal/account_verification/overview



<Note>Mode: `account_verification`</Note>

Opal Account Verification is a pre-built flow for verifying a specific account. It provides a secure, compliant way to verify a single, known account (for example, a specific credit card).

<img alt="account-verification-hero" />

## What this mode does

Account Verification drives a focused verification flow for a single, known account (for example, a specific credit card). You must pass the target account\_id. Account Verification will automatically be invoked when needed (for example, during card\_connect), or can be used as a standalone module.

## Parameters

<ParamList />

## Create a token

You can create an account verification session token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `account_verification`
* Create new entity: provide `entity` + `mode` + `account_verification`
* Resume session: provide `session_id` only (omit `mode` and `account_verification`)

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "account_verification",
  "account_verification": { "account_id": "acc_..." }
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15125551234"
    }
  },
  "mode": "account_verification",
  "account_verification": { "account_id": "acc_..." }
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "valid_until": "2025-06-10T22:50:53.024Z",
  "session_id": "osess_..."
}
```

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Verify account</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Verify account" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>


# Card Connect
Source: https://docs.methodfi.com/opal/card_connect/overview



<Note>Mode: `card_connect`</Note>

Opal Card Connect is the primary way to connect user credit cards with Method.
This pre-built flow gathers a user's consent, verifies their identity, and completes any needed verifications to ensure their cards are connected to the Method ecosystem.

<img alt="account-verification-hero" />

## What this mode does

Card Connect lets users select and verify credit cards. Configure whether users may select a single card or multiple cards. Verified cards are eligible for payments and transactions.

## Parameters

<ParamList />

## Create a token

You can create a card connect session token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `card_connect`
* Create new entity: provide `entity` + `mode` + `card_connect`
* Resume session: provide `session_id` only (omit `mode` and `card_connect`)

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "card_connect",
  "card_connect": {
    "selection_type": "single",
    "account_filters": {
      "exclude": {
        "mch_ids": ["mch_123"],
        "unverified_account_numbers": true
      }
    }
  }
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15125551234"
    }
  },
  "mode": "card_connect",
  "card_connect": {
    "selection_type": "multiple"
  }
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "valid_until": "2025-06-10T22:50:53.024Z",
  "session_id": "osess_..."
}
```

## Testing in Development

When testing the frontend for Card Connect in the dev environment, use the following test values:

* **Verification code**: When the modal prompts you to enter a six-digit verification code, you can use any six-digit code. For example: `123456`. This applies to any test case (e.g. identity verification, connect, etc.).
* **Card verification**: Select the Chase card ending in `1580` and use `878` as the CVV.

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Connect Card</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Connect Card" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>


# Connect
Source: https://docs.methodfi.com/opal/connect/overview



<Note>Mode: `connect`</Note>

Opal Connect is the primary way to connect user liability accounts with Method.
This pre-built flow gathers a user's consent, verifies their identity, and completes any needed verifications to ensure their accounts are connected to the Method ecosystem.

<img alt="connect-hero" />

## What this mode does

Connect lets users find and connect their liability accounts (credit cards, loans, mortgages, etc.). Configure whether users may select a single account, multiple accounts, or by default select all eligible accounts.

## Parameters

<ParamList />

## Create a token

You can create a connect session token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `connect`
* Create new entity: provide `entity` + `mode` + `connect`
* Resume session: provide `session_id` only (omit `mode` and `connect`)

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "connect",
  "connect": {
    "selection_type": "single",
    "account_filters": {
      "include": {
        "account_types": ["credit_card", "auto_loan"],
        "products": ["balance"]
      }
    }
  }
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15125551234"
    }
  },
  "mode": "connect",
  "connect": {
    "selection_type": "multiple",
    "account_filters": {
      "exclude": {
        "account_types": ["personal_loan"],
        "mch_ids": ["mch_123"],
        "unverified_account_numbers": true
      }
    }
  }
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "valid_until": "2025-06-10T22:50:53.024Z",
  "session_id": "osess_..."
}
```

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Connect Accounts</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Connect Accounts" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>


# Opal Events
Source: https://docs.methodfi.com/opal/events



Communication between Opal and your app is handled through a consistent, mode-aware event system. Events are emitted throughout the user session to indicate progress, completion, errors, and important milestones.

## Listening to Events

We strongly recommend using one of the Opal SDKs to receive typed events and lifecycle callbacks. The SDKs provide `onEvent`, `onOpen`, and `onExit` handlers and expose a small enum of well-known events under `OpalEventType` for convenience (e.g., `SESSION_STARTED`, `SESSION_COMPLETED`).

Each Opal mode (`identity_verification`, `connect`, `card_connect`, `account_verification`, `transactions`) emits a set of mode‑specific events in addition to default session events. See below for structure, a complete list, and examples.

## Event Structure

All Opal events follow a consistent structure:

```json theme={null}
{
  "type": "opal.session.started",
  "mode": "opal",
  "object": "session",
  "action": "started",
  "timestamp": "2025-06-10T22:50:53.024Z",
  "data": null
}
```

### Event fields

| Field       | Type           | Description                                                                                                     |
| ----------- | -------------- | --------------------------------------------------------------------------------------------------------------- |
| `type`      | string         | Fully qualified event name: `<flow>.<object>.<action>` or `opal.session.<action>` for default session events.   |
| `mode`      | string         | The active operational mode (e.g., `connect`, `identity_verification`, `account_verification`, `transactions`). |
| `object`    | string         | The related object (e.g., `session`, `flow`, `step`, `identity`, `card`, `accounts`).                           |
| `action`    | string         | The action that occurred (e.g., `started`, `completed`, `verified`, `errored`).                                 |
| `timestamp` | string         | ISO 8601 timestamp of when the event occurred.                                                                  |
| `data`      | object \| null | Additional context that varies by event type; may be `null` for lifecycle events.                               |

### Possible flows:

* `identity_verification`
* `connect`
* `account_verification`
* `transactions`

## Sample Events

### opal.session.started

```json theme={null}
{
  "type": "opal.session.started",
  "mode": "connect",
  "object": "session",
  "action": "started",
  "timestamp": "2025-06-10T22:50:53.024Z",
  "data": null
}
```

### opal.session.errored

```json theme={null}
{
  "type": "opal.session.errored",
  "mode": "connect",
  "object": "session",
  "action": "errored",
  "timestamp": "2025-06-10T22:50:53.024Z",
  "data": {
    "type": "INVALID_REQUEST",
    "sub_type": "INVALID_SMS_CODE",
    "message": "Invalid request please try again"
  }
}
```

### connect.flow\.completed

```json theme={null}
{
  "type": "connect.flow.completed",
  "mode": "connect",
  "object": "flow",
  "action": "completed",
  "timestamp": "2025-06-10T22:50:53.024Z",
  "data": {
    "accounts": ["acc_ge9hxMTPGdXmQ"],
    "entity_id": "ent_wrDBN43PR8LKC"
  }
}
```

## Event Categories

### Default session events (always available)

* `opal.session.started` - Opal UI opened and session began
* `opal.session.completed` - User completed the flow successfully
* `opal.session.errored` - A recoverable or terminal error occurred
* `opal.session.exited` - User exited or dismissed Opal

### Generic flow and step events

Emitted in addition to the default session events. These mirror the active mode‑specific events but are prefixed with `opal` and can be emitted for any mode.

#### Flow

* `opal.flow.started` - A sub‑flow of Opal started (e.g., identity verification, account selection, verification).
* `opal.flow.completed` - A sub‑flow of Opal completed. This does not always signify the end of the session; use `opal.session.completed` to detect when Opal is fully completed.

#### Step

* `opal.step.started` - A new step started (e.g., phone input, card selection, CVV input).
* `opal.step.completed` - A step completed and the next page is opening.

Notes:

* Additional mode-specific events may be introduced over time. Your handler should use the `OpalEventType` enum to handle the specific cases you need.

## All Event Types

The following table lists all currently supported event types with their `OpalEventType` mapping, and when they are typically emitted.

| Event (OpalEventType - type)                                              | When you might see it                              |
| ------------------------------------------------------------------------- | -------------------------------------------------- |
| `SESSION_STARTED` - `opal.session.started`                                | Opal UI opened and session began.                  |
| `SESSION_COMPLETED` - `opal.session.completed`                            | User completed the overall Opal flow successfully. |
| `SESSION_ERRORED` - `opal.session.errored`                                | A recoverable or terminal error occurred.          |
| `SESSION_EXITED` - `opal.session.exited`                                  | User closed or dismissed Opal before completion.   |
| `FLOW_STARTED` - `opal.flow.started`                                      | A sub-flow (for any mode) started.                 |
| `FLOW_COMPLETED` - `opal.flow.completed`                                  | A sub-flow (for any mode) completed.               |
| `STEP_STARTED` - `opal.step.started`                                      | A step (screen) started.                           |
| `STEP_COMPLETED` - `opal.step.completed`                                  | A step (screen) completed.                         |
| `IDV_FLOW_STARTED` - `identity_verification.flow.started`                 | Identity Verification flow started.                |
| `IDV_STEP_STARTED` - `identity_verification.step.started`                 | A step in Identity Verification started.           |
| `IDV_STEP_COMPLETED` - `identity_verification.step.completed`             | A step in Identity Verification completed.         |
| `IDV_FLOW_COMPLETED` - `identity_verification.flow.completed`             | Identity Verification flow completed.              |
| `IDV_VERIFICATION_COMPLETED` - `identity_verification.identity.completed` | Identity successfully verified (KYC passed).       |
| `CXN_FLOW_STARTED` - `connect.flow.started`                               | Connect flow started.                              |
| `CXN_STEP_STARTED` - `connect.step.started`                               | A step in Connect started.                         |
| `CXN_STEP_COMPLETED` - `connect.step.completed`                           | A step in Connect completed.                       |
| `CXN_FLOW_COMPLETED` - `connect.flow.completed`                           | Connect flow completed.                            |
| `CXN_ACCOUNTS_SELECTED` - `connect.accounts.selected`                     | User selected one or more accounts to connect.     |
| `AVF_FLOW_STARTED` - `account_verification.flow.started`                  | Account Verification flow started.                 |
| `AVF_STEP_STARTED` - `account_verification.step.started`                  | A step in Account Verification started.            |
| `AVF_STEP_COMPLETED` - `account_verification.step.completed`              | A step in Account Verification completed.          |
| `AVF_FLOW_COMPLETED` - `account_verification.flow.completed`              | Account Verification flow completed.               |
| `AVF_CARD_VERIFIED` - `account_verification.card.verified`                | Card verified successfully.                        |
| `TXN_FLOW_STARTED` - `transactions.flow.started`                          | Transactions flow started.                         |
| `TXN_STEP_STARTED` - `transactions.step.started`                          | A step in Transactions started.                    |
| `TXN_STEP_COMPLETED` - `transactions.step.completed`                      | A step in Transactions completed.                  |
| `TXN_FLOW_COMPLETED` - `transactions.flow.completed`                      | Transactions flow completed.                       |
| `TXN_ACCOUNTS_LINKED` - `transactions.accounts.linked`                    | Accounts linked and subscribed for transactions.   |

### Data Payloads

The following events always include a non-null `event.data` payload:

* `identity_verification.identity.completed`
* `connect.accounts.selected`
* `account_verification.card.verified`
* `transactions.accounts.linked`

Use these payloads to retrieve context such as selected accounts, verification results, or linkage details.

## Enhanced Event Handling

### Using the JavaScript SDK

```javascript theme={null}
import { OpalEventType } from '@methodfi/opal-react';

const config = {
  onEvent: (event) => {
    console.log("Event received:", event.type);

    // Handle specific events using the OpalEventType enum
    switch (event.type) {
      case OpalEventType.SESSION_STARTED:
        // Session lifecycle
        break;
      case OpalEventType.SESSION_COMPLETED:
        // Entire Opal session completed successfully
        break;
      case OpalEventType.SESSION_ERRORED:
        // Handle recoverable or terminal error
        console.error("Opal error:", event.data);
        break;
      case OpalEventType.IDV_VERIFICATION_COMPLETED:
        // Identity verification completed; payload contains verification details
        handleIdentityVerified(event.data);
        break;
      case OpalEventType.CXN_ACCOUNTS_SELECTED:
        // User selected accounts in Connect
        handleAccountsSelected(event.data);
        break;
      case OpalEventType.AVF_CARD_VERIFIED:
        // Card verified in Account Verification
        handleCardVerified(event.data);
        break;
      case OpalEventType.TXN_ACCOUNTS_LINKED:
        // Accounts linked for Transactions
        handleAccountsLinked(event.data);
        break;
      default:
        // Optionally handle generic flow/step events
        break;
    }
  },

  // Specific event handlers
  onSuccess: (payload) => {
    // Called for successful completion events
    console.log("Success:", payload);
  },

  onError: (error) => {
    // Enhanced error handling with detailed information
    console.error("Error:", error.code, error.message);
    console.error("Details:", error.details);
  },
};

const opal = new MethodOpal(config);
```

## PostMessage Communication

For applications not using the Opal SDKs, you can listen to events via PostMessage:

### Setup PostMessage Listener

```javascript theme={null}
window.addEventListener("message", function (event) {
  // Verify origin for security
  if (event.origin !== "https://opal.production.methodfi.com") {
    return;
  }

  const opalEvent = event.data;
  console.log("Opal event:", opalEvent.type, opalEvent.data);

  // Handle events
  switch (opalEvent.type) {
    case OpalEventType.SESSION_STARTED:
      console.log("Opal started");
      break;
    case OpalEventType.SESSION_COMPLETED:
      console.log("Opal completed:", opalEvent.data);
      break;
  }
});
```

## Best Practices

### Event Handling

* Always verify event origins for security
* Use event filtering to reduce noise
* Implement proper error handling for all events
* Log events for debugging and analytics

### Security

* Validate all event data before processing
* Never trust client-side events for critical business logic


# Identity Verification
Source: https://docs.methodfi.com/opal/identity/overview



<Note>Mode: `identity_verification`</Note>

Opal Identity Verification is a pre-built flow for verifying user identity. It provides a secure, compliant way to collect and verify personal information like name, date of birth, address, and other identity details needed for KYC/AML requirements.

<img alt="identity-hero" />

## What this mode does

Identity Verification collects, confirms, and verifies a user's identity details (name, DOB, address, phone, SSN if needed). Users must explicitly confirm their details before verification challenges begin. Identity Verification will automatically be invoked when needed, or can be used as a standalone module.

## Parameters

<ParamList />

## Create a token

You can create an identity verification session token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `identity_verification`
* Create new entity: provide `entity` + `mode` + `identity_verification`
* Resume session: provide `session_id` only (omit `mode` and `identity_verification`)

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "identity_verification",
  "identity_verification": {
    "skip_pii": ["name", "dob", "address"]
  }
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15125551234"
    }
  },
  "mode": "identity_verification",
  "identity_verification": {
    "skip_pii": []
  }
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "valid_until": "2025-06-10T22:50:53.024Z",
  "session_id": "osess_..."
}
```

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Verify identity</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Verify identity" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>


# Libraries
Source: https://docs.methodfi.com/opal/libraries



Method offers a variety of libraries for your frontend application to make integrating with Opal easy and simple.

## Frontend Libraries

Depending on your application, Method offers multiple frontend libraries to help you integrate with Opal:

<CardGroup>
  <Card title="JavaScript SDK" icon="js" href="https://static.methodfi.com/opal/v1/stable/init.js">
    For vanilla JavaScript applications
  </Card>

  <Card title="React SDK" icon="react" href="https://www.npmjs.com/package/@methodfi/opal-react">
    For React applications
  </Card>

  <Card title="React Native SDK" icon="mobile" href="https://www.npmjs.com/package/@methodfi/opal-react-native">
    For React Native applications
  </Card>
</CardGroup>

All Opal SDKs provide:

* **Token Management**: Automatic token validation and refresh
* **Event Handling**: Comprehensive event system with typed callbacks
* **Error Management**: Enhanced error handling with detailed error codes
* **Security**: Built-in security features and validation

## Installation

<Tabs>
  <Tab title="JavaScript">
    ```html theme={null}
    <script src="https://static.methodfi.com/opal/v1/stable/init.js"></script>
    ```
  </Tab>

  <Tab title="React">
    ```bash theme={null}
    npm install @methodfi/opal-react
    ```

    ## Quick usage: React (Web)

    ```tsx theme={null}
    import { OpalProvider, useOpal, OpalEventType } from "@methodfi/opal-react";

    export default function App() {
      return (
        <OpalProvider>
          <YourApp />
        </OpalProvider>
      );
    }

    function YourApp() {
      const { open, close, isOpen, error } = useOpal({
        env: "dev",
        onOpen: () => {},
        onExit: () => {},
        onEvent: (event) => {
          switch (event.type) {
            case OpalEventType.SESSION_STARTED:
              // ...
              break;
            case OpalEventType.SESSION_COMPLETED:
              // ...
              break;
            case OpalEventType.SESSION_ERRORED:
              // ...
              break;
            case OpalEventType.SESSION_EXITED:
              // ...
              break;
          }
        },
      });

      const onLaunchOpal = async () => {
        const token = await getOpalToken(); // POST /opal/token
        open({ token });
      };

      return <button onClick={onLaunchOpal}>Launch Opal</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```bash theme={null}
    npm install @methodfi/opal-react-native
    ```

    ## Quick usage: React Native (Mobile)

    ```tsx theme={null}
    import {
      OpalProvider,
      useOpal,
      OpalEventType,
    } from "@methodfi/opal-react-native";

    export default function App() {
      return (
        <OpalProvider>
          <YourScreen />
        </OpalProvider>
      );
    }

    function YourScreen() {
      const { open } = useOpal({
        env: "dev",
        onOpen: () => {},
        onExit: () => {},
        onEvent: (event) => {
          switch (event.type) {
            case OpalEventType.SESSION_STARTED:
              // ...
              break;
            case OpalEventType.SESSION_COMPLETED:
              // ...
              break;
            case OpalEventType.SESSION_ERRORED:
              // ...
              break;
            case OpalEventType.SESSION_EXITED:
              // ...
              break;
          }
        },
      });

      const onLaunchOpal = async () => {
        const token = await getOpalToken(); // POST /opal/token returns otkn_*
        open({ token });
      };

      return <Button title="Launch Opal" onPress={onLaunchOpal} />;
    }
    ```
  </Tab>
</Tabs>

## Testing in Development

When testing the Opal frontend in the dev environment, any modal step that prompts you to enter a six-digit verification code will accept any six-digit code. For example: `123456`.

## Notes

* Event types follow the format `<flow>.<object>.<action>` or `opal.session.<action>` for defaults
* See [Events](/opal/events) for structure and sample payloads


# Migration from Elements
Source: https://docs.methodfi.com/opal/migration_guide



When migrating from Elements to Opal, there are several key changes to consider:

## URL Changes

If you're launching Opal directly from a URL, the process remains similar to Elements, but with updated domains:

* Elements: `elements.{environment}.methodfi.com`
* Opal: `opal.{environment}.methodfi.com`

## New Libraries

We've introduced new SDKs specifically designed for Opal integration:

* [@methodfi/opal-react](https://www.npmjs.com/package/@methodfi/opal-react) for React applications
* [@methodfi/opal-react-native](https://www.npmjs.com/package/@methodfi/opal-react-native) for React Native
* Direct CDN integration via `https://static.methodfi.com/opal/v1/stable/init.js`

See our [libraries documentation](/opal/libraries) for detailed implementation guides.

## Token Generation Changes

When generating tokens for Opal, we've added new parameters that must be provided in order for more flexibility and control over the user experience. The token generation process has been streamlined in Opal.

### Elements

```json theme={null}
POST /elements/token
{
  "type": "connect",
  "connect": {
    "entity_id": "ent_au22b1fbFJbp8",
    "products": ["balance"],
    "redirect_url": "https://example.com/callback"
  }
}
```

### Opal

```json theme={null}
POST /opal/token
{
  "mode": "connect",
  "entity_id": "ent_au22b1fbFJbp8",
  "connect": {
    "selection_type": "single",
    "account_filters": {
      "include": {
        "account_types": ["credit_card", "auto_loan"],
        "products": ["balance"]
      }
    }
  }
}
```

In Elements, product filtering was a top-level field (`connect.products`). In Opal, product filtering is done via `connect.account_filters.include.products`. Allowed values: `balance`, `sensitive`, `payoff`, `update`, `payment`.

See Opal [Identity](/opal/identity/overview), [Connect](/opal/connect/overview), [Card Connect](/opal/card_connect/overview), and [Account Verification](/opal/account_verification/overview) guides for more info on token generation.


# Overview
Source: https://docs.methodfi.com/opal/overview

Method Opal - Next-generation embeddable financial components

Method Opal is the single embeddable UI component that provides enhanced
financial connectivity and user experience. Opal serves as a modern replacement
for Method Elements, offering improved performance, better customization, and
advanced features for integrating Method's API into your application.

<img alt="title" />

## What is Opal?

Method's embedded financial platform, with built-in orchestration of
identity, account connection, verification, and transaction streaming- all
in one cohesive experience for end-users.

## Using Method Opal

<Steps>
  <Step title="Create an Entity">
    Create an entity for your user using the
    [Entities](/reference/entities/overview) endpoint.
  </Step>

  <Step title="Create Opal Token">
    Generate an Opal Token by using the [Create Token](/reference/opal/create_token#create-token)
    endpoint.
  </Step>

  <Step title="Launch Opal">
    Using the Opal Token, launch Opal with one of our
    [libraries](/opal/libraries) to launch the intended Opal component for your
    user. Method will handle the rest!
  </Step>

  <Step title="Optional: Handle Opal Events">
    While your user interacts with an Opal component,
    [events](/opal/events) will be triggered for your app to handle.
  </Step>
</Steps>

## Opal Modes

Opal provides several pre-built modes for different use cases:

### [Identity Verification](/opal/identity/overview)

Collect and verify user identity only.

### [Connect](/opal/connect/overview)

Connect user liability accounts.

### [Card Connect](/opal/card_connect/overview)

Verify and connect cards for access to payments.

### [Account Verification](/opal/account_verification/overview)

Verify account ownership with real-time verification.

### [Transactions](/opal/transactions/overview)

Stream transactions for a user's credit cards.

## Understanding Modes and Flows

Opal Modes are typically made up of one or more flows. Modes are the different types of Opal components that can be launched, while flows are the different stages within a mode. For example, the Card Connect mode has a flow for identity verification (`identity_verification`), account selection (`connect`), and verification (`account_verification`).

## Getting Started

Ready to integrate Opal into your application? Start with our [Opal Libraries](/opal/libraries) to choose the right SDK for your platform!

<CardGroup>
  <Card title="Opal Libraries" href="/opal/libraries">
    Choose the right SDK for your platform
  </Card>

  <Card title="API Reference" href="/reference/opal/overview">
    Complete API documentation for Opal endpoints
  </Card>

  <Card title="Events Guide" href="/opal/events">
    Learn how to handle Opal events in your application
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.methodfi.com/opal/quickstart

Get started with Method Opal in minutes

This quickstart guide will help you integrate Method Opal into your application in just a few steps. Opal provides enhanced performance, better security, and advanced features compared to Elements.

## Prerequisites

Before you begin, make sure you have:

* A Method account with API access
* Your Method API key
* A web application or development environment

## Step 1: Install the Opal SDK

Choose the appropriate SDK for your application:

<CodeGroup>
  ```html JavaScript (CDN) theme={null}
  <script src="https://static.methodfi.com/opal/v1/stable/init.js"></script>
  ```

  ```bash React theme={null}
  npm install @methodfi/opal-react
  ```

  ```bash React Native theme={null}
  npm install @methodfi/opal-react-native
  ```
</CodeGroup>

## Step 2: Create an Entity

First, create an entity for your user:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "individual",
      "individual": {
        "first_name": "John",
        "last_name": "Doe",
        "phone": "+15121234567",
        "email": "john.doe@example.com"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const entity = await method.entities.create({
    type: "individual",
    individual: {
      first_name: "John",
      last_name: "Doe",
      phone: "+15121234567",
      email: "john.doe@example.com",
    },
  });
  ```

  ```python Python theme={null}
  entity = method.entities.create({
    'type': 'individual',
    'individual': {
      'first_name': 'John',
      'last_name': 'Doe',
      'phone': '+15121234567',
      'email': 'john.doe@example.com'
    }
  })
  ```
</CodeGroup>

## Step 3: Create an Opal Token

Create an Opal token for the Connect component:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/opal/token \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "entity_id": "ent_fc92i43kc34",
      "mode": "connect",
      "connect": {
        "selection_type": "single",
        "account_filters": {
          "include": {
            "account_types": ["credit_card", "auto_loan"]
          }
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const { token, valid_until, session_id } = await method.opal.token.create({
    entity_id: entity.id,
    mode: "connect",
    connect: {
      selection_type: "single",
      account_filters: {
        include: {
          account_types: ["credit_card", "auto_loan"],
        },
      },
    },
  });
  ```

  ```python Python theme={null}
  res = method.opal.token.create({
    'entity_id': entity.id,
    'mode': 'connect',
    'connect': {
      'selection_type': 'single',
      'account_filters': {
        'include': {
          'account_types': ['credit_card', 'auto_loan']
        }
      }
    }
  })
  ```
</CodeGroup>

## Step 4: Initialize Opal in Your Frontend

<CodeGroup>
  ```html JavaScript (CDN) theme={null}
  <script src="https://static.methodfi.com/opal/v1/stable/init.js"></script>

  <button id="connect-button">Connect Your Account</button>

  <script>
    document
      .getElementById("connect-button")
      .addEventListener("click", async () => {
        // Get token from Method
        const response = await fetch(`${baseURL}/opal/token`, {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({
            entity_id: "ent_fc92i43kc34",
            mode: "connect",
            connect: {
              selection_type: "single",
              account_filters: {
                include: {
                  account_types: ["credit_card", "auto_loan"],
                },
              },
            },
          }),
        });
        const { token } = await response.json();

        // Open iframe with token
        const iframe = document.createElement("iframe");
        iframe.src = `https://opal.${env}$.methodfi.com?token=${token}`;
        iframe.style.width = "100%";
        iframe.style.height = "600px";
        iframe.style.border = "none";
        document.body.appendChild(iframe);
      });
  </script>
  ```

  ```jsx React theme={null}
  import { OpalProvider, useOpal } from "@methodfi/opal-react";

  function App() {
    return (
      <OpalProvider>
        <ConnectButton />
      </OpalProvider>
    );
  }

  function ConnectButton() {
    const { open } = useOpal();

    const handleConnect = async () => {
      // Get token from Method
      const response = await fetch(`${baseURL}/opal/token`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          entity_id: "ent_fc92i43kc34",
          mode: "connect",
          connect: {
            selection_type: "single",
            account_filters: {
              include: {
                account_types: ["credit_card", "auto_loan"],
              },
            },
          },
        }),
      });
      const { token } = await response.json();

      // Launch Opal
      open({ token });
    };

    return <button onClick={handleConnect}>Connect Your Account</button>;
  }
  ```

  ```jsx React Native theme={null}
  import { OpalProvider, useOpal } from "@methodfi/opal-react-native";
  import { Button } from "react-native";

  function App() {
    return (
      <OpalProvider>
        <ConnectButton />
      </OpalProvider>
    );
  }

  function ConnectButton() {
    const { open } = useOpal();

    const handleConnect = async () => {
      // Get token from Method
      const response = await fetch(`${baseURL}/opal/token`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          entity_id: "ent_fc92i43kc34",
          mode: "connect",
          connect: {
            selection_type: "single",
            account_filters: {
              include: {
                account_types: ["credit_card", "auto_loan"],
              },
            },
          },
        }),
      });
      const { token } = await response.json();

      // Launch Opal
      open({ token });
    };

    return <Button title="Connect Your Account" onPress={handleConnect} />;
  }
  ```
</CodeGroup>

## Next Steps

Now that you have Opal working, explore these advanced features:

<CardGroup>
  <Card title="Advanced Configuration" href="/opal/connect/overview">
    Learn about advanced Opal Connect features and configuration options
  </Card>

  <Card title="Event Handling" href="/opal/events">
    Master Opal's comprehensive event system
  </Card>

  <Card title="Migration Guide" href="/opal/migration_guide">
    Migrate from Elements to Opal
  </Card>
</CardGroup>

### Getting Help

* **Documentation**: [Complete Opal Documentation](/opal/overview)
* **API Reference**: [Opal API Reference](/reference/opal/overview)
* **Support**: Contact your Method CSM


# Sessions
Source: https://docs.methodfi.com/opal/sessions

Maintain state and user data across Opal interactions.

Opal Sessions are long-lived stateful connections between your app and Opal.
They allow you to store user data, resume user sessions, and retrieve data later.
Sessions are created when you create an Opal Token, and when passed into Opal,
they are automatically resumed.

## Creating a new session

First, create a new Opal Token with your desired configuration. This will create a new session.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/opal/token \
    -X POST \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "mode": "card_connect",
      "entity_id": "ent_fc92i43kc34",
      "card_connect": {
        "selection_type": "single"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "token": "otkn_THpBacqVBBrDkfqUf9htjm4QWAEJLY9a",
      "valid_until": "2025-05-08T22:21:40.312Z",
      "session_id": "osess_zde3mW34pEHqV"
    },
    "message": null
  }
  ```
</ResponseExample>

## Resuming an existing session

To resume an existing session, create a new token by passing the `session_id` from a previous session

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/opal/token \
    -X POST \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "session_id": "osess_zde3mW34pEHqV"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "token": "otkn_THpBacqVBBrDkfqUf9htjm4QWAEJLY9a",
      "valid_until": "2025-05-08T22:21:40.312Z",
      "session_id": "osess_zde3mW34pEHqV"
    },
    "message": null
  }
  ```
</ResponseExample>


# Transactions
Source: https://docs.methodfi.com/opal/transactions/overview



<Note>Mode: `transactions`</Note>

Opal Transactions is the primary way to obtain consent and subscribe to real-time transactions.
This pre-built flow gathers a user's consent, verifies their identity, and prompts them to select the accounts eligible to be subscribed to.

<img alt="transactions-hero" />

## What this mode does

Transactions will provide a seamless experience for a user to subscribe to real-time transaction updates for supported accounts.
Eligible accounts will be automatically determined by Method, including your team's eligibility criteria.

For details on how to receive transaction updates via [Webhooks](/reference/webhooks/create). Make sure you are subscribed to the relevant webhook events to receive real-time transaction data. Note that you will only receive updates for events that occur after your subscription is active.

Please reach out to your CSM to enable access to this mode!

## Create a token

You can create a transactions token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `transactions`
* Create new entity: provide `entity` + `mode` + `transactions`

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "transactions",
  "transactions": {}
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {}
  },
  "mode": "transactions",
  "transactions": {}
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "session_id": "osess_...",
  "valid_until": "2025-06-10T22:50:53.024Z"
}
```

## Resuming a session

Want to link more cards? In this mode, simply create another token with the same `entity_id` and Method will intelligently pick up where your user left off. They won't ever be asked to link a card twice!

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({
        env: "dev",
        onEvent: (e) => {},
        onExit: (e) => {},
      });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Link Transactions</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({
        env: "dev",
        onEvent: (e) => {},
        onExit: (e) => {},
      });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Link Transactions" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>


# December Updates
Source: https://docs.methodfi.com/changelog/2024/december



## New Features

### New Method Dashboard

<img alt="title" />

We’re thrilled to announce early access to the **all-new Method Dashboard**, purposefully redesigned to harness the full potential of our API’s V2 capabilities.

This intuitive interface is crafted to empower both technical and non-technical team members with:

* Role-based access control
* Advanced data visualization
* Custom reporting capabilities
* Universal search functionality
* Self-service team management
* Key rotation tools
* SSO and Passkey authentication

Everyone across your team can now use the new Method Dashboard:

* **CX** – monitor and troubleshoot any issues associated with end-user data.
* **Engineering** – create API keys and monitor webhooks.
* **Finance** – view high-level metrics to better understand billing.

**How to access?**
Dashboard v2 is available for all teams, including existing ones, ensuring a seamless transition to the new interface.
Log in with your email at [app.methodfi.com](https://app.methodfi.com) to explore the new features!

### Vehicles API

<img alt="title" />

The [Vehicles API](https://docs.methodfi.com/reference/entities/vehicles/overview) enables your application to access detailed vehicle information with minimal PII. This data can help you unlock valuable insights and drive better decision-making.

**Key Use Cases**

* **Increase conversion** with pre-filled vehicle details by optimizing loan repayment terms using the vehicle's depreciation curve.
* **Enhance credit risk underwriting** by leveraging vehicle ownership details.
* **Enable personalized financial management** by correlating vehicle data with user behavior insights.

For example, you can retrieve data such as the vehicle's `VIN`, `year`, `make`, `model`, `color`, and `style`.

The Vehicles API is now available to all teams on Method’s V2 API (version: 2024-04-04). Contact your Method CSM to get access!

***

## Improvements

### Account Verification Limits

To bolster system security and performance, we've introduced new verification limits:

* **Account Verification Session limits**: Up to 10 failed attempts per session.
* **Account-level verification limits**:
  * Maximum of 5 sessions per verification type.
  * Maximum of 10 total sessions across all types.

For more details, visit [Account Verification Sessions Errors](https://docs.methodfi.com/reference/errors/account-verification-session-errors).

***

## SDK Updates

* Released [version 1.1.5](https://github.com/MethodFi/method-python/releases/tag/v1.1.5) of `method-python`.
  * [Vehicles API](https://docs.methodfi.com/reference/entities/vehicles/overview) is now available in `method-python`.
* Released [version 1.1.6](https://github.com/MethodFi/method-node/releases/tag/v1.1.6) of `method-node`.
  * [Vehicles API](https://docs.methodfi.com/reference/entities/vehicles/overview) is now available in `method-node`.


# November Updates
Source: https://docs.methodfi.com/changelog/2024/november



## New Features

### Payment Posted Confirmation

<img alt="title" />

We’re excited to announce [`posted`](https://docs.methodfi.com/reference/payments/overview#possible-enum-values:~:text=The%20Payment%20has%20been%20posted%20to%20the%20destination%20Account), a new payment status that closes the loop on payments by confirming when they have successfully landed in your users’ accounts.

With **real-time account data**, Method now provides a level of visibility that was previously unavailable in the U.S. financial system. By knowing if and when a payment has been applied, you can deliver timely and actionable updates to your users—boosting confidence and creating a seamless payment experience.

**Key highlights:**

* **Enabled for all payments**: The feature is live for all teams and payments processed via Method’s V2 API (version: `2024-04-04`) going forward.
* **No action required**: Start using this feature immediately—just consume the new status in your integration.
* **75% coverage**: We expect approximately 75% visibility into posted status, with improved coverage as more accounts are subscribed to updates.
* **Unlock new use cases**: Use the posted status to notify users via push notifications, emails, or in-app messages, keeping them informed and engaged.
* **Account subscription required**: In a future release, the posted status will only be available for accounts subscribed to updates.

### New Method Brand

<img alt="title" />

We’re excited to introduce Method’s new visual identity, marking a new chapter in our journey under the same thesis we had on day one: consumer financial data is a walled garden, and we’re going to be the ones to open it up.

The updated design features:

* A new icon and wordmark
* A refined color palette centered around Method Opal: a bold, fresh, and vibrant cyan
* A new [website](https://methodfi.com/)

Read more about the redesign [here](https://methodfi.com/blog/rebranding-method).

***

## Improvements

### Detailed Webhook Errors

[Webhook Errors](https://docs.methodfi.com/reference/errors/webhook-errors) now includes detailed explanations of issues that caused your webhook to be disabled.

Webhook objects now feature an `error` field following the common Method error format. The error codes for webhook errors are:

* 25001 – `WEBHOOK_DISABLED_FAILED_OTHER`: Indicates five consecutive failures not classified as 4XX, 5XX, or timeouts.
* 25002 – `WEBHOOK_DISABLED_RECEIVED_4XX_ERROR`: The endpoint returned client errors (4XX) five times.
* 25003 – `WEBHOOK_DISABLED_RECEIVED_5XX_ERROR`: The endpoint returned server errors (5XX) five times.
* 25004 – `WEBHOOK_DISABLED_TIMEOUT_ON_RESPONSE`: No valid response received within 5 seconds for five consecutive attempts.

### New List Endpoints

We’ve expanded our API capabilities by introducing list functionality for the following resources, allowing you to retrieve comprehensive collections, such as all updates or credit scores, for a specific account or entity.

* [Attributes](https://docs.methodfi.com/reference/entities/attributes/list)
* [Credit Scores](https://docs.methodfi.com/reference/entities/credit-scores/list)
* [Connects](https://docs.methodfi.com/reference/entities/connect/list)
* [Identities](https://docs.methodfi.com/reference/entities/identities/list)
* [Entity Verification Sessions](https://docs.methodfi.com/reference/entities/verification-sessions/list)
* [Card Brands](https://docs.methodfi.com/reference/accounts/card-brands/list)
* [Account Updates](https://docs.methodfi.com/reference/accounts/updates/list)
* [Payoffs](https://docs.methodfi.com/reference/accounts/payoffs/list)
* [Sensitive](https://docs.methodfi.com/reference/accounts/sensitive/list)
* [Account Balances](https://docs.methodfi.com/reference/accounts/balances/list)
* [Account Verification Sessions](https://docs.methodfi.com/reference/accounts/verification-sessions/list)

### Elements API

* Removed the ability to pass in `card_brand` in the `products` array when creating an [Element Token](https://docs.methodfi.com/reference/elements/tokens).

***

## SDK Updates

* Released [version 1.1.4](https://github.com/MethodFi/method-python/releases/tag/v1.1.4) of Method Python client (`method-python`).
  * All new `list` endpoints are now available in the Python client.
  * Added `posted` as an enum value for the `payment.status` field.
* Released [version 1.1.5](https://github.com/MethodFi/method-node/releases/tag/v1.1.5) of Method Node.js client (`method-node`).
  * All new `list` endpoints are now available in the Node.js client.
  * Added `posted` as an enum value for the `payment.status` field.


# October Updates
Source: https://docs.methodfi.com/changelog/2024/october



## New Products

### Events API

<img alt="title" />

The [Events API](https://docs.methodfi.com/reference/events/overview) allows your application to monitor specific changes to Method resources.

* For example, you can now be notified when an entity's credit score increases (event type: `credit_score.increased`)
  or if new derogatory marks appear (event type: `attribute.credit_health_derogatory_marks.increased`)

* Events deliver detailed and actionable notifications across all Method products and resources, making webhooks more targeted and specific.
  This ensures you receive alerts for the updates that matter to your application and users.

* Events are classified into two types:
  * Literal changes: Direct updates to a specific field in a resource.
  * Computed changes: Interpreted states derived from multiple field changes or comparisons across different records.

* The Events API is now available to all teams on Method’s V2 API (version: 2024-04-04). This launch includes 10 initial events, with over 100 additional events planned for release in the coming weeks.

### Attributes API

<img alt="title" />

The [Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview) offers a powerful summary of financial profile metrics across all Method API resources.

* For example, it provides real-time indicators on credit utilization, payment reliability, account age, and derogatory marks, allowing developers to access these metrics directly without piecing together data from multiple endpoints.

* Powered by Method’s real-time data integrations, it provides up-to-date insights ensuring your application accesses the most current data for faster, more informed decisions.

* This initial release emphasizes credit health attributes, offering a holistic view of financial stability and risk.

* For information on accessing the Attributes API, please reach out to your Method CSM.

***

## Improvements

### Card Brands API

* Improved our card network integrations (Visa and Mastercard) to deliver lower latencies on Card Brands API requests.
* Expanded coverage across all card products, including providing a reliable unique ID associated with each card product (for example all Chase Sapphire Reserve's across all entities will return the same brand ID)
  * Brand ID is returned within `card_brand.brands[x].id` in the format `brand_*`.

### Credit Scores API

* We've upgraded our Credit Scores API to use VantageScore 4.0, the latest version of the scoring model.
* VantageScore 4.0 provides more predictive scoring by incorporating machine learning techniques and trended credit data, which analyzes credit behaviors over time rather than just a snapshot.
* This upgrade enables more accurate credit risk assessment, especially for consumers with limited credit history.

***

## SDK Updates

* Released [version 1.1.2](https://github.com/MethodFi/method-python/releases/tag/v1.1.2) of Method Python client (`method-python`).
  * [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview) is now available in the Python client.
  * [Events API](https://docs.methodfi.com/reference/events/overview) is now available in the Python client.
* Released [version 1.1.3](https://github.com/MethodFi/method-node/releases/tag/v1.1.3) of Method Node.js client (`method-node`).
  * [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview) is now available in the Node.js client.
  * [Events API](https://docs.methodfi.com/reference/events/overview) is now available in the Node.js client.
* Released [version 2 of Method API Postman Collection](https://www.postman.com/methodfi/method-api/collection/8d5j00b/method-api-v2).


# September Updates
Source: https://docs.methodfi.com/changelog/2024/september



## Improvements

### Performance & Infrastructure

* Improved idempotency locking mechanism to handle simultaneous idempotent requests received across different regions / PoP.
* Under-the-hood liability payment rail improvements to faster settlement time across all major FIs.
* Card Brand has been optimized for increased success speed.
* Expanded checks for invalid update payload from upstream data providers.

### Payment Coverage

* Released new integration with SoFi Personal Loans for near real-time payment settlement speed.
* Payment channels for Sallie Mae, US Bank, and AMEX have been revamped and optimized for speed of posting.
* Additional personal loan payment channels have been enabled - improving payment coverage and speed to posting.
* BMO Harris credit cards are now fully payable when account is connected via Method Connect.

### Developer Experience

* `micro_deposits` verification sessions are now simulatable in dev.
* Speed of `micro_deposists` simulation in dev environment has been increased.
* Expanded Card Brand simulated response in dev environment.
* Improved Student Loans [updates](https://docs.methodfi.com/reference/accounts/updates/overview) documentation for dev environment responses.
* Element now throws an error if any of the requested products are not enabled for the requesting team.

### Account Connectivity

* Improved account update stability for Quicken Loans, Home Depot (Citi), Credit One, and other major FIs.
* "Instant Link" verification was optimized across all networks.
* Visual interaction during the manual Connect Element flow have been streamlined to optimize for conversion.

### Reporting

* Daily emailed reconciliation reports now include the team name in the subject line.
  * e.g. (`Method: Daily ACH Report`) -> (`Method: Daily ACH Report for ${team_name}`)

***

## SDK Updates

* Released [version 1.1.0](https://github.com/MethodFi/method-python/releases/tag/v1.1.0) of Method Python client (`method-python`).
  * [Request ID](/reference/request-id) is now easily accessible via the `last_response` property - we highly recommend logging the request ID for faster issue resolution.
  * This update also includes security updates and test coverage expansion.
* Released [version 1.1.1](https://github.com/MethodFi/method-node/releases/tag/v1.1.1) of Method Node.js client (`method-node`).
  * [Request ID](/reference/request-id) is now easily accessible via the `last_response` property - we highly recommend logging the request ID for faster issue resolution.
  * This update also includes security updates and test coverage expansion.


# April Updates
Source: https://docs.methodfi.com/changelog/2025/april



## New Features

### Dashboard Updates

<img alt="sso" />

We're continuing to improve the Dashboard experience with a few powerful updates:

* **SSO Support** – You can now log in using Single Sign-On. Reach out to your Method CSM to enable SSO for your team.
* **Multi-Team Search** – If you're a member of multiple teams, you can now quickly search and switch between them with ease.
* **PDF Export** – It is now possible to download Entity and Account details as a PDF. Contact your Method CSM to get access to this feature.

## Improvements

### Entity Attribute Handling

We've updated how Entity Attributes are requested. You must now explicitly specify which attributes you'd like to retrieve using a new payload format.

<Warning>Some attributes are restricted by default. Reach out to your Method CSM to get access to these attributes.</Warning>

<Accordion title="Previous">
  ```js theme={null}
  const response = await method
      .entities('ent_TYHMaRJUUeJ7U')
      .attributes
      .create();
  ```
</Accordion>

<Accordion title="New">
  ```js theme={null}
  const response = await method
      .entities('ent_TYHMaRJUUeJ7U')
      .attributes
      .create({
          attributes: [
              "credit_health_credit_card_usage",
              "credit_health_derogatory_marks",
              "credit_health_hard_inquiries",
              "credit_health_soft_inquiries",
              "credit_health_total_accounts",
              "credit_health_credit_age",
              "credit_health_payment_history",
              "credit_health_open_accounts",
              "credit_health_entity_delinquent"
          ]
      });
  ```
</Accordion>

For more details, refer to the [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/create).

### Entity Subscription Creation

Entity subscription creation has been updated to support a new payload format.

<Accordion title="Previous">
  ```js theme={null}
  const response = await method
    .entities('ent_TYHMaRJUUeJ7U')
    .subscriptions
    .create('credit_score');
  ```
</Accordion>

<Accordion title="New">
  ```js theme={null}
  const response = await method
    .entities('ent_TYHMaRJUUeJ7U')
    .subscriptions
    .create({
      enroll: 'credit_score',
    });
  ```
</Accordion>

To enroll in an Entity Attribute subscription, use this format:

```js theme={null}
const response = await method
  .entities('ent_TYHMaRJUUeJ7U')
  .subscriptions
  .create({
    enroll: 'attribute',
    payload: {
      attributes: {
        requested_attributes: [
            'credit_health_credit_card_usage', 
            'credit_health_derogatory_marks'
        ]
      }
    }
  });
```

For more details, refer to the [Entity Subscriptions API](https://docs.methodfi.com/reference/entities/subscriptions/create).

## SDK Updates

* Released [version 1.1.14](https://github.com/MethodFi/method-node/releases/tag/v1.1.14) of `method-node`
* Released [version 1.1.13](https://github.com/MethodFi/method-python/releases/tag/v1.1.13) of `method-python`


# August Updates
Source: https://docs.methodfi.com/changelog/2025/august



## New Features

### Opal

<img alt="opal" />

We're excited to introduce [Opal](/opal/overview), our new embedded UI that can easily be dropped into your existing onboarding flow, enabling a white-labeled, seamless connection to Method. It replaces our current Element UI, allowing you to customize the copy, themes, and other UI components to maintain continuity in your interface and prevent users from feeling like they are moving to a third-party app.

Opal has four different components:

* **Identity Verification (IDV):** collects, confirms, and verifies a user’s identity
* **Connect (CXN):** surfaces all of a user's liability accounts
* **Account Verification (AVF):** verifies credit card details and tokenizes them for payments and checkout use cases
* **Transactions (TXN):** enables users to select cards that they wish to link transaction data

**How it works:**

* Opal is a drop-in SDK, designed for quick and easy integration with minimal effort to implement
* Launch with a single token that’s generated with a mode (e.g., connect, card connect, etc.) and whatever additional parameters you choose
* Once launched, Method handles all of the business logic of the flow, automatically orchestrating all of the information the user needs to provide and determining what part of the flow to route the user to next
* Tokens are persistent - users can pick up exactly where they dropped off
* UI is embedded via JavaScript, React, or React Native

For more information, please visit the [Opal Quickstart](/opal/quickstart) page.


# December Updates
Source: https://docs.methodfi.com/changelog/2025/december



## New features

### Payment Instruments API

Method now supports inbound funding workflows. We’ve added a new `PaymentInstrument` type: `inbound_achwire_payment` which allows liability accounts (e.g., loans, credit cards) to receive direct payments via ACH or wire transfer.

* This feature provisions a unique virtual account number and routing number linked to a specific Method Account, effectively making the underlying liability routable. Third parties can send funds directly to these credentials, and Method automatically applies the funds to the associated account, without requiring you to explicitly create a Payment.

**How it works:**

1. **Create Instrument**: Create a Payment Instrument of type `inbound_achwire_payment` for a specific Method Account
2. **Receive Banking Details**: Method returns unique `account_number` and `routing_number`
3. **Share with a Third Party**: Provide these banking details to a third party (e.g., payroll provider, refinance lender, or another bank)
4. **Inbound Transfer**: When funds are sent to these credentials, Method receives the inbound ACH or wire transfer
5. **Automatic Application**: Method automatically applies the received funds to the associated account

<Note>Available when passing `Method-Version: 2025-12-01` in the request header.</Note>

## Improvements

### Simulate API

The [Simulate API](/reference/simulations/overview) now supports retrieving micro-deposit amounts and simulating inbound ACH / wire payments for inbound\_achwire\_payment Payment Instruments — making it easier for developers to test account verification and inbound payment flows in the development environment.

**[Retrieve Micro-deposit Amounts](/reference/simulations/verification-sessions/get-microdeposit-amounts)**

* This endpoint enables developers to retrieve the exact micro-deposit amounts required to complete ACH account verification flows in the development environment.

**[Simulate Inbound ACH/Wire Payments](/reference/simulations/payment_instruments/create)**

* This endpoint allows developers to simulate receiving an inbound payment and triggers the same automatic payment application logic used in production.

<Warning>This API is available in the development environment only.</Warning>

For more information, visit the [Simulations API](/reference/simulations/overview) documentation.

### Webhooks

We added support for a new webhook event type: `account.number.update`.

* This account-level webhook is triggered when an account number has been updated, allowing developers to be notified of account number changes without polling.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Entities API

The Entities API now supports updating `metadata` via `PUT /entities/{ent_id}`.

* This enables developers to update an Entity's metadata without recreating the Entity, simplifying lifecycle management.

For more information, please refer to the [Update an Entity](/reference/entities/update-entity) documentation.


# February Updates
Source: https://docs.methodfi.com/changelog/2025/february



## New Features

### Dashboard Payment Details Page

<img alt="payment details" />

We've upgraded the Payments experience with a brand-new dedicated Payment Details Page

Now, you get more insights and control than ever before:

* **Payment Timeline** –> Track the full journey of your payments, end to end.
* **Enhanced Payment Info** –> Quickly see whether a payment was made via electronic or paper.
* **Check Images** –> For paper payments, view the check image (if available) directly within the details page.

## Improvements

### Payments API

We've added two new fields to the Payments API to provide better visibility into payment details:

* `destination_payment_method`: Indicates how the payment was delivered to the recipient - either `electronic` or `paper`
* `destination_status`: New status `cashed` available to track when paper checks have been processed

For more information, see our [Payments API documentation](https://docs.methodfi.com/reference/payments/overview).

## SDK Updates

* Released [version 1.1.9](https://github.com/MethodFi/method-python/releases/tag/v1.1.9) of `method-python`
* Released [version 1.1.10](https://github.com/MethodFi/method-node/releases/tag/v1.1.10) of `method-node`


# January Updates
Source: https://docs.methodfi.com/changelog/2025/january



## New Features

### Account Attributes API

<img alt="account attributes" />

We've released a brand new [Account Attributes API](https://docs.methodfi.com/reference/accounts/attributes/overview) that's powered by Method's real-time data integrations for up-to-date insights. It provides:

* Real-time indicators for individual account usage patterns
* Account utilization metrics
* Account standing information
* Delinquency data (period, outcome, and amount)

For access to the Account Attributes API, please contact your Method CSM.

## Improvements

### Entity Attributes API

We've enhanced the [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview) with two new attributes:

* `credit_health_open_accounts`: Total number of open accounts
* `credit_health_entity_delinquent`: Entity delinquency status, rating and a list of delinquent accounts

**Pro tip**: Leverage both the Account Attributes API and the Entity Attributes API to get a holistic view of an entity's credit health.

### Method Dashboard

We've made significant performance and usability improvements to the [Method Dashboard](https://app.methodfi.com):

* Pages load 3x faster. We also made navigating between pages feel a lot better.
* Charts load 2x faster. We also fixed hovering over the bars so it works well.
* Universal Search is now keyboard navigable. You can use your up/down arrows and hit enter.
* Added the ability to right click on a table row and open it in a new tab.
* Created better financial account logos. We will continue to fix bad ones.
* Changed the layout of information on details pages to make reading easier.

Please reach out in Slack with any feedback. We will put your requests at the top of our to-do list.

### Payment Dry-run

We've added a new `dry_run` boolean flag to the `POST /payments` endpoint. When enabled, it will simulate a payment without triggering the actual payment flow. You'll receive accurate information about the payment timeline, helping you preview the payment flow and communicate accurate timing to your users before initiating an actual payment. For more information, see our [Payments API](https://docs.methodfi.com/reference/payments/overview).

## SDK Updates

* Released [version 1.1.8](https://github.com/MethodFi/method-python/releases/tag/v1.1.8) of `method-python`
* Released [version 1.1.9](https://github.com/MethodFi/method-node/releases/tag/v1.1.9) of `method-node`


# July Updates
Source: https://docs.methodfi.com/changelog/2025/july



## New Features

### Message-Level Encryption (MLE)

<img alt="MLE" />

We’ve added support for end-to-end encryption of sensitive data transmitted between your application and Method’s API, available to everyone. Here’s what’s new:

* **Hybrid Encryption:** Uses AES-GCM (for payload encryption) and RSA-OAEP-256 (for key encryption) to ensure confidentiality even if network traffic is intercepted.

* **Public Key Registration:** Register your RSA public key with Method via a `.well-known` endpoint or direct upload.

* **Encrypted Requests & Responses:** Send encrypted payloads using the `Method-MLE: jwe` header; Method encrypts responses using your public key.

* **Key Management:** Support for key rotation, deprecation, deletion, and webhook notifications for Method key changes.

You can find a [quickstart guide here](/reference/message-level-encryption#quickstart). For more information, please refer to the [Message Level Encryption documentation](/reference/message-level-encryption).

### Card Brand API

<img alt="Card Brands" />

We’ve expanded the Card Brand object to provide a more structured format with richer brand details — making it easier to identify, display, and integrate specific card products with consistent issuer, network, and branding data.

<Note>Available when passing `Method-Version: 2025-07-04` in the request header.</Note>

<Accordion title="Previous">
  ```json theme={null}
  {
    "id": "cbrd_eVMDNUPfrFk3e",
    "account_id": "acc_yVf3mkzbhz9tj",
    "network": "visa",
    "issuer": "Chase",
    "last4": "8623",
    "brands": [
      {
        "id": "brand_AMxtjQzAfDCRP",
        "name": "Chase Sapphire Reserve",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
      }
    ],
    "status": "completed",
    "shared": false,
    "source": "network",
    "error": null,
    "created_at": "2024-03-19T01:05:37.247Z",
    "updated_at": "2024-03-19T01:05:37.247Z"
  }
  ```
</Accordion>

<Accordion title="New">
  ```json theme={null}
  {
    "id": "cbrd_Accm7P6t6mYQP",
    "account_id": "acc_LxwEqNicr66yP",
    "brands": [
      {
        "id": "pdt_15_brd_1",
        "card_product_id": "pdt_15",
        "description": "Chase Sapphire Reserve",
        "name": "Chase Sapphire Reserve",
        "issuer": "Chase",
        "network": "visa",
        "network_tier": "infinite",
        "type": "specific",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
      }
    ],
    "status": "completed",
    "source": "method",
    "error": null,
    "created_at": "2025-08-12T00:56:50.139Z",
    "updated_at": "2025-08-12T00:56:50.139Z"
  }
  ```
</Accordion>

**Key Changes**:

* `network` and `issuer` are now nested inside each brand object.
* Added `card_product_id`, `description`, and `type` fields.
* Removed `last4` and `shared` fields.

For more information, please refer to the [Card Brand API](/reference/accounts/card-brands/overview).

### Card Products API

We've added a new `Card Products` directory accesible via our API allowing you to retrieve all `Card Brand` objects associated with a given `Card Product`.

<Note>Available when passing `Method-Version: 2025-07-04` in the request header.</Note>

<Accordion title="Example Request">
  ```bash cURL theme={null}
  curl https://production.methodfi.com/card_products/pdt_17 \
    -H "Method-Version: 2025-07-04" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```
</Accordion>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "pdt_17",
    "name": "Chase Freedom",
    "issuer": "Chase",
    "type": "specific",
    "brands": [
      {
          "id": "pdt_17_brd_1",
          "description": "Chase Freedom",
          "network": "visa",
          "network_tier": "signature",
          "default_image": "https://static.methodfi.com/card_brands/fb5fbd6a5d45b942752b9dc641b93d1f.png"
      },
      {
        "id": "pdt_17_brd_2",
        "description": "Chase Freedom",
        "network": "visa",
        "network_tier": "standard",
        "default_image": "https://static.methodfi.com/card_brands/6cb697528b0771f982f7c0e8b8869de3.png"
      }
    ]
  }
  ```
</Accordion>

For more information, please refer to the [Card Products API](/reference/card-products/overview).

## Improvements

### Connect API

We now support asynchronous Connect requests. You'll receive a `connect.available` webhook when an Async Connect is completed. Async Connect requests can be created by either:

* Setting the `Prefer: respond-async` header
* Specifying `products` and / or `subscriptions` in the request body

The Connect object will now include `requested_products` and `requested_subscriptions` fields in the response body.

<Accordion title="Example Request">
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/connect \
    -X POST \
    -H "Prefer: respond-async" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -d '{
      "requested_products": ["card_brand"],
      "requested_subscriptions": ["card_brand"]
    }'
  ```
</Accordion>

<Accordion title="Example Response after Connect is completed">
  ```json theme={null}
  {
    "id": "cxn_4ewMmBbjYDMR4",
    "entity_id": "ent_qKNBB68bfHGNA",
    "status": "completed",
    "accounts": [
      "acc_eKKmrXDpJBKgw",
      "acc_GV8WbmJW7KGRy",
      "acc_MLPKh9gQDDbT8",
      "acc_LbXE8wVYJLrKt",
      "acc_J3P9fayDFjpAy",
      "acc_eFFRV9zmpLREK"
    ],
    "requested_products": ["card_brand"],
    "requested_subscriptions": ["card_brand"],
    "error": null,
    "created_at": "2024-04-12T14:56:46.645Z",
    "updated_at": "2024-04-12T14:56:46.645Z"
  }
  ```
</Accordion>

For more information, please refer to the [Connect API](/reference/entities/connect/overview).

### Webhook API

We've added a new `refs` object to webhook payloads. This object contains the `entity` ID of the Entity that the webhook is related to.

<Accordion title="Example Webhook Payload">
  ```json theme={null}
  {
    "webhook_id": "whk_cSGjA6d9N8y8R",
    "id": "pmt_zR3nJG3c99P3X",
    "type": "payment.update",
    "op": "update",
    "path": "/payments/pmt_zR3nJG3c99P3X",
    "event": "evt_knqJgxKUnqDVJ",
    "refs": {
      "entity": "ent_qKNBB68bfHGNA"
    }
  }
  ```
</Accordion>

We have also added the following new webhooks:

* `card_brand.available`
* `connect.available`
* `method_jwk.create`
* `method_jwk.update`

For more information, please refer to the [Webhooks API](/reference/webhooks/overview).

### Entity and Account Products

The `product_id` field in the `Product` object and the Retrieve endpoint are now deprecated. We've added the `latest_successful_request_id` field to the `Product` object. This field will contain the ID of the most recently successful Product resource.

For more information, please refer to the [Entity Products API](/reference/entities/products/overview) and [Account Products API](/reference/accounts/products/overview).


# June Updates
Source: https://docs.methodfi.com/changelog/2025/june



## New Features

### Webhook HMAC Signature Verification

We’ve added support for HMAC-SHA256 signatures to further secure your webhook integrations. Here's what's new:

* **Signed Webhooks:** When you provide an `hmac_secret` during webhook registration, Method now includes a `method-webhook-signature` header on each webhook request. This signature is an HMAC-SHA256 digest, computed using your `hmac_secret` as the shared secret and the message format `${method-webhook-timestamp}:${raw_payload}`.

* **Timestamp Header:** Every webhook request now includes a `method-webhook-timestamp` header (UNIX timestamp in seconds), allowing you to validate the freshness of requests and prevent replay attacks.

* **Verification:** You can verify the webhook by recreating the HMAC digest locally and comparing it using a timing-safe equality check.

For more information, please refer to the [Webhook API](/reference/webhooks/overview).

## Improvements

### Connect API

* **Automatic Execution of Account Products and Subscriptions:** You can now optionally include `products` and `subscriptions` arrays in the request body when creating a `Connect` for an entity. These will automatically execute upon a successful connection.

* **Expand Query Parameter:** A new `expand` query parameter has been added to the `Connect` object, allowing you to include additional properties within the `accounts` object.

<Accordion title="Example Request">
  ```js theme={null}
  const connect = await method
      .entities('ent_TYHMaRJUUeJ7U')
      .connect
      .create(
          {
              products: ['attribute', 'card_brand'],
              subscriptions: ['card_brand', 'transaction'],
          }, 
          {
              expand: ['accounts.update']
          }
      );
  ```
</Accordion>

For more information, please refer to the [Connect API](https://docs.methodfi.com/reference/entities/connect/overview) and [Expanding Resources](/reference/expanding).

## SDK Updates

* Released [version 1.2.4](https://github.com/MethodFi/method-node/releases/tag/v1.2.4) of `method-node`
* Released [version 1.2.4](https://github.com/MethodFi/method-python/releases/tag/v1.2.4) of `method-python`


# March Updates
Source: https://docs.methodfi.com/changelog/2025/march



## New Features

### Transactions API

<img alt="transactions" />

We’re excited to launch our new [Transactions API](https://docs.methodfi.com/reference/accounts/transactions/overview) which gives real-time notifications directly from the card networks on credit/debit card purchases. Key benefits include:

* **Real-Time Alerts** -> Instantly notify users about new charges.
* **Intelligent Categorization** -> Automatically categorize spending using merchant category codes (MCCs).
* **Enhanced Security** -> Flag unusual transactions and identify spending in unfamiliar locations.
* **Multi-Currency Support** -> Monitor transactions in both USD and foreign currencies.
* **Refund Visibility** -> Gain complete insight into refund statuses.

For access to the Transactions API, please contact your Method CSM.

### Payment Instruments API

Our new [Payment Instruments API](https://docs.methodfi.com/reference/accounts/payment-instruments/overview) enables you to create and retrieve card credentials for checkout processes. This API provides seamless access to card details and network tokens, streamlining payment experiences across your app or platform.

For access to the Payment Instruments API, please contact your Method CSM.

### Simulate Credit Scores API

In `development` environments, you can now leverage the [Simulate Credit Scores API](https://docs.methodfi.com/reference/simulations/credit-scores/create) to simulate custom credit scores. This feature lets you:

* Simulate scores for test entities.
* Customize score values, sources, and models.
* Include contributing factor data for more realistic testing scenarios.

## Improvements

### Entity Attributes API

We've made significant improvements to the [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview).

* **Credit Health Hard Inquiries**: The `credit_health_hard_inquiries` attribute now includes two additional fields in its metadata history:
  * `institution_name`: Identifies the institution that performed the inquiry.
  * `inquiry_date`: Provides the date the inquiry occurred.
* **New Soft Inquiries Attribute**: A new `credit_health_soft_inquiries` attribute has been added. It mirrors the structure of hard inquiries to consistently track soft credit checks along with the associated institution name and inquiry date.

### Updates API

The [Updates API](https://docs.methodfi.com/reference/accounts/updates/overview) response now includes a new field:

* `data_as_of`: A timestamp indicating when the data in the record was last confirmed to be accurate, providing clear insight into the freshness and reliability of the information returned.

### Card Brands API

The [Card Brands API](https://docs.methodfi.com/reference/accounts/card-brands/overview) is now subscribable. This enhancement allows your system to automatically receive updated card brand information in real time. For example, if a user loses their card and receives a new one, the API will promptly reflect these changes, ensuring that your records are always accurate and up to date.

### Accounts API

We've expanded the [Accounts API](https://docs.methodfi.com/reference/accounts/overview) to support additional account types:

* `BNPL` (Buy Now, Pay Later)
* `Fintech`

### Account Verification Sessions API

The [Account Verification Sessions API](https://docs.methodfi.com/reference/accounts/verification-sessions/overview) now supports the `network` verification type. For more information, please see the [Network Verification Sessions API reference](https://docs.methodfi.com/reference/accounts/verification-sessions/update-network).

## SDK Updates

* Released [version 1.1.13](https://github.com/MethodFi/method-node/releases/tag/v1.1.13) of `method-node`
* Released [version 1.1.12](https://github.com/MethodFi/method-python/releases/tag/v1.1.12) of `method-python`


# May Updates
Source: https://docs.methodfi.com/changelog/2025/may



## Improvements

### Transactions API

A new `merchant` property has been added to the `Transaction` object. This field provides the merchant name and logo associated with each transaction.

<Warning>This property is not available by default. You can enable it by contacting your Method CSM.</Warning>

For more information, please refer to the [Transactions API](https://docs.methodfi.com/reference/accounts/transactions/overview).

### Card Brand API

The `CardBrand` object now includes a `source` property. Possible values are:

* `method` – sourced from Method’s internal systems

* `network` – retrieved directly from the card network

* `null` – source is unavailable

For more information, please refer to the [Card Brand API](https://docs.methodfi.com/reference/accounts/card-brands/overview).

## SDK Updates

* Released [version 1.2.2](https://github.com/MethodFi/method-node/releases/tag/v1.2.2) of `method-node`
* Released [version 1.2.2](https://github.com/MethodFi/method-python/releases/tag/v1.2.2) of `method-python`


# November Updates
Source: https://docs.methodfi.com/changelog/2025/november



## Improvements

### Simulate API

The [Simulate API](/reference/simulations/overview) now supports simulating Card Brand subscription behaviors.

**[Simulate Card Brand API](/reference/simulations/card-brands/create)**

* Card Brand simulations let developers designate a card brand for an account with an active Card Brand Subscription by specifying a `brand_id`. This triggers a `card_brand.available` webhook containing the ID of the designated card brand, allowing developers to test card brand-driven workflows in the development environment.

<Warning>This API is available in the development environment only.</Warning>

For more information, visit the [Simulations API](/reference/simulations/overview) and [Card Brand API](/reference/accounts/card-brands/overview) documentation.


# October Updates
Source: https://docs.methodfi.com/changelog/2025/october



## Improvements

### Accounts API

The [Accounts API](/reference/accounts/overview) now includes a new `sub_type` field under the `liability` object. This field provides additional context about a liability account by specifying its sub-type (for example, distinguishing between a `secured` and `unsecured` `personal_loan`).

For more information, please see <a href="/reference/accounts/overview#account-liability-sub-types">Account Liability Sub-Types.</a>

## SDK Updates

* Released [version 2.0.0](https://github.com/MethodFi/method-node/releases/tag/v2.0.0) of `method-node`
* Released [version 2.0.0](https://github.com/MethodFi/method-python/releases/tag/v2.0.0) of `method-python`

These major releases include default support for the **`2025-07-04` API version**, which introduces the new [Card Products API](/changelog/api-versions/2025-07-04) and updated [Card Brand schema](/changelog/api-versions/2025-07-04#card-brand-api).

See the [2025-07-04 API Version](/changelog/api-versions/2025-07-04) for more details.


# September Updates
Source: https://docs.methodfi.com/changelog/2025/september



## New Features

### Dashboard Updates

**Card Brands Directory**

<img alt="card brands directory" />

We released a new tab in the Method Dashboard – Card Brands – displaying Method's proprietary catalog of credit card brands and metadata. This dataset underpins the Card Brands API, which enables exact 1:1 product matching for each credit card in a user’s wallet, meaning you can identify the specific card brand a user is holding. For example, instead of just knowing a user holds a Chase Visa, you can determine if they hold a Chase Sapphire Reserve, Freedom Unlimited, or any co-branded product.

For access to the Card Brands Directory, please contact your Method CSM.

**New Role: Restricted Member**

You can now invite teammates as a Restricted Member. This role is the same as the Member role, except Restricted Members have no access to view end-users PII.

## Improvements

### Simulate API

The [Simulate API](/reference/simulations/overview) now supports simulating Connect and Attributes behaviors for an entity — making it easier for developers to test how Method responds to various data changes without needing to trigger them in production.

**[Simulate Connect API](https://docs.methodfi.com/reference/simulations/connect/create)**

* You can now configure Connect behaviors such as new\_credit\_card\_account. This is useful when testing account-creation flows or verifying how your system handles new data returned from a subsequent Connect. For example, after configuring this behavior, the next time you execute Connect for that entity, a new credit card account will appear in the response — helping you simulate real-world user events like a customer opening a new card.

**[Simulate Attributes API](https://docs.methodfi.com/reference/simulations/attributes/create)**

* Similarly, you can configure Attribute behaviors such as new\_soft\_inquiry to test how your system reacts to changing credit attributes. On the next Attributes request for that entity, the configured behavior will be applied (e.g., a new soft inquiry will be present).

<Warning>This API is available in the development environment only.</Warning>

These new simulation capabilities give you greater control when testing entity lifecycle scenarios and verifying downstream logic — without needing real production data or user actions.

For more information, visit the [Simulations API](/reference/simulations/overview) documentation.


# February Updates
Source: https://docs.methodfi.com/changelog/2026/february



## New Features

### Forwarding Requests: Entity Bindings

The [Forwarding Requests API](/reference/forwarding-requests/overview) now supports `entity` as a binding type. Previously, the `bindings` object only accepted `payment_instrument` and `secret` resource IDs. You can now bind an Entity and reference its data in your forwarding request templates using the `{{entity.field}}` syntax.

This enables use cases where an individual's first and last name need to be forwarded to third-party services alongside the associated account number, without exposing raw PII to your system.

```json Sample Request theme={null}
{
  "bindings": {
    "payment_instrument": "pmt_inst_7TNTTRQwQxWc",
    "secret": "sec_au22b1fbFrmfp",
    "entity": "ent_au22b1FBFJbp8"
  },
  "url": "https://sample-url/v1/tokens",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{secret.value}}"
  },
  "body": "{\"first_name\":\"{{entity.individual.first_name}}\",\"last_name\":\"{{entity.individual.last_name}}\",\"number\":\"{{payment_instrument.card.number}}\"}"
}
```

For more information, visit the [Forwarding Requests API](/reference/forwarding-requests/overview) documentation.

### Credit Score Simulations

The [Simulate API](/reference/simulations/overview) now supports direct event creation for Credit Score simulations.

* **New endpoint**: `POST /simulate/events` with `type` set to `credit_score.increased` or `credit_score.decreased`
* This endpoint allows developers to trigger credit score change events for an Entity with an active Credit Score subscription in the development environment, streamlining the testing of credit score-driven workflows

<Warning>This API is available in the development environment only.</Warning>

For more information, visit the [Simulations API](/reference/simulations/events/create) documentation.

## Improvements

### Updates API

**Student Loan — Opened At**

The [Updates API](/reference/accounts/updates/overview) now surfaces the `opened_at` field for `student_loan` liability accounts when `source` is `direct`. This field returns the date the student loan was originally opened, providing additional context for loan lifecycle analysis, refinance eligibility assessments, and portfolio segmentation.

For more information, visit the [Updates API](/reference/accounts/updates/overview) documentation.

### Webhooks

**New Accounts Surfaced Event**

The `entity.new_accounts_pending_consent` webhook fires when a previously undiscovered liability account surfaces after a user progresses through [Connect](/opal/connect/overview), but only for users who haven't opted into automatic consent for future accounts. For customers using Opal or the Element, this enables you to surface the new account to your end user for explicit consent, and optionally offer them the ability to auto-consent to future accounts going forward. This removes the need to poll the [Accounts API](/reference/accounts/overview) to discover new accounts.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Connect API

**Filter Accounts by Product**

You can now filter accounts by product type when using [Connect](/opal/connect/overview). This allows you to scope a Connect session to only surface accounts relevant to a specific product (e.g., only accounts eligible for payments or only accounts with update subscriptions), reducing noise and improving the end-user experience in targeted workflows.

For more information, visit the [Connect API](/opal/connect/overview) documentation.

### Payment Instruments API

**Card Billing Zip Code**

A new `billing_zip_code` field is now available on `card` type [Payment Instruments](/reference/accounts/payment-instruments/overview). This field is returned as part of the `card` object when retrieving a Payment Instrument.

* `card.billing_zip_code`: The billing zip code associated with the card

This addition supports address verification (AVS) workflows and reduces payment failures caused by billing address mismatches when forwarding card details to third-party processors.

For more information, visit the [Payment Instruments API](/reference/accounts/payment-instruments/overview) documentation.

### Payments API

**Inbound ACH/Wire Trace Numbers & Metadata**

Inbound ACH and wire payments received via `inbound_achwire_payment` [Payment Instruments](/reference/accounts/payment-instruments/overview) now include trace number and metadata fields on the [Payment](/reference/payments/overview) object.

* `source_trace_id`: enables end-to-end payment tracking and reconciliation for inbound transfers
* `destination_trace_id`: provides the underlying bank transaction ID on the destination Account for outbound reconciliation
* `metadata`: allows clients to associate custom reference information with incoming transactions (e.g., you can now add internal reference IDs, ​​customer IDs, and notes in the metadata)

For more information, see the [Payments API](/reference/payments/overview) documentation.

### Versioned API Reference Docs

The API Reference documentation now supports **version-aware navigation**. A version dropdown in the navigation bar lets you switch between API versions (`2025-12-01`, `2025-07-04`, `2024-04-04`) to view the documentation specific to your pinned API version.

Each version renders its own copy of the API Reference with version-specific request examples, response schemas, and available fields — so the docs you see always match the behavior of the API version you're using.

For more information, visit the [Versioning](/reference/versioning) documentation.


# January Updates
Source: https://docs.methodfi.com/changelog/2026/january



## New Features

### Forwarding Requests API

The [Forwarding Requests API](/reference/forwarding-requests/overview) allows you to securely proxy sensitive data (such as card details) to third-party services without your system ever handling the raw data. This enables use cases like payment processing, tokenization, and partner integrations while maintaining the PCI compliance of existing solutions.

**Key capabilities:**

* **Secure data transmission**: Send templated HTTP requests to whitelisted third-party endpoints.
* **Dynamic data injection**: Use template placeholders (e.g., `{{my_binding.card.number}}`) instead of raw values.
* **Binding resolution**: Bind placeholders to Method resources (currently [Payment Instruments](/reference/accounts/payment-instruments/overview)), allowing Method to securely append the underlying data without ever touching your company database.
* **Destination whitelisting**: Requests can only be sent to pre-approved URLs to prevent data exfiltration.
* **Transparent responses**: The third-party response is forwarded directly back to your application without requiring you to make changes to the way you ingest third-party response data.

For more information, visit the [Forwarding Requests API](/reference/forwarding-requests/overview) documentation.

### Secrets API

The [Secrets API](/reference/secrets/overview) allows you to securely store sensitive configuration values (such as API keys or credentials) for use within Method. Secrets are encrypted at rest and never exposed back to client applications.

**Key capabilities:**

* **Encrypted storage**: Store sensitive values and receive a Secret ID (`sec_...`) in return.
* **No client exposure**: Secret values are never returned in API responses.
* **Forwarding integration**: Secrets can be inserted into [Forwarding Requests](/reference/forwarding-requests/overview) for authenticating with third-party services.

For more information, visit the [Secrets API](/reference/secrets/overview) documentation.

### Opal Appearance Customization

You can now customize the visual appearance of [Opal](/opal/overview), Method's embeddable UI, to better match your application's branding or autofit to your users' devices.

When opening Opal with the client SDK, specify an `appearance` option with one of the following values:

* `light`: Standard light theme (default)
* `dark`: Dark theme for low-light environments
* `system`: Automatically matches the user's device settings

If no appearance is specified, Opal defaults to the `light` theme.

For more information, visit the [Opal Libraries](/opal/libraries) documentation.

## Improvements

### Payment Instruments API

This release introduces several improvements to the [Payment Instruments](/reference/accounts/payment-instruments/overview) product, focused on lifecycle management and subscription control.

**Lifecycle Management for Inbound ACH/Wire**

A new endpoint allows you to close inbound ACH/Wire payment instruments when they are no longer needed. This is useful for decommissioning payment routes after a refinance completes or when a funding relationship ends.

* **New endpoint**: `DELETE /accounts/:accountId/payment_instruments/:pmtInsId`
* **Behavior**: Supported only for `inbound_achwire_payment` instruments. Updates instrument status to `closed` and sets `chargeable` to `false`.

For more information, see the [Payment Instruments API](/reference/accounts/payment-instruments/overview) documentation.

**Granular Subscription Types**

The `payment_instrument` [subscription](/reference/accounts/subscriptions/overview) has been split into two more specific subscription types, giving you more flexibility in determining which webhook events you receive:

* `payment_instrument.card`: Triggered for card-level updates (e.g., PAN changed, expiration updated)
* `payment_instrument.network_token`: Triggered for network token updates (e.g., token provisioned, status changed)

<Note>For API version `2025-12-01`+, clients must use the new specific subscription names.</Note>

### Accounts API

**Collection Account Support**

The [Account Sensitive](/reference/accounts/sensitive/overview) product now supports the `collection` account type. This enables you to retrieve sensitive account details (such as account numbers) for accounts that have been sent to collections, expanding coverage for debt management and recovery workflows.

### Attributes API

**Support for Closed Accounts**

You can now retrieve [Account Attributes](/reference/accounts/attributes/overview) for closed liability accounts. Previously, querying Attributes for a closed account would return an error. With this update, derived financial insights (such as payment history summaries and balance trends) remain accessible even after an account has been closed—useful for historical reporting and analytics.


# March Updates
Source: https://docs.methodfi.com/changelog/2026/march



## New Features

### [API Guides](/guides/overview)

A new API Guides section is now available in Method's documentation. This comprehensive, concept-first companion to the API Docs helps product and business teams understand how Method's platform works and how best to configure Method's APIs for their use case. The API Guides include:

* **How Method Works**: How Method leverages multiple data sources to power identity verification, account discovery, and data retrieval.
* **Core Products**: In-depth guides for each product area, covering payload details, subscription behaviors, error handling, and edge cases.
* **Use Case Guides**: Implementation frameworks for the most common use cases: debt consolidation and balance transfers for lenders, card linking and checkout for commerce platforms, and liability dashboards and bill pay for personal finance apps, with step-by-step flows mapping Method products to each stage of the customer journey.

These guides are designed to complement the existing API Reference documentation by providing the conceptual foundation and product context that teams need to plan and build their integrations effectively.

### [OpenAPI Specification](https://github.com/MethodFi/openapi)

Method now publishes an official OpenAPI specification for the Method API. The spec enables you to:

* **Generate typed API clients** in any language using OpenAPI-compatible code generators
* **Import endpoints** directly into tools like Postman or Insomnia
* **Integrate with any toolchain** that supports the OpenAPI standard

For more information, visit the [Libraries](/libraries/overview) documentation.

## Improvements

### Webhook Idempotency Headers

You can now easily deduplicate retried or replayed webhook deliveries. All outbound webhooks now include a `method-webhook-delivery-id` header, containing a unique identifier for each webhook delivery. If your endpoint receives the same delivery twice (due to network timeouts, retries, or replays), the `method-webhook-delivery-id` value will be identical, letting you skip duplicate processing with a simple lookup.

```json Sample Headers theme={null}
{
  "method-webhook-delivery-id": "obwh_yBaCP3DQxJ4",
  "content-type": "application/json"
}
```

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Simulations API

**Connect Webhook in Account Opened Simulation**

The `POST /simulate/events` endpoint for `account.opened` events now also sends the `connect.create` webhook as part of the simulation, aligned with the endpoint's production behavior.

Previously, simulating an `account.opened` event only fired the `account.opened` webhook. This gap meant customers couldn't fully test their Connect-to-Account-Opened integration pipeline in dev.

Now, when you simulate `account.opened`, both webhooks fire in sequence:

1. `connect.create` — the Connect session that discovered the account
2. `account.opened` — the account itself becoming available

This enables true end-to-end testing of workflows that listen for Connect completion and then act on the resulting accounts.

```json POST /simulate/events theme={null}
{
  "type": "account.opened",
  "entity_id": "ent_au22b1FBFJbp8",
  "account_id": "acc_Dz3E8r4mJ7xKn"
}
```

For more information, visit the [Simulations API](/reference/simulations/events/create) documentation.


# Introducing API v2
Source: https://docs.methodfi.com/changelog/api-versions/2024-04-04



<img alt="title" />

We are excited to announce the launch of API v2 (release `2024-04-04`), the highly anticipated second version of Method's API.
Over the past year, our team has been dedicated to gathering feedback and working closely with our clients to create an even more powerful and developer-friendly API.

This release is packed with new features and enhancements that build upon Method's credential-less consumer permissioned financial network.

Expanded integrations with Visa/Mastercard power new features such as real-time credit card transaction notifications, and enabling 1-click checkout experiences for merchants.
This is in addition to our real-time financial institution liability updates, which have been significantly upgraded to provide better accuracy, expanded coverage, and reduced latency.

### Upgrading to 2024-04-04

The new API version is available to all existing teams.
New teams are automatically pinned to the API version `2024-04-04`.
During the transition phase, teams will be allowed to utilize any API version in tandem.

Note that once upgraded manually, it’s not possible to revert to older versions. Contact your Method CSM for more information on upgrade rollbacks.

* **Request Header**: Set `Method-Version` to `2024-04-04`. See [API Versioning](/reference/versioning#api-versioning) for more information.
* **Client Libraries**: For Method Libraries, the version is locked to the dated version of the API. For example, method-node v0.x.x is locked to 2020-12-06, while method-node v1.x.x is locked to 2024-04-04 and onwards.

#### Upgrade Support

Our technical integration team is here to help! Contact your Method CSM for a 1:1 on best practices and support migrating to `2024-04-04`

<Tip>Personalized upgrade guides have been created for enterprise customers. Contact your Method CSM to receive your guide.</Tip>

**✨ Ask Method:** The search bar of our docs now includes a conversational LLM search powered by ChatGPT. Feel free to ask any questions and receive a personalized answer.

*Sample questions:*

> How are auth\_sessions different in the new version of the API?

> What are the new products in 2024-04-04?

## Entities

New endpoints have been introduced for verification sessions, identities, connect operations, credit scores, products, and subscriptions. Several endpoints, including auth session, credit scores, and sensitive information retrieval, have been deprecated.

The connect endpoint now fetches all liability accounts across Method’s network of financial institutions, replacing auth\_session.
The verification sessions endpoint manages methods for verifying an entity's phone and identity, while the identities endpoint retrieves the underlying identity (PII) of an entity.
The products and subscriptions endpoints provide an overview of the products and continuous updates available for entities.

### New Features

#### The Connect endpoint

[Connect](/reference/entities/connect/overview) identifies and connects all the liability accounts (e.g., credit card, mortgage, auto loans, student loans, etc.)
for an entity across Method’s network of 1500+ financial institutions/lenders.

* **The Connect endpoint replaces:**
  * Auth Session: `POST /entities/{ent_id}/auth_session`

See [Connect](/reference/entities/connect/overview) for more information.

***

#### The Credit Scores endpoint

[Credit Scores](/reference/entities/credit-scores/overview) returns the latest credit score and score factors for an entity.

* **The Credit Scores endpoint replaces:**
  * Credit Score: `GET /entities/{ent_id}/credit_score`

See [Credit Scores](/reference/entities/credit-scores/overview) for more information.

***

#### The Verification Sessions Endpoint

[Entity Verification Sessions](/reference/entities/verification-sessions/overview) manage the methods for verifying an entity's phone and identity. Entities need to verify
their identity and/or phone to be used throughout the Method API. The status
of an entity's verification is returned via the `verification` field in the Entity object.

* **The Verification Sessions endpoint replaces:**
  * KBA questions via Auth Session: `POST /entities/{ent_id}/auth_session` is replaced by [kba](/reference/entities/verification-sessions/create-kba) entity verification session.
  * Non-KBA authentication via Auth Session: `POST /entities/{ent_id}/auth_session` is replaced by [byo\_kyc](/reference/entities/verification-sessions/create-byo-kyc) entity verification session.
  * `individual.phone_verification_type` and `individual.phone_verification_timestamp` via the create Entity request are replaced by [byo\_sms](/reference/entities/verification-sessions/create-byo-sms) phone verification requirements.
  * Utilizing `capabilities`, `available_capabilities`, and `pending_capabilities` in the Entity object to verify if an entity's identity has been matched or if more PII is required.
    * This flow is now replaced by `verification.identity.verified` and `verification.identity.matched` in the `verification` field in the Entity object.

* **Upgrade notes:**
  * The `verification` field in the Entity object returns the status of Identity Verification (`verification.identity`) and Phone Verification (`verification.phone`).
  * The `method` key in the `entity.verification` object enumerates the phone and identity verifications available for your entity.
    * Available verification methods differ on a team-by-team basis and are further defined by the PII provided during entity creation. See [PII Requirements](/reference/entities/overview#pii-requirements) for more information.
    * Teams with pre-defined PII requirements can utilize `byo_kyc` to skip KBA, and `byo_sms` to skip phone verification.
  * Teams upgrading from a prior API version might have some verifications auto-generated. Contact your Method CSM for more info.
  * The `status` key in an entity will only transition to `active` when all verification requirements have been completed.

See [Verification Sessions](/reference/entities/verification-sessions/overview) for more information.

***

#### The Identities endpoint

Entity [Identities](/reference/entities/identities/overview) endpoint is used to retrieve the underlying identity (PII) of an Entity.

* **The Identities endpoint replaces:**
  * Entity Sensitive: `GET /entities/{ent_id}/sensitive`

See [Identities](/reference/entities/identities/overview) for more information.

***

#### The Products endpoint

Entity [Products](/reference/entities/products/overview) endpoint outlines the products (*capabilities*) an entity has access to and provides an overview of the status of all the products.

Products are Method endpoints available for an entity. Access to most products requires an entity to be active.
However, some products have restricted access requiring team-by-team enablement. See [List all Products](/reference/entities/products/list) for more information.

**Entity Products:**

| Name           | Use-Case                                                             | Resource Doc                                                |
| -------------- | -------------------------------------------------------------------- | ----------------------------------------------------------- |
| `connect`      | On-Demand comprehensive view of an Entity’s outstanding liabilities. | [Connect](/reference/entities/connect/overview)             |
| `credit_score` | On-Demand view of an Entity’s credit score.                          | [Credit Scores](/reference/entities/credit-scores/overview) |
| `identity`     | On-Demand retrieval of the full Identity (PII) for any Entity        | [Identities](/reference/entities/identities/overview)       |

* **The Products endpoint replaces:**
  * Utilizing `capabilities`, `available_capabilities`, and `pending_capabilities` in the Entity object to determine the capabilities an entity has access to.
    These fields have been deprecated from the Entity object and removed in favor of:
    * `products` (products available for this entity)
    * `restricted_products` (products not currently available, but can be made available)

See [Products](/reference/entities/products/overview) for more information.

***

#### The Subscriptions endpoint

Entity [Subscriptions](/reference/entities/subscriptions/overview) endpoint controls the state of all subscriptions for an entity. Subscriptions are products that can provide continuous updates via webhooks (e.g., *Credit Score Subscription provides updates on an entity’s credit score*).

**Entity Subscriptions:**

| Name           | Use-Case                                                                                                            | Resource Doc                                                |
| -------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `connect`      | Comprehensive view of an Entity’s outstanding liabilities and continuous near real-time updates on new liabilities. | [Connect](/reference/entities/connect/overview)             |
| `credit_score` | Continuous near real-time updates on an Entity’s credit score.                                                      | [Credit Scores](/reference/entities/credit-scores/overview) |

* **The Subscriptions endpoint replaces:**
  * Custom configuration for continuous credit report pulls via your Method CSM. This has been deprecated and replaced by [Create a Subscription](/reference/entities/subscriptions/create) endpoint.

See [Subscriptions](/reference/entities/subscriptions/overview) for more information.

***

### Breaking Changes

#### Entity object changes

* ✨ Corporation entity types have been simplified to `corporation` during [Create a Corporation](/reference/entities/create-corporation) entity.
  * `c_corporation`, `s_corporation`, `llc`, `partnership`, and `sole_proprietorship` have been deprecated and removed in favor of `corporation`

* ✨ Providing SSN is now supported during [Create an Individual](/reference/entities/create-individual) entity.
  * `individual.ssn`, and `individual.ssn_4`

* ✨ Entity verification status is now returned by the Entity object. See [Entity object](/reference/entities/overview) for more information.
  * `verification`

* ✨ Products and subscription status are now returned by the Entity object. See [Entity object](/reference/entities/overview) for more information.
  * `products`
  * `restricted_products`
  * `subscriptions`
  * `available_subscriptions`
  * `restricted_subscriptions`

* ⛔ Phone verification has been replaced and no longer returned by the Entity object.
  * `individual.phone_verification_type`, and `individual.phone_verification_timestamp` have been deprecated and removed in favor of [Entity Verification Sessions](/reference/entities/verification-sessions/overview)

* ⛔ Entity capabilities have been deprecated and removed from the Entity object.
  * `capabilities`, `available_capabilities`, and `pending_capabilities` have been deprecated and removed in favor of [Products](/reference/entities/products/overview), [Subscriptions](/reference/entities/subscriptions/overview), and [Entity Verification Sessions](/reference/entities/verification-sessions/overview)
    * The `verification` field in the Entity object returns the status of Identity Verification (`verification.identity`) and Phone Verification (`verification.phone`).
    * The `products` array returns the products the entity has access to, replacing `capabilities`.
    * The `restricted_products` array returns the products the entity does not have access to, replacing `pending_capabilities`.
    * The [Entity Products](#) endpoint outlines the products (*capabilities*) an entity has access to and provides an overview of the status of all the products.

* The following fields have been modified in the [Entity object](/reference/entities/overview):

  <AccordionGroup>
    <Accordion title="Fields removed from Entity" icon="circle-minus">
      * `individual.phone_verification_type`
      * `individual.phone_verification_timestamp`
      * `capabilities`
      * `available_capabilities`
      * `pending_capabilities`
    </Accordion>

    <Accordion title="Fields added to Entity" icon="circle-plus">
      * `individual.ssn`
      * `individual.ssn_4`
      * `verification`
      * `products`
      * `restricted_products`
      * `subscriptions`
      * `available_subscriptions`
      * `restricted_subscriptions`
    </Accordion>
  </AccordionGroup>

#### Deprecated endpoints

The following endpoints have been deprecated and removed in `2024-04-04`

* Auth Session: `/entities/{ent_id}/auth_session` removed in favor of [Connect](/reference/entities/connect/overview)
* Credit Score: `/entities/{ent_id}/credit_score` removed in favor of [Credit Scores](/reference/entities/credit-scores/overview)
* Entity Sensitive: `/entities/{ent_id}/sensitive` removed in favor of [Identities](/reference/entities/identities/overview)
* Refresh Capabilities: `/entities/{ent_id}/refresh_capabilities` is no longer supported in `2024-04-04`
* Manual Auth Session: `/entities/{ent_id}/manual_auth_session` is no longer supported in `2024-04-04`
* Entity Vehicles: `/entities/{ent_id}/vehicles` is no longer supported in `2024-04-04`

## Accounts

New endpoints have been introduced for updates, card brands, payoffs, transactions, balances, verification sessions, and sensitive information. Several endpoints, including account syncs, account verification, and sensitive information retrieval, have been deprecated.

The updates endpoint now provides real-time account data directly from financial institutions, replacing syncs, and making liability account data available through the updates endpoint.

The verification process for ACH and liability accounts has been streamlined with Account Verification Sessions.

### New Features

#### The Updates endpoint

[Updates](/reference/accounts/updates/overview) endpoint retrieves in real-time account data including balance, due dates, APRs, directly from the account’s financial institution.
Updates is Method's flagship endpoint and replaces the `sync` endpoint by enabling push notifications directly from the financial institution.

As part of the `2024-04-04` release the Account object has been modified, and most Account data is now returned by an Update object. See [Account object changes](/changelog/api-versions/2024-04-04#account-object-changes) for more information.

* **The Updates endpoint replaces:**
  * Syncing an account using `/accounts/{acc_id}/syncs` has been deprecated and removed in favor of [Create an Update](/reference/accounts/updates/create)
  * Enrolling in auto syncs using `/accounts/{acc_id}/sync_enrollment` or via your Method CSM has been deprecated and removed in favor of [Updates](/reference/accounts/updates/overview) and [Subscriptions](/reference/accounts/subscriptions/overview)
  * Sync status fields in the Account response have been deprecated and removed in favor of [Updates](/reference/accounts/updates/overview). Removed fields include:
    * `data_status`
    * `data_sync_type`
    * `data_last_successful_sync`
    * `data_status_error`
    * `data_source`
    * `data_updated_at`
  * Enrollment into credit report-based updates via your Method CSM has been deprecated and removed in favor of the `update.snapshot` subscription type. See [Subscriptions](/reference/accounts/subscriptions/overview) for more information.
  * Liability data at the account level (`account.liability.<liability_type>`) has been deprecated and removed in favor of an Update object and an expansion. See [Account](/reference/accounts/overview) for more information.
  * Utilizing `data_status` to determine real-time financial institution coverage has been deprecated and removed in favor of the `products` array including `updates`. See [Updates](/reference/accounts/updates/overview) for more information.

* **Upgrade notes:**
  * New updates sources: `direct` and monthly `snapshot` updates.
    * `direct`: Near real-time account update (balance, due dates, etc.) from the account’s financial institution (replaces a `sync`).
    * `snapshot`: Monthly snapshot update (balance, due dates, etc.) from the account’s financial institution (replaces credit report-based updates).
  * Receiving continuous updates requires a subscription to `update` or `update.snapshot`. See [Subscriptions](/reference/accounts/subscriptions/overview) for more information.
  * Liability data at the account level (`account.liability.<liability_type>`) has been deprecated and removed in favor of an Update object and an expansion. See [Account](/reference/accounts/overview) for more information.
  * Any account connected using Entity Connect will receive an initial `snapshot` update and a `direct` update (when available).
  * Legacy accounts connected via `auth_session` have been migrated with an Update object pre-populated.

See [Updates](/reference/accounts/updates/overview) for more information.

***

#### The Card Brand endpoint

[Card Brand](/reference/accounts/card-brands/overview) endpoint retrieves the associated credit card metadata (Product / Brand Name, Art, etc.) directly from the card issuer.
In the future, card brand webhooks will notify in real-time any card changes (e.g., card downgraded, card lost, etc.)

* **The Card Brand endpoint replaces:**
  * Derived card names in the liability account field `name`. Migrating to card brand will provide accurate names across any Visa / Mastercard card regardless of issuing bank.

See [Card Brand](/reference/accounts/card-brands/overview) for more information.

***

#### The Payoffs endpoint

[Payoffs](/reference/accounts/payoffs/overview) endpoint retrieves a payoff quote in real-time from the Account’s financial institution / lender. Payoffs are currently only available for Auto Loan and Mortgage accounts.

* **The Payoffs endpoint replaces:**
  * `payoff_amount` and `payoff_amount_term` fields within the `auto_loan` Account type response. See [Updates](/reference/accounts/updates/overview) for more information on the Account object changes.

See [Payoffs](/reference/accounts/payoffs/overview) for more information.

***

#### The Transactions endpoint

[Transactions](/reference/accounts/transactions/overview) endpoint retrieves real-time transaction (authorization, clearing, etc) notifications for Credit Card Accounts directly from the card networks (Visa, MC).

Enrollment for transactions requires a subscription and additional consent using Method's `connect` element.

* **The Transactions endpoint replaces:**
  * Enrollment for transactions using the `auth` element has been deprecated and removed in favor of the `connect` element. See [Connect Overview](/elements/connect/overview) for more information.
  * Global transactions endpoint `/transactions` has been deprecated and removed in favor of account-scoped transactions. See [Transactions](/reference/accounts/transactions/overview) for more information.
  * `transaction:stream` capability has been deprecated and removed in favor of the `transactions` product. See [Products](/reference/accounts/products/overview) for more information.

See [Transactions](/reference/accounts/transactions/overview) for more information.

***

#### The Balances endpoint

[Balances](/reference/accounts/balances/overview) endpoint retrieves the real-time balance from the account’s financial institution.
Balance is now available for non-liability accounts such as checking accounts. Contact your Method CSM for early access to expanded Balance coverage.

* **The Balances endpoint replaces:**
  * The `balance` field in `liability.<liability_type>.balance` has been deprecated and removed in favor of:
    * Retrieving `balance` using the [Balances](/reference/accounts/balances/overview) endpoint
    * Retrieving  `balance` and additional liability information using the [Updates](/reference/accounts/updates/overview) endpoint

See [Balances](/reference/accounts/balances/overview) for more information.

***

#### The Verification Sessions endpoint

[Account Verification Sessions](/reference/accounts/verification-sessions/overview) manage the methods for verifying an Account to enable specific products for ACH or Liability accounts. For example,
ACH Accounts require a verified Account Verification Session before they can be used as a source for Payments.

* **The Account Verification Sessions endpoint replaces:**
  * ACH Account verification via `/accounts/{acc_id}/verification` has been deprecated and removed in favor of:
    * An Account Verification Session of one of the available methods: `micro_deposits`, `plaid`, `mx`, or `teller`.
    * Teams with corporate disbursement ACH accounts can skip verification and a verification will be auto-provisioned with the type of `auto_verify`.
    * Teams with managed DDAs can whitelist a routing number to skip verification across all their DDAs (routing / account number pair).
    * See [Verification Types](/reference/accounts/verification-sessions/overview#verification-types) for more information.
      A verification of `trusted_provisioner` will be auto-provisioned. Contact your Method CSM for more information.
  * Liability account number verification for AMEX, Apple Card, etc. is now handled by a `standard` Account Verification Session. See [Update a Standard Verification](/reference/accounts/verification-sessions/update-standard) for more information.
  * Instant Link CVV verification is now handled by a `pre_auth` Account Verification Session. See [Update a Pre-auth Verification](/reference/accounts/verification-sessions/update-preauth) for more information.

* **Upgrade notes:**
  * Teams upgrading from a prior API version might have some verifications auto-generated. Contact your Method CSM for more info.

See [Account Verification Sessions](/reference/accounts/verification-sessions/overview) for more information.

***

#### The Sensitive endpoint

[Sensitive](/reference/accounts/sensitive/overview) endpoint returns underlying sensitive account information (e.g., PAN, CVV, account number).
This product is only available for liabilities and requires verification on a team-by-team basis.

* **The Sensitive endpoint replaces:**
  * `GET /accounts/{acc_id}/sensitive` is deprecated and removed in favor of [Create a Sensitive](/reference/accounts/sensitive/create).

See [Sensitive](/reference/accounts/sensitive/overview) for more information.

***

#### The Products endpoint

Account [Products](/reference/accounts/products/overview) endpoint outlines the products (*capabilities*) an account has access to and provides an overview of the status of all the products.

Products are Method endpoints available for an account. Most products are accessible by default.
However, some products have restricted access requiring team-by-team enablement and elevated account verification.

**Account Products:**

| Name         | Use-Case                                                                                                    | Supported Types | Resource Doc                                           |
| ------------ | ----------------------------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------ |
| `update`     | On-Demand real-time account update (balance, due dates, etc.) from the account's financial institution      | All liabilities | [Updates](/reference/accounts/updates/overview)        |
| `balance`    | On-Demand real-time balance from the account's financial institution                                        | All liabilities | [Balances](/reference/accounts/balances/overview)      |
| `card_brand` | On-Demand retrieval of credit card metadata (Product / Brand Name, Art, etc.) directly from the card issuer | Credit Cards    | [Card Brand](/reference/accounts/card-brands/overview) |
| `payoff`     | On-Demand retrieval of auto loan payoff (amount, per diem, etc.) from the account's financial institution   | Auto Loans      | [Payoffs](/reference/accounts/payoffs/overview)        |
| `payment`    | Next day electronic push payments to the account's financial institution                                    | All liabilities | [Payments](/reference/payments/overview)               |
| `sensitive`  | On-Demand retrieval of underlying sensitive account information (PAN, CVV, account number)                  | All liabilities | [Sensitive](/reference/accounts/sensitive/overview)    |

* **The Products endpoint replaces:**
  * Utilizing `capabilities`, `available_capabilities`, and `pending_capabilities` in the Account object to determine the capabilities an account has access to.
    These fields have been deprecated from the Account object and removed in favor of:
  * `products` (products available for this Entity)
  * `restricted_products` (products not currently available, but can be made available)

See [Products](/reference/accounts/products/overview) for more information.

***

#### The Subscriptions endpoint

Account [Subscriptions](/reference/accounts/subscriptions/overview) endpoint controls the state of all subscriptions for an account. Subscriptions are products that can provide continuous updates via Webhooks.
(*e.g., Transaction Subscription provides real-time updates on a Credit Card’s transactions*).

**Account Subscriptions:**

| Name              | Use-Case                                                                                          | Supported Types | Resource Doc                                              |
| ----------------- | ------------------------------------------------------------------------------------------------- | --------------- | --------------------------------------------------------- |
| `transactions`    | Real-time transaction (authorization, purchases, etc.) notifications for credit card accounts     | Credit Cards    | [Transactions](/reference/accounts/transactions/overview) |
| `update`          | Near real-time account update (balance, due dates, etc.) from the account's financial institution | All liabilities | [Updates](/reference/accounts/updates/overview)           |
| `update.snapshot` | Monthly account snapshot update (balance, due dates, etc.) from the credit bureau                 | All liabilities | [Updates](/reference/accounts/updates/overview)           |

* **The Subscriptions endpoint replaces:**
  * Custom configuration for continuous syncs via your Method CSM. This has been deprecated and replaced by [Create a Subscription](/reference/accounts/subscriptions/create) endpoint.
  * Account Sync Enrollment `/accounts/{acc_id}/sync_enrollment` for enrollment in auto syncs. This has been deprecated and replaced with an Updates subscription. See [Updates](/reference/accounts/updates/overview) and [Create a Subscription](/reference/accounts/subscriptions/create) for more information.
  * `data_sync_type` has been removed from the Account endpoint. See [Updates](/reference/accounts/updates/overview) and [List all Subscriptions](/reference/accounts/subscriptions/list) for more information.

See Account [Subscriptions](/reference/accounts/subscriptions/overview) for more information.

***

### Breaking Changes

#### Account object changes

* ✨ Product properties are now included in the Account object. By default, the ID of the latest product resource is returned and can be
  expanded in-line using the `expand` query param. See [Expanding Resources](/reference/expanding) for more information.
  * `latest_verification_session`
  * `update`
  * `balance`
  * `card_brand`
  * `payoff`

* ✨ Products and Subscription status are now returned by the Account object. See [Account object](/reference/accounts/overview) for more information.
  * `products`
  * `restricted_products`
  * `subscriptions`
  * `available_subscriptions`
  * `restricted_subscriptions`

* ✨ Liability name and fingerprint are now returned by the Account object. See [Account object](/reference/accounts/overview) for more information.
  * `liability.name`
  * `liability.fingerprint`

* ✨ New account liability types are now supported and returned by the Account object. See [Account Liability Types](/reference/accounts/overview#account-liability-types) for more information.

* ⛔ Liability data under the `account.liability.<liability_type>` property has been deprecated and removed in favor of [Updates](/reference/accounts/updates/overview)
  * The `updates` field returns the ID of the latest update and can be expanded to return liability account data in-line using the `expand` query param. See [Expanding Resources](/reference/expanding) for more information.

* ⛔ Syncing liability data using `/accounts/{acc_id}/syncs` has been deprecated and removed in favor of [Updates](/reference/accounts/updates/overview)
  * Additionally, data sync status fields at the account liability object have been deprecated and removed in favor of status fields within an [Update](/reference/accounts/updates/overview)
  * `liability.data_status`, `liability.data_sync_type`, `liability.data_sync_type`, `liability.data_last_successful_sync`, `liability.data_source`,
    `liability.data_updated_at`, `liability.data_updated_at`, `liability.data_status_error`

* ⛔ Account capabilities have been deprecated and removed from the Account object.
  * `capabilities`, `available_capabilities`, and `pending_capabilities` have been deprecated and removed in favor of [Products](/reference/accounts/products/overview), [Subscriptions](/reference/accounts/subscriptions/overview), and [Account Verification Sessions](/reference/accounts/verification-sessions/overview)
    * The `products` array returns the products the account has access to, replacing `capabilities`.
    * The `restricted_products` array returns the products the account does not have access to, replacing `pending_capabilities`.
    * The account [Products](/reference/accounts/products/overview) endpoint outlines the products (*capabilities*) an account has access to and provides an overview of the status of all the products.

* ⛔ Account payment status (`liability.payment_status`) has been deprecated and removed in favor of [Products](/reference/accounts/products/overview)

* ⛔ Account clearing (`clearing`) and liability hash (`liability.hash`) has been deprecated and removed in `2024-04-04`

* The following fields have been modified in the [Account object](/reference/accounts/overview):

  <AccordionGroup>
    <Accordion title="Fields removed from Account" icon="circle-minus">
      * `liability.payment_status`
      * `liability.data_status`
      * `liability.data_sync_type`
      * `liability.data_last_successful_sync`
      * `liability.data_source`
      * `liability.data_updated_at`
      * `liability.data_status_error`
      * `liability._liability_type_` - where `liability_type` is any of the [Account Liability Types](/reference/accounts/overview#account-liability-types).
      * `liability.hash`
      * `clearing`
      * `capabilities`
      * `available_capabilities`
      * `pending_capabilities`
    </Accordion>

    <Accordion title="Fields added to Account" icon="circle-plus">
      * `liability.name`
      * `liability.fingerprint`
      * `latest_verification_session`
      * `update`
      * `balance`
      * `card_brand`
      * `payoff`
      * `products`
      * `restricted_products`
      * `subscriptions`
      * `available_subscriptions`
      * `restricted_subscriptions`
    </Accordion>
  </AccordionGroup>

#### Deprecated endpoints

* Account Syncs: `/accounts/{acc_id}/syncs` removed in favor of [Updates](/reference/accounts/updates/overview)
* Account Sync Enrollment: `/accounts/{acc_id}/sync_enrollment` removed in favor of [Updates](/reference/accounts/updates/overview) and [Subscriptions](/reference/accounts/subscriptions/overview)
* Account Verification: `/accounts/{acc_id}/verification` removed in favor of [Account Verification Sessions](/reference/accounts/verification-sessions/overview)
* Account Sensitive: `/accounts/{acc_id}/sensitive` removed in favor of [Sensitive](/reference/accounts/sensitive/overview)
* Account Card: `/accounts/{acc_id}/card` removed in favor of [Card Brand](/reference/accounts/card-brands/overview), [Sensitive](/reference/accounts/sensitive/overview) and Credit Card [Account Verification Sessions](/reference/accounts/verification-sessions/overview)
* Account Payment History: `/accounts/{acc_id}/payment_history` is no longer supported in `2024-04-04`
* Account Details: `/accounts/{acc_id}/details` is no longer supported in `2024-04-04`
* Bulk Sensitive: `/accounts/{acc_id}/bulk_sensitive` is no longer supported in `2024-04-04`
* Bulk Sync: `/accounts/{acc_id}/bulk_sync` is no longer supported in `2024-04-04`
* Account Vehicle: `/accounts/{acc_id}/match_vehicle` is no longer supported in `2024-04-04`
* Routing Numbers: `/routing_numbers` is no longer supported in `2024-04-04`
* BINs: `/bins` is no longer supported in `2024-04-04`

## Additional Changes

### Expand Parameter

New `expand` query parameter for expanding certain properties from an ID to their respective objects in-line in the response body.

Applicable to both Entities and Accounts, allowing expansion of fields such as `connect`, `credit_score`, `update`, `balance`, `payoff`, `sensitive`, `transactions`, `card_brand`, and `latest_verification_session`.

See [Expanding Resources](/reference/expanding) for more information.

### Elements

Introducing the [Connect element](/elements/connect/overview) as the primary way to connect user accounts and complete necessary verifications.

The Auth element has been deprecated in favor of Connect.

See [Connect guide](/elements/connect/overview) for step-by-step instructions on leveraging Connect.


# Introducing API Version 2025-07-04
Source: https://docs.methodfi.com/changelog/api-versions/2025-07-04



We're excited to announce the release of **API version `2025-07-04`**, featuring key improvements to our **Card Brand** model and the introduction of the new **Card Products API**.
This version enhances data consistency across card networks, issuers, and products — enabling more structured integrations and cleaner brand experiences for your users.

***

## What’s New

### Card Brand API

<img alt="Card Brands" />

The [Card Brand API](/reference/accounts/card-brands/overview) has been expanded with a **richer, more structured object**.
This change makes it easier to **identify, display, and integrate** specific card products while ensuring consistent metadata across networks and issuers.

**Key improvements:**

* Brand data is now **fully nested**, encapsulating `network`, `issuer`, and visual assets under each brand.
* New fields such as `card_product_id`, `description`, and `type` provide more granular control when mapping and displaying cards.
* Removed legacy fields (`last4`, `shared`) for a cleaner, product-centric response format.

<Note>Available when passing `Method-Version: 2025-07-04` in the request header.</Note>

<Accordion title="Previous Response">
  ```json theme={null}
  {
    "id": "cbrd_eVMDNUPfrFk3e",
    "account_id": "acc_yVf3mkzbhz9tj",
    "network": "visa",
    "issuer": "Chase",
    "last4": "8623",
    "brands": [
      {
        "id": "brand_AMxtjQzAfDCRP",
        "name": "Chase Sapphire Reserve",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
      }
    ],
    "status": "completed",
    "shared": false,
    "source": "network",
    "error": null,
    "created_at": "2024-03-19T01:05:37.247Z",
    "updated_at": "2024-03-19T01:05:37.247Z"
  }
  ```
</Accordion>

<Accordion title="New Response">
  ```json theme={null}
  {
    "id": "cbrd_Accm7P6t6mYQP",
    "account_id": "acc_LxwEqNicr66yP",
    "brands": [
      {
        "id": "pdt_15_brd_1",
        "card_product_id": "pdt_15",
        "description": "Chase Sapphire Reserve",
        "name": "Chase Sapphire Reserve",
        "issuer": "Chase",
        "network": "visa",
        "network_tier": "infinite",
        "type": "specific",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
      }
    ],
    "status": "completed",
    "source": "method",
    "error": null,
    "created_at": "2025-08-12T00:56:50.139Z",
    "updated_at": "2025-08-12T00:56:50.139Z"
  }
  ```
</Accordion>

***

### Card Products API

We’re introducing the new [Card Products API](/reference/card-products/overview) — a **directory of card products** that allows you to retrieve all associated `Card Brand` objects for a given product.

This endpoint gives developers a unified way to reference and display card metadata (art, network, tier, and issuer) across all variants of a card family.

<Note>Available when passing `Method-Version: 2025-07-04` in the request header.</Note>

<Accordion title="Example Request">
  ```bash theme={null}
  curl https://production.methodfi.com/card_products/pdt_17 \
    -H "Method-Version: 2025-07-04" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```
</Accordion>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "pdt_17",
    "name": "Chase Freedom",
    "issuer": "Chase",
    "type": "specific",
    "brands": [
      {
        "id": "pdt_17_brd_1",
        "description": "Chase Freedom",
        "network": "visa",
        "network_tier": "signature",
        "default_image": "https://static.methodfi.com/card_brands/fb5fbd6a5d45b942752b9dc641b93d1f.png"
      },
      {
        "id": "pdt_17_brd_2",
        "description": "Chase Freedom",
        "network": "visa",
        "network_tier": "standard",
        "default_image": "https://static.methodfi.com/card_brands/6cb697528b0771f982f7c0e8b8869de3.png"
      }
    ]
  }
  ```
</Accordion>

***

## Breaking Changes

* **Card Brand response shape updated**

  * `network` and `issuer` are now nested under each `brand`.
  * New fields: `card_product_id`, `description`, `type`.
  * Removed fields: `last4`, `shared`.

***

## Why It Matters

This release unifies how card data is modeled and consumed across the Method platform.
By standardizing the `Card Brand` object and introducing a canonical `Card Products` directory, developers can now:

* Reliably map and display card details across networks and issuers
* Build consistent card selection and branding experiences in their apps
* Reduce dependency on ad-hoc naming or inferred card data

***

## Upgrading to 2025-07-04

The new API version is available to all existing teams. New teams are automatically pinned to **`2025-07-04`**.

* **Request Header:** Set `Method-Version` to `2025-07-04`. See [API Versioning](/reference/versioning#api-versioning) for more information.
* **Client Libraries:** `method-node` and `method-python` **v2.0.0+** default to this version.

> Once upgraded, rollbacks to prior API versions are not supported. Contact your Method CSM for upgrade assistance.

***

### Upgrade Support

Our technical integration team is available to guide you through the migration. Contact your Method CSM to schedule a review of your current card integration or to receive a personalized upgrade checklist.


# Introducing API Version 2025-12-01
Source: https://docs.methodfi.com/changelog/api-versions/2025-12-01



We're excited to announce the release of **API version `2025-12-01`**, featuring the new **Payment Instruments API** for inbound funding workflows.
This version enables liability accounts to receive direct payments via ACH or wire transfer — allowing third parties to send funds directly to liability accounts without requiring explicit Payment creation.

***

## What's New

### Payment Instruments API

Method now supports **inbound funding workflows** with the introduction of a new `PaymentInstrument` type: `inbound_achwire_payment`.
This feature allows liability accounts (e.g., loans, credit cards) to receive direct payments via ACH or wire transfer.

**Key features:**

* Provisions a unique virtual account number and routing number linked to a specific Method Account, effectively making the underlying liability routable
* Third parties can send funds directly to these credentials, and Method automatically applies the funds to the associated account, without requiring you to explicitly create a Payment
* Supports use cases such as payroll, refinancing, and other direct payment scenarios

**How it works:**

1. **Create Instrument**: Create a Payment Instrument of type `inbound_achwire_payment` for a specific Method Account
2. **Receive Banking Details**: Method returns unique `account_number` and `routing_number`
3. **Share with a Third Party**: Provide these banking details to a third party (e.g., payroll provider, refinance lender, or another bank)
4. **Inbound Transfer**: When funds are sent to these credentials, Method receives the inbound ACH or wire transfer
5. **Automatic Application**: Method automatically applies the received funds to the associated account

<Note>Available when passing `Method-Version: 2025-12-01` in the request header.</Note>

<Accordion title="Example Request">
  ```bash theme={null}
  curl https://production.methodfi.com/accounts/acc_4m9amk4KFiaQX/payment_instruments \
    -X POST \
    -H "Method-Version: 2025-12-01" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "inbound_achwire_payment"
    }'
  ```
</Accordion>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "pmt_inst_cLbaArHhfDBDf",
    "account_id": "acc_GAzrD99cUqGEN",
    "type": "inbound_achwire_payment",
    "card": null,
    "network_token": null,
    "inbound_achwire_payment": {
      "account_number": "2517228863",
      "routing_number": "026015244"
    },
    "chargeable": true,
    "status": "completed",
    "error": null,
    "created_at": "2025-12-11T00:12:58.639Z",
    "updated_at": "2025-12-11T00:12:58.639Z"
  }
  ```
</Accordion>

See [Payment Instruments](/reference/accounts/payment-instruments/overview) for more information.

***

### Simulate API

The [Simulate API](/reference/simulations/overview) now supports simulating inbound ACH / wire payments for `inbound_achwire_payment` Payment Instruments — making it easier for developers to test inbound payment flows in the development environment.

**[Simulate Inbound ACH/Wire Payments](/reference/simulations/payment_instruments/create)**\
This endpoint allows developers to simulate receiving an inbound payment and triggers the same automatic payment application logic used in production.

<Note>Available when passing `Method-Version: 2025-12-01` in the request header.</Note>

<Warning>This API is available in the development environment only.</Warning>

For more information, visit the [Simulations API](/reference/simulations/overview) documentation.

***

## Breaking Changes

* **Payment Instrument product names changed**

  * The `payment_instrument` product name has been split into three separate product names:
    * `payment_instrument.card`
    * `payment_instrument.network_token`
    * `payment_instrument.inbound_achwire_payment`
  * In previous versions (`2024-04-04`, `2025-07-04`), the Account object's `products`, `restricted_products`, `subscriptions`, `available_subscriptions`, and `restricted_subscriptions` arrays contained the single product name `payment_instrument`.
  * In `2025-12-01`, these arrays now contain the three separate product names instead of the single `payment_instrument` name.

***

## Why It Matters

This release enables new inbound funding workflows that simplify payment collection for liability accounts.
By introducing `inbound_achwire_payment` Payment Instruments, developers can now:

* Enable third parties to send payments directly to liability accounts without explicit Payment creation
* Streamline payroll, refinancing, and other direct payment scenarios
* Automatically apply inbound transfers to the associated account
* Test inbound payment flows more easily with enhanced Simulate API support

***

## Upgrading to 2025-12-01

The new API version is available to all existing teams. New teams are automatically pinned to **`2025-12-01`**.

* **Request Header:** Set `Method-Version` to `2025-12-01`. See [API Versioning](/reference/versioning#api-versioning) for more information
* **Client Libraries:** `method-node` and `method-python` **v2.1.0+** default to this version

> Once upgraded, rollbacks to prior API versions are not supported. Contact your Method CSM for upgrade assistance.

***

### Upgrade Support

Our technical integration team is available to guide you through the migration. Contact your Method CSM to schedule a review of your current payment integration or to receive a personalized upgrade checklist.


# Introducing API Version 2026-03-30
Source: https://docs.methodfi.com/changelog/api-versions/2026-03-30



We're excited to announce the release of **API version `2026-03-30`**, featuring redesigned **Attributes** for both **Entities** and **Accounts**.
This release expands the attributes product with richer computed outputs, a unified per-attribute result shape, and support for asynchronous attribute computation workflows.

***

## What's New

### Entity Attributes

The [Entity Attributes API](/reference/entities/attributes/overview) now returns a broader set of aggregated financial attributes computed across an Entity's connected accounts.
These attributes are organized across categories such as revolving credit cards, personal loans, mortgages, installment balances, and overall utilization.

**Key improvements:**

* Introduces a richer set of financial attributes, including balances, utilization trends, deltas, delinquency signals, and payment behavior metrics
* Returns attributes in a simplified `{ value, error }` shape — `error` uses the standard `{ type, sub_type, code, message }` format when the attribute could not be computed
* Computes all supported entity attributes automatically as part of the request lifecycle
* Supports asynchronous processing so teams can poll or rely on webhook-driven workflows for completion

<Note>Available when passing `Method-Version: 2026-03-30` in the request header.</Note>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "attr_dADraNgLBrhgL",
    "entity_id": "ent_EQ3FCTzDUmmCb",
    "status": "completed",
    "attributes": {
      "revolving_credit_card_balance_total": {
        "value": 968400,
        "error": null
      },
      "credit_limit_total": {
        "value": 8100000,
        "error": null
      },
      "credit_card_utilization": {
        "value": 11.96,
        "error": null
      },
      "overall_utilization": {
        "value": 70.5,
        "error": null
      }
    },
    "error": null,
    "created_at": "2026-04-09T17:02:47.910Z",
    "updated_at": "2026-04-09T17:04:35.220Z"
  }
  ```
</Accordion>

***

### Account Attributes

The [Account Attributes API](/reference/accounts/attributes/overview) has been expanded into a dedicated account-level attributes product.
Returned attributes now vary by liability type, including support for credit cards, personal loans, and mortgages.

**Key improvements:**

* Adds account-level financial attributes such as utilization trends, delinquency flags, and installment estimates
* Returns attributes in a simplified `{ value, error }` shape with standardized error objects
* Supports asynchronous attribute computation workflows for account requests
* Adds webhook support for account attribute lifecycle events

<Note>Available when passing `Method-Version: 2026-03-30` in the request header.</Note>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "acc_attr_cWBKqwVP87kim",
    "account_id": "acc_4m9amk4KFiaQX",
    "status": "completed",
    "attributes": {
      "type": {
        "value": "credit_card",
        "error": null
      },
      "usage_pattern": {
        "value": "revolver",
        "error": null
      },
      "delinquency_flag": {
        "value": false,
        "error": null
      },
      "utilization": {
        "value": 11.96,
        "error": null
      }
    },
    "error": null,
    "created_at": "2026-04-09T17:02:47.910Z",
    "updated_at": "2026-04-09T17:04:35.220Z"
  }
  ```
</Accordion>

***

### Account Attribute Subscriptions

Accounts can now be enrolled in an `attribute` [Subscription](/reference/accounts/subscriptions/overview) for
continuous monitoring of an Account's financial attributes. Once enrolled, Method automatically computes new
[Account Attributes](/reference/accounts/attributes/overview) and notifies your team via webhooks as they change.

```bash theme={null}
curl https://production.methodfi.com/accounts/{acc_id}/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "enroll": "attribute"
  }'
```

* Available for credit card, personal loan, and mortgage accounts
* The `attribute` subscription appears in an Account's `available_subscriptions` once eligible

<Note>Available when passing `Method-Version: 2026-03-30` in the request header.</Note>

***

### New Webhook Events

This version adds webhook coverage for the new account attribute resource lifecycle.

**New events:**

* `entity_attribute.create`
* `entity_attribute.update`
* `account_attribute.create`
* `account_attribute.update`

See [Webhooks](/reference/webhooks/overview) for the complete event list.

***

## Breaking Changes

* **Entity Attributes request semantics changed**

  * `POST /entities/{ent_id}/attributes` now computes all supported attributes automatically
  * The legacy request body for selecting specific `credit_health_*` attributes is no longer documented for `2026-03-30`

* **Entity Attributes response shape changed**

  * Legacy attribute payloads that returned `value` and `rating` have been replaced with a simplified `{ value, error }` shape
  * On success, `error` is `null`. On failure, `error` contains a standard `{ type, sub_type, code, message }` object (e.g. `ENTITY_ATTRIBUTE_INSUFFICIENT_DATA` code `27001` for entity attributes, `ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA` code `28001` for account attributes)
  * Attribute names now reflect the new attribute model

* **Account Attributes response shape changed**

  * Account attribute responses now use the same simplified `{ value, error }` result structure
  * Attribute availability now depends on the account's liability type

* **Attributes create endpoints are asynchronous**

  * Create requests now return an in-progress resource that must be polled or observed via webhook until completion

***

## Why It Matters

This release makes the attributes product more useful for underwriting, servicing, monitoring, and decisioning workflows.
With this release, developers can:

* Retrieve a richer set of entity- and account-level financial signals
* Build against a consistent result format across attributes
* Handle unavailable computations explicitly using standardized `error` objects with `type`, `sub_type`, `code`, and `message`
* Use asynchronous workflows that better fit long-running computations

***

## Upgrading to 2026-03-30

The new API version is available to all existing teams. New teams are automatically pinned to **`2026-03-30`**.

* **Request Header:** Set `Method-Version` to `2026-03-30`. See [API Versioning](/reference/versioning#api-versioning) for more information.
* **Client Libraries:** Check your Method SDK version and upgrade guidance before moving production traffic to the new API version.

> Once upgraded, rollbacks to prior API versions are not supported. Contact your Method CSM for upgrade assistance.

***

### Upgrade Support

Our technical integration team is available to help review your current usage of Attributes and plan a migration to `2026-03-30`. Contact your Method CSM for upgrade support.


# Handling Account Edge Cases
Source: https://docs.methodfi.com/guides/accounts/edge-cases

How to handle verification requirements, product limitations, and status changes.

## Handling Account Edge Cases

### 1. Accounts Requiring Verification

Some liability accounts discovered through [Connect](/guides/connect/overview) may appear in `restricted_products` with capabilities that require elevated verification (e.g., an account verification session). This is common for payment-capable accounts where Method needs additional confirmation. Create an [Account Verification Session](/reference/accounts/verification-sessions/create) to unlock these products.

### 2. Product Limitations by Account Type

Not all accounts support all products. Credit cards support [Card Brand](/reference/accounts/card-brands/overview) and [Payment Instruments](/reference/accounts/payment-instruments/overview); auto loans support [Payoffs](/reference/accounts/payoffs/overview); most liability types support [Updates](/guides/updates/overview) and [Balances](/reference/accounts/balances/overview). Always check the `products` array. See the [Liability Types](/guides/accounts/liability-types) page for a breakdown.

### 3. Status Changes Mid-Operation

If an account transitions to `disabled` or `closed` while you have in-flight operations (a pending payment, an in-progress update), those operations may fail. Design your flows to:

* Check account status before initiating operations
* Handle `account.disabled` and `account.closed` [webhooks](/reference/webhooks/overview) gracefully
* Show appropriate UI messages when an account is no longer available

See the [Account Lifecycle](/guides/accounts/lifecycle) guide for status transitions and webhook details.

### 4. Duplicate Accounts

[Connect](/guides/connect/overview) may discover the same underlying account multiple times if the user has accounts reported under slightly different names or through different credit bureaus. Method does attempt to de-duplicate these liability accounts, however instances do occur. Reach out to your CSM if this uncommon event occurs for one of your users.

### 5. Authorized User Accounts

Connect discovers all accounts on a user's credit report, including accounts where they are an authorized user (not the primary holder). The `liability.ownership` field indicates the relationship: `primary`, `authorized`, `joint`, or `unknown`. Consider whether your product should treat authorized-user accounts differently (e.g., payments on authorized-user cards may not be appropriate for [debt consolidation flows](/guides/use-cases/lending/debt-consolidation)).

### 6. Closed / Paid-Off Accounts

Accounts with zero balance or closed status at the financial institution may still appear in Connect results (they remain on the credit report). These accounts will have `status: closed` and limited [product](/reference/accounts/products/overview) availability. Filter them in your UI if they're not relevant to your use case.

### 7. Consent and Data Retention

When an Entity's consent is withdrawn (via the [Consent endpoint](/reference/accounts/consent/withdraw)), their accounts are disabled and data access is revoked. Your application should handle this gracefully — remove the accounts from active views and inform the user.

***

The key principle: design your application to check account status and product availability dynamically, and listen for [webhook notifications](/reference/webhooks/overview) about status changes. Accounts are living objects, and your application should respond to their state changes in real time rather than assuming a static state.

For the full Accounts API, see the [Accounts reference](/reference/accounts/overview).


# Funding Accounts
Source: https://docs.methodfi.com/guides/accounts/funding

Setting up and verifying your corporate payment source.

## Funding Accounts — Setting Up Payment Sources

Before payments can flow through Method, your platform needs a verified funding source — an ACH account that serves as the origin for all outbound payments. This is typically your company's corporate checking account, not an account belonging to your end users.

Your platform creates the funding account by [calling the Accounts API](/reference/accounts/create) with the routing number and account number for your corporate bank account:

```bash theme={null}
curl https://production.methodfi.com/accounts \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "holder_id": "ent_y1a9e1fbnJ1f3",
    "ach": {
      "routing": "021000021",
      "number": "1234567890",
      "type": "checking"
    }
  }'
```

The account must then be verified to confirm your organization controls it. Once verified, this single funding account can serve as the payment source across all of your users' liability payments.

<Note>
  Funding accounts are set up by your team (the platform integrating with Method), not by your end users. End users interact with liability accounts discovered through Connect — your corporate funding account is the source that powers payments to those liabilities.
</Note>

Method supports several verification approaches for funding accounts:

<CardGroup>
  <Card title="Micro-Deposits" icon="coins">
    The traditional verification method. Method sends two small deposits (typically a few cents each) to your corporate bank account. Your team confirms the deposit amounts, proving control of the account. This is universally supported but introduces a 1–2 business day delay while deposits settle.
  </Card>

  <Card title="Plaid" icon="bolt">
    Instant verification through Plaid's bank linking flow. If your platform already uses Plaid, this is a natural fit — authenticate with your bank through Plaid, and the verified account details are passed to Method. No waiting for micro-deposits.
  </Card>

  <Card title="MX" icon="bolt">
    Similar instant verification through MX's bank connectivity platform. Choose this if your platform uses MX for bank account linking.
  </Card>

  <Card title="Teller" icon="bolt">
    Another instant verification path through Teller's banking API. Like Plaid and MX, this eliminates the micro-deposit delay by verifying the account through direct bank authentication.
  </Card>
</CardGroup>

<Note>
  For most teams, instant verification (via Plaid, MX, or Teller) is strongly preferred because it eliminates the multi-day delay of micro-deposits and simplifies initial setup. If you don't have an existing relationship with any of these providers, Plaid is the most widely adopted option.
</Note>

## Verification Flow

1. Create the funding account ([`POST /accounts`](/reference/accounts/create))
2. Create a verification session ([`POST /accounts/{id}/verification_sessions`](/reference/accounts/verification-sessions/create)) specifying your preferred method
3. Complete the verification:
   * **Micro-deposits**: Wait 1–2 business days, then [update the session](/reference/accounts/verification-sessions/update-microdeposits) with the deposit amounts
   * **Plaid / MX / Teller**: Pass the processor token from your aggregator to the update endpoint ([Plaid](/reference/accounts/verification-sessions/update-plaid), [MX](/reference/accounts/verification-sessions/update-mx), [Teller](/reference/accounts/verification-sessions/update-teller))
4. Listen for the `account.active` [webhook](/reference/webhooks/overview) — the account is now ready for payments

See the [Account Verification Sessions reference](/reference/accounts/verification-sessions/overview) for full API details.

<Warning>
  If verification fails (wrong micro-deposit amounts, invalid aggregator token), the verification session moves to a `failed` status. You can create a new verification session to retry. After 3 failed micro-deposit attempts, the account may require a fresh set of deposits.
</Warning>

<Note>
  Your team can have multiple verified funding accounts. When [creating a payment](/reference/payments/create), you specify which funding account to use as the source. Most teams use a single corporate checking account, but you can set up additional funding accounts if your business requires separate payment sources.
</Note>


# Supported Liability Types
Source: https://docs.methodfi.com/guides/accounts/liability-types

The full range of consumer debt types Method supports.

## The Breadth of Supported Liability Types

Method supports an extensive range of liability types, reflecting the diversity of consumer debt in the real world. Supported types include:

* Credit cards — `credit_card` (from major national issuers to regional and community banks)
* Auto loans — `auto_loan` (from captive lenders like GM Financial and Toyota Motor Credit to banks and credit unions)
* Federal and private student loans — `student_loans`
* Personal and installment loans — `personal_loan`
* Mortgages and home equity lines of credit (HELOCs) — `mortgage`
* Collections accounts — `collection`
* Medical debt — `medical`
* Insurance premium obligations — `insurance`
* Utility accounts — `utility`
* Buy Now Pay Later (BNPL) accounts — `bnpl`
* Credit builder accounts — `credit_builder`
* Fintech-originated loans — `fintech`
* Other loan types — `loan`

The values above are the possible `liability.type` enum values on an Account. The `liability.sub_type` field provides additional granularity (e.g., `federal` vs. `private` for student loans, `heloc` for home equity lines). See the [Account reference](/reference/accounts/overview) for the complete list.

## How Liability Type Affects the Data Model

Each liability type also determines what enrichment data is available:

* **Credit cards**: Card brand name and visual art (via [Card Brands](/reference/accounts/card-brands/overview)), tokenized card credentials (via [Payment Instruments](/reference/accounts/payment-instruments/overview))
* **Auto loans**: Payoff quotes (via [Payoffs](/reference/accounts/payoffs/overview)), vehicle details including VIN, make, model (via [Vehicles](/reference/entities/vehicles/overview) on the Entity)
* **Student loans**: Federal vs. private distinction, servicer information
* **All types**: Credit health attributes (via [Attributes](/reference/accounts/attributes/overview)) where credit bureau data exists

<Note>
  Not every liability type supports every Method product. For example, Payments may be available for credit cards and auto loans but not for certain utility or collections accounts. Card Brand data is only relevant for credit cards. Payoff quotes are specific to auto loans. Each account carries a list of available [products](/reference/accounts/products/overview) so your application can adapt its UI and functionality based on what's supported for each specific account.
</Note>


# Account Lifecycle
Source: https://docs.methodfi.com/guides/accounts/lifecycle

Account statuses, available products, and state transitions.

## Account Lifecycle and Status

Accounts move through a defined set of statuses that reflect their current state:

| Status         | Description                                                                                                                                                                                                                                                 |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Active**     | The account is fully connected, verified (if applicable), and ready for use. All supported products are available. This is the normal operating state for most accounts.                                                                                    |
| **Processing** | The account is being set up or verified. For liability accounts, this may be a brief transitional state during discovery. For funding accounts, this typically means verification is in progress (e.g., waiting for micro-deposit confirmation).            |
| **Disabled**   | The account has been deactivated within Method. The account may still be active at the financial institution, but Method will not perform new operations on it. This can happen if the account is flagged for an issue or explicitly disabled by your team. |
| **Closed**     | Method has detected that the account is closed at the financial institution. The debt may have been paid off, the card may have been canceled, or the loan may have been settled. No new operations are available, but historical data remains accessible.  |

<Warning>
  **Common causes of Disabled status:** the Entity's [consent](/reference/accounts/consent/withdraw) was withdrawn, the Entity's verification expired or was revoked, the account was flagged by Method's risk monitoring, or your team explicitly disabled it via the API. Check the account's `error` field for the specific reason.
</Warning>

## State Transitions

* **Processing → Active**: Account setup or verification completes successfully
* **Active → Disabled**: Account is flagged for an issue or explicitly disabled. May be reversible — listen for `account.active` webhooks
* **Active → Closed**: Method detects the account is closed at the financial institution (debt paid off, card canceled, loan settled)
* **Disabled → Active**: The issue is resolved and the account is re-enabled
* **Closed** is terminal — closed accounts do not reopen

<Note>
  **Webhook tip:** Subscribe to `account.active`, `account.disabled`, and `account.closed` [webhook events](/reference/webhooks/overview) to handle transitions in real time rather than polling.
</Note>

### Key Webhooks

* `account.active`: Account transitioned to Active
* `account.disabled`: Account was disabled
* `account.closed`: Account was closed
* `account.update.completed`: An [Update](/guides/updates/overview) finished (balance/data refreshed)

## Subscriptions: Automatic Data Refresh

Instead of manually requesting [Updates](/guides/updates/overview) or [Balances](/reference/accounts/balances/overview), you can subscribe an account to automatic refresh. When subscribed, Method periodically fetches fresh data and notifies you via webhook. See [Update Subscriptions](/guides/updates/subscriptions) for details.

The `subscriptions` and `available_subscriptions` arrays on each Account show what's currently active and what can be enabled.

## Products and the Lifecycle

Each account carries a `products` array — the list of Method capabilities currently available for that account. Products include: `update` (refresh balances/data), `balance` (real-time balance), `payment` (send funds to creditor), `card_brand` (card art and product name), `payoff` (auto loan payoff quotes), `sensitive` (full account numbers), `attribute` (credit health metrics), and `payment_instrument` (card tokenization).

Product availability depends on three factors:

1. **Account type**: `card_brand` only applies to credit cards, `payoff` only to auto loans (see [Liability Types](/guides/accounts/liability-types))
2. **Account status**: Disabled and Closed accounts lose most products
3. **Team configuration**: Some products require team-level enablement (check `restricted_products`)

Always check the `products` array before attempting an operation. Attempting an operation not in `products` will return an error. See the [Products reference](/reference/accounts/products/overview) for the full list.


# Accounts
Source: https://docs.methodfi.com/guides/accounts/overview

Liability and funding accounts — the financial objects at the heart of your product.

<Note>
  **Using Opal?** If you're using [Opal](/guides/opal), Method's embedded UI, liability account discovery is handled for you — users complete a soft credit pull and see their accounts inside Opal's Connect flow. You'll still work with the resulting `Account` objects in your backend for payments, monitoring, and ongoing display in your app. Funding accounts are always configured by your team via the API. The rest of this section is most relevant if you're building a custom integration or want to understand the underlying data model.
</Note>

## What a Method Account Represents

An Account in Method is a connected financial account that belongs to one of your users ([Entities](/guides/entities/overview)). Accounts are the objects your product primarily interacts with. You pull data from accounts, monitor accounts for changes, make payments to accounts, and build your user-facing displays around account information.

Every Account belongs to an [Entity](/guides/entities/overview), the person whose financial life you're working with. An Entity can have many Accounts (a typical consumer has 5–15 liability accounts). You'll interact with Accounts through the Entity that owns them: create an Entity, verify their identity, run [Connect](/guides/connect/overview) to discover their liabilities, then work with the resulting Account objects.

Every account in Method falls into one of two categories, and understanding this distinction is essential for designing your product's payment and data flows:

<Tabs>
  <Tab title="Liability Accounts">
    Represent debts and financial obligations. These are the credit cards, auto loans, other obligations that your users owe money on. Liability accounts are typically discovered automatically through [Connect](/guides/connect/overview) and serve as the destination for payments, this is where money goes when your user pays down debt.
  </Tab>

  <Tab title="Funding Accounts">
    Represent the bank account your platform pays from. This is typically your corporate checking or savings account linked via ACH that serves as the source of funds for all payments. Funding accounts are created by your team by providing routing and account number details, and must be verified before they can be used.
  </Tab>
</Tabs>

In payment flows, the model is simple: money flows from your platform's funding account (source) to a liability account (destination). Your corporate bank account funds the payment; the end user's creditor receives it.

## How Accounts Are Created

Liability accounts are typically discovered automatically through [Connect](/guides/connect/overview). When you run Connect for an Entity, Method pulls their credit report and creates `Account` objects for every discovered liability. You can also [create liability accounts manually via the API](/reference/accounts/create) if you have the account details.

Funding accounts are created by your team through the API by providing a routing number and account number. See [Funding Accounts](/guides/accounts/funding) for setup and verification details.

## Account Products: What You Can Do With an Account

Every Account carries two arrays that control what operations are available:

* `products`: Capabilities currently available (e.g., `balance`, `payment`, `update`, `card_brand`, `payoff`, `sensitive`, `payment_instrument`)
* `restricted_products`: Capabilities the account could support but require additional steps (like elevated verification or team-level enablement), or capabilities the account does not currently support

Always check `products` before attempting an operation. For example, not all liability types support `payment` — attempting to create a payment on an account without `payment` in its `products` list will fail. See the [Products reference](/reference/accounts/products/overview) for the full list.

***

For the full Accounts API, including all fields, endpoints, and expandable resources, see the [Accounts reference](/reference/accounts/overview).


# Card Brand
Source: https://docs.methodfi.com/guides/additional-products/card-brand

Card product names, visual card art, and card details for trust and engagement.

For credit card accounts, Method can retrieve the specific card product name, visual card art, and structured card details, including APRs, fees, rewards, and promotional offers. Instead of displaying a generic "Visa credit card" line item, your product can show "Chase Sapphire Reserve" with the actual card image and card details.

<Frame>
  <img alt="Card Brand enrichment" />
</Frame>

This seemingly small detail has an outsized impact on user trust and engagement. When users see their actual card names and artwork in your product, it signals accuracy and builds confidence that the data is real and current.

<Warning>
  Card Brand is available only to partners processing payments using the PaymentInstrument endpoint. Contact your Method CSM for more information.
</Warning>

## How It Works

Card Brand is available as a Product (on-demand) or Subscription (continuous updates). Create a Card Brand request for a credit card account, and Method returns a `brands` array containing:

* **name:** The card product name (e.g., "Chase Sapphire Reserve")
* **network:** The card network (e.g., `visa`, `mastercard`)
* **network\_tier:** The network tier (e.g., `infinite`, `signature`)
* **url:** A hosted URL for the card art image
* **type:** Brand match quality: `specific` (exact match with card art), `generic` (general metadata, no specific FI offering), or `in_review` (undergoing verification)
* **details:** Structured card details: `card_category`, purchase & cash-advance APRs, annual & late fees, `rewards` (type, program, and earn categories), and `promotions` (with the sign-up bonus). Available on version `2025-07-04` and later; see the [Card Brand reference](/reference/accounts/card-brands/overview).

The `source` field on the response indicates where the data came from (`method` or `network`).

## Quick Start

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/card_brands \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const cardBrand = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .cardBrands
    .create();
  ```

  ```python Python theme={null}
  card_brand = method
    .accounts('acc_yVf3mkzbhz9tj')
    .card_brands
    .create()
  ```
</CodeGroup>

## Supported Cards

Card Brand is available for credit card accounts on Visa and Mastercard networks. Requesting Card Brand for a non-credit-card account or an unsupported network returns a `PRODUCT_UNAVAILABLE` error.

## Error Handling

* `PRODUCT_UNAVAILABLE`: Account isn't a credit card, or the network isn't Visa/Mastercard.
* `TEAM_CAPABILITY_RESTRICTED`: Your team doesn't have access to Card Brand.
* `CARD_BRANDS_NOT_FOUND`: The card's brand could not be found or doesn't exist.

<Card title="Card Brand API Reference" icon="credit-card" href="/reference/accounts/card-brands/overview">
  Full API documentation for Card Brand.
</Card>


# Credit Scores
Source: https://docs.methodfi.com/guides/additional-products/credit-scores

Credit score retrieval and monitoring for financial wellness products.

For financial wellness products, few data points are as universally understood and valued as the credit score. Method can retrieve credit scores for verified Entities, giving your product the ability to show users their score, track changes over time, and alert them to increases or decreases.

## How It Works

Credit Scores are available as a Product (on-demand) or Subscription (continuous updates via webhooks). Requests are asynchronous: you'll get an immediate response with `status: "pending"` and `scores: null`, then a webhook when the score is ready.

The response includes a `scores` array. Each score object contains:

* **score:** The numeric credit score
* **source:** The credit bureau (`equifax`, `experian`, or `transunion`)
* **model:** The scoring model (`vantage_3` for VantageScore 3.0 or `vantage_4` for VantageScore 4.0)
* **factors:** An array of factor objects (each with `code` and `description`) explaining what's influencing the score, e.g., "Total of all balances on bankcard or revolving accounts is too high"

## Quick Start

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/credit_scores \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const creditScore = await method
    .entities('ent_au22b1fbFJbp8')
    .creditScores
    .create();
  ```

  ```python Python theme={null}
  credit_score = method
    .entities('ent_au22b1fbFJbp8')
    .credit_scores
    .create()
  ```
</CodeGroup>

## Subscriptions

Scores can be retrieved on-demand (pull the current score when the user opens your app) or monitored via subscriptions (get notified automatically when the score changes). Webhook events (`credit_score.create`, `credit_score.update`, `credit_score.available`) tell you when a score becomes available or changes, enabling features like "Your credit score went up 12 points this month!" notifications that drive engagement and retention.

## Prerequisites

The Entity must be fully verified before you can request credit scores. Attempting to request scores for an unverified Entity returns an `ENTITY_VERIFICATION_MISSING` error.

## Error Handling

Request errors:

* `ENTITY_VERIFICATION_MISSING`: Entity must be fully verified first.
* `TEAM_CAPABILITY_RESTRICTED`: Your team doesn't have access to Credit Scores.

Resource errors (set on the Credit Score's `error` property):

* `CREDIT_SCORE_FAILED_TEMPORARILY_UNAVAILABLE`: Issue with the credit score provider, request could not be completed.

<Card title="Credit Scores API Reference" icon="chart-line" href="/reference/entities/credit-scores/overview">
  Full API documentation for Credit Scores.
</Card>


# Sensitive
Source: https://docs.methodfi.com/guides/additional-products/sensitive

Gated access to full account numbers and sensitive account data.

Sensitive is a specially gated product that provides access to full account numbers and other sensitive account data. This is not enabled by default; access requires explicit approval from Method.

<Warning>
  Sensitive data requires explicit enablement for your team. Access may require additional review, agreements, and approval from Method. Not all accounts or account types support Sensitive data retrieval.
</Warning>

## How It Works

Unlike most Method products, Sensitive requests are *synchronous*. You'll get the data back immediately in the response.

When creating a Sensitive request, you must specify an `expand` array indicating which fields you want. Available fields depend on the account's liability type:

**Credit Cards:**

* `credit_card.number`: Full card number (PAN)
* `credit_card.exp_month`: Expiration month
* `credit_card.exp_year`: Expiration year
* `credit_card.cvv`: Card CVV
* `credit_card.billing_zip_code`: Billing zip code

**All other liability types** (auto loan, mortgage, personal loan, collection, student loans, credit builder, BNPL, fintech, loan):

* `{type}.number`: Full account number (e.g., `auto_loan.number`, `mortgage.number`)

## Supported Account Types

Sensitive supports: credit card, auto loan, mortgage, personal loan, collection, student loans, credit builder, BNPL, fintech, and loan accounts.

## Quick Start

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/sensitive \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "expand": [
        "credit_card.number",
        "credit_card.exp_month",
        "credit_card.exp_year",
        "credit_card.cvv"
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const sensitive = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .sensitive
    .create({
      expand: [
        'credit_card.number',
        'credit_card.exp_month',
        'credit_card.exp_year',
        'credit_card.cvv'
      ],
    });
  ```

  ```python Python theme={null}
  sensitive = method
    .accounts('acc_yVf3mkzbhz9tj')
    .sensitive
    .create({
      'expand': [
        'credit_card.number',
        'credit_card.exp_month',
        'credit_card.exp_year',
        'credit_card.cvv'
      ]
    })
  ```
</CodeGroup>

## Security Requirements

If your use case requires full account numbers (for example, to initiate payments through external systems or to populate forms on behalf of users), you'll need to request Sensitive access from Method. If approved, you're expected to follow strict security practices:

* Apply the principle of least privilege, only request sensitive data when needed
* Store secrets and sensitive data securely using encryption at rest and in transit
* Maintain audit logging on your side for all access to sensitive data
* PCI compliance is required

<Card title="Sensitive API Reference" icon="lock" href="/reference/accounts/sensitive/overview">
  Full API documentation for Sensitive.
</Card>


# Vehicles
Source: https://docs.methodfi.com/guides/additional-products/vehicles

Auto loan enrichment with VIN, make, model, and vehicle details.

For applications that deal with auto loans, whether that's auto refinancing, insurance, fleet management, or vehicle valuation, Method can enrich an Entity's profile with detailed vehicle information.

## How It Works

Vehicles is an Entity-level product: you request it against an Entity, not an individual Account. This means a single request returns all vehicles associated with that person. The response is synchronous, you'll get the data back immediately.

The `vehicles` array in the response contains one object per vehicle, each with:

* **vin:** Vehicle Identification Number
* **year:** Make year (e.g., "2021")
* **make:** Manufacturer (e.g., "honda")
* **model:** Model (e.g., "accord")
* **series:** Series/Trim/Category (e.g., "lx", "ex"), may be `null`
* **major\_color:** Primary color (e.g., "black")
* **style:** Body style (e.g., "sedan/saloon", "crew\_pickup", "sport\_utility\_vehicle")

This transforms an abstract "auto loan" line item into a concrete vehicle identity. Instead of showing "Auto Loan: \$18,450 balance," your product can display "2022 Honda Civic LX: \$18,450 remaining." This enrichment dramatically improves the user experience and enables vehicle-specific features like valuation estimates, equity calculations, and insurance comparisons.

## Quick Start

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/vehicles \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const vehicles = await method
    .entities('ent_au22b1fbFJbp8')
    .vehicles
    .create();
  ```

  ```python Python theme={null}
  vehicles = method
    .entities('ent_au22b1fbFJbp8')
    .vehicles
    .create()
  ```
</CodeGroup>

## Multiple Vehicles

An Entity can have multiple vehicles. The response `vehicles` array will contain all of them. This is useful for presenting a vehicle selector in your UI or for fleet management use cases.

<Card title="Vehicles API Reference" icon="car" href="/reference/entities/vehicles/overview">
  Full API documentation for Vehicles.
</Card>


# Core Concepts
Source: https://docs.methodfi.com/guides/concepts

The mental model for Method's platform — objects, relationships, and data flow.

This section provides a bird's-eye view of Method's core concepts and how they relate to each other. Think of it as the mental model you'll carry throughout the rest of this guide, every section that follows goes deeper on one of these concepts.

## The Core Platform Objects

<CardGroup>
  <Card title="Entity" icon="user" href="/guides/entities/overview">
    A user's identity in Method. An Entity represents one individual (or business) and serves as the root object for all accounts, verifications, and transactions. Each user in your application maps to exactly one Entity.
  </Card>

  <Card title="Identity Verification (IDV)" icon="shield-check" href="/guides/identity-verification/overview">
    Verifies that a user is who they claim to be before Method can access credit data or process payments. IDV includes phone verification and identity verification and acts as a one-time gate that unlocks downstream products.
  </Card>

  <Card title="Connect" icon="link" href="/guides/connect/overview">
    Discovers what a user owes. Using a verified Entity, Connect performs a soft credit pull to automatically identify liabilities across financial institutions, giving your application visibility into a user's full debt profile.
  </Card>

  <Card title="Accounts" icon="building-columns" href="/guides/accounts/overview">
    The financial objects your application interacts with. Accounts include discovered liabilities (credit cards, loans, etc.) and funding sources used for payments. They are the objects you monitor, update, and pay against.
  </Card>

  <Card title="Updates" icon="arrows-rotate" href="/guides/updates/overview">
    Provides fresh data about accounts. Updates deliver the latest balances, due dates, minimum payments, interest rates, and more through credit report snapshots or direct institutional connections.
  </Card>

  <Card title="Payments" icon="money-bill-transfer" href="/guides/payments/overview">
    Moves money to pay down liabilities. You initiate a payment from a verified funding source, and Method handles the full lifecycle: submission, processing, delivery to the creditor, and confirmation.
  </Card>
</CardGroup>

## The Dependency Chain

These concepts build on each other in a natural progression. Not every integration uses every product, a monitoring-only product might skip Payments entirely, while a paydown-focused product might use all of them. But the dependency chain means you always start with an Entity, verify their identity, and connect their accounts before you can take action.

### Typical End-to-End Flows

| Flow               | Path                                                         |
| ------------------ | ------------------------------------------------------------ |
| **Debt discovery** | Entity → IDV → Connect → Accounts → Updates                  |
| **Debt paydown**   | Entity → IDV → Connect → Accounts → Payments → Updates       |
| **Monitoring**     | Entity → IDV → Connect → Accounts → Subscriptions → Webhooks |

<Note>
  **Using Opal?** Opal handles Entity creation, identity verification, and account discovery in a single embedded flow. If you're using Opal, you don't build the first three steps yourself — Opal orchestrates them for you, and your integration picks up at the Accounts stage.
</Note>

## Additional Products

Beyond the six core concepts, Method offers specialized products that enrich the data and capabilities available on connected accounts.

### Commonly Used

<CardGroup>
  <Card title="Credit Score" icon="chart-line" href="/guides/additional-products/credit-scores">
    Credit score retrieval and monitoring, essential for financial wellness products that want to show users their score alongside their debt profile.
  </Card>

  <Card title="Attributes" icon="chart-pie" href="/guides/additional-products/attributes">
    Delivers structured credit health metrics (e.g., credit card usage, payment history), useful for building personalized insights, recommendations, or risk assessments.
  </Card>

  <Card title="Card Brand" icon="credit-card" href="/guides/additional-products/card-brand">
    Retrieves the specific card product name and card art (e.g., "Chase Sapphire Preferred" with the actual card image), great for building visually rich account displays.
  </Card>
</CardGroup>

### Specialized

<CardGroup>
  <Card title="Vehicles" icon="car" href="/guides/additional-products/vehicles">
    Enriches auto loan accounts with vehicle details (make, model, VIN), valuable for auto-focused lending or insurance products.
  </Card>

  <Card title="Sensitive" icon="lock" href="/guides/additional-products/sensitive">
    Provides gated access to full account numbers and other sensitive data, available by approval only, for use cases that require raw account credentials.
  </Card>

  <Card title="Payment Instruments" icon="wallet" href="/guides/payments/instruments">
    Creates reusable payment configurations (card credentials, ACH details, network tokens), enables repeated payment scenarios without re-collecting credentials each time.
  </Card>
</CardGroup>

Most integrations use a subset of these products. A basic debt discovery app needs only Entities, IDV, Connect, and Updates. A payment-focused product adds Payments and a Funding Account. Start with what your use case requires — you can enable additional products as your product evolves.

<CardGroup>
  <Card title="API Reference" icon="code" href="/reference/introduction">
    Full endpoint documentation for every object described above.
  </Card>
</CardGroup>


# Errors and Edge Cases
Source: https://docs.methodfi.com/guides/connect/errors

Common Connect errors and how to handle them.

## Common Connect Errors

### Request errors (returned immediately)

* **`ENTITY_VERIFICATION_MISSING`**: Entity must be fully verified before Connect. Complete both phone and identity verification first. See [Identity Verification](/guides/identity-verification/overview).
* **`TEAM_CAPABILITY_RESTRICTED`**: Your team doesn't have access to Connect. Contact your CSM.
* **`ACCOUNT_CONSENT_UNAVAILABLE`**: Account consent isn't available for your organization.

### Async errors (returned after processing)

* **`THIN_CREDIT_FILE`**: No tradelines found. The user has no credit history reportable to bureaus.
* **`CREDIT_FREEZE`**: The user has a credit freeze in place. The user must lift their freeze before discovery can complete.
* **`PRODUCT_EXECUTION_FAILED`**: A downstream product (balance, update, etc.) failed to execute on connected accounts. The Connect itself succeeded, but some product data may be missing.

<Warning>
  **Credit freeze messaging.** If a user hits `CREDIT_FREEZE`, surface a clear message explaining they need to lift their credit freeze.
</Warning>

For the full list of Connect error codes, see the [Connect Errors reference](/reference/errors/connect-errors).


# How Connect Works
Source: https://docs.methodfi.com/guides/connect/how-it-works

Soft-pull credit reports, auto vs manual discovery, and coverage.

## How Discovery Works

Connect uses the verified Entity's personally identifying information and the user's consent to perform a soft-pull credit report. A soft pull is fundamentally different from a hard credit inquiry — it has zero impact on the user's credit score and leaves no visible mark on their credit report. This is important messaging for your users, who may be hesitant about anything that touches their credit.

The credit report reveals the user's open liabilities across financial institutions. Method parses this data, matches it against its network of 15,000+ supported institutions, and creates account objects for each discovered liability. These accounts are immediately available in your application for data retrieval, monitoring, and (where supported) payment processing.

<Tip>
  **Processing time.** Connect typically completes within seconds for most users. Users with extensive credit histories (many open accounts) may take slightly longer.
</Tip>

<Tip>
  **Account matching.** Method matches each tradeline on the credit report against its network of 15,000+ financial institutions. When a match is found, Method creates an Account object with the appropriate `products` array based on what's supported for that merchant and liability type. Unmatched tradelines (institutions not in Method's network) are not returned.
</Tip>

## Complete Connect Flow

### Step 1: Create a Connect

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "products": ["balance", "update"],
    "subscriptions": ["update"]
  }'
```

### Step 2: Wait for completion

Connect processes asynchronously when products or subscriptions are specified, or when the `Prefer: respond-async` header is set. Listen for the `connect.update` webhook to know when discovery is complete:

```json theme={null}
{
  "id": "cxn_4ewMmBbjYDMR4",
  "type": "connect.update",
  "path": "/entities/ent_au22b1fbFJbp8/connect/cxn_4ewMmBbjYDMR4"
}
```

### Step 3: Retrieve results

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect/cxn_4ewMmBbjYDMR4 \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

<Tip>
  **Expand for efficiency.** Use the `expand` query parameter to include full Account objects, balances, card brands, or other data in the Connect response, avoiding additional API calls: `?expand=accounts,accounts.balance,accounts.card_brand`
</Tip>

## Synchronous vs Asynchronous Processing

A bare Connect request (no products, no subscriptions, no `Prefer: respond-async` header) processes synchronously — the response includes the completed results immediately.

When you include `products`, `subscriptions`, or the `Prefer: respond-async` header, Connect processes asynchronously. The response returns immediately with `status: pending` or `status: in_progress`, and you'll receive a `connect.update` webhook when processing completes.

<Note>
  **Recommendation:** Always set up webhooks for Connect. Even synchronous requests can take several seconds for users with many liabilities, and products/subscriptions always trigger async processing.
</Note>

## Requesting Products and Subscriptions at Connect Time

Connect can automatically execute products and set up subscriptions on all discovered accounts in a single call. This eliminates the need to iterate over accounts and make individual product requests after discovery.

**Available products:**

* `balance`: Retrieve balances for all discovered accounts
* `update`: Pull real-time data from source institutions
* `card_brand`: Retrieve card brand art and product names
* `attribute`: Pull structured credit health metrics
* `payoff`: Get payoff quotes (auto loans)

**Available subscriptions:**

* `update`: Subscribe to real-time data refreshes
* `update.snapshot`: Subscribe to periodic snapshot updates
* `card_brand`: Subscribe to card brand changes
* `transaction`: Subscribe to new transaction events

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "products": ["balance", "card_brand"],
    "subscriptions": ["update"]
  }'
```

<Note>
  Products and subscriptions are only executed on accounts where they're available. If an account doesn't support a product, requesting it won't cause an error — it simply won't apply to that account.
</Note>

## Connect Statuses

* `pending`: The Connect request is queued for processing
* `in_progress`: Discovery is actively running (soft pull being performed, accounts being matched)
* `completed`: Discovery finished successfully, accounts are available
* `failed`: Discovery failed (see error object for details)

Poll the Connect status or listen for `connect.update` webhooks to track progress.

## Connect vs. Manual Connect

Connect is the automatic discovery path — Method finds the accounts for you. But there are scenarios where you already have account data from another source (a prior data pull, user input, a partner integration) and want to register those accounts in Method without re-discovering them. That's what Manual Connect is for.

Manual Connect creates account objects from data you provide, bypassing the credit report discovery step. This is useful for: migrating existing users from a legacy system, supplementing discovered accounts with additional accounts the user provides manually, or connecting accounts that aren't reported to credit bureaus (and therefore wouldn't be discovered through Connect).

<Tabs>
  <Tab title="Connect (Auto Discovery)">
    Method performs a soft-pull credit report and automatically discovers the user's liabilities.

    **Use when:**

    * Onboarding new users
    * You want the broadest possible account discovery
    * Users don't know all their account details

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```
  </Tab>

  <Tab title="Manual Connect">
    You provide raw credit report tradeline data and Method creates account objects from it, bypassing the soft-pull step.

    **Use when:**

    * Migrating existing users from a legacy system where you already have their bureau data
    * Ingesting tradelines pulled directly from Equifax or TransUnion via your own bureau relationship
    * Backfilling historical tradeline data for an Entity

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/manual_connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "bureau": "transunion",
        "tradelines": [
          {
            "type_code": "18",
            "portfolio_type_code": "revolving",
            "designator_code": "individual",
            "number": "5555555555555555",
            "creditor_name": "CAPITAL ONE",
            "creditor_code": "01DTV001",
            "balance": 500000,
            "highest_balance": 750000,
            "credit_limit": 1000000,
            "term": null,
            "next_payment_minimum_amount": 15000,
            "last_payment_amount": 20000,
            "payment_history": ["1", "1", "1"],
            "past_due_amount": 0,
            "delinquency_charge_off_amount": 0,
            "opened_at": "2016-11-25",
            "last_activity_date": "2024-05-01",
            "reported_date": "2024-05-01",
            "next_payment_due_date": "2024-06-01",
            "last_payment_date": "2024-05-01",
            "delinquency_first_start_date": null,
            "narrative_codes": [
              { "code": "FE", "description": "CREDIT CARD" }
            ]
          }
        ]
      }'
    ```

    <Note>
      Manual Connect ingests **raw bureau tradelines** — it expects the full schema your bureau returns (creditor codes, payment history, delinquency dates, narrative codes, etc.). It is not a lightweight "user enters a missing account" flow. See the [Manual Connect reference](/reference/entities/manual-connect/create) for the full tradeline schema.
    </Note>
  </Tab>
</Tabs>

## Coverage — What Gets Discovered

Connect's coverage spans the broad spectrum of consumer liabilities, including:

<Accordion title="Supported liability types">
  * Credit cards from major issuers and regional banks
  * Auto loans from captive lenders and financial institutions
  * Federal and private student loans
  * Personal and installment loans
  * Mortgages and home equity lines of credit (HELOCs)
  * Collections accounts
  * Medical debt
  * Insurance payment obligations
  * Utility accounts
  * Buy Now Pay Later (BNPL) obligations
  * Credit builder accounts
  * Fintech-originated loans
</Accordion>

<Note>
  **Coverage notes:**

  * Credit cards, auto loans, and student loans have the broadest coverage across issuers
  * Collections accounts are reported inconsistently across bureaus — some may not appear
  * BNPL and utility accounts have growing but variable coverage
  * Closed accounts are included in the first Connect call but may have limited product availability
  * Coverage varies by specific institution, not just liability type. A major bank's credit cards will have broader product support than a small regional lender's
</Note>

## Expanding Connect Results

Use the `expand` query parameter to include full Account objects and their sub-resources directly in the Connect response, eliminating additional API calls:

```
POST /entities/{ent_id}/connect?expand=accounts,accounts.balance,accounts.card_brand
```

Available expansions: `accounts`, `accounts.balance`, `accounts.card_brand`, `accounts.attribute`, `accounts.update`, `accounts.payment_instrument`, `accounts.latest_verification_session`. If you expand a sub-field, the parent `accounts` expansion is applied automatically.


# Connect — Account Discovery
Source: https://docs.methodfi.com/guides/connect/overview

How Method discovers your users' complete liability picture.

<Frame>
  <img alt="Connect" />
</Frame>

<Note>
  **Using Opal?** If you're using Method's embedded UI, Opal handles account discovery as part of its managed flow — you don't need to call the Connect API directly. See the [Opal guide](/opal/overview) for details. The rest of this section is for custom API integrations.
</Note>

## What Connect Does

Connect discovers and links all of a user's financial liabilities in a single API call. Using the Entity's verified identity, Connect performs a soft-pull credit report and matches the results against Method's network of 15,000+ supported financial institutions. Each discovered liability becomes an Account object in your application, immediately available for data retrieval, monitoring, and payments where applicable.

## When to Use Connect

Connect is the standard path for any product that needs a comprehensive view of a user's debts: debt management, financial wellness, lending (pre-qualification, consolidation, portfolio monitoring), and bill pay. If your product involves consumer liabilities, Connect is almost certainly how you'll discover them.

## Prerequisites

Before calling Connect, the Entity must be fully verified (both phone and identity verification completed). Attempting Connect on an unverified Entity returns `ENTITY_VERIFICATION_MISSING`. See [Identity Verification](/guides/identity-verification/overview) for details.

## What Comes Back

A successful Connect returns a list of Account IDs representing the user's discovered liabilities. Each Account includes the merchant (who the debt is owed to), the liability type (credit card, auto loan, mortgage, etc.), and the `products` array indicating what Method can do with that account (balance retrieval, real-time updates, payments).

```json theme={null}
{
  "id": "cxn_4ewMmBbjYDMR4",
  "entity_id": "ent_qKNBB68bfHGNA",
  "status": "completed",
  "accounts": [
    "acc_eKKmrXDpJBKgw",
    "acc_GV8WbmJW7KGRy",
    "acc_MLPKh9gQDDbT8"
  ],
  "requested_products": [],
  "requested_subscriptions": [],
  "error": null,
  "created_at": "2024-04-12T14:56:46.645Z",
  "updated_at": "2024-04-12T14:56:46.645Z"
}
```

<Tip>
  **First Connect vs. subsequent calls.** The first Connect for an Entity returns all discovered liabilities (active and closed). Subsequent Connect calls for the same Entity only return *new* accounts that weren't in previous results. This is important for re-discovery flows — you won't get duplicates.
</Tip>

## Understanding Account Products

Each Account returned from Connect has a `products` array indicating what Method supports for that merchant:

* `balance`: retrieve the current balance
* `update`: pull real-time data (balances, rates, due dates) directly from the institution
* `payment`: send payments to this account through Method
* `sensitive`: access full account numbers (gated, requires approval)

Not every account supports every product. A credit card from a major issuer will likely have `balance`, `update`, and `payment`. A collections account may only have `balance`. Check `products` before building flows that assume full coverage.

## Next Steps

* [How Connect Works](/guides/connect/how-it-works): Soft pulls, auto vs manual discovery, coverage details
* [Handling Partial Results](/guides/connect/partial-results): Designing for incomplete discovery
* [Connect Subscriptions](/guides/connect/subscriptions): Monitoring for new liabilities over time
* [Connect API Reference](/reference/entities/connect/overview): Full endpoint documentation


# Handling Partial Results
Source: https://docs.methodfi.com/guides/connect/partial-results

Designing for incomplete discovery results.

# Handling Partial Results

<Note>
  Connect may not discover every liability a user has. Design your product to treat partial results as the normal case.
</Note>

## Why Results May Be Incomplete

**Not all liabilities appear on credit reports.** Some debts (private loans between individuals, certain employer-provided benefits, some BNPL arrangements) are never reported to credit bureaus and won't be found by Connect.

**Reporting delays.** New accounts may not appear on a credit report for 30–60 days after opening. A user who just opened a credit card last week won't see it in Connect results yet.

**Unmatched institutions.** Method's network covers 15,000+ institutions, but some smaller or newer creditors may not yet be supported. The tradeline exists on the credit report, but Method can't create an actionable Account from it because the institution isn't in Method's network.

**Closed accounts.** The first Connect returns both open and closed accounts. Closed accounts may have limited product availability (e.g., no payments, no updates).

## Recommended Patterns

### Show what was found, supplement where possible

After Connect completes, display the discovered accounts. If you have access to additional bureau data the user, you can supplement the discovered set by ingesting raw credit report tradelines via [Manual Connect](/reference/entities/manual-connect/create):

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/manual_connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "bureau": "transunion",
    "tradelines": [
      {
        "type_code": "18",
        "portfolio_type_code": "revolving",
        "designator_code": "individual",
        "number": "5555555555555555",
        "creditor_name": "CAPITAL ONE",
        "creditor_code": "01DTV001",
        "balance": 500000,
        "highest_balance": 750000,
        "credit_limit": 1000000,
        "term": null,
        "next_payment_minimum_amount": 15000,
        "last_payment_amount": 20000,
        "payment_history": ["1", "1", "1"],
        "past_due_amount": 0,
        "delinquency_charge_off_amount": 0,
        "opened_at": "2016-11-25",
        "last_activity_date": "2024-05-01",
        "reported_date": "2024-05-01",
        "next_payment_due_date": "2024-06-01",
        "last_payment_date": "2024-05-01",
        "delinquency_first_start_date": null,
        "narrative_codes": [
          { "code": "FE", "description": "CREDIT CARD" }
        ]
      }
    ]
  }'
```

<Note>
  Manual Connect requires the full bureau tradeline schema (creditor codes, payment history, delinquency dates, narrative codes, etc.) — it is not a lightweight "user enters a missing account" flow. If you need that pattern, talk to your CSM about the right approach for your use case.
</Note>

### Enable Connect subscriptions for ongoing discovery

New liabilities that appear on future credit reports will be automatically discovered. See [Connect Subscriptions](/guides/connect/subscriptions).

### Handle zero results gracefully

If Connect returns zero accounts (thin credit file), don't show an empty state. Explain that the credit report didn't contain tradelines and offer Manual Connect as the path forward.

### Account-level product gaps

Even when an account is discovered, it may not support all products. Always check the `products` array before making assumptions:

```javascript theme={null}
const account = await method.accounts.retrieve('acc_eKKmrXDpJBKgw');

if (account.products.includes('payment')) {
  // Safe to initiate payments
} else {
  // Data-only — can retrieve balances but can't send money
}
```

For the full Connect API, see the [Connect reference](/reference/entities/connect/overview).


# Raw Credit Reports
Source: https://docs.methodfi.com/guides/connect/raw-credit-reports

Receive the raw bureau credit report behind a Connect as downloadable files.

Connect discovers liabilities using the user's credit report. Teams with raw credit report access enabled can also receive that underlying bureau report itself, as a downloadable raw credit report JSON and/or credit report PDF returned as [Files](/reference/files/overview). Files give you a durable copy of the report (e.g. for compliance archives or underwriting reviews) that can be re-downloaded at any time.

## Prerequisites

* Raw credit report features are enabled on a case-by-case basis. Contact Method to enable these.
* The Entity must be verified and must not have [withdrawn consent](/reference/entities/consent/withdraw).

## Requesting the raw report

<Steps>
  <Step title="Create a Connect with artifacts">
    Pass `bureau` and `artifacts` when [creating a Connect](/reference/entities/connect/create):

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "bureau": "transunion",
        "artifacts": ["raw_credit_report", "credit_report_pdf"]
      }'
    ```

    | Field       | Type    | Notes                                                                                                                              |
    | ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
    | `bureau`    | enum    | `transunion` or `equifax`. Required whenever `artifacts` is set. Method will work with your team to set which bureaus are allowed. |
    | `artifacts` | enum\[] | Any of `raw_credit_report`, `credit_report_pdf`. Each becomes a downloadable File on the Connect.                                  |

    <Note>
      Each Connect pulls from a single bureau. To receive credit reports from both bureaus, you will need to make 2 separate Connect calls.
    </Note>
  </Step>

  <Step title="Read the response">
    The Connect response includes the requested artifacts in `files`:

    ```json theme={null}
    {
      "id": "cxn_4ewMmBbjYDMR4",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "completed",
      "accounts": ["acc_eKKmrXDpJBKgw", "acc_GV8WbmJW7KGRy"],
      "requested_products": [],
      "requested_subscriptions": [],
      "files": [
        {
          "id": "file_jZWkPMhXPeYAn",
          "type": "raw_credit_report",
          "bureau": "transunion",
          "mime_type": "application/json"
        },
        {
          "id": "file_qTnUv7DdKcRW2",
          "type": "credit_report_pdf",
          "bureau": "transunion",
          "mime_type": "application/pdf"
        }
      ],
      "error": null,
      "created_at": "2026-07-06T18:00:00.000Z",
      "updated_at": "2026-07-06T18:00:12.000Z"
    }
    ```
  </Step>

  <Step title="Download the file artifacts">
    Note the `file_id`s in the above response and use [Retrieve a File](/reference/files/retrieve) to get the File's metadata, including a temporary `download_url` to its contents:

    ```bash theme={null}
    curl https://production.methodfi.com/files/file_jZWkPMhXPeYAn \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    Fetch the `download_url`. A new URL is generated on every retrieve and expires at `download_expires_at`.

    Additionally, you can stream a File's contents directly with [Download a File](/reference/files/download):

    ```bash theme={null}
    curl https://production.methodfi.com/files/file_jZWkPMhXPeYAn/download \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -o raw_credit_report.json
    ```
  </Step>
</Steps>

## Retrieving the raw report later

Files persist after the Connect completes. [Retrieve the Connect](/reference/entities/connect/retrieve) at any time to read its `files` array, then download the contents via the [Files API](/reference/files/overview).

## Webhooks

Connects with products or subscriptions (or the `Prefer: respond-async` header) process asynchronously. Listen for `connect.available` to know when an async Connect (including its artifacts) is ready, and `connect.create` for synchronous completions. See [Connect webhooks](/guides/connect/subscriptions).

## Errors

| `sub_type`                              | Cause                                                         |
| --------------------------------------- | ------------------------------------------------------------- |
| `CONNECT_BUREAU_REQUIRED_FOR_ARTIFACTS` | `artifacts` sent without `bureau`                             |
| `CONNECT_BUREAU_NOT_CONFIGURED`         | No bureaus have been configured for your team                 |
| `CONNECT_BUREAU_NOT_ENABLED`            | The requested bureau is not in your team's allowed bureaus    |
| `CONNECT_RAW_REPORT_NOT_ENABLED`        | The `raw_credit_report` artifact is not enabled for your team |
| `CONNECT_CREDIT_REPORT_PDF_NOT_ENABLED` | The `credit_report_pdf` artifact is not enabled for your team |

See [Connect errors](/reference/errors/connect-errors) and [File errors](/reference/errors/file-errors) for the full list.

<Note>
  **Handling sensitive data.** The raw credit report contains the consumer's full bureau file. Treat it as highly sensitive: store it encrypted, restrict access, and only retain it as long as your compliance obligations require.
</Note>

For the full API surface, see the [Connect reference](/reference/entities/connect/overview) and the [Files reference](/reference/files/overview).


# Connect Subscriptions
Source: https://docs.methodfi.com/guides/connect/subscriptions

Monitoring for new liabilities over time.

## Connect Subscriptions — Monitoring for New Liabilities

A user's liability profile isn't static. They open new credit cards, take out new loans, and accumulate new obligations over time. Connect Subscriptions monitor for these changes by periodically checking the Entity's credit report for new liabilities.

When a new account is discovered, Method creates it and notifies you via webhook. This enables your product to surface new debts automatically, keep the user's liability picture complete without requiring them to re-run discovery, and trigger workflows when new accounts appear (e.g., automatically requesting updates for newly discovered accounts).

The typical pattern is to enable a Connect subscription after the initial Connect completes, creating a continuous discovery pipeline that keeps your application's view of the user's liabilities current over time.

## Creating a Connect Subscription

Use the [Entity Subscriptions endpoint](/reference/entities/subscriptions/create) to enroll an Entity in ongoing Connect monitoring:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{ "enroll": "connect" }'
```

<Note>
  The Connect endpoint's `subscriptions` body parameter is for *account-level* subscriptions (`update`, `card_brand`, etc.) that apply to discovered accounts. To subscribe to ongoing *discovery* of new liabilities, use the Entity Subscriptions endpoint with `"enroll": "connect"` as shown above.
</Note>

<Tip>
  **Subscription frequency.** Connect subscriptions periodically perform soft-pull credit checks to detect new tradelines.
</Tip>

## Webhooks

Connect fires the following webhook events:

* `connect.create`: Connect request was created
* `connect.update`: Connect status changed (use this to detect completion)
* `connect.available`: New accounts are available (fired by Connect subscriptions when new liabilities are detected)

```json theme={null}
{
  "id": "cxn_4ewMmBbjYDMR4",
  "type": "connect.update",
  "path": "/entities/ent_au22b1fbFJbp8/connect/cxn_4ewMmBbjYDMR4"
}
```

Set up webhooks via the [Webhooks API](/reference/webhooks/overview) to receive real-time notifications.

## Receiving New Account Notifications

When a Connect subscription discovers new liabilities, Method fires a `connect.available` webhook:

```json theme={null}
{
  "id": "cxn_new123",
  "type": "connect.available",
  "path": "/entities/ent_au22b1fbFJbp8/connect/cxn_new123"
}
```

Retrieve the Connect object to see the newly discovered Account IDs. Only new accounts are included — previously discovered accounts are not repeated.

## Managing Subscriptions

To unsubscribe from Connect monitoring:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/subscriptions/sub_abc123 \
  -X DELETE \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

See [Entity Subscriptions](/reference/entities/subscriptions/overview) for the full subscription management API.

## When to Use Connect Subscriptions

<Tip>
  **When to use Connect subscriptions:**

  * Debt management / financial wellness apps where the user's liability picture must stay current
  * Portfolio monitoring where new liabilities impact risk assessment
  * Lending products that need to detect new debts after origination

  **When you may not need them:**

  * One-time Connect for a loan application (discovery is a point-in-time event)
</Tip>


# Testing Connect
Source: https://docs.methodfi.com/guides/connect/testing

How to test Connect in development.

## Testing Connect in Development

Use the simulation endpoint to queue Connect behaviors in your development environment:

```bash theme={null}
curl https://dev.methodfi.com/simulate/entities/{entity_id}/connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "behaviors": ["new_credit_card_account", "new_auto_loan_account"] }'
```

Each behavior is consumed the next time Connect runs for that Entity. Maximum 5 behaviors per Entity.

**Available behaviors:** `new_credit_card_account`, `new_auto_loan_account`, `new_mortgage_account`, `new_student_loan_account`, `new_personal_loan_account`.

<Note>
  **Simulation limitations.** Simulated accounts won't have real institution data. Use them to test your integration flow (webhooks, UI rendering, product execution), not data accuracy.
</Note>

For the full simulation API, see the [Simulate Connect reference](/reference/simulations/connect/create).


# Entity Errors — What Can Go Wrong and How to Handle It
Source: https://docs.methodfi.com/guides/entities/errors

What can go wrong during Entity creation and how to handle it.

## Entity Errors and Edge Cases

The most common issues during Entity creation stem from missing or incorrectly formatted user information. Understanding these helps you design an onboarding flow that minimizes friction and handles errors gracefully.

* **Missing required fields**: Entity creation requires certain identifying information (at minimum, a name and phone number for individuals). If required fields are omitted, the creation will fail. In your user experience, this typically means your onboarding form should collect all necessary fields upfront and validate completeness before submission. If you're collecting information across multiple screens, ensure the full set is available when you create the Entity.
* **Invalid formats**: PII fields must meet specific format requirements, phone numbers must be valid US numbers, dates of birth must be real dates, and so on. Customer-side validation catches most of these issues before they reach Method's API. Design your input fields with appropriate format masks, validation rules, and helpful error messages so users can correct issues immediately rather than encountering failures downstream.

### Immutable PII Fields

Once a PII field has been set to a non-null value on an Entity (name, phone, DOB, SSN), it **cannot be changed**. If a user enters incorrect information and it gets submitted to Method, you cannot correct it via the API.

**How to handle it:**

* For fields that are still `null`, you can update them at any time via the [Update endpoint](/reference/entities/update-entity)
* For genuine corrections (e.g., legal name change), contact Method support
* You may need to create a new Entity for that user

### Operations on Disabled Entities

If an Entity transitions to `disabled` (via consent withdrawal or a compliance event), any attempt to initiate new operations — connecting accounts, creating payments, requesting products — will fail. Existing data remains readable.

**How to handle it:** Check the Entity's `status` before initiating operations. If `disabled`, display a clear message and prevent actions that would fail. See [Entity Lifecycle](/guides/entities/lifecycle) for more on state transitions.

### Phone Number Formatting

Phone numbers must be in **E.164 format** (e.g., `+15121234567`). Common issues:

* Missing country code (`5121234567` instead of `+15121234567`)
* Including formatting characters (`(512) 123-4567` instead of `+15121234567`)
* Non-US numbers (Method currently supports US numbers only)

Validate and normalize phone numbers on your end before submitting to Method.

### Common Error Responses

When Entity creation or updates fail, Method returns structured error responses. Here are the most common:

**Missing required field:**

```json theme={null}
{
  "error": {
    "type": "INVALID_REQUEST",
    "sub_type": "INVALID_REQUEST",
    "message": "Field \"individual\" is required. Verify your request and try again."
  }
}
```

**Invalid phone format:**

```json theme={null}
{
  "error": {
    "type": "INVALID_REQUEST",
    "sub_type": "INVALID_REQUEST",
    "message": "Field \"individual.phone\" is in an invalid format. Verify your request and try again."
  }
}
```

**Attempting to update an immutable field:**

```json theme={null}
{
  "error": {
    "type": "INVALID_REQUEST",
    "sub_type": "ENTITY_UPDATE_INVALID",
    "message": "Updates are only allowed on fields that have not been set. Verify your request and try again."
  }
}
```

For the complete list of Entity error codes, see [Entity Errors](/reference/errors/entity-errors) in the API Reference.

### When Issues Persist

If Entity creation consistently fails, first check the `error` field on the API response — it contains structured details about what went wrong. Most issues can be resolved by fixing input data and retrying.

If the error is unclear or you believe it's incorrect, contact Method support with:

* The Entity ID (`ent_...`) if one was created
* The full error response
* The request payload that triggered the error

<Note>
  Entity errors should be handled as a normal part of your onboarding flow,
  not as exceptional failures. Validate input early, provide clear error
  messaging, and allow users to correct and retry without starting over.
  For engineering teams: see the full error codes and response formats in the
  <a href="/reference/errors/entity-errors">Entity Errors reference</a>.
</Note>

<CardGroup>
  <Card title="Identity Verification Guide" icon="shield-check" href="/guides/identity-verification/overview">
    Next: verify your user's identity to unlock products.
  </Card>

  <Card title="Entity Errors Reference" icon="code" href="/reference/errors/entity-errors">
    Full list of error codes, types, and sub-types.
  </Card>
</CardGroup>


# Entity Lifecycle — From Creation to Active Use
Source: https://docs.methodfi.com/guides/entities/lifecycle

From creation to active use — understanding Entity states and transitions.

## Entity Lifecycle — From Creation to Active Use

### Lifecycle States

Every Entity in Method exists in one of three states, and understanding these states helps you design the right user experience at each stage of your onboarding flow:

* **Incomplete:** The Entity has been created in Method, but the user hasn't completed all required steps to unlock the platform's capabilities. This is the starting state for every new Entity. In practical terms, your application knows who this person is, but Method hasn't yet verified their identity or connected their accounts. Most products are unavailable in this state. Your application should guide the user through the remaining setup steps (typically identity verification) and clearly indicate that setup isn't finished.
* **Active:** The Entity is fully set up and ready for use. Identity verification is complete, and the full range of eligible products is available. This is the steady state for most of your users. Your application can connect accounts, request updates, initiate payments, and enable monitoring. The user should experience the full value of your product.
* **Disabled:** The Entity has been deactivated and can no longer be used for new operations. This may happen because your team withdrew consent via the [Consent endpoint](/reference/entities/consent/withdraw), because Method disabled the Entity for compliance reasons, or because the user requested account closure through your application.
  No new operations can be initiated, but existing data, accounts, payment history, updates — remains accessible for reference and reporting.

### Common Lifecycle Transitions

**incomplete → active**
Triggered when the Entity completes all verification requirements configured for your team. For most teams, this means both phone and identity verification. The transition happens automatically — once the final verification session succeeds, the Entity's status updates and products become available.

**active → disabled**
Can be triggered by:

* Your team withdrawing consent via the [Consent endpoint](/reference/entities/consent/withdraw)
* A compliance event (e.g., a payment reversal triggers a policy review)
* Method disabling the Entity for policy reasons

This transition is permanent — disabled Entities cannot be reactivated. To re-onboard the user, create a new Entity.

**What about abandoned onboarding?**
Entities that stay in `incomplete` (the user never finished verification) don't expire. Build a resume flow that picks up where the user left off rather than creating a new Entity on their next visit.

Entities must be `active` before they can be `disabled`. An `incomplete` Entity that's no longer needed can simply be left in place — it doesn't incur cost or require cleanup.

### Reacting to State Changes

Entity state changes trigger `entity.update` webhooks. Subscribe to these to react in real time — for example, unlocking features when an Entity transitions to `active`, or displaying a deactivation notice when it becomes `disabled`. See [Webhooks](/reference/webhooks/overview).

### Designing Around Lifecycle States

Your user experiences should reflect the Entity's state:

* For incomplete Entities, show a clear onboarding progress indicator. Let the user know what steps remain (e.g., "Verify your identity to see your accounts"). Avoid showing empty states that suggest the product is broken — the user is mid-setup, not experiencing an error.
* For active Entities, provide full access to your product's features. This is your core experience.
* For disabled Entities, display a clear, non-alarming message explaining that the account is no longer active. Allow the user to view historical data if appropriate, but prevent any actions that would fail (payment initiation, account connection, etc.)

<CardGroup>
  <Card title="Errors & Edge Cases" icon="triangle-exclamation" href="/guides/entities/errors">
    What can go wrong during Entity creation and how to handle it.
  </Card>

  <Card title="Entity API Reference" icon="code" href="/reference/entities/overview">
    See the full Entity object including status, verification, products, and subscriptions.
  </Card>
</CardGroup>


# Entities — The Foundation of Every Integration
Source: https://docs.methodfi.com/guides/entities/overview

What an Entity represents, why it matters, and how it maps to your users.

## Entities — The Foundation of Every Integration

### The Entity Model

An Entity is Method's representation of a person or business in your system — a persistent profile that anchors everything Method knows about your user. Their verified identity, discovered accounts, payment history, and active subscriptions all connect through a single Entity. Every operation your application performs through Method — identity verification, account discovery, payments, monitoring — flows through the user's Entity.

### Why the Entity Model Matters

* **Persistent verification:** Once verified, the Entity carries that status forward. You don't re-verify for every operation.
* **Single reference point:** All accounts, payments, and updates for a user are scoped to their Entity. This also enforces authorization boundaries — one Entity's operations can't affect another.
* **Lifecycle management:** The Entity's status tracks the user's journey from onboarding through active use to potential deactivation, enforcing appropriate constraints at each stage.

### Entity vs End User

Your application has users; Method has Entities. These map one-to-one. Each end user in your application corresponds to exactly one Entity in Method, and that relationship persists throughout the user's lifecycle. You'll typically store the Method Entity ID alongside your internal user ID so you can bridge between the two systems seamlessly.

<Warning>
  Method does not automatically deduplicate Entities. If your application
  creates two Entities for the same person, both will exist independently
  with separate accounts and data. Your application should enforce uniqueness
  (typically by phone number) before creating new Entities.
</Warning>

### Individual vs Corporation Entities

Method supports two types of Entities, corresponding to the two types of financial actors:

<Tabs>
  <Tab title="Individual">
    Individual Entities represent people. To create one, you provide identifying information,  typically at minimum a name and phone number, with additional fields (date of birth, address, SSN) required for identity verification and access to downstream products. Individual Entities are by far the most common type and support the full range of Method's products.

    ```bash theme={null}
    curl https://production.methodfi.com/entities \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "individual",
        "individual": {
          "first_name": "John",
          "last_name": "Doe",
          "phone": "+15121234567"
        }
      }'
    ```
  </Tab>

  <Tab title="Corporation">
    Corporation Entity represents any business, regardless of its legal structure. Corporation Entities go through a business-specific verification process (KYB) and have their own product eligibility path.

    Corporation Entities support a different subset of capabilities than Individuals. They are primarily used for payment origination scenarios and do not have the same product catalog (no credit scores, Connect, or individual-specific features). If your use case involves both consumers and businesses, your architecture will need to account for this difference.

    ```bash theme={null}
    curl https://production.methodfi.com/entities \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "corporation",
        "corporation": {
          "name": "Acme Inc.",
          "ein": "123456789"
        }
      }'
    ```
  </Tab>
</Tabs>

### What Information Do You Need to Collect?

At minimum, most teams need a user's **name and phone number** to create an Individual Entity. However, additional PII (date of birth, SSN or last 4 of SSN, email, address) is typically required to complete identity verification and unlock products like Connect and Credit Score.

Your specific PII requirements are configured during onboarding. A common pattern is to create the Entity early with minimal information, then progressively update it as you collect more data during your onboarding flow. Contact your Method CSM if you're unsure about your team's requirements.

<CardGroup>
  <Card title="Entity Lifecycle" icon="arrows-spin" href="/guides/entities/lifecycle">
    Understand Entity states and how users transition from onboarding to active use.
  </Card>

  <Card title="Errors & Edge Cases" icon="triangle-exclamation" href="/guides/entities/errors">
    What can go wrong during Entity creation and how to design around it.
  </Card>

  <Card title="Identity Verification" icon="shield-check" href="/guides/identity-verification/overview">
    The next step after Entity creation — verifying your user's identity.
  </Card>

  <Card title="Entity API Reference" icon="code" href="/reference/entities/overview">
    Full Entity object schema, CRUD endpoints, and field details.
  </Card>
</CardGroup>


# IDV Errors & Edge Cases
Source: https://docs.methodfi.com/guides/identity-verification/errors

Common verification errors, failure modes, and how to handle edge cases.

## IDV Errors & Edge Cases

### Phone Verification Failures

| Error                                                    | Cause                                                             | Resolution                                                                                                                           |
| -------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `VERIFICATION_SESSION_EXPIRED` (19001)                   | Session not completed within the 10-minute window                 | Create a new verification session. Consider adding a timer or progress indicator to your UX.                                         |
| `VERIFICATION_SESSION_FAILED_INCORRECT_SMS_CODE` (19002) | User entered the wrong SMS code                                   | Create a new verification session. Confirm the user is entering the code from the most recent SMS.                                   |
| `VERIFICATION_SESSION_FAILED_SNA` (19003)                | User not on a mobile device, or on an unsupported carrier/network | Fall back to SMS verification. SNA access attempts are limited to 5 per session.                                                     |
| `ENTITY_PHONE_VERIFICATION_MAX_ATTEMPTS`                 | Too many verification attempts for this Entity's phone number     | The underlying SMS provider has rate-limited this phone number. Wait before retrying, and surface appropriate messaging to the user. |

### Identity Verification Failures

| Error                                                | Cause                                                                                           | Resolution                                                                                                                                                                               |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MISSING_IDENTITY_MATCH`                             | Method couldn't correlate the Entity's PII to a known identity — insufficient or incorrect PII  | [Update the Entity](/reference/entities/update-entity) with additional fields (DOB, SSN, address) and retry. See [Maximizing Success](/guides/identity-verification/maximizing-success). |
| `VERIFICATION_SESSION_FAILED_INVALID_ANSWER` (19004) | User answered one or more KBA questions incorrectly, or a question was missing from the request | Create a new verification session — a fresh set of questions will be generated. Confirm the user is answering carefully.                                                                 |
| `VERIFICATION_SESSION_EXPIRED` (19001)               | Session not completed within the 10-minute window                                               | Create a new verification session.                                                                                                                                                       |

### Request Errors

| Error                              | Cause                                                                                        | Resolution                                                                        |
| ---------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `MISSING_PHONE_VERIFICATION`       | Attempted to create an identity verification session before phone verification was completed | Complete phone verification first, then create the identity verification session. |
| `EXISTING_VERIFIED_SESSION`        | The Entity has already completed verification for that type (phone or identity)              | No action needed — the Entity is already verified for that step.                  |
| `INVALID_ENTITY_TYPE`              | Attempted to create a verification session on a corporation Entity                           | Verification sessions are only available for Entities of type `individual`.       |
| `UNAUTHORIZED_VERIFICATION_METHOD` | The team is not authorized to use the requested verification method                          | Contact your Method CSM to enable the method (e.g., `byo_sms`, `byo_kyc`).        |

### Edge Cases

<Accordion title="User needs a different phone number mid-flow">
  An Entity's phone number cannot be changed once it has been set. If the user entered the wrong phone number, you'll need to create a new Entity with the correct phone number and start the verification process from the beginning.
</Accordion>

<Accordion title="Same phone number across multiple Entities">
  Multiple Entities can share the same phone number, but each Entity must complete its own verification independently.
</Accordion>

<Accordion title="Re-verification after Entity was previously verified">
  Attempting to create a verification session for an already-verified type will return `EXISTING_VERIFIED_SESSION`. Verification is persistent and does not need to be repeated.
</Accordion>

<Accordion title="Attempting verification on a disabled Entity">
  Verification sessions cannot be created for Entities that have been disabled. Ensure the Entity is in an active state before initiating verification.
</Accordion>

<Accordion title="Corporation Entity">
  Verification sessions are only available for individual Entities. Attempting to create a session on a corporation Entity will return `INVALID_ENTITY_TYPE`.
</Accordion>

### Error Code Reference

For the full list of error codes with response bodies, see the [Entity Verification Session Errors](/reference/errors/entity-verification-session-errors) reference.


# Maximizing Verification Success
Source: https://docs.methodfi.com/guides/identity-verification/maximizing-success

How to improve match rates and verification success through better data collection.

## Maximizing Verification Success

Not all PII fields are required for every verification method, but providing more data significantly improves match rates and verification success. At minimum, you need a name and phone number, but including date of birth, address, and SSN (last 4 or full) dramatically increases the likelihood of a successful match. Design your onboarding flow to collect as much PII as practical without creating excessive friction.

| Field                | Impact   | Why it matters                                            |
| -------------------- | -------- | --------------------------------------------------------- |
| First + Last name    | Required | Baseline identity anchor                                  |
| Phone number         | Required | Links to carrier records and Method's network             |
| Date of birth        | High     | Disambiguates common names, strong identity signal        |
| Address              | High     | Confirms geographic identity, helps with thin files       |
| Email                | Moderate | Secondary signal, helps when primary fields are ambiguous |
| SSN (last 4 or full) | Highest  | Strongest single identity signal, near-guaranteed match   |

### Common Pitfalls

* **Phone number without country code** — Method only accepts US phone numbers at this time, and they must include the `+1` country code (e.g., `+15551234567`)
* **Abbreviated names vs. legal names** — use the name on their credit file, not nicknames (e.g., "William" not "Bill")
* **PO Box instead of physical address** — physical addresses match better against identity records
* **Stale or outdated address** — use the user's current address, not a previous one

<Note>
  For platform availability details, see the [IDV Overview](/guides/identity-verification/overview).
</Note>

<CardGroup>
  <Card title="Verification Outcomes" icon="circle-check" href="/guides/identity-verification/outcomes">
    When data collection is maximized but matching still fails.
  </Card>

  <Card title="Verification Sessions API" icon="code" href="/reference/entities/verification-sessions/overview">
    Full API reference for verification session endpoints.
  </Card>
</CardGroup>


# Verification Methods
Source: https://docs.methodfi.com/guides/identity-verification/methods

Choosing the right phone and identity verification approach for your integration.

## Verification Methods

<Warning>
  All verification sessions expire **10 minutes** after creation. If the user doesn't complete verification within that window, you'll need to create a new session. Design your UX to guide users through verification promptly and handle the expired session error gracefully. See [Errors & Edge Cases](/guides/identity-verification/errors) for details.
</Warning>

Phone verification must be completed before identity verification can begin. Choose one method from each step below. Most teams use the same approach (Opal, API-driven, or BYO) for both steps, but you can mix — for example, SNA for phone and KBA for identity.

### Choosing Your Phone Verification Method

<Tabs>
  <Tab title="Opal (Recommended)">
    Phone verification is handled entirely within the Opal embedded UI. The user enters their phone number, receives a verification code, and enters it — all within a polished, pre-built interface. This is the fastest path to implementation and provides the most consistent user experience.
  </Tab>

  <Tab title="SMS Verification">
    Method sends a verification code to the user's phone, and your application collects and submits the code. Choose this if you want to integrate phone verification into your own custom UI while still having Method handle the SMS delivery.

    ```bash theme={null}
    # 1. Create SMS verification session
    curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "sms",
        "sms": {}
      }'

    # 2. Submit the code the user received
    curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "sms",
        "sms": {
          "sms_code": "123456"
        }
      }'
    ```
  </Tab>

  <Tab title="Silent Network Auth (SNA)">
    The phone is verified in the background using carrier-level network signals, with no user interaction required. This provides the best user experience (the user doesn't have to do anything), but availability depends on the user's carrier and network conditions. Consider SNA as a primary method with SMS as a fallback.

    <Warning>
      SNA requires the user to be on a mobile device connected to a supported carrier's network. It does not work on landlines, VoIP numbers, or most prepaid/MVNO carriers. The returned URLs must be opened via background request or the device's mobile browser. Always implement SMS as a fallback — SNA failures may be silent and your application needs to detect them (via session status polling or webhook) and offer an alternative. SNA access attempts are limited to 5 per session before the session fails.
    </Warning>
  </Tab>

  <Tab title="BYO SMS">
    You handle SMS delivery and verification entirely on your side and report the result to Method. Choose this if you already have a robust SMS verification system and want to maintain a single verification flow across your application.

    <Note>
      BYO SMS requires your team to be pre-authorized during onboarding. You'll create a verification session with method `byo_sms` and provide the `byo_sms.timestamp` field — the ISO 8601 timestamp of when you verified the phone number. Contact your Method CSM to enable this method.
    </Note>

    ```bash theme={null}
    curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "byo_sms",
        "byo_sms": {
          "timestamp": "2026-04-10T12:00:00.000Z"
        }
      }'
    ```
  </Tab>
</Tabs>

#### Choosing a Phone Method

| Method      | User Experience            | Implementation                | Reliability                  | Best For                                 |
| ----------- | -------------------------- | ----------------------------- | ---------------------------- | ---------------------------------------- |
| **Opal**    | Polished, pre-built        | Minimal (embed SDK)           | High                         | Most teams                               |
| **SMS**     | Standard (enter code)      | Medium (collect + submit)     | High                         | Custom UI with Method SMS delivery       |
| **SNA**     | Invisible (no user action) | Medium (background URL calls) | Variable (carrier-dependent) | Mobile-first products, with SMS fallback |
| **BYO SMS** | Your existing flow         | Low (report result)           | Depends on your provider     | Teams with existing SMS verification     |

**Recommended pattern:** Use SNA as primary with SMS as automatic fallback. This gives the best conversion rate while ensuring every user can complete verification.

<Note>
  Phone verification has a maximum attempt limit enforced by the underlying SMS provider. If the limit is reached, the error `ENTITY_PHONE_VERIFICATION_MAX_ATTEMPTS` is returned and you'll need to wait before retrying. Design your flow to inform users of the limit and avoid excessive retries.
</Note>

### Choosing Your Identity Verification Method

<Tabs>
  <Tab title="Opal (Recommended)">
    Identity verification is handled within the Opal embedded UI. The user is guided through the KYC process in a managed, tested flow. This is the simplest path and ensures the verification experience is optimized for completion.
  </Tab>

  <Tab title="KBA">
    The user answers a set of identity questions generated from their credit and public record history (e.g., "Which of these addresses have you lived at?"). Your application presents the questions and collects answers. KBA is widely supported but can be frustrating for users if questions are obscure or ambiguous.

    ```bash theme={null}
    # 1. Create KBA verification session (returns questions)
    curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "identity",
        "method": "kba",
        "kba": {}
      }'

    # 2. Submit answers to the questions
    curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "identity",
        "method": "kba",
        "kba": {
          "answers": [
            { "question_id": "qtn_xxx", "answer_id": "ans_xxx" },
            { "question_id": "qtn_yyy", "answer_id": "ans_yyy" }
          ]
        }
      }'
    ```
  </Tab>

  <Tab title="BYO KYC">
    You perform identity verification on your side using your own KYC provider and report the outcome to Method. Choose this if you already have a KYC integration and want to consolidate verification into a single flow, or if you need to meet specific compliance requirements that require a particular KYC vendor.

    <Note>
      BYO KYC requires your team to be pre-authorized during onboarding. By creating this session, you're asserting that your external KYC process has passed for this user. Method trusts your KYC result — there are no constraints on which KYC vendor you use. Contact your Method CSM to enable this method.
    </Note>

    ```bash theme={null}
    curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "identity",
        "method": "byo_kyc",
        "byo_kyc": {}
      }'
    ```

    The response will include `byo_kyc: { authenticated: true }` confirming the verification was recorded.
  </Tab>
</Tabs>

#### Choosing an Identity Method

| Method      | User Experience     | Implementation                              | Best For                                   |
| ----------- | ------------------- | ------------------------------------------- | ------------------------------------------ |
| **Opal**    | Guided, pre-built   | Minimal                                     | Most teams                                 |
| **KBA**     | Multi-question quiz | Medium (present questions, collect answers) | API-only integrations without existing KYC |
| **BYO KYC** | Your existing flow  | Low (report result)                         | Teams with existing KYC provider           |

<Note>
  **About `element` and `method_verified` methods:** The API also lists `element` and `method_verified` as valid verification methods. `element` is the predecessor to Opal — new integrations should use Opal instead. `method_verified` is an internal method used by Method and is not available for external use.
</Note>


# Verification Outcomes
Source: https://docs.methodfi.com/guides/identity-verification/outcomes

Understanding the difference between Matched and Verified states.

## Verification Outcomes

### Understanding Verification Outcomes: Matched vs. Verified

Method distinguishes between two verification states, and understanding the difference matters:

| State                        | Meaning                                                        | Unlocks products? |
| ---------------------------- | -------------------------------------------------------------- | ----------------- |
| Neither matched nor verified | Entity created, not yet verified                               | No                |
| Matched only                 | Method identified the person, but they haven't proven identity | No                |
| Matched + Verified           | Full identity confirmation complete                            | Yes               |

An Entity cannot reach Verified status without first being Matched. If matching fails, verification cannot proceed.

In practical terms: matched means "we know who you are," and verified means "you've proven you're that person." Both are required.

### How Matching Works

When you create or update an Entity with PII (name, DOB, SSN, address, phone), Method attempts to correlate that information against its identity records. If the PII matches a known identity, the Entity becomes `matched`. This happens automatically when the Entity's PII is processed — you don't call a separate endpoint for matching.

The Entity's `matched` status is then checked when you create an identity verification session. If the Entity is not yet matched, the session creation will fail with `MISSING_IDENTITY_MATCH`.

Matching can fail if:

* The PII is incomplete (name + phone only, no DOB or SSN)
* The PII has typos or formatting issues
* The person has a thin file (limited credit/identity history)

See [Maximizing Verification Success](/guides/identity-verification/maximizing-success) for how to improve match rates.

### When Matching Fails

If Method cannot match the Entity's PII to a known identity, creating an identity verification session will return a `MISSING_IDENTITY_MATCH` error. Your options:

1. **Collect more PII:** Update the Entity with additional fields (DOB, SSN, address) and retry. More PII dramatically improves match rates.
2. **Verify the data:** Check for typos, name variations (maiden names, Jr/Sr suffixes), or incorrect phone numbers.

<Warning>
  Match failures are not the same as verification failures. A match failure means Method couldn't identify the person at all. A verification failure (KBA wrong answers, SMS wrong code) means the person was identified but couldn't prove they're that person.

  You will need to create a new Entity if a user fails identity verification (e.g., incorrect KBA answers). The failed Entity cannot be reused for identity verification.
</Warning>

### Checking Verification Status

The Entity object includes a `verification` field that reflects the current state:

```json theme={null}
"verification": {
  "identity": {
    "verified": true,
    "matched": true,
    "latest_verification_session": "evf_xxx",
    "methods": []
  },
  "phone": {
    "verified": true,
    "latest_verification_session": "evf_yyy",
    "methods": []
  }
}
```

When verification is incomplete, the `methods` arrays will contain the available verification methods for that step (e.g., `["sms", "sna"]` for phone, `["kba"]` for identity). Once a step is completed, its `methods` array becomes empty.

Use these fields to determine what actions are available for the Entity. See the [Entity API Reference](/reference/entities/overview) for full field documentation.

<CardGroup>
  <Card title="Maximizing Success" icon="chart-line" href="/guides/identity-verification/maximizing-success">
    Improve match rates through better data collection.
  </Card>

  <Card title="Verification Sessions API" icon="code" href="/reference/entities/verification-sessions/overview">
    Full API reference for verification session endpoints.
  </Card>
</CardGroup>


# Identity Verification (IDV)
Source: https://docs.methodfi.com/guides/identity-verification/overview

Why identity verification matters and how the two-step process works.

<Frame>
  <img alt="Identity Verification" />
</Frame>

## Proving Your Users Are Who They Claim to Be

<Warning>
  Method currently supports identity verification for US-based individuals only. Users without a US credit history or US phone number cannot complete verification.
</Warning>

### Why IDV Matters

Identity verification is the gateway to Method's platform. Before Method will discover a user's accounts, retrieve their credit data, or process payments on their behalf, the user must prove they are who they claim to be. It's a fundamental fraud prevention and compliance requirement that protects both your users and your platform.

For your product, IDV is typically the first meaningful interaction a user has after signing up. The verification experience directly impacts your onboarding conversion rate: a smooth, fast verification flow keeps users engaged, while a clunky or confusing one creates drop-off. Choosing the right verification approach is one of the most impactful product decisions you'll make in your Method integration.

IDV gates access to every downstream product: [Connect](/guides/connect/overview) (account discovery), [Updates](/guides/updates/overview) (fresh balances), [Payments](/guides/payments/overview), [Credit Scores](/guides/additional-products/credit-scores), [Attributes](/guides/additional-products/attributes), and more. An Entity that hasn't completed IDV stays in `incomplete` status with no product access. For most integrations, IDV is the single highest-impact step to optimize — every percentage point of verification conversion translates directly to users who can access your product's core features.

<Info>
  **Using Opal?** If you're using Method's embedded UI, Opal handles both phone verification and identity verification in a single, managed flow. You don't need to build verification screens or manage session state — Opal orchestrates the entire process. The rest of this section is relevant if you're building a custom integration or want to understand what Opal is doing under the hood. See the [Opal guide](/opal/identity/overview) for details.
</Info>

### The Two-Step Process

IDV consists of two sequential steps, each serving a distinct purpose:

<Steps>
  <Step title="Phone Verification">
    Confirms that the user controls the phone number associated with their identity. This is the "something you have" factor — it proves the person filling out your form actually possesses the phone number they provided.

    <Warning>
      Phone verification must be completed before identity verification can begin. Attempting to create an identity verification session for an Entity without phone verification will fail with `MISSING_PHONE_VERIFICATION`.
    </Warning>
  </Step>

  <Step title="Identity Verification">
    Confirms that the user's provided information matches a real person's identity through a KYC (Know Your Customer) process — it proves they are who they claim to be, not just someone who has access to a phone number.
  </Step>
</Steps>

Both steps must be completed for an Entity to be fully verified and gain access to downstream products.

### What Happens After Verification

Once both steps are complete, the Entity's status updates to `active` and the Entity becomes both `matched` and `verified`, unlocking downstream products: [Connect](/guides/connect/overview) (account discovery), [Credit Scores](/guides/additional-products/credit-scores), [Payments](/guides/payments/overview), and more. The verification is persistent — you don't need to re-verify for subsequent operations. See [Entity Lifecycle](/guides/entities/lifecycle) for how verification status affects what you can do.

<CardGroup>
  <Card title="Verification Methods" icon="list-check" href="/guides/identity-verification/methods">
    Choose the right phone and identity verification approach.
  </Card>

  <Card title="Verification Outcomes" icon="circle-check" href="/guides/identity-verification/outcomes">
    Understand the difference between Matched and Verified.
  </Card>

  <Card title="Maximizing Success" icon="chart-line" href="/guides/identity-verification/maximizing-success">
    Improve match rates through better data collection.
  </Card>

  <Card title="Verification Sessions API" icon="code" href="/reference/entities/verification-sessions/overview">
    Full API reference for verification session endpoints.
  </Card>
</CardGroup>


# The Verification Flow
Source: https://docs.methodfi.com/guides/identity-verification/verification-flow

Step-by-step verification sequence, state transitions, webhooks, and code walkthroughs.

## The Verification Flow

### Step-by-Step Sequence

<Steps>
  <Step title="Create Entity with PII">
    Create an Entity with at minimum a name and phone number. If you're using the API-driven flow (not Opal), providing more PII (DOB, SSN, address) significantly improves match rates. Opal collects PII directly from the user during its flow, so upfront PII is less critical when using Opal. See [Maximizing Success](/guides/identity-verification/maximizing-success).
  </Step>

  <Step title="Check available verification methods">
    Inspect `entity.verification.phone.methods` and `entity.verification.identity.methods` to see which verification methods are available for this Entity.
  </Step>

  <Step title="Create phone verification session">
    Choose a phone verification method (SMS, SNA, or BYO SMS) and create a verification session.
  </Step>

  <Step title="Complete phone verification">
    Complete the phone verification using the method-specific flow (submit SMS code, process SNA URLs, or report BYO result).
  </Step>

  <Step title="Create identity verification session">
    Once phone is verified, create an identity verification session (KBA or BYO KYC). This will fail with `MISSING_PHONE_VERIFICATION` if phone verification is not complete, or `MISSING_IDENTITY_MATCH` if Method couldn't match the Entity's PII.
  </Step>

  <Step title="Complete identity verification">
    Complete the identity verification using the method-specific flow (submit KBA answers or report BYO KYC result).
  </Step>

  <Step title="Entity is verified">
    Entity is now matched + verified. Proceed to [Connect](/guides/connect/overview), [Payments](/guides/payments/overview), or other products.
  </Step>
</Steps>

### State Diagram

```
[Entity created] → [Phone: unverified] → [Phone: verified] → [Identity: unverified] → [Identity: matched + verified] → [Products unlocked]
```

Each verification session goes through its own lifecycle:

```
pending → in_progress → verified (success)
                       → failed (expired, incorrect code/answer, SNA failure)
```

### Webhooks

Subscribe to verification session events to track progress:

* **`entity_verification_session.create`** — Fired when a new verification session is created.
* **`entity_verification_session.update`** — Fired when a session's status changes (e.g., `pending` → `verified`, `pending` → `failed`).

These events allow you to build reactive flows — for example, unlocking the next step of your onboarding when phone verification completes.

### Code Walkthroughs

#### SMS + KBA (most common API-driven path)

```bash theme={null}
# 1. Create an Entity
curl -X POST https://production.methodfi.com/entities \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "individual": {
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+15551234567",
      "dob": "1990-01-15"
    }
  }'

# 2. Create SMS phone verification session
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sms",
    "sms": {}
  }'

# 3. User receives SMS code, submit it
curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sms",
    "sms": { "sms_code": "123456" }
  }'

# 4. Create KBA identity verification session (returns questions)
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity",
    "method": "kba",
    "kba": {}
  }'

# 5. Present questions to user, then submit answers
curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_yyy \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity",
    "method": "kba",
    "kba": {
      "answers": [
        { "question_id": "qtn_aaa", "answer_id": "ans_bbb" },
        { "question_id": "qtn_ccc", "answer_id": "ans_ddd" }
      ]
    }
  }'

# Entity is now verified — proceed to Connect or other products
```

#### SNA + KBA (best UX path)

```bash theme={null}
# 1. Create Entity (same as above)

# 2. Create SNA phone verification session
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sna",
    "sna": {}
  }'
# Response includes SNA URLs — open them via background request on the user's device

# 3. Update SNA session to check verification status
curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sna",
    "sna": {}
  }'
# If SNA fails, fall back to SMS (create a new session with method "sms")

# 4-5. Proceed with KBA identity verification (same as above)
```

#### BYO SMS + BYO KYC (existing infrastructure path)

```bash theme={null}
# 1. Create Entity (same as above)

# 2. Report BYO SMS phone verification
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "byo_sms",
    "byo_sms": {
      "timestamp": "2026-04-10T12:00:00.000Z"
    }
  }'

# 3. Report BYO KYC identity verification
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity",
    "method": "byo_kyc",
    "byo_kyc": {}
  }'

# Entity is now verified
```


# Opal
Source: https://docs.methodfi.com/guides/opal

Method's embedded UI for identity verification, account discovery, and more.

## What Opal Is and Why It Matters

Opal is Method's embedded UI, a set of pre-built, white-labeled screens and flows that you drop into your application to handle the complex, multi-step processes of identity verification, account discovery, and more. Instead of designing, building, testing, and maintaining these flows yourself, you launch Opal and let it guide your users through the process in a polished, tested experience.

Opal represents a significant acceleration of your roadmap. Building identity verification and account linking flows from scratch typically takes weeks of engineering time, plus ongoing maintenance as edge cases, error states, and accessibility requirements emerge. Opal compresses this to days, your engineering team creates a session token, launches the component, and listens for completion events. Everything in between is handled by Method.

Opal is also designed for conversion. The flows are optimized for completion rates, with clear progress indicators, helpful error messaging, and the ability for users to resume interrupted sessions without starting over. When a user's phone dies mid-verification or they need to step away, their progress is saved.

## Opal Modes — What Your Users Experience

Opal operates in distinct modes, each handling a specific part of the user journey. You can launch these independently depending on where the user is in your flow:

<CardGroup>
  <Card title="Identity Verification" icon="shield-check" href="/opal/identity/overview">
    Guides the user through Method's two-step verification process. First, the user confirms their phone number (via SMS code, silent network auth, or other methods). Then, they complete identity verification through a KYC process. From the user's perspective, this feels like a simple onboarding step, enter some information, confirm a code, answer a few questions, and they're verified. Behind the scenes, Opal is orchestrating phone verification, identity matching, and KYC compliance.
  </Card>

  <Card title="Connect" icon="link" href="/opal/connect/overview">
    After verification, the user consents to a soft credit pull, and Opal displays the discovered liability accounts, credit cards, loans, mortgages, and more, in a clear, organized interface. The user can see what was found and proceed to the next step in your flow. This is often the "wow moment" in a debt management product: the user sees their complete liability picture for the first time, surfaced automatically without manual entry.
  </Card>

  <Card title="Card Connect" icon="credit-card" href="/opal/card_connect/overview">
    Handles the specific case where a user needs to verify and connect a particular card for payment flows. This is useful when your product needs to work with a specific card rather than discovering all liabilities.
  </Card>

  <Card title="Account Verification" icon="building-columns" href="/opal/account_verification/overview">
    Confirms ownership of a specific account. This is used when you need to verify that a user controls a particular financial account before enabling certain operations.
  </Card>
</CardGroup>

Each mode can be launched independently depending on where the user is in your flow.

## How Opal Integrates Into Your Flow

<Steps>
  <Step title="Request a session token">
    Your backend requests a session token from Method, scoped to a specific user (Entity) and a specific mode
  </Step>

  <Step title="Load the SDK">
    Your frontend application loads Opal using one of Method's client SDKs (available for web, React, and React Native)
  </Step>

  <Step title="User interacts with Opal">
    The user interacts with Opal directly, filling in information, confirming codes, reviewing discovered accounts
  </Step>

  <Step title="Receive webhook events">
    Your backend listens for webhook events that signal progress and completion, triggering whatever comes next in your application flow
  </Step>
</Steps>

Sessions are persistent, meaning users can leave and return without losing progress. This is particularly important for mobile users who may be interrupted by notifications, phone calls, or simply needing to come back later.

## Customization and Branding

Opal is designed to feel like a native part of your application, not a third-party widget. Customization options include:

* Brand colors and accent colors
* Typography and font choices
* Logo placement and branding elements
* Light/dark mode support

The goal is that your users never feel like they've been handed off to a different product. Refer to the [Opal documentation](/opal/overview) for the full range of theming options and accessibility compliance details.

## When to Consider API-Only

Opal covers the vast majority of integration scenarios, but there are cases where building directly against Method's APIs may be a better fit:

* Your product has an existing onboarding flow that users are already familiar with, and you need the verification steps to feel native to that flow's design language
* Your compliance or security requirements demand that PII collection happens entirely within your own infrastructure
* You need fine-grained control over the verification step ordering or conditional logic that Opal's session model doesn't support

If you're unsure, start with Opal. You can always migrate specific steps to API-only later without rebuilding everything.

<Warning>
  Elements was Method's previous embedded UI, deprecated on December 31, 2025. All new integrations should use Opal. If your team is still using Elements, plan your migration using the [Opal migration guide](/opal/migration_guide).
</Warning>

## What's Next

<CardGroup>
  <Card title="Opal Quickstart" icon="rocket" href="/opal/quickstart">
    Get Opal running in your application in minutes.
  </Card>

  <Card title="Opal Libraries" icon="book" href="/opal/libraries">
    SDK installation and setup for web, React, and React Native.
  </Card>

  <Card title="Opal Sessions" icon="key" href="/opal/sessions">
    Session management, token creation, and lifecycle.
  </Card>

  <Card title="Opal Events" icon="bell" href="/opal/events">
    Event handling and completion callbacks.
  </Card>

  <Card title="Opal API Reference" icon="code" href="/reference/opal/overview">
    Token creation, session management, and event types.
  </Card>
</CardGroup>


# What is Method
Source: https://docs.methodfi.com/guides/overview

Method is the infrastructure layer for consumer liability data and payments.

In a financial ecosystem where liability information is fragmented across thousands of institutions, reported inconsistently, and often weeks out of date, Method provides a single, unified platform that brings structure and reliability to this fragmented landscape.

<Note>
  These Guides cover concepts and product decisions. For implementation details and code, see the [API Reference](/reference/introduction).
</Note>

## How Method Works

Unlike aggregators that require users to share their bank login credentials, Method uses a fundamentally different approach. When a user verifies their identity, Method performs a soft credit pull (no impact to the user's credit score) to automatically discover all of their liabilities, without any manual account entry or credential sharing.

Once accounts are discovered, Method can retrieve real-time data directly from financial institutions for supported accounts, giving you current balances, due dates, interest rates, and payment amounts. For accounts where direct connections aren't available, Method falls back to credit report data as a reliable baseline.

This two-source model, credit report discovery paired with direct institutional access, means your product gets both breadth (visibility into virtually every liability) and depth (real-time data where it matters most).

## What Method Does

<CardGroup>
  <Card title="Discover and connect consumer liabilities at scale" icon="magnifying-glass">
    Method connects to 15,000+ financial institutions, from major banks to regional lenders. When a user links their identity, you gain visibility into their full liability picture — credit cards, auto loans, student loans, mortgages, personal loans, and more.
  </Card>

  <Card title="Keep liability data fresh and normalized" icon="arrows-rotate">
    Liability data arrives from institutions in inconsistent formats and update cycles. Method standardizes balances, due dates, interest rates, payment amounts, and limits into a clean, consistent data model accessible through a single API.
  </Card>

  <Card title="Move money to pay down debts" icon="money-bill-transfer">
    Method enables payments directly to connected liability accounts. Initiate paydowns from a verified funding source while Method handles submission, processing, delivery to the creditor, and confirmation.
  </Card>

  <Card title="Monitor changes over time for your users" icon="bell">
    Financial accounts constantly change — balances update, payments post, and accounts open or close. Method's subscription system keeps your application synced with these updates through near-real-time notifications.
  </Card>
</CardGroup>

## Who Method Is Built For

### Commerce

Commerce and card-linked platforms that need to connect to consumers' card accounts for transaction data, card-on-file verification, or payment instrument provisioning to power checkout, rewards, and card-linked offer experiences.

<CardGroup>
  <Card title="Wallet Onboarding" icon="wallet" href="/guides/use-cases/commerce/wallet-onboarding">
    Connect every credit card a customer owns in a single flow, then enrich and tokenize for checkout.
  </Card>

  <Card title="Preauth Signals" icon="signal" href="/guides/use-cases/commerce/preauth-signals">
    Evaluate payment readiness before authorization and retry failed payments at the optimal time.
  </Card>
</CardGroup>

### Lending

Lenders and underwriters that need verified, up-to-date liability data to make credit decisions, calculate debt-to-income ratios, verify existing obligations, and enable debt consolidation through structured plans, lump-sum payments, or automated recurring transfers.

<CardGroup>
  <Card title="Application & Qualification" icon="clipboard-check" href="/guides/use-cases/lending/application-prefill">
    Pre-fill loan applications with verified liability data and assess risk with credit health attributes.
  </Card>

  <Card title="Debt Consolidation" icon="money-bill-transfer" href="/guides/use-cases/lending/debt-consolidation">
    Discover eligible accounts, verify current balances, and disburse funds directly to creditors.
  </Card>

  <Card title="Portfolio Intelligence" icon="chart-line" href="/guides/use-cases/lending/portfolio-monitoring">
    Monitor borrower liability, utilization, and delinquency signals continuously after origination.
  </Card>
</CardGroup>

### Personal Finance & Financial Wellness

Personal finance and financial wellness applications that want to give users a comprehensive view of their liabilities alongside their assets, track progress over time, and provide actionable insights about credit health.

<CardGroup>
  <Card title="Onboarding & Discovery" icon="magnifying-glass" href="/guides/use-cases/pfm/onboarding-discovery">
    Identity verification options, liability discovery via Connect, and vehicle enrichment for auto loans.
  </Card>

  <Card title="Dashboard & Insights" icon="chart-mixed" href="/guides/use-cases/pfm/monitoring-insights">
    Build real-time debt dashboards with account updates, card brand art, credit scores, and financial health attributes.
  </Card>

  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Stream credit card transactions for spend management and initiate bill payments to your users' creditors.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/guides/quickstart">
    Most integrations follow this four-step pattern, though the exact flow may vary depending on your product and use case.
  </Card>

  <Card title="Core Concepts" icon="diagram-project" href="/guides/concepts">
    Understand Method's object model and how everything connects.
  </Card>

  <Card title="Opal" icon="window" href="/guides/opal">
    Drop-in embedded UI that handles identity verification, account discovery, and more — get to value in days, not weeks.
  </Card>

  <Card title="API Reference" icon="code" href="/reference/introduction">
    Dive into the full API documentation.
  </Card>
</CardGroup>


# Payment Errors and Constraints
Source: https://docs.methodfi.com/guides/payments/errors

Processing windows, posting timing, return codes, and idempotency.

## Payment Errors and Constraints

* Payments submitted outside of processing windows will be held until the next window.
* Posting timing depends on the creditor and is outside Method's control.
* Return codes may be provided when a payment fails or is returned.
* Duplicate payments can be prevented using [idempotency keys](/reference/idempotency).


# Payment Instruments
Source: https://docs.methodfi.com/guides/payments/instruments

Reusable payment configurations for recurring and repeated payments.

## Payment Instruments — Reusable Payment Configurations

For products that involve recurring or repeated payments (e.g., a monthly debt paydown plan), Payment Instruments provide a convenience layer. Instead of collecting and submitting payment details for every transaction, you create a Payment Instrument once, capturing the card credentials, ACH details, or network token, and reference it for subsequent payments.

Think of a Payment Instrument as a saved payment method. The user sets it up once, and your product can initiate payments against it repeatedly without re-collecting credentials. Instruments remain valid until explicitly closed or the underlying account changes.

Method supports three types of Payment Instruments:

| Type                 | Description                                                         |
| -------------------- | ------------------------------------------------------------------- |
| **Card**             | Card credentials for payment                                        |
| **Inbound ACH/Wire** | Routing and account details for ACH or wire payments to a liability |
| **Network Token**    | Tokenized card credentials for secure, network-level transactions   |

<Note>
  Not all accounts support all instrument types, check the account's available products before attempting to create an instrument. And listen for webhook events about instrument status changes, as instruments may become invalid if the underlying account is closed or credentials expire.
</Note>

For the full Payments API, see the [Payments reference](/reference/payments/overview). For Payment Instruments, see the [Payment Instruments reference](/reference/accounts/payment-instruments/overview).


# Payment Lifecycle
Source: https://docs.methodfi.com/guides/payments/lifecycle

What your users should see as payments move through the system.

## Payment Lifecycle — What Your Users Should See

Every payment moves through a defined lifecycle, and each stage should map to a clear user-facing status in your product:

| Method Status           | User-Facing Copy                        | Description                                                                 |
| ----------------------- | --------------------------------------- | --------------------------------------------------------------------------- |
| **Pending**             | "Payment scheduled" or "Payment queued" | The payment has been created and is waiting for the next processing window. |
| **Canceled**            | "Payment canceled"                      | The payment was canceled before it was processed.                           |
| **Processing**          | "Payment in progress"                   | The payment is actively being processed through the banking system.         |
| **Sent**                | "Payment sent to your creditor"         | Funds have been initiated and sent to the creditor.                         |
| **Posted**              | "Payment complete"                      | The creditor has confirmed the payment has been applied to the account.     |
| **Failed**              | "Payment couldn't be processed"         | An error occurred — see failure details.                                    |
| **Reversal Processing** | "Reversal in progress"                  | A reversal has been approved and is being processed.                        |
| **Reversed**            | "Payment returned"                      | A previously sent payment was returned.                                     |

Design your product to show clear status transitions as webhook events arrive. Users should feel confident that their money is moving and that the system is working, ambiguity about payment status is one of the fastest ways to erode trust.

### Handling Reversals and Failures

Payments can fail or be reversed, and your product should be able to handle these scenarios gracefully:

**Failed Payments**

Failed payments can occur at various stages due to insufficient funds in the funding account, invalid or closed account details, or creditor rejection. When a payment fails, Method emits a webhook event with the failure details. Your product should notify the user clearly, explain what happened in plain language, and provide a path to retry if applicable.

**Reversed Payments**

Reversals occur when a payment that was already sent is returned, for example, if the funding account has insufficient funds after the payment was initiated, or if the creditor returns the payment for any reason. Reversals are tracked as separate objects with their own lifecycle and webhook events. Your product should notify the user, explain the reversal, and update any progress displays that reflected the original payment.

<Warning>
  In both cases, avoid technical jargon. Users don't need to know about ACH return codes or processing windows, they need to know what happened, why, and what to do next.
</Warning>

### Settlement Timing

Settlement and posting timing varies by creditor and payment rail. Do not make hard assumptions about when a payment will post.


# Payments
Source: https://docs.methodfi.com/guides/payments/overview

How Method moves money to pay down debt.

## Payments — Moving Money to Pay Down Debt

### What Payments Enable

Payments are where Method's platform closes the loop from data to action. After discovering a user's liabilities and retrieving their current account data, Payments enable your application to actually move money — initiating paydowns from your platform's corporate funding account to your users' creditors.

This is the capability that transforms Method from a data platform into a complete debt management infrastructure. Without Payments, you can show users what they owe. With Payments, you can help them do something about it.

### What's Required Before a Payment Can Be Made

<Steps>
  <Step title="A verified Entity">
    The user must have completed [identity verification](/guides/identity-verification/overview). This is a non-negotiable compliance and fraud prevention requirement.
  </Step>

  <Step title="A destination liability account">
    The credit card, loan, or other debt being paid down, typically discovered through [Connect](/guides/connect/overview). This is where the money goes.
  </Step>

  <Step title="A verified funding source">
    Your platform's corporate bank account (checking or savings), linked via ACH and [verified](/guides/accounts/funding) through micro-deposits, Plaid, MX, or Teller. This is where the money comes from.
  </Step>

  <Step title="Webhook handling">
    Because payment processing is asynchronous (it takes time for money to move through the banking system), your application must listen for [webhook](/guides/platform-fundamentals#real-time-notifications-via-webhooks) notifications to track the payment's progress through its lifecycle.
  </Step>
</Steps>

### Payment Processing and Timing

Method supports electronic push payments to liability accounts. When a payment is submitted, funds are initiated from your platform's verified funding account and delivered to the creditor.

Processing typically takes 2–3 business days, though the exact timing varies by institution. Payments are processed in defined windows throughout the business day, so the time you submit a payment relative to the next processing window affects when it begins moving. Payments submitted outside of processing windows are held until the next window.

Settlement and posting times are ultimately controlled by the receiving creditor, not by Method. Some creditors apply payments same-day upon receipt; others may take additional time. This means your product should set user expectations appropriately: "Your payment has been sent and will be applied by your creditor, typically within a few business days." Avoid making hard promises about exact posting dates.


# Platform Fundamentals
Source: https://docs.methodfi.com/guides/platform-fundamentals

Environments, authentication, data flow patterns, and webhooks.

## Environments

Method provides three isolated environments, each serving a distinct purpose in your integration lifecycle:

<CardGroup>
  <Card title="Development" icon="wrench">
    Mocked responses. No real institutions contacted, no payments processed.
  </Card>

  <Card title="Sandbox" icon="flask-vial">
    Simulated flows with test data. Mimics real account discovery, payment timelines, and error states.
  </Card>

  <Card title="Production" icon="rocket">
    Live environment. Real institutions, real data, real money.
  </Card>
</CardGroup>

<Warning>
  Each environment uses separate API credentials and data does not cross environments. This allows you to test safely in Development and Sandbox without affecting Production users or data.
</Warning>

## Authentication and API Keys

Method uses API keys for authentication. Include your key in the `Authorization` header of every request. Each environment under each team has its own unique API key.

```bash theme={null}
curl https://production.methodfi.com/entities \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Method-Version: 2026-03-30"
```

The `Method-Version` header pins your requests to a specific API version, ensuring your integration behaves consistently even as Method's API evolves. When a new version is released, you can migrate on your own timeline. If the header is omitted, your team's default version is used. See [Versioning](/reference/versioning) in the API Reference for details.

See the [Authentication](/reference/authentication) reference for details.

## How Data Flows: On-Demand vs Subscriptions

Method offers two complementary models for accessing data, and understanding when to use each is important for designing your product experience.

<Tabs>
  <Tab title="On-Demand">
    On-demand access means you request data when you need it. For example, when a user opens their dashboard, you might request a fresh balance update for their accounts at that moment. On-demand is best for user-initiated actions, one-time data pulls, or situations where you need specific data at a specific time.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates \
      -X POST \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Method-Version: 2026-03-30" \
      -H "Content-Type: application/json" \
      -d '{"type": "direct"}'
    ```
  </Tab>

  <Tab title="Subscriptions">
    Subscription-based access means Method continuously monitors for changes and delivers new data to you automatically. For example, you might subscribe to balance updates for all of a user's accounts, and Method will notify you whenever new data is available, whether that's daily, weekly, or whenever the financial institution reports. Subscriptions are best for keeping dashboards current, triggering automated workflows, and monitoring for changes without requiring user action.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions \
      -X POST \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Method-Version: 2026-03-30" \
      -H "Content-Type: application/json" \
      -d '{"enroll": "update"}'
    ```
  </Tab>
</Tabs>

<Note>
  Not all products support both modes. Refer to each product's documentation for availability.
</Note>

## Real-Time Notifications via Webhook Events

Method's platform is fundamentally asynchronous, when you request an account update or initiate a payment, the result isn't always available immediately. Instead, Method notifies your system when something happens through webhook events: real-time HTTP notifications sent to an endpoint you configure.

For your product team, the key implication is this: your application should be designed around event-driven updates rather than polling or refresh buttons. When a payment posts, when new account data is available, when a user's credit score changes, Method tells you. This event-driven model enables responsive, real-time user experiences without the complexity and cost of constant polling.

The typical webhook handling pattern looks like this:

1. Method sends an HTTP POST to your configured endpoint with event details
2. Your backend acknowledges receipt (return a 2xx response promptly)
3. Your backend fetches the updated resource using the IDs in the event payload
4. Your application updates its local state and, if needed, refreshes the user's UI

This pattern applies to virtually every webhook: payment status changes, new account data, completed discovery, credit score updates, and more.

<Warning>
  Return your 2xx response before processing the event. If your endpoint takes too long to respond, Method will retry the delivery, which can cause duplicate processing. Deduplicate deliveries using the `method-webhook-delivery-id` request header and make your processing idempotent; see [Handling duplicate deliveries](/reference/webhooks/overview#handling-duplicate-deliveries).
</Warning>

Nearly every product creates and updates events, so webhooks are the primary mechanism for keeping your system in sync with Method.

Common webhook events include:

| Event                 | Description                             |
| --------------------- | --------------------------------------- |
| `payment.update`      | A payment's status has changed          |
| `account.create`      | A new account was discovered or created |
| `connect.completed`   | Account discovery finished              |
| `update.completed`    | Fresh account data is available         |
| `credit_score.update` | A credit score has changed              |

See the [Webhooks](/reference/webhooks/overview) reference for setup instructions and the [Events](/reference/events/overview) reference for the full list of event types.

## Reliability and Safety

Method's platform includes built-in mechanisms to ensure reliability. Your engineering team will handle implementation details, but at a product level the key guarantees are:

* **Idempotency keys:** Duplicate operations are prevented automatically (so a network hiccup doesn't create two payments). See [Idempotency](/reference/idempotency).
* **Rate limits:** Requests are rate-limited to maintain platform stability, and operations can be safely retried without unintended side effects. See [Rate Limiting](/reference/rate-limiting) in the API Reference for details.
* **Versioned APIs:** Method maintains versioned APIs so integrations remain stable as the platform evolves. New capabilities are introduced without breaking existing implementations.
* **Paginated list endpoints:** All list endpoints return paginated results, ensuring predictable performance regardless of data volume. See [Pagination](/reference/pagination) in the API Reference for details.
* **Reliable updates:** Changes to liabilities and payments are delivered through subscriptions and webhooks, ensuring your application stays in sync with real account activity.

These aren't features you need to design around, they're guardrails Method provides out of the box.

<CardGroup>
  <Card title="Authentication Reference" icon="key" href="/reference/authentication">
    API keys, headers, and request setup.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.methodfi.com/guides/quickstart

Get up and running with Method's four-step integration process.

Getting up and running with Method follows a predictable path, whether you're building a debt repayment app, a financial wellness dashboard, or an embedded lending experience.

## The Four-Step Integration Process

Most integrations follow the same high-level pattern, regardless of your specific use case:

<Steps>
  <Step title="Represent your user">
    Every end user in your application maps to an [Entity](/guides/entities/overview) in Method. This is the foundational object that everything else, verification, accounts, payments, attaches to. You provide basic identifying information (name, phone number, and optionally additional PII), and Method creates a persistent identity that follows the user throughout their lifecycle in your product.
  </Step>

  <Step title="Verify their identity">
    Before Method can discover a user's accounts or process payments on their behalf, the user must complete [identity verification](/guides/identity-verification/overview). This is a two-part process: first confirming they control their phone number, then verifying their identity through a KYC process.

    Method supports multiple verification approaches (SMS, silent network auth, KBA, and BYO options). Method will partner with your team to help determine which methods are best suited for your use case and user demographics.
  </Step>

  <Step title="Discover their accounts">
    Once verified, Method can discover the user's financial liabilities using a soft-pull credit report (no impact to their credit score). This is the moment where your product goes from knowing who a user is to knowing what they owe — and to whom. [Accounts](/guides/accounts/overview) are automatically created in Method as they're discovered, giving you immediate access to liability data across credit cards, loans, mortgages, and more.

    Each discovered account comes with the data reported to the credit bureau, including balance, credit limit, payment status, account type, and the financial institution that holds the account. From there, you can request real-time [Updates](/guides/updates/overview) to get current balances, due dates, minimum payments, interest rates, and more directly from the institution.
  </Step>

  <Step title="Take action">
    With accounts connected, you can now do the things that make your product valuable: pull fresh balance and payment data ([Updates](/guides/updates/overview)), initiate paydowns and bill pay ([Payments](/guides/payments/overview)), monitor for changes over time, and present your users with a clear, actionable picture of their financial obligations.

    Updates return structured, normalized fields — balances, due dates, minimum payments, interest rates, credit limits, and more — in a consistent format regardless of the underlying financial institution.
  </Step>
</Steps>

## Choosing Your Integration Approach

Method offers two primary integration approaches, and understanding the tradeoff early saves significant time:

<Tabs>
  <Tab title="Opal (Embedded UI)">
    **Best for most teams.** [Opal](/guides/opal) is Method's pre-built, white-labeled UI that handles identity verification, account discovery, and more. It's designed to drop into your application with minimal frontend work while providing a polished, tested user experience.

    *Choose Opal if you want to move fast, minimize custom UI development, and leverage Method's UX expertise. Most teams start here.*
  </Tab>

  <Tab title="API-Only">
    **Best for teams with specific UX requirements.** If you have an existing in-app flow, a highly customized user experience, or specific design requirements that Opal can't accommodate, you can integrate directly with Method's APIs.

    *This gives you complete control over the user experience but requires more frontend development and ongoing maintenance.*
  </Tab>
</Tabs>

## Example Integration Paths

To make the integration journey concrete, here are three common paths mapped to real product scenarios:

<AccordionGroup>
  <Accordion title="Debt Discovery (e.g., a financial wellness dashboard)">
    Your user signs up → you create an Entity and verify their identity → Method discovers all their liabilities → you display a comprehensive debt overview with balances, interest rates, and payment schedules → you subscribe to updates to keep the dashboard current.

    *Timeline to first value: the user sees their complete debt picture within minutes of completing verification.*
  </Accordion>

  <Accordion title="Debt Paydown (e.g., a debt repayment lender)">
    Your user signs up → identity verification → account discovery → you link your corporate account as a funding source → your user flow presents a paydown strategy → payments are initiated through Method → you track each payment from submission to posting and update the user's progress.

    *This is the full end-to-end loop that turns data into action.*
  </Accordion>

  <Accordion title="Ongoing Monitoring (e.g., a credit health tool)">
    Your user completes the initial setup → you subscribe to account updates and credit score monitoring → Method notifies you when balances change, payments post, credit scores shift, or new accounts appear → your app surfaces these changes as alerts, insights, or progress updates.

    *The user gets continuous value without ever repeating the setup process.*
  </Accordion>

  <Accordion title="Card Linking (e.g., a card-linked offers platform)">
    Your user signs up → you create an Entity and verify their identity → Method discovers their credit card accounts → you retrieve card brand details (card art, product name) and tokenize card credentials via Payment Instruments → your platform uses these tokens for checkout, rewards enrollment, or transaction monitoring.

    *This flow connects your product to the user's existing cards without manual entry or credential sharing.*
  </Accordion>
</AccordionGroup>

## What's Next

<CardGroup>
  <Card title="Platform Fundamentals" icon="gear" href="/guides/platform-fundamentals">
    Environments, authentication, webhooks, and data flow patterns.
  </Card>

  <Card title="Core Concepts" icon="diagram-project" href="/guides/concepts">
    Understand Method's object model and dependency chain.
  </Card>

  <Card title="Opal" icon="window" href="/guides/opal">
    Drop-in embedded UI for identity verification and account discovery.
  </Card>

  <Card title="API Reference" icon="code" href="/reference/introduction">
    Dive into the full API documentation.
  </Card>
</CardGroup>


# Billing Lifecycle and Data Availability
Source: https://docs.methodfi.com/guides/updates/billing-lifecycle

How a cardholder's billing stage determines which fields come back in an Update.

## Billing Lifecycle and Data Availability

Financial institutions determine which data fields are returned for Updates based on the cardholder's billing lifecycle stage. The four common cardholder states:

* **Bill Created**: A new statement has been generated. All billing fields are available.
* **Bill Due**: A payment is owed. Balance, minimum payment, and due date are present, but no last payment information has been reported yet.
* **Bill Paid**: A payment has been made. Last payment amount and date are available, but the next due date has not yet been generated.
* **Dormant**: The account is open but shows minimal activity. Typically only balance (and sometimes available credit) is returned.

| Field                          | Created | Due | Paid | Dormant |
| ------------------------------ | :-----: | :-: | :--: | :-----: |
| available\_credit              |    ✓    |  ✓  |   ✓  |    ✓    |
| balance                        |    ✓    |  ✓  |   ✓  |    ✓    |
| last\_payment\_amount          |    ✓    |     |   ✓  |         |
| last\_payment\_date            |    ✓    |     |   ✓  |         |
| next\_payment\_minimum\_amount |    ✓    |  ✓  |   ✓  |         |
| next\_payment\_due\_date       |    ✓    |  ✓  |      |         |

*Approximate distribution across states: Bill Created 28%, Bill Due 10%, Bill Paid 31%, Dormant 10%, Other 20%.*

The distribution across these states varies significantly by issuer. Each financial institution presents data differently, resulting in different extraction profiles.


# Handling Update Failures
Source: https://docs.methodfi.com/guides/updates/failures

Recommended patterns for handling stale data and failed refreshes.

## Common Failure Modes

Direct Updates can fail for several reasons. In the Update response, direct retrieval failures currently surface through a canonical `error` object:

| Failure Mode                                           | Where it surfaces                                                                      | Recommended Action                                                                                          |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Institution unreachable or temporarily unavailable     | Update `error.code: 21001`; account `data_status_error` is usually `15004` or `15006`. | Retry after a delay. These are usually transient.                                                           |
| Account not supported                                  | Account `data_status_error: 15009`.                                                    | Check the account's `products` array, then rely on snapshot Updates from an `update.snapshot` subscription. |
| Account closed, paid off, transferred, or consolidated | Account `data_status_error` is `15001`, `15002`, `15003`, or `15010`.                  | Update your local records. Re-discover via Connect when appropriate.                                        |
| Authentication or account detail mismatch              | Account `data_status_error` is `15005` or `15007`.                                     | Refresh identity or account details, then re-enroll or re-discover the account.                             |
| Delinquent or disabled liability                       | Account `data_status_error` is `15008` or `15011`.                                     | Surface the state to the user or contact support if unexpected.                                             |

```json theme={null}
{
  "id": "upt_NYV5kfjskTTCJ",
  "status": "failed",
  "error": {
    "type": "UPDATE_FAILED",
    "sub_type": "UPDATE_TEMPORARILY_UNAVAILABLE",
    "code": 21001,
    "message": "Update is temporarily unavailable for this account."
  }
}
```

For the granular reason, read the underlying account liability's `data_status_error`. These are the codes exposed by the API:

| Code    | Reason                     | What it means                                                                                                                                                | Recommended action                                                        |
| ------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `15001` | Closed                     | The account has been closed at the institution.                                                                                                              | Update your local records. Don't retry.                                   |
| `15002` | Paid in full               | The liability has been paid off.                                                                                                                             | Update your local records. Don't retry.                                   |
| `15003` | No longer serviced         | The institution no longer services this account (e.g. transferred or sold).                                                                                  | Update your local records. Don't retry.                                   |
| `15004` | Unauthorized / sync failed | Catch-all for transient and connection-level failures (institution timeouts, technical issues, outside-hours, internal errors, repeated failure throttling). | Retry after a delay. If persistent, contact support.                      |
| `15005` | Invalid holder details     | The institution rejected the holder details Method has on file (e.g., DOB, postal code, KYC).                                                                | Refresh the entity's identity data and re-enroll.                         |
| `15006` | Temporarily unavailable    | Generic temporary failure.                                                                                                                                   | Retry after a delay.                                                      |
| `15007` | Invalid account number     | The account number Method has is no longer valid at the institution.                                                                                         | Re-discover the account via Connect.                                      |
| `15008` | Delinquent                 | The account is in a delinquent state at the institution.                                                                                                     | Surface this to the user. Don't retry until resolved.                     |
| `15009` | Unsupported merchant       | The institution doesn't support real-time data connections for this account type.                                                                            | Rely on snapshot Updates delivered via an `update.snapshot` subscription. |
| `15010` | Consolidated loan          | The student loan has been consolidated into a different loan.                                                                                                | Re-discover via Connect.                                                  |
| `15011` | Liability disabled         | Updates have been disabled for this liability.                                                                                                               | Don't retry. Contact support if unexpected.                               |

<Note>
  Rate limiting is not currently exposed as a distinct Update failure code. Repeated failure throttling may appear under the catch-all sync failed reason (`15004`).
</Note>

## Retry Strategy

```
1. First retry: wait 5 minutes
2. Second retry: wait 30 minutes
3. Third retry: wait 2 hours
4. After 3 failures: display the most recent snapshot data and alert your CSM
```

Use [idempotency keys](/reference/idempotency) when retrying to avoid duplicate requests.

## Fallback Pattern: Direct to Snapshot

When direct Updates aren't available or keep failing, snapshot data provides a reliable baseline. Note that `POST /accounts/{acc_id}/updates` always creates a direct Update; you cannot request a snapshot Update on demand. Snapshot Updates are produced by `update.snapshot` [subscriptions](/guides/updates/subscriptions) and delivered via webhook.

To fall back to snapshot data, list the account's existing Updates and use the most recent one whose `source` is `snapshot`:

```bash theme={null}
curl "https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates?source=snapshot" \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

If no snapshot Update exists yet, create an `update.snapshot` subscription so future bureau refreshes are delivered automatically:

```bash theme={null}
curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{"enroll": "update.snapshot"}'
```

## UX Recommendations

* **Always show the most recent known data**, even if it's stale. A balance from last week is better than a blank screen.
* **Indicate freshness.** Show the `data_as_of` timestamp so users know how current the data is: "Balance as of March 20, 2024."
* **Show refresh state.** When an Update is in progress, show a loading indicator alongside the existing data.
* **Don't block on failures.** If a direct Update fails, display the last snapshot data and retry in the background.

## Subscription Failures

For failed subscription executions, Method requeues the subscription execution for retry. The subscription queue retries failed executions daily up to three times, then schedules the next run according to the subscription's normal cadence.

Monitor `update.update` webhooks for failed Updates to detect persistent issues with specific accounts or institutions and to drive your own fallback (e.g., showing snapshot data, prompting the user to reconnect for `15005`/`15007`).

## Fields by Liability Type

The data returned in an Update depends on the account type. Common patterns:

| Liability Type | Key Fields                                                                                          |
| -------------- | --------------------------------------------------------------------------------------------------- |
| Credit Card    | balance, available\_credit, credit\_limit, interest\_rate (min/max/type), payment info, opened\_at  |
| Auto Loan      | balance, interest\_rate, original\_loan\_amount, term\_length, expected\_payoff\_date, payment info |
| Student Loan   | balance, original\_loan\_amount, term\_length, payment info                                         |
| Mortgage       | balance, interest\_rate, original\_loan\_amount, term\_length, expected\_payoff\_date, payment info |
| Personal Loan  | balance, available\_credit, interest\_rate, original\_loan\_amount, term\_length, payment info      |

All types share: `balance`, `last_payment_amount`, `last_payment_date`, `next_payment_due_date`, `next_payment_minimum_amount`, `opened_at`, `closed_at`.

For the full Updates API, see the [Updates reference](/reference/accounts/updates/overview).


# Update Lifecycle
Source: https://docs.methodfi.com/guides/updates/lifecycle

The stages of an Update request and how to track them.

## Update Lifecycle

### Status Transitions

```
Created -> Processing -> Completed -> Failed
```

| Status       | Description                                                                      | What to do                                                                                      |
| ------------ | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `pending`    | Request submitted, queued for processing.                                        | Wait for webhook or poll.                                                                       |
| `processing` | Method is actively retrieving data from the source.                              | Wait. Direct Updates typically complete within seconds to minutes depending on the institution. |
| `completed`  | Data is available. The liability-type object (e.g., `credit_card`) is populated. | Read the data, update your local store, display to user.                                        |
| `failed`     | Retrieval was unsuccessful. The `error` object is populated with details.        | See [Handling Failures](/guides/updates/failures).                                              |

### Timing Expectations

* **Snapshot Updates:** Return synchronously in the POST response. No lifecycle to track. The response is immediately `completed` (or `failed`).
* **Direct Updates:** Asynchronous. Typical completion time varies by institution. Most complete within seconds, some may take up to a few minutes. Design your UI to show a loading state and handle the webhook.

### Webhook Events

| Event           | When it fires                                                                                 |
| --------------- | --------------------------------------------------------------------------------------------- |
| `update.create` | An Update has been created (status: `pending`).                                               |
| `update.update` | An Update's status has changed (typically `pending` to `completed` or `pending` to `failed`). |

Subscribe to `update.update` to react when data is ready. The webhook payload includes the path to retrieve the full Update object.

### Idempotency

If you need to retry a failed Update, use [idempotency keys](/reference/idempotency) to avoid creating duplicate requests.


# Updates
Source: https://docs.methodfi.com/guides/updates/overview

How Method keeps account data fresh, snapshot vs direct sources.

## Keeping Account Data Fresh and Accurate

### What an Update Is

An Update is the mechanism through which Method delivers the latest state of a connected account: current balance, payment due date, minimum payment amount, interest rate, credit limit, and other relevant fields depending on the account type. If [Connect](/guides/connect/overview) is how you discover accounts, Updates are how you keep those accounts' data current over time.

The freshness and accuracy of your account data directly impacts the quality of your product experience. A debt repayment app that shows last month's balance feels broken. A payment scheduler that uses stale due dates risks missed payments. Updates are how you ensure your product reflects financial reality, not an outdated snapshot.

### Two Sources of Truth: Snapshot vs. Direct

Updates come from two fundamentally different data sources, and choosing between them is an important product decision:

## Checking Update Availability

Before requesting an Update, check the account's `products` array:

* `update` in `products` means direct Updates are available (real-time data from the institution).

If `update` is in `restricted_products` instead of `products`, direct Updates require additional steps (e.g., account verification). If `update` does not appear, data retrieval isn't currently available for this account.

<Tabs>
  <Tab title="Snapshot">
    Pull data from the user's credit report. Credit reports are compiled by the major bureaus and updated when creditors submit their reporting data, typically on a monthly cycle. Snapshot data is available for the broadest range of accounts, but it's only as fresh as the most recent creditor report.

    | Attribute     | Detail                                                                  |
    | ------------- | ----------------------------------------------------------------------- |
    | **Freshness** | Monthly (credit report cycle)                                           |
    | **Delivery**  | Produced by an `update.snapshot` subscription and delivered via webhook |
    | **Coverage**  | Broadest, works for virtually every account                             |

    **Best for:** Building account overview screens, displaying general balance trends, monitoring credit health over time, showing account summaries where approximate data is acceptable, or when you need data for account types where direct connections aren't available. Snapshot Updates are your reliable baseline. They work for virtually every discovered account and provide a good-enough picture for many use cases.

    Snapshot Updates cannot be created on demand. Subscribe to `update.snapshot` so Method delivers a fresh snapshot whenever the bureau reports new data, then retrieve the most recent snapshot from the list endpoint:

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{"enroll": "update.snapshot"}'

    curl "https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates?source=snapshot" \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```
  </Tab>

  <Tab title="Direct">
    Pull data directly from the financial institution in real time. This means the data reflects the account's current state as of the moment the institution responds, including very recent payments, daily interest accrual, and same-day balance changes. Direct Updates are asynchronous (you submit a request and receive the result via webhook when it completes) and take longer, but the data is significantly more current.

    | Attribute     | Detail                                   |
    | ------------- | ---------------------------------------- |
    | **Freshness** | Real-time (as of institution response)   |
    | **Response**  | Async (webhook delivery)                 |
    | **Coverage**  | Narrower, depends on institution support |

    **Best for:** Confirming a balance before initiating a payment, displaying exact payment due dates or minimum payment amounts, current interest rate or APR information, verifying that a recent payment has posted, or when accuracy is critical to your product's core value proposition.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{"type": "direct"}'
    ```
  </Tab>
</Tabs>

<Note>
  Many products use both: snapshot data as the default display, with direct Updates triggered when the user takes an action that requires current data (like preparing to make a payment).
</Note>

## The Update Flow

<Accordion title="On-demand direct Update walkthrough">
  ### On-Demand (Direct) Update

  **Step 1: Request a direct Update**

  ```bash theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{"type": "direct"}'
  ```

  The response returns immediately with `status: pending`:

  ```json theme={null}
  {
    "id": "upt_NYV5kfjskTTCJ",
    "status": "pending",
    "account_id": "acc_yVf3mkzbhz9tj",
    "source": "direct",
    "type": "credit_card",
    "credit_card": null,
    "error": null,
    "created_at": "2024-03-20T04:43:21.434Z",
    "updated_at": "2024-03-20T04:43:21.655Z"
  }
  ```

  ### Step 2: Wait for completion

  Listen for the `update.update` webhook:

  ```json theme={null}
  {
    "type": "update.update",
    "path": "/accounts/acc_yVf3mkzbhz9tj/updates/upt_NYV5kfjskTTCJ"
  }
  ```

  ### Step 3: Retrieve the completed Update

  ```bash theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates/upt_NYV5kfjskTTCJ \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  The completed Update contains the account's current data:

  ```json theme={null}
  {
    "id": "upt_NYV5kfjskTTCJ",
    "status": "completed",
    "account_id": "acc_yVf3mkzbhz9tj",
    "source": "direct",
    "type": "credit_card",
    "data_as_of": "2024-03-20T04:43:21.434Z",
    "credit_card": {
      "available_credit": 120000,
      "balance": 80000,
      "credit_limit": 200000,
      "interest_rate_percentage_max": 23.5,
      "interest_rate_percentage_min": 12.0,
      "interest_rate_type": "variable",
      "last_payment_amount": 5000,
      "last_payment_date": "2024-04-05",
      "next_payment_due_date": "2024-05-01",
      "next_payment_minimum_amount": 4000,
      "opened_at": "2018-10-30"
    },
    "error": null,
    "created_at": "2024-03-20T04:43:21.434Z",
    "updated_at": "2024-03-20T04:43:21.655Z"
  }
  ```
</Accordion>

## Reading the Update Response

The Update response wraps the account data inside a liability-type object. The key fields:

| Field              | Description                                                                                                                                                             |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source`           | `snapshot` or `direct`, which data source this Update used.                                                                                                             |
| `type`             | The liability type: `credit_card`, `auto_loan`, `student_loans`, `mortgage`, `personal_loan`, etc.                                                                      |
| `data_as_of`       | Timestamp of when this data was current. For direct, this is the moment the institution responded. For snapshot, this is when the creditor last reported to the bureau. |
| `[liability_type]` | The data object (e.g., `credit_card`, `auto_loan`). Contains the balance, rates, payment info, and dates specific to that account type.                                 |
| `status`           | `pending`, `processing`, `completed`, or `failed`. See [Update Lifecycle](/guides/updates/lifecycle).                                                                   |
| `error`            | Populated if the Update failed. See [Handling Failures](/guides/updates/failures).                                                                                      |

<Note>
  **All monetary amounts are in cents.** A `balance` of `80000` means \$800.00. A `last_payment_amount` of `5000` means \$50.00.
</Note>

## Next Steps

<CardGroup>
  <Card title="Update Subscriptions" icon="arrows-rotate" href="/guides/updates/subscriptions">
    Set up automatic data refreshes without manual requests.
  </Card>

  <Card title="Update Lifecycle" icon="arrows-spin" href="/guides/updates/lifecycle">
    Understand the stages of an Update request.
  </Card>

  <Card title="Handling Failures" icon="triangle-exclamation" href="/guides/updates/failures">
    Design resilient UX around failed or stale data.
  </Card>

  <Card title="Updates API Reference" icon="code" href="/reference/accounts/updates/overview">
    Full endpoint documentation, fields, and error codes.
  </Card>
</CardGroup>


# Update Subscriptions
Source: https://docs.methodfi.com/guides/updates/subscriptions

Set-and-forget monitoring to keep account data current.

## What Update Subscriptions Do

For products that need to keep data current without requiring users to manually refresh, Update Subscriptions provide a set-and-forget monitoring capability.

* A direct Update subscription tells Method to periodically pull fresh data from the financial institution and deliver it to you via webhook as it becomes available. The refresh cadence depends on the institution and account type.
* A snapshot-only subscription delivers new data whenever the credit report refreshes (typically monthly), ensuring your baseline data stays current without manual intervention.

Subscriptions are essential for: dashboards and account overview screens that should always show reasonably current data, alerting systems that detect changes (missed payments, balance spikes, rate changes), progress tracking features that show debt paydown over time, and any feature where the user expects data to be fresh without taking action.

The combination of on-demand Updates for user-initiated actions and subscription-based Updates for background freshness gives you a complete data strategy.

## Creating a Subscription

You can set up subscriptions either at Connect time (recommended for new accounts) or individually on existing accounts.

### At Connect Time (Recommended)

Include `subscriptions` in your Connect request to automatically subscribe all discovered accounts:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptions": ["update"]
  }'
```

### On an Existing Account

```bash theme={null}
curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{"enroll": "update"}'
```

## Subscription Types

| Type              | What it does                                                                                                                                                     |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `update`          | Periodically pulls real-time data directly from the financial institution and delivers via webhook. Refresh cadence depends on the institution and account type. |
| `update.snapshot` | Delivers new credit report data whenever the bureau refreshes (typically monthly). Lower cost, broader coverage.                                                 |

<Note>
  Check the account's `available_subscriptions` array before creating a subscription. If `update` isn't listed, direct subscriptions aren't available for that account.
</Note>

### Refresh Cadence

<Note>
  The frequency of updates for direct subscriptions depends on the liability type and the individual account. Credit cards generally update more frequently (every 1 to 3 days), while personal loans and mortgages typically refresh every \~30 days, aligning with billing cycles and account activity. Snapshot subscriptions refresh whenever the credit bureau receives updated data from the creditor, usually on a monthly basis.
</Note>

## Receiving Updates via Webhook

When a subscription triggers a refresh, Method sends an `update.create` webhook when the Update is created, followed by an `update.update` webhook when its status changes (typically to `completed` or `failed`):

```json theme={null}
{
  "type": "update.update",
  "path": "/accounts/acc_yVf3mkzbhz9tj/updates/upt_NYV5kfjskTTCJ"
}
```

Retrieve the Update from the path to get the fresh data. Your application should process these webhooks to update its local data store or cache.

## Managing Subscriptions

* **List active subscriptions:** `GET /accounts/{acc_id}/subscriptions`
* **Delete a subscription:** `DELETE /accounts/{acc_id}/subscriptions/{sub_id}`

Subscriptions remain active until explicitly deleted or the account is disabled/closed.

## When to Use Subscriptions vs On-Demand Updates

| Scenario                                      | Approach                          |
| --------------------------------------------- | --------------------------------- |
| Dashboard showing current balances            | Subscription (background refresh) |
| Pre-payment balance confirmation              | On-demand direct Update           |
| Debt paydown progress tracking                | Subscription                      |
| One-time underwriting check                   | On-demand direct Update           |
| Alerting on missed payments or balance spikes | Subscription                      |


# Getting Started
Source: https://docs.methodfi.com/guides/use-cases/commerce/getting-started

Create an entity, verify identity, and connect credit cards — the foundational 3-step flow for every commerce integration.

Every commerce integration begins the same way: represent your customer, verify their identity, and discover their credit cards. This 3-step flow is the shared foundation for [Wallet Onboarding](/guides/use-cases/commerce/wallet-onboarding), [Preauth Signals](/guides/use-cases/commerce/preauth-signals), and [Wallet Intelligence](/guides/use-cases/commerce/wallet-intelligence).

<Steps>
  <Step title="Create an Entity">
    Every end user maps to an [Entity](/guides/entities/overview) in Method. Create one with the user's full name and phone number, and provide additional identity information such as date of birth, email address, or SSN when available to improve match rates. This is the foundational object that verification, card discovery, and all downstream products attach to.

    ```bash theme={null}
    curl https://production.methodfi.com/entities \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "individual",
        "individual": {
          "first_name": "Emily",
          "last_name": "Park",
          "phone": "+13105550789",
          "email": "emily.park@email.com",
          "dob": "1995-11-08"
        },
        "address": {
          "line1": "789 Sunset Blvd",
          "line2": null,
          "city": "Los Angeles",
          "state": "CA",
          "zip": "90028"
        }
      }'
    ```

    ```json theme={null}
    {
      "id": "ent_BzirqpLEm3BW7",
      "type": "individual",
      "individual": {
        "first_name": "Emily",
        "last_name": "Park",
        "phone": "+13105550789",
        "dob": "1995-11-08",
        "email": "emily.park@email.com",
        "ssn_4": null,
        "ssn": null
      },
      "error": null,
      "address": {
        "line1": "789 Sunset Blvd",
        "line2": null,
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90028"
      },
      "status": "incomplete",
      "verification": {
        "identity": {
          "verified": false,
          "matched": false,
          "latest_verification_session": null,
          "methods": [
            "element",
            "kba"
          ]
        },
        "phone": {
          "verified": false,
          "latest_verification_session": null,
          "methods": [
            "sms",
            "sna",
            "byo_sms"
          ]
        }
      },
      "connect": null,
      "credit_score": null,
      "products": [
        "identity"
      ],
      "restricted_products": [
        "connect",
        "credit_score",
        "attribute"
      ],
      "subscriptions": [],
      "available_subscriptions": [
        "connect",
        "credit_score"
      ],
      "restricted_subscriptions": [],
      "metadata": null,
      "created_at": "2025-12-10T14:22:31.024Z",
      "updated_at": "2025-12-10T14:22:31.024Z"
    }
    ```

    The Entity is created in `incomplete` status. Before you can discover Emily's credit cards, you need to verify her identity.
  </Step>

  <Step title="Verify Identity">
    Method requires phone verification before card discovery. Verify the customer's phone number using either **Method OTP** (Method sends and verifies the one-time passcode) or **Bring Your Own OTP** (you verify the phone number yourself and provide the verification result to Method). The example below initiates a Method-sent SMS verification session, which sends a one-time code to Emily's phone number on record.

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/verification_sessions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "sms",
        "sms": {}
      }'
    ```

    ```json theme={null}
    {
      "id": "evf_nKLp7WzQdR4mF",
      "entity_id": "ent_BzirqpLEm3BW7",
      "status": "in_progress",
      "type": "phone",
      "method": "sms",
      "sms": {},
      "error": null,
      "created_at": "2025-12-10T14:23:12.271Z",
      "updated_at": "2025-12-10T14:23:12.271Z"
    }
    ```

    After Emily receives and submits the SMS code, the verification session transitions to `verified`. Once both phone and identity verification are complete, the Entity status updates to `active` and Connect becomes available.

    <Note>
      For a complete overview of all verification methods (SMS, SNA, BYO-SMS, KBA), see the [Identity Verification](/guides/identity-verification/overview) guide.
    </Note>
  </Step>

  <Step title="Connect Credit Cards">
    With verification complete, call Connect to discover Emily's credit cards via a soft-pull credit report. This has no impact on the user's credit score.

    For commerce use cases, the key discovery is **credit cards**: these are the accounts you'll use for wallet onboarding, preauth signals, and wallet intelligence.

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    ```json theme={null}
    {
      "id": "cxn_7hTmRvXkYpN3w",
      "entity_id": "ent_BzirqpLEm3BW7",
      "status": "completed",
      "accounts": [
        "acc_LxwEqNicr66yP",
        "acc_4m9amk4KFiaQX",
        "acc_XtKTpHLGhD9Qn",
        "acc_GAzrD99cUqGEN"
      ],
      "requested_products": [],
      "requested_subscriptions": [],
      "error": null,
      "created_at": "2025-12-10T14:24:45.645Z",
      "updated_at": "2025-12-10T14:24:45.645Z"
    }
    ```

    Method discovered 4 credit card accounts for Emily:

    | Account ID          | Card                            |
    | ------------------- | ------------------------------- |
    | `acc_LxwEqNicr66yP` | Chase Sapphire Preferred (Visa) |
    | `acc_4m9amk4KFiaQX` | Amex Gold (Amex)                |
    | `acc_XtKTpHLGhD9Qn` | Citi Double Cash (Mastercard)   |
    | `acc_GAzrD99cUqGEN` | Capital One Venture X (Visa)    |

    These accounts are now ready for every Commerce use case.
  </Step>
</Steps>

## What's Next

<CardGroup>
  <Card title="Wallet Onboarding" icon="wallet" href="/guides/use-cases/commerce/wallet-onboarding">
    Enrich cards with brand art and retrieve payment credentials to render a complete wallet.
  </Card>

  <Card title="Preauth Signals" icon="signal" href="/guides/use-cases/commerce/preauth-signals">
    Evaluate payment readiness before authorization and optimize payment retries.
  </Card>

  <Card title="Wallet Intelligence" icon="lightbulb" href="/guides/use-cases/commerce/wallet-intelligence">
    Retrieve wallet-level insights to personalize customer experiences.
  </Card>
</CardGroup>


# Commerce
Source: https://docs.methodfi.com/guides/use-cases/commerce/overview

Connect customers' credit cards, reduce failed payments, and personalize customer experiences with Method's Commerce APIs.

## What This Section Covers

Learn how to use Method's Commerce APIs to:

* **Connect every credit card** a customer owns in a single flow.
* **Evaluate payment readiness** before authorizing a transaction.
* **Retry failed payments at the optimal time** to improve recovery.
* **Personalize customer experiences** using wallet intelligence.

Whether you're building a wallet, improving payment success, or personalizing customer experiences, every Commerce integration follows the same core workflow.

```mermaid theme={null}
flowchart TD
    A[Create Entity] --> B[Verify Identity]
    B --> C[Connect Credit Cards]
    C --> D[Wallet Onboarding]
    C --> E[Preauth Signals]
    C --> F[Wallet Intelligence]
    style C fill:#00B29D,color:#fff
```

## Commerce Use Cases

| Use case                                                                  | Core endpoints                                  | Use when you want to                                                                                                           |
| ------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| [**Wallet Onboarding**](/guides/use-cases/commerce/wallet-onboarding)     | Entity-Connect, Card Brand, Payment Instruments | Reduce onboarding friction by letting customers connect all their credit cards in one flow                                     |
| [**Preauth Signals**](/guides/use-cases/commerce/preauth-signals)         | Entity-Connect, Preauth Signals                 | Increase payment success by evaluating payment readiness before authorization and retrying failed payments at the optimal time |
| [**Wallet Intelligence**](/guides/use-cases/commerce/wallet-intelligence) | Entity-Connect, Attributes                      | Personalize offers and product experiences based on customers' credit cards                                                    |

## Two Integration Paths

<Tabs>
  <Tab title="API-Only">
    Integrate directly with Method's APIs for entity creation, identity verification, Connect, and all downstream card operations. You build the user-facing flow and have full control over the UX.

    PCI compliance is not required: by default, tokenization returns network tokens that don't expose raw card credentials.
  </Tab>

  <Tab title="Embedded UI (Opal)">
    Use [Opal Card Connect](/opal/card_connect/overview) as a drop-in UI for identity verification and card discovery. Opal handles the user-facing flow while you use the API for card brand enrichment, payment instruments, and wallet attributes.
  </Tab>
</Tabs>

## Get Started

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="/guides/use-cases/commerce/getting-started">
    The 3-step setup: create an entity, verify identity, and connect credit cards.
  </Card>

  <Card title="Wallet Onboarding" icon="wallet" href="/guides/use-cases/commerce/wallet-onboarding">
    Connect every credit card without manual entry, then enrich and tokenize for checkout.
  </Card>

  <Card title="Preauth Signals" icon="signal" href="/guides/use-cases/commerce/preauth-signals">
    Evaluate payment readiness before authorization and optimize payment retries.
  </Card>

  <Card title="Wallet Intelligence" icon="lightbulb" href="/guides/use-cases/commerce/wallet-intelligence">
    Retrieve wallet-level insights to personalize customer experiences.
  </Card>
</CardGroup>


# Preauth Signals
Source: https://docs.methodfi.com/guides/use-cases/commerce/preauth-signals

Evaluate payment readiness before authorization and retry failed payments at the optimal time.

Evaluate payment readiness before authorization and optimize payment retries. After your customer has connected their credit cards, evaluate each card before attempting a payment. Method returns behavioral signals used to estimate payment readiness and recommends when to retry failed payments.

<Note>
  **Public preview.** Preauth Signals is in public preview. Contact your Method CSM to request access.
</Note>

## Prerequisites

Before using Preauth Signals, complete the [Getting Started](/guides/use-cases/commerce/getting-started) flow:

* Entity created
* Identity verified
* Credit cards connected

## Why Use It?

* **Reduce involuntary churn:** Identify the best time to retry failed payments.
* **Increase authorization rates:** Know a payment's likelihood of success before sending it to the network.

## How It Works

Before attempting a payment, create a Preauth Signals assessment for the card, then retrieve the result to decide whether to authorize now or retry later.

```mermaid theme={null}
flowchart TD
    A["Create Preauth Signals<br/>POST /preauth"] --> B["Retrieve Preauth Signals<br/>GET /preauth/{preauth_id}"]
    B --> C[Authorize now]
    B --> D[Retry later]
    style C fill:#00B29D,color:#fff
```

<Steps>
  <Step title="Create Preauth Signals">
    Create a Preauth Signals assessment with `POST /preauth`. Provide either an authenticated Method `account_id` or a `card` object to identify the payment method. You can also include `purchase` context, such as the transaction amount or merchant category code (MCC), to improve the assessment.

    ```bash theme={null}
    curl https://production.methodfi.com/preauth \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "account_id": "acc_4m9amk4KFiaQX",
        "purchase": {
          "amount": 9999,
          "mcc": "4511"
        }
      }'
    ```
  </Step>

  <Step title="Retrieve Preauth Signals">
    Retrieve the completed assessment with `GET /preauth/{preauth_id}` to determine whether to authorize the payment immediately or retry later.

    ```bash theme={null}
    curl https://production.methodfi.com/preauth/preauth_qV7kRaFm4JNxw \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    ```json theme={null}
    {
      "id": "preauth_qV7kRaFm4JNxw",
      "account_id": "acc_4m9amk4KFiaQX",
      "status": "completed",
      "verified_ownership": "match",
      "card_standing": "open",
      "success_likelihood": 0.87,
      "optimal_retry_date": "2026-06-02",
      "error": null,
      "metadata": null,
      "created_at": "2026-05-28T14:00:00.000Z",
      "updated_at": "2026-05-28T14:00:00.180Z"
    }
    ```

    | Field                | Description                                               |
    | -------------------- | --------------------------------------------------------- |
    | `success_likelihood` | Estimated likelihood that the payment will authorize.     |
    | `optimal_retry_date` | Recommended retry date if the payment does not authorize. |

    Use `success_likelihood` to choose the best card for a payment, and `optimal_retry_date` to schedule retries for failed payments.
  </Step>
</Steps>

## What's Next

<CardGroup>
  <Card title="Wallet Intelligence" icon="lightbulb" href="/guides/use-cases/commerce/wallet-intelligence">
    Retrieve wallet-level insights to personalize customer experiences.
  </Card>

  <Card title="Preauth Signals API Reference" icon="signal" href="/reference/preauth/overview">
    Full API documentation for Preauth Signals.
  </Card>
</CardGroup>


# Wallet Intelligence
Source: https://docs.methodfi.com/guides/use-cases/commerce/wallet-intelligence

Retrieve wallet-level behavioral attributes to power recommendations, segmentation, and personalized product experiences.

Retrieve wallet-level insights to personalize customer experiences. After connecting a customer's credit cards, retrieve wallet-level behavioral attributes to power recommendations, segmentation, and personalized product experiences.

## Prerequisites

Before using Wallet Intelligence, complete the [Getting Started](/guides/use-cases/commerce/getting-started) flow:

* Entity created
* Identity verified
* Credit cards connected

## Why Use It?

* **Reach the right audience:** Identify the customers most likely to benefit from every offer.
* **Power partner offers:** Deliver issuer and partner offers only to eligible customers.
* **Design better experiences:** Understand wallet trends and customer behavior to inform product decisions.
* **Complete customer profiles:** Enrich the customer data you already have.

## How It Works

Retrieve the attributes of the customer's wallet with a single request: `POST /entities/{ent_id}/attributes`. Method returns behavioral attributes computed across every connected credit card in the customer's wallet, including:

* Overall utilization
* Credit card utilization
* Usage patterns
* Payment behavior
* Balance trends

```bash theme={null}
curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/attributes \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

This endpoint is asynchronous. The initial response returns `status: in_progress`. Retrieve the completed attributes by subscribing to the `entity_attribute.create` webhook or polling the [retrieve endpoint](/reference/entities/attributes/retrieve).

Below is an example of a completed response:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "attr_dADraNgLBrhgL",
    "entity_id": "ent_BzirqpLEm3BW7",
    "status": "completed",
    "attributes": {
      "usage_pattern":           { "value": "transactor", "error": null, "metadata": null },
      "credit_card_utilization": { "value": 11.96, "error": null, "metadata": null },
      "overall_utilization":     { "value": 18.4, "error": null, "metadata": null }
    },
    "error": null,
    "created_at": "2026-04-09T17:02:47.910Z",
    "updated_at": "2026-04-09T17:04:35.220Z"
  }
}
```

Each attribute returns `{ value, error }`. When data is insufficient (for example, not enough history for a 60-day delta), `value` is `null` and `error` is populated with details.

Use these attributes to build better experiences, personalize offers, segment customers, and improve targeting.

## What's Next

<CardGroup>
  <Card title="Attributes API Reference" icon="chart-line" href="/reference/entities/attributes/overview">
    Full API documentation for Entity Attributes.
  </Card>

  <Card title="Wallet Onboarding" icon="wallet" href="/guides/use-cases/commerce/wallet-onboarding">
    Connect every credit card without manual entry.
  </Card>
</CardGroup>


# Wallet Onboarding
Source: https://docs.methodfi.com/guides/use-cases/commerce/wallet-onboarding

Connect every credit card a customer owns without manual entry, then enrich and tokenize the cards to render a complete wallet.

Connect every credit card without manual entry. Using a customer's name and phone number, Method discovers the credit cards they own, verifies ownership, and returns the metadata needed to render a complete wallet.

## Why Use It?

* **Faster onboarding:** Connect every credit card in one simple and seamless flow.
* **Frictionless checkout:** Let customers pay instantly with any of their credit cards, with no manual entry.
* **Rewards activation:** Enable customers to connect all their credit cards and start earning rewards across every eligible purchase.
* **Payment resilience:** Keep multiple credit cards on file to automatically recover failed payments and reduce churn.

## How It Works

```mermaid theme={null}
flowchart TD
    A["Create Entity<br/>POST /entities"] --> B["Verify Identity<br/>POST /verification_sessions"]
    B --> C["Discover Credit Cards<br/>POST /connect"]
    C --> D["Enrich Cards<br/>POST /card_brands"]
    D --> E["Retrieve Payment Cards<br/>POST /payment_instruments"]
    E --> F[Complete Wallet]
    style F fill:#00B29D,color:#fff
```

<Steps>
  <Step title="Create an Entity">
    Create an [Entity](/guides/entities/overview) to represent your customer. Include their full name and phone number, and provide additional identity information such as date of birth, email address, or SSN when available to improve match rates.
  </Step>

  <Step title="Verify the Customer's Identity">
    Verify the customer's phone number using either **Method OTP** (Method sends and verifies the one-time passcode) or **Bring Your Own OTP** (you verify the phone number yourself and provide the verification result to Method). See the [Identity Verification](/guides/identity-verification/overview) guide for all supported methods.
  </Step>

  <Step title="Discover the Customer's Credit Cards">
    Call [Connect](/guides/connect/overview) to discover the credit card accounts your customer holds via a soft-pull credit report, with no impact on their credit score.

    <Note>
      Steps 1-3 are the same foundational flow used by every Commerce use case. See [Getting Started](/guides/use-cases/commerce/getting-started) for full request and response examples.
    </Note>
  </Step>

  <Step title="Enrich the Discovered Cards">
    For each account returned by Connect, call [Card Brand](/guides/additional-products/card-brand) to retrieve enriched card metadata, including the issuer, card network, card product, card artwork, and rewards program. Use this metadata to render your customer's wallet with recognizable card visuals.

    Here's a card brand request for Emily's Chase Sapphire Preferred (`acc_LxwEqNicr66yP`):

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_LxwEqNicr66yP/card_brands \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    ```json theme={null}
    {
      "id": "cbrd_Accm7P6t6mYQP",
      "account_id": "acc_LxwEqNicr66yP",
      "brands": [
        {
          "id": "pdt_27_brd_1",
          "card_product_id": "pdt_27",
          "description": "Chase Sapphire Preferred",
          "name": "Chase Sapphire Preferred",
          "issuer": "Chase",
          "network": "visa",
          "network_tier": "signature",
          "type": "specific",
          "url": "https://static.methodfi.com/card_brands/7d2f8a1bc3e5f094a6d831e5c7b29f04.png"
        }
      ],
      "status": "completed",
      "source": "method",
      "error": null,
      "created_at": "2025-12-10T14:30:12.139Z",
      "updated_at": "2025-12-10T14:30:12.139Z"
    }
    ```

    The `brands` array contains the card product details. Use `name` for display, `url` for the card art image, `issuer` for the bank name, and `network` / `network_tier` for routing decisions.

    <Note>
      Card Brand is an asynchronous operation. The response above shows a completed request; in practice, subscribe to the `card_brand.completed` webhook to know when brand data is ready.
    </Note>
  </Step>

  <Step title="Retrieve Available Payment Cards">
    For each account returned by Connect, create a [Payment Instrument](/reference/accounts/payment-instruments/overview) to retrieve the card credentials required for checkout.

    Request a `network_token` Payment Instrument to receive a network-provisioned token instead of the raw card number. No raw card credentials are exposed to your systems, so you don't need PCI compliance, and network tokens typically yield better authorization rates.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_GAzrD99cUqGEN/payment_instruments \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "network_token"
      }'
    ```

    If your processor requires raw card data, request a `card` Payment Instrument instead to receive the full credentials: number, expiration date, CVV, and billing zip code. This approach exposes PAN data to your systems and requires PCI compliance.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_GAzrD99cUqGEN/payment_instruments \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "card"
      }'
    ```

    ```json theme={null}
    {
      "success": true,
      "data": {
        "id": "pmt_inst_pd788hPVhLT37",
        "account_id": "acc_GAzrD99cUqGEN",
        "type": "card",
        "card": {
          "number": "4000120000001154",
          "exp_month": "09",
          "exp_year": "2028",
          "cvv": "878",
          "billing_zip_code": "90028"
        },
        "network_token": null,
        "inbound_achwire_payment": null,
        "chargeable": true,
        "status": "completed",
        "error": null,
        "created_at": "2025-12-10T14:35:22.039Z",
        "updated_at": "2025-12-10T14:35:22.039Z"
      },
      "message": null
    }
    ```

    <Warning>
      Payment Instruments is a gated product that requires approval. Contact your Method representative to enable access.
    </Warning>
  </Step>
</Steps>

<Note>
  **Alternative path:** If you don't need complete control over the onboarding experience, [Opal](/opal/overview) provides an embedded flow that handles identity verification and card discovery for you.
</Note>

## What's Next

<CardGroup>
  <Card title="Preauth Signals" icon="signal" href="/guides/use-cases/commerce/preauth-signals">
    Evaluate payment readiness before authorizing a transaction.
  </Card>

  <Card title="Card Brand API Reference" icon="credit-card" href="/reference/accounts/card-brands/overview">
    Full API documentation for Card Brand.
  </Card>

  <Card title="Payment Instruments API Reference" icon="key" href="/reference/accounts/payment-instruments/overview">
    Full API documentation for Payment Instruments.
  </Card>
</CardGroup>


# Mortgage & HELOC
Source: https://docs.methodfi.com/guides/use-cases/lending/mortgage-heloc

Top-of-funnel qualification through portfolio targeting for secured-lending teams.

*Top-of-funnel qualification through portfolio targeting for secured-lending teams.*

Pull a borrower's full liability picture before pre-approval, size HELOC and refi offers against real-time balances and APRs, and continuously surface existing customers who are in the market for a HELOC or new mortgage. From nothing more than a name and phone, Method discovers every liability a borrower holds (mortgages, HELOCs, credit cards, auto, student, and personal loans), pulls current balances, APRs, and payment behavior directly from each financial institution, and keeps that picture refreshed after the borrower is in the book. The same data fabric powers two motions: origination (pre-qualification and HELOC/refi sizing) and portfolio intelligence (continuous monitoring to surface HELOC- and mortgage-ready customers before they shop elsewhere).

## How it works

Create the borrower Entity, verify them, run Connect to discover their liabilities, then subscribe to the v2 attribute set for a continuous, real-time view. All examples use `Method-Version: 2026-03-30`. Monetary values are in **cents** (`1420000` = \$14,200.00); utilization is a percentage (`37.4` = 37.4%); deltas are percentage points.

<Steps>
  <Step title="Create the Entity">
    `POST /entities`. You only need `first_name`, `last_name`, and `phone`. An Entity can be created minimally and enriched later; passing `dob` and `ssn_4` when you have them measurably improves match rates during account discovery, so include them in production where available. The Entity returns `status: "incomplete"` with `connect`, `credit_score`, and `attribute` in `restricted_products` until verification completes.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{
          "type": "individual",
          "individual": {
            "first_name": "Maya",
            "last_name": "Chen",
            "phone": "+13105550147"
          }
        }'
      ```

      ```json theme={null}
      {
        "id": "ent_BzirqpLEm3BW7",
        "type": "individual",
        "individual": {
          "first_name": "Maya",
          "last_name": "Chen",
          "phone": "+13105550147"
        },
        "status": "incomplete",
        "products": ["identity"],
        "restricted_products": ["connect", "credit_score", "attribute"],
        "available_subscriptions": ["connect", "credit_score"]
      }
      ```
    </Expandable>
  </Step>

  <Step title="Verify the borrower (BYO SMS + BYO KYC)">
    Verification must complete before Connect, credit, and attribute products unlock. The lending flows in these guides use BYO SMS and BYO KYC, which let you assert results you already captured in your own onboarding. Both require your team to be pre-authorized, so contact your Method CSM to enable them. For other verification methods, see [Verification Methods](/guides/identity-verification/methods). Once both sessions complete, the Entity moves to `status: "active"` and `connect`, `credit_score`, and `attribute` move from `restricted_products` into `products`. For the full walkthrough, see the [Getting Started](/guides/use-cases/lending/getting-started) guide.

    <Expandable title="phone and identity requests">
      Verify the phone with BYO SMS, passing the ISO 8601 timestamp of when you verified the number:

      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/verification_sessions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "type": "phone", "method": "byo_sms", "byo_sms": { "timestamp": "2026-03-30T12:00:00.000Z" } }'
      ```

      Then assert identity with BYO KYC (you're confirming your external KYC process passed for this borrower):

      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/verification_sessions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "type": "identity", "method": "byo_kyc", "byo_kyc": {} }'
      ```
    </Expandable>
  </Step>

  <Step title="Run Connect">
    `POST /entities/{ent_id}/connect`. Connect performs a soft credit pull (no score impact) and returns the account IDs Method created for each liability. The first Connect returns all liability accounts, both active and closed; subsequent calls return only newly discovered accounts.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/connect \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "cxn_4ewMmBbjYDMR4",
        "entity_id": "ent_BzirqpLEm3BW7",
        "status": "completed",
        "accounts": [
          "acc_RGACQH7XdfYhC",
          "acc_TmGPLxkz7Nrh6",
          "acc_WqNhMRNVZjbKg",
          "acc_YXDrjADGjC76U"
        ],
        "error": null
      }
      ```
    </Expandable>
  </Step>

  <Step title="List the discovered accounts">
    `GET /accounts`. Filter to `type=liability` and `status=active` to work with live debt only. Narrow with `liability.type` (e.g. `mortgage`, `credit_card`) to isolate the secured-debt picture that matters for a HELOC decision. For decision-time accuracy, pull a fresh `POST /accounts/{acc_id}/updates` on the accounts that drive the decision (balances on revolving and mortgage debt shift daily).

    <Expandable title="request & response">
      ```bash theme={null}
      curl "https://production.methodfi.com/accounts?holder_id=ent_BzirqpLEm3BW7&type=liability&status=active" \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "data": [
          {
            "id": "acc_RGACQH7XdfYhC",
            "holder_id": "ent_BzirqpLEm3BW7",
            "status": "active",
            "type": "liability",
            "liability": {
              "mch_id": "mch_300012",
              "mask": "8842",
              "ownership": "primary",
              "type": "mortgage",
              "name": "Rocket Mortgage Home Loan"
            },
            "products": ["balance", "update"],
            "restricted_products": ["attribute", "sensitive"]
          },
          {
            "id": "acc_WqNhMRNVZjbKg",
            "holder_id": "ent_BzirqpLEm3BW7",
            "status": "active",
            "type": "liability",
            "liability": {
              "mch_id": "mch_302086",
              "mask": "1580",
              "ownership": "primary",
              "type": "credit_card",
              "name": "Chase Sapphire Reserve Credit Card"
            },
            "products": ["balance", "update", "card_brand"],
            "restricted_products": ["attribute", "sensitive"]
          }
        ]
      }
      ```
    </Expandable>
  </Step>

  <Step title="Enroll the entity in the attribute subscription">
    `POST /entities/{ent_id}/subscriptions` with `enroll: attribute`. Method computes credit-health attributes (utilization, balances, APRs, trends, payment behavior, delinquency flags) at both the entity level and the account level. Pass the `portfolio_intelligence` bundle to onboard the full PI attribute set in one call, plus any HELOC/mortgage-specific attributes you want explicitly. Once enrolled, every account on the entity is eligible for attribute generation; you do not enroll accounts individually. Portfolio Intelligence (`portfolio_intelligence`) is separately enabled, so ask your Method CSM to turn it on first.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{
          "enroll": "attribute",
          "payload": {
            "attributes": {
              "bundles": ["portfolio_intelligence"],
              "requested_attributes": [
                "mortgage_balance_total",
                "heloc_balance_total",
                "heloc_utilization",
                "overall_utilization",
                "revolving_credit_card_balance_total",
                "weighted_average_apr_credit_card",
                "delinquency_flag_credit_cards"
              ]
            }
          }
        }'
      ```

      ```json theme={null}
      {
        "id": "sub_Tm8qNnLx5RjWk",
        "name": "attribute",
        "status": "active",
        "latest_request_id": null,
        "created_at": "2026-04-09T17:00:12.218Z",
        "updated_at": "2026-04-09T17:00:12.218Z"
      }
      ```
    </Expandable>

    Once `status` is `active`, Method begins pulling directly from the borrower's institutions and attribute generation starts.
  </Step>

  <Step title="(Optional) Enroll accounts in Update subscriptions">
    `POST /accounts/{acc_id}/subscriptions` with `enroll: update`. Adds a near-real-time balance/payment event stream on a specific account, on top of the entity attribute layer, useful when you want a webhook the moment a tracked mortgage or card balance moves.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_WqNhMRNVZjbKg/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "update" }'
      ```
    </Expandable>
  </Step>

  <Step title="Pull the entity attribute set">
    `POST /entities/{ent_id}/attributes`. Asynchronous: it returns immediately with `status: "in_progress"` and `attributes: null`, then fires an `entity_attribute.create` webhook when computation completes. Retrieve the finished object via `GET /entities/{ent_id}/attributes/{attr_id}`. Attributes that can't be computed (e.g. a trend with insufficient history, or HELOC attributes for a borrower with no HELOC) return `value: null` with an `error` object rather than failing the whole response.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/attributes \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "attr_Qk9nPmRw3LjTx",
        "entity_id": "ent_BzirqpLEm3BW7",
        "status": "completed",
        "attributes": {
          "mortgage_balance_total":               { "value": 31200000, "error": null, "metadata": null },
          "heloc_balance_total":                  { "value": 0, "error": null, "metadata": null },
          "heloc_utilization":                    { "value": null, "error": { "type": "ENTITY_ATTRIBUTE_INSUFFICIENT_DATA", "code": 27001, "message": "Insufficient data to compute this entity attribute." }, "metadata": null },
          "overall_utilization":                  { "value": 41.8, "error": null, "metadata": null },
          "revolving_credit_card_balance_total":  { "value": 1840000, "error": null, "metadata": null },
          "credit_card_utilization":              { "value": 63.0, "error": null, "metadata": null },
          "weighted_average_apr_credit_card":     { "value": 23.4, "error": null, "metadata": null },
          "usage_pattern":                        { "value": "revolver", "error": null, "metadata": null },
          "payment_to_minimum_ratio_avg_credit_cards": { "value": 1.6, "error": null, "metadata": null },
          "delinquency_flag_credit_cards":        { "value": "on_time", "error": null, "metadata": null }
        }
      }
      ```
    </Expandable>
  </Step>
</Steps>

**Webhooks.** A PI-enrolled entity fires `entity_attribute.create` on the first computation and `entity_attribute.update` thereafter whenever new values are surfaced; account-level signals fire `account_attribute.create` / `account_attribute.update`. Subscribe to these to drive monitoring workflows without polling.

A primer on the full attribute set, entity-vs-account availability, and webhook payloads lives in the [Portfolio Intelligence guide](/guides/use-cases/lending/portfolio-monitoring).

## Pre-qualification

Run the create-and-Connect flow at intake, then read the entity attribute set to qualify before the borrower invests in a full application. Because the data comes straight from each institution rather than a weeks-old bureau snapshot, the pre-approval decision rests on what the borrower actually owes today.

*Key attributes:* `overall_utilization`, `credit_card_utilization`, `usage_pattern`, `delinquency_flag_credit_cards`, `payment_to_minimum_ratio_avg_credit_cards`.

## HELOC expansion

For a HELOC offer, the secured picture and the borrower's revolving leverage drive both eligibility and sizing. Method surfaces the existing mortgage and HELOC balances directly, alongside the unsecured debt that informs capacity.

*Key attributes:* `mortgage_balance_total`, `heloc_balance_total`, `heloc_utilization`, `overall_utilization`, `revolving_credit_card_balance_total`.

## Debt consolidation / refi

A borrower carrying high-APR revolving balances is a consolidation candidate. Method shows the blended rate they're actually paying, so the savings you quote are priced against real debt, not an estimated rate band. The example borrower above carries \$18,400 in revolving balances at a 23.4% blended APR, a clear consolidation target a HELOC or refi will retire. When the borrower accepts, Direct Pay (the Payments API) routes the verified payoff straight to the incumbent creditor.

*Key attributes:* `weighted_average_apr_credit_card`, `revolving_credit_card_balance_total`, `credit_card_utilization`, `personal_loan_monthly_installments_estimate`.

## Portfolio Intelligence: HELOC / mortgage targeting

Enroll existing customers in the attribute subscription and let the continuous attribute stream surface who is in the market. Watch for the signals that indicate HELOC or new-mortgage intent (sustained revolving paydown that frees capacity, rising high-APR balances that a HELOC will consolidate, or an improving overall profile) and trigger a targeted offer before they shop a competitor.

*Key attributes:* `revolving_credit_card_balance_change_30d/60d/90d`, `overall_utilization_delta_90d`, `overall_utilization_trend_90d`, `weighted_average_apr_credit_card`, `mortgage_balance_total`.


# Portfolio Intelligence: Grow
Source: https://docs.methodfi.com/guides/use-cases/lending/portfolio-monitoring-grow

Post-origination monitoring for refi, 2nd loan, CLI, and cross-sell.

*Post-origination monitoring for refi, 2nd loan, CLI, cross-sell.*

After a loan funds, most lenders lose visibility into their borrowers. Method's Portfolio Intelligence monitors the full liability picture continuously after origination, surfacing 91 real-time signals across 8 categories, so growth, retention, risk, and servicing teams reach their best borrowers before competitors do.

## How it works

Funded loans are enrolled in Attributes v2 + Update + Credit Score Subscriptions, Method continuously monitors the borrower's full liability picture across 15,000+ institutions, improvement signals trigger CLI / 2nd-loan / refi workflows, and Direct Pay retires competitor balances when the borrower accepts.

<Steps>
  <Step title="Enroll the entity in the Attributes v2 subscription">
    `POST /entities/{ent_id}/subscriptions` with `enroll: attribute`. Pass the `portfolio_intelligence` bundle to onboard the full PI attribute set in one call. Every account on the entity then becomes eligible for attribute generation, and Method pushes recomputed values as the underlying data changes. Portfolio Intelligence (`portfolio_intelligence`) is a separately enabled product, so ask your Method CSM to turn it on first.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "attribute", "payload": { "attributes": { "bundles": ["portfolio_intelligence"] } } }'
      ```
    </Expandable>
  </Step>

  <Step title="Enroll the borrower's accounts in Update Subscriptions">
    `POST /accounts/{acc_id}/subscriptions` with `enroll: update`.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_TmGPLxkz7Nrh6/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "update" }'
      ```
    </Expandable>
  </Step>

  <Step title="Enroll the entity in Credit Score Subscriptions">
    `POST /entities/{ent_id}/subscriptions` with `enroll: credit_score`.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "credit_score" }'
      ```
    </Expandable>
  </Step>
</Steps>

For Portfolio Intelligence: Grow workflows, the readiness, offer-targeting, consolidation, and LTV sub-flows below pull from this same v2 attribute set.

## Identify readiness

Score every borrower against their live liability picture: who's revolving, who's approaching payoff, who has a balance worth consolidating. Bureau snapshots are already weeks old at the moment of intent.

*Key v2 attributes:* `usage_pattern`, `overall_utilization`, `credit_card_utilization`, `revolving_credit_card_balance_total`, `revolving_credit_card_balance_change_30d`.

## Target with the right offer

Method surfaces APR ranges and live balances. Offers are priced against the rate the borrower is actually paying, not a bureau-estimated rate band.

*Key v2 attributes:* `weighted_average_apr_credit_card`, `revolving_credit_card_balance_total`, `next_payment_minimum_total_credit_cards`, `credit_limit_total`.

## Execute the consolidation

When the borrower accepts, Direct Pay routes a verified payoff directly to the incumbent issuer. Consolidated payoffs cut delinquency up to \~50% vs. cash-to-borrower disbursement.

*Driven by Direct Pay (Payments API) rather than the Attributes endpoint. See the [Direct Pay](/guides/use-cases/lending/debt-consolidation) use case for the payment-initiation flow.*

## Post-origination LTV: 2nd loan and CLI

\~33% of personal-loan customers take a second loan within 6 to 12 months. Continuous monitoring surfaces who's a renewal candidate, and detects when a borrower's external profile improves enough to support a proactive CLI before they shop competitors.

*Key v2 attributes:* `revolving_credit_card_balance_change_90d`, `overall_utilization_delta_90d`, `overall_utilization_trend_90d`, `revolving_credit_card_utilization_delta_90d`, `revolving_credit_card_utilization_trend_90d`.


# Portfolio Intelligence: Protect
Source: https://docs.methodfi.com/guides/use-cases/lending/portfolio-monitoring-protect

Early warning, line decreases, and real-time delinquency and autopay signals.

*Early warning, line decreases, real-time delinquency and autopay signals.*

Bureau won't tell you a borrower just turned off autopay, opened a balance transfer card, or stacked debt, until it's already on your balance sheet. Method catches all three weeks earlier, with direct evidence from the FI. Same data fabric as PI: Grow, applied to loss prevention.

## How it works

Same subscription setup as PI: Grow, with the attribute bundle tuned to distress signals. Distress events (autopay off, DPD progression, balance stacking) fire as webhooks; risk and servicing teams trigger early intervention.

<Steps>
  <Step title="Enroll funded-loan accounts in Update Subscriptions">
    Enroll with `enroll: update` (`POST /accounts/{acc_id}/subscriptions`).

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_TmGPLxkz7Nrh6/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "update" }'
      ```
    </Expandable>
  </Step>

  <Step title="Pull the v2 attribute set tuned for distress signals">
    `POST /entities/{ent_id}/attributes`. Method computes the full set automatically. Consume the delinquency flags, the balance-change deltas, and the payment-to-minimum ratio for distress detection. For continuous monitoring, enroll in the Entity Attributes subscription (`entity_attribute.create` webhook); Method pushes recomputed attributes as the underlying account data changes.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/attributes \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "attr_dADraNgLBrhgL",
        "entity_id": "ent_qKNBB68bfHGNA",
        "status": "completed",
        "attributes": {
          "delinquency_flag_credit_cards":              { "value": "overdue", "error": null, "metadata": null },
          "any_delinquent_flag":                        { "value": true, "error": null, "metadata": null },
          "serious_delinquent_flag":                    { "value": false, "error": null, "metadata": null },
          "delinquency_worst_dpd_bucket":               { "value": "30_dpd", "error": null, "metadata": null },
          "delinquency_accounts_count":                 { "value": 2, "error": null, "metadata": null },
          "delinquent_balance_total":                   { "value": 41200, "error": null, "metadata": { "partial": true, "accounts_with_data": 1, "accounts_total": 2 } },
          "delinquency_progression_flag":               { "value": true, "error": null, "metadata": null },
          "delinquency_recently_cured_flag":            { "value": false, "error": null, "metadata": null },
          "delinquent_outcome":                         { "value": "current", "error": null, "metadata": null },
          "payment_to_minimum_ratio_avg_credit_cards":  { "value": 0.85, "error": null, "metadata": null },
          "revolving_credit_card_balance_change_30d":   { "value": 381700, "error": null, "metadata": null },
          "revolving_credit_card_utilization_delta_30d":{ "value": 8.4, "error": null, "metadata": null },
          "revolving_credit_card_utilization_trend_30d":{ "value": "increasing", "error": null, "metadata": null },
          "credit_card_utilization":                    { "value": 74.2, "error": null, "metadata": null },
          "installment_balance_change_30d":             { "value": 250000, "error": null, "metadata": null }
        }
      }
      ```
    </Expandable>
  </Step>
</Steps>

## Early delinquency detection

Flag delinquency progression weeks before bureau refresh; act on early-cure or workout opportunities while the borrower still has capacity.

*Key v2 attributes:* `delinquency_flag_credit_cards`, `any_delinquent_flag`, `serious_delinquent_flag`, `delinquency_worst_dpd_bucket`, `delinquency_progression_flag`, `delinquent_outcome`, `delinquency_recently_cured_flag`, `delinquency_accounts_count`, `delinquent_balance_total`, `payment_to_minimum_ratio_avg_credit_cards`, `next_payment_minimum_total_credit_cards`.

## Payment-behavior leading indicators

A declining payment-to-minimum ratio flags borrowers before the first missed payment. (Autopay-specific signals such as autopay disablement detection and autopay-enabled counts surface through Account Updates and account-level attributes rather than entity attributes today.)

*Key v2 attributes:* `payment_to_minimum_ratio_avg_credit_cards`.

## Line decreases on stress signals

Detect borrower distress: utilization spikes, balance stacking, rising aggregate utilization. Act on lines before losses materialize.

*Key v2 attributes:* `revolving_credit_card_balance_change_30d`, `revolving_credit_card_utilization_delta_30d`, `revolving_credit_card_utilization_trend_30d`, `credit_card_utilization`, `overall_utilization_delta_30d`.

## Debt stacking and settlement detection

Surface borrowers taking on new debt across institutions before bureau catches up. Use change-over-time attributes across credit cards and installment accounts to detect stacking patterns through the cross-account view.

*Key v2 attributes:* `delinquency_flag_credit_cards`, `installment_balance_change_30d`, `installment_balance_change_60d`, `revolving_credit_card_balance_change_30d`, `revolving_credit_card_balance_change_60d`.


# Getting Started
Source: https://docs.methodfi.com/guides/use-cases/pfm/getting-started

The universal 3-step flow for PFM integrations: create an entity, verify identity, and connect liabilities.

Every PFM integration begins with the same three steps: represent your user as an Entity, verify their identity, and discover their liabilities through Connect. Once these steps are complete, every product in Method's platform becomes available.

This guide walks through the full API flow using a single user, Sarah Chen, whose data threads through the rest of the PFM guides.

<Steps>
  <Step title="Create an Entity">
    An [Entity](/guides/entities/overview) is Method's representation of your end user. You provide their PII, and Method creates a persistent identity that everything else — verification, accounts, payments — attaches to.

    ```bash theme={null}
    curl https://production.methodfi.com/entities \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "individual",
        "individual": {
          "first_name": "Sarah",
          "last_name": "Chen",
          "phone": "+14155550123",
          "email": "sarah.chen@email.com",
          "dob": "1992-07-15"
        },
        "address": {
          "line1": "123 Main St",
          "line2": null,
          "city": "San Francisco",
          "state": "CA",
          "zip": "94102"
        }
      }'
    ```

    The Entity is created with `status: "incomplete"` because identity verification hasn't happened yet. Products like Connect and Credit Scores remain in `restricted_products` until verification is complete.

    ```json theme={null}
    {
      "id": "ent_au22b1fbFJbp8",
      "type": "individual",
      "individual": {
        "first_name": "Sarah",
        "last_name": "Chen",
        "phone": "+14155550123",
        "dob": "1992-07-15",
        "email": "sarah.chen@email.com",
        "ssn_4": null,
        "ssn": null
      },
      "error": null,
      "address": {
        "line1": "123 Main St",
        "line2": null,
        "city": "San Francisco",
        "state": "CA",
        "zip": "94102"
      },
      "status": "incomplete",
      "verification": {
        "identity": {
          "verified": false,
          "matched": false,
          "latest_verification_session": null,
          "methods": [
            "element",
            "kba"
          ]
        },
        "phone": {
          "verified": false,
          "latest_verification_session": null,
          "methods": [
            "sms",
            "sna"
          ]
        }
      },
      "connect": null,
      "credit_score": null,
      "products": [
        "identity"
      ],
      "restricted_products": [
        "connect",
        "credit_score",
        "attribute"
      ],
      "subscriptions": [],
      "available_subscriptions": [
        "connect",
        "credit_score"
      ],
      "restricted_subscriptions": [],
      "metadata": null,
      "created_at": "2025-09-15T14:30:00.000Z",
      "updated_at": "2025-09-15T14:30:00.000Z"
    }
    ```
  </Step>

  <Step title="Verify the User">
    Before Method can discover Sarah's accounts, she must complete [identity verification](/guides/identity-verification/overview). This is a two-part process: first confirming she controls her phone number, then verifying her identity.

    ### Phone Verification (SMS)

    Start by verifying Sarah's phone number. This sends an SMS code to `+14155550123`.

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/verification_sessions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "sms",
        "sms": {}
      }'
    ```

    ```json theme={null}
    {
      "id": "evf_3VT3bHTCnPbrm",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "in_progress",
      "type": "phone",
      "method": "sms",
      "sms": {},
      "error": null,
      "created_at": "2025-09-15T14:31:00.000Z",
      "updated_at": "2025-09-15T14:31:00.000Z"
    }
    ```

    After the user provides the SMS code and completes identity verification (via [KBA](/reference/entities/verification-sessions/create-kba) or [Opal](/guides/opal)), the Entity transitions to `status: "active"` and products are unlocked.

    <Note>
      **Recommended: Use [Opal](/guides/opal)** for identity verification. Opal is Method's pre-built, white-labeled UI that handles both phone verification and identity verification in a single drop-in component. Most teams start here.
    </Note>

    ### After Verification

    Once verified, the Entity's `products` array expands and `restricted_products` clears:

    ```json theme={null}
    {
      "id": "ent_au22b1fbFJbp8",
      "status": "active",
      "verification": {
        "identity": {
          "verified": true,
          "matched": true,
          "latest_verification_session": "evf_9kR2fGhLmNpQ4",
          "methods": []
        },
        "phone": {
          "verified": true,
          "latest_verification_session": "evf_3VT3bHTCnPbrm",
          "methods": []
        }
      },
      "products": [
        "identity",
        "connect",
        "credit_score",
        "attribute"
      ],
      "restricted_products": [],
      "available_subscriptions": [
        "connect",
        "credit_score"
      ],
      "restricted_subscriptions": []
    }
    ```
  </Step>

  <Step title="Connect Liabilities">
    With Sarah verified, you can now discover her complete liability picture using [Connect](/guides/connect/overview). This performs a soft-pull credit report (no impact to her credit score) and returns all discovered accounts.

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```

    Connect discovers all of Sarah's open liabilities and returns them as account IDs:

    ```json theme={null}
    {
      "id": "cxn_iYGhvTRDnE4y7",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "completed",
      "accounts": [
        "acc_eKKmrXDpJBKgw",
        "acc_GV8WbmJW7KGRy",
        "acc_MLPKh9gQDDbT8",
        "acc_LbXE8wVYJLrKt",
        "acc_J3P9fayDFjpAy",
        "acc_eFFRV9zmpLREK"
      ],
      "requested_products": [],
      "requested_subscriptions": [],
      "error": null,
      "created_at": "2025-09-15T14:35:00.000Z",
      "updated_at": "2025-09-15T14:35:00.000Z"
    }
    ```

    ### What Was Discovered

    Each account ID maps to a liability that Method found on Sarah's credit report. You can retrieve any account to see its details:

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    ```json theme={null}
    {
      "id": "acc_eKKmrXDpJBKgw",
      "holder_id": "ent_au22b1fbFJbp8",
      "type": "liability",
      "liability": {
        "mch_id": "mch_302086",
        "type": "credit_card",
        "name": "Chase Sapphire Reserve"
      },
      "status": "active",
      "products": [
        "update",
        "payment",
        "card_brand",
        "transaction"
      ],
      "created_at": "2025-09-15T14:35:00.000Z",
      "updated_at": "2025-09-15T14:35:00.000Z"
    }
    ```

    Here's what Sarah's full liability picture looks like:

    | Account ID          | Creditor               | Type          |
    | ------------------- | ---------------------- | ------------- |
    | `acc_eKKmrXDpJBKgw` | Chase Sapphire Reserve | Credit Card   |
    | `acc_GV8WbmJW7KGRy` | Citi Double Cash       | Credit Card   |
    | `acc_MLPKh9gQDDbT8` | Capital One            | Auto Loan     |
    | `acc_LbXE8wVYJLrKt` | Navient                | Student Loan  |
    | `acc_J3P9fayDFjpAy` | SoFi                   | Personal Loan |
    | `acc_eFFRV9zmpLREK` | Wells Fargo            | Mortgage      |
  </Step>
</Steps>

## What's Next

With Sarah's entity created, verified, and her liabilities discovered, you're ready to build the core PFM experience. Each of the following guides picks up where this setup leaves off.

<CardGroup>
  <Card title="Onboarding & Discovery" icon="magnifying-glass" href="/guides/use-cases/pfm/onboarding-discovery">
    Deep dive into identity verification options, connect subscriptions for ongoing discovery, and vehicle enrichment for auto loans.
  </Card>

  <Card title="Dashboard & Insights" icon="chart-mixed" href="/guides/use-cases/pfm/monitoring-insights">
    Pull real-time balances, credit scores, card brand art, and entity-level financial health attributes.
  </Card>

  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Stream credit card transactions and initiate bill payments to your users' creditors.
  </Card>
</CardGroup>


# Debt Dashboard & Credit Insights
Source: https://docs.methodfi.com/guides/use-cases/pfm/monitoring-insights

Build real-time debt dashboards with account updates, card brand art, credit scores, and financial health attributes.

Once a user's liabilities are connected, the next step is turning that raw data into a useful dashboard. This guide covers pulling real-time account data, enriching cards with brand art, monitoring balances over time, and surfacing credit health insights.

All examples use Sarah Chen's accounts from the [Getting Started](/guides/use-cases/pfm/getting-started) guide.

## Debt Dashboard & Real-Time Monitoring

### Requesting an Account Update

[Updates](/guides/updates/overview) pull real-time data — balance, credit limit, APR, due dates, payment history — directly from the financial institution. This is the core data feed for any debt dashboard.

Request an update for Sarah's Chase Sapphire Reserve card:

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/updates \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "upt_NYV5kfjskTTCJ",
      "status": "completed",
      "account_id": "acc_eKKmrXDpJBKgw",
      "source": "direct",
      "type": "credit_card",
      "credit_card": {
        "available_credit": 1920000,
        "balance": 80000,
        "closed_at": null,
        "credit_limit": 2000000,
        "interest_rate_percentage_max": 22.49,
        "interest_rate_percentage_min": 22.49,
        "interest_rate_type": "variable",
        "last_payment_amount": 15000,
        "last_payment_date": "2025-08-28",
        "next_payment_due_date": "2025-10-01",
        "next_payment_minimum_amount": 2500,
        "opened_at": "2022-03-15",
        "sub_type": "flexible_spending",
        "usage_pattern": "transactor"
      },
      "data_as_of": "2025-09-15T14:45:00.000Z",
      "error": null,
      "created_at": "2025-09-15T14:45:00.000Z",
      "updated_at": "2025-09-15T14:45:00.312Z"
    }
    ```
  </Tab>
</Tabs>

Sarah's Chase card has an \$800.00 balance on a \$20,000.00 limit (4% utilization), with a minimum payment of \$25.00 due on October 1st. Her last payment of \$150.00 was made on August 28th, and her `usage_pattern` is `transactor` — she pays in full each month.

### Subscribing to Continuous Updates

Rather than polling for updates, subscribe to receive them automatically. When the financial institution reports new data, Method delivers it via webhook.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/subscriptions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "enroll": "update"
      }'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "sub_xM4VcfRWcJP8D",
      "name": "update",
      "status": "active",
      "payload": null,
      "latest_request_id": "upt_NYV5kfjskTTCJ",
      "created_at": "2025-09-15T15:10:00.000Z",
      "updated_at": "2025-09-15T15:10:00.000Z"
    }
    ```
  </Tab>
</Tabs>

With the subscription active, Method will fire `update.create` and `update.update` webhook events whenever new data is available. Your app can refresh the dashboard in real time without the user taking any action.

### Card Brand Art

For credit card accounts, [Card Brand](/guides/additional-products/card-brand) retrieves the card's product name, issuer, network, and card art image. This lets your wallet UI display the actual card visual instead of a generic placeholder.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/card_brands \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "cbrd_Accm7P6t6mYQP",
      "account_id": "acc_eKKmrXDpJBKgw",
      "brands": [
        {
          "id": "pdt_15_brd_1",
          "card_product_id": "pdt_15",
          "description": "Chase Sapphire Reserve",
          "name": "Chase Sapphire Reserve",
          "issuer": "Chase",
          "network": "visa",
          "network_tier": "infinite",
          "type": "specific",
          "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
        }
      ],
      "status": "completed",
      "source": "method",
      "error": null,
      "created_at": "2025-09-15T15:15:00.000Z",
      "updated_at": "2025-09-15T15:15:00.000Z"
    }
    ```
  </Tab>
</Tabs>

The `url` field provides a direct link to the card's art image, which you can render in your wallet or dashboard UI.

### Entity-Level Attributes

[Attributes](/guides/additional-products/attributes) provide entity-level financial health metrics aggregated across all of a user's accounts. These power features like credit health dashboards, utilization alerts, and financial wellness scores.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/attributes \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    <Note>
      Attribute requests are asynchronous and compute all available attributes automatically. The initial response will have `status: "in_progress"` and `attributes: null`. You'll receive a webhook when the attributes are ready.
    </Note>
  </Tab>

  <Tab title="Response (completed)">
    ```json theme={null}
    {
      "id": "attr_nrPjaahMX4yRA",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "completed",
      "attributes": {
        "revolving_credit_card_balance_total": {
          "value": 550000,
          "error": null,
          "metadata": null
        },
        "credit_limit_total": {
          "value": 2500000,
          "error": null,
          "metadata": null
        },
        "credit_card_utilization": {
          "value": 22.0,
          "error": null,
          "metadata": null
        },
        "weighted_average_apr_credit_card": {
          "value": 21.24,
          "error": null,
          "metadata": null
        },
        "usage_pattern": {
          "value": "transactor",
          "error": null,
          "metadata": null
        },
        "overall_utilization": {
          "value": 22.0,
          "error": null,
          "metadata": null
        }
      },
      "error": null,
      "created_at": "2025-09-15T15:20:00.000Z",
      "updated_at": "2025-09-15T15:20:30.000Z"
    }
    ```
  </Tab>
</Tabs>

Sarah's attributes show 22% aggregate credit card utilization ($5,500.00 in revolving balances against $25,000.00 in combined limits), a weighted average card APR of 21.24%, and a `transactor` usage pattern (she pays in full each month). These data points map directly to the factors that credit scoring models weigh most heavily. Each attribute is returned as an object with `value`, `error`, and `metadata` fields; if an attribute cannot be computed, `value` is `null` and `error` explains why.

***

## Credit Building & Score Insights

### Retrieving Credit Scores

[Credit Scores](/guides/additional-products/credit-scores) retrieve the user's credit score sourced from Equifax using the VantageScore 4.0 model. The response includes contributing factors that explain what's helping or hurting the score.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/credit_scores \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    <Note>
      Credit score requests are asynchronous. The initial response will have `status: "pending"` and `scores: null`. You'll receive a webhook when the score is ready.
    </Note>
  </Tab>

  <Tab title="Response (completed)">
    ```json theme={null}
    {
      "id": "crs_pn4ca33GXFaCE",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "completed",
      "scores": [
        {
          "score": 734,
          "source": "equifax",
          "model": "vantage_4",
          "factors": [
            "Length of time accounts have been established",
            "Too few accounts currently paid as agreed",
            "Lack of recent installment loan information",
            "Proportion of balances to credit limits is too high on bank revolving or other revolving accounts"
          ],
          "created_at": "2025-09-15T15:25:00.000Z"
        }
      ],
      "error": null,
      "created_at": "2025-09-15T15:25:00.000Z",
      "updated_at": "2025-09-15T15:25:30.000Z"
    }
    ```
  </Tab>
</Tabs>

Sarah's VantageScore 4.0 is 734 ("Good" tier). The factors array explains what's influencing her score — you can surface these directly in your app to help users understand what actions would improve their score.

### Credit Score Subscriptions

To monitor Sarah's credit score over time, enroll her in a credit score subscription. Method will automatically check for score changes and send webhook events when her score increases or decreases.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/subscriptions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "enroll": "credit_score"
      }'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "sub_c3a7hVjHCJzF3",
      "name": "credit_score",
      "status": "active",
      "payload": null,
      "latest_request_id": null,
      "created_at": "2025-09-15T15:30:00.000Z",
      "updated_at": "2025-09-15T15:30:00.000Z"
    }
    ```
  </Tab>
</Tabs>

With the subscription active, your app can power features like monthly score reports, trend charts, and push notifications ("Your credit score went up 12 points this month!") that drive engagement and retention.

### Combining Scores and Attributes

The most effective credit building experiences combine credit scores with attributes. The score tells users *where they stand*, while attributes tell them *why* and *what to do about it*:

| Attribute                             | Sarah's Value | What to Surface                                                             |
| ------------------------------------- | ------------- | --------------------------------------------------------------------------- |
| `credit_card_utilization`             | 22%           | "Your utilization is healthy. Keep it under 30%"                            |
| `usage_pattern`                       | `transactor`  | "You pay your cards in full each month. Keep it up!"                        |
| `weighted_average_apr_credit_card`    | 21.24%        | "Your average card APR is 21.24%. A balance transfer could reduce interest" |
| `revolving_credit_card_balance_total` | \$5,500.00    | "Your total card balances across all accounts"                              |

<Card title="Attributes API Reference" icon="chart-bar" href="/reference/entities/attributes/create">
  Full documentation for all available attribute types and their value, error, and metadata fields.
</Card>

## What's Next

<CardGroup>
  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Stream credit card transactions for spend management and initiate bill payments.
  </Card>

  <Card title="Update Subscriptions Guide" icon="rotate" href="/guides/updates/subscriptions">
    Deep dive into update subscription types, frequencies, and webhook payloads.
  </Card>
</CardGroup>


# Onboarding & Liability Discovery
Source: https://docs.methodfi.com/guides/use-cases/pfm/onboarding-discovery

Identity verification options, liability discovery via Connect, ongoing connect subscriptions, and vehicle enrichment for auto loans.

This guide covers the onboarding layer of a PFM integration: how users get verified, how their liabilities are discovered, how to detect new liabilities over time, and how to enrich auto loan accounts with vehicle details.

If you haven't completed the [Getting Started](/guides/use-cases/pfm/getting-started) steps (creating and verifying Sarah Chen's Entity, and running Connect), start there first.

## Identity Verification with Opal

[Opal](/guides/opal) is Method's pre-built, white-labeled UI component that handles the entire verification flow — phone verification and identity verification — in a single drop-in experience. It's the fastest path to getting users verified and is recommended for most integrations.

<Tabs>
  <Tab title="Opal (Recommended)">
    Opal handles phone verification (SMS or SNA) and identity verification (KBA) in a single embedded flow. Your user completes the process in your app, and you receive a webhook when verification is complete.

    **Advantages:**

    * Minimal frontend development
    * Tested, optimized UX for conversion
    * Handles edge cases (retries, fallbacks, error states)
    * White-labeled to match your brand

    <Card title="Opal Integration Guide" icon="window" href="/guides/opal">
      Full guide for embedding Opal in your application.
    </Card>
  </Tab>

  <Tab title="BYO Identity Verification">
    If you have an existing identity verification flow or need complete control over the UX, you can use Method's API directly. This involves separate calls for [phone verification](/reference/entities/verification-sessions/create-sms) and [identity verification](/reference/entities/verification-sessions/create-kba).

    **When to use BYO:**

    * You already have a KYC/IDV provider and want to pass results to Method
    * Your UX requires a custom verification flow
    * You need to integrate verification into an existing onboarding funnel

    <Card title="Identity Verification Methods" icon="shield-check" href="/guides/identity-verification/methods">
      All available verification methods and when to use each.
    </Card>
  </Tab>
</Tabs>

## Liability Discovery via Connect

Once Sarah is verified, [Connect](/guides/connect/overview) performs a soft-pull credit report to discover her liabilities. The [Getting Started](/guides/use-cases/pfm/getting-started) guide showed the Connect call that discovered all 6 of her accounts.

Here's what Connect found for Sarah:

| Account ID          | Creditor               | Type          | What Your App Shows            |
| ------------------- | ---------------------- | ------------- | ------------------------------ |
| `acc_eKKmrXDpJBKgw` | Chase Sapphire Reserve | Credit Card   | Card balance, APR, due date    |
| `acc_GV8WbmJW7KGRy` | Citi Double Cash       | Credit Card   | Card balance, APR, due date    |
| `acc_MLPKh9gQDDbT8` | Capital One            | Auto Loan     | Loan balance, payment schedule |
| `acc_LbXE8wVYJLrKt` | Navient                | Student Loan  | Loan balance, disbursements    |
| `acc_J3P9fayDFjpAy` | SoFi                   | Personal Loan | Balance, term, rate            |
| `acc_eFFRV9zmpLREK` | Wells Fargo            | Mortgage      | Balance, rate, payoff date     |

<Note>
  Connect discovers both open and closed liabilities on the first call. Subsequent Connect calls for the same Entity only return newly opened accounts.
</Note>

## Connect Subscriptions

A user's liability picture changes over time — they open new credit cards, take out loans, or consolidate debt. Connect subscriptions automatically re-run discovery on a recurring basis and notify you via webhook when new accounts are found.

Enroll the Entity in a connect subscription:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "enroll": "connect"
  }'
```

```json theme={null}
{
  "id": "sub_Wm3FJkqV8hpDR",
  "name": "connect",
  "status": "active",
  "payload": null,
  "latest_request_id": null,
  "created_at": "2025-09-15T15:00:00.000Z",
  "updated_at": "2025-09-15T15:00:00.000Z"
}
```

When Method detects a new liability for Sarah, you'll receive a webhook event with the new Connect result containing the newly discovered account IDs. Your app can then automatically add these to her dashboard without any user action.

## Vehicle Enrichment

For auto loan accounts like Sarah's Capital One loan (`acc_MLPKh9gQDDbT8`), Method can retrieve the associated vehicle details — VIN, year, make, model, and style. This transforms a generic "Auto Loan: \$18,450 balance" into "2021 Honda CR-V EX: \$18,450 remaining."

Request vehicle data for Sarah's Entity:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/vehicles \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

```json theme={null}
{
  "id": "evhl_QnT4mKxBfVpJ8",
  "entity_id": "ent_au22b1fbFJbp8",
  "vehicles": [
    {
      "vin": "7FARW2H83ME012345",
      "year": "2021",
      "make": "honda",
      "model": "cr-v",
      "series": null,
      "major_color": "blue",
      "style": "sport_utility_vehicle"
    }
  ],
  "status": "completed",
  "error": null,
  "created_at": "2025-09-15T15:05:00.000Z",
  "updated_at": "2025-09-15T15:05:00.000Z"
}
```

With vehicle data, your PFM app can display rich auto loan details, enable equity calculations (comparing vehicle value against remaining balance), and power features like insurance comparison or refinancing recommendations.

<Card title="Vehicles API Reference" icon="car" href="/reference/entities/vehicles/create">
  Full API documentation for the Vehicles endpoint.
</Card>

## What's Next

<CardGroup>
  <Card title="Dashboard & Insights" icon="chart-mixed" href="/guides/use-cases/pfm/monitoring-insights">
    Pull real-time balances, credit scores, card brand art, and financial health attributes.
  </Card>

  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Stream credit card transactions and initiate bill payments.
  </Card>
</CardGroup>


# Digital Engagement & PFM
Source: https://docs.methodfi.com/guides/use-cases/pfm/overview

Build comprehensive personal financial management experiences with Method's liability data, credit insights, and payment infrastructure.

## What This Section Covers

Products and APIs that enable comprehensive personal financial management experiences — from discovering a user's complete debt picture to monitoring changes in real time, surfacing credit insights, and enabling bill pay directly from your app.

If you're building any product that helps consumers understand, manage, or pay down their financial obligations, this is where to start.

### Example Use Cases

* **Digital wallets** that display card balances, brand art, and recent transactions
* **Spend management apps** that categorize liability transactions and track spending patterns
* **Financial wellness platforms** that surface credit scores, debt-to-income insights, and payoff strategies
* **Neobanks** that embed bill pay and debt repayment into the core banking experience

## How Method Enables End-to-End PFM

Every PFM integration follows the same high-level journey: discover the user's liabilities, enrich them with real-time data, surface insights, and enable action.

| Stage        | What Happens                                                               | Method Products                                                                                                                           |
| ------------ | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Connect**  | Discover the user's complete liability picture via soft-pull credit report | [Entity](/guides/entities/overview), [Identity Verification](/guides/identity-verification/overview), [Connect](/guides/connect/overview) |
| **Data**     | Pull real-time balances, APRs, due dates, card art, and transactions       | [Updates](/guides/updates/overview), [Card Brand](/guides/additional-products/card-brand)                                                 |
| **Insights** | Surface credit scores, payment history, utilization, and attributes        | [Credit Scores](/guides/additional-products/credit-scores), [Attributes](/guides/additional-products/attributes)                          |
| **Pay**      | Initiate payments from your platform's funding account to users' creditors | [Payments](/guides/payments/overview)                                                                                                     |

## Get Started

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="/guides/use-cases/pfm/getting-started">
    The universal 3-step setup: create an entity, verify identity, and connect liabilities.
  </Card>

  <Card title="Onboarding & Discovery" icon="magnifying-glass" href="/guides/use-cases/pfm/onboarding-discovery">
    Identity verification, liability discovery, connect subscriptions, and vehicle enrichment.
  </Card>

  <Card title="Dashboard & Insights" icon="chart-mixed" href="/guides/use-cases/pfm/monitoring-insights">
    Real-time balances, credit scores, card brands, and entity-level attributes.
  </Card>

  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Transaction streaming, spend management, bill pay, and debt repayment.
  </Card>
</CardGroup>


# Transactions & Bill Pay
Source: https://docs.methodfi.com/guides/use-cases/pfm/transactions-payments

Stream credit card transactions for spend management and initiate bill payments to your users' creditors.

This guide covers the action layer of a PFM integration: streaming transaction data for spend management, and initiating payments from your platform's corporate funding account to pay down user liabilities.

All examples use Sarah Chen's accounts from the [Getting Started](/guides/use-cases/pfm/getting-started) guide.

## Transaction Stream & Spend Management

### Listing Transactions

Transactions provide transaction-level detail for connected Visa and Mastercard credit card accounts. Once subscribed, you can query historical transactions and receive new ones in real time via webhooks.

Retrieve recent transactions for Sarah's Chase Sapphire Reserve card:

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl "https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/transactions?from_date=2025-09-01&to_date=2025-09-15" \
      -X GET \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "data": [
        {
          "id": "txn_t73AdHRFYwhT9",
          "account_id": "acc_eKKmrXDpJBKgw",
          "status": "posted",
          "descriptor": "SQ *BLUE BOTTLE COFF",
          "merchant": {
            "name": "Blue Bottle Coffee",
            "logo": null
          },
          "merchant_category_code": "5814",
          "amount": 675,
          "auth_amount": 675,
          "currency_code": "USD",
          "transaction_amount": 675,
          "transaction_auth_amount": 675,
          "transaction_currency_code": "USD",
          "transacted_at": "2025-09-14T08:22:00.000Z",
          "posted_at": "2025-09-15T05:00:00.000Z",
          "voided_at": null,
          "original_txn_id": null,
          "created_at": "2025-09-14T08:22:00.000Z",
          "updated_at": "2025-09-15T05:00:00.000Z"
        },
        {
          "id": "txn_kP4mRvTnBcWx2",
          "account_id": "acc_eKKmrXDpJBKgw",
          "status": "posted",
          "descriptor": "WHOLE FOODS MKT #1042",
          "merchant": {
            "name": "Whole Foods Market",
            "logo": null
          },
          "merchant_category_code": "5411",
          "amount": 8743,
          "auth_amount": 8743,
          "currency_code": "USD",
          "transaction_amount": 8743,
          "transaction_auth_amount": 8743,
          "transaction_currency_code": "USD",
          "transacted_at": "2025-09-12T18:45:00.000Z",
          "posted_at": "2025-09-13T05:00:00.000Z",
          "voided_at": null,
          "original_txn_id": null,
          "created_at": "2025-09-12T18:45:00.000Z",
          "updated_at": "2025-09-13T05:00:00.000Z"
        },
        {
          "id": "txn_qN7jWvHmDfRa5",
          "account_id": "acc_eKKmrXDpJBKgw",
          "status": "posted",
          "descriptor": "SHELL OIL 57442",
          "merchant": {
            "name": "Shell",
            "logo": null
          },
          "merchant_category_code": "5541",
          "amount": 5218,
          "auth_amount": 5218,
          "currency_code": "USD",
          "transaction_amount": 5218,
          "transaction_auth_amount": 5218,
          "transaction_currency_code": "USD",
          "transacted_at": "2025-09-10T14:30:00.000Z",
          "posted_at": "2025-09-11T05:00:00.000Z",
          "voided_at": null,
          "original_txn_id": null,
          "created_at": "2025-09-10T14:30:00.000Z",
          "updated_at": "2025-09-11T05:00:00.000Z"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

Sarah's recent transactions show \$6.75 at Blue Bottle Coffee, \$87.43 at Whole Foods, and \$52.18 at Shell. All amounts are in cents. The `merchant_category_code` enables spend categorization (5814 = restaurants, 5411 = grocery, 5541 = gas stations).

### Subscribing to Transactions

Transaction data requires an active subscription. Enroll Sarah's Chase card to receive transaction events in real time:

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/subscriptions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "enroll": "transaction"
      }'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "sub_P8c4bjj6xajxF",
      "name": "transaction",
      "status": "active",
      "payload": null,
      "latest_request_id": null,
      "created_at": "2025-09-15T15:40:00.000Z",
      "updated_at": "2025-09-15T15:40:00.000Z"
    }
    ```
  </Tab>
</Tabs>

With the subscription active, Method fires webhook events for both authorization events (when Sarah swipes her card) and settlement events (when the transaction clears). This enables real-time spend alerts, budget tracking, and transaction feeds.

<Warning>
  Transaction streaming is available for Visa and Mastercard credit cards. Not all card accounts will support transactions — check the account's `products` array to confirm `transaction` is available.
</Warning>

***

## Bill Pay & Debt Repayment

### Getting a Fresh Balance Before Payment

Before initiating a payment, pull the latest balance to ensure accuracy. If you've already subscribed to updates (covered in the [Dashboard & Insights](/guides/use-cases/pfm/monitoring-insights) guide), you'll have recent data. Otherwise, request an on-demand update:

```bash theme={null}
curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/updates \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

The completed update confirms Sarah's Chase card balance is \$800.00 (`80000` cents) with a minimum payment of \$25.00 due on October 1st. She decides to pay \$500.00 toward the balance.

### Creating a Payment

[Payments](/guides/payments/overview) move money from your platform's verified funding account (ACH) to a liability account. Your corporate funding account `acc_hmap9mbgfLcf9` serves as the payment source for all user payments.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/payments \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 50000,
        "source": "acc_hmap9mbgfLcf9",
        "destination": "acc_eKKmrXDpJBKgw",
        "description": "Chase Pmt"
      }'
    ```
  </Tab>

  <Tab title="Response (pending)">
    ```json theme={null}
    {
      "id": "pmt_VeCfmkwGKb",
      "source": "acc_hmap9mbgfLcf9",
      "destination": "acc_eKKmrXDpJBKgw",
      "amount": 50000,
      "description": "Chase Pmt",
      "status": "pending",
      "estimated_completion_date": "2025-09-18",
      "source_trace_id": null,
      "source_settlement_date": "2025-09-16",
      "source_status": "pending",
      "destination_trace_id": null,
      "destination_settlement_date": "2025-09-18",
      "destination_payment_method": "paper",
      "destination_status": "pending",
      "reversal_id": null,
      "error": null,
      "metadata": null,
      "created_at": "2025-09-15T16:00:00.000Z",
      "updated_at": "2025-09-15T16:00:00.000Z"
    }
    ```
  </Tab>
</Tabs>

The payment is created with `status: "pending"` and an estimated completion date of September 18th. The `description` field (max 10 characters) appears on the user's bank statement.

<Note>
  All amounts are in **cents**. `50000` = \$500.00. The `description` field has a maximum length of 10 characters.
</Note>

### Payment Lifecycle

Payments move through a lifecycle from creation to settlement. Track progress via webhook events:

Once the payment settles, the status transitions to `posted`:

```json theme={null}
{
  "id": "pmt_VeCfmkwGKb",
  "source": "acc_hmap9mbgfLcf9",
  "destination": "acc_eKKmrXDpJBKgw",
  "amount": 50000,
  "description": "Chase Pmt",
  "status": "posted",
  "estimated_completion_date": "2025-09-18",
  "source_trace_id": "203942084920",
  "source_settlement_date": "2025-09-16",
  "source_status": "posted",
  "destination_trace_id": "304820184832",
  "destination_settlement_date": "2025-09-18",
  "destination_payment_method": "paper",
  "destination_status": "posted",
  "reversal_id": null,
  "error": null,
  "metadata": null,
  "created_at": "2025-09-15T16:00:00.000Z",
  "updated_at": "2025-09-18T12:00:00.000Z"
}
```

## Putting It All Together

With transactions and payments, Sarah's PFM experience is complete:

| Capability         | Product                                                    | Example                                           |
| ------------------ | ---------------------------------------------------------- | ------------------------------------------------- |
| View all debts     | [Connect](/guides/connect/overview)                        | 6 liabilities discovered automatically            |
| Real-time balances | [Updates](/guides/updates/overview)                        | Chase card: \$800.00 balance, \$25.00 minimum due |
| Card visuals       | [Card Brand](/guides/additional-products/card-brand)       | Chase Sapphire Reserve card art                   |
| Credit score       | [Credit Scores](/guides/additional-products/credit-scores) | VantageScore 4.0: 734                             |
| Financial health   | [Attributes](/guides/additional-products/attributes)       | 22% utilization, 100% payment history             |
| Spending activity  | Transactions                                               | Coffee, groceries, gas — categorized in real time |
| Bill pay           | [Payments](/guides/payments/overview)                      | \$500 payment to Chase, settled in 3 days         |

<CardGroup>
  <Card title="Payments Lifecycle" icon="arrows-spin" href="/guides/payments/lifecycle">
    Deep dive into payment states, timing, and error handling.
  </Card>

  <Card title="Payment Errors" icon="triangle-exclamation" href="/guides/payments/errors">
    Understanding and handling payment failures and reversals.
  </Card>
</CardGroup>


# Libraries
Source: https://docs.methodfi.com/opal/libraries



Method offers a variety of libraries for your frontend application to make integrating with Opal easy and simple.

## Frontend Libraries

Depending on your application, Method offers multiple frontend libraries to help you integrate with Opal:

<CardGroup>
  <Card title="JavaScript SDK" icon="js" href="https://static.methodfi.com/opal/v1/stable/init.js">
    For vanilla JavaScript applications
  </Card>

  <Card title="React SDK" icon="react" href="https://www.npmjs.com/package/@methodfi/opal-react">
    For React applications
  </Card>

  <Card title="React Native SDK" icon="mobile" href="https://www.npmjs.com/package/@methodfi/opal-react-native">
    For React Native applications
  </Card>
</CardGroup>

All Opal SDKs provide:

* **Token Management**: Automatic token validation and refresh
* **Event Handling**: Comprehensive event system with typed callbacks
* **Error Management**: Enhanced error handling with detailed error codes
* **Security**: Built-in security features and validation

## Installation

<Tabs>
  <Tab title="JavaScript">
    ```html theme={null}
    <script src="https://static.methodfi.com/opal/v1/stable/init.js"></script>
    ```
  </Tab>

  <Tab title="React">
    ```bash theme={null}
    npm install @methodfi/opal-react
    ```

    ## Quick usage: React (Web)

    ```tsx theme={null}
    import { OpalProvider, useOpal, OpalEventType } from "@methodfi/opal-react";

    export default function App() {
      return (
        <OpalProvider>
          <YourApp />
        </OpalProvider>
      );
    }

    function YourApp() {
      const { open, close, isOpen, error } = useOpal({
        env: "dev",
        onOpen: () => {},
        onExit: () => {},
        onEvent: (event) => {
          switch (event.type) {
            case OpalEventType.SESSION_STARTED:
              // ...
              break;
            case OpalEventType.SESSION_COMPLETED:
              // ...
              break;
            case OpalEventType.SESSION_ERRORED:
              // ...
              break;
            case OpalEventType.SESSION_EXITED:
              // ...
              break;
          }
        },
      });

      const onLaunchOpal = async () => {
        const token = await getOpalToken(); // POST /opal/token
        open({ token });
      };

      return <button onClick={onLaunchOpal}>Launch Opal</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```bash theme={null}
    npm install @methodfi/opal-react-native
    ```

    ## Quick usage: React Native (Mobile)

    ```tsx theme={null}
    import {
      OpalProvider,
      useOpal,
      OpalEventType,
    } from "@methodfi/opal-react-native";

    export default function App() {
      return (
        <OpalProvider>
          <YourScreen />
        </OpalProvider>
      );
    }

    function YourScreen() {
      const { open } = useOpal({
        env: "dev",
        onOpen: () => {},
        onExit: () => {},
        onEvent: (event) => {
          switch (event.type) {
            case OpalEventType.SESSION_STARTED:
              // ...
              break;
            case OpalEventType.SESSION_COMPLETED:
              // ...
              break;
            case OpalEventType.SESSION_ERRORED:
              // ...
              break;
            case OpalEventType.SESSION_EXITED:
              // ...
              break;
          }
        },
      });

      const onLaunchOpal = async () => {
        const token = await getOpalToken(); // POST /opal/token returns otkn_*
        open({ token });
      };

      return <Button title="Launch Opal" onPress={onLaunchOpal} />;
    }
    ```
  </Tab>
</Tabs>

## Testing in Development

When testing the Opal frontend in the dev environment, any modal step that prompts you to enter a six-digit verification code will accept any six-digit code. For example: `123456`.

## Notes

* Event types follow the format `<flow>.<object>.<action>` or `opal.session.<action>` for defaults
* See [Events](/opal/events) for structure and sample payloads


# Overview
Source: https://docs.methodfi.com/opal/overview

Method Opal - Next-generation embeddable financial components

Method Opal is the single embeddable UI component that provides enhanced
financial connectivity and user experience. Opal serves as a modern replacement
for Method Elements, offering improved performance, better customization, and
advanced features for integrating Method's API into your application.

<img alt="title" />

## What is Opal?

Method's embedded financial platform, with built-in orchestration of
identity, account connection, verification, and transaction streaming- all
in one cohesive experience for end-users.

## Using Method Opal

<Steps>
  <Step title="Create an Entity">
    Create an entity for your user using the
    [Entities](/reference/entities/overview) endpoint.
  </Step>

  <Step title="Create Opal Token">
    Generate an Opal Token by using the [Create Token](/reference/opal/create_token#create-token)
    endpoint.
  </Step>

  <Step title="Launch Opal">
    Using the Opal Token, launch Opal with one of our
    [libraries](/opal/libraries) to launch the intended Opal component for your
    user. Method will handle the rest!
  </Step>

  <Step title="Optional: Handle Opal Events">
    While your user interacts with an Opal component,
    [events](/opal/events) will be triggered for your app to handle.
  </Step>
</Steps>

## Opal Modes

Opal provides several pre-built modes for different use cases:

### [Identity Verification](/opal/identity/overview)

Collect and verify user identity only.

### [Connect](/opal/connect/overview)

Connect user liability accounts.

### [Card Connect](/opal/card_connect/overview)

Verify and connect cards for access to payments.

### [Account Verification](/opal/account_verification/overview)

Verify account ownership with real-time verification.

### [Transactions](/opal/transactions/overview)

Stream transactions for a user's credit cards.

## Understanding Modes and Flows

Opal Modes are typically made up of one or more flows. Modes are the different types of Opal components that can be launched, while flows are the different stages within a mode. For example, the Card Connect mode has a flow for identity verification (`identity_verification`), account selection (`connect`), and verification (`account_verification`).

## Getting Started

Ready to integrate Opal into your application? Start with our [Opal Libraries](/opal/libraries) to choose the right SDK for your platform!

<CardGroup>
  <Card title="Opal Libraries" href="/opal/libraries">
    Choose the right SDK for your platform
  </Card>

  <Card title="API Reference" href="/reference/opal/overview">
    Complete API documentation for Opal endpoints
  </Card>

  <Card title="Events Guide" href="/opal/events">
    Learn how to handle Opal events in your application
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.methodfi.com/opal/quickstart

Get started with Method Opal in minutes

This quickstart guide will help you integrate Method Opal into your application in just a few steps. Opal provides enhanced performance, better security, and advanced features compared to Elements.

## Prerequisites

Before you begin, make sure you have:

* A Method account with API access
* Your Method API key
* A web application or development environment

## Step 1: Install the Opal SDK

Choose the appropriate SDK for your application:

<CodeGroup>
  ```html JavaScript (CDN) theme={null}
  <script src="https://static.methodfi.com/opal/v1/stable/init.js"></script>
  ```

  ```bash React theme={null}
  npm install @methodfi/opal-react
  ```

  ```bash React Native theme={null}
  npm install @methodfi/opal-react-native
  ```
</CodeGroup>

## Step 2: Create an Entity

First, create an entity for your user:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "individual",
      "individual": {
        "first_name": "John",
        "last_name": "Doe",
        "phone": "+15121234567",
        "email": "john.doe@example.com"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const entity = await method.entities.create({
    type: "individual",
    individual: {
      first_name: "John",
      last_name: "Doe",
      phone: "+15121234567",
      email: "john.doe@example.com",
    },
  });
  ```

  ```python Python theme={null}
  entity = method.entities.create({
    'type': 'individual',
    'individual': {
      'first_name': 'John',
      'last_name': 'Doe',
      'phone': '+15121234567',
      'email': 'john.doe@example.com'
    }
  })
  ```
</CodeGroup>

## Step 3: Create an Opal Token

Create an Opal token for the Connect component:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/opal/token \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "entity_id": "ent_fc92i43kc34",
      "mode": "connect",
      "connect": {
        "selection_type": "single",
        "account_filters": {
          "include": {
            "account_types": ["credit_card", "auto_loan"]
          }
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const { token, valid_until, session_id } = await method.opal.token.create({
    entity_id: entity.id,
    mode: "connect",
    connect: {
      selection_type: "single",
      account_filters: {
        include: {
          account_types: ["credit_card", "auto_loan"],
        },
      },
    },
  });
  ```

  ```python Python theme={null}
  res = method.opal.token.create({
    'entity_id': entity.id,
    'mode': 'connect',
    'connect': {
      'selection_type': 'single',
      'account_filters': {
        'include': {
          'account_types': ['credit_card', 'auto_loan']
        }
      }
    }
  })
  ```
</CodeGroup>

## Step 4: Initialize Opal in Your Frontend

<CodeGroup>
  ```html JavaScript (CDN) theme={null}
  <script src="https://static.methodfi.com/opal/v1/stable/init.js"></script>

  <button id="connect-button">Connect Your Account</button>

  <script>
    document
      .getElementById("connect-button")
      .addEventListener("click", async () => {
        // Get token from Method
        const response = await fetch(`${baseURL}/opal/token`, {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({
            entity_id: "ent_fc92i43kc34",
            mode: "connect",
            connect: {
              selection_type: "single",
              account_filters: {
                include: {
                  account_types: ["credit_card", "auto_loan"],
                },
              },
            },
          }),
        });
        const { token } = await response.json();

        // Open iframe with token
        const iframe = document.createElement("iframe");
        iframe.src = `https://opal.${env}$.methodfi.com?token=${token}`;
        iframe.style.width = "100%";
        iframe.style.height = "600px";
        iframe.style.border = "none";
        document.body.appendChild(iframe);
      });
  </script>
  ```

  ```jsx React theme={null}
  import { OpalProvider, useOpal } from "@methodfi/opal-react";

  function App() {
    return (
      <OpalProvider>
        <ConnectButton />
      </OpalProvider>
    );
  }

  function ConnectButton() {
    const { open } = useOpal();

    const handleConnect = async () => {
      // Get token from Method
      const response = await fetch(`${baseURL}/opal/token`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          entity_id: "ent_fc92i43kc34",
          mode: "connect",
          connect: {
            selection_type: "single",
            account_filters: {
              include: {
                account_types: ["credit_card", "auto_loan"],
              },
            },
          },
        }),
      });
      const { token } = await response.json();

      // Launch Opal
      open({ token });
    };

    return <button onClick={handleConnect}>Connect Your Account</button>;
  }
  ```

  ```jsx React Native theme={null}
  import { OpalProvider, useOpal } from "@methodfi/opal-react-native";
  import { Button } from "react-native";

  function App() {
    return (
      <OpalProvider>
        <ConnectButton />
      </OpalProvider>
    );
  }

  function ConnectButton() {
    const { open } = useOpal();

    const handleConnect = async () => {
      // Get token from Method
      const response = await fetch(`${baseURL}/opal/token`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          entity_id: "ent_fc92i43kc34",
          mode: "connect",
          connect: {
            selection_type: "single",
            account_filters: {
              include: {
                account_types: ["credit_card", "auto_loan"],
              },
            },
          },
        }),
      });
      const { token } = await response.json();

      // Launch Opal
      open({ token });
    };

    return <Button title="Connect Your Account" onPress={handleConnect} />;
  }
  ```
</CodeGroup>

## Next Steps

Now that you have Opal working, explore these advanced features:

<CardGroup>
  <Card title="Advanced Configuration" href="/opal/connect/overview">
    Learn about advanced Opal Connect features and configuration options
  </Card>

  <Card title="Event Handling" href="/opal/events">
    Master Opal's comprehensive event system
  </Card>

  <Card title="Migration Guide" href="/opal/migration_guide">
    Migrate from Elements to Opal
  </Card>
</CardGroup>

### Getting Help

* **Documentation**: [Complete Opal Documentation](/opal/overview)
* **API Reference**: [Opal API Reference](/reference/opal/overview)
* **Support**: Contact your Method CSM


# December Updates
Source: https://docs.methodfi.com/changelog/2024/december



## New Features

### New Method Dashboard

<img alt="title" />

We’re thrilled to announce early access to the **all-new Method Dashboard**, purposefully redesigned to harness the full potential of our API’s V2 capabilities.

This intuitive interface is crafted to empower both technical and non-technical team members with:

* Role-based access control
* Advanced data visualization
* Custom reporting capabilities
* Universal search functionality
* Self-service team management
* Key rotation tools
* SSO and Passkey authentication

Everyone across your team can now use the new Method Dashboard:

* **CX** – monitor and troubleshoot any issues associated with end-user data.
* **Engineering** – create API keys and monitor webhooks.
* **Finance** – view high-level metrics to better understand billing.

**How to access?**
Dashboard v2 is available for all teams, including existing ones, ensuring a seamless transition to the new interface.
Log in with your email at [app.methodfi.com](https://app.methodfi.com) to explore the new features!

### Vehicles API

<img alt="title" />

The [Vehicles API](https://docs.methodfi.com/reference/entities/vehicles/overview) enables your application to access detailed vehicle information with minimal PII. This data can help you unlock valuable insights and drive better decision-making.

**Key Use Cases**

* **Increase conversion** with pre-filled vehicle details by optimizing loan repayment terms using the vehicle's depreciation curve.
* **Enhance credit risk underwriting** by leveraging vehicle ownership details.
* **Enable personalized financial management** by correlating vehicle data with user behavior insights.

For example, you can retrieve data such as the vehicle's `VIN`, `year`, `make`, `model`, `color`, and `style`.

The Vehicles API is now available to all teams on Method’s V2 API (version: 2024-04-04). Contact your Method CSM to get access!

***

## Improvements

### Account Verification Limits

To bolster system security and performance, we've introduced new verification limits:

* **Account Verification Session limits**: Up to 10 failed attempts per session.
* **Account-level verification limits**:
  * Maximum of 5 sessions per verification type.
  * Maximum of 10 total sessions across all types.

For more details, visit [Account Verification Sessions Errors](https://docs.methodfi.com/reference/errors/account-verification-session-errors).

***

## SDK Updates

* Released [version 1.1.5](https://github.com/MethodFi/method-python/releases/tag/v1.1.5) of `method-python`.
  * [Vehicles API](https://docs.methodfi.com/reference/entities/vehicles/overview) is now available in `method-python`.
* Released [version 1.1.6](https://github.com/MethodFi/method-node/releases/tag/v1.1.6) of `method-node`.
  * [Vehicles API](https://docs.methodfi.com/reference/entities/vehicles/overview) is now available in `method-node`.


# November Updates
Source: https://docs.methodfi.com/changelog/2024/november



## New Features

### Payment Posted Confirmation

<img alt="title" />

We’re excited to announce [`posted`](https://docs.methodfi.com/reference/payments/overview#possible-enum-values:~:text=The%20Payment%20has%20been%20posted%20to%20the%20destination%20Account), a new payment status that closes the loop on payments by confirming when they have successfully landed in your users’ accounts.

With **real-time account data**, Method now provides a level of visibility that was previously unavailable in the U.S. financial system. By knowing if and when a payment has been applied, you can deliver timely and actionable updates to your users—boosting confidence and creating a seamless payment experience.

**Key highlights:**

* **Enabled for all payments**: The feature is live for all teams and payments processed via Method’s V2 API (version: `2024-04-04`) going forward.
* **No action required**: Start using this feature immediately—just consume the new status in your integration.
* **75% coverage**: We expect approximately 75% visibility into posted status, with improved coverage as more accounts are subscribed to updates.
* **Unlock new use cases**: Use the posted status to notify users via push notifications, emails, or in-app messages, keeping them informed and engaged.
* **Account subscription required**: In a future release, the posted status will only be available for accounts subscribed to updates.

### New Method Brand

<img alt="title" />

We’re excited to introduce Method’s new visual identity, marking a new chapter in our journey under the same thesis we had on day one: consumer financial data is a walled garden, and we’re going to be the ones to open it up.

The updated design features:

* A new icon and wordmark
* A refined color palette centered around Method Opal: a bold, fresh, and vibrant cyan
* A new [website](https://methodfi.com/)

Read more about the redesign [here](https://methodfi.com/blog/rebranding-method).

***

## Improvements

### Detailed Webhook Errors

[Webhook Errors](https://docs.methodfi.com/reference/errors/webhook-errors) now includes detailed explanations of issues that caused your webhook to be disabled.

Webhook objects now feature an `error` field following the common Method error format. The error codes for webhook errors are:

* 25001 – `WEBHOOK_DISABLED_FAILED_OTHER`: Indicates five consecutive failures not classified as 4XX, 5XX, or timeouts.
* 25002 – `WEBHOOK_DISABLED_RECEIVED_4XX_ERROR`: The endpoint returned client errors (4XX) five times.
* 25003 – `WEBHOOK_DISABLED_RECEIVED_5XX_ERROR`: The endpoint returned server errors (5XX) five times.
* 25004 – `WEBHOOK_DISABLED_TIMEOUT_ON_RESPONSE`: No valid response received within 5 seconds for five consecutive attempts.

### New List Endpoints

We’ve expanded our API capabilities by introducing list functionality for the following resources, allowing you to retrieve comprehensive collections, such as all updates or credit scores, for a specific account or entity.

* [Attributes](https://docs.methodfi.com/reference/entities/attributes/list)
* [Credit Scores](https://docs.methodfi.com/reference/entities/credit-scores/list)
* [Connects](https://docs.methodfi.com/reference/entities/connect/list)
* [Identities](https://docs.methodfi.com/reference/entities/identities/list)
* [Entity Verification Sessions](https://docs.methodfi.com/reference/entities/verification-sessions/list)
* [Card Brands](https://docs.methodfi.com/reference/accounts/card-brands/list)
* [Account Updates](https://docs.methodfi.com/reference/accounts/updates/list)
* [Payoffs](https://docs.methodfi.com/reference/accounts/payoffs/list)
* [Sensitive](https://docs.methodfi.com/reference/accounts/sensitive/list)
* [Account Balances](https://docs.methodfi.com/reference/accounts/balances/list)
* [Account Verification Sessions](https://docs.methodfi.com/reference/accounts/verification-sessions/list)

### Elements API

* Removed the ability to pass in `card_brand` in the `products` array when creating an [Element Token](https://docs.methodfi.com/reference/elements/tokens).

***

## SDK Updates

* Released [version 1.1.4](https://github.com/MethodFi/method-python/releases/tag/v1.1.4) of Method Python client (`method-python`).
  * All new `list` endpoints are now available in the Python client.
  * Added `posted` as an enum value for the `payment.status` field.
* Released [version 1.1.5](https://github.com/MethodFi/method-node/releases/tag/v1.1.5) of Method Node.js client (`method-node`).
  * All new `list` endpoints are now available in the Node.js client.
  * Added `posted` as an enum value for the `payment.status` field.


# October Updates
Source: https://docs.methodfi.com/changelog/2024/october



## New Products

### Events API

<img alt="title" />

The [Events API](https://docs.methodfi.com/reference/events/overview) allows your application to monitor specific changes to Method resources.

* For example, you can now be notified when an entity's credit score increases (event type: `credit_score.increased`)
  or if new derogatory marks appear (event type: `attribute.credit_health_derogatory_marks.increased`)

* Events deliver detailed and actionable notifications across all Method products and resources, making webhooks more targeted and specific.
  This ensures you receive alerts for the updates that matter to your application and users.

* Events are classified into two types:
  * Literal changes: Direct updates to a specific field in a resource.
  * Computed changes: Interpreted states derived from multiple field changes or comparisons across different records.

* The Events API is now available to all teams on Method’s V2 API (version: 2024-04-04). This launch includes 10 initial events, with over 100 additional events planned for release in the coming weeks.

### Attributes API

<img alt="title" />

The [Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview) offers a powerful summary of financial profile metrics across all Method API resources.

* For example, it provides real-time indicators on credit utilization, payment reliability, account age, and derogatory marks, allowing developers to access these metrics directly without piecing together data from multiple endpoints.

* Powered by Method’s real-time data integrations, it provides up-to-date insights ensuring your application accesses the most current data for faster, more informed decisions.

* This initial release emphasizes credit health attributes, offering a holistic view of financial stability and risk.

* For information on accessing the Attributes API, please reach out to your Method CSM.

***

## Improvements

### Card Brands API

* Improved our card network integrations (Visa and Mastercard) to deliver lower latencies on Card Brands API requests.
* Expanded coverage across all card products, including providing a reliable unique ID associated with each card product (for example all Chase Sapphire Reserve's across all entities will return the same brand ID)
  * Brand ID is returned within `card_brand.brands[x].id` in the format `brand_*`.

### Credit Scores API

* We've upgraded our Credit Scores API to use VantageScore 4.0, the latest version of the scoring model.
* VantageScore 4.0 provides more predictive scoring by incorporating machine learning techniques and trended credit data, which analyzes credit behaviors over time rather than just a snapshot.
* This upgrade enables more accurate credit risk assessment, especially for consumers with limited credit history.

***

## SDK Updates

* Released [version 1.1.2](https://github.com/MethodFi/method-python/releases/tag/v1.1.2) of Method Python client (`method-python`).
  * [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview) is now available in the Python client.
  * [Events API](https://docs.methodfi.com/reference/events/overview) is now available in the Python client.
* Released [version 1.1.3](https://github.com/MethodFi/method-node/releases/tag/v1.1.3) of Method Node.js client (`method-node`).
  * [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview) is now available in the Node.js client.
  * [Events API](https://docs.methodfi.com/reference/events/overview) is now available in the Node.js client.
* Released [version 2 of Method API Postman Collection](https://www.postman.com/methodfi/method-api/collection/8d5j00b/method-api-v2).


# September Updates
Source: https://docs.methodfi.com/changelog/2024/september



## Improvements

### Performance & Infrastructure

* Improved idempotency locking mechanism to handle simultaneous idempotent requests received across different regions / PoP.
* Under-the-hood liability payment rail improvements to faster settlement time across all major FIs.
* Card Brand has been optimized for increased success speed.
* Expanded checks for invalid update payload from upstream data providers.

### Payment Coverage

* Released new integration with SoFi Personal Loans for near real-time payment settlement speed.
* Payment channels for Sallie Mae, US Bank, and AMEX have been revamped and optimized for speed of posting.
* Additional personal loan payment channels have been enabled - improving payment coverage and speed to posting.
* BMO Harris credit cards are now fully payable when account is connected via Method Connect.

### Developer Experience

* `micro_deposits` verification sessions are now simulatable in dev.
* Speed of `micro_deposists` simulation in dev environment has been increased.
* Expanded Card Brand simulated response in dev environment.
* Improved Student Loans [updates](https://docs.methodfi.com/reference/accounts/updates/overview) documentation for dev environment responses.
* Element now throws an error if any of the requested products are not enabled for the requesting team.

### Account Connectivity

* Improved account update stability for Quicken Loans, Home Depot (Citi), Credit One, and other major FIs.
* "Instant Link" verification was optimized across all networks.
* Visual interaction during the manual Connect Element flow have been streamlined to optimize for conversion.

### Reporting

* Daily emailed reconciliation reports now include the team name in the subject line.
  * e.g. (`Method: Daily ACH Report`) -> (`Method: Daily ACH Report for ${team_name}`)

***

## SDK Updates

* Released [version 1.1.0](https://github.com/MethodFi/method-python/releases/tag/v1.1.0) of Method Python client (`method-python`).
  * [Request ID](/reference/request-id) is now easily accessible via the `last_response` property - we highly recommend logging the request ID for faster issue resolution.
  * This update also includes security updates and test coverage expansion.
* Released [version 1.1.1](https://github.com/MethodFi/method-node/releases/tag/v1.1.1) of Method Node.js client (`method-node`).
  * [Request ID](/reference/request-id) is now easily accessible via the `last_response` property - we highly recommend logging the request ID for faster issue resolution.
  * This update also includes security updates and test coverage expansion.


# April Updates
Source: https://docs.methodfi.com/changelog/2025/april



## New Features

### Dashboard Updates

<img alt="sso" />

We're continuing to improve the Dashboard experience with a few powerful updates:

* **SSO Support** – You can now log in using Single Sign-On. Reach out to your Method CSM to enable SSO for your team.
* **Multi-Team Search** – If you're a member of multiple teams, you can now quickly search and switch between them with ease.
* **PDF Export** – It is now possible to download Entity and Account details as a PDF. Contact your Method CSM to get access to this feature.

## Improvements

### Entity Attribute Handling

We've updated how Entity Attributes are requested. You must now explicitly specify which attributes you'd like to retrieve using a new payload format.

<Warning>Some attributes are restricted by default. Reach out to your Method CSM to get access to these attributes.</Warning>

<Accordion title="Previous">
  ```js theme={null}
  const response = await method
      .entities('ent_TYHMaRJUUeJ7U')
      .attributes
      .create();
  ```
</Accordion>

<Accordion title="New">
  ```js theme={null}
  const response = await method
      .entities('ent_TYHMaRJUUeJ7U')
      .attributes
      .create({
          attributes: [
              "credit_health_credit_card_usage",
              "credit_health_derogatory_marks",
              "credit_health_hard_inquiries",
              "credit_health_soft_inquiries",
              "credit_health_total_accounts",
              "credit_health_credit_age",
              "credit_health_payment_history",
              "credit_health_open_accounts",
              "credit_health_entity_delinquent"
          ]
      });
  ```
</Accordion>

For more details, refer to the [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/create).

### Entity Subscription Creation

Entity subscription creation has been updated to support a new payload format.

<Accordion title="Previous">
  ```js theme={null}
  const response = await method
    .entities('ent_TYHMaRJUUeJ7U')
    .subscriptions
    .create('credit_score');
  ```
</Accordion>

<Accordion title="New">
  ```js theme={null}
  const response = await method
    .entities('ent_TYHMaRJUUeJ7U')
    .subscriptions
    .create({
      enroll: 'credit_score',
    });
  ```
</Accordion>

To enroll in an Entity Attribute subscription, use this format:

```js theme={null}
const response = await method
  .entities('ent_TYHMaRJUUeJ7U')
  .subscriptions
  .create({
    enroll: 'attribute',
    payload: {
      attributes: {
        requested_attributes: [
            'credit_health_credit_card_usage', 
            'credit_health_derogatory_marks'
        ]
      }
    }
  });
```

For more details, refer to the [Entity Subscriptions API](https://docs.methodfi.com/reference/entities/subscriptions/create).

## SDK Updates

* Released [version 1.1.14](https://github.com/MethodFi/method-node/releases/tag/v1.1.14) of `method-node`
* Released [version 1.1.13](https://github.com/MethodFi/method-python/releases/tag/v1.1.13) of `method-python`


# August Updates
Source: https://docs.methodfi.com/changelog/2025/august



## New Features

### Opal

<img alt="opal" />

We're excited to introduce [Opal](/opal/overview), our new embedded UI that can easily be dropped into your existing onboarding flow, enabling a white-labeled, seamless connection to Method. It replaces our current Element UI, allowing you to customize the copy, themes, and other UI components to maintain continuity in your interface and prevent users from feeling like they are moving to a third-party app.

Opal has four different components:

* **Identity Verification (IDV):** collects, confirms, and verifies a user’s identity
* **Connect (CXN):** surfaces all of a user's liability accounts
* **Account Verification (AVF):** verifies credit card details and tokenizes them for payments and checkout use cases
* **Transactions (TXN):** enables users to select cards that they wish to link transaction data

**How it works:**

* Opal is a drop-in SDK, designed for quick and easy integration with minimal effort to implement
* Launch with a single token that’s generated with a mode (e.g., connect, card connect, etc.) and whatever additional parameters you choose
* Once launched, Method handles all of the business logic of the flow, automatically orchestrating all of the information the user needs to provide and determining what part of the flow to route the user to next
* Tokens are persistent - users can pick up exactly where they dropped off
* UI is embedded via JavaScript, React, or React Native

For more information, please visit the [Opal Quickstart](/opal/quickstart) page.


# December Updates
Source: https://docs.methodfi.com/changelog/2025/december



## New features

### Payment Instruments API

Method now supports inbound funding workflows. We’ve added a new `PaymentInstrument` type: `inbound_achwire_payment` which allows liability accounts (e.g., loans, credit cards) to receive direct payments via ACH or wire transfer.

* This feature provisions a unique virtual account number and routing number linked to a specific Method Account, effectively making the underlying liability routable. Third parties can send funds directly to these credentials, and Method automatically applies the funds to the associated account, without requiring you to explicitly create a Payment.

**How it works:**

1. **Create Instrument**: Create a Payment Instrument of type `inbound_achwire_payment` for a specific Method Account
2. **Receive Banking Details**: Method returns unique `account_number` and `routing_number`
3. **Share with a Third Party**: Provide these banking details to a third party (e.g., payroll provider, refinance lender, or another bank)
4. **Inbound Transfer**: When funds are sent to these credentials, Method receives the inbound ACH or wire transfer
5. **Automatic Application**: Method automatically applies the received funds to the associated account

<Note>Available when passing `Method-Version: 2025-12-01` in the request header.</Note>

## Improvements

### Simulate API

The [Simulate API](/reference/simulations/overview) now supports retrieving micro-deposit amounts and simulating inbound ACH / wire payments for inbound\_achwire\_payment Payment Instruments — making it easier for developers to test account verification and inbound payment flows in the development environment.

**[Retrieve Micro-deposit Amounts](/reference/simulations/verification-sessions/get-microdeposit-amounts)**

* This endpoint enables developers to retrieve the exact micro-deposit amounts required to complete ACH account verification flows in the development environment.

**[Simulate Inbound ACH/Wire Payments](/reference/simulations/payment_instruments/create)**

* This endpoint allows developers to simulate receiving an inbound payment and triggers the same automatic payment application logic used in production.

<Warning>This API is available in the development environment only.</Warning>

For more information, visit the [Simulations API](/reference/simulations/overview) documentation.

### Webhooks

We added support for a new webhook event type: `account.number.update`.

* This account-level webhook is triggered when an account number has been updated, allowing developers to be notified of account number changes without polling.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Entities API

The Entities API now supports updating `metadata` via `PUT /entities/{ent_id}`.

* This enables developers to update an Entity's metadata without recreating the Entity, simplifying lifecycle management.

For more information, please refer to the [Update an Entity](/reference/entities/update-entity) documentation.


# February Updates
Source: https://docs.methodfi.com/changelog/2025/february



## New Features

### Dashboard Payment Details Page

<img alt="payment details" />

We've upgraded the Payments experience with a brand-new dedicated Payment Details Page

Now, you get more insights and control than ever before:

* **Payment Timeline** –> Track the full journey of your payments, end to end.
* **Enhanced Payment Info** –> Quickly see whether a payment was made via electronic or paper.
* **Check Images** –> For paper payments, view the check image (if available) directly within the details page.

## Improvements

### Payments API

We've added two new fields to the Payments API to provide better visibility into payment details:

* `destination_payment_method`: Indicates how the payment was delivered to the recipient - either `electronic` or `paper`
* `destination_status`: New status `cashed` available to track when paper checks have been processed

For more information, see our [Payments API documentation](https://docs.methodfi.com/reference/payments/overview).

## SDK Updates

* Released [version 1.1.9](https://github.com/MethodFi/method-python/releases/tag/v1.1.9) of `method-python`
* Released [version 1.1.10](https://github.com/MethodFi/method-node/releases/tag/v1.1.10) of `method-node`


# January Updates
Source: https://docs.methodfi.com/changelog/2025/january



## New Features

### Account Attributes API

<img alt="account attributes" />

We've released a brand new [Account Attributes API](https://docs.methodfi.com/reference/accounts/attributes/overview) that's powered by Method's real-time data integrations for up-to-date insights. It provides:

* Real-time indicators for individual account usage patterns
* Account utilization metrics
* Account standing information
* Delinquency data (period, outcome, and amount)

For access to the Account Attributes API, please contact your Method CSM.

## Improvements

### Entity Attributes API

We've enhanced the [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview) with two new attributes:

* `credit_health_open_accounts`: Total number of open accounts
* `credit_health_entity_delinquent`: Entity delinquency status, rating and a list of delinquent accounts

**Pro tip**: Leverage both the Account Attributes API and the Entity Attributes API to get a holistic view of an entity's credit health.

### Method Dashboard

We've made significant performance and usability improvements to the [Method Dashboard](https://app.methodfi.com):

* Pages load 3x faster. We also made navigating between pages feel a lot better.
* Charts load 2x faster. We also fixed hovering over the bars so it works well.
* Universal Search is now keyboard navigable. You can use your up/down arrows and hit enter.
* Added the ability to right click on a table row and open it in a new tab.
* Created better financial account logos. We will continue to fix bad ones.
* Changed the layout of information on details pages to make reading easier.

Please reach out in Slack with any feedback. We will put your requests at the top of our to-do list.

### Payment Dry-run

We've added a new `dry_run` boolean flag to the `POST /payments` endpoint. When enabled, it will simulate a payment without triggering the actual payment flow. You'll receive accurate information about the payment timeline, helping you preview the payment flow and communicate accurate timing to your users before initiating an actual payment. For more information, see our [Payments API](https://docs.methodfi.com/reference/payments/overview).

## SDK Updates

* Released [version 1.1.8](https://github.com/MethodFi/method-python/releases/tag/v1.1.8) of `method-python`
* Released [version 1.1.9](https://github.com/MethodFi/method-node/releases/tag/v1.1.9) of `method-node`


# July Updates
Source: https://docs.methodfi.com/changelog/2025/july



## New Features

### Message-Level Encryption (MLE)

<img alt="MLE" />

We’ve added support for end-to-end encryption of sensitive data transmitted between your application and Method’s API, available to everyone. Here’s what’s new:

* **Hybrid Encryption:** Uses AES-GCM (for payload encryption) and RSA-OAEP-256 (for key encryption) to ensure confidentiality even if network traffic is intercepted.

* **Public Key Registration:** Register your RSA public key with Method via a `.well-known` endpoint or direct upload.

* **Encrypted Requests & Responses:** Send encrypted payloads using the `Method-MLE: jwe` header; Method encrypts responses using your public key.

* **Key Management:** Support for key rotation, deprecation, deletion, and webhook notifications for Method key changes.

You can find a [quickstart guide here](/reference/message-level-encryption#quickstart). For more information, please refer to the [Message Level Encryption documentation](/reference/message-level-encryption).

### Card Brand API

<img alt="Card Brands" />

We’ve expanded the Card Brand object to provide a more structured format with richer brand details — making it easier to identify, display, and integrate specific card products with consistent issuer, network, and branding data.

<Note>Available when passing `Method-Version: 2025-07-04` in the request header.</Note>

<Accordion title="Previous">
  ```json theme={null}
  {
    "id": "cbrd_eVMDNUPfrFk3e",
    "account_id": "acc_yVf3mkzbhz9tj",
    "network": "visa",
    "issuer": "Chase",
    "last4": "8623",
    "brands": [
      {
        "id": "brand_AMxtjQzAfDCRP",
        "name": "Chase Sapphire Reserve",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
      }
    ],
    "status": "completed",
    "shared": false,
    "source": "network",
    "error": null,
    "created_at": "2024-03-19T01:05:37.247Z",
    "updated_at": "2024-03-19T01:05:37.247Z"
  }
  ```
</Accordion>

<Accordion title="New">
  ```json theme={null}
  {
    "id": "cbrd_Accm7P6t6mYQP",
    "account_id": "acc_LxwEqNicr66yP",
    "brands": [
      {
        "id": "pdt_15_brd_1",
        "card_product_id": "pdt_15",
        "description": "Chase Sapphire Reserve",
        "name": "Chase Sapphire Reserve",
        "issuer": "Chase",
        "network": "visa",
        "network_tier": "infinite",
        "type": "specific",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
      }
    ],
    "status": "completed",
    "source": "method",
    "error": null,
    "created_at": "2025-08-12T00:56:50.139Z",
    "updated_at": "2025-08-12T00:56:50.139Z"
  }
  ```
</Accordion>

**Key Changes**:

* `network` and `issuer` are now nested inside each brand object.
* Added `card_product_id`, `description`, and `type` fields.
* Removed `last4` and `shared` fields.

For more information, please refer to the [Card Brand API](/reference/accounts/card-brands/overview).

### Card Products API

We've added a new `Card Products` directory accesible via our API allowing you to retrieve all `Card Brand` objects associated with a given `Card Product`.

<Note>Available when passing `Method-Version: 2025-07-04` in the request header.</Note>

<Accordion title="Example Request">
  ```bash cURL theme={null}
  curl https://production.methodfi.com/card_products/pdt_17 \
    -H "Method-Version: 2025-07-04" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```
</Accordion>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "pdt_17",
    "name": "Chase Freedom",
    "issuer": "Chase",
    "type": "specific",
    "brands": [
      {
          "id": "pdt_17_brd_1",
          "description": "Chase Freedom",
          "network": "visa",
          "network_tier": "signature",
          "default_image": "https://static.methodfi.com/card_brands/fb5fbd6a5d45b942752b9dc641b93d1f.png"
      },
      {
        "id": "pdt_17_brd_2",
        "description": "Chase Freedom",
        "network": "visa",
        "network_tier": "standard",
        "default_image": "https://static.methodfi.com/card_brands/6cb697528b0771f982f7c0e8b8869de3.png"
      }
    ]
  }
  ```
</Accordion>

For more information, please refer to the [Card Products API](/reference/card-products/overview).

## Improvements

### Connect API

We now support asynchronous Connect requests. You'll receive a `connect.available` webhook when an Async Connect is completed. Async Connect requests can be created by either:

* Setting the `Prefer: respond-async` header
* Specifying `products` and / or `subscriptions` in the request body

The Connect object will now include `requested_products` and `requested_subscriptions` fields in the response body.

<Accordion title="Example Request">
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/connect \
    -X POST \
    -H "Prefer: respond-async" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -d '{
      "requested_products": ["card_brand"],
      "requested_subscriptions": ["card_brand"]
    }'
  ```
</Accordion>

<Accordion title="Example Response after Connect is completed">
  ```json theme={null}
  {
    "id": "cxn_4ewMmBbjYDMR4",
    "entity_id": "ent_qKNBB68bfHGNA",
    "status": "completed",
    "accounts": [
      "acc_eKKmrXDpJBKgw",
      "acc_GV8WbmJW7KGRy",
      "acc_MLPKh9gQDDbT8",
      "acc_LbXE8wVYJLrKt",
      "acc_J3P9fayDFjpAy",
      "acc_eFFRV9zmpLREK"
    ],
    "requested_products": ["card_brand"],
    "requested_subscriptions": ["card_brand"],
    "error": null,
    "created_at": "2024-04-12T14:56:46.645Z",
    "updated_at": "2024-04-12T14:56:46.645Z"
  }
  ```
</Accordion>

For more information, please refer to the [Connect API](/reference/entities/connect/overview).

### Webhook API

We've added a new `refs` object to webhook payloads. This object contains the `entity` ID of the Entity that the webhook is related to.

<Accordion title="Example Webhook Payload">
  ```json theme={null}
  {
    "webhook_id": "whk_cSGjA6d9N8y8R",
    "id": "pmt_zR3nJG3c99P3X",
    "type": "payment.update",
    "op": "update",
    "path": "/payments/pmt_zR3nJG3c99P3X",
    "event": "evt_knqJgxKUnqDVJ",
    "refs": {
      "entity": "ent_qKNBB68bfHGNA"
    }
  }
  ```
</Accordion>

We have also added the following new webhooks:

* `card_brand.available`
* `connect.available`
* `method_jwk.create`
* `method_jwk.update`

For more information, please refer to the [Webhooks API](/reference/webhooks/overview).

### Entity and Account Products

The `product_id` field in the `Product` object and the Retrieve endpoint are now deprecated. We've added the `latest_successful_request_id` field to the `Product` object. This field will contain the ID of the most recently successful Product resource.

For more information, please refer to the [Entity Products API](/reference/entities/products/overview) and [Account Products API](/reference/accounts/products/overview).


# June Updates
Source: https://docs.methodfi.com/changelog/2025/june



## New Features

### Webhook HMAC Signature Verification

We’ve added support for HMAC-SHA256 signatures to further secure your webhook integrations. Here's what's new:

* **Signed Webhooks:** When you provide an `hmac_secret` during webhook registration, Method now includes a `method-webhook-signature` header on each webhook request. This signature is an HMAC-SHA256 digest, computed using your `hmac_secret` as the shared secret and the message format `${method-webhook-timestamp}:${raw_payload}`.

* **Timestamp Header:** Every webhook request now includes a `method-webhook-timestamp` header (UNIX timestamp in seconds), allowing you to validate the freshness of requests and prevent replay attacks.

* **Verification:** You can verify the webhook by recreating the HMAC digest locally and comparing it using a timing-safe equality check.

For more information, please refer to the [Webhook API](/reference/webhooks/overview).

## Improvements

### Connect API

* **Automatic Execution of Account Products and Subscriptions:** You can now optionally include `products` and `subscriptions` arrays in the request body when creating a `Connect` for an entity. These will automatically execute upon a successful connection.

* **Expand Query Parameter:** A new `expand` query parameter has been added to the `Connect` object, allowing you to include additional properties within the `accounts` object.

<Accordion title="Example Request">
  ```js theme={null}
  const connect = await method
      .entities('ent_TYHMaRJUUeJ7U')
      .connect
      .create(
          {
              products: ['attribute', 'card_brand'],
              subscriptions: ['card_brand', 'transaction'],
          }, 
          {
              expand: ['accounts.update']
          }
      );
  ```
</Accordion>

For more information, please refer to the [Connect API](https://docs.methodfi.com/reference/entities/connect/overview) and [Expanding Resources](/reference/expanding).

## SDK Updates

* Released [version 1.2.4](https://github.com/MethodFi/method-node/releases/tag/v1.2.4) of `method-node`
* Released [version 1.2.4](https://github.com/MethodFi/method-python/releases/tag/v1.2.4) of `method-python`


# March Updates
Source: https://docs.methodfi.com/changelog/2025/march



## New Features

### Transactions API

<img alt="transactions" />

We’re excited to launch our new [Transactions API](https://docs.methodfi.com/reference/accounts/transactions/overview) which gives real-time notifications directly from the card networks on credit/debit card purchases. Key benefits include:

* **Real-Time Alerts** -> Instantly notify users about new charges.
* **Intelligent Categorization** -> Automatically categorize spending using merchant category codes (MCCs).
* **Enhanced Security** -> Flag unusual transactions and identify spending in unfamiliar locations.
* **Multi-Currency Support** -> Monitor transactions in both USD and foreign currencies.
* **Refund Visibility** -> Gain complete insight into refund statuses.

For access to the Transactions API, please contact your Method CSM.

### Payment Instruments API

Our new [Payment Instruments API](https://docs.methodfi.com/reference/accounts/payment-instruments/overview) enables you to create and retrieve card credentials for checkout processes. This API provides seamless access to card details and network tokens, streamlining payment experiences across your app or platform.

For access to the Payment Instruments API, please contact your Method CSM.

### Simulate Credit Scores API

In `development` environments, you can now leverage the [Simulate Credit Scores API](https://docs.methodfi.com/reference/simulations/credit-scores/create) to simulate custom credit scores. This feature lets you:

* Simulate scores for test entities.
* Customize score values, sources, and models.
* Include contributing factor data for more realistic testing scenarios.

## Improvements

### Entity Attributes API

We've made significant improvements to the [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview).

* **Credit Health Hard Inquiries**: The `credit_health_hard_inquiries` attribute now includes two additional fields in its metadata history:
  * `institution_name`: Identifies the institution that performed the inquiry.
  * `inquiry_date`: Provides the date the inquiry occurred.
* **New Soft Inquiries Attribute**: A new `credit_health_soft_inquiries` attribute has been added. It mirrors the structure of hard inquiries to consistently track soft credit checks along with the associated institution name and inquiry date.

### Updates API

The [Updates API](https://docs.methodfi.com/reference/accounts/updates/overview) response now includes a new field:

* `data_as_of`: A timestamp indicating when the data in the record was last confirmed to be accurate, providing clear insight into the freshness and reliability of the information returned.

### Card Brands API

The [Card Brands API](https://docs.methodfi.com/reference/accounts/card-brands/overview) is now subscribable. This enhancement allows your system to automatically receive updated card brand information in real time. For example, if a user loses their card and receives a new one, the API will promptly reflect these changes, ensuring that your records are always accurate and up to date.

### Accounts API

We've expanded the [Accounts API](https://docs.methodfi.com/reference/accounts/overview) to support additional account types:

* `BNPL` (Buy Now, Pay Later)
* `Fintech`

### Account Verification Sessions API

The [Account Verification Sessions API](https://docs.methodfi.com/reference/accounts/verification-sessions/overview) now supports the `network` verification type. For more information, please see the [Network Verification Sessions API reference](https://docs.methodfi.com/reference/accounts/verification-sessions/update-network).

## SDK Updates

* Released [version 1.1.13](https://github.com/MethodFi/method-node/releases/tag/v1.1.13) of `method-node`
* Released [version 1.1.12](https://github.com/MethodFi/method-python/releases/tag/v1.1.12) of `method-python`


# May Updates
Source: https://docs.methodfi.com/changelog/2025/may



## Improvements

### Transactions API

A new `merchant` property has been added to the `Transaction` object. This field provides the merchant name and logo associated with each transaction.

<Warning>This property is not available by default. You can enable it by contacting your Method CSM.</Warning>

For more information, please refer to the [Transactions API](https://docs.methodfi.com/reference/accounts/transactions/overview).

### Card Brand API

The `CardBrand` object now includes a `source` property. Possible values are:

* `method` – sourced from Method’s internal systems

* `network` – retrieved directly from the card network

* `null` – source is unavailable

For more information, please refer to the [Card Brand API](https://docs.methodfi.com/reference/accounts/card-brands/overview).

## SDK Updates

* Released [version 1.2.2](https://github.com/MethodFi/method-node/releases/tag/v1.2.2) of `method-node`
* Released [version 1.2.2](https://github.com/MethodFi/method-python/releases/tag/v1.2.2) of `method-python`


# November Updates
Source: https://docs.methodfi.com/changelog/2025/november



## Improvements

### Simulate API

The [Simulate API](/reference/simulations/overview) now supports simulating Card Brand subscription behaviors.

**[Simulate Card Brand API](/reference/simulations/card-brands/create)**

* Card Brand simulations let developers designate a card brand for an account with an active Card Brand Subscription by specifying a `brand_id`. This triggers a `card_brand.available` webhook containing the ID of the designated card brand, allowing developers to test card brand-driven workflows in the development environment.

<Warning>This API is available in the development environment only.</Warning>

For more information, visit the [Simulations API](/reference/simulations/overview) and [Card Brand API](/reference/accounts/card-brands/overview) documentation.


# October Updates
Source: https://docs.methodfi.com/changelog/2025/october



## Improvements

### Accounts API

The [Accounts API](/reference/accounts/overview) now includes a new `sub_type` field under the `liability` object. This field provides additional context about a liability account by specifying its sub-type (for example, distinguishing between a `secured` and `unsecured` `personal_loan`).

For more information, please see <a href="/reference/accounts/overview#account-liability-sub-types">Account Liability Sub-Types.</a>

## SDK Updates

* Released [version 2.0.0](https://github.com/MethodFi/method-node/releases/tag/v2.0.0) of `method-node`
* Released [version 2.0.0](https://github.com/MethodFi/method-python/releases/tag/v2.0.0) of `method-python`

These major releases include default support for the **`2025-07-04` API version**, which introduces the new [Card Products API](/changelog/api-versions/2025-07-04) and updated [Card Brand schema](/changelog/api-versions/2025-07-04#card-brand-api).

See the [2025-07-04 API Version](/changelog/api-versions/2025-07-04) for more details.


# September Updates
Source: https://docs.methodfi.com/changelog/2025/september



## New Features

### Dashboard Updates

**Card Brands Directory**

<img alt="card brands directory" />

We released a new tab in the Method Dashboard – Card Brands – displaying Method's proprietary catalog of credit card brands and metadata. This dataset underpins the Card Brands API, which enables exact 1:1 product matching for each credit card in a user’s wallet, meaning you can identify the specific card brand a user is holding. For example, instead of just knowing a user holds a Chase Visa, you can determine if they hold a Chase Sapphire Reserve, Freedom Unlimited, or any co-branded product.

For access to the Card Brands Directory, please contact your Method CSM.

**New Role: Restricted Member**

You can now invite teammates as a Restricted Member. This role is the same as the Member role, except Restricted Members have no access to view end-users PII.

## Improvements

### Simulate API

The [Simulate API](/reference/simulations/overview) now supports simulating Connect and Attributes behaviors for an entity — making it easier for developers to test how Method responds to various data changes without needing to trigger them in production.

**[Simulate Connect API](https://docs.methodfi.com/reference/simulations/connect/create)**

* You can now configure Connect behaviors such as new\_credit\_card\_account. This is useful when testing account-creation flows or verifying how your system handles new data returned from a subsequent Connect. For example, after configuring this behavior, the next time you execute Connect for that entity, a new credit card account will appear in the response — helping you simulate real-world user events like a customer opening a new card.

**[Simulate Attributes API](https://docs.methodfi.com/reference/simulations/attributes/create)**

* Similarly, you can configure Attribute behaviors such as new\_soft\_inquiry to test how your system reacts to changing credit attributes. On the next Attributes request for that entity, the configured behavior will be applied (e.g., a new soft inquiry will be present).

<Warning>This API is available in the development environment only.</Warning>

These new simulation capabilities give you greater control when testing entity lifecycle scenarios and verifying downstream logic — without needing real production data or user actions.

For more information, visit the [Simulations API](/reference/simulations/overview) documentation.


# April Updates
Source: https://docs.methodfi.com/changelog/2026/april



## New Features

### Attributes V2: Entity & Account Attributes

A new version of the [Attributes API](/reference/entities/attributes/overview) introduces 50+ new computed attributes across both Entities and Accounts, giving you a more complete, up-to-date picture of a user's financial health:

* **Utilization & Credit Health**: See a user's credit utilization broken out by account type, with 30/60/90-day trend lines and delta calculations that show whether utilization is rising or falling over time. Includes delinquency flags and payment-to-minimum ratios that help identify users who may be falling behind.
* **Balance & Debt Movement**: Track how balances are changing across a user's full liability portfolio with 30/60/90-day balance change attributes. Understand whether a user is paying down debt or accumulating it, across credit cards, personal loans, mortgages, and installment accounts.
* **Cost of Debt**: Weighted average APR calculations across liability types help you understand what a user is actually paying in interest, useful for refinance targeting, rate optimization, and cross-sell opportunities.
* **Payment Behavior**: Monthly installment estimates, minimum payment totals, and autopay detection give visibility into how a user is managing their obligations and whether they're likely to stay current.

V2 attributes are available at both the Entity level (aggregated across all of a user's accounts) and the Account level (per-account metrics). V2 attributes support webhook delivery and subscriptions, and can be simulated in the development environment via the [Simulations API](/reference/simulations/attributes/create).

For more information, visit the [Attributes API](/reference/entities/attributes/overview) documentation.

### Opal Embeddable Mode

[Opal](/opal/overview) now supports a fully embeddable rendering mode for JavaScript and React integrations. The new embeddable mode allows Opal to be rendered inline within your application's DOM rather than in a modal overlay, giving you full control over layout and positioning.

* **React SDK**: The `@methodfi/opal-react` package has been updated to v1.5.0 with embeddable mode support.
* **JavaScript SDK**: Native JavaScript integrations can now pass `mode: "embeddable"` when initializing Opal.

For more information, visit the [Opal Libraries](/opal/libraries) documentation.

### Managed Accounts API

A new [Managed Accounts API](/reference/managed-accounts/overview) provides programmatic access to Method-managed FBO accounts. You can now retrieve managed account balance information and list transactions for reconciliation:

* `GET /managed_accounts` — list all Managed Accounts on your team
* `GET /managed_accounts/{macc_id}` — retrieve a specific Managed Account
* `GET /managed_accounts/{macc_id}/transactions` — list transactions for a Managed Account

For more information, visit the [Managed Accounts API](/reference/managed-accounts/overview) documentation.

## Improvements

### Opal UI

* **CVV Autofill Detection**: Browsers that autofill CVV fields were sometimes causing silent submission failures because Opal didn't detect the autofilled value. This is now handled correctly, so users who rely on password managers or browser autofill won't hit unexpected errors.
* **Input Trimming**: Whitespace is now automatically stripped from user inputs before submission. This catches a common issue where users copy-paste account numbers or card details with trailing spaces, which would previously cause validation failures.

For more information, visit the [Opal](/opal/overview) documentation.

### Webhooks

**Improved Duplicate Detection**

Previously, webhooks with the same endpoint URL and different authentication credentials (for example, separate webhook configs for staging and production that share a URL) were treated as duplicates, delivering to only one of them. Deduplication now accounts for authentication configuration, so each distinct webhook registration receives its own deliveries as expected.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.


# February Updates
Source: https://docs.methodfi.com/changelog/2026/february



## New Features

### Forwarding Requests: Entity Bindings

The [Forwarding Requests API](/reference/forwarding-requests/overview) now supports `entity` as a binding type. Previously, the `bindings` object only accepted `payment_instrument` and `secret` resource IDs. You can now bind an Entity and reference its data in your forwarding request templates using the `{{entity.field}}` syntax.

This enables use cases where an individual's first and last name need to be forwarded to third-party services alongside the associated account number, without exposing raw PII to your system.

```json Sample Request theme={null}
{
  "bindings": {
    "payment_instrument": "pmt_inst_7TNTTRQwQxWc",
    "secret": "sec_au22b1fbFrmfp",
    "entity": "ent_au22b1FBFJbp8"
  },
  "url": "https://sample-url/v1/tokens",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{secret.value}}"
  },
  "body": "{\"first_name\":\"{{entity.individual.first_name}}\",\"last_name\":\"{{entity.individual.last_name}}\",\"number\":\"{{payment_instrument.card.number}}\"}"
}
```

For more information, visit the [Forwarding Requests API](/reference/forwarding-requests/overview) documentation.

### Credit Score Simulations

The [Simulate API](/reference/simulations/overview) now supports direct event creation for Credit Score simulations.

* **New endpoint**: `POST /simulate/events` with `type` set to `credit_score.increased` or `credit_score.decreased`
* This endpoint allows developers to trigger credit score change events for an Entity with an active Credit Score subscription in the development environment, streamlining the testing of credit score-driven workflows

<Warning>This API is available in the development environment only.</Warning>

For more information, visit the [Simulations API](/reference/simulations/events/create) documentation.

## Improvements

### Updates API

**Student Loan — Opened At**

The [Updates API](/reference/accounts/updates/overview) now surfaces the `opened_at` field for `student_loan` liability accounts when `source` is `direct`. This field returns the date the student loan was originally opened, providing additional context for loan lifecycle analysis, refinance eligibility assessments, and portfolio segmentation.

For more information, visit the [Updates API](/reference/accounts/updates/overview) documentation.

### Webhooks

**New Accounts Surfaced Event**

The `entity.new_accounts_pending_consent` webhook fires when a previously undiscovered liability account surfaces after a user progresses through [Connect](/opal/connect/overview), but only for users who haven't opted into automatic consent for future accounts. For customers using Opal or the Element, this enables you to surface the new account to your end user for explicit consent, and optionally offer them the ability to auto-consent to future accounts going forward. This removes the need to poll the [Accounts API](/reference/accounts/overview) to discover new accounts.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Connect API

**Filter Accounts by Product**

You can now filter accounts by product type when using [Connect](/opal/connect/overview). This allows you to scope a Connect session to only surface accounts relevant to a specific product (e.g., only accounts eligible for payments or only accounts with update subscriptions), reducing noise and improving the end-user experience in targeted workflows.

For more information, visit the [Connect API](/opal/connect/overview) documentation.

### Payment Instruments API

**Card Billing Zip Code**

A new `billing_zip_code` field is now available on `card` type [Payment Instruments](/reference/accounts/payment-instruments/overview). This field is returned as part of the `card` object when retrieving a Payment Instrument.

* `card.billing_zip_code`: The billing zip code associated with the card

This addition supports address verification (AVS) workflows and reduces payment failures caused by billing address mismatches when forwarding card details to third-party processors.

For more information, visit the [Payment Instruments API](/reference/accounts/payment-instruments/overview) documentation.

### Payments API

**Inbound ACH/Wire Trace Numbers & Metadata**

Inbound ACH and wire payments received via `inbound_achwire_payment` [Payment Instruments](/reference/accounts/payment-instruments/overview) now include trace number and metadata fields on the [Payment](/reference/payments/overview) object.

* `source_trace_id`: enables end-to-end payment tracking and reconciliation for inbound transfers
* `destination_trace_id`: provides the underlying bank transaction ID on the destination Account for outbound reconciliation
* `metadata`: allows clients to associate custom reference information with incoming transactions (e.g., you can now add internal reference IDs, ​​customer IDs, and notes in the metadata)

For more information, see the [Payments API](/reference/payments/overview) documentation.

### Versioned API Reference Docs

The API Reference documentation now supports **version-aware navigation**. A version dropdown in the navigation bar lets you switch between API versions (`2025-12-01`, `2025-07-04`, `2024-04-04`) to view the documentation specific to your pinned API version.

Each version renders its own copy of the API Reference with version-specific request examples, response schemas, and available fields — so the docs you see always match the behavior of the API version you're using.

For more information, visit the [Versioning](/reference/versioning) documentation.


# January Updates
Source: https://docs.methodfi.com/changelog/2026/january



## New Features

### Forwarding Requests API

The [Forwarding Requests API](/reference/forwarding-requests/overview) allows you to securely proxy sensitive data (such as card details) to third-party services without your system ever handling the raw data. This enables use cases like payment processing, tokenization, and partner integrations while maintaining the PCI compliance of existing solutions.

**Key capabilities:**

* **Secure data transmission**: Send templated HTTP requests to whitelisted third-party endpoints.
* **Dynamic data injection**: Use template placeholders (e.g., `{{my_binding.card.number}}`) instead of raw values.
* **Binding resolution**: Bind placeholders to Method resources (currently [Payment Instruments](/reference/accounts/payment-instruments/overview)), allowing Method to securely append the underlying data without ever touching your company database.
* **Destination whitelisting**: Requests can only be sent to pre-approved URLs to prevent data exfiltration.
* **Transparent responses**: The third-party response is forwarded directly back to your application without requiring you to make changes to the way you ingest third-party response data.

For more information, visit the [Forwarding Requests API](/reference/forwarding-requests/overview) documentation.

### Secrets API

The [Secrets API](/reference/secrets/overview) allows you to securely store sensitive configuration values (such as API keys or credentials) for use within Method. Secrets are encrypted at rest and never exposed back to client applications.

**Key capabilities:**

* **Encrypted storage**: Store sensitive values and receive a Secret ID (`sec_...`) in return.
* **No client exposure**: Secret values are never returned in API responses.
* **Forwarding integration**: Secrets can be inserted into [Forwarding Requests](/reference/forwarding-requests/overview) for authenticating with third-party services.

For more information, visit the [Secrets API](/reference/secrets/overview) documentation.

### Opal Appearance Customization

You can now customize the visual appearance of [Opal](/opal/overview), Method's embeddable UI, to better match your application's branding or autofit to your users' devices.

When opening Opal with the client SDK, specify an `appearance` option with one of the following values:

* `light`: Standard light theme (default)
* `dark`: Dark theme for low-light environments
* `system`: Automatically matches the user's device settings

If no appearance is specified, Opal defaults to the `light` theme.

For more information, visit the [Opal Libraries](/opal/libraries) documentation.

## Improvements

### Payment Instruments API

This release introduces several improvements to the [Payment Instruments](/reference/accounts/payment-instruments/overview) product, focused on lifecycle management and subscription control.

**Lifecycle Management for Inbound ACH/Wire**

A new endpoint allows you to close inbound ACH/Wire payment instruments when they are no longer needed. This is useful for decommissioning payment routes after a refinance completes or when a funding relationship ends.

* **New endpoint**: `DELETE /accounts/:accountId/payment_instruments/:pmtInsId`
* **Behavior**: Supported only for `inbound_achwire_payment` instruments. Updates instrument status to `closed` and sets `chargeable` to `false`.

For more information, see the [Payment Instruments API](/reference/accounts/payment-instruments/overview) documentation.

**Granular Subscription Types**

The `payment_instrument` [subscription](/reference/accounts/subscriptions/overview) has been split into two more specific subscription types, giving you more flexibility in determining which webhook events you receive:

* `payment_instrument.card`: Triggered for card-level updates (e.g., PAN changed, expiration updated)
* `payment_instrument.network_token`: Triggered for network token updates (e.g., token provisioned, status changed)

<Note>For API version `2025-12-01`+, clients must use the new specific subscription names.</Note>

### Accounts API

**Collection Account Support**

The [Account Sensitive](/reference/accounts/sensitive/overview) product now supports the `collection` account type. This enables you to retrieve sensitive account details (such as account numbers) for accounts that have been sent to collections, expanding coverage for debt management and recovery workflows.

### Attributes API

**Support for Closed Accounts**

You can now retrieve [Account Attributes](/reference/accounts/attributes/overview) for closed liability accounts. Previously, querying Attributes for a closed account would return an error. With this update, derived financial insights (such as payment history summaries and balance trends) remain accessible even after an account has been closed—useful for historical reporting and analytics.


# July Updates
Source: https://docs.methodfi.com/changelog/2026/july



## New Features

### Raw Credit Report Artifacts and Files API

Teams with raw credit report access can now request the bureau report underlying a Connect as downloadable JSON or PDF artifacts. This gives lenders the full bureau file behind a Connect, so underwriting, risk, and compliance logic can run against the same source data Method used.

Pass `bureau` and `artifacts` when creating a Connect. Equifax and TransUnion are supported:

```json theme={null}
{
  "bureau": "transunion",
  "artifacts": ["raw_credit_report", "credit_report_pdf"]
}
```

The completed Connect returns each artifact in its `files` array. The new Files API provides two ways to access them:

* `GET /files/{file_id}` returns File metadata and a temporary download URL
* `GET /files/{file_id}/download` streams the original file directly

Files remain available after the Connect completes, allowing lenders to run their existing underwriting and risk logic on the same raw credit report output without maintaining a separate bureau integration. Raw credit report access is enabled per team; contact your Method CSM to get started.

For implementation details, visit the [Raw Credit Reports guide](/guides/connect/raw-credit-reports) and [Files API](/reference/files/overview) documentation.

### Estimated Statement Attribute

Account Attributes can now return the upcoming payment due date and minimum amount due for supported accounts through the new `statement` bundle:

* `next_payment_due_date`: the upcoming payment due date
* `next_payment_minimum_amount`: the upcoming minimum amount due, in cents

Previously this required maintaining an Update subscription and waiting for a refreshed Update to land, and between statement cycles the values were frequently missing altogether. Teams can now schedule autopay and reminders against a real due date, size a payment that reliably clears the minimum, and sequence payments across a user's accounts by what comes due first.

When current statement data is unavailable, Method estimates both values from account history and identifies them with `metadata.estimated: true`. When a value cannot be determined, the attribute returns an `ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA` error rather than a fabricated fallback.

```json theme={null}
{
  "bundles": ["statement"]
}
```

For more information, visit the [Account Attributes](/reference/accounts/attributes/overview) API documentation.

### Estimated Credit Card APR

Account Attributes can now return a single `estimated_apr` for supported credit card accounts with qualifying account history.

Card issuers rarely expose an account-level APR through any programmatic channel, which has left teams either asking the end user for their rate or assuming one. Estimated APR lets teams size interest savings, rank refinance and balance transfer offers, and prioritize outreach to the highest-rate balances in a user's profile, without asking the end user for anything.

Every value is identified with `metadata.estimated: true` and carries a `metadata.confidence` of `medium` or `high` based on the depth of available history, so teams can set their own threshold for acting on it. When an APR cannot be inferred with sufficient confidence, the attribute returns an `ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA` error rather than a fabricated fallback.

```json theme={null}
{
  "estimated_apr": {
    "value": 19.5,
    "error": null,
    "metadata": {
      "estimated": true,
      "confidence": "high"
    }
  }
}
```

For more information, visit the [Account Attributes](/reference/accounts/attributes/overview) API documentation.

## Changes

### Payment Processing Windows

Payment processing windows have been updated. Payments using the Method Debit Model are now processed at 1:30 PM CT, and payments using the Prefunded Model are now processed at 3:30 PM CT. Payments submitted before the applicable cutoff are processed same-day; payments submitted after are queued for next-business-day processing.

For more information, visit the [Payments API](/reference/payments/overview) documentation.

## Improvements

### Idempotency and Stuck-Request Recovery

Improvements to Method's idempotency system eliminated persistent `INTERNAL_BAD_STATE` errors on retried requests. Dropped connections now recover automatically on retry, previously stuck requests self-heal rather than remaining locked, and orphaned in-flight requests are released after a short interval.

End users no longer become locked mid-flow after a dropped connection. Requests already stuck in `INTERNAL_BAD_STATE` also recover automatically the next time the end user retries, and no integration changes are required.

For more information, visit the [API Idempotency](/reference/idempotency) documentation.

### Dashboard Navigation and Search

The [Method Dashboard](https://dashboard.methodfi.com) now includes:

* A responsive, collapsible sidebar with improved mobile support
* Faster global search with a more compact results experience
* Faster switching between development and production environments
* Persistence of the most recently used environment across sessions
* FIS trace IDs on sent and posted payments in the payments view

Users with the Developer role can also create API keys and webhook registrations directly from the Dashboard, consistent with their existing permissions. Together these reduce the time spent locating a request, entity, or payment when responding to a customer question.

### Payability Check at Account Creation

Method now runs a payability check when an account is created, so teams learn whether an account can be paid at the point of creation rather than discovering it at payment time. This prevents users from attempting a payment that was never going to succeed.

### Webhook Reliability

Outbound webhook delivery now includes stronger duplicate-delivery protection and prevents queued deliveries from being sent to disabled webhook registrations. Delivery and replay handling have also been hardened to reduce the risk of events being lost during transient service failures.

This means fewer events to deduplicate on your side and less reconciliation work after a transient failure, with no change to how you consume webhooks.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Development Environment

Manual Connect flows can now be configured dynamically, and payments can be simulated against payment instruments without production dependencies. Teams can therefore test a full Connect-to-payment path, including failure cases, before touching a live account.

For more information, visit the [Development Environment](/reference/environments) documentation.


# June Updates
Source: https://docs.methodfi.com/changelog/2026/june



## New Features

### Card Brand Details

The Card Brands endpoint now returns a structured `details` object on each brand, giving you the full marketing-level terms behind a user's card, including APRs, fees, rewards, and promotional offers.

* **APRs**: Purchase and cash-advance APR ranges via `purchase_apr_min` / `purchase_apr_max` and `cash_advance_apr_min` / `cash_advance_apr_max`.
* **Fees**: `annual_fee` and `late_payment_fee`.
* **Rewards**: A full rewards object with program name, reward type (for example, `cash_back`, `points`, `miles`), and per-category earn rates (dining, travel, groceries, gas, and more), including the base-rate category for all other purchases.
* **Promotions**: A `promotions` array covering sign-up bonuses, intro APR offers, statement credits, and more, each with value, spend requirement, qualifying period, and expiration.
* **Classification and freshness**: `card_category` classifies the card (for example, `travel`, `cash_back`, `store`), and `data_as_of` tells you when the details were last captured.

**Key Use Cases**

* Power balance-transfer and refinance offers with accurate rate and promotion data.
* Enrich PFM experiences by showing users the detailed terms and benefits of the cards they carry.
* Optimize checkout and reward experiences by auto-routing purchases to the top-earning card.

Card Brands is available as both a Product (on-demand) and a Subscription (near real-time updates), and the details object is available on API version `2025-07-04` and later. The endpoint is available to partners processing payments through the Payment Instruments endpoint. Contact your Method CSM to enable it. See the [Card Brands reference](/reference/accounts/card-brands/overview) to get started.

### Dashboard: Check Payment Management

Admins can now manage check payments directly from the payment detail page in the [Method Dashboard](https://dashboard.methodfi.com).

* **Stop payment**: Place a stop on a paper check that has been sent but not yet cashed. The check is stopped and funds are reversed to the source.
* **Check endorsement image**: View the front and back endorsed image of a check once it has been cashed.
* **Source & destination status**: The payment detail page now surfaces source status and destination status alongside the existing payment status for better visibility into where a payment is in its lifecycle.

<Note>Stop payment and check image viewing are available to admin users only.</Note>

For more information, visit the [Method Dashboard](https://dashboard.methodfi.com).

### Preauth Signals

The new Preauth Signals endpoint returns the predicted likelihood that a transaction will succeed, alongside verified ownership of the card and recommended retry timing. Built for merchants and commerce platforms looking to optimize payment performance.

**Key Use Cases**

* Predict whether a card payment will go through before attempting the charge to reduce false declines at checkout.
* Identify the best date to retry a payment for recurring charges.

This endpoint is currently in Public Preview. Reach out to your Method CSM for access and documentation.

### New Attributes: Delinquency, HELOC & Available Credit

New entity-level and account-level attributes give you a more complete, real-time picture of borrower risk and capacity.

* **Delinquency signals**: Aggregate borrower-level risk with the worst days-past-due bucket across accounts, whether delinquency is progressing or recently cured, total delinquent balance, and the highest-severity outcome (charge-off, collections, foreclosure, and more).
* **HELOC-specific attributes**: You can now separate out attributes related to HELOCs from mortgages and personal loans to isolate appetite for a new HELOC, CLI, or refi.
* **Available credit**: Understand a borrower's total credit headroom in near real time to assess their riskiness and eligibility for new products.
* **Direct Pay enrichment**: Completed attribute responses now include Method Direct Pay history (recency, amount, and trailing 12-month count), providing a clearer picture of a borrower's risk profile and appetite for debt consolidation.

For more information, visit the [Entity Attributes](/reference/entities/attributes/overview) and [Account Attributes](/reference/accounts/attributes/overview) API documentation.

### Account Attribute Subscriptions

Method now triggers events whenever an account's attributes change, so you can react to balance, utilization, and delinquency shifts in real time instead of polling. Subscribe to the attributes you care about and Method delivers updates to your configured webhooks as they occur.

* Manage what you listen to through the [Subscriptions endpoint](/reference/accounts/subscriptions/overview).
* Receive changes through [Events](/reference/events/overview) and webhooks.

This pairs naturally with continuous, post-origination portfolio monitoring use cases.

### Team IP Allowlisting

Teams can now restrict API access to a defined set of IP addresses. Once an allowlist is configured, requests from outside the approved ranges are rejected, with enforcement backed by a 24-hour cache for low-latency checks. See [IP Whitelisting](/reference/ip-whitelisting) to configure.

## Improvements

### Payments

* **More accurate estimated completion dates**: The `estimated_completion_date` returned on a payment now always shows the correct date or a slightly conservative estimate, especially for same-day ACH source payments.
* **Destination posted date**: The `destination_posted_date` field is now populated once the destination posts, giving you a precise reconciliation signal that is distinct from the estimated completion date.

For more information, visit the [Payments API](/reference/payments/overview) documentation.

### Payment Limits

To protect platform safety and stability, per-transaction and 24-hour limits are now enforced on payment volumes.

A new Limits tab under Dashboard Settings surfaces your team's money-movement capabilities and associated limits in one place. You can now see at a glance what your team is permitted to send and receive, and where caps apply.

Contact your customer success manager to learn more about your team's limits.


# March Updates
Source: https://docs.methodfi.com/changelog/2026/march



## New Features

### [API Guides](/guides/overview)

A new API Guides section is now available in Method's documentation. This comprehensive, concept-first companion to the API Docs helps product and business teams understand how Method's platform works and how best to configure Method's APIs for their use case. The API Guides include:

* **How Method Works**: How Method leverages multiple data sources to power identity verification, account discovery, and data retrieval.
* **Core Products**: In-depth guides for each product area, covering payload details, subscription behaviors, error handling, and edge cases.
* **Use Case Guides**: Implementation frameworks for the most common use cases: debt consolidation and balance transfers for lenders, card linking and checkout for commerce platforms, and liability dashboards and bill pay for personal finance apps, with step-by-step flows mapping Method products to each stage of the customer journey.

These guides are designed to complement the existing API Reference documentation by providing the conceptual foundation and product context that teams need to plan and build their integrations effectively.

### [OpenAPI Specification](https://github.com/MethodFi/openapi)

Method now publishes an official OpenAPI specification for the Method API. The spec enables you to:

* **Generate typed API clients** in any language using OpenAPI-compatible code generators
* **Import endpoints** directly into tools like Postman or Insomnia
* **Integrate with any toolchain** that supports the OpenAPI standard

For more information, visit the [Libraries](/libraries/overview) documentation.

## Improvements

### Webhook Idempotency Headers

You can now easily deduplicate retried or replayed webhook deliveries. All outbound webhooks now include a `method-webhook-delivery-id` header, containing a unique identifier for each webhook delivery. If your endpoint receives the same delivery twice (due to network timeouts, retries, or replays), the `method-webhook-delivery-id` value will be identical, letting you skip duplicate processing with a simple lookup.

```json Sample Headers theme={null}
{
  "method-webhook-delivery-id": "obwh_yBaCP3DQxJ4",
  "content-type": "application/json"
}
```

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Simulations API

**Connect Webhook in Account Opened Simulation**

The `POST /simulate/events` endpoint for `account.opened` events now also sends the `connect.create` webhook as part of the simulation, aligned with the endpoint's production behavior.

Previously, simulating an `account.opened` event only fired the `account.opened` webhook. This gap meant customers couldn't fully test their Connect-to-Account-Opened integration pipeline in dev.

Now, when you simulate `account.opened`, both webhooks fire in sequence:

1. `connect.create` — the Connect session that discovered the account
2. `account.opened` — the account itself becoming available

This enables true end-to-end testing of workflows that listen for Connect completion and then act on the resulting accounts.

```json POST /simulate/events theme={null}
{
  "type": "account.opened",
  "entity_id": "ent_au22b1FBFJbp8",
  "account_id": "acc_Dz3E8r4mJ7xKn"
}
```

For more information, visit the [Simulations API](/reference/simulations/events/create) documentation.


# May Updates
Source: https://docs.methodfi.com/changelog/2026/may



## New Features

### Snapshot Delinquency Data

[Updates](/reference/accounts/updates/overview) with `source: "snapshot"` now include a comprehensive set of delinquency fields sourced from the credit report. These fields give you a full picture of a borrower's delinquency status without pulling a separate credit report for the user.

* **Delinquency Status & Period**: `delinquent_status`, `delinquent_period`, and `delinquent_start_date` indicate the current delinquency state, severity bucket (`less_than_30`, `30`, `60`, `90`, `120`, `over_120`), and when the delinquency began.
* **Delinquent Actions**: `delinquent_action` surfaces servicer-level actions such as `charge_off`, `foreclosure`, `repossession`, `chapter_7`, `chapter_13`, `wage_garnishment`, `payment_agreement`, and `bankruptcy`.
* **Delinquent Amount**: `delinquent_amount` returns the dollar amount currently reported as delinquent.
* **Delinquency History**: `delinquent_history` provides a time-series array of historical delinquency periods, each with `start_date`, `end_date`, `status`, `period`, and `action`, enabling trend analysis across multiple reporting cycles.

Delinquency fields are available on snapshot Updates for `credit_card`, `auto_loan`, `personal_loan`, `mortgage`, and `student_loan` liability types. These fields are not included on Updates with `source: "direct"`.

For more information, visit the [Updates API](/reference/accounts/updates/overview) documentation.

### Receive Reversals via Wire

You can now receive payment reversals via wire. This functionality allows customers to quickly and easily access funds from reversed payments that previously could not run on ACH rails (such as inbound wire transfers via payment instrument).

<Note>These accounts are receive-only and do not support outbound payments.</Note>

For more information, visit the [Accounts API](/reference/accounts/overview) documentation.

### Dashboard: Webhook Management

The [Method Dashboard](https://dashboard.methodfi.com) now supports full webhook lifecycle management. You can create, view, update, and delete webhook endpoints directly from the UI, with no API calls or support requests required.

* Register new webhook endpoints with custom event filters and authentication
* View all active webhooks and their status
* Update endpoint URLs and configuration in place
* Delete webhooks that are no longer needed

For more information, visit the [Method Dashboard](https://dashboard.methodfi.com).

## Improvements

### Rate Limiting

To protect platform stability and ensure consistent performance across all customers, all API requests are now subject to published, tiered rate limits. Documented limits mean your engineering team can design around known thresholds rather than hitting undefined behavior during peak operations.

* Rate limits are applied per API key within a 60-second rolling window, organized into tiers based on operation type.
* Each tier tracks independently, so usage against one tier does not affect capacity in another.
* Customers with high-volume integrations can request custom limits through their customer success manager.

For more information, visit the [Rate Limiting](/reference/rate-limiting) documentation.

### Webhooks

**Delivery Rate Limiting**

Outbound webhook deliveries are now rate-limited to 15 deliveries per second per webhook registration. This smooths delivery during high-volume events (e.g., bulk Connect completions or batch Update subscriptions) and reduces the likelihood of triggering rate-limit responses on your infrastructure.

**Failure Handling**

An individual webhook delivery is now retried up to 5 times before it is marked as failed, rather than remaining in a retry loop indefinitely. After 5 consecutive delivery failures, the webhook `status` is set to `disabled`, consistent with the documented automatic-disabling behavior. You can reactivate a disabled webhook from the Dashboard or via the [Update a Webhook](/reference/webhooks/update) endpoint once the underlying issue is resolved.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Payments API

**Destination Processing Window**

The destination processing window has been updated to 4:00 PM CT (5:00 PM ET). Payments submitted before this cutoff can be processed the same-day; payments submitted after are queued for next-business-day processing.

For more information, visit the [Payments API](/reference/payments/overview) documentation.

### Simulations API

**Account Closed Event**

The `POST /simulate/events` endpoint for `account.closed` events now also triggers the `account.update` webhook as part of the simulation, matching production behavior. This enables more complete end-to-end testing of account lifecycle workflows in the development environment.

```json POST /simulate/events theme={null}
{
  "type": "account.closed",
  "entity_id": "ent_au22b1FBFJbp8",
  "account_id": "acc_Dz3E8r4mJ7xKn"
}
```

When simulating `account.closed`, both webhooks now fire in sequence:

1. `account.update`: the account snapshot is updated with the closed status
2. `account.closed`: the account itself transitions to closed

For more information, visit the [Simulations API](/reference/simulations/events/create) documentation.

### Development Environment

**Mock Credit Reports for Connect**

Mock raw credit reports are now available for [Connect](/opal/connect/overview) flows in the development environment, enabling end-to-end testing of credit report-based account discovery without live bureau data.

<Warning>This feature is available in the development environment only.</Warning>

**Payment Destination Details in Responses**

The development environment `POST /payments` response now includes the `destination_payment_method` field, aligning dev responses with production behavior. This field indicates how the payment is delivered to the recipient, either `electronic` or `paper`.

```json theme={null}
{
  "id": "pmt_rPrDPEwyCVUcm",
  "status": "pending",
  "source": "acc_JMJZT6r7iHi8e",
  "destination": "acc_AXthnzpBnxxWP",
  "destination_payment_method": "electronic"
}
```

For more information, visit the [Payments API](/reference/payments/overview) documentation.


# Introducing API v2
Source: https://docs.methodfi.com/changelog/api-versions/2024-04-04



<img alt="title" />

We are excited to announce the launch of API v2 (release `2024-04-04`), the highly anticipated second version of Method's API.
Over the past year, our team has been dedicated to gathering feedback and working closely with our clients to create an even more powerful and developer-friendly API.

This release is packed with new features and enhancements that build upon Method's credential-less consumer permissioned financial network.

Expanded integrations with Visa/Mastercard power new features such as real-time credit card transaction notifications, and enabling 1-click checkout experiences for merchants.
This is in addition to our real-time financial institution liability updates, which have been significantly upgraded to provide better accuracy, expanded coverage, and reduced latency.

### Upgrading to 2024-04-04

The new API version is available to all existing teams.
New teams are automatically pinned to the API version `2024-04-04`.
During the transition phase, teams will be allowed to utilize any API version in tandem.

Note that once upgraded manually, it’s not possible to revert to older versions. Contact your Method CSM for more information on upgrade rollbacks.

* **Request Header**: Set `Method-Version` to `2024-04-04`. See [API Versioning](/reference/versioning#api-versioning) for more information.
* **Client Libraries**: For Method Libraries, the version is locked to the dated version of the API. For example, method-node v0.x.x is locked to 2020-12-06, while method-node v1.x.x is locked to 2024-04-04 and onwards.

#### Upgrade Support

Our technical integration team is here to help! Contact your Method CSM for a 1:1 on best practices and support migrating to `2024-04-04`

<Tip>Personalized upgrade guides have been created for enterprise customers. Contact your Method CSM to receive your guide.</Tip>

**✨ Ask Method:** The search bar of our docs now includes a conversational LLM search powered by ChatGPT. Feel free to ask any questions and receive a personalized answer.

*Sample questions:*

> How are auth\_sessions different in the new version of the API?

> What are the new products in 2024-04-04?

## Entities

New endpoints have been introduced for verification sessions, identities, connect operations, credit scores, products, and subscriptions. Several endpoints, including auth session, credit scores, and sensitive information retrieval, have been deprecated.

The connect endpoint now fetches all liability accounts across Method’s network of financial institutions, replacing auth\_session.
The verification sessions endpoint manages methods for verifying an entity's phone and identity, while the identities endpoint retrieves the underlying identity (PII) of an entity.
The products and subscriptions endpoints provide an overview of the products and continuous updates available for entities.

### New Features

#### The Connect endpoint

[Connect](/reference/entities/connect/overview) identifies and connects all the liability accounts (e.g., credit card, mortgage, auto loans, student loans, etc.)
for an entity across Method’s network of 1500+ financial institutions/lenders.

* **The Connect endpoint replaces:**
  * Auth Session: `POST /entities/{ent_id}/auth_session`

See [Connect](/reference/entities/connect/overview) for more information.

***

#### The Credit Scores endpoint

[Credit Scores](/reference/entities/credit-scores/overview) returns the latest credit score and score factors for an entity.

* **The Credit Scores endpoint replaces:**
  * Credit Score: `GET /entities/{ent_id}/credit_score`

See [Credit Scores](/reference/entities/credit-scores/overview) for more information.

***

#### The Verification Sessions Endpoint

[Entity Verification Sessions](/reference/entities/verification-sessions/overview) manage the methods for verifying an entity's phone and identity. Entities need to verify
their identity and/or phone to be used throughout the Method API. The status
of an entity's verification is returned via the `verification` field in the Entity object.

* **The Verification Sessions endpoint replaces:**
  * KBA questions via Auth Session: `POST /entities/{ent_id}/auth_session` is replaced by [kba](/reference/entities/verification-sessions/create-kba) entity verification session.
  * Non-KBA authentication via Auth Session: `POST /entities/{ent_id}/auth_session` is replaced by [byo\_kyc](/reference/entities/verification-sessions/create-byo-kyc) entity verification session.
  * `individual.phone_verification_type` and `individual.phone_verification_timestamp` via the create Entity request are replaced by [byo\_sms](/reference/entities/verification-sessions/create-byo-sms) phone verification requirements.
  * Utilizing `capabilities`, `available_capabilities`, and `pending_capabilities` in the Entity object to verify if an entity's identity has been matched or if more PII is required.
    * This flow is now replaced by `verification.identity.verified` and `verification.identity.matched` in the `verification` field in the Entity object.

* **Upgrade notes:**
  * The `verification` field in the Entity object returns the status of Identity Verification (`verification.identity`) and Phone Verification (`verification.phone`).
  * The `method` key in the `entity.verification` object enumerates the phone and identity verifications available for your entity.
    * Available verification methods differ on a team-by-team basis and are further defined by the PII provided during entity creation. See [PII Requirements](/reference/entities/overview#pii-requirements) for more information.
    * Teams with pre-defined PII requirements can utilize `byo_kyc` to skip KBA, and `byo_sms` to skip phone verification.
  * Teams upgrading from a prior API version might have some verifications auto-generated. Contact your Method CSM for more info.
  * The `status` key in an entity will only transition to `active` when all verification requirements have been completed.

See [Verification Sessions](/reference/entities/verification-sessions/overview) for more information.

***

#### The Identities endpoint

Entity [Identities](/reference/entities/identities/overview) endpoint is used to retrieve the underlying identity (PII) of an Entity.

* **The Identities endpoint replaces:**
  * Entity Sensitive: `GET /entities/{ent_id}/sensitive`

See [Identities](/reference/entities/identities/overview) for more information.

***

#### The Products endpoint

Entity [Products](/reference/entities/products/overview) endpoint outlines the products (*capabilities*) an entity has access to and provides an overview of the status of all the products.

Products are Method endpoints available for an entity. Access to most products requires an entity to be active.
However, some products have restricted access requiring team-by-team enablement. See [List all Products](/reference/entities/products/list) for more information.

**Entity Products:**

| Name           | Use-Case                                                             | Resource Doc                                                |
| -------------- | -------------------------------------------------------------------- | ----------------------------------------------------------- |
| `connect`      | On-Demand comprehensive view of an Entity’s outstanding liabilities. | [Connect](/reference/entities/connect/overview)             |
| `credit_score` | On-Demand view of an Entity’s credit score.                          | [Credit Scores](/reference/entities/credit-scores/overview) |
| `identity`     | On-Demand retrieval of the full Identity (PII) for any Entity        | [Identities](/reference/entities/identities/overview)       |

* **The Products endpoint replaces:**
  * Utilizing `capabilities`, `available_capabilities`, and `pending_capabilities` in the Entity object to determine the capabilities an entity has access to.
    These fields have been deprecated from the Entity object and removed in favor of:
    * `products` (products available for this entity)
    * `restricted_products` (products not currently available, but can be made available)

See [Products](/reference/entities/products/overview) for more information.

***

#### The Subscriptions endpoint

Entity [Subscriptions](/reference/entities/subscriptions/overview) endpoint controls the state of all subscriptions for an entity. Subscriptions are products that can provide continuous updates via webhooks (e.g., *Credit Score Subscription provides updates on an entity’s credit score*).

**Entity Subscriptions:**

| Name           | Use-Case                                                                                                            | Resource Doc                                                |
| -------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `connect`      | Comprehensive view of an Entity’s outstanding liabilities and continuous near real-time updates on new liabilities. | [Connect](/reference/entities/connect/overview)             |
| `credit_score` | Continuous near real-time updates on an Entity’s credit score.                                                      | [Credit Scores](/reference/entities/credit-scores/overview) |

* **The Subscriptions endpoint replaces:**
  * Custom configuration for continuous credit report pulls via your Method CSM. This has been deprecated and replaced by [Create a Subscription](/reference/entities/subscriptions/create) endpoint.

See [Subscriptions](/reference/entities/subscriptions/overview) for more information.

***

### Breaking Changes

#### Entity object changes

* ✨ Corporation entity types have been simplified to `corporation` during [Create a Corporation](/reference/entities/create-corporation) entity.
  * `c_corporation`, `s_corporation`, `llc`, `partnership`, and `sole_proprietorship` have been deprecated and removed in favor of `corporation`

* ✨ Providing SSN is now supported during [Create an Individual](/reference/entities/create-individual) entity.
  * `individual.ssn`, and `individual.ssn_4`

* ✨ Entity verification status is now returned by the Entity object. See [Entity object](/reference/entities/overview) for more information.
  * `verification`

* ✨ Products and subscription status are now returned by the Entity object. See [Entity object](/reference/entities/overview) for more information.
  * `products`
  * `restricted_products`
  * `subscriptions`
  * `available_subscriptions`
  * `restricted_subscriptions`

* ⛔ Phone verification has been replaced and no longer returned by the Entity object.
  * `individual.phone_verification_type`, and `individual.phone_verification_timestamp` have been deprecated and removed in favor of [Entity Verification Sessions](/reference/entities/verification-sessions/overview)

* ⛔ Entity capabilities have been deprecated and removed from the Entity object.
  * `capabilities`, `available_capabilities`, and `pending_capabilities` have been deprecated and removed in favor of [Products](/reference/entities/products/overview), [Subscriptions](/reference/entities/subscriptions/overview), and [Entity Verification Sessions](/reference/entities/verification-sessions/overview)
    * The `verification` field in the Entity object returns the status of Identity Verification (`verification.identity`) and Phone Verification (`verification.phone`).
    * The `products` array returns the products the entity has access to, replacing `capabilities`.
    * The `restricted_products` array returns the products the entity does not have access to, replacing `pending_capabilities`.
    * The [Entity Products](#) endpoint outlines the products (*capabilities*) an entity has access to and provides an overview of the status of all the products.

* The following fields have been modified in the [Entity object](/reference/entities/overview):

  <AccordionGroup>
    <Accordion title="Fields removed from Entity" icon="circle-minus">
      * `individual.phone_verification_type`
      * `individual.phone_verification_timestamp`
      * `capabilities`
      * `available_capabilities`
      * `pending_capabilities`
    </Accordion>

    <Accordion title="Fields added to Entity" icon="circle-plus">
      * `individual.ssn`
      * `individual.ssn_4`
      * `verification`
      * `products`
      * `restricted_products`
      * `subscriptions`
      * `available_subscriptions`
      * `restricted_subscriptions`
    </Accordion>
  </AccordionGroup>

#### Deprecated endpoints

The following endpoints have been deprecated and removed in `2024-04-04`

* Auth Session: `/entities/{ent_id}/auth_session` removed in favor of [Connect](/reference/entities/connect/overview)
* Credit Score: `/entities/{ent_id}/credit_score` removed in favor of [Credit Scores](/reference/entities/credit-scores/overview)
* Entity Sensitive: `/entities/{ent_id}/sensitive` removed in favor of [Identities](/reference/entities/identities/overview)
* Refresh Capabilities: `/entities/{ent_id}/refresh_capabilities` is no longer supported in `2024-04-04`
* Manual Auth Session: `/entities/{ent_id}/manual_auth_session` is no longer supported in `2024-04-04`
* Entity Vehicles: `/entities/{ent_id}/vehicles` is no longer supported in `2024-04-04`

## Accounts

New endpoints have been introduced for updates, card brands, payoffs, transactions, balances, verification sessions, and sensitive information. Several endpoints, including account syncs, account verification, and sensitive information retrieval, have been deprecated.

The updates endpoint now provides real-time account data directly from financial institutions, replacing syncs, and making liability account data available through the updates endpoint.

The verification process for ACH and liability accounts has been streamlined with Account Verification Sessions.

### New Features

#### The Updates endpoint

[Updates](/reference/accounts/updates/overview) endpoint retrieves in real-time account data including balance, due dates, APRs, directly from the account’s financial institution.
Updates is Method's flagship endpoint and replaces the `sync` endpoint by enabling push notifications directly from the financial institution.

As part of the `2024-04-04` release the Account object has been modified, and most Account data is now returned by an Update object. See [Account object changes](/changelog/api-versions/2024-04-04#account-object-changes) for more information.

* **The Updates endpoint replaces:**
  * Syncing an account using `/accounts/{acc_id}/syncs` has been deprecated and removed in favor of [Create an Update](/reference/accounts/updates/create)
  * Enrolling in auto syncs using `/accounts/{acc_id}/sync_enrollment` or via your Method CSM has been deprecated and removed in favor of [Updates](/reference/accounts/updates/overview) and [Subscriptions](/reference/accounts/subscriptions/overview)
  * Sync status fields in the Account response have been deprecated and removed in favor of [Updates](/reference/accounts/updates/overview). Removed fields include:
    * `data_status`
    * `data_sync_type`
    * `data_last_successful_sync`
    * `data_status_error`
    * `data_source`
    * `data_updated_at`
  * Enrollment into credit report-based updates via your Method CSM has been deprecated and removed in favor of the `update.snapshot` subscription type. See [Subscriptions](/reference/accounts/subscriptions/overview) for more information.
  * Liability data at the account level (`account.liability.<liability_type>`) has been deprecated and removed in favor of an Update object and an expansion. See [Account](/reference/accounts/overview) for more information.
  * Utilizing `data_status` to determine real-time financial institution coverage has been deprecated and removed in favor of the `products` array including `updates`. See [Updates](/reference/accounts/updates/overview) for more information.

* **Upgrade notes:**
  * New updates sources: `direct` and monthly `snapshot` updates.
    * `direct`: Near real-time account update (balance, due dates, etc.) from the account’s financial institution (replaces a `sync`).
    * `snapshot`: Monthly snapshot update (balance, due dates, etc.) from the account’s financial institution (replaces credit report-based updates).
  * Receiving continuous updates requires a subscription to `update` or `update.snapshot`. See [Subscriptions](/reference/accounts/subscriptions/overview) for more information.
  * Liability data at the account level (`account.liability.<liability_type>`) has been deprecated and removed in favor of an Update object and an expansion. See [Account](/reference/accounts/overview) for more information.
  * Any account connected using Entity Connect will receive an initial `snapshot` update and a `direct` update (when available).
  * Legacy accounts connected via `auth_session` have been migrated with an Update object pre-populated.

See [Updates](/reference/accounts/updates/overview) for more information.

***

#### The Card Brand endpoint

[Card Brand](/reference/accounts/card-brands/overview) endpoint retrieves the associated credit card metadata (Product / Brand Name, Art, etc.) directly from the card issuer.
In the future, card brand webhooks will notify in real-time any card changes (e.g., card downgraded, card lost, etc.)

* **The Card Brand endpoint replaces:**
  * Derived card names in the liability account field `name`. Migrating to card brand will provide accurate names across any Visa / Mastercard card regardless of issuing bank.

See [Card Brand](/reference/accounts/card-brands/overview) for more information.

***

#### The Payoffs endpoint

[Payoffs](/reference/accounts/payoffs/overview) endpoint retrieves a payoff quote in real-time from the Account’s financial institution / lender. Payoffs are currently only available for Auto Loan and Mortgage accounts.

* **The Payoffs endpoint replaces:**
  * `payoff_amount` and `payoff_amount_term` fields within the `auto_loan` Account type response. See [Updates](/reference/accounts/updates/overview) for more information on the Account object changes.

See [Payoffs](/reference/accounts/payoffs/overview) for more information.

***

#### The Transactions endpoint

[Transactions](/reference/accounts/transactions/overview) endpoint retrieves real-time transaction (authorization, clearing, etc) notifications for Credit Card Accounts directly from the card networks (Visa, MC).

Enrollment for transactions requires a subscription and additional consent using Method's `connect` element.

* **The Transactions endpoint replaces:**
  * Enrollment for transactions using the `auth` element has been deprecated and removed in favor of the `connect` element. See [Connect Overview](/elements/connect/overview) for more information.
  * Global transactions endpoint `/transactions` has been deprecated and removed in favor of account-scoped transactions. See [Transactions](/reference/accounts/transactions/overview) for more information.
  * `transaction:stream` capability has been deprecated and removed in favor of the `transactions` product. See [Products](/reference/accounts/products/overview) for more information.

See [Transactions](/reference/accounts/transactions/overview) for more information.

***

#### The Balances endpoint

[Balances](/reference/accounts/balances/overview) endpoint retrieves the real-time balance from the account’s financial institution.
Balance is now available for non-liability accounts such as checking accounts. Contact your Method CSM for early access to expanded Balance coverage.

* **The Balances endpoint replaces:**
  * The `balance` field in `liability.<liability_type>.balance` has been deprecated and removed in favor of:
    * Retrieving `balance` using the [Balances](/reference/accounts/balances/overview) endpoint
    * Retrieving  `balance` and additional liability information using the [Updates](/reference/accounts/updates/overview) endpoint

See [Balances](/reference/accounts/balances/overview) for more information.

***

#### The Verification Sessions endpoint

[Account Verification Sessions](/reference/accounts/verification-sessions/overview) manage the methods for verifying an Account to enable specific products for ACH or Liability accounts. For example,
ACH Accounts require a verified Account Verification Session before they can be used as a source for Payments.

* **The Account Verification Sessions endpoint replaces:**
  * ACH Account verification via `/accounts/{acc_id}/verification` has been deprecated and removed in favor of:
    * An Account Verification Session of one of the available methods: `micro_deposits`, `plaid`, `mx`, or `teller`.
    * Teams with corporate disbursement ACH accounts can skip verification and a verification will be auto-provisioned with the type of `auto_verify`.
    * Teams with managed DDAs can whitelist a routing number to skip verification across all their DDAs (routing / account number pair).
    * See [Verification Types](/reference/accounts/verification-sessions/overview#verification-types) for more information.
      A verification of `trusted_provisioner` will be auto-provisioned. Contact your Method CSM for more information.
  * Liability account number verification for AMEX, Apple Card, etc. is now handled by a `standard` Account Verification Session. See [Update a Standard Verification](/reference/accounts/verification-sessions/update-standard) for more information.
  * Instant Link CVV verification is now handled by a `pre_auth` Account Verification Session. See [Update a Pre-auth Verification](/reference/accounts/verification-sessions/update-preauth) for more information.

* **Upgrade notes:**
  * Teams upgrading from a prior API version might have some verifications auto-generated. Contact your Method CSM for more info.

See [Account Verification Sessions](/reference/accounts/verification-sessions/overview) for more information.

***

#### The Sensitive endpoint

[Sensitive](/reference/accounts/sensitive/overview) endpoint returns underlying sensitive account information (e.g., PAN, CVV, account number).
This product is only available for liabilities and requires verification on a team-by-team basis.

* **The Sensitive endpoint replaces:**
  * `GET /accounts/{acc_id}/sensitive` is deprecated and removed in favor of [Create a Sensitive](/reference/accounts/sensitive/create).

See [Sensitive](/reference/accounts/sensitive/overview) for more information.

***

#### The Products endpoint

Account [Products](/reference/accounts/products/overview) endpoint outlines the products (*capabilities*) an account has access to and provides an overview of the status of all the products.

Products are Method endpoints available for an account. Most products are accessible by default.
However, some products have restricted access requiring team-by-team enablement and elevated account verification.

**Account Products:**

| Name         | Use-Case                                                                                                    | Supported Types | Resource Doc                                           |
| ------------ | ----------------------------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------ |
| `update`     | On-Demand real-time account update (balance, due dates, etc.) from the account's financial institution      | All liabilities | [Updates](/reference/accounts/updates/overview)        |
| `balance`    | On-Demand real-time balance from the account's financial institution                                        | All liabilities | [Balances](/reference/accounts/balances/overview)      |
| `card_brand` | On-Demand retrieval of credit card metadata (Product / Brand Name, Art, etc.) directly from the card issuer | Credit Cards    | [Card Brand](/reference/accounts/card-brands/overview) |
| `payoff`     | On-Demand retrieval of auto loan payoff (amount, per diem, etc.) from the account's financial institution   | Auto Loans      | [Payoffs](/reference/accounts/payoffs/overview)        |
| `payment`    | Next day electronic push payments to the account's financial institution                                    | All liabilities | [Payments](/reference/payments/overview)               |
| `sensitive`  | On-Demand retrieval of underlying sensitive account information (PAN, CVV, account number)                  | All liabilities | [Sensitive](/reference/accounts/sensitive/overview)    |

* **The Products endpoint replaces:**
  * Utilizing `capabilities`, `available_capabilities`, and `pending_capabilities` in the Account object to determine the capabilities an account has access to.
    These fields have been deprecated from the Account object and removed in favor of:
  * `products` (products available for this Entity)
  * `restricted_products` (products not currently available, but can be made available)

See [Products](/reference/accounts/products/overview) for more information.

***

#### The Subscriptions endpoint

Account [Subscriptions](/reference/accounts/subscriptions/overview) endpoint controls the state of all subscriptions for an account. Subscriptions are products that can provide continuous updates via Webhooks.
(*e.g., Transaction Subscription provides real-time updates on a Credit Card’s transactions*).

**Account Subscriptions:**

| Name              | Use-Case                                                                                          | Supported Types | Resource Doc                                              |
| ----------------- | ------------------------------------------------------------------------------------------------- | --------------- | --------------------------------------------------------- |
| `transactions`    | Real-time transaction (authorization, purchases, etc.) notifications for credit card accounts     | Credit Cards    | [Transactions](/reference/accounts/transactions/overview) |
| `update`          | Near real-time account update (balance, due dates, etc.) from the account's financial institution | All liabilities | [Updates](/reference/accounts/updates/overview)           |
| `update.snapshot` | Monthly account snapshot update (balance, due dates, etc.) from the credit bureau                 | All liabilities | [Updates](/reference/accounts/updates/overview)           |

* **The Subscriptions endpoint replaces:**
  * Custom configuration for continuous syncs via your Method CSM. This has been deprecated and replaced by [Create a Subscription](/reference/accounts/subscriptions/create) endpoint.
  * Account Sync Enrollment `/accounts/{acc_id}/sync_enrollment` for enrollment in auto syncs. This has been deprecated and replaced with an Updates subscription. See [Updates](/reference/accounts/updates/overview) and [Create a Subscription](/reference/accounts/subscriptions/create) for more information.
  * `data_sync_type` has been removed from the Account endpoint. See [Updates](/reference/accounts/updates/overview) and [List all Subscriptions](/reference/accounts/subscriptions/list) for more information.

See Account [Subscriptions](/reference/accounts/subscriptions/overview) for more information.

***

### Breaking Changes

#### Account object changes

* ✨ Product properties are now included in the Account object. By default, the ID of the latest product resource is returned and can be
  expanded in-line using the `expand` query param. See [Expanding Resources](/reference/expanding) for more information.
  * `latest_verification_session`
  * `update`
  * `balance`
  * `card_brand`
  * `payoff`

* ✨ Products and Subscription status are now returned by the Account object. See [Account object](/reference/accounts/overview) for more information.
  * `products`
  * `restricted_products`
  * `subscriptions`
  * `available_subscriptions`
  * `restricted_subscriptions`

* ✨ Liability name and fingerprint are now returned by the Account object. See [Account object](/reference/accounts/overview) for more information.
  * `liability.name`
  * `liability.fingerprint`

* ✨ New account liability types are now supported and returned by the Account object. See [Account Liability Types](/reference/accounts/overview#account-liability-types) for more information.

* ⛔ Liability data under the `account.liability.<liability_type>` property has been deprecated and removed in favor of [Updates](/reference/accounts/updates/overview)
  * The `updates` field returns the ID of the latest update and can be expanded to return liability account data in-line using the `expand` query param. See [Expanding Resources](/reference/expanding) for more information.

* ⛔ Syncing liability data using `/accounts/{acc_id}/syncs` has been deprecated and removed in favor of [Updates](/reference/accounts/updates/overview)
  * Additionally, data sync status fields at the account liability object have been deprecated and removed in favor of status fields within an [Update](/reference/accounts/updates/overview)
  * `liability.data_status`, `liability.data_sync_type`, `liability.data_sync_type`, `liability.data_last_successful_sync`, `liability.data_source`,
    `liability.data_updated_at`, `liability.data_updated_at`, `liability.data_status_error`

* ⛔ Account capabilities have been deprecated and removed from the Account object.
  * `capabilities`, `available_capabilities`, and `pending_capabilities` have been deprecated and removed in favor of [Products](/reference/accounts/products/overview), [Subscriptions](/reference/accounts/subscriptions/overview), and [Account Verification Sessions](/reference/accounts/verification-sessions/overview)
    * The `products` array returns the products the account has access to, replacing `capabilities`.
    * The `restricted_products` array returns the products the account does not have access to, replacing `pending_capabilities`.
    * The account [Products](/reference/accounts/products/overview) endpoint outlines the products (*capabilities*) an account has access to and provides an overview of the status of all the products.

* ⛔ Account payment status (`liability.payment_status`) has been deprecated and removed in favor of [Products](/reference/accounts/products/overview)

* ⛔ Account clearing (`clearing`) and liability hash (`liability.hash`) has been deprecated and removed in `2024-04-04`

* The following fields have been modified in the [Account object](/reference/accounts/overview):

  <AccordionGroup>
    <Accordion title="Fields removed from Account" icon="circle-minus">
      * `liability.payment_status`
      * `liability.data_status`
      * `liability.data_sync_type`
      * `liability.data_last_successful_sync`
      * `liability.data_source`
      * `liability.data_updated_at`
      * `liability.data_status_error`
      * `liability._liability_type_` - where `liability_type` is any of the [Account Liability Types](/reference/accounts/overview#account-liability-types).
      * `liability.hash`
      * `clearing`
      * `capabilities`
      * `available_capabilities`
      * `pending_capabilities`
    </Accordion>

    <Accordion title="Fields added to Account" icon="circle-plus">
      * `liability.name`
      * `liability.fingerprint`
      * `latest_verification_session`
      * `update`
      * `balance`
      * `card_brand`
      * `payoff`
      * `products`
      * `restricted_products`
      * `subscriptions`
      * `available_subscriptions`
      * `restricted_subscriptions`
    </Accordion>
  </AccordionGroup>

#### Deprecated endpoints

* Account Syncs: `/accounts/{acc_id}/syncs` removed in favor of [Updates](/reference/accounts/updates/overview)
* Account Sync Enrollment: `/accounts/{acc_id}/sync_enrollment` removed in favor of [Updates](/reference/accounts/updates/overview) and [Subscriptions](/reference/accounts/subscriptions/overview)
* Account Verification: `/accounts/{acc_id}/verification` removed in favor of [Account Verification Sessions](/reference/accounts/verification-sessions/overview)
* Account Sensitive: `/accounts/{acc_id}/sensitive` removed in favor of [Sensitive](/reference/accounts/sensitive/overview)
* Account Card: `/accounts/{acc_id}/card` removed in favor of [Card Brand](/reference/accounts/card-brands/overview), [Sensitive](/reference/accounts/sensitive/overview) and Credit Card [Account Verification Sessions](/reference/accounts/verification-sessions/overview)
* Account Payment History: `/accounts/{acc_id}/payment_history` is no longer supported in `2024-04-04`
* Account Details: `/accounts/{acc_id}/details` is no longer supported in `2024-04-04`
* Bulk Sensitive: `/accounts/{acc_id}/bulk_sensitive` is no longer supported in `2024-04-04`
* Bulk Sync: `/accounts/{acc_id}/bulk_sync` is no longer supported in `2024-04-04`
* Account Vehicle: `/accounts/{acc_id}/match_vehicle` is no longer supported in `2024-04-04`
* Routing Numbers: `/routing_numbers` is no longer supported in `2024-04-04`
* BINs: `/bins` is no longer supported in `2024-04-04`

## Additional Changes

### Expand Parameter

New `expand` query parameter for expanding certain properties from an ID to their respective objects in-line in the response body.

Applicable to both Entities and Accounts, allowing expansion of fields such as `connect`, `credit_score`, `update`, `balance`, `payoff`, `sensitive`, `transactions`, `card_brand`, and `latest_verification_session`.

See [Expanding Resources](/reference/expanding) for more information.

### Elements

Introducing the [Connect element](/elements/connect/overview) as the primary way to connect user accounts and complete necessary verifications.

The Auth element has been deprecated in favor of Connect.

See [Connect guide](/elements/connect/overview) for step-by-step instructions on leveraging Connect.


# Introducing API Version 2025-07-04
Source: https://docs.methodfi.com/changelog/api-versions/2025-07-04



We're excited to announce the release of **API version `2025-07-04`**, featuring key improvements to our **Card Brand** model and the introduction of the new **Card Products API**.
This version enhances data consistency across card networks, issuers, and products — enabling more structured integrations and cleaner brand experiences for your users.

***

## What’s New

### Card Brand API

<img alt="Card Brands" />

The [Card Brand API](/reference/accounts/card-brands/overview) has been expanded with a **richer, more structured object**.
This change makes it easier to **identify, display, and integrate** specific card products while ensuring consistent metadata across networks and issuers.

**Key improvements:**

* Brand data is now **fully nested**, encapsulating `network`, `issuer`, and visual assets under each brand.
* New fields such as `card_product_id`, `description`, and `type` provide more granular control when mapping and displaying cards.
* Removed legacy fields (`last4`, `shared`) for a cleaner, product-centric response format.

<Note>Available when passing `Method-Version: 2025-07-04` in the request header.</Note>

<Accordion title="Previous Response">
  ```json theme={null}
  {
    "id": "cbrd_eVMDNUPfrFk3e",
    "account_id": "acc_yVf3mkzbhz9tj",
    "network": "visa",
    "issuer": "Chase",
    "last4": "8623",
    "brands": [
      {
        "id": "brand_AMxtjQzAfDCRP",
        "name": "Chase Sapphire Reserve",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
      }
    ],
    "status": "completed",
    "shared": false,
    "source": "network",
    "error": null,
    "created_at": "2024-03-19T01:05:37.247Z",
    "updated_at": "2024-03-19T01:05:37.247Z"
  }
  ```
</Accordion>

<Accordion title="New Response">
  ```json theme={null}
  {
    "id": "cbrd_Accm7P6t6mYQP",
    "account_id": "acc_LxwEqNicr66yP",
    "brands": [
      {
        "id": "pdt_15_brd_1",
        "card_product_id": "pdt_15",
        "description": "Chase Sapphire Reserve",
        "name": "Chase Sapphire Reserve",
        "issuer": "Chase",
        "network": "visa",
        "network_tier": "infinite",
        "type": "specific",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
      }
    ],
    "status": "completed",
    "source": "method",
    "error": null,
    "created_at": "2025-08-12T00:56:50.139Z",
    "updated_at": "2025-08-12T00:56:50.139Z"
  }
  ```
</Accordion>

***

### Card Products API

We’re introducing the new [Card Products API](/reference/card-products/overview) — a **directory of card products** that allows you to retrieve all associated `Card Brand` objects for a given product.

This endpoint gives developers a unified way to reference and display card metadata (art, network, tier, and issuer) across all variants of a card family.

<Note>Available when passing `Method-Version: 2025-07-04` in the request header.</Note>

<Accordion title="Example Request">
  ```bash theme={null}
  curl https://production.methodfi.com/card_products/pdt_17 \
    -H "Method-Version: 2025-07-04" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```
</Accordion>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "pdt_17",
    "name": "Chase Freedom",
    "issuer": "Chase",
    "type": "specific",
    "brands": [
      {
        "id": "pdt_17_brd_1",
        "description": "Chase Freedom",
        "network": "visa",
        "network_tier": "signature",
        "default_image": "https://static.methodfi.com/card_brands/fb5fbd6a5d45b942752b9dc641b93d1f.png"
      },
      {
        "id": "pdt_17_brd_2",
        "description": "Chase Freedom",
        "network": "visa",
        "network_tier": "standard",
        "default_image": "https://static.methodfi.com/card_brands/6cb697528b0771f982f7c0e8b8869de3.png"
      }
    ]
  }
  ```
</Accordion>

***

## Breaking Changes

* **Card Brand response shape updated**

  * `network` and `issuer` are now nested under each `brand`.
  * New fields: `card_product_id`, `description`, `type`.
  * Removed fields: `last4`, `shared`.

***

## Why It Matters

This release unifies how card data is modeled and consumed across the Method platform.
By standardizing the `Card Brand` object and introducing a canonical `Card Products` directory, developers can now:

* Reliably map and display card details across networks and issuers
* Build consistent card selection and branding experiences in their apps
* Reduce dependency on ad-hoc naming or inferred card data

***

## Upgrading to 2025-07-04

The new API version is available to all existing teams. New teams are automatically pinned to **`2025-07-04`**.

* **Request Header:** Set `Method-Version` to `2025-07-04`. See [API Versioning](/reference/versioning#api-versioning) for more information.
* **Client Libraries:** `method-node` and `method-python` **v2.0.0+** default to this version.

> Once upgraded, rollbacks to prior API versions are not supported. Contact your Method CSM for upgrade assistance.

***

### Upgrade Support

Our technical integration team is available to guide you through the migration. Contact your Method CSM to schedule a review of your current card integration or to receive a personalized upgrade checklist.


# Introducing API Version 2025-12-01
Source: https://docs.methodfi.com/changelog/api-versions/2025-12-01



We're excited to announce the release of **API version `2025-12-01`**, featuring the new **Payment Instruments API** for inbound funding workflows.
This version enables liability accounts to receive direct payments via ACH or wire transfer — allowing third parties to send funds directly to liability accounts without requiring explicit Payment creation.

***

## What's New

### Payment Instruments API

Method now supports **inbound funding workflows** with the introduction of a new `PaymentInstrument` type: `inbound_achwire_payment`.
This feature allows liability accounts (e.g., loans, credit cards) to receive direct payments via ACH or wire transfer.

**Key features:**

* Provisions a unique virtual account number and routing number linked to a specific Method Account, effectively making the underlying liability routable
* Third parties can send funds directly to these credentials, and Method automatically applies the funds to the associated account, without requiring you to explicitly create a Payment
* Supports use cases such as payroll, refinancing, and other direct payment scenarios

**How it works:**

1. **Create Instrument**: Create a Payment Instrument of type `inbound_achwire_payment` for a specific Method Account
2. **Receive Banking Details**: Method returns unique `account_number` and `routing_number`
3. **Share with a Third Party**: Provide these banking details to a third party (e.g., payroll provider, refinance lender, or another bank)
4. **Inbound Transfer**: When funds are sent to these credentials, Method receives the inbound ACH or wire transfer
5. **Automatic Application**: Method automatically applies the received funds to the associated account

<Note>Available when passing `Method-Version: 2025-12-01` in the request header.</Note>

<Accordion title="Example Request">
  ```bash theme={null}
  curl https://production.methodfi.com/accounts/acc_4m9amk4KFiaQX/payment_instruments \
    -X POST \
    -H "Method-Version: 2025-12-01" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "inbound_achwire_payment"
    }'
  ```
</Accordion>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "pmt_inst_cLbaArHhfDBDf",
    "account_id": "acc_GAzrD99cUqGEN",
    "type": "inbound_achwire_payment",
    "card": null,
    "network_token": null,
    "inbound_achwire_payment": {
      "account_number": "2517228863",
      "routing_number": "026015244"
    },
    "chargeable": true,
    "status": "completed",
    "error": null,
    "created_at": "2025-12-11T00:12:58.639Z",
    "updated_at": "2025-12-11T00:12:58.639Z"
  }
  ```
</Accordion>

See [Payment Instruments](/reference/accounts/payment-instruments/overview) for more information.

***

### Simulate API

The [Simulate API](/reference/simulations/overview) now supports simulating inbound ACH / wire payments for `inbound_achwire_payment` Payment Instruments — making it easier for developers to test inbound payment flows in the development environment.

**[Simulate Inbound ACH/Wire Payments](/reference/simulations/payment_instruments/create)**\
This endpoint allows developers to simulate receiving an inbound payment and triggers the same automatic payment application logic used in production.

<Note>Available when passing `Method-Version: 2025-12-01` in the request header.</Note>

<Warning>This API is available in the development environment only.</Warning>

For more information, visit the [Simulations API](/reference/simulations/overview) documentation.

***

## Breaking Changes

* **Payment Instrument product names changed**

  * The `payment_instrument` product name has been split into three separate product names:
    * `payment_instrument.card`
    * `payment_instrument.network_token`
    * `payment_instrument.inbound_achwire_payment`
  * In previous versions (`2024-04-04`, `2025-07-04`), the Account object's `products`, `restricted_products`, `subscriptions`, `available_subscriptions`, and `restricted_subscriptions` arrays contained the single product name `payment_instrument`.
  * In `2025-12-01`, these arrays now contain the three separate product names instead of the single `payment_instrument` name.

***

## Why It Matters

This release enables new inbound funding workflows that simplify payment collection for liability accounts.
By introducing `inbound_achwire_payment` Payment Instruments, developers can now:

* Enable third parties to send payments directly to liability accounts without explicit Payment creation
* Streamline payroll, refinancing, and other direct payment scenarios
* Automatically apply inbound transfers to the associated account
* Test inbound payment flows more easily with enhanced Simulate API support

***

## Upgrading to 2025-12-01

The new API version is available to all existing teams. New teams are automatically pinned to **`2025-12-01`**.

* **Request Header:** Set `Method-Version` to `2025-12-01`. See [API Versioning](/reference/versioning#api-versioning) for more information
* **Client Libraries:** `method-node` and `method-python` **v2.1.0+** default to this version

> Once upgraded, rollbacks to prior API versions are not supported. Contact your Method CSM for upgrade assistance.

***

### Upgrade Support

Our technical integration team is available to guide you through the migration. Contact your Method CSM to schedule a review of your current payment integration or to receive a personalized upgrade checklist.


# Introducing API Version 2026-03-30
Source: https://docs.methodfi.com/changelog/api-versions/2026-03-30



We're excited to announce the release of **API version `2026-03-30`**, featuring redesigned **Attributes** for both **Entities** and **Accounts**.
This release expands the attributes product with richer computed outputs, a unified per-attribute result shape, and support for asynchronous attribute computation workflows.

***

## What's New

### Entity Attributes

The [Entity Attributes API](/reference/entities/attributes/overview) now returns a broader set of aggregated financial attributes computed across an Entity's connected accounts.
These attributes are organized across categories such as revolving credit cards, personal loans, mortgages, installment balances, and overall utilization.

**Key improvements:**

* Introduces a richer set of financial attributes, including balances, utilization trends, deltas, delinquency signals, and payment behavior metrics
* Returns attributes in a simplified `{ value, error }` shape — `error` uses the standard `{ type, sub_type, code, message }` format when the attribute could not be computed
* Computes all supported entity attributes automatically as part of the request lifecycle
* Supports asynchronous processing so teams can poll or rely on webhook-driven workflows for completion

<Note>Available when passing `Method-Version: 2026-03-30` in the request header.</Note>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "attr_dADraNgLBrhgL",
    "entity_id": "ent_EQ3FCTzDUmmCb",
    "status": "completed",
    "attributes": {
      "revolving_credit_card_balance_total": {
        "value": 968400,
        "error": null
      },
      "credit_limit_total": {
        "value": 8100000,
        "error": null
      },
      "credit_card_utilization": {
        "value": 11.96,
        "error": null
      },
      "overall_utilization": {
        "value": 70.5,
        "error": null
      }
    },
    "error": null,
    "created_at": "2026-04-09T17:02:47.910Z",
    "updated_at": "2026-04-09T17:04:35.220Z"
  }
  ```
</Accordion>

***

### Account Attributes

The [Account Attributes API](/reference/accounts/attributes/overview) has been expanded into a dedicated account-level attributes product.
Returned attributes now vary by liability type, including support for credit cards, personal loans, and mortgages.

**Key improvements:**

* Adds account-level financial attributes such as utilization trends, delinquency flags, and installment estimates
* Returns attributes in a simplified `{ value, error }` shape with standardized error objects
* Supports asynchronous attribute computation workflows for account requests
* Adds webhook support for account attribute lifecycle events

<Note>Available when passing `Method-Version: 2026-03-30` in the request header.</Note>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "acc_attr_cWBKqwVP87kim",
    "account_id": "acc_4m9amk4KFiaQX",
    "status": "completed",
    "attributes": {
      "type": {
        "value": "credit_card",
        "error": null
      },
      "usage_pattern": {
        "value": "revolver",
        "error": null
      },
      "delinquency_flag": {
        "value": false,
        "error": null
      },
      "utilization": {
        "value": 11.96,
        "error": null
      }
    },
    "error": null,
    "created_at": "2026-04-09T17:02:47.910Z",
    "updated_at": "2026-04-09T17:04:35.220Z"
  }
  ```
</Accordion>

***

### Account Attribute Subscriptions

Accounts can now be enrolled in an `attribute` [Subscription](/reference/accounts/subscriptions/overview) for
continuous monitoring of an Account's financial attributes. Once enrolled, Method automatically computes new
[Account Attributes](/reference/accounts/attributes/overview) and notifies your team via webhooks as they change.

```bash theme={null}
curl https://production.methodfi.com/accounts/{acc_id}/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "enroll": "attribute"
  }'
```

* Available for credit card, personal loan, and mortgage accounts
* The `attribute` subscription appears in an Account's `available_subscriptions` once eligible

<Note>Available when passing `Method-Version: 2026-03-30` in the request header.</Note>

***

### New Webhook Events

This version adds webhook coverage for the new account attribute resource lifecycle.

**New events:**

* `entity_attribute.create`
* `entity_attribute.update`
* `account_attribute.create`
* `account_attribute.update`

See [Webhooks](/reference/webhooks/overview) for the complete event list.

***

## Breaking Changes

* **Entity Attributes request semantics changed**

  * `POST /entities/{ent_id}/attributes` now computes all supported attributes automatically
  * The legacy request body for selecting specific `credit_health_*` attributes is no longer documented for `2026-03-30`

* **Entity Attributes response shape changed**

  * Legacy attribute payloads that returned `value` and `rating` have been replaced with a simplified `{ value, error }` shape
  * On success, `error` is `null`. On failure, `error` contains a standard `{ type, sub_type, code, message }` object (e.g. `ENTITY_ATTRIBUTE_INSUFFICIENT_DATA` code `27001` for entity attributes, `ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA` code `28001` for account attributes)
  * Attribute names now reflect the new attribute model

* **Account Attributes response shape changed**

  * Account attribute responses now use the same simplified `{ value, error }` result structure
  * Attribute availability now depends on the account's liability type

* **Attributes create endpoints are asynchronous**

  * Create requests now return an in-progress resource that must be polled or observed via webhook until completion

***

## Why It Matters

This release makes the attributes product more useful for underwriting, servicing, monitoring, and decisioning workflows.
With this release, developers can:

* Retrieve a richer set of entity- and account-level financial signals
* Build against a consistent result format across attributes
* Handle unavailable computations explicitly using standardized `error` objects with `type`, `sub_type`, `code`, and `message`
* Use asynchronous workflows that better fit long-running computations

***

## Upgrading to 2026-03-30

The new API version is available to all existing teams. New teams are automatically pinned to **`2026-03-30`**.

* **Request Header:** Set `Method-Version` to `2026-03-30`. See [API Versioning](/reference/versioning#api-versioning) for more information.
* **Client Libraries:** Check your Method SDK version and upgrade guidance before moving production traffic to the new API version.

> Once upgraded, rollbacks to prior API versions are not supported. Contact your Method CSM for upgrade assistance.

***

### Upgrade Support

Our technical integration team is available to help review your current usage of Attributes and plan a migration to `2026-03-30`. Contact your Method CSM for upgrade support.


# Create a Connect Element Token
Source: https://docs.methodfi.com/elements/connect/create_connect_token



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

To start using Connect, you will first need to create a [Connect Element Token](/reference/elements/tokens).
There are a few different use cases that will determine what you pass to the endpoint.

### New Entities

If you do not have any identity information about your users, you will likely create a token using a payload similar to this:

```json theme={null}
{
  "type": "connect",
  "connect": {
    "products": ["balance"],
    "entity": {
      "type": "individual",
      "individual": {}
    }
  }
}
```

This will return a token that you can use to create a new entity and connect their accounts. Fill in the `products` array with a list of the different products you want to connect (for example `["balance", "card"]`).

### New Entities with Partial Information

If you have some information already about a given user (such as their name), you can pass that information into the `individual` object:

```json theme={null}
{
  "type": "connect",
  "connect": {
    "products": ["balance"],
    "entity": {
      "type": "individual",
      "individual": {
        "first_name": "Kevin",
        "last_name": "Doyle"
      }
    }
  }
}
```

You can also pass in a user's phone number, address, DOB, or the last 4 digits of their SSN to make the identity verification process faster.

### Using with Existing Entities

You can also pass in an existing entity\_id:

```json theme={null}
{
  "type": "connect",
  "entity_id": "ent_au22b1fbFJbp8",
  "connect": {
    "products": ["balance"]
  }
}
```

### Using with Existing Accounts

If you also have specific accounts you'd like to connect, you can pass the account ids:

```json theme={null}
{
  "type": "connect",
  "entity_id": "ent_au22b1fbFJbp8",
  "connect": {
    "products": ["balance"],
    "accounts": ["acc_k8LAKDnED7kti", "acc_KUaFnxn7eUAeH"]
  }
}
```

<RequestExample>
  ```bash cURL theme={null}
  curl https://dev.methodfi.com/elements/token \
    -X POST \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "connect",
      "connect": {
        "products": ["balance"],
        "entity": {
          "type": "individual",
          "individual": {
            "first_name": "Kevin",
            "last_name": "Doyle"
          }
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const token = await method.elements.token.create({
    type: "connect",
    connect: {
      products: ["balance"],
      entity: {
        type: "individual",
        individual: {
          first_name: "Kevin",
          last_name: "Doyle"
        }
      }
    }
  });
  ```

  ```python Python theme={null}
  token = method.elements.token.create({
    'type': "connect",
    'connect': {
      'products': ["balance"],
      'entity': {
        'type': "individual",
        'individual': {
          'first_name': "Kevin",
          'last_name': "Doyle"
        }
      }
    }
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "element_token": "pk_elem_qPmypE9wwphr3WL3yTj7JhxjrPzAmK8G"
  }
  ```
</ResponseExample>


# Getting Connect Results
Source: https://docs.methodfi.com/elements/connect/get_results



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

In addition to [listening for the success event](/elements/events/overview), the result of the Connect session can also be retrieved by calling the `results` endpoint with the element token for that session.

```bash theme={null}
GET /elements/token/{element_token}/results
```

See [Retrieve Element Results](/reference/elements/results) for more information about this endpoint.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/elements/token/pk_elem_dDe4r9M6X3Ad9zjpbgYpzLNtRCXfhPYR/results \
    -X GET \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .elements
    .token
    .results('pk_elem_dDe4r9M6X3Ad9zjpbgYpzLNtRCXfhPYR');
  ```

  ```python Python theme={null}
  response = method
    .elements
    .token
    .results('pk_elem_dDe4r9M6X3Ad9zjpbgYpzLNtRCXfhPYR')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "authenticated": true,
    "cxn_id": "cxn_xr86xHEcWmpmB",
    "accounts": [
      "acc_jPXLFqd6KzH3N",
      "acc_DALLeLrj3TH8h"
    ],
    "entity_id": "ent_GWKYtnFyE79db",
    "events": [
      {
        "type": "open",
        "metadata": {
          "element_type": "connect",
          "op": "open"
        },
        "timestamp": "2024-04-25T02:35:28.097Z"
      },
      {
        "type": "success",
        "metadata": {
          "entity_id": "ent_GWKYtnFyE79db",
          "accounts": [
            "acc_jPXLFqd6KzH3N",
            "acc_DALLeLrj3TH8h"
          ],
          "element_type": "connect",
          "op": "success"
        },
        "timestamp": "2024-04-25T02:35:57.120Z"
      },
      {
        "type": "exit",
        "metadata": {
          "element_type": "connect",
          "op": "exit"
        },
        "timestamp": "2024-04-25T02:35:57.138Z"
      }
    ]
  }
  ```
</ResponseExample>


# Launching a Connect Session
Source: https://docs.methodfi.com/elements/connect/launch_connect



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

After creating a Connect Element token, you can launch a Connect session in a webview.

## Initializing the Connect Element

The Connect Element is optimized to work within Webviews, including on iOS and Android. Open a webview in your app to your desired environment using the `element_token` you generated.

Example:

Using the [Element SDK](/elements/libraries) (recommended):

```javascript theme={null}
method.open('pk_elem_BtzySdrQGFmLdAPw5gXSQNCxQkhCkT3K');
```

Without SDK:

```bash theme={null}
https://elements.production.methodfi.com/
  ?token=pk_elem_4PpMTPcchb49VBjwP3bREKhMN93hrQHR
```


# Connect Overview
Source: https://docs.methodfi.com/elements/connect/overview



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Connect is the primary way to leverage Method Elements to connect your users' liabilities. Connect allows you to verify a user's identity, gather their consent, and complete any needed verifications to ensure their accounts are connected to the desired Method [Products](/reference/accounts/products/overview).

The Connect element itself consists of two main steps:

<Steps>
  <Step title="Auth">
    Verify the user's identity and connect their accounts. If no entity
    information is provided when creating the Connect element token, the user
    will be asked to provide identity information such as name, phone, last 4
    digits of SSN, DOB, or address.
  </Step>

  <Step title="Account Verification">
    Request any additional information needed from the user to connect their
    accounts and leverage specific products.
  </Step>
</Steps>


# Environments
Source: https://docs.methodfi.com/elements/environments



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Elements are available in each of our three [Environments](/reference/environments):

```
https://elements.dev.methodfi.com (Development)
https://elements.sandbox.methodfi.com (Sandbox)
https://elements.production.methodfi.com (Production)
```

## Considerations for Connect

When using the [Connect Element](/elements/connect/overview), there are a few
things to keep in mind related to the different environments.

### Development Environment

In dev, you can use the following phone numbers to ensure your entity gets verified:

```bash theme={null}
Phone        | Required Fields
------------------------------
+15121231111 | Name, Phone
+15121231112 | Name, Phone, DOB (Date of Birth)
+15121231113 | Name, Phone, DOB (Date of Birth), Address
```

You can either pass in the required fields on token creation or during the Connect session.

**Note**: If you do not use one of the above phone numbers, your dev entities will not be verified.


# General Events
Source: https://docs.methodfi.com/elements/events/general_events



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

## Open

The open event is triggered when an element has successfully launched. No additional data is passed at this time.

```bash theme={null}
methodelements://general
  ?op=open
  &element_type=connect
```

The event payload will have the following form:

<ParamList />

## Error

The error event is sent for any element that encounters any error while it's active.

```bash theme={null}
methodelements://general
  ?op=error
  &element_type=unknown
  &type=INVALID_REQUEST
  &sub_type=EXPIRED_TOKEN
  &message=The public element token is no longer valid. Element tokens are short lived and can only be used once. Request a new element token and try your request again.
  &code=400
```

The event payload will have the following form:

<ParamList />

## Exit

The exit event is the last event in the element flow, at this point your app should no longer present the Method Element. Exit is triggered after an error, a user requested exit or a successful element event.

```bash theme={null}
methodelements://general
  ?op=exit
  &element_type=connect
```

The event payload will have the following form:

<ParamList />


# Events Overview
Source: https://docs.methodfi.com/elements/events/overview



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Communication between the Element and your app can be handled either by PostMessage communication or via HTTP redirects.

## Listening to Events

We strongly recommend using one of the [Element SDKs](/elements/libraries) to make listening to events easy. They provide you with callback functions that are invoked every time a specific type of event occurs (such as `open`, `success`, `exit`, etc).

Each type of Element will emit its own events. See [General Events](/elements/events/general_events) and [Element Specific Events](/elements/events/specific_events) for more information about the events that are emitted.

### PostMessage without SDK

To receive events via PostMessage, pass the query parameter `event_channel=message` to the Elements url. For example:

```bash theme={null}
https://elements.production.methodfi.com
  ?token=pk_elem_4PpMTPcchb49VBjwP3bREKhMN93hrQHR
  &event_channel=message
```

To listen to the emitted events, add an event listener onto the window object:

```javascript theme={null}
window.addEventListener('message', function(event) {
  const { payload, type } = event.data;
  console.log('Received event!', type, payload);
});
```

### Redirects

Redirects are the default way of listening to element events if you are not using one of the SDKs. Your webview / app should intercept the redirects in order to react accordingly to state changes. All redirect URLs will have the scheme ("prefix") `methodelements`. The event source will be the URL host and the payload will be query strings.

HTTP redirects from Method Elements are in the following format:

```bash theme={null}
methodelements://{event_source}?{event_data}
```


# Element Specific Events
Source: https://docs.methodfi.com/elements/events/specific_events



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

## Connect

Connect will emit a `success` event when the user has successfully completed all required authentication and verification:

```bash theme={null}
methodelements://connect
  ?op=success
  &element_type=connect
  &entity_id=ent_WyDmJnQgaxVRH
  &accounts=["acc_PFUNazUbpUpfm","acc_gjWr4Cb8H7TLz"]
```

When parsed, will result in the following JSON

```json theme={null}
{
  "op": "success",
  "element_type": "connect",
  "entity_id": "ent_WyDmJnQgaxVRH",
  "accounts": ["acc_PFUNazUbpUpfm","acc_gjWr4Cb8H7TLz"]
}
```

This will list all of the accounts that were consented and connected to at least one of the products passed into the Element token creation (Note: Some accounts are ineligible for some products).

## Other Events

For more granular information about specific actions a user is taking, `auth` and `account_verification` will emit the following events.

### Auth

Auth will emit a variety of events that describe how the user is progressing through the authentication process. Most events are of the following form:

```bash theme={null}
AUTH_{STEP}_{ACTION}
```

STEP will reference a step during the auth process: `INTRO`, `NAME`, `PHONE`, `PHONE_VERIFY`, `DOB`, `ADDRESS`, `SSN4`, `SECQ`, and `CONSENT`.

ACTION will refer to the action the user took: `OPEN`, `CONTINUE`, `SUBMIT`, and `CLOSE`.

**Note**: Not all steps will have all actions, and that there are a few actions that do not follow this pattern

For example, if the user was prompted for the last 4 of their SSN, then submitted their info and was directed to the DOB page, you would see the following events:

```bash theme={null}
AUTH_SSN4_OPEN
AUTH_SSN4_CONTINUE
AUTH_DOB_OPEN
```

### Account Verification

Account Verification will emit a variety of events using a similar structure to auth:

```bash theme={null}
AVF_{STEP}_{ACTION}
```

STEP will reference a step during the account verification process: `ACCOUNT_LIST`, `LEARN_MORE`, and `ACCOUNT_VERIFY`.

ACTION will refer to the action the user took: `OPEN`, `CONTINUE`, `SUBMIT`, `SKIP`, and `CLOSE`.

For example, if the user was prompted to verify their credit card, then submitted their info and was directed to the success screen, you would see the following events:

```bash theme={null}
AVF_ACCOUNT_VERIFY_OPEN
AVF_ACCOUNT_VERIFY_SUBMIT
AVF_SUCCESS_OPEN
```


# Element SDKs
Source: https://docs.methodfi.com/elements/libraries



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Method offers a variety of libraries for your frontend application to make integrating
with Elements easy and simple. We also offer [backend libraries](TODO:Where_is_link)
to help manage token creation and using the API more broadly.

## Frontend Libraries

Depending on your application, Method offers three different frontend libraries to help you integrate with Element:

1. [method-js](https://docs.methodfi.com/libraries/js-sdk), for vanilla JavaScript applications
2. [react-method-elements](https://github.com/MethodFi/react-method-elements), for React applications
3. [react-native-method-elements](https://github.com/MethodFi/react-native-method-elements), for React Native applications


# Overview
Source: https://docs.methodfi.com/elements/overview



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Method Elements is a collection of embeddable UI components that make it easy to
integrate Method's API into your experience. Using Method Elements, you can
securely identify your users, connect their liabilities, and move money across
accounts.

## Using Method Elements

<Steps>
  <Step title="Create Element Token">
    Your app's backend will generate an `element_token` by hitting the
    [/elements/token](/reference/elements/tokens) endpoint.
  </Step>

  <Step title="Initialize Element">
    Using the `element_token`, Method Elements will be
    [initialized](/elements/libraries) with the intended Element for your user.
  </Step>

  <Step title="Handling Element Events">
    While your user interacts with an Element,
    [events](/elements/events/overview) will be triggered for your app to
    handle.
  </Step>
</Steps>

### Authentication

Ensure you have an [API key created](/reference/authentication) for your organization in order to request an Element token.


# Handling Account Edge Cases
Source: https://docs.methodfi.com/guides/accounts/edge-cases

How to handle verification requirements, product limitations, and status changes.

## Handling Account Edge Cases

### 1. Accounts Requiring Verification

Some liability accounts discovered through [Connect](/guides/connect/overview) may appear in `restricted_products` with capabilities that require elevated verification (e.g., an account verification session). This is common for payment-capable accounts where Method needs additional confirmation. Create an [Account Verification Session](/reference/accounts/verification-sessions/create) to unlock these products.

### 2. Product Limitations by Account Type

Not all accounts support all products. Credit cards support [Card Brand](/reference/accounts/card-brands/overview) and [Payment Instruments](/reference/accounts/payment-instruments/overview); auto loans support [Payoffs](/reference/accounts/payoffs/overview); most liability types support [Updates](/guides/updates/overview) and [Balances](/reference/accounts/balances/overview). Always check the `products` array. See the [Liability Types](/guides/accounts/liability-types) page for a breakdown.

### 3. Status Changes Mid-Operation

If an account transitions to `disabled` or `closed` while you have in-flight operations (a pending payment, an in-progress update), those operations may fail. Design your flows to:

* Check account status before initiating operations
* Handle `account.disabled` and `account.closed` [webhooks](/reference/webhooks/overview) gracefully
* Show appropriate UI messages when an account is no longer available

See the [Account Lifecycle](/guides/accounts/lifecycle) guide for status transitions and webhook details.

### 4. Duplicate Accounts

[Connect](/guides/connect/overview) may discover the same underlying account multiple times if the user has accounts reported under slightly different names or through different credit bureaus. Method does attempt to de-duplicate these liability accounts, however instances do occur. Reach out to your CSM if this uncommon event occurs for one of your users.

### 5. Authorized User Accounts

Connect discovers all accounts on a user's credit report, including accounts where they are an authorized user (not the primary holder). The `liability.ownership` field indicates the relationship: `primary`, `authorized`, `joint`, or `unknown`. Consider whether your product should treat authorized-user accounts differently (e.g., payments on authorized-user cards may not be appropriate for [debt consolidation flows](/guides/use-cases/lending/debt-consolidation)).

### 6. Closed / Paid-Off Accounts

Accounts with zero balance or closed status at the financial institution may still appear in Connect results (they remain on the credit report). These accounts will have `status: closed` and limited [product](/reference/accounts/products/overview) availability. Filter them in your UI if they're not relevant to your use case.

### 7. Consent and Data Retention

When an Entity's consent is withdrawn (via the [Consent endpoint](/reference/accounts/consent/withdraw)), their accounts are disabled and data access is revoked. Your application should handle this gracefully — remove the accounts from active views and inform the user.

***

The key principle: design your application to check account status and product availability dynamically, and listen for [webhook notifications](/reference/webhooks/overview) about status changes. Accounts are living objects, and your application should respond to their state changes in real time rather than assuming a static state.

For the full Accounts API, see the [Accounts reference](/reference/accounts/overview).


# Funding Accounts
Source: https://docs.methodfi.com/guides/accounts/funding

Setting up and verifying your corporate payment source.

## Funding Accounts — Setting Up Payment Sources

Before payments can flow through Method, your platform needs a verified funding source — an ACH account that serves as the origin for all outbound payments. This is typically your company's corporate checking account, not an account belonging to your end users.

Your platform creates the funding account by [calling the Accounts API](/reference/accounts/create) with the routing number and account number for your corporate bank account:

```bash theme={null}
curl https://production.methodfi.com/accounts \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "holder_id": "ent_y1a9e1fbnJ1f3",
    "ach": {
      "routing": "021000021",
      "number": "1234567890",
      "type": "checking"
    }
  }'
```

The account must then be verified to confirm your organization controls it. Once verified, this single funding account can serve as the payment source across all of your users' liability payments.

<Note>
  Funding accounts are set up by your team (the platform integrating with Method), not by your end users. End users interact with liability accounts discovered through Connect — your corporate funding account is the source that powers payments to those liabilities.
</Note>

Method supports several verification approaches for funding accounts:

<CardGroup>
  <Card title="Micro-Deposits" icon="coins">
    The traditional verification method. Method sends two small deposits (typically a few cents each) to your corporate bank account. Your team confirms the deposit amounts, proving control of the account. This is universally supported but introduces a 1–2 business day delay while deposits settle.
  </Card>

  <Card title="Plaid" icon="bolt">
    Instant verification through Plaid's bank linking flow. If your platform already uses Plaid, this is a natural fit — authenticate with your bank through Plaid, and the verified account details are passed to Method. No waiting for micro-deposits.
  </Card>

  <Card title="MX" icon="bolt">
    Similar instant verification through MX's bank connectivity platform. Choose this if your platform uses MX for bank account linking.
  </Card>

  <Card title="Teller" icon="bolt">
    Another instant verification path through Teller's banking API. Like Plaid and MX, this eliminates the micro-deposit delay by verifying the account through direct bank authentication.
  </Card>
</CardGroup>

<Note>
  For most teams, instant verification (via Plaid, MX, or Teller) is strongly preferred because it eliminates the multi-day delay of micro-deposits and simplifies initial setup. If you don't have an existing relationship with any of these providers, Plaid is the most widely adopted option.
</Note>

## Verification Flow

1. Create the funding account ([`POST /accounts`](/reference/accounts/create))
2. Create a verification session ([`POST /accounts/{id}/verification_sessions`](/reference/accounts/verification-sessions/create)) specifying your preferred method
3. Complete the verification:
   * **Micro-deposits**: Wait 1–2 business days, then [update the session](/reference/accounts/verification-sessions/update-microdeposits) with the deposit amounts
   * **Plaid / MX / Teller**: Pass the processor token from your aggregator to the update endpoint ([Plaid](/reference/accounts/verification-sessions/update-plaid), [MX](/reference/accounts/verification-sessions/update-mx), [Teller](/reference/accounts/verification-sessions/update-teller))
4. Listen for the `account.active` [webhook](/reference/webhooks/overview) — the account is now ready for payments

See the [Account Verification Sessions reference](/reference/accounts/verification-sessions/overview) for full API details.

<Warning>
  If verification fails (wrong micro-deposit amounts, invalid aggregator token), the verification session moves to a `failed` status. You can create a new verification session to retry. After 3 failed micro-deposit attempts, the account may require a fresh set of deposits.
</Warning>

<Note>
  Your team can have multiple verified funding accounts. When [creating a payment](/reference/payments/create), you specify which funding account to use as the source. Most teams use a single corporate checking account, but you can set up additional funding accounts if your business requires separate payment sources.
</Note>


# Supported Liability Types
Source: https://docs.methodfi.com/guides/accounts/liability-types

The full range of consumer debt types Method supports.

## The Breadth of Supported Liability Types

Method supports an extensive range of liability types, reflecting the diversity of consumer debt in the real world. Supported types include:

* Credit cards — `credit_card` (from major national issuers to regional and community banks)
* Auto loans — `auto_loan` (from captive lenders like GM Financial and Toyota Motor Credit to banks and credit unions)
* Federal and private student loans — `student_loans`
* Personal and installment loans — `personal_loan`
* Mortgages and home equity lines of credit (HELOCs) — `mortgage`
* Collections accounts — `collection`
* Medical debt — `medical`
* Insurance premium obligations — `insurance`
* Utility accounts — `utility`
* Buy Now Pay Later (BNPL) accounts — `bnpl`
* Credit builder accounts — `credit_builder`
* Fintech-originated loans — `fintech`
* Other loan types — `loan`

The values above are the possible `liability.type` enum values on an Account. The `liability.sub_type` field provides additional granularity (e.g., `federal` vs. `private` for student loans, `heloc` for home equity lines). See the [Account reference](/reference/accounts/overview) for the complete list.

## How Liability Type Affects the Data Model

Each liability type also determines what enrichment data is available:

* **Credit cards**: Card brand name and visual art (via [Card Brands](/reference/accounts/card-brands/overview)), tokenized card credentials (via [Payment Instruments](/reference/accounts/payment-instruments/overview))
* **Auto loans**: Payoff quotes (via [Payoffs](/reference/accounts/payoffs/overview)), vehicle details including VIN, make, model (via [Vehicles](/reference/entities/vehicles/overview) on the Entity)
* **Student loans**: Federal vs. private distinction, servicer information
* **All types**: Credit health attributes (via [Attributes](/reference/accounts/attributes/overview)) where credit bureau data exists

<Note>
  Not every liability type supports every Method product. For example, Payments may be available for credit cards and auto loans but not for certain utility or collections accounts. Card Brand data is only relevant for credit cards. Payoff quotes are specific to auto loans. Each account carries a list of available [products](/reference/accounts/products/overview) so your application can adapt its UI and functionality based on what's supported for each specific account.
</Note>


# Account Lifecycle
Source: https://docs.methodfi.com/guides/accounts/lifecycle

Account statuses, available products, and state transitions.

## Account Lifecycle and Status

Accounts move through a defined set of statuses that reflect their current state:

| Status         | Description                                                                                                                                                                                                                                                 |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Active**     | The account is fully connected, verified (if applicable), and ready for use. All supported products are available. This is the normal operating state for most accounts.                                                                                    |
| **Processing** | The account is being set up or verified. For liability accounts, this may be a brief transitional state during discovery. For funding accounts, this typically means verification is in progress (e.g., waiting for micro-deposit confirmation).            |
| **Disabled**   | The account has been deactivated within Method. The account may still be active at the financial institution, but Method will not perform new operations on it. This can happen if the account is flagged for an issue or explicitly disabled by your team. |
| **Closed**     | Method has detected that the account is closed at the financial institution. The debt may have been paid off, the card may have been canceled, or the loan may have been settled. No new operations are available, but historical data remains accessible.  |

<Warning>
  **Common causes of Disabled status:** the Entity's [consent](/reference/accounts/consent/withdraw) was withdrawn, the Entity's verification expired or was revoked, the account was flagged by Method's risk monitoring, or your team explicitly disabled it via the API. Check the account's `error` field for the specific reason.
</Warning>

## State Transitions

* **Processing → Active**: Account setup or verification completes successfully
* **Active → Disabled**: Account is flagged for an issue or explicitly disabled. May be reversible — listen for `account.active` webhooks
* **Active → Closed**: Method detects the account is closed at the financial institution (debt paid off, card canceled, loan settled)
* **Disabled → Active**: The issue is resolved and the account is re-enabled
* **Closed** is terminal — closed accounts do not reopen

<Note>
  **Webhook tip:** Subscribe to `account.active`, `account.disabled`, and `account.closed` [webhook events](/reference/webhooks/overview) to handle transitions in real time rather than polling.
</Note>

### Key Webhooks

* `account.active`: Account transitioned to Active
* `account.disabled`: Account was disabled
* `account.closed`: Account was closed
* `account.update.completed`: An [Update](/guides/updates/overview) finished (balance/data refreshed)

## Subscriptions: Automatic Data Refresh

Instead of manually requesting [Updates](/guides/updates/overview) or [Balances](/reference/accounts/balances/overview), you can subscribe an account to automatic refresh. When subscribed, Method periodically fetches fresh data and notifies you via webhook. See [Update Subscriptions](/guides/updates/subscriptions) for details.

The `subscriptions` and `available_subscriptions` arrays on each Account show what's currently active and what can be enabled.

## Products and the Lifecycle

Each account carries a `products` array — the list of Method capabilities currently available for that account. Products include: `update` (refresh balances/data), `balance` (real-time balance), `payment` (send funds to creditor), `card_brand` (card art and product name), `payoff` (auto loan payoff quotes), `sensitive` (full account numbers), `attribute` (credit health metrics), and `payment_instrument` (card tokenization).

Product availability depends on three factors:

1. **Account type**: `card_brand` only applies to credit cards, `payoff` only to auto loans (see [Liability Types](/guides/accounts/liability-types))
2. **Account status**: Disabled and Closed accounts lose most products
3. **Team configuration**: Some products require team-level enablement (check `restricted_products`)

Always check the `products` array before attempting an operation. Attempting an operation not in `products` will return an error. See the [Products reference](/reference/accounts/products/overview) for the full list.


# Accounts
Source: https://docs.methodfi.com/guides/accounts/overview

Liability and funding accounts — the financial objects at the heart of your product.

<Note>
  **Using Opal?** If you're using [Opal](/guides/opal), Method's embedded UI, liability account discovery is handled for you — users complete a soft credit pull and see their accounts inside Opal's Connect flow. You'll still work with the resulting `Account` objects in your backend for payments, monitoring, and ongoing display in your app. Funding accounts are always configured by your team via the API. The rest of this section is most relevant if you're building a custom integration or want to understand the underlying data model.
</Note>

## What a Method Account Represents

An Account in Method is a connected financial account that belongs to one of your users ([Entities](/guides/entities/overview)). Accounts are the objects your product primarily interacts with. You pull data from accounts, monitor accounts for changes, make payments to accounts, and build your user-facing displays around account information.

Every Account belongs to an [Entity](/guides/entities/overview), the person whose financial life you're working with. An Entity can have many Accounts (a typical consumer has 5–15 liability accounts). You'll interact with Accounts through the Entity that owns them: create an Entity, verify their identity, run [Connect](/guides/connect/overview) to discover their liabilities, then work with the resulting Account objects.

Every account in Method falls into one of two categories, and understanding this distinction is essential for designing your product's payment and data flows:

<Tabs>
  <Tab title="Liability Accounts">
    Represent debts and financial obligations. These are the credit cards, auto loans, other obligations that your users owe money on. Liability accounts are typically discovered automatically through [Connect](/guides/connect/overview) and serve as the destination for payments, this is where money goes when your user pays down debt.
  </Tab>

  <Tab title="Funding Accounts">
    Represent the bank account your platform pays from. This is typically your corporate checking or savings account linked via ACH that serves as the source of funds for all payments. Funding accounts are created by your team by providing routing and account number details, and must be verified before they can be used.
  </Tab>
</Tabs>

In payment flows, the model is simple: money flows from your platform's funding account (source) to a liability account (destination). Your corporate bank account funds the payment; the end user's creditor receives it.

## How Accounts Are Created

Liability accounts are typically discovered automatically through [Connect](/guides/connect/overview). When you run Connect for an Entity, Method pulls their credit report and creates `Account` objects for every discovered liability. You can also [create liability accounts manually via the API](/reference/accounts/create) if you have the account details.

Funding accounts are created by your team through the API by providing a routing number and account number. See [Funding Accounts](/guides/accounts/funding) for setup and verification details.

## Account Products: What You Can Do With an Account

Every Account carries two arrays that control what operations are available:

* `products`: Capabilities currently available (e.g., `balance`, `payment`, `update`, `card_brand`, `payoff`, `sensitive`, `payment_instrument`)
* `restricted_products`: Capabilities the account could support but require additional steps (like elevated verification or team-level enablement), or capabilities the account does not currently support

Always check `products` before attempting an operation. For example, not all liability types support `payment` — attempting to create a payment on an account without `payment` in its `products` list will fail. See the [Products reference](/reference/accounts/products/overview) for the full list.

***

For the full Accounts API, including all fields, endpoints, and expandable resources, see the [Accounts reference](/reference/accounts/overview).


# Card Brand
Source: https://docs.methodfi.com/guides/additional-products/card-brand

Card product names, visual card art, and card details for trust and engagement.

For credit card accounts, Method can retrieve the specific card product name, visual card art, and structured card details, including APRs, fees, rewards, and promotional offers. Instead of displaying a generic "Visa credit card" line item, your product can show "Chase Sapphire Reserve" with the actual card image and card details.

<Frame>
  <img alt="Card Brand enrichment" />
</Frame>

This seemingly small detail has an outsized impact on user trust and engagement. When users see their actual card names and artwork in your product, it signals accuracy and builds confidence that the data is real and current.

<Warning>
  Card Brand is available only to partners processing payments using the PaymentInstrument endpoint. Contact your Method CSM for more information.
</Warning>

## How It Works

Card Brand is available as a Product (on-demand) or Subscription (continuous updates). Create a Card Brand request for a credit card account, and Method returns a `brands` array containing:

* **name:** The card product name (e.g., "Chase Sapphire Reserve")
* **network:** The card network (e.g., `visa`, `mastercard`)
* **network\_tier:** The network tier (e.g., `infinite`, `signature`)
* **url:** A hosted URL for the card art image
* **type:** Brand match quality: `specific` (exact match with card art), `generic` (general metadata, no specific FI offering), or `in_review` (undergoing verification)
* **details:** Structured card details: `card_category`, purchase & cash-advance APRs, annual & late fees, `rewards` (type, program, and earn categories), and `promotions` (with the sign-up bonus). Available on version `2025-07-04` and later; see the [Card Brand reference](/reference/accounts/card-brands/overview).

The `source` field on the response indicates where the data came from (`method` or `network`).

## Quick Start

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/card_brands \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const cardBrand = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .cardBrands
    .create();
  ```

  ```python Python theme={null}
  card_brand = method
    .accounts('acc_yVf3mkzbhz9tj')
    .card_brands
    .create()
  ```
</CodeGroup>

## Supported Cards

Card Brand is available for credit card accounts on Visa and Mastercard networks. Requesting Card Brand for a non-credit-card account or an unsupported network returns a `PRODUCT_UNAVAILABLE` error.

## Error Handling

* `PRODUCT_UNAVAILABLE`: Account isn't a credit card, or the network isn't Visa/Mastercard.
* `TEAM_CAPABILITY_RESTRICTED`: Your team doesn't have access to Card Brand.
* `CARD_BRANDS_NOT_FOUND`: The card's brand could not be found or doesn't exist.

<Card title="Card Brand API Reference" icon="credit-card" href="/reference/accounts/card-brands/overview">
  Full API documentation for Card Brand.
</Card>


# Credit Scores
Source: https://docs.methodfi.com/guides/additional-products/credit-scores

Credit score retrieval and monitoring for financial wellness products.

For financial wellness products, few data points are as universally understood and valued as the credit score. Method can retrieve credit scores for verified Entities, giving your product the ability to show users their score, track changes over time, and alert them to increases or decreases.

## How It Works

Credit Scores are available as a Product (on-demand) or Subscription (continuous updates via webhooks). Requests are asynchronous: you'll get an immediate response with `status: "pending"` and `scores: null`, then a webhook when the score is ready.

The response includes a `scores` array. Each score object contains:

* **score:** The numeric credit score
* **source:** The credit bureau (`equifax`, `experian`, or `transunion`)
* **model:** The scoring model (`vantage_3` for VantageScore 3.0 or `vantage_4` for VantageScore 4.0)
* **factors:** An array of factor objects (each with `code` and `description`) explaining what's influencing the score, e.g., "Total of all balances on bankcard or revolving accounts is too high"

## Quick Start

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/credit_scores \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const creditScore = await method
    .entities('ent_au22b1fbFJbp8')
    .creditScores
    .create();
  ```

  ```python Python theme={null}
  credit_score = method
    .entities('ent_au22b1fbFJbp8')
    .credit_scores
    .create()
  ```
</CodeGroup>

## Subscriptions

Scores can be retrieved on-demand (pull the current score when the user opens your app) or monitored via subscriptions (get notified automatically when the score changes). Webhook events (`credit_score.create`, `credit_score.update`, `credit_score.available`) tell you when a score becomes available or changes, enabling features like "Your credit score went up 12 points this month!" notifications that drive engagement and retention.

## Prerequisites

The Entity must be fully verified before you can request credit scores. Attempting to request scores for an unverified Entity returns an `ENTITY_VERIFICATION_MISSING` error.

## Error Handling

Request errors:

* `ENTITY_VERIFICATION_MISSING`: Entity must be fully verified first.
* `TEAM_CAPABILITY_RESTRICTED`: Your team doesn't have access to Credit Scores.

Resource errors (set on the Credit Score's `error` property):

* `CREDIT_SCORE_FAILED_TEMPORARILY_UNAVAILABLE`: Issue with the credit score provider, request could not be completed.

<Card title="Credit Scores API Reference" icon="chart-line" href="/reference/entities/credit-scores/overview">
  Full API documentation for Credit Scores.
</Card>


# Sensitive
Source: https://docs.methodfi.com/guides/additional-products/sensitive

Gated access to full account numbers and sensitive account data.

Sensitive is a specially gated product that provides access to full account numbers and other sensitive account data. This is not enabled by default; access requires explicit approval from Method.

<Warning>
  Sensitive data requires explicit enablement for your team. Access may require additional review, agreements, and approval from Method. Not all accounts or account types support Sensitive data retrieval.
</Warning>

## How It Works

Unlike most Method products, Sensitive requests are *synchronous*. You'll get the data back immediately in the response.

When creating a Sensitive request, you must specify an `expand` array indicating which fields you want. Available fields depend on the account's liability type:

**Credit Cards:**

* `credit_card.number`: Full card number (PAN)
* `credit_card.exp_month`: Expiration month
* `credit_card.exp_year`: Expiration year
* `credit_card.cvv`: Card CVV
* `credit_card.billing_zip_code`: Billing zip code

**All other liability types** (auto loan, mortgage, personal loan, collection, student loans, credit builder, BNPL, fintech, loan):

* `{type}.number`: Full account number (e.g., `auto_loan.number`, `mortgage.number`)

## Supported Account Types

Sensitive supports: credit card, auto loan, mortgage, personal loan, collection, student loans, credit builder, BNPL, fintech, and loan accounts.

## Quick Start

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/sensitive \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "expand": [
        "credit_card.number",
        "credit_card.exp_month",
        "credit_card.exp_year",
        "credit_card.cvv"
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const sensitive = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .sensitive
    .create({
      expand: [
        'credit_card.number',
        'credit_card.exp_month',
        'credit_card.exp_year',
        'credit_card.cvv'
      ],
    });
  ```

  ```python Python theme={null}
  sensitive = method
    .accounts('acc_yVf3mkzbhz9tj')
    .sensitive
    .create({
      'expand': [
        'credit_card.number',
        'credit_card.exp_month',
        'credit_card.exp_year',
        'credit_card.cvv'
      ]
    })
  ```
</CodeGroup>

## Security Requirements

If your use case requires full account numbers (for example, to initiate payments through external systems or to populate forms on behalf of users), you'll need to request Sensitive access from Method. If approved, you're expected to follow strict security practices:

* Apply the principle of least privilege, only request sensitive data when needed
* Store secrets and sensitive data securely using encryption at rest and in transit
* Maintain audit logging on your side for all access to sensitive data
* PCI compliance is required

<Card title="Sensitive API Reference" icon="lock" href="/reference/accounts/sensitive/overview">
  Full API documentation for Sensitive.
</Card>


# Vehicles
Source: https://docs.methodfi.com/guides/additional-products/vehicles

Auto loan enrichment with VIN, make, model, and vehicle details.

For applications that deal with auto loans, whether that's auto refinancing, insurance, fleet management, or vehicle valuation, Method can enrich an Entity's profile with detailed vehicle information.

## How It Works

Vehicles is an Entity-level product: you request it against an Entity, not an individual Account. This means a single request returns all vehicles associated with that person. The response is synchronous, you'll get the data back immediately.

The `vehicles` array in the response contains one object per vehicle, each with:

* **vin:** Vehicle Identification Number
* **year:** Make year (e.g., "2021")
* **make:** Manufacturer (e.g., "honda")
* **model:** Model (e.g., "accord")
* **series:** Series/Trim/Category (e.g., "lx", "ex"), may be `null`
* **major\_color:** Primary color (e.g., "black")
* **style:** Body style (e.g., "sedan/saloon", "crew\_pickup", "sport\_utility\_vehicle")

This transforms an abstract "auto loan" line item into a concrete vehicle identity. Instead of showing "Auto Loan: \$18,450 balance," your product can display "2022 Honda Civic LX: \$18,450 remaining." This enrichment dramatically improves the user experience and enables vehicle-specific features like valuation estimates, equity calculations, and insurance comparisons.

## Quick Start

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/vehicles \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const vehicles = await method
    .entities('ent_au22b1fbFJbp8')
    .vehicles
    .create();
  ```

  ```python Python theme={null}
  vehicles = method
    .entities('ent_au22b1fbFJbp8')
    .vehicles
    .create()
  ```
</CodeGroup>

## Multiple Vehicles

An Entity can have multiple vehicles. The response `vehicles` array will contain all of them. This is useful for presenting a vehicle selector in your UI or for fleet management use cases.

<Card title="Vehicles API Reference" icon="car" href="/reference/entities/vehicles/overview">
  Full API documentation for Vehicles.
</Card>


# Core Concepts
Source: https://docs.methodfi.com/guides/concepts

The mental model for Method's platform — objects, relationships, and data flow.

This section provides a bird's-eye view of Method's core concepts and how they relate to each other. Think of it as the mental model you'll carry throughout the rest of this guide, every section that follows goes deeper on one of these concepts.

## The Core Platform Objects

<CardGroup>
  <Card title="Entity" icon="user" href="/guides/entities/overview">
    A user's identity in Method. An Entity represents one individual (or business) and serves as the root object for all accounts, verifications, and transactions. Each user in your application maps to exactly one Entity.
  </Card>

  <Card title="Identity Verification (IDV)" icon="shield-check" href="/guides/identity-verification/overview">
    Verifies that a user is who they claim to be before Method can access credit data or process payments. IDV includes phone verification and identity verification and acts as a one-time gate that unlocks downstream products.
  </Card>

  <Card title="Connect" icon="link" href="/guides/connect/overview">
    Discovers what a user owes. Using a verified Entity, Connect performs a soft credit pull to automatically identify liabilities across financial institutions, giving your application visibility into a user's full debt profile.
  </Card>

  <Card title="Accounts" icon="building-columns" href="/guides/accounts/overview">
    The financial objects your application interacts with. Accounts include discovered liabilities (credit cards, loans, etc.) and funding sources used for payments. They are the objects you monitor, update, and pay against.
  </Card>

  <Card title="Updates" icon="arrows-rotate" href="/guides/updates/overview">
    Provides fresh data about accounts. Updates deliver the latest balances, due dates, minimum payments, interest rates, and more through credit report snapshots or direct institutional connections.
  </Card>

  <Card title="Payments" icon="money-bill-transfer" href="/guides/payments/overview">
    Moves money to pay down liabilities. You initiate a payment from a verified funding source, and Method handles the full lifecycle: submission, processing, delivery to the creditor, and confirmation.
  </Card>
</CardGroup>

## The Dependency Chain

These concepts build on each other in a natural progression. Not every integration uses every product, a monitoring-only product might skip Payments entirely, while a paydown-focused product might use all of them. But the dependency chain means you always start with an Entity, verify their identity, and connect their accounts before you can take action.

### Typical End-to-End Flows

| Flow               | Path                                                         |
| ------------------ | ------------------------------------------------------------ |
| **Debt discovery** | Entity → IDV → Connect → Accounts → Updates                  |
| **Debt paydown**   | Entity → IDV → Connect → Accounts → Payments → Updates       |
| **Monitoring**     | Entity → IDV → Connect → Accounts → Subscriptions → Webhooks |

<Note>
  **Using Opal?** Opal handles Entity creation, identity verification, and account discovery in a single embedded flow. If you're using Opal, you don't build the first three steps yourself — Opal orchestrates them for you, and your integration picks up at the Accounts stage.
</Note>

## Additional Products

Beyond the six core concepts, Method offers specialized products that enrich the data and capabilities available on connected accounts.

### Commonly Used

<CardGroup>
  <Card title="Credit Score" icon="chart-line" href="/guides/additional-products/credit-scores">
    Credit score retrieval and monitoring, essential for financial wellness products that want to show users their score alongside their debt profile.
  </Card>

  <Card title="Attributes" icon="chart-pie" href="/guides/additional-products/attributes">
    Delivers structured credit health metrics (e.g., credit card usage, payment history), useful for building personalized insights, recommendations, or risk assessments.
  </Card>

  <Card title="Card Brand" icon="credit-card" href="/guides/additional-products/card-brand">
    Retrieves the specific card product name and card art (e.g., "Chase Sapphire Preferred" with the actual card image), great for building visually rich account displays.
  </Card>
</CardGroup>

### Specialized

<CardGroup>
  <Card title="Vehicles" icon="car" href="/guides/additional-products/vehicles">
    Enriches auto loan accounts with vehicle details (make, model, VIN), valuable for auto-focused lending or insurance products.
  </Card>

  <Card title="Sensitive" icon="lock" href="/guides/additional-products/sensitive">
    Provides gated access to full account numbers and other sensitive data, available by approval only, for use cases that require raw account credentials.
  </Card>

  <Card title="Payment Instruments" icon="wallet" href="/guides/payments/instruments">
    Creates reusable payment configurations (card credentials, ACH details, network tokens), enables repeated payment scenarios without re-collecting credentials each time.
  </Card>
</CardGroup>

Most integrations use a subset of these products. A basic debt discovery app needs only Entities, IDV, Connect, and Updates. A payment-focused product adds Payments and a Funding Account. Start with what your use case requires — you can enable additional products as your product evolves.

<CardGroup>
  <Card title="API Reference" icon="code" href="/reference/introduction">
    Full endpoint documentation for every object described above.
  </Card>
</CardGroup>


# Errors and Edge Cases
Source: https://docs.methodfi.com/guides/connect/errors

Common Connect errors and how to handle them.

## Common Connect Errors

### Request errors (returned immediately)

* **`ENTITY_VERIFICATION_MISSING`**: Entity must be fully verified before Connect. Complete both phone and identity verification first. See [Identity Verification](/guides/identity-verification/overview).
* **`TEAM_CAPABILITY_RESTRICTED`**: Your team doesn't have access to Connect. Contact your CSM.
* **`ACCOUNT_CONSENT_UNAVAILABLE`**: Account consent isn't available for your organization.

### Async errors (returned after processing)

* **`THIN_CREDIT_FILE`**: No tradelines found. The user has no credit history reportable to bureaus.
* **`CREDIT_FREEZE`**: The user has a credit freeze in place. The user must lift their freeze before discovery can complete.
* **`PRODUCT_EXECUTION_FAILED`**: A downstream product (balance, update, etc.) failed to execute on connected accounts. The Connect itself succeeded, but some product data may be missing.

<Warning>
  **Credit freeze messaging.** If a user hits `CREDIT_FREEZE`, surface a clear message explaining they need to lift their credit freeze.
</Warning>

For the full list of Connect error codes, see the [Connect Errors reference](/reference/errors/connect-errors).


# How Connect Works
Source: https://docs.methodfi.com/guides/connect/how-it-works

Soft-pull credit reports, auto vs manual discovery, and coverage.

## How Discovery Works

Connect uses the verified Entity's personally identifying information and the user's consent to perform a soft-pull credit report. A soft pull is fundamentally different from a hard credit inquiry — it has zero impact on the user's credit score and leaves no visible mark on their credit report. This is important messaging for your users, who may be hesitant about anything that touches their credit.

The credit report reveals the user's open liabilities across financial institutions. Method parses this data, matches it against its network of 15,000+ supported institutions, and creates account objects for each discovered liability. These accounts are immediately available in your application for data retrieval, monitoring, and (where supported) payment processing.

<Tip>
  **Processing time.** Connect typically completes within seconds for most users. Users with extensive credit histories (many open accounts) may take slightly longer.
</Tip>

<Tip>
  **Account matching.** Method matches each tradeline on the credit report against its network of 15,000+ financial institutions. When a match is found, Method creates an Account object with the appropriate `products` array based on what's supported for that merchant and liability type. Unmatched tradelines (institutions not in Method's network) are not returned.
</Tip>

## Complete Connect Flow

### Step 1: Create a Connect

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "products": ["balance", "update"],
    "subscriptions": ["update"]
  }'
```

### Step 2: Wait for completion

Connect processes asynchronously when products or subscriptions are specified, or when the `Prefer: respond-async` header is set. Listen for the `connect.update` webhook to know when discovery is complete:

```json theme={null}
{
  "id": "cxn_4ewMmBbjYDMR4",
  "type": "connect.update",
  "path": "/entities/ent_au22b1fbFJbp8/connect/cxn_4ewMmBbjYDMR4"
}
```

### Step 3: Retrieve results

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect/cxn_4ewMmBbjYDMR4 \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

<Tip>
  **Expand for efficiency.** Use the `expand` query parameter to include full Account objects, balances, card brands, or other data in the Connect response, avoiding additional API calls: `?expand=accounts,accounts.balance,accounts.card_brand`
</Tip>

## Synchronous vs Asynchronous Processing

A bare Connect request (no products, no subscriptions, no `Prefer: respond-async` header) processes synchronously — the response includes the completed results immediately.

When you include `products`, `subscriptions`, or the `Prefer: respond-async` header, Connect processes asynchronously. The response returns immediately with `status: pending` or `status: in_progress`, and you'll receive a `connect.update` webhook when processing completes.

<Note>
  **Recommendation:** Always set up webhooks for Connect. Even synchronous requests can take several seconds for users with many liabilities, and products/subscriptions always trigger async processing.
</Note>

## Requesting Products and Subscriptions at Connect Time

Connect can automatically execute products and set up subscriptions on all discovered accounts in a single call. This eliminates the need to iterate over accounts and make individual product requests after discovery.

**Available products:**

* `balance`: Retrieve balances for all discovered accounts
* `update`: Pull real-time data from source institutions
* `card_brand`: Retrieve card brand art and product names
* `attribute`: Pull structured credit health metrics
* `payoff`: Get payoff quotes (auto loans)

**Available subscriptions:**

* `update`: Subscribe to real-time data refreshes
* `update.snapshot`: Subscribe to periodic snapshot updates
* `card_brand`: Subscribe to card brand changes
* `transaction`: Subscribe to new transaction events

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "products": ["balance", "card_brand"],
    "subscriptions": ["update"]
  }'
```

<Note>
  Products and subscriptions are only executed on accounts where they're available. If an account doesn't support a product, requesting it won't cause an error — it simply won't apply to that account.
</Note>

## Connect Statuses

* `pending`: The Connect request is queued for processing
* `in_progress`: Discovery is actively running (soft pull being performed, accounts being matched)
* `completed`: Discovery finished successfully, accounts are available
* `failed`: Discovery failed (see error object for details)

Poll the Connect status or listen for `connect.update` webhooks to track progress.

## Connect vs. Manual Connect

Connect is the automatic discovery path — Method finds the accounts for you. But there are scenarios where you already have account data from another source (a prior data pull, user input, a partner integration) and want to register those accounts in Method without re-discovering them. That's what Manual Connect is for.

Manual Connect creates account objects from data you provide, bypassing the credit report discovery step. This is useful for: migrating existing users from a legacy system, supplementing discovered accounts with additional accounts the user provides manually, or connecting accounts that aren't reported to credit bureaus (and therefore wouldn't be discovered through Connect).

<Tabs>
  <Tab title="Connect (Auto Discovery)">
    Method performs a soft-pull credit report and automatically discovers the user's liabilities.

    **Use when:**

    * Onboarding new users
    * You want the broadest possible account discovery
    * Users don't know all their account details

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```
  </Tab>

  <Tab title="Manual Connect">
    You provide raw credit report tradeline data and Method creates account objects from it, bypassing the soft-pull step.

    **Use when:**

    * Migrating existing users from a legacy system where you already have their bureau data
    * Ingesting tradelines pulled directly from Equifax or TransUnion via your own bureau relationship
    * Backfilling historical tradeline data for an Entity

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/manual_connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "bureau": "transunion",
        "tradelines": [
          {
            "type_code": "18",
            "portfolio_type_code": "revolving",
            "designator_code": "individual",
            "number": "5555555555555555",
            "creditor_name": "CAPITAL ONE",
            "creditor_code": "01DTV001",
            "balance": 500000,
            "highest_balance": 750000,
            "credit_limit": 1000000,
            "term": null,
            "next_payment_minimum_amount": 15000,
            "last_payment_amount": 20000,
            "payment_history": ["1", "1", "1"],
            "past_due_amount": 0,
            "delinquency_charge_off_amount": 0,
            "opened_at": "2016-11-25",
            "last_activity_date": "2024-05-01",
            "reported_date": "2024-05-01",
            "next_payment_due_date": "2024-06-01",
            "last_payment_date": "2024-05-01",
            "delinquency_first_start_date": null,
            "narrative_codes": [
              { "code": "FE", "description": "CREDIT CARD" }
            ]
          }
        ]
      }'
    ```

    <Note>
      Manual Connect ingests **raw bureau tradelines** — it expects the full schema your bureau returns (creditor codes, payment history, delinquency dates, narrative codes, etc.). It is not a lightweight "user enters a missing account" flow. See the [Manual Connect reference](/reference/entities/manual-connect/create) for the full tradeline schema.
    </Note>
  </Tab>
</Tabs>

## Coverage — What Gets Discovered

Connect's coverage spans the broad spectrum of consumer liabilities, including:

<Accordion title="Supported liability types">
  * Credit cards from major issuers and regional banks
  * Auto loans from captive lenders and financial institutions
  * Federal and private student loans
  * Personal and installment loans
  * Mortgages and home equity lines of credit (HELOCs)
  * Collections accounts
  * Medical debt
  * Insurance payment obligations
  * Utility accounts
  * Buy Now Pay Later (BNPL) obligations
  * Credit builder accounts
  * Fintech-originated loans
</Accordion>

<Note>
  **Coverage notes:**

  * Credit cards, auto loans, and student loans have the broadest coverage across issuers
  * Collections accounts are reported inconsistently across bureaus — some may not appear
  * BNPL and utility accounts have growing but variable coverage
  * Closed accounts are included in the first Connect call but may have limited product availability
  * Coverage varies by specific institution, not just liability type. A major bank's credit cards will have broader product support than a small regional lender's
</Note>

## Expanding Connect Results

Use the `expand` query parameter to include full Account objects and their sub-resources directly in the Connect response, eliminating additional API calls:

```
POST /entities/{ent_id}/connect?expand=accounts,accounts.balance,accounts.card_brand
```

Available expansions: `accounts`, `accounts.balance`, `accounts.card_brand`, `accounts.attribute`, `accounts.update`, `accounts.payment_instrument`, `accounts.latest_verification_session`. If you expand a sub-field, the parent `accounts` expansion is applied automatically.


# Connect — Account Discovery
Source: https://docs.methodfi.com/guides/connect/overview

How Method discovers your users' complete liability picture.

<Frame>
  <img alt="Connect" />
</Frame>

<Note>
  **Using Opal?** If you're using Method's embedded UI, Opal handles account discovery as part of its managed flow — you don't need to call the Connect API directly. See the [Opal guide](/opal/overview) for details. The rest of this section is for custom API integrations.
</Note>

## What Connect Does

Connect discovers and links all of a user's financial liabilities in a single API call. Using the Entity's verified identity, Connect performs a soft-pull credit report and matches the results against Method's network of 15,000+ supported financial institutions. Each discovered liability becomes an Account object in your application, immediately available for data retrieval, monitoring, and payments where applicable.

## When to Use Connect

Connect is the standard path for any product that needs a comprehensive view of a user's debts: debt management, financial wellness, lending (pre-qualification, consolidation, portfolio monitoring), and bill pay. If your product involves consumer liabilities, Connect is almost certainly how you'll discover them.

## Prerequisites

Before calling Connect, the Entity must be fully verified (both phone and identity verification completed). Attempting Connect on an unverified Entity returns `ENTITY_VERIFICATION_MISSING`. See [Identity Verification](/guides/identity-verification/overview) for details.

## What Comes Back

A successful Connect returns a list of Account IDs representing the user's discovered liabilities. Each Account includes the merchant (who the debt is owed to), the liability type (credit card, auto loan, mortgage, etc.), and the `products` array indicating what Method can do with that account (balance retrieval, real-time updates, payments).

```json theme={null}
{
  "id": "cxn_4ewMmBbjYDMR4",
  "entity_id": "ent_qKNBB68bfHGNA",
  "status": "completed",
  "accounts": [
    "acc_eKKmrXDpJBKgw",
    "acc_GV8WbmJW7KGRy",
    "acc_MLPKh9gQDDbT8"
  ],
  "requested_products": [],
  "requested_subscriptions": [],
  "error": null,
  "created_at": "2024-04-12T14:56:46.645Z",
  "updated_at": "2024-04-12T14:56:46.645Z"
}
```

<Tip>
  **First Connect vs. subsequent calls.** The first Connect for an Entity returns all discovered liabilities (active and closed). Subsequent Connect calls for the same Entity only return *new* accounts that weren't in previous results. This is important for re-discovery flows — you won't get duplicates.
</Tip>

## Understanding Account Products

Each Account returned from Connect has a `products` array indicating what Method supports for that merchant:

* `balance`: retrieve the current balance
* `update`: pull real-time data (balances, rates, due dates) directly from the institution
* `payment`: send payments to this account through Method
* `sensitive`: access full account numbers (gated, requires approval)

Not every account supports every product. A credit card from a major issuer will likely have `balance`, `update`, and `payment`. A collections account may only have `balance`. Check `products` before building flows that assume full coverage.

## Next Steps

* [How Connect Works](/guides/connect/how-it-works): Soft pulls, auto vs manual discovery, coverage details
* [Handling Partial Results](/guides/connect/partial-results): Designing for incomplete discovery
* [Connect Subscriptions](/guides/connect/subscriptions): Monitoring for new liabilities over time
* [Connect API Reference](/reference/entities/connect/overview): Full endpoint documentation


# Handling Partial Results
Source: https://docs.methodfi.com/guides/connect/partial-results

Designing for incomplete discovery results.

# Handling Partial Results

<Note>
  Connect may not discover every liability a user has. Design your product to treat partial results as the normal case.
</Note>

## Why Results May Be Incomplete

**Not all liabilities appear on credit reports.** Some debts (private loans between individuals, certain employer-provided benefits, some BNPL arrangements) are never reported to credit bureaus and won't be found by Connect.

**Reporting delays.** New accounts may not appear on a credit report for 30–60 days after opening. A user who just opened a credit card last week won't see it in Connect results yet.

**Unmatched institutions.** Method's network covers 15,000+ institutions, but some smaller or newer creditors may not yet be supported. The tradeline exists on the credit report, but Method can't create an actionable Account from it because the institution isn't in Method's network.

**Closed accounts.** The first Connect returns both open and closed accounts. Closed accounts may have limited product availability (e.g., no payments, no updates).

## Recommended Patterns

### Show what was found, supplement where possible

After Connect completes, display the discovered accounts. If you have access to additional bureau data the user, you can supplement the discovered set by ingesting raw credit report tradelines via [Manual Connect](/reference/entities/manual-connect/create):

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/manual_connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "bureau": "transunion",
    "tradelines": [
      {
        "type_code": "18",
        "portfolio_type_code": "revolving",
        "designator_code": "individual",
        "number": "5555555555555555",
        "creditor_name": "CAPITAL ONE",
        "creditor_code": "01DTV001",
        "balance": 500000,
        "highest_balance": 750000,
        "credit_limit": 1000000,
        "term": null,
        "next_payment_minimum_amount": 15000,
        "last_payment_amount": 20000,
        "payment_history": ["1", "1", "1"],
        "past_due_amount": 0,
        "delinquency_charge_off_amount": 0,
        "opened_at": "2016-11-25",
        "last_activity_date": "2024-05-01",
        "reported_date": "2024-05-01",
        "next_payment_due_date": "2024-06-01",
        "last_payment_date": "2024-05-01",
        "delinquency_first_start_date": null,
        "narrative_codes": [
          { "code": "FE", "description": "CREDIT CARD" }
        ]
      }
    ]
  }'
```

<Note>
  Manual Connect requires the full bureau tradeline schema (creditor codes, payment history, delinquency dates, narrative codes, etc.) — it is not a lightweight "user enters a missing account" flow. If you need that pattern, talk to your CSM about the right approach for your use case.
</Note>

### Enable Connect subscriptions for ongoing discovery

New liabilities that appear on future credit reports will be automatically discovered. See [Connect Subscriptions](/guides/connect/subscriptions).

### Handle zero results gracefully

If Connect returns zero accounts (thin credit file), don't show an empty state. Explain that the credit report didn't contain tradelines and offer Manual Connect as the path forward.

### Account-level product gaps

Even when an account is discovered, it may not support all products. Always check the `products` array before making assumptions:

```javascript theme={null}
const account = await method.accounts.retrieve('acc_eKKmrXDpJBKgw');

if (account.products.includes('payment')) {
  // Safe to initiate payments
} else {
  // Data-only — can retrieve balances but can't send money
}
```

For the full Connect API, see the [Connect reference](/reference/entities/connect/overview).


# Raw Credit Reports
Source: https://docs.methodfi.com/guides/connect/raw-credit-reports

Receive the raw bureau credit report behind a Connect as downloadable files.

Connect discovers liabilities using the user's credit report. Teams with raw credit report access enabled can also receive that underlying bureau report itself, as a downloadable raw credit report JSON and/or credit report PDF returned as [Files](/reference/files/overview). Files give you a durable copy of the report (e.g. for compliance archives or underwriting reviews) that can be re-downloaded at any time.

## Prerequisites

* Raw credit report features are enabled on a case-by-case basis. Contact Method to enable these.
* The Entity must be verified and must not have [withdrawn consent](/reference/entities/consent/withdraw).

## Requesting the raw report

<Steps>
  <Step title="Create a Connect with artifacts">
    Pass `bureau` and `artifacts` when [creating a Connect](/reference/entities/connect/create):

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "bureau": "transunion",
        "artifacts": ["raw_credit_report", "credit_report_pdf"]
      }'
    ```

    | Field       | Type    | Notes                                                                                                                              |
    | ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
    | `bureau`    | enum    | `transunion` or `equifax`. Required whenever `artifacts` is set. Method will work with your team to set which bureaus are allowed. |
    | `artifacts` | enum\[] | Any of `raw_credit_report`, `credit_report_pdf`. Each becomes a downloadable File on the Connect.                                  |

    <Note>
      Each Connect pulls from a single bureau. To receive credit reports from both bureaus, you will need to make 2 separate Connect calls.
    </Note>
  </Step>

  <Step title="Read the response">
    The Connect response includes the requested artifacts in `files`:

    ```json theme={null}
    {
      "id": "cxn_4ewMmBbjYDMR4",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "completed",
      "accounts": ["acc_eKKmrXDpJBKgw", "acc_GV8WbmJW7KGRy"],
      "requested_products": [],
      "requested_subscriptions": [],
      "files": [
        {
          "id": "file_jZWkPMhXPeYAn",
          "type": "raw_credit_report",
          "bureau": "transunion",
          "mime_type": "application/json"
        },
        {
          "id": "file_qTnUv7DdKcRW2",
          "type": "credit_report_pdf",
          "bureau": "transunion",
          "mime_type": "application/pdf"
        }
      ],
      "error": null,
      "created_at": "2026-07-06T18:00:00.000Z",
      "updated_at": "2026-07-06T18:00:12.000Z"
    }
    ```
  </Step>

  <Step title="Download the file artifacts">
    Note the `file_id`s in the above response and use [Retrieve a File](/reference/files/retrieve) to get the File's metadata, including a temporary `download_url` to its contents:

    ```bash theme={null}
    curl https://production.methodfi.com/files/file_jZWkPMhXPeYAn \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    Fetch the `download_url`. A new URL is generated on every retrieve and expires at `download_expires_at`.

    Additionally, you can stream a File's contents directly with [Download a File](/reference/files/download):

    ```bash theme={null}
    curl https://production.methodfi.com/files/file_jZWkPMhXPeYAn/download \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -o raw_credit_report.json
    ```
  </Step>
</Steps>

## Retrieving the raw report later

Files persist after the Connect completes. [Retrieve the Connect](/reference/entities/connect/retrieve) at any time to read its `files` array, then download the contents via the [Files API](/reference/files/overview).

## Webhooks

Connects with products or subscriptions (or the `Prefer: respond-async` header) process asynchronously. Listen for `connect.available` to know when an async Connect (including its artifacts) is ready, and `connect.create` for synchronous completions. See [Connect webhooks](/guides/connect/subscriptions).

## Errors

| `sub_type`                              | Cause                                                         |
| --------------------------------------- | ------------------------------------------------------------- |
| `CONNECT_BUREAU_REQUIRED_FOR_ARTIFACTS` | `artifacts` sent without `bureau`                             |
| `CONNECT_BUREAU_NOT_CONFIGURED`         | No bureaus have been configured for your team                 |
| `CONNECT_BUREAU_NOT_ENABLED`            | The requested bureau is not in your team's allowed bureaus    |
| `CONNECT_RAW_REPORT_NOT_ENABLED`        | The `raw_credit_report` artifact is not enabled for your team |
| `CONNECT_CREDIT_REPORT_PDF_NOT_ENABLED` | The `credit_report_pdf` artifact is not enabled for your team |

See [Connect errors](/reference/errors/connect-errors) and [File errors](/reference/errors/file-errors) for the full list.

<Note>
  **Handling sensitive data.** The raw credit report contains the consumer's full bureau file. Treat it as highly sensitive: store it encrypted, restrict access, and only retain it as long as your compliance obligations require.
</Note>

For the full API surface, see the [Connect reference](/reference/entities/connect/overview) and the [Files reference](/reference/files/overview).


# Connect Subscriptions
Source: https://docs.methodfi.com/guides/connect/subscriptions

Monitoring for new liabilities over time.

## Connect Subscriptions — Monitoring for New Liabilities

A user's liability profile isn't static. They open new credit cards, take out new loans, and accumulate new obligations over time. Connect Subscriptions monitor for these changes by periodically checking the Entity's credit report for new liabilities.

When a new account is discovered, Method creates it and notifies you via webhook. This enables your product to surface new debts automatically, keep the user's liability picture complete without requiring them to re-run discovery, and trigger workflows when new accounts appear (e.g., automatically requesting updates for newly discovered accounts).

The typical pattern is to enable a Connect subscription after the initial Connect completes, creating a continuous discovery pipeline that keeps your application's view of the user's liabilities current over time.

## Creating a Connect Subscription

Use the [Entity Subscriptions endpoint](/reference/entities/subscriptions/create) to enroll an Entity in ongoing Connect monitoring:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{ "enroll": "connect" }'
```

<Note>
  The Connect endpoint's `subscriptions` body parameter is for *account-level* subscriptions (`update`, `card_brand`, etc.) that apply to discovered accounts. To subscribe to ongoing *discovery* of new liabilities, use the Entity Subscriptions endpoint with `"enroll": "connect"` as shown above.
</Note>

<Tip>
  **Subscription frequency.** Connect subscriptions periodically perform soft-pull credit checks to detect new tradelines.
</Tip>

## Webhooks

Connect fires the following webhook events:

* `connect.create`: Connect request was created
* `connect.update`: Connect status changed (use this to detect completion)
* `connect.available`: New accounts are available (fired by Connect subscriptions when new liabilities are detected)

```json theme={null}
{
  "id": "cxn_4ewMmBbjYDMR4",
  "type": "connect.update",
  "path": "/entities/ent_au22b1fbFJbp8/connect/cxn_4ewMmBbjYDMR4"
}
```

Set up webhooks via the [Webhooks API](/reference/webhooks/overview) to receive real-time notifications.

## Receiving New Account Notifications

When a Connect subscription discovers new liabilities, Method fires a `connect.available` webhook:

```json theme={null}
{
  "id": "cxn_new123",
  "type": "connect.available",
  "path": "/entities/ent_au22b1fbFJbp8/connect/cxn_new123"
}
```

Retrieve the Connect object to see the newly discovered Account IDs. Only new accounts are included — previously discovered accounts are not repeated.

## Managing Subscriptions

To unsubscribe from Connect monitoring:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/subscriptions/sub_abc123 \
  -X DELETE \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

See [Entity Subscriptions](/reference/entities/subscriptions/overview) for the full subscription management API.

## When to Use Connect Subscriptions

<Tip>
  **When to use Connect subscriptions:**

  * Debt management / financial wellness apps where the user's liability picture must stay current
  * Portfolio monitoring where new liabilities impact risk assessment
  * Lending products that need to detect new debts after origination

  **When you may not need them:**

  * One-time Connect for a loan application (discovery is a point-in-time event)
</Tip>


# Testing Connect
Source: https://docs.methodfi.com/guides/connect/testing

How to test Connect in development.

## Testing Connect in Development

Use the simulation endpoint to queue Connect behaviors in your development environment:

```bash theme={null}
curl https://dev.methodfi.com/simulate/entities/{entity_id}/connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "behaviors": ["new_credit_card_account", "new_auto_loan_account"] }'
```

Each behavior is consumed the next time Connect runs for that Entity. Maximum 5 behaviors per Entity.

**Available behaviors:** `new_credit_card_account`, `new_auto_loan_account`, `new_mortgage_account`, `new_student_loan_account`, `new_personal_loan_account`.

<Note>
  **Simulation limitations.** Simulated accounts won't have real institution data. Use them to test your integration flow (webhooks, UI rendering, product execution), not data accuracy.
</Note>

For the full simulation API, see the [Simulate Connect reference](/reference/simulations/connect/create).


# Entity Errors — What Can Go Wrong and How to Handle It
Source: https://docs.methodfi.com/guides/entities/errors

What can go wrong during Entity creation and how to handle it.

## Entity Errors and Edge Cases

The most common issues during Entity creation stem from missing or incorrectly formatted user information. Understanding these helps you design an onboarding flow that minimizes friction and handles errors gracefully.

* **Missing required fields**: Entity creation requires certain identifying information (at minimum, a name and phone number for individuals). If required fields are omitted, the creation will fail. In your user experience, this typically means your onboarding form should collect all necessary fields upfront and validate completeness before submission. If you're collecting information across multiple screens, ensure the full set is available when you create the Entity.
* **Invalid formats**: PII fields must meet specific format requirements, phone numbers must be valid US numbers, dates of birth must be real dates, and so on. Customer-side validation catches most of these issues before they reach Method's API. Design your input fields with appropriate format masks, validation rules, and helpful error messages so users can correct issues immediately rather than encountering failures downstream.

### Immutable PII Fields

Once a PII field has been set to a non-null value on an Entity (name, phone, DOB, SSN), it **cannot be changed**. If a user enters incorrect information and it gets submitted to Method, you cannot correct it via the API.

**How to handle it:**

* For fields that are still `null`, you can update them at any time via the [Update endpoint](/reference/entities/update-entity)
* For genuine corrections (e.g., legal name change), contact Method support
* You may need to create a new Entity for that user

### Operations on Disabled Entities

If an Entity transitions to `disabled` (via consent withdrawal or a compliance event), any attempt to initiate new operations — connecting accounts, creating payments, requesting products — will fail. Existing data remains readable.

**How to handle it:** Check the Entity's `status` before initiating operations. If `disabled`, display a clear message and prevent actions that would fail. See [Entity Lifecycle](/guides/entities/lifecycle) for more on state transitions.

### Phone Number Formatting

Phone numbers must be in **E.164 format** (e.g., `+15121234567`). Common issues:

* Missing country code (`5121234567` instead of `+15121234567`)
* Including formatting characters (`(512) 123-4567` instead of `+15121234567`)
* Non-US numbers (Method currently supports US numbers only)

Validate and normalize phone numbers on your end before submitting to Method.

### Common Error Responses

When Entity creation or updates fail, Method returns structured error responses. Here are the most common:

**Missing required field:**

```json theme={null}
{
  "error": {
    "type": "INVALID_REQUEST",
    "sub_type": "INVALID_REQUEST",
    "message": "Field \"individual\" is required. Verify your request and try again."
  }
}
```

**Invalid phone format:**

```json theme={null}
{
  "error": {
    "type": "INVALID_REQUEST",
    "sub_type": "INVALID_REQUEST",
    "message": "Field \"individual.phone\" is in an invalid format. Verify your request and try again."
  }
}
```

**Attempting to update an immutable field:**

```json theme={null}
{
  "error": {
    "type": "INVALID_REQUEST",
    "sub_type": "ENTITY_UPDATE_INVALID",
    "message": "Updates are only allowed on fields that have not been set. Verify your request and try again."
  }
}
```

For the complete list of Entity error codes, see [Entity Errors](/reference/errors/entity-errors) in the API Reference.

### When Issues Persist

If Entity creation consistently fails, first check the `error` field on the API response — it contains structured details about what went wrong. Most issues can be resolved by fixing input data and retrying.

If the error is unclear or you believe it's incorrect, contact Method support with:

* The Entity ID (`ent_...`) if one was created
* The full error response
* The request payload that triggered the error

<Note>
  Entity errors should be handled as a normal part of your onboarding flow,
  not as exceptional failures. Validate input early, provide clear error
  messaging, and allow users to correct and retry without starting over.
  For engineering teams: see the full error codes and response formats in the
  <a href="/reference/errors/entity-errors">Entity Errors reference</a>.
</Note>

<CardGroup>
  <Card title="Identity Verification Guide" icon="shield-check" href="/guides/identity-verification/overview">
    Next: verify your user's identity to unlock products.
  </Card>

  <Card title="Entity Errors Reference" icon="code" href="/reference/errors/entity-errors">
    Full list of error codes, types, and sub-types.
  </Card>
</CardGroup>


# Entity Lifecycle — From Creation to Active Use
Source: https://docs.methodfi.com/guides/entities/lifecycle

From creation to active use — understanding Entity states and transitions.

## Entity Lifecycle — From Creation to Active Use

### Lifecycle States

Every Entity in Method exists in one of three states, and understanding these states helps you design the right user experience at each stage of your onboarding flow:

* **Incomplete:** The Entity has been created in Method, but the user hasn't completed all required steps to unlock the platform's capabilities. This is the starting state for every new Entity. In practical terms, your application knows who this person is, but Method hasn't yet verified their identity or connected their accounts. Most products are unavailable in this state. Your application should guide the user through the remaining setup steps (typically identity verification) and clearly indicate that setup isn't finished.
* **Active:** The Entity is fully set up and ready for use. Identity verification is complete, and the full range of eligible products is available. This is the steady state for most of your users. Your application can connect accounts, request updates, initiate payments, and enable monitoring. The user should experience the full value of your product.
* **Disabled:** The Entity has been deactivated and can no longer be used for new operations. This may happen because your team withdrew consent via the [Consent endpoint](/reference/entities/consent/withdraw), because Method disabled the Entity for compliance reasons, or because the user requested account closure through your application.
  No new operations can be initiated, but existing data, accounts, payment history, updates — remains accessible for reference and reporting.

### Common Lifecycle Transitions

**incomplete → active**
Triggered when the Entity completes all verification requirements configured for your team. For most teams, this means both phone and identity verification. The transition happens automatically — once the final verification session succeeds, the Entity's status updates and products become available.

**active → disabled**
Can be triggered by:

* Your team withdrawing consent via the [Consent endpoint](/reference/entities/consent/withdraw)
* A compliance event (e.g., a payment reversal triggers a policy review)
* Method disabling the Entity for policy reasons

This transition is permanent — disabled Entities cannot be reactivated. To re-onboard the user, create a new Entity.

**What about abandoned onboarding?**
Entities that stay in `incomplete` (the user never finished verification) don't expire. Build a resume flow that picks up where the user left off rather than creating a new Entity on their next visit.

Entities must be `active` before they can be `disabled`. An `incomplete` Entity that's no longer needed can simply be left in place — it doesn't incur cost or require cleanup.

### Reacting to State Changes

Entity state changes trigger `entity.update` webhooks. Subscribe to these to react in real time — for example, unlocking features when an Entity transitions to `active`, or displaying a deactivation notice when it becomes `disabled`. See [Webhooks](/reference/webhooks/overview).

### Designing Around Lifecycle States

Your user experiences should reflect the Entity's state:

* For incomplete Entities, show a clear onboarding progress indicator. Let the user know what steps remain (e.g., "Verify your identity to see your accounts"). Avoid showing empty states that suggest the product is broken — the user is mid-setup, not experiencing an error.
* For active Entities, provide full access to your product's features. This is your core experience.
* For disabled Entities, display a clear, non-alarming message explaining that the account is no longer active. Allow the user to view historical data if appropriate, but prevent any actions that would fail (payment initiation, account connection, etc.)

<CardGroup>
  <Card title="Errors & Edge Cases" icon="triangle-exclamation" href="/guides/entities/errors">
    What can go wrong during Entity creation and how to handle it.
  </Card>

  <Card title="Entity API Reference" icon="code" href="/reference/entities/overview">
    See the full Entity object including status, verification, products, and subscriptions.
  </Card>
</CardGroup>


# Entities — The Foundation of Every Integration
Source: https://docs.methodfi.com/guides/entities/overview

What an Entity represents, why it matters, and how it maps to your users.

## Entities — The Foundation of Every Integration

### The Entity Model

An Entity is Method's representation of a person or business in your system — a persistent profile that anchors everything Method knows about your user. Their verified identity, discovered accounts, payment history, and active subscriptions all connect through a single Entity. Every operation your application performs through Method — identity verification, account discovery, payments, monitoring — flows through the user's Entity.

### Why the Entity Model Matters

* **Persistent verification:** Once verified, the Entity carries that status forward. You don't re-verify for every operation.
* **Single reference point:** All accounts, payments, and updates for a user are scoped to their Entity. This also enforces authorization boundaries — one Entity's operations can't affect another.
* **Lifecycle management:** The Entity's status tracks the user's journey from onboarding through active use to potential deactivation, enforcing appropriate constraints at each stage.

### Entity vs End User

Your application has users; Method has Entities. These map one-to-one. Each end user in your application corresponds to exactly one Entity in Method, and that relationship persists throughout the user's lifecycle. You'll typically store the Method Entity ID alongside your internal user ID so you can bridge between the two systems seamlessly.

<Warning>
  Method does not automatically deduplicate Entities. If your application
  creates two Entities for the same person, both will exist independently
  with separate accounts and data. Your application should enforce uniqueness
  (typically by phone number) before creating new Entities.
</Warning>

### Individual vs Corporation Entities

Method supports two types of Entities, corresponding to the two types of financial actors:

<Tabs>
  <Tab title="Individual">
    Individual Entities represent people. To create one, you provide identifying information,  typically at minimum a name and phone number, with additional fields (date of birth, address, SSN) required for identity verification and access to downstream products. Individual Entities are by far the most common type and support the full range of Method's products.

    ```bash theme={null}
    curl https://production.methodfi.com/entities \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "individual",
        "individual": {
          "first_name": "John",
          "last_name": "Doe",
          "phone": "+15121234567"
        }
      }'
    ```
  </Tab>

  <Tab title="Corporation">
    Corporation Entity represents any business, regardless of its legal structure. Corporation Entities go through a business-specific verification process (KYB) and have their own product eligibility path.

    Corporation Entities support a different subset of capabilities than Individuals. They are primarily used for payment origination scenarios and do not have the same product catalog (no credit scores, Connect, or individual-specific features). If your use case involves both consumers and businesses, your architecture will need to account for this difference.

    ```bash theme={null}
    curl https://production.methodfi.com/entities \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "corporation",
        "corporation": {
          "name": "Acme Inc.",
          "ein": "123456789"
        }
      }'
    ```
  </Tab>
</Tabs>

### What Information Do You Need to Collect?

At minimum, most teams need a user's **name and phone number** to create an Individual Entity. However, additional PII (date of birth, SSN or last 4 of SSN, email, address) is typically required to complete identity verification and unlock products like Connect and Credit Score.

Your specific PII requirements are configured during onboarding. A common pattern is to create the Entity early with minimal information, then progressively update it as you collect more data during your onboarding flow. Contact your Method CSM if you're unsure about your team's requirements.

<CardGroup>
  <Card title="Entity Lifecycle" icon="arrows-spin" href="/guides/entities/lifecycle">
    Understand Entity states and how users transition from onboarding to active use.
  </Card>

  <Card title="Errors & Edge Cases" icon="triangle-exclamation" href="/guides/entities/errors">
    What can go wrong during Entity creation and how to design around it.
  </Card>

  <Card title="Identity Verification" icon="shield-check" href="/guides/identity-verification/overview">
    The next step after Entity creation — verifying your user's identity.
  </Card>

  <Card title="Entity API Reference" icon="code" href="/reference/entities/overview">
    Full Entity object schema, CRUD endpoints, and field details.
  </Card>
</CardGroup>


# IDV Errors & Edge Cases
Source: https://docs.methodfi.com/guides/identity-verification/errors

Common verification errors, failure modes, and how to handle edge cases.

## IDV Errors & Edge Cases

### Phone Verification Failures

| Error                                                    | Cause                                                             | Resolution                                                                                                                           |
| -------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `VERIFICATION_SESSION_EXPIRED` (19001)                   | Session not completed within the 10-minute window                 | Create a new verification session. Consider adding a timer or progress indicator to your UX.                                         |
| `VERIFICATION_SESSION_FAILED_INCORRECT_SMS_CODE` (19002) | User entered the wrong SMS code                                   | Create a new verification session. Confirm the user is entering the code from the most recent SMS.                                   |
| `VERIFICATION_SESSION_FAILED_SNA` (19003)                | User not on a mobile device, or on an unsupported carrier/network | Fall back to SMS verification. SNA access attempts are limited to 5 per session.                                                     |
| `ENTITY_PHONE_VERIFICATION_MAX_ATTEMPTS`                 | Too many verification attempts for this Entity's phone number     | The underlying SMS provider has rate-limited this phone number. Wait before retrying, and surface appropriate messaging to the user. |

### Identity Verification Failures

| Error                                                | Cause                                                                                           | Resolution                                                                                                                                                                               |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MISSING_IDENTITY_MATCH`                             | Method couldn't correlate the Entity's PII to a known identity — insufficient or incorrect PII  | [Update the Entity](/reference/entities/update-entity) with additional fields (DOB, SSN, address) and retry. See [Maximizing Success](/guides/identity-verification/maximizing-success). |
| `VERIFICATION_SESSION_FAILED_INVALID_ANSWER` (19004) | User answered one or more KBA questions incorrectly, or a question was missing from the request | Create a new verification session — a fresh set of questions will be generated. Confirm the user is answering carefully.                                                                 |
| `VERIFICATION_SESSION_EXPIRED` (19001)               | Session not completed within the 10-minute window                                               | Create a new verification session.                                                                                                                                                       |

### Request Errors

| Error                              | Cause                                                                                        | Resolution                                                                        |
| ---------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `MISSING_PHONE_VERIFICATION`       | Attempted to create an identity verification session before phone verification was completed | Complete phone verification first, then create the identity verification session. |
| `EXISTING_VERIFIED_SESSION`        | The Entity has already completed verification for that type (phone or identity)              | No action needed — the Entity is already verified for that step.                  |
| `INVALID_ENTITY_TYPE`              | Attempted to create a verification session on a corporation Entity                           | Verification sessions are only available for Entities of type `individual`.       |
| `UNAUTHORIZED_VERIFICATION_METHOD` | The team is not authorized to use the requested verification method                          | Contact your Method CSM to enable the method (e.g., `byo_sms`, `byo_kyc`).        |

### Edge Cases

<Accordion title="User needs a different phone number mid-flow">
  An Entity's phone number cannot be changed once it has been set. If the user entered the wrong phone number, you'll need to create a new Entity with the correct phone number and start the verification process from the beginning.
</Accordion>

<Accordion title="Same phone number across multiple Entities">
  Multiple Entities can share the same phone number, but each Entity must complete its own verification independently.
</Accordion>

<Accordion title="Re-verification after Entity was previously verified">
  Attempting to create a verification session for an already-verified type will return `EXISTING_VERIFIED_SESSION`. Verification is persistent and does not need to be repeated.
</Accordion>

<Accordion title="Attempting verification on a disabled Entity">
  Verification sessions cannot be created for Entities that have been disabled. Ensure the Entity is in an active state before initiating verification.
</Accordion>

<Accordion title="Corporation Entity">
  Verification sessions are only available for individual Entities. Attempting to create a session on a corporation Entity will return `INVALID_ENTITY_TYPE`.
</Accordion>

### Error Code Reference

For the full list of error codes with response bodies, see the [Entity Verification Session Errors](/reference/errors/entity-verification-session-errors) reference.


# Maximizing Verification Success
Source: https://docs.methodfi.com/guides/identity-verification/maximizing-success

How to improve match rates and verification success through better data collection.

## Maximizing Verification Success

Not all PII fields are required for every verification method, but providing more data significantly improves match rates and verification success. At minimum, you need a name and phone number, but including date of birth, address, and SSN (last 4 or full) dramatically increases the likelihood of a successful match. Design your onboarding flow to collect as much PII as practical without creating excessive friction.

| Field                | Impact   | Why it matters                                            |
| -------------------- | -------- | --------------------------------------------------------- |
| First + Last name    | Required | Baseline identity anchor                                  |
| Phone number         | Required | Links to carrier records and Method's network             |
| Date of birth        | High     | Disambiguates common names, strong identity signal        |
| Address              | High     | Confirms geographic identity, helps with thin files       |
| Email                | Moderate | Secondary signal, helps when primary fields are ambiguous |
| SSN (last 4 or full) | Highest  | Strongest single identity signal, near-guaranteed match   |

### Common Pitfalls

* **Phone number without country code** — Method only accepts US phone numbers at this time, and they must include the `+1` country code (e.g., `+15551234567`)
* **Abbreviated names vs. legal names** — use the name on their credit file, not nicknames (e.g., "William" not "Bill")
* **PO Box instead of physical address** — physical addresses match better against identity records
* **Stale or outdated address** — use the user's current address, not a previous one

<Note>
  For platform availability details, see the [IDV Overview](/guides/identity-verification/overview).
</Note>

<CardGroup>
  <Card title="Verification Outcomes" icon="circle-check" href="/guides/identity-verification/outcomes">
    When data collection is maximized but matching still fails.
  </Card>

  <Card title="Verification Sessions API" icon="code" href="/reference/entities/verification-sessions/overview">
    Full API reference for verification session endpoints.
  </Card>
</CardGroup>


# Verification Methods
Source: https://docs.methodfi.com/guides/identity-verification/methods

Choosing the right phone and identity verification approach for your integration.

## Verification Methods

<Warning>
  All verification sessions expire **10 minutes** after creation. If the user doesn't complete verification within that window, you'll need to create a new session. Design your UX to guide users through verification promptly and handle the expired session error gracefully. See [Errors & Edge Cases](/guides/identity-verification/errors) for details.
</Warning>

Phone verification must be completed before identity verification can begin. Choose one method from each step below. Most teams use the same approach (Opal, API-driven, or BYO) for both steps, but you can mix — for example, SNA for phone and KBA for identity.

### Choosing Your Phone Verification Method

<Tabs>
  <Tab title="Opal (Recommended)">
    Phone verification is handled entirely within the Opal embedded UI. The user enters their phone number, receives a verification code, and enters it — all within a polished, pre-built interface. This is the fastest path to implementation and provides the most consistent user experience.
  </Tab>

  <Tab title="SMS Verification">
    Method sends a verification code to the user's phone, and your application collects and submits the code. Choose this if you want to integrate phone verification into your own custom UI while still having Method handle the SMS delivery.

    ```bash theme={null}
    # 1. Create SMS verification session
    curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "sms",
        "sms": {}
      }'

    # 2. Submit the code the user received
    curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "sms",
        "sms": {
          "sms_code": "123456"
        }
      }'
    ```
  </Tab>

  <Tab title="Silent Network Auth (SNA)">
    The phone is verified in the background using carrier-level network signals, with no user interaction required. This provides the best user experience (the user doesn't have to do anything), but availability depends on the user's carrier and network conditions. Consider SNA as a primary method with SMS as a fallback.

    <Warning>
      SNA requires the user to be on a mobile device connected to a supported carrier's network. It does not work on landlines, VoIP numbers, or most prepaid/MVNO carriers. The returned URLs must be opened via background request or the device's mobile browser. Always implement SMS as a fallback — SNA failures may be silent and your application needs to detect them (via session status polling or webhook) and offer an alternative. SNA access attempts are limited to 5 per session before the session fails.
    </Warning>
  </Tab>

  <Tab title="BYO SMS">
    You handle SMS delivery and verification entirely on your side and report the result to Method. Choose this if you already have a robust SMS verification system and want to maintain a single verification flow across your application.

    <Note>
      BYO SMS requires your team to be pre-authorized during onboarding. You'll create a verification session with method `byo_sms` and provide the `byo_sms.timestamp` field — the ISO 8601 timestamp of when you verified the phone number. Contact your Method CSM to enable this method.
    </Note>

    ```bash theme={null}
    curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "byo_sms",
        "byo_sms": {
          "timestamp": "2026-04-10T12:00:00.000Z"
        }
      }'
    ```
  </Tab>
</Tabs>

#### Choosing a Phone Method

| Method      | User Experience            | Implementation                | Reliability                  | Best For                                 |
| ----------- | -------------------------- | ----------------------------- | ---------------------------- | ---------------------------------------- |
| **Opal**    | Polished, pre-built        | Minimal (embed SDK)           | High                         | Most teams                               |
| **SMS**     | Standard (enter code)      | Medium (collect + submit)     | High                         | Custom UI with Method SMS delivery       |
| **SNA**     | Invisible (no user action) | Medium (background URL calls) | Variable (carrier-dependent) | Mobile-first products, with SMS fallback |
| **BYO SMS** | Your existing flow         | Low (report result)           | Depends on your provider     | Teams with existing SMS verification     |

**Recommended pattern:** Use SNA as primary with SMS as automatic fallback. This gives the best conversion rate while ensuring every user can complete verification.

<Note>
  Phone verification has a maximum attempt limit enforced by the underlying SMS provider. If the limit is reached, the error `ENTITY_PHONE_VERIFICATION_MAX_ATTEMPTS` is returned and you'll need to wait before retrying. Design your flow to inform users of the limit and avoid excessive retries.
</Note>

### Choosing Your Identity Verification Method

<Tabs>
  <Tab title="Opal (Recommended)">
    Identity verification is handled within the Opal embedded UI. The user is guided through the KYC process in a managed, tested flow. This is the simplest path and ensures the verification experience is optimized for completion.
  </Tab>

  <Tab title="KBA">
    The user answers a set of identity questions generated from their credit and public record history (e.g., "Which of these addresses have you lived at?"). Your application presents the questions and collects answers. KBA is widely supported but can be frustrating for users if questions are obscure or ambiguous.

    ```bash theme={null}
    # 1. Create KBA verification session (returns questions)
    curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "identity",
        "method": "kba",
        "kba": {}
      }'

    # 2. Submit answers to the questions
    curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "identity",
        "method": "kba",
        "kba": {
          "answers": [
            { "question_id": "qtn_xxx", "answer_id": "ans_xxx" },
            { "question_id": "qtn_yyy", "answer_id": "ans_yyy" }
          ]
        }
      }'
    ```
  </Tab>

  <Tab title="BYO KYC">
    You perform identity verification on your side using your own KYC provider and report the outcome to Method. Choose this if you already have a KYC integration and want to consolidate verification into a single flow, or if you need to meet specific compliance requirements that require a particular KYC vendor.

    <Note>
      BYO KYC requires your team to be pre-authorized during onboarding. By creating this session, you're asserting that your external KYC process has passed for this user. Method trusts your KYC result — there are no constraints on which KYC vendor you use. Contact your Method CSM to enable this method.
    </Note>

    ```bash theme={null}
    curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "identity",
        "method": "byo_kyc",
        "byo_kyc": {}
      }'
    ```

    The response will include `byo_kyc: { authenticated: true }` confirming the verification was recorded.
  </Tab>
</Tabs>

#### Choosing an Identity Method

| Method      | User Experience     | Implementation                              | Best For                                   |
| ----------- | ------------------- | ------------------------------------------- | ------------------------------------------ |
| **Opal**    | Guided, pre-built   | Minimal                                     | Most teams                                 |
| **KBA**     | Multi-question quiz | Medium (present questions, collect answers) | API-only integrations without existing KYC |
| **BYO KYC** | Your existing flow  | Low (report result)                         | Teams with existing KYC provider           |

<Note>
  **About `element` and `method_verified` methods:** The API also lists `element` and `method_verified` as valid verification methods. `element` is the predecessor to Opal — new integrations should use Opal instead. `method_verified` is an internal method used by Method and is not available for external use.
</Note>


# Verification Outcomes
Source: https://docs.methodfi.com/guides/identity-verification/outcomes

Understanding the difference between Matched and Verified states.

## Verification Outcomes

### Understanding Verification Outcomes: Matched vs. Verified

Method distinguishes between two verification states, and understanding the difference matters:

| State                        | Meaning                                                        | Unlocks products? |
| ---------------------------- | -------------------------------------------------------------- | ----------------- |
| Neither matched nor verified | Entity created, not yet verified                               | No                |
| Matched only                 | Method identified the person, but they haven't proven identity | No                |
| Matched + Verified           | Full identity confirmation complete                            | Yes               |

An Entity cannot reach Verified status without first being Matched. If matching fails, verification cannot proceed.

In practical terms: matched means "we know who you are," and verified means "you've proven you're that person." Both are required.

### How Matching Works

When you create or update an Entity with PII (name, DOB, SSN, address, phone), Method attempts to correlate that information against its identity records. If the PII matches a known identity, the Entity becomes `matched`. This happens automatically when the Entity's PII is processed — you don't call a separate endpoint for matching.

The Entity's `matched` status is then checked when you create an identity verification session. If the Entity is not yet matched, the session creation will fail with `MISSING_IDENTITY_MATCH`.

Matching can fail if:

* The PII is incomplete (name + phone only, no DOB or SSN)
* The PII has typos or formatting issues
* The person has a thin file (limited credit/identity history)

See [Maximizing Verification Success](/guides/identity-verification/maximizing-success) for how to improve match rates.

### When Matching Fails

If Method cannot match the Entity's PII to a known identity, creating an identity verification session will return a `MISSING_IDENTITY_MATCH` error. Your options:

1. **Collect more PII:** Update the Entity with additional fields (DOB, SSN, address) and retry. More PII dramatically improves match rates.
2. **Verify the data:** Check for typos, name variations (maiden names, Jr/Sr suffixes), or incorrect phone numbers.

<Warning>
  Match failures are not the same as verification failures. A match failure means Method couldn't identify the person at all. A verification failure (KBA wrong answers, SMS wrong code) means the person was identified but couldn't prove they're that person.

  You will need to create a new Entity if a user fails identity verification (e.g., incorrect KBA answers). The failed Entity cannot be reused for identity verification.
</Warning>

### Checking Verification Status

The Entity object includes a `verification` field that reflects the current state:

```json theme={null}
"verification": {
  "identity": {
    "verified": true,
    "matched": true,
    "latest_verification_session": "evf_xxx",
    "methods": []
  },
  "phone": {
    "verified": true,
    "latest_verification_session": "evf_yyy",
    "methods": []
  }
}
```

When verification is incomplete, the `methods` arrays will contain the available verification methods for that step (e.g., `["sms", "sna"]` for phone, `["kba"]` for identity). Once a step is completed, its `methods` array becomes empty.

Use these fields to determine what actions are available for the Entity. See the [Entity API Reference](/reference/entities/overview) for full field documentation.

<CardGroup>
  <Card title="Maximizing Success" icon="chart-line" href="/guides/identity-verification/maximizing-success">
    Improve match rates through better data collection.
  </Card>

  <Card title="Verification Sessions API" icon="code" href="/reference/entities/verification-sessions/overview">
    Full API reference for verification session endpoints.
  </Card>
</CardGroup>


# Identity Verification (IDV)
Source: https://docs.methodfi.com/guides/identity-verification/overview

Why identity verification matters and how the two-step process works.

<Frame>
  <img alt="Identity Verification" />
</Frame>

## Proving Your Users Are Who They Claim to Be

<Warning>
  Method currently supports identity verification for US-based individuals only. Users without a US credit history or US phone number cannot complete verification.
</Warning>

### Why IDV Matters

Identity verification is the gateway to Method's platform. Before Method will discover a user's accounts, retrieve their credit data, or process payments on their behalf, the user must prove they are who they claim to be. It's a fundamental fraud prevention and compliance requirement that protects both your users and your platform.

For your product, IDV is typically the first meaningful interaction a user has after signing up. The verification experience directly impacts your onboarding conversion rate: a smooth, fast verification flow keeps users engaged, while a clunky or confusing one creates drop-off. Choosing the right verification approach is one of the most impactful product decisions you'll make in your Method integration.

IDV gates access to every downstream product: [Connect](/guides/connect/overview) (account discovery), [Updates](/guides/updates/overview) (fresh balances), [Payments](/guides/payments/overview), [Credit Scores](/guides/additional-products/credit-scores), [Attributes](/guides/additional-products/attributes), and more. An Entity that hasn't completed IDV stays in `incomplete` status with no product access. For most integrations, IDV is the single highest-impact step to optimize — every percentage point of verification conversion translates directly to users who can access your product's core features.

<Info>
  **Using Opal?** If you're using Method's embedded UI, Opal handles both phone verification and identity verification in a single, managed flow. You don't need to build verification screens or manage session state — Opal orchestrates the entire process. The rest of this section is relevant if you're building a custom integration or want to understand what Opal is doing under the hood. See the [Opal guide](/opal/identity/overview) for details.
</Info>

### The Two-Step Process

IDV consists of two sequential steps, each serving a distinct purpose:

<Steps>
  <Step title="Phone Verification">
    Confirms that the user controls the phone number associated with their identity. This is the "something you have" factor — it proves the person filling out your form actually possesses the phone number they provided.

    <Warning>
      Phone verification must be completed before identity verification can begin. Attempting to create an identity verification session for an Entity without phone verification will fail with `MISSING_PHONE_VERIFICATION`.
    </Warning>
  </Step>

  <Step title="Identity Verification">
    Confirms that the user's provided information matches a real person's identity through a KYC (Know Your Customer) process — it proves they are who they claim to be, not just someone who has access to a phone number.
  </Step>
</Steps>

Both steps must be completed for an Entity to be fully verified and gain access to downstream products.

### What Happens After Verification

Once both steps are complete, the Entity's status updates to `active` and the Entity becomes both `matched` and `verified`, unlocking downstream products: [Connect](/guides/connect/overview) (account discovery), [Credit Scores](/guides/additional-products/credit-scores), [Payments](/guides/payments/overview), and more. The verification is persistent — you don't need to re-verify for subsequent operations. See [Entity Lifecycle](/guides/entities/lifecycle) for how verification status affects what you can do.

<CardGroup>
  <Card title="Verification Methods" icon="list-check" href="/guides/identity-verification/methods">
    Choose the right phone and identity verification approach.
  </Card>

  <Card title="Verification Outcomes" icon="circle-check" href="/guides/identity-verification/outcomes">
    Understand the difference between Matched and Verified.
  </Card>

  <Card title="Maximizing Success" icon="chart-line" href="/guides/identity-verification/maximizing-success">
    Improve match rates through better data collection.
  </Card>

  <Card title="Verification Sessions API" icon="code" href="/reference/entities/verification-sessions/overview">
    Full API reference for verification session endpoints.
  </Card>
</CardGroup>


# The Verification Flow
Source: https://docs.methodfi.com/guides/identity-verification/verification-flow

Step-by-step verification sequence, state transitions, webhooks, and code walkthroughs.

## The Verification Flow

### Step-by-Step Sequence

<Steps>
  <Step title="Create Entity with PII">
    Create an Entity with at minimum a name and phone number. If you're using the API-driven flow (not Opal), providing more PII (DOB, SSN, address) significantly improves match rates. Opal collects PII directly from the user during its flow, so upfront PII is less critical when using Opal. See [Maximizing Success](/guides/identity-verification/maximizing-success).
  </Step>

  <Step title="Check available verification methods">
    Inspect `entity.verification.phone.methods` and `entity.verification.identity.methods` to see which verification methods are available for this Entity.
  </Step>

  <Step title="Create phone verification session">
    Choose a phone verification method (SMS, SNA, or BYO SMS) and create a verification session.
  </Step>

  <Step title="Complete phone verification">
    Complete the phone verification using the method-specific flow (submit SMS code, process SNA URLs, or report BYO result).
  </Step>

  <Step title="Create identity verification session">
    Once phone is verified, create an identity verification session (KBA or BYO KYC). This will fail with `MISSING_PHONE_VERIFICATION` if phone verification is not complete, or `MISSING_IDENTITY_MATCH` if Method couldn't match the Entity's PII.
  </Step>

  <Step title="Complete identity verification">
    Complete the identity verification using the method-specific flow (submit KBA answers or report BYO KYC result).
  </Step>

  <Step title="Entity is verified">
    Entity is now matched + verified. Proceed to [Connect](/guides/connect/overview), [Payments](/guides/payments/overview), or other products.
  </Step>
</Steps>

### State Diagram

```
[Entity created] → [Phone: unverified] → [Phone: verified] → [Identity: unverified] → [Identity: matched + verified] → [Products unlocked]
```

Each verification session goes through its own lifecycle:

```
pending → in_progress → verified (success)
                       → failed (expired, incorrect code/answer, SNA failure)
```

### Webhooks

Subscribe to verification session events to track progress:

* **`entity_verification_session.create`** — Fired when a new verification session is created.
* **`entity_verification_session.update`** — Fired when a session's status changes (e.g., `pending` → `verified`, `pending` → `failed`).

These events allow you to build reactive flows — for example, unlocking the next step of your onboarding when phone verification completes.

### Code Walkthroughs

#### SMS + KBA (most common API-driven path)

```bash theme={null}
# 1. Create an Entity
curl -X POST https://production.methodfi.com/entities \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "individual": {
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+15551234567",
      "dob": "1990-01-15"
    }
  }'

# 2. Create SMS phone verification session
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sms",
    "sms": {}
  }'

# 3. User receives SMS code, submit it
curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sms",
    "sms": { "sms_code": "123456" }
  }'

# 4. Create KBA identity verification session (returns questions)
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity",
    "method": "kba",
    "kba": {}
  }'

# 5. Present questions to user, then submit answers
curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_yyy \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity",
    "method": "kba",
    "kba": {
      "answers": [
        { "question_id": "qtn_aaa", "answer_id": "ans_bbb" },
        { "question_id": "qtn_ccc", "answer_id": "ans_ddd" }
      ]
    }
  }'

# Entity is now verified — proceed to Connect or other products
```

#### SNA + KBA (best UX path)

```bash theme={null}
# 1. Create Entity (same as above)

# 2. Create SNA phone verification session
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sna",
    "sna": {}
  }'
# Response includes SNA URLs — open them via background request on the user's device

# 3. Update SNA session to check verification status
curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sna",
    "sna": {}
  }'
# If SNA fails, fall back to SMS (create a new session with method "sms")

# 4-5. Proceed with KBA identity verification (same as above)
```

#### BYO SMS + BYO KYC (existing infrastructure path)

```bash theme={null}
# 1. Create Entity (same as above)

# 2. Report BYO SMS phone verification
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "byo_sms",
    "byo_sms": {
      "timestamp": "2026-04-10T12:00:00.000Z"
    }
  }'

# 3. Report BYO KYC identity verification
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity",
    "method": "byo_kyc",
    "byo_kyc": {}
  }'

# Entity is now verified
```


# Opal
Source: https://docs.methodfi.com/guides/opal

Method's embedded UI for identity verification, account discovery, and more.

## What Opal Is and Why It Matters

Opal is Method's embedded UI, a set of pre-built, white-labeled screens and flows that you drop into your application to handle the complex, multi-step processes of identity verification, account discovery, and more. Instead of designing, building, testing, and maintaining these flows yourself, you launch Opal and let it guide your users through the process in a polished, tested experience.

Opal represents a significant acceleration of your roadmap. Building identity verification and account linking flows from scratch typically takes weeks of engineering time, plus ongoing maintenance as edge cases, error states, and accessibility requirements emerge. Opal compresses this to days, your engineering team creates a session token, launches the component, and listens for completion events. Everything in between is handled by Method.

Opal is also designed for conversion. The flows are optimized for completion rates, with clear progress indicators, helpful error messaging, and the ability for users to resume interrupted sessions without starting over. When a user's phone dies mid-verification or they need to step away, their progress is saved.

## Opal Modes — What Your Users Experience

Opal operates in distinct modes, each handling a specific part of the user journey. You can launch these independently depending on where the user is in your flow:

<CardGroup>
  <Card title="Identity Verification" icon="shield-check" href="/opal/identity/overview">
    Guides the user through Method's two-step verification process. First, the user confirms their phone number (via SMS code, silent network auth, or other methods). Then, they complete identity verification through a KYC process. From the user's perspective, this feels like a simple onboarding step, enter some information, confirm a code, answer a few questions, and they're verified. Behind the scenes, Opal is orchestrating phone verification, identity matching, and KYC compliance.
  </Card>

  <Card title="Connect" icon="link" href="/opal/connect/overview">
    After verification, the user consents to a soft credit pull, and Opal displays the discovered liability accounts, credit cards, loans, mortgages, and more, in a clear, organized interface. The user can see what was found and proceed to the next step in your flow. This is often the "wow moment" in a debt management product: the user sees their complete liability picture for the first time, surfaced automatically without manual entry.
  </Card>

  <Card title="Card Connect" icon="credit-card" href="/opal/card_connect/overview">
    Handles the specific case where a user needs to verify and connect a particular card for payment flows. This is useful when your product needs to work with a specific card rather than discovering all liabilities.
  </Card>

  <Card title="Account Verification" icon="building-columns" href="/opal/account_verification/overview">
    Confirms ownership of a specific account. This is used when you need to verify that a user controls a particular financial account before enabling certain operations.
  </Card>
</CardGroup>

Each mode can be launched independently depending on where the user is in your flow.

## How Opal Integrates Into Your Flow

<Steps>
  <Step title="Request a session token">
    Your backend requests a session token from Method, scoped to a specific user (Entity) and a specific mode
  </Step>

  <Step title="Load the SDK">
    Your frontend application loads Opal using one of Method's client SDKs (available for web, React, and React Native)
  </Step>

  <Step title="User interacts with Opal">
    The user interacts with Opal directly, filling in information, confirming codes, reviewing discovered accounts
  </Step>

  <Step title="Receive webhook events">
    Your backend listens for webhook events that signal progress and completion, triggering whatever comes next in your application flow
  </Step>
</Steps>

Sessions are persistent, meaning users can leave and return without losing progress. This is particularly important for mobile users who may be interrupted by notifications, phone calls, or simply needing to come back later.

## Customization and Branding

Opal is designed to feel like a native part of your application, not a third-party widget. Customization options include:

* Brand colors and accent colors
* Typography and font choices
* Logo placement and branding elements
* Light/dark mode support

The goal is that your users never feel like they've been handed off to a different product. Refer to the [Opal documentation](/opal/overview) for the full range of theming options and accessibility compliance details.

## When to Consider API-Only

Opal covers the vast majority of integration scenarios, but there are cases where building directly against Method's APIs may be a better fit:

* Your product has an existing onboarding flow that users are already familiar with, and you need the verification steps to feel native to that flow's design language
* Your compliance or security requirements demand that PII collection happens entirely within your own infrastructure
* You need fine-grained control over the verification step ordering or conditional logic that Opal's session model doesn't support

If you're unsure, start with Opal. You can always migrate specific steps to API-only later without rebuilding everything.

<Warning>
  Elements was Method's previous embedded UI, deprecated on December 31, 2025. All new integrations should use Opal. If your team is still using Elements, plan your migration using the [Opal migration guide](/opal/migration_guide).
</Warning>

## What's Next

<CardGroup>
  <Card title="Opal Quickstart" icon="rocket" href="/opal/quickstart">
    Get Opal running in your application in minutes.
  </Card>

  <Card title="Opal Libraries" icon="book" href="/opal/libraries">
    SDK installation and setup for web, React, and React Native.
  </Card>

  <Card title="Opal Sessions" icon="key" href="/opal/sessions">
    Session management, token creation, and lifecycle.
  </Card>

  <Card title="Opal Events" icon="bell" href="/opal/events">
    Event handling and completion callbacks.
  </Card>

  <Card title="Opal API Reference" icon="code" href="/reference/opal/overview">
    Token creation, session management, and event types.
  </Card>
</CardGroup>


# What is Method
Source: https://docs.methodfi.com/guides/overview

Method is the infrastructure layer for consumer liability data and payments.

In a financial ecosystem where liability information is fragmented across thousands of institutions, reported inconsistently, and often weeks out of date, Method provides a single, unified platform that brings structure and reliability to this fragmented landscape.

<Note>
  These Guides cover concepts and product decisions. For implementation details and code, see the [API Reference](/reference/introduction).
</Note>

## How Method Works

Unlike aggregators that require users to share their bank login credentials, Method uses a fundamentally different approach. When a user verifies their identity, Method performs a soft credit pull (no impact to the user's credit score) to automatically discover all of their liabilities, without any manual account entry or credential sharing.

Once accounts are discovered, Method can retrieve real-time data directly from financial institutions for supported accounts, giving you current balances, due dates, interest rates, and payment amounts. For accounts where direct connections aren't available, Method falls back to credit report data as a reliable baseline.

This two-source model, credit report discovery paired with direct institutional access, means your product gets both breadth (visibility into virtually every liability) and depth (real-time data where it matters most).

## What Method Does

<CardGroup>
  <Card title="Discover and connect consumer liabilities at scale" icon="magnifying-glass">
    Method connects to 15,000+ financial institutions, from major banks to regional lenders. When a user links their identity, you gain visibility into their full liability picture — credit cards, auto loans, student loans, mortgages, personal loans, and more.
  </Card>

  <Card title="Keep liability data fresh and normalized" icon="arrows-rotate">
    Liability data arrives from institutions in inconsistent formats and update cycles. Method standardizes balances, due dates, interest rates, payment amounts, and limits into a clean, consistent data model accessible through a single API.
  </Card>

  <Card title="Move money to pay down debts" icon="money-bill-transfer">
    Method enables payments directly to connected liability accounts. Initiate paydowns from a verified funding source while Method handles submission, processing, delivery to the creditor, and confirmation.
  </Card>

  <Card title="Monitor changes over time for your users" icon="bell">
    Financial accounts constantly change — balances update, payments post, and accounts open or close. Method's subscription system keeps your application synced with these updates through near-real-time notifications.
  </Card>
</CardGroup>

## Who Method Is Built For

### Commerce

Commerce and card-linked platforms that need to connect to consumers' card accounts for transaction data, card-on-file verification, or payment instrument provisioning to power checkout, rewards, and card-linked offer experiences.

<CardGroup>
  <Card title="Wallet Onboarding" icon="wallet" href="/guides/use-cases/commerce/wallet-onboarding">
    Connect every credit card a customer owns in a single flow, then enrich and tokenize for checkout.
  </Card>

  <Card title="Preauth Signals" icon="signal" href="/guides/use-cases/commerce/preauth-signals">
    Evaluate payment readiness before authorization and retry failed payments at the optimal time.
  </Card>
</CardGroup>

### Lending

Lenders and underwriters that need verified, up-to-date liability data to make credit decisions, calculate debt-to-income ratios, verify existing obligations, and enable debt consolidation through structured plans, lump-sum payments, or automated recurring transfers.

<CardGroup>
  <Card title="Application & Qualification" icon="clipboard-check" href="/guides/use-cases/lending/application-prefill">
    Pre-fill loan applications with verified liability data and assess risk with credit health attributes.
  </Card>

  <Card title="Debt Consolidation" icon="money-bill-transfer" href="/guides/use-cases/lending/debt-consolidation">
    Discover eligible accounts, verify current balances, and disburse funds directly to creditors.
  </Card>

  <Card title="Portfolio Intelligence" icon="chart-line" href="/guides/use-cases/lending/portfolio-monitoring">
    Monitor borrower liability, utilization, and delinquency signals continuously after origination.
  </Card>
</CardGroup>

### Personal Finance & Financial Wellness

Personal finance and financial wellness applications that want to give users a comprehensive view of their liabilities alongside their assets, track progress over time, and provide actionable insights about credit health.

<CardGroup>
  <Card title="Onboarding & Discovery" icon="magnifying-glass" href="/guides/use-cases/pfm/onboarding-discovery">
    Identity verification options, liability discovery via Connect, and vehicle enrichment for auto loans.
  </Card>

  <Card title="Dashboard & Insights" icon="chart-mixed" href="/guides/use-cases/pfm/monitoring-insights">
    Build real-time debt dashboards with account updates, card brand art, credit scores, and financial health attributes.
  </Card>

  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Stream credit card transactions for spend management and initiate bill payments to your users' creditors.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/guides/quickstart">
    Most integrations follow this four-step pattern, though the exact flow may vary depending on your product and use case.
  </Card>

  <Card title="Core Concepts" icon="diagram-project" href="/guides/concepts">
    Understand Method's object model and how everything connects.
  </Card>

  <Card title="Opal" icon="window" href="/guides/opal">
    Drop-in embedded UI that handles identity verification, account discovery, and more — get to value in days, not weeks.
  </Card>

  <Card title="API Reference" icon="code" href="/reference/introduction">
    Dive into the full API documentation.
  </Card>
</CardGroup>


# Payment Errors and Constraints
Source: https://docs.methodfi.com/guides/payments/errors

Processing windows, posting timing, return codes, and idempotency.

## Payment Errors and Constraints

* Payments submitted outside of processing windows will be held until the next window.
* Posting timing depends on the creditor and is outside Method's control.
* Return codes may be provided when a payment fails or is returned.
* Duplicate payments can be prevented using [idempotency keys](/reference/idempotency).


# Payment Instruments
Source: https://docs.methodfi.com/guides/payments/instruments

Reusable payment configurations for recurring and repeated payments.

## Payment Instruments — Reusable Payment Configurations

For products that involve recurring or repeated payments (e.g., a monthly debt paydown plan), Payment Instruments provide a convenience layer. Instead of collecting and submitting payment details for every transaction, you create a Payment Instrument once, capturing the card credentials, ACH details, or network token, and reference it for subsequent payments.

Think of a Payment Instrument as a saved payment method. The user sets it up once, and your product can initiate payments against it repeatedly without re-collecting credentials. Instruments remain valid until explicitly closed or the underlying account changes.

Method supports three types of Payment Instruments:

| Type                 | Description                                                         |
| -------------------- | ------------------------------------------------------------------- |
| **Card**             | Card credentials for payment                                        |
| **Inbound ACH/Wire** | Routing and account details for ACH or wire payments to a liability |
| **Network Token**    | Tokenized card credentials for secure, network-level transactions   |

<Note>
  Not all accounts support all instrument types, check the account's available products before attempting to create an instrument. And listen for webhook events about instrument status changes, as instruments may become invalid if the underlying account is closed or credentials expire.
</Note>

For the full Payments API, see the [Payments reference](/reference/payments/overview). For Payment Instruments, see the [Payment Instruments reference](/reference/accounts/payment-instruments/overview).


# Payment Lifecycle
Source: https://docs.methodfi.com/guides/payments/lifecycle

What your users should see as payments move through the system.

## Payment Lifecycle — What Your Users Should See

Every payment moves through a defined lifecycle, and each stage should map to a clear user-facing status in your product:

| Method Status           | User-Facing Copy                        | Description                                                                 |
| ----------------------- | --------------------------------------- | --------------------------------------------------------------------------- |
| **Pending**             | "Payment scheduled" or "Payment queued" | The payment has been created and is waiting for the next processing window. |
| **Canceled**            | "Payment canceled"                      | The payment was canceled before it was processed.                           |
| **Processing**          | "Payment in progress"                   | The payment is actively being processed through the banking system.         |
| **Sent**                | "Payment sent to your creditor"         | Funds have been initiated and sent to the creditor.                         |
| **Posted**              | "Payment complete"                      | The creditor has confirmed the payment has been applied to the account.     |
| **Failed**              | "Payment couldn't be processed"         | An error occurred — see failure details.                                    |
| **Reversal Processing** | "Reversal in progress"                  | A reversal has been approved and is being processed.                        |
| **Reversed**            | "Payment returned"                      | A previously sent payment was returned.                                     |

Design your product to show clear status transitions as webhook events arrive. Users should feel confident that their money is moving and that the system is working, ambiguity about payment status is one of the fastest ways to erode trust.

### Handling Reversals and Failures

Payments can fail or be reversed, and your product should be able to handle these scenarios gracefully:

**Failed Payments**

Failed payments can occur at various stages due to insufficient funds in the funding account, invalid or closed account details, or creditor rejection. When a payment fails, Method emits a webhook event with the failure details. Your product should notify the user clearly, explain what happened in plain language, and provide a path to retry if applicable.

**Reversed Payments**

Reversals occur when a payment that was already sent is returned, for example, if the funding account has insufficient funds after the payment was initiated, or if the creditor returns the payment for any reason. Reversals are tracked as separate objects with their own lifecycle and webhook events. Your product should notify the user, explain the reversal, and update any progress displays that reflected the original payment.

<Warning>
  In both cases, avoid technical jargon. Users don't need to know about ACH return codes or processing windows, they need to know what happened, why, and what to do next.
</Warning>

### Settlement Timing

Settlement and posting timing varies by creditor and payment rail. Do not make hard assumptions about when a payment will post.


# Payments
Source: https://docs.methodfi.com/guides/payments/overview

How Method moves money to pay down debt.

## Payments — Moving Money to Pay Down Debt

### What Payments Enable

Payments are where Method's platform closes the loop from data to action. After discovering a user's liabilities and retrieving their current account data, Payments enable your application to actually move money — initiating paydowns from your platform's corporate funding account to your users' creditors.

This is the capability that transforms Method from a data platform into a complete debt management infrastructure. Without Payments, you can show users what they owe. With Payments, you can help them do something about it.

### What's Required Before a Payment Can Be Made

<Steps>
  <Step title="A verified Entity">
    The user must have completed [identity verification](/guides/identity-verification/overview). This is a non-negotiable compliance and fraud prevention requirement.
  </Step>

  <Step title="A destination liability account">
    The credit card, loan, or other debt being paid down, typically discovered through [Connect](/guides/connect/overview). This is where the money goes.
  </Step>

  <Step title="A verified funding source">
    Your platform's corporate bank account (checking or savings), linked via ACH and [verified](/guides/accounts/funding) through micro-deposits, Plaid, MX, or Teller. This is where the money comes from.
  </Step>

  <Step title="Webhook handling">
    Because payment processing is asynchronous (it takes time for money to move through the banking system), your application must listen for [webhook](/guides/platform-fundamentals#real-time-notifications-via-webhooks) notifications to track the payment's progress through its lifecycle.
  </Step>
</Steps>

### Payment Processing and Timing

Method supports electronic push payments to liability accounts. When a payment is submitted, funds are initiated from your platform's verified funding account and delivered to the creditor.

Processing typically takes 2–3 business days, though the exact timing varies by institution. Payments are processed in defined windows throughout the business day, so the time you submit a payment relative to the next processing window affects when it begins moving. Payments submitted outside of processing windows are held until the next window.

Settlement and posting times are ultimately controlled by the receiving creditor, not by Method. Some creditors apply payments same-day upon receipt; others may take additional time. This means your product should set user expectations appropriately: "Your payment has been sent and will be applied by your creditor, typically within a few business days." Avoid making hard promises about exact posting dates.


# Platform Fundamentals
Source: https://docs.methodfi.com/guides/platform-fundamentals

Environments, authentication, data flow patterns, and webhooks.

## Environments

Method provides three isolated environments, each serving a distinct purpose in your integration lifecycle:

<CardGroup>
  <Card title="Development" icon="wrench">
    Mocked responses. No real institutions contacted, no payments processed.
  </Card>

  <Card title="Sandbox" icon="flask-vial">
    Simulated flows with test data. Mimics real account discovery, payment timelines, and error states.
  </Card>

  <Card title="Production" icon="rocket">
    Live environment. Real institutions, real data, real money.
  </Card>
</CardGroup>

<Warning>
  Each environment uses separate API credentials and data does not cross environments. This allows you to test safely in Development and Sandbox without affecting Production users or data.
</Warning>

## Authentication and API Keys

Method uses API keys for authentication. Include your key in the `Authorization` header of every request. Each environment under each team has its own unique API key.

```bash theme={null}
curl https://production.methodfi.com/entities \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Method-Version: 2026-03-30"
```

The `Method-Version` header pins your requests to a specific API version, ensuring your integration behaves consistently even as Method's API evolves. When a new version is released, you can migrate on your own timeline. If the header is omitted, your team's default version is used. See [Versioning](/reference/versioning) in the API Reference for details.

See the [Authentication](/reference/authentication) reference for details.

## How Data Flows: On-Demand vs Subscriptions

Method offers two complementary models for accessing data, and understanding when to use each is important for designing your product experience.

<Tabs>
  <Tab title="On-Demand">
    On-demand access means you request data when you need it. For example, when a user opens their dashboard, you might request a fresh balance update for their accounts at that moment. On-demand is best for user-initiated actions, one-time data pulls, or situations where you need specific data at a specific time.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates \
      -X POST \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Method-Version: 2026-03-30" \
      -H "Content-Type: application/json" \
      -d '{"type": "direct"}'
    ```
  </Tab>

  <Tab title="Subscriptions">
    Subscription-based access means Method continuously monitors for changes and delivers new data to you automatically. For example, you might subscribe to balance updates for all of a user's accounts, and Method will notify you whenever new data is available, whether that's daily, weekly, or whenever the financial institution reports. Subscriptions are best for keeping dashboards current, triggering automated workflows, and monitoring for changes without requiring user action.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions \
      -X POST \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Method-Version: 2026-03-30" \
      -H "Content-Type: application/json" \
      -d '{"enroll": "update"}'
    ```
  </Tab>
</Tabs>

<Note>
  Not all products support both modes. Refer to each product's documentation for availability.
</Note>

## Real-Time Notifications via Webhook Events

Method's platform is fundamentally asynchronous, when you request an account update or initiate a payment, the result isn't always available immediately. Instead, Method notifies your system when something happens through webhook events: real-time HTTP notifications sent to an endpoint you configure.

For your product team, the key implication is this: your application should be designed around event-driven updates rather than polling or refresh buttons. When a payment posts, when new account data is available, when a user's credit score changes, Method tells you. This event-driven model enables responsive, real-time user experiences without the complexity and cost of constant polling.

The typical webhook handling pattern looks like this:

1. Method sends an HTTP POST to your configured endpoint with event details
2. Your backend acknowledges receipt (return a 2xx response promptly)
3. Your backend fetches the updated resource using the IDs in the event payload
4. Your application updates its local state and, if needed, refreshes the user's UI

This pattern applies to virtually every webhook: payment status changes, new account data, completed discovery, credit score updates, and more.

<Warning>
  Return your 2xx response before processing the event. If your endpoint takes too long to respond, Method will retry the delivery, which can cause duplicate processing. Deduplicate deliveries using the `method-webhook-delivery-id` request header and make your processing idempotent; see [Handling duplicate deliveries](/reference/webhooks/overview#handling-duplicate-deliveries).
</Warning>

Nearly every product creates and updates events, so webhooks are the primary mechanism for keeping your system in sync with Method.

Common webhook events include:

| Event                 | Description                             |
| --------------------- | --------------------------------------- |
| `payment.update`      | A payment's status has changed          |
| `account.create`      | A new account was discovered or created |
| `connect.completed`   | Account discovery finished              |
| `update.completed`    | Fresh account data is available         |
| `credit_score.update` | A credit score has changed              |

See the [Webhooks](/reference/webhooks/overview) reference for setup instructions and the [Events](/reference/events/overview) reference for the full list of event types.

## Reliability and Safety

Method's platform includes built-in mechanisms to ensure reliability. Your engineering team will handle implementation details, but at a product level the key guarantees are:

* **Idempotency keys:** Duplicate operations are prevented automatically (so a network hiccup doesn't create two payments). See [Idempotency](/reference/idempotency).
* **Rate limits:** Requests are rate-limited to maintain platform stability, and operations can be safely retried without unintended side effects. See [Rate Limiting](/reference/rate-limiting) in the API Reference for details.
* **Versioned APIs:** Method maintains versioned APIs so integrations remain stable as the platform evolves. New capabilities are introduced without breaking existing implementations.
* **Paginated list endpoints:** All list endpoints return paginated results, ensuring predictable performance regardless of data volume. See [Pagination](/reference/pagination) in the API Reference for details.
* **Reliable updates:** Changes to liabilities and payments are delivered through subscriptions and webhooks, ensuring your application stays in sync with real account activity.

These aren't features you need to design around, they're guardrails Method provides out of the box.

<CardGroup>
  <Card title="Authentication Reference" icon="key" href="/reference/authentication">
    API keys, headers, and request setup.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.methodfi.com/guides/quickstart

Get up and running with Method's four-step integration process.

Getting up and running with Method follows a predictable path, whether you're building a debt repayment app, a financial wellness dashboard, or an embedded lending experience.

## The Four-Step Integration Process

Most integrations follow the same high-level pattern, regardless of your specific use case:

<Steps>
  <Step title="Represent your user">
    Every end user in your application maps to an [Entity](/guides/entities/overview) in Method. This is the foundational object that everything else, verification, accounts, payments, attaches to. You provide basic identifying information (name, phone number, and optionally additional PII), and Method creates a persistent identity that follows the user throughout their lifecycle in your product.
  </Step>

  <Step title="Verify their identity">
    Before Method can discover a user's accounts or process payments on their behalf, the user must complete [identity verification](/guides/identity-verification/overview). This is a two-part process: first confirming they control their phone number, then verifying their identity through a KYC process.

    Method supports multiple verification approaches (SMS, silent network auth, KBA, and BYO options). Method will partner with your team to help determine which methods are best suited for your use case and user demographics.
  </Step>

  <Step title="Discover their accounts">
    Once verified, Method can discover the user's financial liabilities using a soft-pull credit report (no impact to their credit score). This is the moment where your product goes from knowing who a user is to knowing what they owe — and to whom. [Accounts](/guides/accounts/overview) are automatically created in Method as they're discovered, giving you immediate access to liability data across credit cards, loans, mortgages, and more.

    Each discovered account comes with the data reported to the credit bureau, including balance, credit limit, payment status, account type, and the financial institution that holds the account. From there, you can request real-time [Updates](/guides/updates/overview) to get current balances, due dates, minimum payments, interest rates, and more directly from the institution.
  </Step>

  <Step title="Take action">
    With accounts connected, you can now do the things that make your product valuable: pull fresh balance and payment data ([Updates](/guides/updates/overview)), initiate paydowns and bill pay ([Payments](/guides/payments/overview)), monitor for changes over time, and present your users with a clear, actionable picture of their financial obligations.

    Updates return structured, normalized fields — balances, due dates, minimum payments, interest rates, credit limits, and more — in a consistent format regardless of the underlying financial institution.
  </Step>
</Steps>

## Choosing Your Integration Approach

Method offers two primary integration approaches, and understanding the tradeoff early saves significant time:

<Tabs>
  <Tab title="Opal (Embedded UI)">
    **Best for most teams.** [Opal](/guides/opal) is Method's pre-built, white-labeled UI that handles identity verification, account discovery, and more. It's designed to drop into your application with minimal frontend work while providing a polished, tested user experience.

    *Choose Opal if you want to move fast, minimize custom UI development, and leverage Method's UX expertise. Most teams start here.*
  </Tab>

  <Tab title="API-Only">
    **Best for teams with specific UX requirements.** If you have an existing in-app flow, a highly customized user experience, or specific design requirements that Opal can't accommodate, you can integrate directly with Method's APIs.

    *This gives you complete control over the user experience but requires more frontend development and ongoing maintenance.*
  </Tab>
</Tabs>

## Example Integration Paths

To make the integration journey concrete, here are three common paths mapped to real product scenarios:

<AccordionGroup>
  <Accordion title="Debt Discovery (e.g., a financial wellness dashboard)">
    Your user signs up → you create an Entity and verify their identity → Method discovers all their liabilities → you display a comprehensive debt overview with balances, interest rates, and payment schedules → you subscribe to updates to keep the dashboard current.

    *Timeline to first value: the user sees their complete debt picture within minutes of completing verification.*
  </Accordion>

  <Accordion title="Debt Paydown (e.g., a debt repayment lender)">
    Your user signs up → identity verification → account discovery → you link your corporate account as a funding source → your user flow presents a paydown strategy → payments are initiated through Method → you track each payment from submission to posting and update the user's progress.

    *This is the full end-to-end loop that turns data into action.*
  </Accordion>

  <Accordion title="Ongoing Monitoring (e.g., a credit health tool)">
    Your user completes the initial setup → you subscribe to account updates and credit score monitoring → Method notifies you when balances change, payments post, credit scores shift, or new accounts appear → your app surfaces these changes as alerts, insights, or progress updates.

    *The user gets continuous value without ever repeating the setup process.*
  </Accordion>

  <Accordion title="Card Linking (e.g., a card-linked offers platform)">
    Your user signs up → you create an Entity and verify their identity → Method discovers their credit card accounts → you retrieve card brand details (card art, product name) and tokenize card credentials via Payment Instruments → your platform uses these tokens for checkout, rewards enrollment, or transaction monitoring.

    *This flow connects your product to the user's existing cards without manual entry or credential sharing.*
  </Accordion>
</AccordionGroup>

## What's Next

<CardGroup>
  <Card title="Platform Fundamentals" icon="gear" href="/guides/platform-fundamentals">
    Environments, authentication, webhooks, and data flow patterns.
  </Card>

  <Card title="Core Concepts" icon="diagram-project" href="/guides/concepts">
    Understand Method's object model and dependency chain.
  </Card>

  <Card title="Opal" icon="window" href="/guides/opal">
    Drop-in embedded UI for identity verification and account discovery.
  </Card>

  <Card title="API Reference" icon="code" href="/reference/introduction">
    Dive into the full API documentation.
  </Card>
</CardGroup>


# Billing Lifecycle and Data Availability
Source: https://docs.methodfi.com/guides/updates/billing-lifecycle

How a cardholder's billing stage determines which fields come back in an Update.

## Billing Lifecycle and Data Availability

Financial institutions determine which data fields are returned for Updates based on the cardholder's billing lifecycle stage. The four common cardholder states:

* **Bill Created**: A new statement has been generated. All billing fields are available.
* **Bill Due**: A payment is owed. Balance, minimum payment, and due date are present, but no last payment information has been reported yet.
* **Bill Paid**: A payment has been made. Last payment amount and date are available, but the next due date has not yet been generated.
* **Dormant**: The account is open but shows minimal activity. Typically only balance (and sometimes available credit) is returned.

| Field                          | Created | Due | Paid | Dormant |
| ------------------------------ | :-----: | :-: | :--: | :-----: |
| available\_credit              |    ✓    |  ✓  |   ✓  |    ✓    |
| balance                        |    ✓    |  ✓  |   ✓  |    ✓    |
| last\_payment\_amount          |    ✓    |     |   ✓  |         |
| last\_payment\_date            |    ✓    |     |   ✓  |         |
| next\_payment\_minimum\_amount |    ✓    |  ✓  |   ✓  |         |
| next\_payment\_due\_date       |    ✓    |  ✓  |      |         |

*Approximate distribution across states: Bill Created 28%, Bill Due 10%, Bill Paid 31%, Dormant 10%, Other 20%.*

The distribution across these states varies significantly by issuer. Each financial institution presents data differently, resulting in different extraction profiles.


# Handling Update Failures
Source: https://docs.methodfi.com/guides/updates/failures

Recommended patterns for handling stale data and failed refreshes.

## Common Failure Modes

Direct Updates can fail for several reasons. In the Update response, direct retrieval failures currently surface through a canonical `error` object:

| Failure Mode                                           | Where it surfaces                                                                      | Recommended Action                                                                                          |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Institution unreachable or temporarily unavailable     | Update `error.code: 21001`; account `data_status_error` is usually `15004` or `15006`. | Retry after a delay. These are usually transient.                                                           |
| Account not supported                                  | Account `data_status_error: 15009`.                                                    | Check the account's `products` array, then rely on snapshot Updates from an `update.snapshot` subscription. |
| Account closed, paid off, transferred, or consolidated | Account `data_status_error` is `15001`, `15002`, `15003`, or `15010`.                  | Update your local records. Re-discover via Connect when appropriate.                                        |
| Authentication or account detail mismatch              | Account `data_status_error` is `15005` or `15007`.                                     | Refresh identity or account details, then re-enroll or re-discover the account.                             |
| Delinquent or disabled liability                       | Account `data_status_error` is `15008` or `15011`.                                     | Surface the state to the user or contact support if unexpected.                                             |

```json theme={null}
{
  "id": "upt_NYV5kfjskTTCJ",
  "status": "failed",
  "error": {
    "type": "UPDATE_FAILED",
    "sub_type": "UPDATE_TEMPORARILY_UNAVAILABLE",
    "code": 21001,
    "message": "Update is temporarily unavailable for this account."
  }
}
```

For the granular reason, read the underlying account liability's `data_status_error`. These are the codes exposed by the API:

| Code    | Reason                     | What it means                                                                                                                                                | Recommended action                                                        |
| ------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `15001` | Closed                     | The account has been closed at the institution.                                                                                                              | Update your local records. Don't retry.                                   |
| `15002` | Paid in full               | The liability has been paid off.                                                                                                                             | Update your local records. Don't retry.                                   |
| `15003` | No longer serviced         | The institution no longer services this account (e.g. transferred or sold).                                                                                  | Update your local records. Don't retry.                                   |
| `15004` | Unauthorized / sync failed | Catch-all for transient and connection-level failures (institution timeouts, technical issues, outside-hours, internal errors, repeated failure throttling). | Retry after a delay. If persistent, contact support.                      |
| `15005` | Invalid holder details     | The institution rejected the holder details Method has on file (e.g., DOB, postal code, KYC).                                                                | Refresh the entity's identity data and re-enroll.                         |
| `15006` | Temporarily unavailable    | Generic temporary failure.                                                                                                                                   | Retry after a delay.                                                      |
| `15007` | Invalid account number     | The account number Method has is no longer valid at the institution.                                                                                         | Re-discover the account via Connect.                                      |
| `15008` | Delinquent                 | The account is in a delinquent state at the institution.                                                                                                     | Surface this to the user. Don't retry until resolved.                     |
| `15009` | Unsupported merchant       | The institution doesn't support real-time data connections for this account type.                                                                            | Rely on snapshot Updates delivered via an `update.snapshot` subscription. |
| `15010` | Consolidated loan          | The student loan has been consolidated into a different loan.                                                                                                | Re-discover via Connect.                                                  |
| `15011` | Liability disabled         | Updates have been disabled for this liability.                                                                                                               | Don't retry. Contact support if unexpected.                               |

<Note>
  Rate limiting is not currently exposed as a distinct Update failure code. Repeated failure throttling may appear under the catch-all sync failed reason (`15004`).
</Note>

## Retry Strategy

```
1. First retry: wait 5 minutes
2. Second retry: wait 30 minutes
3. Third retry: wait 2 hours
4. After 3 failures: display the most recent snapshot data and alert your CSM
```

Use [idempotency keys](/reference/idempotency) when retrying to avoid duplicate requests.

## Fallback Pattern: Direct to Snapshot

When direct Updates aren't available or keep failing, snapshot data provides a reliable baseline. Note that `POST /accounts/{acc_id}/updates` always creates a direct Update; you cannot request a snapshot Update on demand. Snapshot Updates are produced by `update.snapshot` [subscriptions](/guides/updates/subscriptions) and delivered via webhook.

To fall back to snapshot data, list the account's existing Updates and use the most recent one whose `source` is `snapshot`:

```bash theme={null}
curl "https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates?source=snapshot" \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

If no snapshot Update exists yet, create an `update.snapshot` subscription so future bureau refreshes are delivered automatically:

```bash theme={null}
curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{"enroll": "update.snapshot"}'
```

## UX Recommendations

* **Always show the most recent known data**, even if it's stale. A balance from last week is better than a blank screen.
* **Indicate freshness.** Show the `data_as_of` timestamp so users know how current the data is: "Balance as of March 20, 2024."
* **Show refresh state.** When an Update is in progress, show a loading indicator alongside the existing data.
* **Don't block on failures.** If a direct Update fails, display the last snapshot data and retry in the background.

## Subscription Failures

For failed subscription executions, Method requeues the subscription execution for retry. The subscription queue retries failed executions daily up to three times, then schedules the next run according to the subscription's normal cadence.

Monitor `update.update` webhooks for failed Updates to detect persistent issues with specific accounts or institutions and to drive your own fallback (e.g., showing snapshot data, prompting the user to reconnect for `15005`/`15007`).

## Fields by Liability Type

The data returned in an Update depends on the account type. Common patterns:

| Liability Type | Key Fields                                                                                          |
| -------------- | --------------------------------------------------------------------------------------------------- |
| Credit Card    | balance, available\_credit, credit\_limit, interest\_rate (min/max/type), payment info, opened\_at  |
| Auto Loan      | balance, interest\_rate, original\_loan\_amount, term\_length, expected\_payoff\_date, payment info |
| Student Loan   | balance, original\_loan\_amount, term\_length, payment info                                         |
| Mortgage       | balance, interest\_rate, original\_loan\_amount, term\_length, expected\_payoff\_date, payment info |
| Personal Loan  | balance, available\_credit, interest\_rate, original\_loan\_amount, term\_length, payment info      |

All types share: `balance`, `last_payment_amount`, `last_payment_date`, `next_payment_due_date`, `next_payment_minimum_amount`, `opened_at`, `closed_at`.

For the full Updates API, see the [Updates reference](/reference/accounts/updates/overview).


# Update Lifecycle
Source: https://docs.methodfi.com/guides/updates/lifecycle

The stages of an Update request and how to track them.

## Update Lifecycle

### Status Transitions

```
Created -> Processing -> Completed -> Failed
```

| Status       | Description                                                                      | What to do                                                                                      |
| ------------ | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `pending`    | Request submitted, queued for processing.                                        | Wait for webhook or poll.                                                                       |
| `processing` | Method is actively retrieving data from the source.                              | Wait. Direct Updates typically complete within seconds to minutes depending on the institution. |
| `completed`  | Data is available. The liability-type object (e.g., `credit_card`) is populated. | Read the data, update your local store, display to user.                                        |
| `failed`     | Retrieval was unsuccessful. The `error` object is populated with details.        | See [Handling Failures](/guides/updates/failures).                                              |

### Timing Expectations

* **Snapshot Updates:** Return synchronously in the POST response. No lifecycle to track. The response is immediately `completed` (or `failed`).
* **Direct Updates:** Asynchronous. Typical completion time varies by institution. Most complete within seconds, some may take up to a few minutes. Design your UI to show a loading state and handle the webhook.

### Webhook Events

| Event           | When it fires                                                                                 |
| --------------- | --------------------------------------------------------------------------------------------- |
| `update.create` | An Update has been created (status: `pending`).                                               |
| `update.update` | An Update's status has changed (typically `pending` to `completed` or `pending` to `failed`). |

Subscribe to `update.update` to react when data is ready. The webhook payload includes the path to retrieve the full Update object.

### Idempotency

If you need to retry a failed Update, use [idempotency keys](/reference/idempotency) to avoid creating duplicate requests.


# Updates
Source: https://docs.methodfi.com/guides/updates/overview

How Method keeps account data fresh, snapshot vs direct sources.

## Keeping Account Data Fresh and Accurate

### What an Update Is

An Update is the mechanism through which Method delivers the latest state of a connected account: current balance, payment due date, minimum payment amount, interest rate, credit limit, and other relevant fields depending on the account type. If [Connect](/guides/connect/overview) is how you discover accounts, Updates are how you keep those accounts' data current over time.

The freshness and accuracy of your account data directly impacts the quality of your product experience. A debt repayment app that shows last month's balance feels broken. A payment scheduler that uses stale due dates risks missed payments. Updates are how you ensure your product reflects financial reality, not an outdated snapshot.

### Two Sources of Truth: Snapshot vs. Direct

Updates come from two fundamentally different data sources, and choosing between them is an important product decision:

## Checking Update Availability

Before requesting an Update, check the account's `products` array:

* `update` in `products` means direct Updates are available (real-time data from the institution).

If `update` is in `restricted_products` instead of `products`, direct Updates require additional steps (e.g., account verification). If `update` does not appear, data retrieval isn't currently available for this account.

<Tabs>
  <Tab title="Snapshot">
    Pull data from the user's credit report. Credit reports are compiled by the major bureaus and updated when creditors submit their reporting data, typically on a monthly cycle. Snapshot data is available for the broadest range of accounts, but it's only as fresh as the most recent creditor report.

    | Attribute     | Detail                                                                  |
    | ------------- | ----------------------------------------------------------------------- |
    | **Freshness** | Monthly (credit report cycle)                                           |
    | **Delivery**  | Produced by an `update.snapshot` subscription and delivered via webhook |
    | **Coverage**  | Broadest, works for virtually every account                             |

    **Best for:** Building account overview screens, displaying general balance trends, monitoring credit health over time, showing account summaries where approximate data is acceptable, or when you need data for account types where direct connections aren't available. Snapshot Updates are your reliable baseline. They work for virtually every discovered account and provide a good-enough picture for many use cases.

    Snapshot Updates cannot be created on demand. Subscribe to `update.snapshot` so Method delivers a fresh snapshot whenever the bureau reports new data, then retrieve the most recent snapshot from the list endpoint:

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{"enroll": "update.snapshot"}'

    curl "https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates?source=snapshot" \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```
  </Tab>

  <Tab title="Direct">
    Pull data directly from the financial institution in real time. This means the data reflects the account's current state as of the moment the institution responds, including very recent payments, daily interest accrual, and same-day balance changes. Direct Updates are asynchronous (you submit a request and receive the result via webhook when it completes) and take longer, but the data is significantly more current.

    | Attribute     | Detail                                   |
    | ------------- | ---------------------------------------- |
    | **Freshness** | Real-time (as of institution response)   |
    | **Response**  | Async (webhook delivery)                 |
    | **Coverage**  | Narrower, depends on institution support |

    **Best for:** Confirming a balance before initiating a payment, displaying exact payment due dates or minimum payment amounts, current interest rate or APR information, verifying that a recent payment has posted, or when accuracy is critical to your product's core value proposition.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{"type": "direct"}'
    ```
  </Tab>
</Tabs>

<Note>
  Many products use both: snapshot data as the default display, with direct Updates triggered when the user takes an action that requires current data (like preparing to make a payment).
</Note>

## The Update Flow

<Accordion title="On-demand direct Update walkthrough">
  ### On-Demand (Direct) Update

  **Step 1: Request a direct Update**

  ```bash theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{"type": "direct"}'
  ```

  The response returns immediately with `status: pending`:

  ```json theme={null}
  {
    "id": "upt_NYV5kfjskTTCJ",
    "status": "pending",
    "account_id": "acc_yVf3mkzbhz9tj",
    "source": "direct",
    "type": "credit_card",
    "credit_card": null,
    "error": null,
    "created_at": "2024-03-20T04:43:21.434Z",
    "updated_at": "2024-03-20T04:43:21.655Z"
  }
  ```

  ### Step 2: Wait for completion

  Listen for the `update.update` webhook:

  ```json theme={null}
  {
    "type": "update.update",
    "path": "/accounts/acc_yVf3mkzbhz9tj/updates/upt_NYV5kfjskTTCJ"
  }
  ```

  ### Step 3: Retrieve the completed Update

  ```bash theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates/upt_NYV5kfjskTTCJ \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  The completed Update contains the account's current data:

  ```json theme={null}
  {
    "id": "upt_NYV5kfjskTTCJ",
    "status": "completed",
    "account_id": "acc_yVf3mkzbhz9tj",
    "source": "direct",
    "type": "credit_card",
    "data_as_of": "2024-03-20T04:43:21.434Z",
    "credit_card": {
      "available_credit": 120000,
      "balance": 80000,
      "credit_limit": 200000,
      "interest_rate_percentage_max": 23.5,
      "interest_rate_percentage_min": 12.0,
      "interest_rate_type": "variable",
      "last_payment_amount": 5000,
      "last_payment_date": "2024-04-05",
      "next_payment_due_date": "2024-05-01",
      "next_payment_minimum_amount": 4000,
      "opened_at": "2018-10-30"
    },
    "error": null,
    "created_at": "2024-03-20T04:43:21.434Z",
    "updated_at": "2024-03-20T04:43:21.655Z"
  }
  ```
</Accordion>

## Reading the Update Response

The Update response wraps the account data inside a liability-type object. The key fields:

| Field              | Description                                                                                                                                                             |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source`           | `snapshot` or `direct`, which data source this Update used.                                                                                                             |
| `type`             | The liability type: `credit_card`, `auto_loan`, `student_loans`, `mortgage`, `personal_loan`, etc.                                                                      |
| `data_as_of`       | Timestamp of when this data was current. For direct, this is the moment the institution responded. For snapshot, this is when the creditor last reported to the bureau. |
| `[liability_type]` | The data object (e.g., `credit_card`, `auto_loan`). Contains the balance, rates, payment info, and dates specific to that account type.                                 |
| `status`           | `pending`, `processing`, `completed`, or `failed`. See [Update Lifecycle](/guides/updates/lifecycle).                                                                   |
| `error`            | Populated if the Update failed. See [Handling Failures](/guides/updates/failures).                                                                                      |

<Note>
  **All monetary amounts are in cents.** A `balance` of `80000` means \$800.00. A `last_payment_amount` of `5000` means \$50.00.
</Note>

## Next Steps

<CardGroup>
  <Card title="Update Subscriptions" icon="arrows-rotate" href="/guides/updates/subscriptions">
    Set up automatic data refreshes without manual requests.
  </Card>

  <Card title="Update Lifecycle" icon="arrows-spin" href="/guides/updates/lifecycle">
    Understand the stages of an Update request.
  </Card>

  <Card title="Handling Failures" icon="triangle-exclamation" href="/guides/updates/failures">
    Design resilient UX around failed or stale data.
  </Card>

  <Card title="Updates API Reference" icon="code" href="/reference/accounts/updates/overview">
    Full endpoint documentation, fields, and error codes.
  </Card>
</CardGroup>


# Update Subscriptions
Source: https://docs.methodfi.com/guides/updates/subscriptions

Set-and-forget monitoring to keep account data current.

## What Update Subscriptions Do

For products that need to keep data current without requiring users to manually refresh, Update Subscriptions provide a set-and-forget monitoring capability.

* A direct Update subscription tells Method to periodically pull fresh data from the financial institution and deliver it to you via webhook as it becomes available. The refresh cadence depends on the institution and account type.
* A snapshot-only subscription delivers new data whenever the credit report refreshes (typically monthly), ensuring your baseline data stays current without manual intervention.

Subscriptions are essential for: dashboards and account overview screens that should always show reasonably current data, alerting systems that detect changes (missed payments, balance spikes, rate changes), progress tracking features that show debt paydown over time, and any feature where the user expects data to be fresh without taking action.

The combination of on-demand Updates for user-initiated actions and subscription-based Updates for background freshness gives you a complete data strategy.

## Creating a Subscription

You can set up subscriptions either at Connect time (recommended for new accounts) or individually on existing accounts.

### At Connect Time (Recommended)

Include `subscriptions` in your Connect request to automatically subscribe all discovered accounts:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptions": ["update"]
  }'
```

### On an Existing Account

```bash theme={null}
curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{"enroll": "update"}'
```

## Subscription Types

| Type              | What it does                                                                                                                                                     |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `update`          | Periodically pulls real-time data directly from the financial institution and delivers via webhook. Refresh cadence depends on the institution and account type. |
| `update.snapshot` | Delivers new credit report data whenever the bureau refreshes (typically monthly). Lower cost, broader coverage.                                                 |

<Note>
  Check the account's `available_subscriptions` array before creating a subscription. If `update` isn't listed, direct subscriptions aren't available for that account.
</Note>

### Refresh Cadence

<Note>
  The frequency of updates for direct subscriptions depends on the liability type and the individual account. Credit cards generally update more frequently (every 1 to 3 days), while personal loans and mortgages typically refresh every \~30 days, aligning with billing cycles and account activity. Snapshot subscriptions refresh whenever the credit bureau receives updated data from the creditor, usually on a monthly basis.
</Note>

## Receiving Updates via Webhook

When a subscription triggers a refresh, Method sends an `update.create` webhook when the Update is created, followed by an `update.update` webhook when its status changes (typically to `completed` or `failed`):

```json theme={null}
{
  "type": "update.update",
  "path": "/accounts/acc_yVf3mkzbhz9tj/updates/upt_NYV5kfjskTTCJ"
}
```

Retrieve the Update from the path to get the fresh data. Your application should process these webhooks to update its local data store or cache.

## Managing Subscriptions

* **List active subscriptions:** `GET /accounts/{acc_id}/subscriptions`
* **Delete a subscription:** `DELETE /accounts/{acc_id}/subscriptions/{sub_id}`

Subscriptions remain active until explicitly deleted or the account is disabled/closed.

## When to Use Subscriptions vs On-Demand Updates

| Scenario                                      | Approach                          |
| --------------------------------------------- | --------------------------------- |
| Dashboard showing current balances            | Subscription (background refresh) |
| Pre-payment balance confirmation              | On-demand direct Update           |
| Debt paydown progress tracking                | Subscription                      |
| One-time underwriting check                   | On-demand direct Update           |
| Alerting on missed payments or balance spikes | Subscription                      |


# Getting Started
Source: https://docs.methodfi.com/guides/use-cases/commerce/getting-started

Create an entity, verify identity, and connect credit cards — the foundational 3-step flow for every commerce integration.

Every commerce integration begins the same way: represent your customer, verify their identity, and discover their credit cards. This 3-step flow is the shared foundation for [Wallet Onboarding](/guides/use-cases/commerce/wallet-onboarding), [Preauth Signals](/guides/use-cases/commerce/preauth-signals), and [Wallet Intelligence](/guides/use-cases/commerce/wallet-intelligence).

<Steps>
  <Step title="Create an Entity">
    Every end user maps to an [Entity](/guides/entities/overview) in Method. Create one with the user's full name and phone number, and provide additional identity information such as date of birth, email address, or SSN when available to improve match rates. This is the foundational object that verification, card discovery, and all downstream products attach to.

    ```bash theme={null}
    curl https://production.methodfi.com/entities \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "individual",
        "individual": {
          "first_name": "Emily",
          "last_name": "Park",
          "phone": "+13105550789",
          "email": "emily.park@email.com",
          "dob": "1995-11-08"
        },
        "address": {
          "line1": "789 Sunset Blvd",
          "line2": null,
          "city": "Los Angeles",
          "state": "CA",
          "zip": "90028"
        }
      }'
    ```

    ```json theme={null}
    {
      "id": "ent_BzirqpLEm3BW7",
      "type": "individual",
      "individual": {
        "first_name": "Emily",
        "last_name": "Park",
        "phone": "+13105550789",
        "dob": "1995-11-08",
        "email": "emily.park@email.com",
        "ssn_4": null,
        "ssn": null
      },
      "error": null,
      "address": {
        "line1": "789 Sunset Blvd",
        "line2": null,
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90028"
      },
      "status": "incomplete",
      "verification": {
        "identity": {
          "verified": false,
          "matched": false,
          "latest_verification_session": null,
          "methods": [
            "element",
            "kba"
          ]
        },
        "phone": {
          "verified": false,
          "latest_verification_session": null,
          "methods": [
            "sms",
            "sna",
            "byo_sms"
          ]
        }
      },
      "connect": null,
      "credit_score": null,
      "products": [
        "identity"
      ],
      "restricted_products": [
        "connect",
        "credit_score",
        "attribute"
      ],
      "subscriptions": [],
      "available_subscriptions": [
        "connect",
        "credit_score"
      ],
      "restricted_subscriptions": [],
      "metadata": null,
      "created_at": "2025-12-10T14:22:31.024Z",
      "updated_at": "2025-12-10T14:22:31.024Z"
    }
    ```

    The Entity is created in `incomplete` status. Before you can discover Emily's credit cards, you need to verify her identity.
  </Step>

  <Step title="Verify Identity">
    Method requires phone verification before card discovery. Verify the customer's phone number using either **Method OTP** (Method sends and verifies the one-time passcode) or **Bring Your Own OTP** (you verify the phone number yourself and provide the verification result to Method). The example below initiates a Method-sent SMS verification session, which sends a one-time code to Emily's phone number on record.

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/verification_sessions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "sms",
        "sms": {}
      }'
    ```

    ```json theme={null}
    {
      "id": "evf_nKLp7WzQdR4mF",
      "entity_id": "ent_BzirqpLEm3BW7",
      "status": "in_progress",
      "type": "phone",
      "method": "sms",
      "sms": {},
      "error": null,
      "created_at": "2025-12-10T14:23:12.271Z",
      "updated_at": "2025-12-10T14:23:12.271Z"
    }
    ```

    After Emily receives and submits the SMS code, the verification session transitions to `verified`. Once both phone and identity verification are complete, the Entity status updates to `active` and Connect becomes available.

    <Note>
      For a complete overview of all verification methods (SMS, SNA, BYO-SMS, KBA), see the [Identity Verification](/guides/identity-verification/overview) guide.
    </Note>
  </Step>

  <Step title="Connect Credit Cards">
    With verification complete, call Connect to discover Emily's credit cards via a soft-pull credit report. This has no impact on the user's credit score.

    For commerce use cases, the key discovery is **credit cards**: these are the accounts you'll use for wallet onboarding, preauth signals, and wallet intelligence.

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    ```json theme={null}
    {
      "id": "cxn_7hTmRvXkYpN3w",
      "entity_id": "ent_BzirqpLEm3BW7",
      "status": "completed",
      "accounts": [
        "acc_LxwEqNicr66yP",
        "acc_4m9amk4KFiaQX",
        "acc_XtKTpHLGhD9Qn",
        "acc_GAzrD99cUqGEN"
      ],
      "requested_products": [],
      "requested_subscriptions": [],
      "error": null,
      "created_at": "2025-12-10T14:24:45.645Z",
      "updated_at": "2025-12-10T14:24:45.645Z"
    }
    ```

    Method discovered 4 credit card accounts for Emily:

    | Account ID          | Card                            |
    | ------------------- | ------------------------------- |
    | `acc_LxwEqNicr66yP` | Chase Sapphire Preferred (Visa) |
    | `acc_4m9amk4KFiaQX` | Amex Gold (Amex)                |
    | `acc_XtKTpHLGhD9Qn` | Citi Double Cash (Mastercard)   |
    | `acc_GAzrD99cUqGEN` | Capital One Venture X (Visa)    |

    These accounts are now ready for every Commerce use case.
  </Step>
</Steps>

## What's Next

<CardGroup>
  <Card title="Wallet Onboarding" icon="wallet" href="/guides/use-cases/commerce/wallet-onboarding">
    Enrich cards with brand art and retrieve payment credentials to render a complete wallet.
  </Card>

  <Card title="Preauth Signals" icon="signal" href="/guides/use-cases/commerce/preauth-signals">
    Evaluate payment readiness before authorization and optimize payment retries.
  </Card>

  <Card title="Wallet Intelligence" icon="lightbulb" href="/guides/use-cases/commerce/wallet-intelligence">
    Retrieve wallet-level insights to personalize customer experiences.
  </Card>
</CardGroup>


# Commerce
Source: https://docs.methodfi.com/guides/use-cases/commerce/overview

Connect customers' credit cards, reduce failed payments, and personalize customer experiences with Method's Commerce APIs.

## What This Section Covers

Learn how to use Method's Commerce APIs to:

* **Connect every credit card** a customer owns in a single flow.
* **Evaluate payment readiness** before authorizing a transaction.
* **Retry failed payments at the optimal time** to improve recovery.
* **Personalize customer experiences** using wallet intelligence.

Whether you're building a wallet, improving payment success, or personalizing customer experiences, every Commerce integration follows the same core workflow.

```mermaid theme={null}
flowchart TD
    A[Create Entity] --> B[Verify Identity]
    B --> C[Connect Credit Cards]
    C --> D[Wallet Onboarding]
    C --> E[Preauth Signals]
    C --> F[Wallet Intelligence]
    style C fill:#00B29D,color:#fff
```

## Commerce Use Cases

| Use case                                                                  | Core endpoints                                  | Use when you want to                                                                                                           |
| ------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| [**Wallet Onboarding**](/guides/use-cases/commerce/wallet-onboarding)     | Entity-Connect, Card Brand, Payment Instruments | Reduce onboarding friction by letting customers connect all their credit cards in one flow                                     |
| [**Preauth Signals**](/guides/use-cases/commerce/preauth-signals)         | Entity-Connect, Preauth Signals                 | Increase payment success by evaluating payment readiness before authorization and retrying failed payments at the optimal time |
| [**Wallet Intelligence**](/guides/use-cases/commerce/wallet-intelligence) | Entity-Connect, Attributes                      | Personalize offers and product experiences based on customers' credit cards                                                    |

## Two Integration Paths

<Tabs>
  <Tab title="API-Only">
    Integrate directly with Method's APIs for entity creation, identity verification, Connect, and all downstream card operations. You build the user-facing flow and have full control over the UX.

    PCI compliance is not required: by default, tokenization returns network tokens that don't expose raw card credentials.
  </Tab>

  <Tab title="Embedded UI (Opal)">
    Use [Opal Card Connect](/opal/card_connect/overview) as a drop-in UI for identity verification and card discovery. Opal handles the user-facing flow while you use the API for card brand enrichment, payment instruments, and wallet attributes.
  </Tab>
</Tabs>

## Get Started

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="/guides/use-cases/commerce/getting-started">
    The 3-step setup: create an entity, verify identity, and connect credit cards.
  </Card>

  <Card title="Wallet Onboarding" icon="wallet" href="/guides/use-cases/commerce/wallet-onboarding">
    Connect every credit card without manual entry, then enrich and tokenize for checkout.
  </Card>

  <Card title="Preauth Signals" icon="signal" href="/guides/use-cases/commerce/preauth-signals">
    Evaluate payment readiness before authorization and optimize payment retries.
  </Card>

  <Card title="Wallet Intelligence" icon="lightbulb" href="/guides/use-cases/commerce/wallet-intelligence">
    Retrieve wallet-level insights to personalize customer experiences.
  </Card>
</CardGroup>


# Preauth Signals
Source: https://docs.methodfi.com/guides/use-cases/commerce/preauth-signals

Evaluate payment readiness before authorization and retry failed payments at the optimal time.

Evaluate payment readiness before authorization and optimize payment retries. After your customer has connected their credit cards, evaluate each card before attempting a payment. Method returns behavioral signals used to estimate payment readiness and recommends when to retry failed payments.

<Note>
  **Public preview.** Preauth Signals is in public preview. Contact your Method CSM to request access.
</Note>

## Prerequisites

Before using Preauth Signals, complete the [Getting Started](/guides/use-cases/commerce/getting-started) flow:

* Entity created
* Identity verified
* Credit cards connected

## Why Use It?

* **Reduce involuntary churn:** Identify the best time to retry failed payments.
* **Increase authorization rates:** Know a payment's likelihood of success before sending it to the network.

## How It Works

Before attempting a payment, create a Preauth Signals assessment for the card, then retrieve the result to decide whether to authorize now or retry later.

```mermaid theme={null}
flowchart TD
    A["Create Preauth Signals<br/>POST /preauth"] --> B["Retrieve Preauth Signals<br/>GET /preauth/{preauth_id}"]
    B --> C[Authorize now]
    B --> D[Retry later]
    style C fill:#00B29D,color:#fff
```

<Steps>
  <Step title="Create Preauth Signals">
    Create a Preauth Signals assessment with `POST /preauth`. Provide either an authenticated Method `account_id` or a `card` object to identify the payment method. You can also include `purchase` context, such as the transaction amount or merchant category code (MCC), to improve the assessment.

    ```bash theme={null}
    curl https://production.methodfi.com/preauth \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "account_id": "acc_4m9amk4KFiaQX",
        "purchase": {
          "amount": 9999,
          "mcc": "4511"
        }
      }'
    ```
  </Step>

  <Step title="Retrieve Preauth Signals">
    Retrieve the completed assessment with `GET /preauth/{preauth_id}` to determine whether to authorize the payment immediately or retry later.

    ```bash theme={null}
    curl https://production.methodfi.com/preauth/preauth_qV7kRaFm4JNxw \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    ```json theme={null}
    {
      "id": "preauth_qV7kRaFm4JNxw",
      "account_id": "acc_4m9amk4KFiaQX",
      "status": "completed",
      "verified_ownership": "match",
      "card_standing": "open",
      "success_likelihood": 0.87,
      "optimal_retry_date": "2026-06-02",
      "error": null,
      "metadata": null,
      "created_at": "2026-05-28T14:00:00.000Z",
      "updated_at": "2026-05-28T14:00:00.180Z"
    }
    ```

    | Field                | Description                                               |
    | -------------------- | --------------------------------------------------------- |
    | `success_likelihood` | Estimated likelihood that the payment will authorize.     |
    | `optimal_retry_date` | Recommended retry date if the payment does not authorize. |

    Use `success_likelihood` to choose the best card for a payment, and `optimal_retry_date` to schedule retries for failed payments.
  </Step>
</Steps>

## What's Next

<CardGroup>
  <Card title="Wallet Intelligence" icon="lightbulb" href="/guides/use-cases/commerce/wallet-intelligence">
    Retrieve wallet-level insights to personalize customer experiences.
  </Card>

  <Card title="Preauth Signals API Reference" icon="signal" href="/reference/preauth/overview">
    Full API documentation for Preauth Signals.
  </Card>
</CardGroup>


# Wallet Intelligence
Source: https://docs.methodfi.com/guides/use-cases/commerce/wallet-intelligence

Retrieve wallet-level behavioral attributes to power recommendations, segmentation, and personalized product experiences.

Retrieve wallet-level insights to personalize customer experiences. After connecting a customer's credit cards, retrieve wallet-level behavioral attributes to power recommendations, segmentation, and personalized product experiences.

## Prerequisites

Before using Wallet Intelligence, complete the [Getting Started](/guides/use-cases/commerce/getting-started) flow:

* Entity created
* Identity verified
* Credit cards connected

## Why Use It?

* **Reach the right audience:** Identify the customers most likely to benefit from every offer.
* **Power partner offers:** Deliver issuer and partner offers only to eligible customers.
* **Design better experiences:** Understand wallet trends and customer behavior to inform product decisions.
* **Complete customer profiles:** Enrich the customer data you already have.

## How It Works

Retrieve the attributes of the customer's wallet with a single request: `POST /entities/{ent_id}/attributes`. Method returns behavioral attributes computed across every connected credit card in the customer's wallet, including:

* Overall utilization
* Credit card utilization
* Usage patterns
* Payment behavior
* Balance trends

```bash theme={null}
curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/attributes \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

This endpoint is asynchronous. The initial response returns `status: in_progress`. Retrieve the completed attributes by subscribing to the `entity_attribute.create` webhook or polling the [retrieve endpoint](/reference/entities/attributes/retrieve).

Below is an example of a completed response:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "attr_dADraNgLBrhgL",
    "entity_id": "ent_BzirqpLEm3BW7",
    "status": "completed",
    "attributes": {
      "usage_pattern":           { "value": "transactor", "error": null, "metadata": null },
      "credit_card_utilization": { "value": 11.96, "error": null, "metadata": null },
      "overall_utilization":     { "value": 18.4, "error": null, "metadata": null }
    },
    "error": null,
    "created_at": "2026-04-09T17:02:47.910Z",
    "updated_at": "2026-04-09T17:04:35.220Z"
  }
}
```

Each attribute returns `{ value, error }`. When data is insufficient (for example, not enough history for a 60-day delta), `value` is `null` and `error` is populated with details.

Use these attributes to build better experiences, personalize offers, segment customers, and improve targeting.

## What's Next

<CardGroup>
  <Card title="Attributes API Reference" icon="chart-line" href="/reference/entities/attributes/overview">
    Full API documentation for Entity Attributes.
  </Card>

  <Card title="Wallet Onboarding" icon="wallet" href="/guides/use-cases/commerce/wallet-onboarding">
    Connect every credit card without manual entry.
  </Card>
</CardGroup>


# Wallet Onboarding
Source: https://docs.methodfi.com/guides/use-cases/commerce/wallet-onboarding

Connect every credit card a customer owns without manual entry, then enrich and tokenize the cards to render a complete wallet.

Connect every credit card without manual entry. Using a customer's name and phone number, Method discovers the credit cards they own, verifies ownership, and returns the metadata needed to render a complete wallet.

## Why Use It?

* **Faster onboarding:** Connect every credit card in one simple and seamless flow.
* **Frictionless checkout:** Let customers pay instantly with any of their credit cards, with no manual entry.
* **Rewards activation:** Enable customers to connect all their credit cards and start earning rewards across every eligible purchase.
* **Payment resilience:** Keep multiple credit cards on file to automatically recover failed payments and reduce churn.

## How It Works

```mermaid theme={null}
flowchart TD
    A["Create Entity<br/>POST /entities"] --> B["Verify Identity<br/>POST /verification_sessions"]
    B --> C["Discover Credit Cards<br/>POST /connect"]
    C --> D["Enrich Cards<br/>POST /card_brands"]
    D --> E["Retrieve Payment Cards<br/>POST /payment_instruments"]
    E --> F[Complete Wallet]
    style F fill:#00B29D,color:#fff
```

<Steps>
  <Step title="Create an Entity">
    Create an [Entity](/guides/entities/overview) to represent your customer. Include their full name and phone number, and provide additional identity information such as date of birth, email address, or SSN when available to improve match rates.
  </Step>

  <Step title="Verify the Customer's Identity">
    Verify the customer's phone number using either **Method OTP** (Method sends and verifies the one-time passcode) or **Bring Your Own OTP** (you verify the phone number yourself and provide the verification result to Method). See the [Identity Verification](/guides/identity-verification/overview) guide for all supported methods.
  </Step>

  <Step title="Discover the Customer's Credit Cards">
    Call [Connect](/guides/connect/overview) to discover the credit card accounts your customer holds via a soft-pull credit report, with no impact on their credit score.

    <Note>
      Steps 1-3 are the same foundational flow used by every Commerce use case. See [Getting Started](/guides/use-cases/commerce/getting-started) for full request and response examples.
    </Note>
  </Step>

  <Step title="Enrich the Discovered Cards">
    For each account returned by Connect, call [Card Brand](/guides/additional-products/card-brand) to retrieve enriched card metadata, including the issuer, card network, card product, card artwork, and rewards program. Use this metadata to render your customer's wallet with recognizable card visuals.

    Here's a card brand request for Emily's Chase Sapphire Preferred (`acc_LxwEqNicr66yP`):

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_LxwEqNicr66yP/card_brands \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    ```json theme={null}
    {
      "id": "cbrd_Accm7P6t6mYQP",
      "account_id": "acc_LxwEqNicr66yP",
      "brands": [
        {
          "id": "pdt_27_brd_1",
          "card_product_id": "pdt_27",
          "description": "Chase Sapphire Preferred",
          "name": "Chase Sapphire Preferred",
          "issuer": "Chase",
          "network": "visa",
          "network_tier": "signature",
          "type": "specific",
          "url": "https://static.methodfi.com/card_brands/7d2f8a1bc3e5f094a6d831e5c7b29f04.png"
        }
      ],
      "status": "completed",
      "source": "method",
      "error": null,
      "created_at": "2025-12-10T14:30:12.139Z",
      "updated_at": "2025-12-10T14:30:12.139Z"
    }
    ```

    The `brands` array contains the card product details. Use `name` for display, `url` for the card art image, `issuer` for the bank name, and `network` / `network_tier` for routing decisions.

    <Note>
      Card Brand is an asynchronous operation. The response above shows a completed request; in practice, subscribe to the `card_brand.completed` webhook to know when brand data is ready.
    </Note>
  </Step>

  <Step title="Retrieve Available Payment Cards">
    For each account returned by Connect, create a [Payment Instrument](/reference/accounts/payment-instruments/overview) to retrieve the card credentials required for checkout.

    Request a `network_token` Payment Instrument to receive a network-provisioned token instead of the raw card number. No raw card credentials are exposed to your systems, so you don't need PCI compliance, and network tokens typically yield better authorization rates.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_GAzrD99cUqGEN/payment_instruments \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "network_token"
      }'
    ```

    If your processor requires raw card data, request a `card` Payment Instrument instead to receive the full credentials: number, expiration date, CVV, and billing zip code. This approach exposes PAN data to your systems and requires PCI compliance.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_GAzrD99cUqGEN/payment_instruments \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "card"
      }'
    ```

    ```json theme={null}
    {
      "success": true,
      "data": {
        "id": "pmt_inst_pd788hPVhLT37",
        "account_id": "acc_GAzrD99cUqGEN",
        "type": "card",
        "card": {
          "number": "4000120000001154",
          "exp_month": "09",
          "exp_year": "2028",
          "cvv": "878",
          "billing_zip_code": "90028"
        },
        "network_token": null,
        "inbound_achwire_payment": null,
        "chargeable": true,
        "status": "completed",
        "error": null,
        "created_at": "2025-12-10T14:35:22.039Z",
        "updated_at": "2025-12-10T14:35:22.039Z"
      },
      "message": null
    }
    ```

    <Warning>
      Payment Instruments is a gated product that requires approval. Contact your Method representative to enable access.
    </Warning>
  </Step>
</Steps>

<Note>
  **Alternative path:** If you don't need complete control over the onboarding experience, [Opal](/opal/overview) provides an embedded flow that handles identity verification and card discovery for you.
</Note>

## What's Next

<CardGroup>
  <Card title="Preauth Signals" icon="signal" href="/guides/use-cases/commerce/preauth-signals">
    Evaluate payment readiness before authorizing a transaction.
  </Card>

  <Card title="Card Brand API Reference" icon="credit-card" href="/reference/accounts/card-brands/overview">
    Full API documentation for Card Brand.
  </Card>

  <Card title="Payment Instruments API Reference" icon="key" href="/reference/accounts/payment-instruments/overview">
    Full API documentation for Payment Instruments.
  </Card>
</CardGroup>


# Mortgage & HELOC
Source: https://docs.methodfi.com/guides/use-cases/lending/mortgage-heloc

Top-of-funnel qualification through portfolio targeting for secured-lending teams.

*Top-of-funnel qualification through portfolio targeting for secured-lending teams.*

Pull a borrower's full liability picture before pre-approval, size HELOC and refi offers against real-time balances and APRs, and continuously surface existing customers who are in the market for a HELOC or new mortgage. From nothing more than a name and phone, Method discovers every liability a borrower holds (mortgages, HELOCs, credit cards, auto, student, and personal loans), pulls current balances, APRs, and payment behavior directly from each financial institution, and keeps that picture refreshed after the borrower is in the book. The same data fabric powers two motions: origination (pre-qualification and HELOC/refi sizing) and portfolio intelligence (continuous monitoring to surface HELOC- and mortgage-ready customers before they shop elsewhere).

## How it works

Create the borrower Entity, verify them, run Connect to discover their liabilities, then subscribe to the v2 attribute set for a continuous, real-time view. All examples use `Method-Version: 2026-03-30`. Monetary values are in **cents** (`1420000` = \$14,200.00); utilization is a percentage (`37.4` = 37.4%); deltas are percentage points.

<Steps>
  <Step title="Create the Entity">
    `POST /entities`. You only need `first_name`, `last_name`, and `phone`. An Entity can be created minimally and enriched later; passing `dob` and `ssn_4` when you have them measurably improves match rates during account discovery, so include them in production where available. The Entity returns `status: "incomplete"` with `connect`, `credit_score`, and `attribute` in `restricted_products` until verification completes.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{
          "type": "individual",
          "individual": {
            "first_name": "Maya",
            "last_name": "Chen",
            "phone": "+13105550147"
          }
        }'
      ```

      ```json theme={null}
      {
        "id": "ent_BzirqpLEm3BW7",
        "type": "individual",
        "individual": {
          "first_name": "Maya",
          "last_name": "Chen",
          "phone": "+13105550147"
        },
        "status": "incomplete",
        "products": ["identity"],
        "restricted_products": ["connect", "credit_score", "attribute"],
        "available_subscriptions": ["connect", "credit_score"]
      }
      ```
    </Expandable>
  </Step>

  <Step title="Verify the borrower (BYO SMS + BYO KYC)">
    Verification must complete before Connect, credit, and attribute products unlock. The lending flows in these guides use BYO SMS and BYO KYC, which let you assert results you already captured in your own onboarding. Both require your team to be pre-authorized, so contact your Method CSM to enable them. For other verification methods, see [Verification Methods](/guides/identity-verification/methods). Once both sessions complete, the Entity moves to `status: "active"` and `connect`, `credit_score`, and `attribute` move from `restricted_products` into `products`. For the full walkthrough, see the [Getting Started](/guides/use-cases/lending/getting-started) guide.

    <Expandable title="phone and identity requests">
      Verify the phone with BYO SMS, passing the ISO 8601 timestamp of when you verified the number:

      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/verification_sessions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "type": "phone", "method": "byo_sms", "byo_sms": { "timestamp": "2026-03-30T12:00:00.000Z" } }'
      ```

      Then assert identity with BYO KYC (you're confirming your external KYC process passed for this borrower):

      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/verification_sessions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "type": "identity", "method": "byo_kyc", "byo_kyc": {} }'
      ```
    </Expandable>
  </Step>

  <Step title="Run Connect">
    `POST /entities/{ent_id}/connect`. Connect performs a soft credit pull (no score impact) and returns the account IDs Method created for each liability. The first Connect returns all liability accounts, both active and closed; subsequent calls return only newly discovered accounts.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/connect \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "cxn_4ewMmBbjYDMR4",
        "entity_id": "ent_BzirqpLEm3BW7",
        "status": "completed",
        "accounts": [
          "acc_RGACQH7XdfYhC",
          "acc_TmGPLxkz7Nrh6",
          "acc_WqNhMRNVZjbKg",
          "acc_YXDrjADGjC76U"
        ],
        "error": null
      }
      ```
    </Expandable>
  </Step>

  <Step title="List the discovered accounts">
    `GET /accounts`. Filter to `type=liability` and `status=active` to work with live debt only. Narrow with `liability.type` (e.g. `mortgage`, `credit_card`) to isolate the secured-debt picture that matters for a HELOC decision. For decision-time accuracy, pull a fresh `POST /accounts/{acc_id}/updates` on the accounts that drive the decision (balances on revolving and mortgage debt shift daily).

    <Expandable title="request & response">
      ```bash theme={null}
      curl "https://production.methodfi.com/accounts?holder_id=ent_BzirqpLEm3BW7&type=liability&status=active" \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "data": [
          {
            "id": "acc_RGACQH7XdfYhC",
            "holder_id": "ent_BzirqpLEm3BW7",
            "status": "active",
            "type": "liability",
            "liability": {
              "mch_id": "mch_300012",
              "mask": "8842",
              "ownership": "primary",
              "type": "mortgage",
              "name": "Rocket Mortgage Home Loan"
            },
            "products": ["balance", "update"],
            "restricted_products": ["attribute", "sensitive"]
          },
          {
            "id": "acc_WqNhMRNVZjbKg",
            "holder_id": "ent_BzirqpLEm3BW7",
            "status": "active",
            "type": "liability",
            "liability": {
              "mch_id": "mch_302086",
              "mask": "1580",
              "ownership": "primary",
              "type": "credit_card",
              "name": "Chase Sapphire Reserve Credit Card"
            },
            "products": ["balance", "update", "card_brand"],
            "restricted_products": ["attribute", "sensitive"]
          }
        ]
      }
      ```
    </Expandable>
  </Step>

  <Step title="Enroll the entity in the attribute subscription">
    `POST /entities/{ent_id}/subscriptions` with `enroll: attribute`. Method computes credit-health attributes (utilization, balances, APRs, trends, payment behavior, delinquency flags) at both the entity level and the account level. Pass the `portfolio_intelligence` bundle to onboard the full PI attribute set in one call, plus any HELOC/mortgage-specific attributes you want explicitly. Once enrolled, every account on the entity is eligible for attribute generation; you do not enroll accounts individually. Portfolio Intelligence (`portfolio_intelligence`) is separately enabled, so ask your Method CSM to turn it on first.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{
          "enroll": "attribute",
          "payload": {
            "attributes": {
              "bundles": ["portfolio_intelligence"],
              "requested_attributes": [
                "mortgage_balance_total",
                "heloc_balance_total",
                "heloc_utilization",
                "overall_utilization",
                "revolving_credit_card_balance_total",
                "weighted_average_apr_credit_card",
                "delinquency_flag_credit_cards"
              ]
            }
          }
        }'
      ```

      ```json theme={null}
      {
        "id": "sub_Tm8qNnLx5RjWk",
        "name": "attribute",
        "status": "active",
        "latest_request_id": null,
        "created_at": "2026-04-09T17:00:12.218Z",
        "updated_at": "2026-04-09T17:00:12.218Z"
      }
      ```
    </Expandable>

    Once `status` is `active`, Method begins pulling directly from the borrower's institutions and attribute generation starts.
  </Step>

  <Step title="(Optional) Enroll accounts in Update subscriptions">
    `POST /accounts/{acc_id}/subscriptions` with `enroll: update`. Adds a near-real-time balance/payment event stream on a specific account, on top of the entity attribute layer, useful when you want a webhook the moment a tracked mortgage or card balance moves.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_WqNhMRNVZjbKg/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "update" }'
      ```
    </Expandable>
  </Step>

  <Step title="Pull the entity attribute set">
    `POST /entities/{ent_id}/attributes`. Asynchronous: it returns immediately with `status: "in_progress"` and `attributes: null`, then fires an `entity_attribute.create` webhook when computation completes. Retrieve the finished object via `GET /entities/{ent_id}/attributes/{attr_id}`. Attributes that can't be computed (e.g. a trend with insufficient history, or HELOC attributes for a borrower with no HELOC) return `value: null` with an `error` object rather than failing the whole response.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/attributes \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "attr_Qk9nPmRw3LjTx",
        "entity_id": "ent_BzirqpLEm3BW7",
        "status": "completed",
        "attributes": {
          "mortgage_balance_total":               { "value": 31200000, "error": null, "metadata": null },
          "heloc_balance_total":                  { "value": 0, "error": null, "metadata": null },
          "heloc_utilization":                    { "value": null, "error": { "type": "ENTITY_ATTRIBUTE_INSUFFICIENT_DATA", "code": 27001, "message": "Insufficient data to compute this entity attribute." }, "metadata": null },
          "overall_utilization":                  { "value": 41.8, "error": null, "metadata": null },
          "revolving_credit_card_balance_total":  { "value": 1840000, "error": null, "metadata": null },
          "credit_card_utilization":              { "value": 63.0, "error": null, "metadata": null },
          "weighted_average_apr_credit_card":     { "value": 23.4, "error": null, "metadata": null },
          "usage_pattern":                        { "value": "revolver", "error": null, "metadata": null },
          "payment_to_minimum_ratio_avg_credit_cards": { "value": 1.6, "error": null, "metadata": null },
          "delinquency_flag_credit_cards":        { "value": "on_time", "error": null, "metadata": null }
        }
      }
      ```
    </Expandable>
  </Step>
</Steps>

**Webhooks.** A PI-enrolled entity fires `entity_attribute.create` on the first computation and `entity_attribute.update` thereafter whenever new values are surfaced; account-level signals fire `account_attribute.create` / `account_attribute.update`. Subscribe to these to drive monitoring workflows without polling.

A primer on the full attribute set, entity-vs-account availability, and webhook payloads lives in the [Portfolio Intelligence guide](/guides/use-cases/lending/portfolio-monitoring).

## Pre-qualification

Run the create-and-Connect flow at intake, then read the entity attribute set to qualify before the borrower invests in a full application. Because the data comes straight from each institution rather than a weeks-old bureau snapshot, the pre-approval decision rests on what the borrower actually owes today.

*Key attributes:* `overall_utilization`, `credit_card_utilization`, `usage_pattern`, `delinquency_flag_credit_cards`, `payment_to_minimum_ratio_avg_credit_cards`.

## HELOC expansion

For a HELOC offer, the secured picture and the borrower's revolving leverage drive both eligibility and sizing. Method surfaces the existing mortgage and HELOC balances directly, alongside the unsecured debt that informs capacity.

*Key attributes:* `mortgage_balance_total`, `heloc_balance_total`, `heloc_utilization`, `overall_utilization`, `revolving_credit_card_balance_total`.

## Debt consolidation / refi

A borrower carrying high-APR revolving balances is a consolidation candidate. Method shows the blended rate they're actually paying, so the savings you quote are priced against real debt, not an estimated rate band. The example borrower above carries \$18,400 in revolving balances at a 23.4% blended APR, a clear consolidation target a HELOC or refi will retire. When the borrower accepts, Direct Pay (the Payments API) routes the verified payoff straight to the incumbent creditor.

*Key attributes:* `weighted_average_apr_credit_card`, `revolving_credit_card_balance_total`, `credit_card_utilization`, `personal_loan_monthly_installments_estimate`.

## Portfolio Intelligence: HELOC / mortgage targeting

Enroll existing customers in the attribute subscription and let the continuous attribute stream surface who is in the market. Watch for the signals that indicate HELOC or new-mortgage intent (sustained revolving paydown that frees capacity, rising high-APR balances that a HELOC will consolidate, or an improving overall profile) and trigger a targeted offer before they shop a competitor.

*Key attributes:* `revolving_credit_card_balance_change_30d/60d/90d`, `overall_utilization_delta_90d`, `overall_utilization_trend_90d`, `weighted_average_apr_credit_card`, `mortgage_balance_total`.


# Portfolio Intelligence: Grow
Source: https://docs.methodfi.com/guides/use-cases/lending/portfolio-monitoring-grow

Post-origination monitoring for refi, 2nd loan, CLI, and cross-sell.

*Post-origination monitoring for refi, 2nd loan, CLI, cross-sell.*

After a loan funds, most lenders lose visibility into their borrowers. Method's Portfolio Intelligence monitors the full liability picture continuously after origination, surfacing 91 real-time signals across 8 categories, so growth, retention, risk, and servicing teams reach their best borrowers before competitors do.

## How it works

Funded loans are enrolled in Attributes v2 + Update + Credit Score Subscriptions, Method continuously monitors the borrower's full liability picture across 15,000+ institutions, improvement signals trigger CLI / 2nd-loan / refi workflows, and Direct Pay retires competitor balances when the borrower accepts.

<Steps>
  <Step title="Enroll the entity in the Attributes v2 subscription">
    `POST /entities/{ent_id}/subscriptions` with `enroll: attribute`. Pass the `portfolio_intelligence` bundle to onboard the full PI attribute set in one call. Every account on the entity then becomes eligible for attribute generation, and Method pushes recomputed values as the underlying data changes. Portfolio Intelligence (`portfolio_intelligence`) is a separately enabled product, so ask your Method CSM to turn it on first.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "attribute", "payload": { "attributes": { "bundles": ["portfolio_intelligence"] } } }'
      ```
    </Expandable>
  </Step>

  <Step title="Enroll the borrower's accounts in Update Subscriptions">
    `POST /accounts/{acc_id}/subscriptions` with `enroll: update`.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_TmGPLxkz7Nrh6/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "update" }'
      ```
    </Expandable>
  </Step>

  <Step title="Enroll the entity in Credit Score Subscriptions">
    `POST /entities/{ent_id}/subscriptions` with `enroll: credit_score`.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "credit_score" }'
      ```
    </Expandable>
  </Step>
</Steps>

For Portfolio Intelligence: Grow workflows, the readiness, offer-targeting, consolidation, and LTV sub-flows below pull from this same v2 attribute set.

## Identify readiness

Score every borrower against their live liability picture: who's revolving, who's approaching payoff, who has a balance worth consolidating. Bureau snapshots are already weeks old at the moment of intent.

*Key v2 attributes:* `usage_pattern`, `overall_utilization`, `credit_card_utilization`, `revolving_credit_card_balance_total`, `revolving_credit_card_balance_change_30d`.

## Target with the right offer

Method surfaces APR ranges and live balances. Offers are priced against the rate the borrower is actually paying, not a bureau-estimated rate band.

*Key v2 attributes:* `weighted_average_apr_credit_card`, `revolving_credit_card_balance_total`, `next_payment_minimum_total_credit_cards`, `credit_limit_total`.

## Execute the consolidation

When the borrower accepts, Direct Pay routes a verified payoff directly to the incumbent issuer. Consolidated payoffs cut delinquency up to \~50% vs. cash-to-borrower disbursement.

*Driven by Direct Pay (Payments API) rather than the Attributes endpoint. See the [Direct Pay](/guides/use-cases/lending/debt-consolidation) use case for the payment-initiation flow.*

## Post-origination LTV: 2nd loan and CLI

\~33% of personal-loan customers take a second loan within 6 to 12 months. Continuous monitoring surfaces who's a renewal candidate, and detects when a borrower's external profile improves enough to support a proactive CLI before they shop competitors.

*Key v2 attributes:* `revolving_credit_card_balance_change_90d`, `overall_utilization_delta_90d`, `overall_utilization_trend_90d`, `revolving_credit_card_utilization_delta_90d`, `revolving_credit_card_utilization_trend_90d`.


# Portfolio Intelligence: Protect
Source: https://docs.methodfi.com/guides/use-cases/lending/portfolio-monitoring-protect

Early warning, line decreases, and real-time delinquency and autopay signals.

*Early warning, line decreases, real-time delinquency and autopay signals.*

Bureau won't tell you a borrower just turned off autopay, opened a balance transfer card, or stacked debt, until it's already on your balance sheet. Method catches all three weeks earlier, with direct evidence from the FI. Same data fabric as PI: Grow, applied to loss prevention.

## How it works

Same subscription setup as PI: Grow, with the attribute bundle tuned to distress signals. Distress events (autopay off, DPD progression, balance stacking) fire as webhooks; risk and servicing teams trigger early intervention.

<Steps>
  <Step title="Enroll funded-loan accounts in Update Subscriptions">
    Enroll with `enroll: update` (`POST /accounts/{acc_id}/subscriptions`).

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_TmGPLxkz7Nrh6/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "update" }'
      ```
    </Expandable>
  </Step>

  <Step title="Pull the v2 attribute set tuned for distress signals">
    `POST /entities/{ent_id}/attributes`. Method computes the full set automatically. Consume the delinquency flags, the balance-change deltas, and the payment-to-minimum ratio for distress detection. For continuous monitoring, enroll in the Entity Attributes subscription (`entity_attribute.create` webhook); Method pushes recomputed attributes as the underlying account data changes.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/attributes \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "attr_dADraNgLBrhgL",
        "entity_id": "ent_qKNBB68bfHGNA",
        "status": "completed",
        "attributes": {
          "delinquency_flag_credit_cards":              { "value": "overdue", "error": null, "metadata": null },
          "any_delinquent_flag":                        { "value": true, "error": null, "metadata": null },
          "serious_delinquent_flag":                    { "value": false, "error": null, "metadata": null },
          "delinquency_worst_dpd_bucket":               { "value": "30_dpd", "error": null, "metadata": null },
          "delinquency_accounts_count":                 { "value": 2, "error": null, "metadata": null },
          "delinquent_balance_total":                   { "value": 41200, "error": null, "metadata": { "partial": true, "accounts_with_data": 1, "accounts_total": 2 } },
          "delinquency_progression_flag":               { "value": true, "error": null, "metadata": null },
          "delinquency_recently_cured_flag":            { "value": false, "error": null, "metadata": null },
          "delinquent_outcome":                         { "value": "current", "error": null, "metadata": null },
          "payment_to_minimum_ratio_avg_credit_cards":  { "value": 0.85, "error": null, "metadata": null },
          "revolving_credit_card_balance_change_30d":   { "value": 381700, "error": null, "metadata": null },
          "revolving_credit_card_utilization_delta_30d":{ "value": 8.4, "error": null, "metadata": null },
          "revolving_credit_card_utilization_trend_30d":{ "value": "increasing", "error": null, "metadata": null },
          "credit_card_utilization":                    { "value": 74.2, "error": null, "metadata": null },
          "installment_balance_change_30d":             { "value": 250000, "error": null, "metadata": null }
        }
      }
      ```
    </Expandable>
  </Step>
</Steps>

## Early delinquency detection

Flag delinquency progression weeks before bureau refresh; act on early-cure or workout opportunities while the borrower still has capacity.

*Key v2 attributes:* `delinquency_flag_credit_cards`, `any_delinquent_flag`, `serious_delinquent_flag`, `delinquency_worst_dpd_bucket`, `delinquency_progression_flag`, `delinquent_outcome`, `delinquency_recently_cured_flag`, `delinquency_accounts_count`, `delinquent_balance_total`, `payment_to_minimum_ratio_avg_credit_cards`, `next_payment_minimum_total_credit_cards`.

## Payment-behavior leading indicators

A declining payment-to-minimum ratio flags borrowers before the first missed payment. (Autopay-specific signals such as autopay disablement detection and autopay-enabled counts surface through Account Updates and account-level attributes rather than entity attributes today.)

*Key v2 attributes:* `payment_to_minimum_ratio_avg_credit_cards`.

## Line decreases on stress signals

Detect borrower distress: utilization spikes, balance stacking, rising aggregate utilization. Act on lines before losses materialize.

*Key v2 attributes:* `revolving_credit_card_balance_change_30d`, `revolving_credit_card_utilization_delta_30d`, `revolving_credit_card_utilization_trend_30d`, `credit_card_utilization`, `overall_utilization_delta_30d`.

## Debt stacking and settlement detection

Surface borrowers taking on new debt across institutions before bureau catches up. Use change-over-time attributes across credit cards and installment accounts to detect stacking patterns through the cross-account view.

*Key v2 attributes:* `delinquency_flag_credit_cards`, `installment_balance_change_30d`, `installment_balance_change_60d`, `revolving_credit_card_balance_change_30d`, `revolving_credit_card_balance_change_60d`.


# Digital Engagement & PFM
Source: https://docs.methodfi.com/guides/use-cases/pfm/overview

Build comprehensive personal financial management experiences with Method's liability data, credit insights, and payment infrastructure.

## What This Section Covers

Products and APIs that enable comprehensive personal financial management experiences — from discovering a user's complete debt picture to monitoring changes in real time, surfacing credit insights, and enabling bill pay directly from your app.

If you're building any product that helps consumers understand, manage, or pay down their financial obligations, this is where to start.

### Example Use Cases

* **Digital wallets** that display card balances, brand art, and recent transactions
* **Spend management apps** that categorize liability transactions and track spending patterns
* **Financial wellness platforms** that surface credit scores, debt-to-income insights, and payoff strategies
* **Neobanks** that embed bill pay and debt repayment into the core banking experience

## How Method Enables End-to-End PFM

Every PFM integration follows the same high-level journey: discover the user's liabilities, enrich them with real-time data, surface insights, and enable action.

| Stage        | What Happens                                                               | Method Products                                                                                                                           |
| ------------ | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Connect**  | Discover the user's complete liability picture via soft-pull credit report | [Entity](/guides/entities/overview), [Identity Verification](/guides/identity-verification/overview), [Connect](/guides/connect/overview) |
| **Data**     | Pull real-time balances, APRs, due dates, card art, and transactions       | [Updates](/guides/updates/overview), [Card Brand](/guides/additional-products/card-brand)                                                 |
| **Insights** | Surface credit scores, payment history, utilization, and attributes        | [Credit Scores](/guides/additional-products/credit-scores), [Attributes](/guides/additional-products/attributes)                          |
| **Pay**      | Initiate payments from your platform's funding account to users' creditors | [Payments](/guides/payments/overview)                                                                                                     |

## Get Started

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="/guides/use-cases/pfm/getting-started">
    The universal 3-step setup: create an entity, verify identity, and connect liabilities.
  </Card>

  <Card title="Onboarding & Discovery" icon="magnifying-glass" href="/guides/use-cases/pfm/onboarding-discovery">
    Identity verification, liability discovery, connect subscriptions, and vehicle enrichment.
  </Card>

  <Card title="Dashboard & Insights" icon="chart-mixed" href="/guides/use-cases/pfm/monitoring-insights">
    Real-time balances, credit scores, card brands, and entity-level attributes.
  </Card>

  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Transaction streaming, spend management, bill pay, and debt repayment.
  </Card>
</CardGroup>


# Overview
Source: https://docs.methodfi.com/libraries/overview



Method offers a list of official libraries that help developers easily
interact and build on top of the Method services.

## API client Libraries

Below is a list of libraries for each supported programming language. These
libraries are updated frequently to provide the best developer experience
when interacting with the Method API.

<CardGroup>
  <Card title="Node.js" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/nodejs-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=57e4626e40345a82da3e7effb6ab274a" />} href="https://github.com/MethodFi/method-node" />

  <Card title="Python" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/python-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=2e67dd38fef1f2c7d80ce0e422f6943c" />} href="https://github.com/MethodFi/method-python" />

  <Card title="OpenAPI" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/openapi-logo.svg?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=96448d2076f343383dd60886f7eebc20" />} href="https://github.com/MethodFi/openapi" />
</CardGroup>

## Element client libraries

Method supports a list of frontend libraries to make integrating Element
into your applications more seamless.

<CardGroup>
  <Card title="Javascript" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/js-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=ea0213b8187f61bcb5c5ecb75abd29f8" />} href="/libraries/js-sdk" />

  <Card title="React" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/react-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=9c683655cfe19c265ac9f077575b7a9e" />} href="https://github.com/MethodFi/react-method-elements" />

  <Card title="React Native" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/react-native-logo.svg?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=a3157c02adfdff112505e4c6ed5d91b0" />} href="https://github.com/MethodFi/react-native-method-elements" />
</CardGroup>

## Quickstart and examples

We've built a couple of quickstart applications to help you get started with
seamlessly building on top of Method.

<CardGroup>
  <Card title="Postman" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/postman-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=e23ad5829a5ea39ac00b25fcc1a34b4d" />} href="https://www.postman.com/methodfi/method-api/collection/8d5j00b/method-api-v2" />
</CardGroup>


# Account Verification
Source: https://docs.methodfi.com/opal/account_verification/overview



<Note>Mode: `account_verification`</Note>

Opal Account Verification is a pre-built flow for verifying a specific account. It provides a secure, compliant way to verify a single, known account (for example, a specific credit card).

<img alt="account-verification-hero" />

## What this mode does

Account Verification drives a focused verification flow for a single, known account (for example, a specific credit card). You must pass the target account\_id. Account Verification will automatically be invoked when needed (for example, during card\_connect), or can be used as a standalone module.

## Parameters

<ParamList />

## Create a token

You can create an account verification session token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `account_verification`
* Create new entity: provide `entity` + `mode` + `account_verification`
* Resume session: provide `session_id` only (omit `mode` and `account_verification`)

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "account_verification",
  "account_verification": { "account_id": "acc_..." }
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15125551234"
    }
  },
  "mode": "account_verification",
  "account_verification": { "account_id": "acc_..." }
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "valid_until": "2025-06-10T22:50:53.024Z",
  "session_id": "osess_..."
}
```

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Verify account</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Verify account" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>


# Card Connect
Source: https://docs.methodfi.com/opal/card_connect/overview



<Note>Mode: `card_connect`</Note>

Opal Card Connect is the primary way to connect user credit cards with Method.
This pre-built flow gathers a user's consent, verifies their identity, and completes any needed verifications to ensure their cards are connected to the Method ecosystem.

<img alt="account-verification-hero" />

## What this mode does

Card Connect lets users select and verify credit cards. Configure whether users may select a single card or multiple cards. Verified cards are eligible for payments and transactions.

## Parameters

<ParamList />

## Create a token

You can create a card connect session token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `card_connect`
* Create new entity: provide `entity` + `mode` + `card_connect`
* Resume session: provide `session_id` only (omit `mode` and `card_connect`)

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "card_connect",
  "card_connect": {
    "selection_type": "single",
    "account_filters": {
      "exclude": {
        "mch_ids": ["mch_123"],
        "unverified_account_numbers": true
      }
    }
  }
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15125551234"
    }
  },
  "mode": "card_connect",
  "card_connect": {
    "selection_type": "multiple"
  }
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "valid_until": "2025-06-10T22:50:53.024Z",
  "session_id": "osess_..."
}
```

## Testing in Development

When testing the frontend for Card Connect in the dev environment, use the following test values:

* **Verification code**: When the modal prompts you to enter a six-digit verification code, you can use any six-digit code. For example: `123456`. This applies to any test case (e.g. identity verification, connect, etc.).
* **Card verification**: Select the Chase card ending in `1580` and use `878` as the CVV.

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Connect Card</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Connect Card" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>


# Connect
Source: https://docs.methodfi.com/opal/connect/overview



<Note>Mode: `connect`</Note>

Opal Connect is the primary way to connect user liability accounts with Method.
This pre-built flow gathers a user's consent, verifies their identity, and completes any needed verifications to ensure their accounts are connected to the Method ecosystem.

<img alt="connect-hero" />

## What this mode does

Connect lets users find and connect their liability accounts (credit cards, loans, mortgages, etc.). Configure whether users may select a single account, multiple accounts, or by default select all eligible accounts.

## Parameters

<ParamList />

## Create a token

You can create a connect session token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `connect`
* Create new entity: provide `entity` + `mode` + `connect`
* Resume session: provide `session_id` only (omit `mode` and `connect`)

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "connect",
  "connect": {
    "selection_type": "single",
    "account_filters": {
      "include": {
        "account_types": ["credit_card", "auto_loan"],
        "products": ["balance"]
      }
    }
  }
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15125551234"
    }
  },
  "mode": "connect",
  "connect": {
    "selection_type": "multiple",
    "account_filters": {
      "exclude": {
        "account_types": ["personal_loan"],
        "mch_ids": ["mch_123"],
        "unverified_account_numbers": true
      }
    }
  }
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "valid_until": "2025-06-10T22:50:53.024Z",
  "session_id": "osess_..."
}
```

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Connect Accounts</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Connect Accounts" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>


# Opal Events
Source: https://docs.methodfi.com/opal/events



Communication between Opal and your app is handled through a consistent, mode-aware event system. Events are emitted throughout the user session to indicate progress, completion, errors, and important milestones.

## Listening to Events

We strongly recommend using one of the Opal SDKs to receive typed events and lifecycle callbacks. The SDKs provide `onEvent`, `onOpen`, and `onExit` handlers and expose a small enum of well-known events under `OpalEventType` for convenience (e.g., `SESSION_STARTED`, `SESSION_COMPLETED`).

Each Opal mode (`identity_verification`, `connect`, `card_connect`, `account_verification`, `transactions`) emits a set of mode‑specific events in addition to default session events. See below for structure, a complete list, and examples.

## Event Structure

All Opal events follow a consistent structure:

```json theme={null}
{
  "type": "opal.session.started",
  "mode": "opal",
  "object": "session",
  "action": "started",
  "timestamp": "2025-06-10T22:50:53.024Z",
  "data": null
}
```

### Event fields

| Field       | Type           | Description                                                                                                     |
| ----------- | -------------- | --------------------------------------------------------------------------------------------------------------- |
| `type`      | string         | Fully qualified event name: `<flow>.<object>.<action>` or `opal.session.<action>` for default session events.   |
| `mode`      | string         | The active operational mode (e.g., `connect`, `identity_verification`, `account_verification`, `transactions`). |
| `object`    | string         | The related object (e.g., `session`, `flow`, `step`, `identity`, `card`, `accounts`).                           |
| `action`    | string         | The action that occurred (e.g., `started`, `completed`, `verified`, `errored`).                                 |
| `timestamp` | string         | ISO 8601 timestamp of when the event occurred.                                                                  |
| `data`      | object \| null | Additional context that varies by event type; may be `null` for lifecycle events.                               |

### Possible flows:

* `identity_verification`
* `connect`
* `account_verification`
* `transactions`

## Sample Events

### opal.session.started

```json theme={null}
{
  "type": "opal.session.started",
  "mode": "connect",
  "object": "session",
  "action": "started",
  "timestamp": "2025-06-10T22:50:53.024Z",
  "data": null
}
```

### opal.session.errored

```json theme={null}
{
  "type": "opal.session.errored",
  "mode": "connect",
  "object": "session",
  "action": "errored",
  "timestamp": "2025-06-10T22:50:53.024Z",
  "data": {
    "type": "INVALID_REQUEST",
    "sub_type": "INVALID_SMS_CODE",
    "message": "Invalid request please try again"
  }
}
```

### connect.flow\.completed

```json theme={null}
{
  "type": "connect.flow.completed",
  "mode": "connect",
  "object": "flow",
  "action": "completed",
  "timestamp": "2025-06-10T22:50:53.024Z",
  "data": {
    "accounts": ["acc_ge9hxMTPGdXmQ"],
    "entity_id": "ent_wrDBN43PR8LKC"
  }
}
```

## Event Categories

### Default session events (always available)

* `opal.session.started` - Opal UI opened and session began
* `opal.session.completed` - User completed the flow successfully
* `opal.session.errored` - A recoverable or terminal error occurred
* `opal.session.exited` - User exited or dismissed Opal

### Generic flow and step events

Emitted in addition to the default session events. These mirror the active mode‑specific events but are prefixed with `opal` and can be emitted for any mode.

#### Flow

* `opal.flow.started` - A sub‑flow of Opal started (e.g., identity verification, account selection, verification).
* `opal.flow.completed` - A sub‑flow of Opal completed. This does not always signify the end of the session; use `opal.session.completed` to detect when Opal is fully completed.

#### Step

* `opal.step.started` - A new step started (e.g., phone input, card selection, CVV input).
* `opal.step.completed` - A step completed and the next page is opening.

Notes:

* Additional mode-specific events may be introduced over time. Your handler should use the `OpalEventType` enum to handle the specific cases you need.

## All Event Types

The following table lists all currently supported event types with their `OpalEventType` mapping, and when they are typically emitted.

| Event (OpalEventType - type)                                              | When you might see it                              |
| ------------------------------------------------------------------------- | -------------------------------------------------- |
| `SESSION_STARTED` - `opal.session.started`                                | Opal UI opened and session began.                  |
| `SESSION_COMPLETED` - `opal.session.completed`                            | User completed the overall Opal flow successfully. |
| `SESSION_ERRORED` - `opal.session.errored`                                | A recoverable or terminal error occurred.          |
| `SESSION_EXITED` - `opal.session.exited`                                  | User closed or dismissed Opal before completion.   |
| `FLOW_STARTED` - `opal.flow.started`                                      | A sub-flow (for any mode) started.                 |
| `FLOW_COMPLETED` - `opal.flow.completed`                                  | A sub-flow (for any mode) completed.               |
| `STEP_STARTED` - `opal.step.started`                                      | A step (screen) started.                           |
| `STEP_COMPLETED` - `opal.step.completed`                                  | A step (screen) completed.                         |
| `IDV_FLOW_STARTED` - `identity_verification.flow.started`                 | Identity Verification flow started.                |
| `IDV_STEP_STARTED` - `identity_verification.step.started`                 | A step in Identity Verification started.           |
| `IDV_STEP_COMPLETED` - `identity_verification.step.completed`             | A step in Identity Verification completed.         |
| `IDV_FLOW_COMPLETED` - `identity_verification.flow.completed`             | Identity Verification flow completed.              |
| `IDV_VERIFICATION_COMPLETED` - `identity_verification.identity.completed` | Identity successfully verified (KYC passed).       |
| `CXN_FLOW_STARTED` - `connect.flow.started`                               | Connect flow started.                              |
| `CXN_STEP_STARTED` - `connect.step.started`                               | A step in Connect started.                         |
| `CXN_STEP_COMPLETED` - `connect.step.completed`                           | A step in Connect completed.                       |
| `CXN_FLOW_COMPLETED` - `connect.flow.completed`                           | Connect flow completed.                            |
| `CXN_ACCOUNTS_SELECTED` - `connect.accounts.selected`                     | User selected one or more accounts to connect.     |
| `AVF_FLOW_STARTED` - `account_verification.flow.started`                  | Account Verification flow started.                 |
| `AVF_STEP_STARTED` - `account_verification.step.started`                  | A step in Account Verification started.            |
| `AVF_STEP_COMPLETED` - `account_verification.step.completed`              | A step in Account Verification completed.          |
| `AVF_FLOW_COMPLETED` - `account_verification.flow.completed`              | Account Verification flow completed.               |
| `AVF_CARD_VERIFIED` - `account_verification.card.verified`                | Card verified successfully.                        |
| `TXN_FLOW_STARTED` - `transactions.flow.started`                          | Transactions flow started.                         |
| `TXN_STEP_STARTED` - `transactions.step.started`                          | A step in Transactions started.                    |
| `TXN_STEP_COMPLETED` - `transactions.step.completed`                      | A step in Transactions completed.                  |
| `TXN_FLOW_COMPLETED` - `transactions.flow.completed`                      | Transactions flow completed.                       |
| `TXN_ACCOUNTS_LINKED` - `transactions.accounts.linked`                    | Accounts linked and subscribed for transactions.   |

### Data Payloads

The following events always include a non-null `event.data` payload:

* `identity_verification.identity.completed`
* `connect.accounts.selected`
* `account_verification.card.verified`
* `transactions.accounts.linked`

Use these payloads to retrieve context such as selected accounts, verification results, or linkage details.

## Enhanced Event Handling

### Using the JavaScript SDK

```javascript theme={null}
import { OpalEventType } from '@methodfi/opal-react';

const config = {
  onEvent: (event) => {
    console.log("Event received:", event.type);

    // Handle specific events using the OpalEventType enum
    switch (event.type) {
      case OpalEventType.SESSION_STARTED:
        // Session lifecycle
        break;
      case OpalEventType.SESSION_COMPLETED:
        // Entire Opal session completed successfully
        break;
      case OpalEventType.SESSION_ERRORED:
        // Handle recoverable or terminal error
        console.error("Opal error:", event.data);
        break;
      case OpalEventType.IDV_VERIFICATION_COMPLETED:
        // Identity verification completed; payload contains verification details
        handleIdentityVerified(event.data);
        break;
      case OpalEventType.CXN_ACCOUNTS_SELECTED:
        // User selected accounts in Connect
        handleAccountsSelected(event.data);
        break;
      case OpalEventType.AVF_CARD_VERIFIED:
        // Card verified in Account Verification
        handleCardVerified(event.data);
        break;
      case OpalEventType.TXN_ACCOUNTS_LINKED:
        // Accounts linked for Transactions
        handleAccountsLinked(event.data);
        break;
      default:
        // Optionally handle generic flow/step events
        break;
    }
  },

  // Specific event handlers
  onSuccess: (payload) => {
    // Called for successful completion events
    console.log("Success:", payload);
  },

  onError: (error) => {
    // Enhanced error handling with detailed information
    console.error("Error:", error.code, error.message);
    console.error("Details:", error.details);
  },
};

const opal = new MethodOpal(config);
```

## PostMessage Communication

For applications not using the Opal SDKs, you can listen to events via PostMessage:

### Setup PostMessage Listener

```javascript theme={null}
window.addEventListener("message", function (event) {
  // Verify origin for security
  if (event.origin !== "https://opal.production.methodfi.com") {
    return;
  }

  const opalEvent = event.data;
  console.log("Opal event:", opalEvent.type, opalEvent.data);

  // Handle events
  switch (opalEvent.type) {
    case OpalEventType.SESSION_STARTED:
      console.log("Opal started");
      break;
    case OpalEventType.SESSION_COMPLETED:
      console.log("Opal completed:", opalEvent.data);
      break;
  }
});
```

## Best Practices

### Event Handling

* Always verify event origins for security
* Use event filtering to reduce noise
* Implement proper error handling for all events
* Log events for debugging and analytics

### Security

* Validate all event data before processing
* Never trust client-side events for critical business logic


# Identity Verification
Source: https://docs.methodfi.com/opal/identity/overview



<Note>Mode: `identity_verification`</Note>

Opal Identity Verification is a pre-built flow for verifying user identity. It provides a secure, compliant way to collect and verify personal information like name, date of birth, address, and other identity details needed for KYC/AML requirements.

<img alt="identity-hero" />

## What this mode does

Identity Verification collects, confirms, and verifies a user's identity details (name, DOB, address, phone, SSN if needed). Users must explicitly confirm their details before verification challenges begin. Identity Verification will automatically be invoked when needed, or can be used as a standalone module.

## Parameters

<ParamList />

## Create a token

You can create an identity verification session token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `identity_verification`
* Create new entity: provide `entity` + `mode` + `identity_verification`
* Resume session: provide `session_id` only (omit `mode` and `identity_verification`)

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "identity_verification",
  "identity_verification": {
    "skip_pii": ["name", "dob", "address"]
  }
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15125551234"
    }
  },
  "mode": "identity_verification",
  "identity_verification": {
    "skip_pii": []
  }
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "valid_until": "2025-06-10T22:50:53.024Z",
  "session_id": "osess_..."
}
```

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Verify identity</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Verify identity" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>


# Migration from Elements
Source: https://docs.methodfi.com/opal/migration_guide



When migrating from Elements to Opal, there are several key changes to consider:

## URL Changes

If you're launching Opal directly from a URL, the process remains similar to Elements, but with updated domains:

* Elements: `elements.{environment}.methodfi.com`
* Opal: `opal.{environment}.methodfi.com`

## New Libraries

We've introduced new SDKs specifically designed for Opal integration:

* [@methodfi/opal-react](https://www.npmjs.com/package/@methodfi/opal-react) for React applications
* [@methodfi/opal-react-native](https://www.npmjs.com/package/@methodfi/opal-react-native) for React Native
* Direct CDN integration via `https://static.methodfi.com/opal/v1/stable/init.js`

See our [libraries documentation](/opal/libraries) for detailed implementation guides.

## Token Generation Changes

When generating tokens for Opal, we've added new parameters that must be provided in order for more flexibility and control over the user experience. The token generation process has been streamlined in Opal.

### Elements

```json theme={null}
POST /elements/token
{
  "type": "connect",
  "connect": {
    "entity_id": "ent_au22b1fbFJbp8",
    "products": ["balance"],
    "redirect_url": "https://example.com/callback"
  }
}
```

### Opal

```json theme={null}
POST /opal/token
{
  "mode": "connect",
  "entity_id": "ent_au22b1fbFJbp8",
  "connect": {
    "selection_type": "single",
    "account_filters": {
      "include": {
        "account_types": ["credit_card", "auto_loan"],
        "products": ["balance"]
      }
    }
  }
}
```

In Elements, product filtering was a top-level field (`connect.products`). In Opal, product filtering is done via `connect.account_filters.include.products`. Allowed values: `balance`, `sensitive`, `payoff`, `update`, `payment`.

See Opal [Identity](/opal/identity/overview), [Connect](/opal/connect/overview), [Card Connect](/opal/card_connect/overview), and [Account Verification](/opal/account_verification/overview) guides for more info on token generation.


# Sessions
Source: https://docs.methodfi.com/opal/sessions

Maintain state and user data across Opal interactions.

Opal Sessions are long-lived stateful connections between your app and Opal.
They allow you to store user data, resume user sessions, and retrieve data later.
Sessions are created when you create an Opal Token, and when passed into Opal,
they are automatically resumed.

## Creating a new session

First, create a new Opal Token with your desired configuration. This will create a new session.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/opal/token \
    -X POST \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "mode": "card_connect",
      "entity_id": "ent_fc92i43kc34",
      "card_connect": {
        "selection_type": "single"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "token": "otkn_THpBacqVBBrDkfqUf9htjm4QWAEJLY9a",
      "valid_until": "2025-05-08T22:21:40.312Z",
      "session_id": "osess_zde3mW34pEHqV"
    },
    "message": null
  }
  ```
</ResponseExample>

## Resuming an existing session

To resume an existing session, create a new token by passing the `session_id` from a previous session

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/opal/token \
    -X POST \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "session_id": "osess_zde3mW34pEHqV"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "token": "otkn_THpBacqVBBrDkfqUf9htjm4QWAEJLY9a",
      "valid_until": "2025-05-08T22:21:40.312Z",
      "session_id": "osess_zde3mW34pEHqV"
    },
    "message": null
  }
  ```
</ResponseExample>


# Transactions
Source: https://docs.methodfi.com/opal/transactions/overview



<Note>Mode: `transactions`</Note>

Opal Transactions is the primary way to obtain consent and subscribe to real-time transactions.
This pre-built flow gathers a user's consent, verifies their identity, and prompts them to select the accounts eligible to be subscribed to.

<img alt="transactions-hero" />

## What this mode does

Transactions will provide a seamless experience for a user to subscribe to real-time transaction updates for supported accounts.
Eligible accounts will be automatically determined by Method, including your team's eligibility criteria.

For details on how to receive transaction updates via [Webhooks](/reference/webhooks/create). Make sure you are subscribed to the relevant webhook events to receive real-time transaction data. Note that you will only receive updates for events that occur after your subscription is active.

Please reach out to your CSM to enable access to this mode!

## Create a token

You can create a transactions token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `transactions`
* Create new entity: provide `entity` + `mode` + `transactions`

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "transactions",
  "transactions": {}
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {}
  },
  "mode": "transactions",
  "transactions": {}
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "session_id": "osess_...",
  "valid_until": "2025-06-10T22:50:53.024Z"
}
```

## Resuming a session

Want to link more cards? In this mode, simply create another token with the same `entity_id` and Method will intelligently pick up where your user left off. They won't ever be asked to link a card twice!

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({
        env: "dev",
        onEvent: (e) => {},
        onExit: (e) => {},
      });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Link Transactions</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({
        env: "dev",
        onEvent: (e) => {},
        onExit: (e) => {},
      });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Link Transactions" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>


# Getting Started
Source: https://docs.methodfi.com/guides/use-cases/pfm/getting-started

The universal 3-step flow for PFM integrations: create an entity, verify identity, and connect liabilities.

Every PFM integration begins with the same three steps: represent your user as an Entity, verify their identity, and discover their liabilities through Connect. Once these steps are complete, every product in Method's platform becomes available.

This guide walks through the full API flow using a single user, Sarah Chen, whose data threads through the rest of the PFM guides.

<Steps>
  <Step title="Create an Entity">
    An [Entity](/guides/entities/overview) is Method's representation of your end user. You provide their PII, and Method creates a persistent identity that everything else — verification, accounts, payments — attaches to.

    ```bash theme={null}
    curl https://production.methodfi.com/entities \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "individual",
        "individual": {
          "first_name": "Sarah",
          "last_name": "Chen",
          "phone": "+14155550123",
          "email": "sarah.chen@email.com",
          "dob": "1992-07-15"
        },
        "address": {
          "line1": "123 Main St",
          "line2": null,
          "city": "San Francisco",
          "state": "CA",
          "zip": "94102"
        }
      }'
    ```

    The Entity is created with `status: "incomplete"` because identity verification hasn't happened yet. Products like Connect and Credit Scores remain in `restricted_products` until verification is complete.

    ```json theme={null}
    {
      "id": "ent_au22b1fbFJbp8",
      "type": "individual",
      "individual": {
        "first_name": "Sarah",
        "last_name": "Chen",
        "phone": "+14155550123",
        "dob": "1992-07-15",
        "email": "sarah.chen@email.com",
        "ssn_4": null,
        "ssn": null
      },
      "error": null,
      "address": {
        "line1": "123 Main St",
        "line2": null,
        "city": "San Francisco",
        "state": "CA",
        "zip": "94102"
      },
      "status": "incomplete",
      "verification": {
        "identity": {
          "verified": false,
          "matched": false,
          "latest_verification_session": null,
          "methods": [
            "element",
            "kba"
          ]
        },
        "phone": {
          "verified": false,
          "latest_verification_session": null,
          "methods": [
            "sms",
            "sna"
          ]
        }
      },
      "connect": null,
      "credit_score": null,
      "products": [
        "identity"
      ],
      "restricted_products": [
        "connect",
        "credit_score",
        "attribute"
      ],
      "subscriptions": [],
      "available_subscriptions": [
        "connect",
        "credit_score"
      ],
      "restricted_subscriptions": [],
      "metadata": null,
      "created_at": "2025-09-15T14:30:00.000Z",
      "updated_at": "2025-09-15T14:30:00.000Z"
    }
    ```
  </Step>

  <Step title="Verify the User">
    Before Method can discover Sarah's accounts, she must complete [identity verification](/guides/identity-verification/overview). This is a two-part process: first confirming she controls her phone number, then verifying her identity.

    ### Phone Verification (SMS)

    Start by verifying Sarah's phone number. This sends an SMS code to `+14155550123`.

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/verification_sessions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "sms",
        "sms": {}
      }'
    ```

    ```json theme={null}
    {
      "id": "evf_3VT3bHTCnPbrm",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "in_progress",
      "type": "phone",
      "method": "sms",
      "sms": {},
      "error": null,
      "created_at": "2025-09-15T14:31:00.000Z",
      "updated_at": "2025-09-15T14:31:00.000Z"
    }
    ```

    After the user provides the SMS code and completes identity verification (via [KBA](/reference/entities/verification-sessions/create-kba) or [Opal](/guides/opal)), the Entity transitions to `status: "active"` and products are unlocked.

    <Note>
      **Recommended: Use [Opal](/guides/opal)** for identity verification. Opal is Method's pre-built, white-labeled UI that handles both phone verification and identity verification in a single drop-in component. Most teams start here.
    </Note>

    ### After Verification

    Once verified, the Entity's `products` array expands and `restricted_products` clears:

    ```json theme={null}
    {
      "id": "ent_au22b1fbFJbp8",
      "status": "active",
      "verification": {
        "identity": {
          "verified": true,
          "matched": true,
          "latest_verification_session": "evf_9kR2fGhLmNpQ4",
          "methods": []
        },
        "phone": {
          "verified": true,
          "latest_verification_session": "evf_3VT3bHTCnPbrm",
          "methods": []
        }
      },
      "products": [
        "identity",
        "connect",
        "credit_score",
        "attribute"
      ],
      "restricted_products": [],
      "available_subscriptions": [
        "connect",
        "credit_score"
      ],
      "restricted_subscriptions": []
    }
    ```
  </Step>

  <Step title="Connect Liabilities">
    With Sarah verified, you can now discover her complete liability picture using [Connect](/guides/connect/overview). This performs a soft-pull credit report (no impact to her credit score) and returns all discovered accounts.

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```

    Connect discovers all of Sarah's open liabilities and returns them as account IDs:

    ```json theme={null}
    {
      "id": "cxn_iYGhvTRDnE4y7",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "completed",
      "accounts": [
        "acc_eKKmrXDpJBKgw",
        "acc_GV8WbmJW7KGRy",
        "acc_MLPKh9gQDDbT8",
        "acc_LbXE8wVYJLrKt",
        "acc_J3P9fayDFjpAy",
        "acc_eFFRV9zmpLREK"
      ],
      "requested_products": [],
      "requested_subscriptions": [],
      "error": null,
      "created_at": "2025-09-15T14:35:00.000Z",
      "updated_at": "2025-09-15T14:35:00.000Z"
    }
    ```

    ### What Was Discovered

    Each account ID maps to a liability that Method found on Sarah's credit report. You can retrieve any account to see its details:

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    ```json theme={null}
    {
      "id": "acc_eKKmrXDpJBKgw",
      "holder_id": "ent_au22b1fbFJbp8",
      "type": "liability",
      "liability": {
        "mch_id": "mch_302086",
        "type": "credit_card",
        "name": "Chase Sapphire Reserve"
      },
      "status": "active",
      "products": [
        "update",
        "payment",
        "card_brand",
        "transaction"
      ],
      "created_at": "2025-09-15T14:35:00.000Z",
      "updated_at": "2025-09-15T14:35:00.000Z"
    }
    ```

    Here's what Sarah's full liability picture looks like:

    | Account ID          | Creditor               | Type          |
    | ------------------- | ---------------------- | ------------- |
    | `acc_eKKmrXDpJBKgw` | Chase Sapphire Reserve | Credit Card   |
    | `acc_GV8WbmJW7KGRy` | Citi Double Cash       | Credit Card   |
    | `acc_MLPKh9gQDDbT8` | Capital One            | Auto Loan     |
    | `acc_LbXE8wVYJLrKt` | Navient                | Student Loan  |
    | `acc_J3P9fayDFjpAy` | SoFi                   | Personal Loan |
    | `acc_eFFRV9zmpLREK` | Wells Fargo            | Mortgage      |
  </Step>
</Steps>

## What's Next

With Sarah's entity created, verified, and her liabilities discovered, you're ready to build the core PFM experience. Each of the following guides picks up where this setup leaves off.

<CardGroup>
  <Card title="Onboarding & Discovery" icon="magnifying-glass" href="/guides/use-cases/pfm/onboarding-discovery">
    Deep dive into identity verification options, connect subscriptions for ongoing discovery, and vehicle enrichment for auto loans.
  </Card>

  <Card title="Dashboard & Insights" icon="chart-mixed" href="/guides/use-cases/pfm/monitoring-insights">
    Pull real-time balances, credit scores, card brand art, and entity-level financial health attributes.
  </Card>

  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Stream credit card transactions and initiate bill payments to your users' creditors.
  </Card>
</CardGroup>


# Debt Dashboard & Credit Insights
Source: https://docs.methodfi.com/guides/use-cases/pfm/monitoring-insights

Build real-time debt dashboards with account updates, card brand art, credit scores, and financial health attributes.

Once a user's liabilities are connected, the next step is turning that raw data into a useful dashboard. This guide covers pulling real-time account data, enriching cards with brand art, monitoring balances over time, and surfacing credit health insights.

All examples use Sarah Chen's accounts from the [Getting Started](/guides/use-cases/pfm/getting-started) guide.

## Debt Dashboard & Real-Time Monitoring

### Requesting an Account Update

[Updates](/guides/updates/overview) pull real-time data — balance, credit limit, APR, due dates, payment history — directly from the financial institution. This is the core data feed for any debt dashboard.

Request an update for Sarah's Chase Sapphire Reserve card:

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/updates \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "upt_NYV5kfjskTTCJ",
      "status": "completed",
      "account_id": "acc_eKKmrXDpJBKgw",
      "source": "direct",
      "type": "credit_card",
      "credit_card": {
        "available_credit": 1920000,
        "balance": 80000,
        "closed_at": null,
        "credit_limit": 2000000,
        "interest_rate_percentage_max": 22.49,
        "interest_rate_percentage_min": 22.49,
        "interest_rate_type": "variable",
        "last_payment_amount": 15000,
        "last_payment_date": "2025-08-28",
        "next_payment_due_date": "2025-10-01",
        "next_payment_minimum_amount": 2500,
        "opened_at": "2022-03-15",
        "sub_type": "flexible_spending",
        "usage_pattern": "transactor"
      },
      "data_as_of": "2025-09-15T14:45:00.000Z",
      "error": null,
      "created_at": "2025-09-15T14:45:00.000Z",
      "updated_at": "2025-09-15T14:45:00.312Z"
    }
    ```
  </Tab>
</Tabs>

Sarah's Chase card has an \$800.00 balance on a \$20,000.00 limit (4% utilization), with a minimum payment of \$25.00 due on October 1st. Her last payment of \$150.00 was made on August 28th, and her `usage_pattern` is `transactor` — she pays in full each month.

### Subscribing to Continuous Updates

Rather than polling for updates, subscribe to receive them automatically. When the financial institution reports new data, Method delivers it via webhook.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/subscriptions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "enroll": "update"
      }'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "sub_xM4VcfRWcJP8D",
      "name": "update",
      "status": "active",
      "payload": null,
      "latest_request_id": "upt_NYV5kfjskTTCJ",
      "created_at": "2025-09-15T15:10:00.000Z",
      "updated_at": "2025-09-15T15:10:00.000Z"
    }
    ```
  </Tab>
</Tabs>

With the subscription active, Method will fire `update.create` and `update.update` webhook events whenever new data is available. Your app can refresh the dashboard in real time without the user taking any action.

### Card Brand Art

For credit card accounts, [Card Brand](/guides/additional-products/card-brand) retrieves the card's product name, issuer, network, and card art image. This lets your wallet UI display the actual card visual instead of a generic placeholder.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/card_brands \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "cbrd_Accm7P6t6mYQP",
      "account_id": "acc_eKKmrXDpJBKgw",
      "brands": [
        {
          "id": "pdt_15_brd_1",
          "card_product_id": "pdt_15",
          "description": "Chase Sapphire Reserve",
          "name": "Chase Sapphire Reserve",
          "issuer": "Chase",
          "network": "visa",
          "network_tier": "infinite",
          "type": "specific",
          "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
        }
      ],
      "status": "completed",
      "source": "method",
      "error": null,
      "created_at": "2025-09-15T15:15:00.000Z",
      "updated_at": "2025-09-15T15:15:00.000Z"
    }
    ```
  </Tab>
</Tabs>

The `url` field provides a direct link to the card's art image, which you can render in your wallet or dashboard UI.

### Entity-Level Attributes

[Attributes](/guides/additional-products/attributes) provide entity-level financial health metrics aggregated across all of a user's accounts. These power features like credit health dashboards, utilization alerts, and financial wellness scores.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/attributes \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    <Note>
      Attribute requests are asynchronous and compute all available attributes automatically. The initial response will have `status: "in_progress"` and `attributes: null`. You'll receive a webhook when the attributes are ready.
    </Note>
  </Tab>

  <Tab title="Response (completed)">
    ```json theme={null}
    {
      "id": "attr_nrPjaahMX4yRA",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "completed",
      "attributes": {
        "revolving_credit_card_balance_total": {
          "value": 550000,
          "error": null,
          "metadata": null
        },
        "credit_limit_total": {
          "value": 2500000,
          "error": null,
          "metadata": null
        },
        "credit_card_utilization": {
          "value": 22.0,
          "error": null,
          "metadata": null
        },
        "weighted_average_apr_credit_card": {
          "value": 21.24,
          "error": null,
          "metadata": null
        },
        "usage_pattern": {
          "value": "transactor",
          "error": null,
          "metadata": null
        },
        "overall_utilization": {
          "value": 22.0,
          "error": null,
          "metadata": null
        }
      },
      "error": null,
      "created_at": "2025-09-15T15:20:00.000Z",
      "updated_at": "2025-09-15T15:20:30.000Z"
    }
    ```
  </Tab>
</Tabs>

Sarah's attributes show 22% aggregate credit card utilization ($5,500.00 in revolving balances against $25,000.00 in combined limits), a weighted average card APR of 21.24%, and a `transactor` usage pattern (she pays in full each month). These data points map directly to the factors that credit scoring models weigh most heavily. Each attribute is returned as an object with `value`, `error`, and `metadata` fields; if an attribute cannot be computed, `value` is `null` and `error` explains why.

***

## Credit Building & Score Insights

### Retrieving Credit Scores

[Credit Scores](/guides/additional-products/credit-scores) retrieve the user's credit score sourced from Equifax using the VantageScore 4.0 model. The response includes contributing factors that explain what's helping or hurting the score.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/credit_scores \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    <Note>
      Credit score requests are asynchronous. The initial response will have `status: "pending"` and `scores: null`. You'll receive a webhook when the score is ready.
    </Note>
  </Tab>

  <Tab title="Response (completed)">
    ```json theme={null}
    {
      "id": "crs_pn4ca33GXFaCE",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "completed",
      "scores": [
        {
          "score": 734,
          "source": "equifax",
          "model": "vantage_4",
          "factors": [
            "Length of time accounts have been established",
            "Too few accounts currently paid as agreed",
            "Lack of recent installment loan information",
            "Proportion of balances to credit limits is too high on bank revolving or other revolving accounts"
          ],
          "created_at": "2025-09-15T15:25:00.000Z"
        }
      ],
      "error": null,
      "created_at": "2025-09-15T15:25:00.000Z",
      "updated_at": "2025-09-15T15:25:30.000Z"
    }
    ```
  </Tab>
</Tabs>

Sarah's VantageScore 4.0 is 734 ("Good" tier). The factors array explains what's influencing her score — you can surface these directly in your app to help users understand what actions would improve their score.

### Credit Score Subscriptions

To monitor Sarah's credit score over time, enroll her in a credit score subscription. Method will automatically check for score changes and send webhook events when her score increases or decreases.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/subscriptions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "enroll": "credit_score"
      }'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "sub_c3a7hVjHCJzF3",
      "name": "credit_score",
      "status": "active",
      "payload": null,
      "latest_request_id": null,
      "created_at": "2025-09-15T15:30:00.000Z",
      "updated_at": "2025-09-15T15:30:00.000Z"
    }
    ```
  </Tab>
</Tabs>

With the subscription active, your app can power features like monthly score reports, trend charts, and push notifications ("Your credit score went up 12 points this month!") that drive engagement and retention.

### Combining Scores and Attributes

The most effective credit building experiences combine credit scores with attributes. The score tells users *where they stand*, while attributes tell them *why* and *what to do about it*:

| Attribute                             | Sarah's Value | What to Surface                                                             |
| ------------------------------------- | ------------- | --------------------------------------------------------------------------- |
| `credit_card_utilization`             | 22%           | "Your utilization is healthy. Keep it under 30%"                            |
| `usage_pattern`                       | `transactor`  | "You pay your cards in full each month. Keep it up!"                        |
| `weighted_average_apr_credit_card`    | 21.24%        | "Your average card APR is 21.24%. A balance transfer could reduce interest" |
| `revolving_credit_card_balance_total` | \$5,500.00    | "Your total card balances across all accounts"                              |

<Card title="Attributes API Reference" icon="chart-bar" href="/reference/entities/attributes/create">
  Full documentation for all available attribute types and their value, error, and metadata fields.
</Card>

## What's Next

<CardGroup>
  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Stream credit card transactions for spend management and initiate bill payments.
  </Card>

  <Card title="Update Subscriptions Guide" icon="rotate" href="/guides/updates/subscriptions">
    Deep dive into update subscription types, frequencies, and webhook payloads.
  </Card>
</CardGroup>


# Onboarding & Liability Discovery
Source: https://docs.methodfi.com/guides/use-cases/pfm/onboarding-discovery

Identity verification options, liability discovery via Connect, ongoing connect subscriptions, and vehicle enrichment for auto loans.

This guide covers the onboarding layer of a PFM integration: how users get verified, how their liabilities are discovered, how to detect new liabilities over time, and how to enrich auto loan accounts with vehicle details.

If you haven't completed the [Getting Started](/guides/use-cases/pfm/getting-started) steps (creating and verifying Sarah Chen's Entity, and running Connect), start there first.

## Identity Verification with Opal

[Opal](/guides/opal) is Method's pre-built, white-labeled UI component that handles the entire verification flow — phone verification and identity verification — in a single drop-in experience. It's the fastest path to getting users verified and is recommended for most integrations.

<Tabs>
  <Tab title="Opal (Recommended)">
    Opal handles phone verification (SMS or SNA) and identity verification (KBA) in a single embedded flow. Your user completes the process in your app, and you receive a webhook when verification is complete.

    **Advantages:**

    * Minimal frontend development
    * Tested, optimized UX for conversion
    * Handles edge cases (retries, fallbacks, error states)
    * White-labeled to match your brand

    <Card title="Opal Integration Guide" icon="window" href="/guides/opal">
      Full guide for embedding Opal in your application.
    </Card>
  </Tab>

  <Tab title="BYO Identity Verification">
    If you have an existing identity verification flow or need complete control over the UX, you can use Method's API directly. This involves separate calls for [phone verification](/reference/entities/verification-sessions/create-sms) and [identity verification](/reference/entities/verification-sessions/create-kba).

    **When to use BYO:**

    * You already have a KYC/IDV provider and want to pass results to Method
    * Your UX requires a custom verification flow
    * You need to integrate verification into an existing onboarding funnel

    <Card title="Identity Verification Methods" icon="shield-check" href="/guides/identity-verification/methods">
      All available verification methods and when to use each.
    </Card>
  </Tab>
</Tabs>

## Liability Discovery via Connect

Once Sarah is verified, [Connect](/guides/connect/overview) performs a soft-pull credit report to discover her liabilities. The [Getting Started](/guides/use-cases/pfm/getting-started) guide showed the Connect call that discovered all 6 of her accounts.

Here's what Connect found for Sarah:

| Account ID          | Creditor               | Type          | What Your App Shows            |
| ------------------- | ---------------------- | ------------- | ------------------------------ |
| `acc_eKKmrXDpJBKgw` | Chase Sapphire Reserve | Credit Card   | Card balance, APR, due date    |
| `acc_GV8WbmJW7KGRy` | Citi Double Cash       | Credit Card   | Card balance, APR, due date    |
| `acc_MLPKh9gQDDbT8` | Capital One            | Auto Loan     | Loan balance, payment schedule |
| `acc_LbXE8wVYJLrKt` | Navient                | Student Loan  | Loan balance, disbursements    |
| `acc_J3P9fayDFjpAy` | SoFi                   | Personal Loan | Balance, term, rate            |
| `acc_eFFRV9zmpLREK` | Wells Fargo            | Mortgage      | Balance, rate, payoff date     |

<Note>
  Connect discovers both open and closed liabilities on the first call. Subsequent Connect calls for the same Entity only return newly opened accounts.
</Note>

## Connect Subscriptions

A user's liability picture changes over time — they open new credit cards, take out loans, or consolidate debt. Connect subscriptions automatically re-run discovery on a recurring basis and notify you via webhook when new accounts are found.

Enroll the Entity in a connect subscription:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "enroll": "connect"
  }'
```

```json theme={null}
{
  "id": "sub_Wm3FJkqV8hpDR",
  "name": "connect",
  "status": "active",
  "payload": null,
  "latest_request_id": null,
  "created_at": "2025-09-15T15:00:00.000Z",
  "updated_at": "2025-09-15T15:00:00.000Z"
}
```

When Method detects a new liability for Sarah, you'll receive a webhook event with the new Connect result containing the newly discovered account IDs. Your app can then automatically add these to her dashboard without any user action.

## Vehicle Enrichment

For auto loan accounts like Sarah's Capital One loan (`acc_MLPKh9gQDDbT8`), Method can retrieve the associated vehicle details — VIN, year, make, model, and style. This transforms a generic "Auto Loan: \$18,450 balance" into "2021 Honda CR-V EX: \$18,450 remaining."

Request vehicle data for Sarah's Entity:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/vehicles \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

```json theme={null}
{
  "id": "evhl_QnT4mKxBfVpJ8",
  "entity_id": "ent_au22b1fbFJbp8",
  "vehicles": [
    {
      "vin": "7FARW2H83ME012345",
      "year": "2021",
      "make": "honda",
      "model": "cr-v",
      "series": null,
      "major_color": "blue",
      "style": "sport_utility_vehicle"
    }
  ],
  "status": "completed",
  "error": null,
  "created_at": "2025-09-15T15:05:00.000Z",
  "updated_at": "2025-09-15T15:05:00.000Z"
}
```

With vehicle data, your PFM app can display rich auto loan details, enable equity calculations (comparing vehicle value against remaining balance), and power features like insurance comparison or refinancing recommendations.

<Card title="Vehicles API Reference" icon="car" href="/reference/entities/vehicles/create">
  Full API documentation for the Vehicles endpoint.
</Card>

## What's Next

<CardGroup>
  <Card title="Dashboard & Insights" icon="chart-mixed" href="/guides/use-cases/pfm/monitoring-insights">
    Pull real-time balances, credit scores, card brand art, and financial health attributes.
  </Card>

  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Stream credit card transactions and initiate bill payments.
  </Card>
</CardGroup>


# Transactions & Bill Pay
Source: https://docs.methodfi.com/guides/use-cases/pfm/transactions-payments

Stream credit card transactions for spend management and initiate bill payments to your users' creditors.

This guide covers the action layer of a PFM integration: streaming transaction data for spend management, and initiating payments from your platform's corporate funding account to pay down user liabilities.

All examples use Sarah Chen's accounts from the [Getting Started](/guides/use-cases/pfm/getting-started) guide.

## Transaction Stream & Spend Management

### Listing Transactions

Transactions provide transaction-level detail for connected Visa and Mastercard credit card accounts. Once subscribed, you can query historical transactions and receive new ones in real time via webhooks.

Retrieve recent transactions for Sarah's Chase Sapphire Reserve card:

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl "https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/transactions?from_date=2025-09-01&to_date=2025-09-15" \
      -X GET \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "data": [
        {
          "id": "txn_t73AdHRFYwhT9",
          "account_id": "acc_eKKmrXDpJBKgw",
          "status": "posted",
          "descriptor": "SQ *BLUE BOTTLE COFF",
          "merchant": {
            "name": "Blue Bottle Coffee",
            "logo": null
          },
          "merchant_category_code": "5814",
          "amount": 675,
          "auth_amount": 675,
          "currency_code": "USD",
          "transaction_amount": 675,
          "transaction_auth_amount": 675,
          "transaction_currency_code": "USD",
          "transacted_at": "2025-09-14T08:22:00.000Z",
          "posted_at": "2025-09-15T05:00:00.000Z",
          "voided_at": null,
          "original_txn_id": null,
          "created_at": "2025-09-14T08:22:00.000Z",
          "updated_at": "2025-09-15T05:00:00.000Z"
        },
        {
          "id": "txn_kP4mRvTnBcWx2",
          "account_id": "acc_eKKmrXDpJBKgw",
          "status": "posted",
          "descriptor": "WHOLE FOODS MKT #1042",
          "merchant": {
            "name": "Whole Foods Market",
            "logo": null
          },
          "merchant_category_code": "5411",
          "amount": 8743,
          "auth_amount": 8743,
          "currency_code": "USD",
          "transaction_amount": 8743,
          "transaction_auth_amount": 8743,
          "transaction_currency_code": "USD",
          "transacted_at": "2025-09-12T18:45:00.000Z",
          "posted_at": "2025-09-13T05:00:00.000Z",
          "voided_at": null,
          "original_txn_id": null,
          "created_at": "2025-09-12T18:45:00.000Z",
          "updated_at": "2025-09-13T05:00:00.000Z"
        },
        {
          "id": "txn_qN7jWvHmDfRa5",
          "account_id": "acc_eKKmrXDpJBKgw",
          "status": "posted",
          "descriptor": "SHELL OIL 57442",
          "merchant": {
            "name": "Shell",
            "logo": null
          },
          "merchant_category_code": "5541",
          "amount": 5218,
          "auth_amount": 5218,
          "currency_code": "USD",
          "transaction_amount": 5218,
          "transaction_auth_amount": 5218,
          "transaction_currency_code": "USD",
          "transacted_at": "2025-09-10T14:30:00.000Z",
          "posted_at": "2025-09-11T05:00:00.000Z",
          "voided_at": null,
          "original_txn_id": null,
          "created_at": "2025-09-10T14:30:00.000Z",
          "updated_at": "2025-09-11T05:00:00.000Z"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

Sarah's recent transactions show \$6.75 at Blue Bottle Coffee, \$87.43 at Whole Foods, and \$52.18 at Shell. All amounts are in cents. The `merchant_category_code` enables spend categorization (5814 = restaurants, 5411 = grocery, 5541 = gas stations).

### Subscribing to Transactions

Transaction data requires an active subscription. Enroll Sarah's Chase card to receive transaction events in real time:

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/subscriptions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "enroll": "transaction"
      }'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "sub_P8c4bjj6xajxF",
      "name": "transaction",
      "status": "active",
      "payload": null,
      "latest_request_id": null,
      "created_at": "2025-09-15T15:40:00.000Z",
      "updated_at": "2025-09-15T15:40:00.000Z"
    }
    ```
  </Tab>
</Tabs>

With the subscription active, Method fires webhook events for both authorization events (when Sarah swipes her card) and settlement events (when the transaction clears). This enables real-time spend alerts, budget tracking, and transaction feeds.

<Warning>
  Transaction streaming is available for Visa and Mastercard credit cards. Not all card accounts will support transactions — check the account's `products` array to confirm `transaction` is available.
</Warning>

***

## Bill Pay & Debt Repayment

### Getting a Fresh Balance Before Payment

Before initiating a payment, pull the latest balance to ensure accuracy. If you've already subscribed to updates (covered in the [Dashboard & Insights](/guides/use-cases/pfm/monitoring-insights) guide), you'll have recent data. Otherwise, request an on-demand update:

```bash theme={null}
curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/updates \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

The completed update confirms Sarah's Chase card balance is \$800.00 (`80000` cents) with a minimum payment of \$25.00 due on October 1st. She decides to pay \$500.00 toward the balance.

### Creating a Payment

[Payments](/guides/payments/overview) move money from your platform's verified funding account (ACH) to a liability account. Your corporate funding account `acc_hmap9mbgfLcf9` serves as the payment source for all user payments.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/payments \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 50000,
        "source": "acc_hmap9mbgfLcf9",
        "destination": "acc_eKKmrXDpJBKgw",
        "description": "Chase Pmt"
      }'
    ```
  </Tab>

  <Tab title="Response (pending)">
    ```json theme={null}
    {
      "id": "pmt_VeCfmkwGKb",
      "source": "acc_hmap9mbgfLcf9",
      "destination": "acc_eKKmrXDpJBKgw",
      "amount": 50000,
      "description": "Chase Pmt",
      "status": "pending",
      "estimated_completion_date": "2025-09-18",
      "source_trace_id": null,
      "source_settlement_date": "2025-09-16",
      "source_status": "pending",
      "destination_trace_id": null,
      "destination_settlement_date": "2025-09-18",
      "destination_payment_method": "paper",
      "destination_status": "pending",
      "reversal_id": null,
      "error": null,
      "metadata": null,
      "created_at": "2025-09-15T16:00:00.000Z",
      "updated_at": "2025-09-15T16:00:00.000Z"
    }
    ```
  </Tab>
</Tabs>

The payment is created with `status: "pending"` and an estimated completion date of September 18th. The `description` field (max 10 characters) appears on the user's bank statement.

<Note>
  All amounts are in **cents**. `50000` = \$500.00. The `description` field has a maximum length of 10 characters.
</Note>

### Payment Lifecycle

Payments move through a lifecycle from creation to settlement. Track progress via webhook events:

Once the payment settles, the status transitions to `posted`:

```json theme={null}
{
  "id": "pmt_VeCfmkwGKb",
  "source": "acc_hmap9mbgfLcf9",
  "destination": "acc_eKKmrXDpJBKgw",
  "amount": 50000,
  "description": "Chase Pmt",
  "status": "posted",
  "estimated_completion_date": "2025-09-18",
  "source_trace_id": "203942084920",
  "source_settlement_date": "2025-09-16",
  "source_status": "posted",
  "destination_trace_id": "304820184832",
  "destination_settlement_date": "2025-09-18",
  "destination_payment_method": "paper",
  "destination_status": "posted",
  "reversal_id": null,
  "error": null,
  "metadata": null,
  "created_at": "2025-09-15T16:00:00.000Z",
  "updated_at": "2025-09-18T12:00:00.000Z"
}
```

## Putting It All Together

With transactions and payments, Sarah's PFM experience is complete:

| Capability         | Product                                                    | Example                                           |
| ------------------ | ---------------------------------------------------------- | ------------------------------------------------- |
| View all debts     | [Connect](/guides/connect/overview)                        | 6 liabilities discovered automatically            |
| Real-time balances | [Updates](/guides/updates/overview)                        | Chase card: \$800.00 balance, \$25.00 minimum due |
| Card visuals       | [Card Brand](/guides/additional-products/card-brand)       | Chase Sapphire Reserve card art                   |
| Credit score       | [Credit Scores](/guides/additional-products/credit-scores) | VantageScore 4.0: 734                             |
| Financial health   | [Attributes](/guides/additional-products/attributes)       | 22% utilization, 100% payment history             |
| Spending activity  | Transactions                                               | Coffee, groceries, gas — categorized in real time |
| Bill pay           | [Payments](/guides/payments/overview)                      | \$500 payment to Chase, settled in 3 days         |

<CardGroup>
  <Card title="Payments Lifecycle" icon="arrows-spin" href="/guides/payments/lifecycle">
    Deep dive into payment states, timing, and error handling.
  </Card>

  <Card title="Payment Errors" icon="triangle-exclamation" href="/guides/payments/errors">
    Understanding and handling payment failures and reversals.
  </Card>
</CardGroup>


# December Updates
Source: https://docs.methodfi.com/changelog/2024/december



## New Features

### New Method Dashboard

<img alt="title" />

We’re thrilled to announce early access to the **all-new Method Dashboard**, purposefully redesigned to harness the full potential of our API’s V2 capabilities.

This intuitive interface is crafted to empower both technical and non-technical team members with:

* Role-based access control
* Advanced data visualization
* Custom reporting capabilities
* Universal search functionality
* Self-service team management
* Key rotation tools
* SSO and Passkey authentication

Everyone across your team can now use the new Method Dashboard:

* **CX** – monitor and troubleshoot any issues associated with end-user data.
* **Engineering** – create API keys and monitor webhooks.
* **Finance** – view high-level metrics to better understand billing.

**How to access?**
Dashboard v2 is available for all teams, including existing ones, ensuring a seamless transition to the new interface.
Log in with your email at [app.methodfi.com](https://app.methodfi.com) to explore the new features!

### Vehicles API

<img alt="title" />

The [Vehicles API](https://docs.methodfi.com/reference/entities/vehicles/overview) enables your application to access detailed vehicle information with minimal PII. This data can help you unlock valuable insights and drive better decision-making.

**Key Use Cases**

* **Increase conversion** with pre-filled vehicle details by optimizing loan repayment terms using the vehicle's depreciation curve.
* **Enhance credit risk underwriting** by leveraging vehicle ownership details.
* **Enable personalized financial management** by correlating vehicle data with user behavior insights.

For example, you can retrieve data such as the vehicle's `VIN`, `year`, `make`, `model`, `color`, and `style`.

The Vehicles API is now available to all teams on Method’s V2 API (version: 2024-04-04). Contact your Method CSM to get access!

***

## Improvements

### Account Verification Limits

To bolster system security and performance, we've introduced new verification limits:

* **Account Verification Session limits**: Up to 10 failed attempts per session.
* **Account-level verification limits**:
  * Maximum of 5 sessions per verification type.
  * Maximum of 10 total sessions across all types.

For more details, visit [Account Verification Sessions Errors](https://docs.methodfi.com/reference/errors/account-verification-session-errors).

***

## SDK Updates

* Released [version 1.1.5](https://github.com/MethodFi/method-python/releases/tag/v1.1.5) of `method-python`.
  * [Vehicles API](https://docs.methodfi.com/reference/entities/vehicles/overview) is now available in `method-python`.
* Released [version 1.1.6](https://github.com/MethodFi/method-node/releases/tag/v1.1.6) of `method-node`.
  * [Vehicles API](https://docs.methodfi.com/reference/entities/vehicles/overview) is now available in `method-node`.


# November Updates
Source: https://docs.methodfi.com/changelog/2024/november



## New Features

### Payment Posted Confirmation

<img alt="title" />

We’re excited to announce [`posted`](https://docs.methodfi.com/reference/payments/overview#possible-enum-values:~:text=The%20Payment%20has%20been%20posted%20to%20the%20destination%20Account), a new payment status that closes the loop on payments by confirming when they have successfully landed in your users’ accounts.

With **real-time account data**, Method now provides a level of visibility that was previously unavailable in the U.S. financial system. By knowing if and when a payment has been applied, you can deliver timely and actionable updates to your users—boosting confidence and creating a seamless payment experience.

**Key highlights:**

* **Enabled for all payments**: The feature is live for all teams and payments processed via Method’s V2 API (version: `2024-04-04`) going forward.
* **No action required**: Start using this feature immediately—just consume the new status in your integration.
* **75% coverage**: We expect approximately 75% visibility into posted status, with improved coverage as more accounts are subscribed to updates.
* **Unlock new use cases**: Use the posted status to notify users via push notifications, emails, or in-app messages, keeping them informed and engaged.
* **Account subscription required**: In a future release, the posted status will only be available for accounts subscribed to updates.

### New Method Brand

<img alt="title" />

We’re excited to introduce Method’s new visual identity, marking a new chapter in our journey under the same thesis we had on day one: consumer financial data is a walled garden, and we’re going to be the ones to open it up.

The updated design features:

* A new icon and wordmark
* A refined color palette centered around Method Opal: a bold, fresh, and vibrant cyan
* A new [website](https://methodfi.com/)

Read more about the redesign [here](https://methodfi.com/blog/rebranding-method).

***

## Improvements

### Detailed Webhook Errors

[Webhook Errors](https://docs.methodfi.com/reference/errors/webhook-errors) now includes detailed explanations of issues that caused your webhook to be disabled.

Webhook objects now feature an `error` field following the common Method error format. The error codes for webhook errors are:

* 25001 – `WEBHOOK_DISABLED_FAILED_OTHER`: Indicates five consecutive failures not classified as 4XX, 5XX, or timeouts.
* 25002 – `WEBHOOK_DISABLED_RECEIVED_4XX_ERROR`: The endpoint returned client errors (4XX) five times.
* 25003 – `WEBHOOK_DISABLED_RECEIVED_5XX_ERROR`: The endpoint returned server errors (5XX) five times.
* 25004 – `WEBHOOK_DISABLED_TIMEOUT_ON_RESPONSE`: No valid response received within 5 seconds for five consecutive attempts.

### New List Endpoints

We’ve expanded our API capabilities by introducing list functionality for the following resources, allowing you to retrieve comprehensive collections, such as all updates or credit scores, for a specific account or entity.

* [Attributes](https://docs.methodfi.com/reference/entities/attributes/list)
* [Credit Scores](https://docs.methodfi.com/reference/entities/credit-scores/list)
* [Connects](https://docs.methodfi.com/reference/entities/connect/list)
* [Identities](https://docs.methodfi.com/reference/entities/identities/list)
* [Entity Verification Sessions](https://docs.methodfi.com/reference/entities/verification-sessions/list)
* [Card Brands](https://docs.methodfi.com/reference/accounts/card-brands/list)
* [Account Updates](https://docs.methodfi.com/reference/accounts/updates/list)
* [Payoffs](https://docs.methodfi.com/reference/accounts/payoffs/list)
* [Sensitive](https://docs.methodfi.com/reference/accounts/sensitive/list)
* [Account Balances](https://docs.methodfi.com/reference/accounts/balances/list)
* [Account Verification Sessions](https://docs.methodfi.com/reference/accounts/verification-sessions/list)

### Elements API

* Removed the ability to pass in `card_brand` in the `products` array when creating an [Element Token](https://docs.methodfi.com/reference/elements/tokens).

***

## SDK Updates

* Released [version 1.1.4](https://github.com/MethodFi/method-python/releases/tag/v1.1.4) of Method Python client (`method-python`).
  * All new `list` endpoints are now available in the Python client.
  * Added `posted` as an enum value for the `payment.status` field.
* Released [version 1.1.5](https://github.com/MethodFi/method-node/releases/tag/v1.1.5) of Method Node.js client (`method-node`).
  * All new `list` endpoints are now available in the Node.js client.
  * Added `posted` as an enum value for the `payment.status` field.


# October Updates
Source: https://docs.methodfi.com/changelog/2024/october



## New Products

### Events API

<img alt="title" />

The [Events API](https://docs.methodfi.com/reference/events/overview) allows your application to monitor specific changes to Method resources.

* For example, you can now be notified when an entity's credit score increases (event type: `credit_score.increased`)
  or if new derogatory marks appear (event type: `attribute.credit_health_derogatory_marks.increased`)

* Events deliver detailed and actionable notifications across all Method products and resources, making webhooks more targeted and specific.
  This ensures you receive alerts for the updates that matter to your application and users.

* Events are classified into two types:
  * Literal changes: Direct updates to a specific field in a resource.
  * Computed changes: Interpreted states derived from multiple field changes or comparisons across different records.

* The Events API is now available to all teams on Method’s V2 API (version: 2024-04-04). This launch includes 10 initial events, with over 100 additional events planned for release in the coming weeks.

### Attributes API

<img alt="title" />

The [Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview) offers a powerful summary of financial profile metrics across all Method API resources.

* For example, it provides real-time indicators on credit utilization, payment reliability, account age, and derogatory marks, allowing developers to access these metrics directly without piecing together data from multiple endpoints.

* Powered by Method’s real-time data integrations, it provides up-to-date insights ensuring your application accesses the most current data for faster, more informed decisions.

* This initial release emphasizes credit health attributes, offering a holistic view of financial stability and risk.

* For information on accessing the Attributes API, please reach out to your Method CSM.

***

## Improvements

### Card Brands API

* Improved our card network integrations (Visa and Mastercard) to deliver lower latencies on Card Brands API requests.
* Expanded coverage across all card products, including providing a reliable unique ID associated with each card product (for example all Chase Sapphire Reserve's across all entities will return the same brand ID)
  * Brand ID is returned within `card_brand.brands[x].id` in the format `brand_*`.

### Credit Scores API

* We've upgraded our Credit Scores API to use VantageScore 4.0, the latest version of the scoring model.
* VantageScore 4.0 provides more predictive scoring by incorporating machine learning techniques and trended credit data, which analyzes credit behaviors over time rather than just a snapshot.
* This upgrade enables more accurate credit risk assessment, especially for consumers with limited credit history.

***

## SDK Updates

* Released [version 1.1.2](https://github.com/MethodFi/method-python/releases/tag/v1.1.2) of Method Python client (`method-python`).
  * [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview) is now available in the Python client.
  * [Events API](https://docs.methodfi.com/reference/events/overview) is now available in the Python client.
* Released [version 1.1.3](https://github.com/MethodFi/method-node/releases/tag/v1.1.3) of Method Node.js client (`method-node`).
  * [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview) is now available in the Node.js client.
  * [Events API](https://docs.methodfi.com/reference/events/overview) is now available in the Node.js client.
* Released [version 2 of Method API Postman Collection](https://www.postman.com/methodfi/method-api/collection/8d5j00b/method-api-v2).


# September Updates
Source: https://docs.methodfi.com/changelog/2024/september



## Improvements

### Performance & Infrastructure

* Improved idempotency locking mechanism to handle simultaneous idempotent requests received across different regions / PoP.
* Under-the-hood liability payment rail improvements to faster settlement time across all major FIs.
* Card Brand has been optimized for increased success speed.
* Expanded checks for invalid update payload from upstream data providers.

### Payment Coverage

* Released new integration with SoFi Personal Loans for near real-time payment settlement speed.
* Payment channels for Sallie Mae, US Bank, and AMEX have been revamped and optimized for speed of posting.
* Additional personal loan payment channels have been enabled - improving payment coverage and speed to posting.
* BMO Harris credit cards are now fully payable when account is connected via Method Connect.

### Developer Experience

* `micro_deposits` verification sessions are now simulatable in dev.
* Speed of `micro_deposists` simulation in dev environment has been increased.
* Expanded Card Brand simulated response in dev environment.
* Improved Student Loans [updates](https://docs.methodfi.com/reference/accounts/updates/overview) documentation for dev environment responses.
* Element now throws an error if any of the requested products are not enabled for the requesting team.

### Account Connectivity

* Improved account update stability for Quicken Loans, Home Depot (Citi), Credit One, and other major FIs.
* "Instant Link" verification was optimized across all networks.
* Visual interaction during the manual Connect Element flow have been streamlined to optimize for conversion.

### Reporting

* Daily emailed reconciliation reports now include the team name in the subject line.
  * e.g. (`Method: Daily ACH Report`) -> (`Method: Daily ACH Report for ${team_name}`)

***

## SDK Updates

* Released [version 1.1.0](https://github.com/MethodFi/method-python/releases/tag/v1.1.0) of Method Python client (`method-python`).
  * [Request ID](/reference/request-id) is now easily accessible via the `last_response` property - we highly recommend logging the request ID for faster issue resolution.
  * This update also includes security updates and test coverage expansion.
* Released [version 1.1.1](https://github.com/MethodFi/method-node/releases/tag/v1.1.1) of Method Node.js client (`method-node`).
  * [Request ID](/reference/request-id) is now easily accessible via the `last_response` property - we highly recommend logging the request ID for faster issue resolution.
  * This update also includes security updates and test coverage expansion.


# April Updates
Source: https://docs.methodfi.com/changelog/2025/april



## New Features

### Dashboard Updates

<img alt="sso" />

We're continuing to improve the Dashboard experience with a few powerful updates:

* **SSO Support** – You can now log in using Single Sign-On. Reach out to your Method CSM to enable SSO for your team.
* **Multi-Team Search** – If you're a member of multiple teams, you can now quickly search and switch between them with ease.
* **PDF Export** – It is now possible to download Entity and Account details as a PDF. Contact your Method CSM to get access to this feature.

## Improvements

### Entity Attribute Handling

We've updated how Entity Attributes are requested. You must now explicitly specify which attributes you'd like to retrieve using a new payload format.

<Warning>Some attributes are restricted by default. Reach out to your Method CSM to get access to these attributes.</Warning>

<Accordion title="Previous">
  ```js theme={null}
  const response = await method
      .entities('ent_TYHMaRJUUeJ7U')
      .attributes
      .create();
  ```
</Accordion>

<Accordion title="New">
  ```js theme={null}
  const response = await method
      .entities('ent_TYHMaRJUUeJ7U')
      .attributes
      .create({
          attributes: [
              "credit_health_credit_card_usage",
              "credit_health_derogatory_marks",
              "credit_health_hard_inquiries",
              "credit_health_soft_inquiries",
              "credit_health_total_accounts",
              "credit_health_credit_age",
              "credit_health_payment_history",
              "credit_health_open_accounts",
              "credit_health_entity_delinquent"
          ]
      });
  ```
</Accordion>

For more details, refer to the [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/create).

### Entity Subscription Creation

Entity subscription creation has been updated to support a new payload format.

<Accordion title="Previous">
  ```js theme={null}
  const response = await method
    .entities('ent_TYHMaRJUUeJ7U')
    .subscriptions
    .create('credit_score');
  ```
</Accordion>

<Accordion title="New">
  ```js theme={null}
  const response = await method
    .entities('ent_TYHMaRJUUeJ7U')
    .subscriptions
    .create({
      enroll: 'credit_score',
    });
  ```
</Accordion>

To enroll in an Entity Attribute subscription, use this format:

```js theme={null}
const response = await method
  .entities('ent_TYHMaRJUUeJ7U')
  .subscriptions
  .create({
    enroll: 'attribute',
    payload: {
      attributes: {
        requested_attributes: [
            'credit_health_credit_card_usage', 
            'credit_health_derogatory_marks'
        ]
      }
    }
  });
```

For more details, refer to the [Entity Subscriptions API](https://docs.methodfi.com/reference/entities/subscriptions/create).

## SDK Updates

* Released [version 1.1.14](https://github.com/MethodFi/method-node/releases/tag/v1.1.14) of `method-node`
* Released [version 1.1.13](https://github.com/MethodFi/method-python/releases/tag/v1.1.13) of `method-python`


# August Updates
Source: https://docs.methodfi.com/changelog/2025/august



## New Features

### Opal

<img alt="opal" />

We're excited to introduce [Opal](/opal/overview), our new embedded UI that can easily be dropped into your existing onboarding flow, enabling a white-labeled, seamless connection to Method. It replaces our current Element UI, allowing you to customize the copy, themes, and other UI components to maintain continuity in your interface and prevent users from feeling like they are moving to a third-party app.

Opal has four different components:

* **Identity Verification (IDV):** collects, confirms, and verifies a user’s identity
* **Connect (CXN):** surfaces all of a user's liability accounts
* **Account Verification (AVF):** verifies credit card details and tokenizes them for payments and checkout use cases
* **Transactions (TXN):** enables users to select cards that they wish to link transaction data

**How it works:**

* Opal is a drop-in SDK, designed for quick and easy integration with minimal effort to implement
* Launch with a single token that’s generated with a mode (e.g., connect, card connect, etc.) and whatever additional parameters you choose
* Once launched, Method handles all of the business logic of the flow, automatically orchestrating all of the information the user needs to provide and determining what part of the flow to route the user to next
* Tokens are persistent - users can pick up exactly where they dropped off
* UI is embedded via JavaScript, React, or React Native

For more information, please visit the [Opal Quickstart](/opal/quickstart) page.


# December Updates
Source: https://docs.methodfi.com/changelog/2025/december



## New features

### Payment Instruments API

Method now supports inbound funding workflows. We’ve added a new `PaymentInstrument` type: `inbound_achwire_payment` which allows liability accounts (e.g., loans, credit cards) to receive direct payments via ACH or wire transfer.

* This feature provisions a unique virtual account number and routing number linked to a specific Method Account, effectively making the underlying liability routable. Third parties can send funds directly to these credentials, and Method automatically applies the funds to the associated account, without requiring you to explicitly create a Payment.

**How it works:**

1. **Create Instrument**: Create a Payment Instrument of type `inbound_achwire_payment` for a specific Method Account
2. **Receive Banking Details**: Method returns unique `account_number` and `routing_number`
3. **Share with a Third Party**: Provide these banking details to a third party (e.g., payroll provider, refinance lender, or another bank)
4. **Inbound Transfer**: When funds are sent to these credentials, Method receives the inbound ACH or wire transfer
5. **Automatic Application**: Method automatically applies the received funds to the associated account

<Note>Available when passing `Method-Version: 2025-12-01` in the request header.</Note>

## Improvements

### Simulate API

The [Simulate API](/reference/simulations/overview) now supports retrieving micro-deposit amounts and simulating inbound ACH / wire payments for inbound\_achwire\_payment Payment Instruments — making it easier for developers to test account verification and inbound payment flows in the development environment.

**[Retrieve Micro-deposit Amounts](/reference/simulations/verification-sessions/get-microdeposit-amounts)**

* This endpoint enables developers to retrieve the exact micro-deposit amounts required to complete ACH account verification flows in the development environment.

**[Simulate Inbound ACH/Wire Payments](/reference/simulations/payment_instruments/create)**

* This endpoint allows developers to simulate receiving an inbound payment and triggers the same automatic payment application logic used in production.

<Warning>This API is available in the development environment only.</Warning>

For more information, visit the [Simulations API](/reference/simulations/overview) documentation.

### Webhooks

We added support for a new webhook event type: `account.number.update`.

* This account-level webhook is triggered when an account number has been updated, allowing developers to be notified of account number changes without polling.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Entities API

The Entities API now supports updating `metadata` via `PUT /entities/{ent_id}`.

* This enables developers to update an Entity's metadata without recreating the Entity, simplifying lifecycle management.

For more information, please refer to the [Update an Entity](/reference/entities/update-entity) documentation.


# February Updates
Source: https://docs.methodfi.com/changelog/2025/february



## New Features

### Dashboard Payment Details Page

<img alt="payment details" />

We've upgraded the Payments experience with a brand-new dedicated Payment Details Page

Now, you get more insights and control than ever before:

* **Payment Timeline** –> Track the full journey of your payments, end to end.
* **Enhanced Payment Info** –> Quickly see whether a payment was made via electronic or paper.
* **Check Images** –> For paper payments, view the check image (if available) directly within the details page.

## Improvements

### Payments API

We've added two new fields to the Payments API to provide better visibility into payment details:

* `destination_payment_method`: Indicates how the payment was delivered to the recipient - either `electronic` or `paper`
* `destination_status`: New status `cashed` available to track when paper checks have been processed

For more information, see our [Payments API documentation](https://docs.methodfi.com/reference/payments/overview).

## SDK Updates

* Released [version 1.1.9](https://github.com/MethodFi/method-python/releases/tag/v1.1.9) of `method-python`
* Released [version 1.1.10](https://github.com/MethodFi/method-node/releases/tag/v1.1.10) of `method-node`


# January Updates
Source: https://docs.methodfi.com/changelog/2025/january



## New Features

### Account Attributes API

<img alt="account attributes" />

We've released a brand new [Account Attributes API](https://docs.methodfi.com/reference/accounts/attributes/overview) that's powered by Method's real-time data integrations for up-to-date insights. It provides:

* Real-time indicators for individual account usage patterns
* Account utilization metrics
* Account standing information
* Delinquency data (period, outcome, and amount)

For access to the Account Attributes API, please contact your Method CSM.

## Improvements

### Entity Attributes API

We've enhanced the [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview) with two new attributes:

* `credit_health_open_accounts`: Total number of open accounts
* `credit_health_entity_delinquent`: Entity delinquency status, rating and a list of delinquent accounts

**Pro tip**: Leverage both the Account Attributes API and the Entity Attributes API to get a holistic view of an entity's credit health.

### Method Dashboard

We've made significant performance and usability improvements to the [Method Dashboard](https://app.methodfi.com):

* Pages load 3x faster. We also made navigating between pages feel a lot better.
* Charts load 2x faster. We also fixed hovering over the bars so it works well.
* Universal Search is now keyboard navigable. You can use your up/down arrows and hit enter.
* Added the ability to right click on a table row and open it in a new tab.
* Created better financial account logos. We will continue to fix bad ones.
* Changed the layout of information on details pages to make reading easier.

Please reach out in Slack with any feedback. We will put your requests at the top of our to-do list.

### Payment Dry-run

We've added a new `dry_run` boolean flag to the `POST /payments` endpoint. When enabled, it will simulate a payment without triggering the actual payment flow. You'll receive accurate information about the payment timeline, helping you preview the payment flow and communicate accurate timing to your users before initiating an actual payment. For more information, see our [Payments API](https://docs.methodfi.com/reference/payments/overview).

## SDK Updates

* Released [version 1.1.8](https://github.com/MethodFi/method-python/releases/tag/v1.1.8) of `method-python`
* Released [version 1.1.9](https://github.com/MethodFi/method-node/releases/tag/v1.1.9) of `method-node`


# July Updates
Source: https://docs.methodfi.com/changelog/2025/july



## New Features

### Message-Level Encryption (MLE)

<img alt="MLE" />

We’ve added support for end-to-end encryption of sensitive data transmitted between your application and Method’s API, available to everyone. Here’s what’s new:

* **Hybrid Encryption:** Uses AES-GCM (for payload encryption) and RSA-OAEP-256 (for key encryption) to ensure confidentiality even if network traffic is intercepted.

* **Public Key Registration:** Register your RSA public key with Method via a `.well-known` endpoint or direct upload.

* **Encrypted Requests & Responses:** Send encrypted payloads using the `Method-MLE: jwe` header; Method encrypts responses using your public key.

* **Key Management:** Support for key rotation, deprecation, deletion, and webhook notifications for Method key changes.

You can find a [quickstart guide here](/reference/message-level-encryption#quickstart). For more information, please refer to the [Message Level Encryption documentation](/reference/message-level-encryption).

### Card Brand API

<img alt="Card Brands" />

We’ve expanded the Card Brand object to provide a more structured format with richer brand details — making it easier to identify, display, and integrate specific card products with consistent issuer, network, and branding data.

<Note>Available when passing `Method-Version: 2025-07-04` in the request header.</Note>

<Accordion title="Previous">
  ```json theme={null}
  {
    "id": "cbrd_eVMDNUPfrFk3e",
    "account_id": "acc_yVf3mkzbhz9tj",
    "network": "visa",
    "issuer": "Chase",
    "last4": "8623",
    "brands": [
      {
        "id": "brand_AMxtjQzAfDCRP",
        "name": "Chase Sapphire Reserve",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
      }
    ],
    "status": "completed",
    "shared": false,
    "source": "network",
    "error": null,
    "created_at": "2024-03-19T01:05:37.247Z",
    "updated_at": "2024-03-19T01:05:37.247Z"
  }
  ```
</Accordion>

<Accordion title="New">
  ```json theme={null}
  {
    "id": "cbrd_Accm7P6t6mYQP",
    "account_id": "acc_LxwEqNicr66yP",
    "brands": [
      {
        "id": "pdt_15_brd_1",
        "card_product_id": "pdt_15",
        "description": "Chase Sapphire Reserve",
        "name": "Chase Sapphire Reserve",
        "issuer": "Chase",
        "network": "visa",
        "network_tier": "infinite",
        "type": "specific",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
      }
    ],
    "status": "completed",
    "source": "method",
    "error": null,
    "created_at": "2025-08-12T00:56:50.139Z",
    "updated_at": "2025-08-12T00:56:50.139Z"
  }
  ```
</Accordion>

**Key Changes**:

* `network` and `issuer` are now nested inside each brand object.
* Added `card_product_id`, `description`, and `type` fields.
* Removed `last4` and `shared` fields.

For more information, please refer to the [Card Brand API](/reference/accounts/card-brands/overview).

### Card Products API

We've added a new `Card Products` directory accesible via our API allowing you to retrieve all `Card Brand` objects associated with a given `Card Product`.

<Note>Available when passing `Method-Version: 2025-07-04` in the request header.</Note>

<Accordion title="Example Request">
  ```bash cURL theme={null}
  curl https://production.methodfi.com/card_products/pdt_17 \
    -H "Method-Version: 2025-07-04" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```
</Accordion>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "pdt_17",
    "name": "Chase Freedom",
    "issuer": "Chase",
    "type": "specific",
    "brands": [
      {
          "id": "pdt_17_brd_1",
          "description": "Chase Freedom",
          "network": "visa",
          "network_tier": "signature",
          "default_image": "https://static.methodfi.com/card_brands/fb5fbd6a5d45b942752b9dc641b93d1f.png"
      },
      {
        "id": "pdt_17_brd_2",
        "description": "Chase Freedom",
        "network": "visa",
        "network_tier": "standard",
        "default_image": "https://static.methodfi.com/card_brands/6cb697528b0771f982f7c0e8b8869de3.png"
      }
    ]
  }
  ```
</Accordion>

For more information, please refer to the [Card Products API](/reference/card-products/overview).

## Improvements

### Connect API

We now support asynchronous Connect requests. You'll receive a `connect.available` webhook when an Async Connect is completed. Async Connect requests can be created by either:

* Setting the `Prefer: respond-async` header
* Specifying `products` and / or `subscriptions` in the request body

The Connect object will now include `requested_products` and `requested_subscriptions` fields in the response body.

<Accordion title="Example Request">
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/connect \
    -X POST \
    -H "Prefer: respond-async" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -d '{
      "requested_products": ["card_brand"],
      "requested_subscriptions": ["card_brand"]
    }'
  ```
</Accordion>

<Accordion title="Example Response after Connect is completed">
  ```json theme={null}
  {
    "id": "cxn_4ewMmBbjYDMR4",
    "entity_id": "ent_qKNBB68bfHGNA",
    "status": "completed",
    "accounts": [
      "acc_eKKmrXDpJBKgw",
      "acc_GV8WbmJW7KGRy",
      "acc_MLPKh9gQDDbT8",
      "acc_LbXE8wVYJLrKt",
      "acc_J3P9fayDFjpAy",
      "acc_eFFRV9zmpLREK"
    ],
    "requested_products": ["card_brand"],
    "requested_subscriptions": ["card_brand"],
    "error": null,
    "created_at": "2024-04-12T14:56:46.645Z",
    "updated_at": "2024-04-12T14:56:46.645Z"
  }
  ```
</Accordion>

For more information, please refer to the [Connect API](/reference/entities/connect/overview).

### Webhook API

We've added a new `refs` object to webhook payloads. This object contains the `entity` ID of the Entity that the webhook is related to.

<Accordion title="Example Webhook Payload">
  ```json theme={null}
  {
    "webhook_id": "whk_cSGjA6d9N8y8R",
    "id": "pmt_zR3nJG3c99P3X",
    "type": "payment.update",
    "op": "update",
    "path": "/payments/pmt_zR3nJG3c99P3X",
    "event": "evt_knqJgxKUnqDVJ",
    "refs": {
      "entity": "ent_qKNBB68bfHGNA"
    }
  }
  ```
</Accordion>

We have also added the following new webhooks:

* `card_brand.available`
* `connect.available`
* `method_jwk.create`
* `method_jwk.update`

For more information, please refer to the [Webhooks API](/reference/webhooks/overview).

### Entity and Account Products

The `product_id` field in the `Product` object and the Retrieve endpoint are now deprecated. We've added the `latest_successful_request_id` field to the `Product` object. This field will contain the ID of the most recently successful Product resource.

For more information, please refer to the [Entity Products API](/reference/entities/products/overview) and [Account Products API](/reference/accounts/products/overview).


# June Updates
Source: https://docs.methodfi.com/changelog/2025/june



## New Features

### Webhook HMAC Signature Verification

We’ve added support for HMAC-SHA256 signatures to further secure your webhook integrations. Here's what's new:

* **Signed Webhooks:** When you provide an `hmac_secret` during webhook registration, Method now includes a `method-webhook-signature` header on each webhook request. This signature is an HMAC-SHA256 digest, computed using your `hmac_secret` as the shared secret and the message format `${method-webhook-timestamp}:${raw_payload}`.

* **Timestamp Header:** Every webhook request now includes a `method-webhook-timestamp` header (UNIX timestamp in seconds), allowing you to validate the freshness of requests and prevent replay attacks.

* **Verification:** You can verify the webhook by recreating the HMAC digest locally and comparing it using a timing-safe equality check.

For more information, please refer to the [Webhook API](/reference/webhooks/overview).

## Improvements

### Connect API

* **Automatic Execution of Account Products and Subscriptions:** You can now optionally include `products` and `subscriptions` arrays in the request body when creating a `Connect` for an entity. These will automatically execute upon a successful connection.

* **Expand Query Parameter:** A new `expand` query parameter has been added to the `Connect` object, allowing you to include additional properties within the `accounts` object.

<Accordion title="Example Request">
  ```js theme={null}
  const connect = await method
      .entities('ent_TYHMaRJUUeJ7U')
      .connect
      .create(
          {
              products: ['attribute', 'card_brand'],
              subscriptions: ['card_brand', 'transaction'],
          }, 
          {
              expand: ['accounts.update']
          }
      );
  ```
</Accordion>

For more information, please refer to the [Connect API](https://docs.methodfi.com/reference/entities/connect/overview) and [Expanding Resources](/reference/expanding).

## SDK Updates

* Released [version 1.2.4](https://github.com/MethodFi/method-node/releases/tag/v1.2.4) of `method-node`
* Released [version 1.2.4](https://github.com/MethodFi/method-python/releases/tag/v1.2.4) of `method-python`


# March Updates
Source: https://docs.methodfi.com/changelog/2025/march



## New Features

### Transactions API

<img alt="transactions" />

We’re excited to launch our new [Transactions API](https://docs.methodfi.com/reference/accounts/transactions/overview) which gives real-time notifications directly from the card networks on credit/debit card purchases. Key benefits include:

* **Real-Time Alerts** -> Instantly notify users about new charges.
* **Intelligent Categorization** -> Automatically categorize spending using merchant category codes (MCCs).
* **Enhanced Security** -> Flag unusual transactions and identify spending in unfamiliar locations.
* **Multi-Currency Support** -> Monitor transactions in both USD and foreign currencies.
* **Refund Visibility** -> Gain complete insight into refund statuses.

For access to the Transactions API, please contact your Method CSM.

### Payment Instruments API

Our new [Payment Instruments API](https://docs.methodfi.com/reference/accounts/payment-instruments/overview) enables you to create and retrieve card credentials for checkout processes. This API provides seamless access to card details and network tokens, streamlining payment experiences across your app or platform.

For access to the Payment Instruments API, please contact your Method CSM.

### Simulate Credit Scores API

In `development` environments, you can now leverage the [Simulate Credit Scores API](https://docs.methodfi.com/reference/simulations/credit-scores/create) to simulate custom credit scores. This feature lets you:

* Simulate scores for test entities.
* Customize score values, sources, and models.
* Include contributing factor data for more realistic testing scenarios.

## Improvements

### Entity Attributes API

We've made significant improvements to the [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview).

* **Credit Health Hard Inquiries**: The `credit_health_hard_inquiries` attribute now includes two additional fields in its metadata history:
  * `institution_name`: Identifies the institution that performed the inquiry.
  * `inquiry_date`: Provides the date the inquiry occurred.
* **New Soft Inquiries Attribute**: A new `credit_health_soft_inquiries` attribute has been added. It mirrors the structure of hard inquiries to consistently track soft credit checks along with the associated institution name and inquiry date.

### Updates API

The [Updates API](https://docs.methodfi.com/reference/accounts/updates/overview) response now includes a new field:

* `data_as_of`: A timestamp indicating when the data in the record was last confirmed to be accurate, providing clear insight into the freshness and reliability of the information returned.

### Card Brands API

The [Card Brands API](https://docs.methodfi.com/reference/accounts/card-brands/overview) is now subscribable. This enhancement allows your system to automatically receive updated card brand information in real time. For example, if a user loses their card and receives a new one, the API will promptly reflect these changes, ensuring that your records are always accurate and up to date.

### Accounts API

We've expanded the [Accounts API](https://docs.methodfi.com/reference/accounts/overview) to support additional account types:

* `BNPL` (Buy Now, Pay Later)
* `Fintech`

### Account Verification Sessions API

The [Account Verification Sessions API](https://docs.methodfi.com/reference/accounts/verification-sessions/overview) now supports the `network` verification type. For more information, please see the [Network Verification Sessions API reference](https://docs.methodfi.com/reference/accounts/verification-sessions/update-network).

## SDK Updates

* Released [version 1.1.13](https://github.com/MethodFi/method-node/releases/tag/v1.1.13) of `method-node`
* Released [version 1.1.12](https://github.com/MethodFi/method-python/releases/tag/v1.1.12) of `method-python`


# May Updates
Source: https://docs.methodfi.com/changelog/2025/may



## Improvements

### Transactions API

A new `merchant` property has been added to the `Transaction` object. This field provides the merchant name and logo associated with each transaction.

<Warning>This property is not available by default. You can enable it by contacting your Method CSM.</Warning>

For more information, please refer to the [Transactions API](https://docs.methodfi.com/reference/accounts/transactions/overview).

### Card Brand API

The `CardBrand` object now includes a `source` property. Possible values are:

* `method` – sourced from Method’s internal systems

* `network` – retrieved directly from the card network

* `null` – source is unavailable

For more information, please refer to the [Card Brand API](https://docs.methodfi.com/reference/accounts/card-brands/overview).

## SDK Updates

* Released [version 1.2.2](https://github.com/MethodFi/method-node/releases/tag/v1.2.2) of `method-node`
* Released [version 1.2.2](https://github.com/MethodFi/method-python/releases/tag/v1.2.2) of `method-python`


# November Updates
Source: https://docs.methodfi.com/changelog/2025/november



## Improvements

### Simulate API

The [Simulate API](/reference/simulations/overview) now supports simulating Card Brand subscription behaviors.

**[Simulate Card Brand API](/reference/simulations/card-brands/create)**

* Card Brand simulations let developers designate a card brand for an account with an active Card Brand Subscription by specifying a `brand_id`. This triggers a `card_brand.available` webhook containing the ID of the designated card brand, allowing developers to test card brand-driven workflows in the development environment.

<Warning>This API is available in the development environment only.</Warning>

For more information, visit the [Simulations API](/reference/simulations/overview) and [Card Brand API](/reference/accounts/card-brands/overview) documentation.


# October Updates
Source: https://docs.methodfi.com/changelog/2025/october



## Improvements

### Accounts API

The [Accounts API](/reference/accounts/overview) now includes a new `sub_type` field under the `liability` object. This field provides additional context about a liability account by specifying its sub-type (for example, distinguishing between a `secured` and `unsecured` `personal_loan`).

For more information, please see <a href="/reference/accounts/overview#account-liability-sub-types">Account Liability Sub-Types.</a>

## SDK Updates

* Released [version 2.0.0](https://github.com/MethodFi/method-node/releases/tag/v2.0.0) of `method-node`
* Released [version 2.0.0](https://github.com/MethodFi/method-python/releases/tag/v2.0.0) of `method-python`

These major releases include default support for the **`2025-07-04` API version**, which introduces the new [Card Products API](/changelog/api-versions/2025-07-04) and updated [Card Brand schema](/changelog/api-versions/2025-07-04#card-brand-api).

See the [2025-07-04 API Version](/changelog/api-versions/2025-07-04) for more details.


# September Updates
Source: https://docs.methodfi.com/changelog/2025/september



## New Features

### Dashboard Updates

**Card Brands Directory**

<img alt="card brands directory" />

We released a new tab in the Method Dashboard – Card Brands – displaying Method's proprietary catalog of credit card brands and metadata. This dataset underpins the Card Brands API, which enables exact 1:1 product matching for each credit card in a user’s wallet, meaning you can identify the specific card brand a user is holding. For example, instead of just knowing a user holds a Chase Visa, you can determine if they hold a Chase Sapphire Reserve, Freedom Unlimited, or any co-branded product.

For access to the Card Brands Directory, please contact your Method CSM.

**New Role: Restricted Member**

You can now invite teammates as a Restricted Member. This role is the same as the Member role, except Restricted Members have no access to view end-users PII.

## Improvements

### Simulate API

The [Simulate API](/reference/simulations/overview) now supports simulating Connect and Attributes behaviors for an entity — making it easier for developers to test how Method responds to various data changes without needing to trigger them in production.

**[Simulate Connect API](https://docs.methodfi.com/reference/simulations/connect/create)**

* You can now configure Connect behaviors such as new\_credit\_card\_account. This is useful when testing account-creation flows or verifying how your system handles new data returned from a subsequent Connect. For example, after configuring this behavior, the next time you execute Connect for that entity, a new credit card account will appear in the response — helping you simulate real-world user events like a customer opening a new card.

**[Simulate Attributes API](https://docs.methodfi.com/reference/simulations/attributes/create)**

* Similarly, you can configure Attribute behaviors such as new\_soft\_inquiry to test how your system reacts to changing credit attributes. On the next Attributes request for that entity, the configured behavior will be applied (e.g., a new soft inquiry will be present).

<Warning>This API is available in the development environment only.</Warning>

These new simulation capabilities give you greater control when testing entity lifecycle scenarios and verifying downstream logic — without needing real production data or user actions.

For more information, visit the [Simulations API](/reference/simulations/overview) documentation.


# April Updates
Source: https://docs.methodfi.com/changelog/2026/april



## New Features

### Attributes V2: Entity & Account Attributes

A new version of the [Attributes API](/reference/entities/attributes/overview) introduces 50+ new computed attributes across both Entities and Accounts, giving you a more complete, up-to-date picture of a user's financial health:

* **Utilization & Credit Health**: See a user's credit utilization broken out by account type, with 30/60/90-day trend lines and delta calculations that show whether utilization is rising or falling over time. Includes delinquency flags and payment-to-minimum ratios that help identify users who may be falling behind.
* **Balance & Debt Movement**: Track how balances are changing across a user's full liability portfolio with 30/60/90-day balance change attributes. Understand whether a user is paying down debt or accumulating it, across credit cards, personal loans, mortgages, and installment accounts.
* **Cost of Debt**: Weighted average APR calculations across liability types help you understand what a user is actually paying in interest, useful for refinance targeting, rate optimization, and cross-sell opportunities.
* **Payment Behavior**: Monthly installment estimates, minimum payment totals, and autopay detection give visibility into how a user is managing their obligations and whether they're likely to stay current.

V2 attributes are available at both the Entity level (aggregated across all of a user's accounts) and the Account level (per-account metrics). V2 attributes support webhook delivery and subscriptions, and can be simulated in the development environment via the [Simulations API](/reference/simulations/attributes/create).

For more information, visit the [Attributes API](/reference/entities/attributes/overview) documentation.

### Opal Embeddable Mode

[Opal](/opal/overview) now supports a fully embeddable rendering mode for JavaScript and React integrations. The new embeddable mode allows Opal to be rendered inline within your application's DOM rather than in a modal overlay, giving you full control over layout and positioning.

* **React SDK**: The `@methodfi/opal-react` package has been updated to v1.5.0 with embeddable mode support.
* **JavaScript SDK**: Native JavaScript integrations can now pass `mode: "embeddable"` when initializing Opal.

For more information, visit the [Opal Libraries](/opal/libraries) documentation.

### Managed Accounts API

A new [Managed Accounts API](/reference/managed-accounts/overview) provides programmatic access to Method-managed FBO accounts. You can now retrieve managed account balance information and list transactions for reconciliation:

* `GET /managed_accounts` — list all Managed Accounts on your team
* `GET /managed_accounts/{macc_id}` — retrieve a specific Managed Account
* `GET /managed_accounts/{macc_id}/transactions` — list transactions for a Managed Account

For more information, visit the [Managed Accounts API](/reference/managed-accounts/overview) documentation.

## Improvements

### Opal UI

* **CVV Autofill Detection**: Browsers that autofill CVV fields were sometimes causing silent submission failures because Opal didn't detect the autofilled value. This is now handled correctly, so users who rely on password managers or browser autofill won't hit unexpected errors.
* **Input Trimming**: Whitespace is now automatically stripped from user inputs before submission. This catches a common issue where users copy-paste account numbers or card details with trailing spaces, which would previously cause validation failures.

For more information, visit the [Opal](/opal/overview) documentation.

### Webhooks

**Improved Duplicate Detection**

Previously, webhooks with the same endpoint URL and different authentication credentials (for example, separate webhook configs for staging and production that share a URL) were treated as duplicates, delivering to only one of them. Deduplication now accounts for authentication configuration, so each distinct webhook registration receives its own deliveries as expected.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.


# February Updates
Source: https://docs.methodfi.com/changelog/2026/february



## New Features

### Forwarding Requests: Entity Bindings

The [Forwarding Requests API](/reference/forwarding-requests/overview) now supports `entity` as a binding type. Previously, the `bindings` object only accepted `payment_instrument` and `secret` resource IDs. You can now bind an Entity and reference its data in your forwarding request templates using the `{{entity.field}}` syntax.

This enables use cases where an individual's first and last name need to be forwarded to third-party services alongside the associated account number, without exposing raw PII to your system.

```json Sample Request theme={null}
{
  "bindings": {
    "payment_instrument": "pmt_inst_7TNTTRQwQxWc",
    "secret": "sec_au22b1fbFrmfp",
    "entity": "ent_au22b1FBFJbp8"
  },
  "url": "https://sample-url/v1/tokens",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{secret.value}}"
  },
  "body": "{\"first_name\":\"{{entity.individual.first_name}}\",\"last_name\":\"{{entity.individual.last_name}}\",\"number\":\"{{payment_instrument.card.number}}\"}"
}
```

For more information, visit the [Forwarding Requests API](/reference/forwarding-requests/overview) documentation.

### Credit Score Simulations

The [Simulate API](/reference/simulations/overview) now supports direct event creation for Credit Score simulations.

* **New endpoint**: `POST /simulate/events` with `type` set to `credit_score.increased` or `credit_score.decreased`
* This endpoint allows developers to trigger credit score change events for an Entity with an active Credit Score subscription in the development environment, streamlining the testing of credit score-driven workflows

<Warning>This API is available in the development environment only.</Warning>

For more information, visit the [Simulations API](/reference/simulations/events/create) documentation.

## Improvements

### Updates API

**Student Loan — Opened At**

The [Updates API](/reference/accounts/updates/overview) now surfaces the `opened_at` field for `student_loan` liability accounts when `source` is `direct`. This field returns the date the student loan was originally opened, providing additional context for loan lifecycle analysis, refinance eligibility assessments, and portfolio segmentation.

For more information, visit the [Updates API](/reference/accounts/updates/overview) documentation.

### Webhooks

**New Accounts Surfaced Event**

The `entity.new_accounts_pending_consent` webhook fires when a previously undiscovered liability account surfaces after a user progresses through [Connect](/opal/connect/overview), but only for users who haven't opted into automatic consent for future accounts. For customers using Opal or the Element, this enables you to surface the new account to your end user for explicit consent, and optionally offer them the ability to auto-consent to future accounts going forward. This removes the need to poll the [Accounts API](/reference/accounts/overview) to discover new accounts.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Connect API

**Filter Accounts by Product**

You can now filter accounts by product type when using [Connect](/opal/connect/overview). This allows you to scope a Connect session to only surface accounts relevant to a specific product (e.g., only accounts eligible for payments or only accounts with update subscriptions), reducing noise and improving the end-user experience in targeted workflows.

For more information, visit the [Connect API](/opal/connect/overview) documentation.

### Payment Instruments API

**Card Billing Zip Code**

A new `billing_zip_code` field is now available on `card` type [Payment Instruments](/reference/accounts/payment-instruments/overview). This field is returned as part of the `card` object when retrieving a Payment Instrument.

* `card.billing_zip_code`: The billing zip code associated with the card

This addition supports address verification (AVS) workflows and reduces payment failures caused by billing address mismatches when forwarding card details to third-party processors.

For more information, visit the [Payment Instruments API](/reference/accounts/payment-instruments/overview) documentation.

### Payments API

**Inbound ACH/Wire Trace Numbers & Metadata**

Inbound ACH and wire payments received via `inbound_achwire_payment` [Payment Instruments](/reference/accounts/payment-instruments/overview) now include trace number and metadata fields on the [Payment](/reference/payments/overview) object.

* `source_trace_id`: enables end-to-end payment tracking and reconciliation for inbound transfers
* `destination_trace_id`: provides the underlying bank transaction ID on the destination Account for outbound reconciliation
* `metadata`: allows clients to associate custom reference information with incoming transactions (e.g., you can now add internal reference IDs, ​​customer IDs, and notes in the metadata)

For more information, see the [Payments API](/reference/payments/overview) documentation.

### Versioned API Reference Docs

The API Reference documentation now supports **version-aware navigation**. A version dropdown in the navigation bar lets you switch between API versions (`2025-12-01`, `2025-07-04`, `2024-04-04`) to view the documentation specific to your pinned API version.

Each version renders its own copy of the API Reference with version-specific request examples, response schemas, and available fields — so the docs you see always match the behavior of the API version you're using.

For more information, visit the [Versioning](/reference/versioning) documentation.


# January Updates
Source: https://docs.methodfi.com/changelog/2026/january



## New Features

### Forwarding Requests API

The [Forwarding Requests API](/reference/forwarding-requests/overview) allows you to securely proxy sensitive data (such as card details) to third-party services without your system ever handling the raw data. This enables use cases like payment processing, tokenization, and partner integrations while maintaining the PCI compliance of existing solutions.

**Key capabilities:**

* **Secure data transmission**: Send templated HTTP requests to whitelisted third-party endpoints.
* **Dynamic data injection**: Use template placeholders (e.g., `{{my_binding.card.number}}`) instead of raw values.
* **Binding resolution**: Bind placeholders to Method resources (currently [Payment Instruments](/reference/accounts/payment-instruments/overview)), allowing Method to securely append the underlying data without ever touching your company database.
* **Destination whitelisting**: Requests can only be sent to pre-approved URLs to prevent data exfiltration.
* **Transparent responses**: The third-party response is forwarded directly back to your application without requiring you to make changes to the way you ingest third-party response data.

For more information, visit the [Forwarding Requests API](/reference/forwarding-requests/overview) documentation.

### Secrets API

The [Secrets API](/reference/secrets/overview) allows you to securely store sensitive configuration values (such as API keys or credentials) for use within Method. Secrets are encrypted at rest and never exposed back to client applications.

**Key capabilities:**

* **Encrypted storage**: Store sensitive values and receive a Secret ID (`sec_...`) in return.
* **No client exposure**: Secret values are never returned in API responses.
* **Forwarding integration**: Secrets can be inserted into [Forwarding Requests](/reference/forwarding-requests/overview) for authenticating with third-party services.

For more information, visit the [Secrets API](/reference/secrets/overview) documentation.

### Opal Appearance Customization

You can now customize the visual appearance of [Opal](/opal/overview), Method's embeddable UI, to better match your application's branding or autofit to your users' devices.

When opening Opal with the client SDK, specify an `appearance` option with one of the following values:

* `light`: Standard light theme (default)
* `dark`: Dark theme for low-light environments
* `system`: Automatically matches the user's device settings

If no appearance is specified, Opal defaults to the `light` theme.

For more information, visit the [Opal Libraries](/opal/libraries) documentation.

## Improvements

### Payment Instruments API

This release introduces several improvements to the [Payment Instruments](/reference/accounts/payment-instruments/overview) product, focused on lifecycle management and subscription control.

**Lifecycle Management for Inbound ACH/Wire**

A new endpoint allows you to close inbound ACH/Wire payment instruments when they are no longer needed. This is useful for decommissioning payment routes after a refinance completes or when a funding relationship ends.

* **New endpoint**: `DELETE /accounts/:accountId/payment_instruments/:pmtInsId`
* **Behavior**: Supported only for `inbound_achwire_payment` instruments. Updates instrument status to `closed` and sets `chargeable` to `false`.

For more information, see the [Payment Instruments API](/reference/accounts/payment-instruments/overview) documentation.

**Granular Subscription Types**

The `payment_instrument` [subscription](/reference/accounts/subscriptions/overview) has been split into two more specific subscription types, giving you more flexibility in determining which webhook events you receive:

* `payment_instrument.card`: Triggered for card-level updates (e.g., PAN changed, expiration updated)
* `payment_instrument.network_token`: Triggered for network token updates (e.g., token provisioned, status changed)

<Note>For API version `2025-12-01`+, clients must use the new specific subscription names.</Note>

### Accounts API

**Collection Account Support**

The [Account Sensitive](/reference/accounts/sensitive/overview) product now supports the `collection` account type. This enables you to retrieve sensitive account details (such as account numbers) for accounts that have been sent to collections, expanding coverage for debt management and recovery workflows.

### Attributes API

**Support for Closed Accounts**

You can now retrieve [Account Attributes](/reference/accounts/attributes/overview) for closed liability accounts. Previously, querying Attributes for a closed account would return an error. With this update, derived financial insights (such as payment history summaries and balance trends) remain accessible even after an account has been closed—useful for historical reporting and analytics.


# July Updates
Source: https://docs.methodfi.com/changelog/2026/july



## New Features

### Raw Credit Report Artifacts and Files API

Teams with raw credit report access can now request the bureau report underlying a Connect as downloadable JSON or PDF artifacts. This gives lenders the full bureau file behind a Connect, so underwriting, risk, and compliance logic can run against the same source data Method used.

Pass `bureau` and `artifacts` when creating a Connect. Equifax and TransUnion are supported:

```json theme={null}
{
  "bureau": "transunion",
  "artifacts": ["raw_credit_report", "credit_report_pdf"]
}
```

The completed Connect returns each artifact in its `files` array. The new Files API provides two ways to access them:

* `GET /files/{file_id}` returns File metadata and a temporary download URL
* `GET /files/{file_id}/download` streams the original file directly

Files remain available after the Connect completes, allowing lenders to run their existing underwriting and risk logic on the same raw credit report output without maintaining a separate bureau integration. Raw credit report access is enabled per team; contact your Method CSM to get started.

For implementation details, visit the [Raw Credit Reports guide](/guides/connect/raw-credit-reports) and [Files API](/reference/files/overview) documentation.

### Estimated Statement Attribute

Account Attributes can now return the upcoming payment due date and minimum amount due for supported accounts through the new `statement` bundle:

* `next_payment_due_date`: the upcoming payment due date
* `next_payment_minimum_amount`: the upcoming minimum amount due, in cents

Previously this required maintaining an Update subscription and waiting for a refreshed Update to land, and between statement cycles the values were frequently missing altogether. Teams can now schedule autopay and reminders against a real due date, size a payment that reliably clears the minimum, and sequence payments across a user's accounts by what comes due first.

When current statement data is unavailable, Method estimates both values from account history and identifies them with `metadata.estimated: true`. When a value cannot be determined, the attribute returns an `ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA` error rather than a fabricated fallback.

```json theme={null}
{
  "bundles": ["statement"]
}
```

For more information, visit the [Account Attributes](/reference/accounts/attributes/overview) API documentation.

### Estimated Credit Card APR

Account Attributes can now return a single `estimated_apr` for supported credit card accounts with qualifying account history.

Card issuers rarely expose an account-level APR through any programmatic channel, which has left teams either asking the end user for their rate or assuming one. Estimated APR lets teams size interest savings, rank refinance and balance transfer offers, and prioritize outreach to the highest-rate balances in a user's profile, without asking the end user for anything.

Every value is identified with `metadata.estimated: true` and carries a `metadata.confidence` of `medium` or `high` based on the depth of available history, so teams can set their own threshold for acting on it. When an APR cannot be inferred with sufficient confidence, the attribute returns an `ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA` error rather than a fabricated fallback.

```json theme={null}
{
  "estimated_apr": {
    "value": 19.5,
    "error": null,
    "metadata": {
      "estimated": true,
      "confidence": "high"
    }
  }
}
```

For more information, visit the [Account Attributes](/reference/accounts/attributes/overview) API documentation.

## Changes

### Payment Processing Windows

Payment processing windows have been updated. Payments using the Method Debit Model are now processed at 1:30 PM CT, and payments using the Prefunded Model are now processed at 3:30 PM CT. Payments submitted before the applicable cutoff are processed same-day; payments submitted after are queued for next-business-day processing.

For more information, visit the [Payments API](/reference/payments/overview) documentation.

## Improvements

### Idempotency and Stuck-Request Recovery

Improvements to Method's idempotency system eliminated persistent `INTERNAL_BAD_STATE` errors on retried requests. Dropped connections now recover automatically on retry, previously stuck requests self-heal rather than remaining locked, and orphaned in-flight requests are released after a short interval.

End users no longer become locked mid-flow after a dropped connection. Requests already stuck in `INTERNAL_BAD_STATE` also recover automatically the next time the end user retries, and no integration changes are required.

For more information, visit the [API Idempotency](/reference/idempotency) documentation.

### Dashboard Navigation and Search

The [Method Dashboard](https://dashboard.methodfi.com) now includes:

* A responsive, collapsible sidebar with improved mobile support
* Faster global search with a more compact results experience
* Faster switching between development and production environments
* Persistence of the most recently used environment across sessions
* FIS trace IDs on sent and posted payments in the payments view

Users with the Developer role can also create API keys and webhook registrations directly from the Dashboard, consistent with their existing permissions. Together these reduce the time spent locating a request, entity, or payment when responding to a customer question.

### Payability Check at Account Creation

Method now runs a payability check when an account is created, so teams learn whether an account can be paid at the point of creation rather than discovering it at payment time. This prevents users from attempting a payment that was never going to succeed.

### Webhook Reliability

Outbound webhook delivery now includes stronger duplicate-delivery protection and prevents queued deliveries from being sent to disabled webhook registrations. Delivery and replay handling have also been hardened to reduce the risk of events being lost during transient service failures.

This means fewer events to deduplicate on your side and less reconciliation work after a transient failure, with no change to how you consume webhooks.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Development Environment

Manual Connect flows can now be configured dynamically, and payments can be simulated against payment instruments without production dependencies. Teams can therefore test a full Connect-to-payment path, including failure cases, before touching a live account.

For more information, visit the [Development Environment](/reference/environments) documentation.


# June Updates
Source: https://docs.methodfi.com/changelog/2026/june



## New Features

### Card Brand Details

The Card Brands endpoint now returns a structured `details` object on each brand, giving you the full marketing-level terms behind a user's card, including APRs, fees, rewards, and promotional offers.

* **APRs**: Purchase and cash-advance APR ranges via `purchase_apr_min` / `purchase_apr_max` and `cash_advance_apr_min` / `cash_advance_apr_max`.
* **Fees**: `annual_fee` and `late_payment_fee`.
* **Rewards**: A full rewards object with program name, reward type (for example, `cash_back`, `points`, `miles`), and per-category earn rates (dining, travel, groceries, gas, and more), including the base-rate category for all other purchases.
* **Promotions**: A `promotions` array covering sign-up bonuses, intro APR offers, statement credits, and more, each with value, spend requirement, qualifying period, and expiration.
* **Classification and freshness**: `card_category` classifies the card (for example, `travel`, `cash_back`, `store`), and `data_as_of` tells you when the details were last captured.

**Key Use Cases**

* Power balance-transfer and refinance offers with accurate rate and promotion data.
* Enrich PFM experiences by showing users the detailed terms and benefits of the cards they carry.
* Optimize checkout and reward experiences by auto-routing purchases to the top-earning card.

Card Brands is available as both a Product (on-demand) and a Subscription (near real-time updates), and the details object is available on API version `2025-07-04` and later. The endpoint is available to partners processing payments through the Payment Instruments endpoint. Contact your Method CSM to enable it. See the [Card Brands reference](/reference/accounts/card-brands/overview) to get started.

### Dashboard: Check Payment Management

Admins can now manage check payments directly from the payment detail page in the [Method Dashboard](https://dashboard.methodfi.com).

* **Stop payment**: Place a stop on a paper check that has been sent but not yet cashed. The check is stopped and funds are reversed to the source.
* **Check endorsement image**: View the front and back endorsed image of a check once it has been cashed.
* **Source & destination status**: The payment detail page now surfaces source status and destination status alongside the existing payment status for better visibility into where a payment is in its lifecycle.

<Note>Stop payment and check image viewing are available to admin users only.</Note>

For more information, visit the [Method Dashboard](https://dashboard.methodfi.com).

### Preauth Signals

The new Preauth Signals endpoint returns the predicted likelihood that a transaction will succeed, alongside verified ownership of the card and recommended retry timing. Built for merchants and commerce platforms looking to optimize payment performance.

**Key Use Cases**

* Predict whether a card payment will go through before attempting the charge to reduce false declines at checkout.
* Identify the best date to retry a payment for recurring charges.

This endpoint is currently in Public Preview. Reach out to your Method CSM for access and documentation.

### New Attributes: Delinquency, HELOC & Available Credit

New entity-level and account-level attributes give you a more complete, real-time picture of borrower risk and capacity.

* **Delinquency signals**: Aggregate borrower-level risk with the worst days-past-due bucket across accounts, whether delinquency is progressing or recently cured, total delinquent balance, and the highest-severity outcome (charge-off, collections, foreclosure, and more).
* **HELOC-specific attributes**: You can now separate out attributes related to HELOCs from mortgages and personal loans to isolate appetite for a new HELOC, CLI, or refi.
* **Available credit**: Understand a borrower's total credit headroom in near real time to assess their riskiness and eligibility for new products.
* **Direct Pay enrichment**: Completed attribute responses now include Method Direct Pay history (recency, amount, and trailing 12-month count), providing a clearer picture of a borrower's risk profile and appetite for debt consolidation.

For more information, visit the [Entity Attributes](/reference/entities/attributes/overview) and [Account Attributes](/reference/accounts/attributes/overview) API documentation.

### Account Attribute Subscriptions

Method now triggers events whenever an account's attributes change, so you can react to balance, utilization, and delinquency shifts in real time instead of polling. Subscribe to the attributes you care about and Method delivers updates to your configured webhooks as they occur.

* Manage what you listen to through the [Subscriptions endpoint](/reference/accounts/subscriptions/overview).
* Receive changes through [Events](/reference/events/overview) and webhooks.

This pairs naturally with continuous, post-origination portfolio monitoring use cases.

### Team IP Allowlisting

Teams can now restrict API access to a defined set of IP addresses. Once an allowlist is configured, requests from outside the approved ranges are rejected, with enforcement backed by a 24-hour cache for low-latency checks. See [IP Whitelisting](/reference/ip-whitelisting) to configure.

## Improvements

### Payments

* **More accurate estimated completion dates**: The `estimated_completion_date` returned on a payment now always shows the correct date or a slightly conservative estimate, especially for same-day ACH source payments.
* **Destination posted date**: The `destination_posted_date` field is now populated once the destination posts, giving you a precise reconciliation signal that is distinct from the estimated completion date.

For more information, visit the [Payments API](/reference/payments/overview) documentation.

### Payment Limits

To protect platform safety and stability, per-transaction and 24-hour limits are now enforced on payment volumes.

A new Limits tab under Dashboard Settings surfaces your team's money-movement capabilities and associated limits in one place. You can now see at a glance what your team is permitted to send and receive, and where caps apply.

Contact your customer success manager to learn more about your team's limits.


# March Updates
Source: https://docs.methodfi.com/changelog/2026/march



## New Features

### [API Guides](/guides/overview)

A new API Guides section is now available in Method's documentation. This comprehensive, concept-first companion to the API Docs helps product and business teams understand how Method's platform works and how best to configure Method's APIs for their use case. The API Guides include:

* **How Method Works**: How Method leverages multiple data sources to power identity verification, account discovery, and data retrieval.
* **Core Products**: In-depth guides for each product area, covering payload details, subscription behaviors, error handling, and edge cases.
* **Use Case Guides**: Implementation frameworks for the most common use cases: debt consolidation and balance transfers for lenders, card linking and checkout for commerce platforms, and liability dashboards and bill pay for personal finance apps, with step-by-step flows mapping Method products to each stage of the customer journey.

These guides are designed to complement the existing API Reference documentation by providing the conceptual foundation and product context that teams need to plan and build their integrations effectively.

### [OpenAPI Specification](https://github.com/MethodFi/openapi)

Method now publishes an official OpenAPI specification for the Method API. The spec enables you to:

* **Generate typed API clients** in any language using OpenAPI-compatible code generators
* **Import endpoints** directly into tools like Postman or Insomnia
* **Integrate with any toolchain** that supports the OpenAPI standard

For more information, visit the [Libraries](/libraries/overview) documentation.

## Improvements

### Webhook Idempotency Headers

You can now easily deduplicate retried or replayed webhook deliveries. All outbound webhooks now include a `method-webhook-delivery-id` header, containing a unique identifier for each webhook delivery. If your endpoint receives the same delivery twice (due to network timeouts, retries, or replays), the `method-webhook-delivery-id` value will be identical, letting you skip duplicate processing with a simple lookup.

```json Sample Headers theme={null}
{
  "method-webhook-delivery-id": "obwh_yBaCP3DQxJ4",
  "content-type": "application/json"
}
```

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Simulations API

**Connect Webhook in Account Opened Simulation**

The `POST /simulate/events` endpoint for `account.opened` events now also sends the `connect.create` webhook as part of the simulation, aligned with the endpoint's production behavior.

Previously, simulating an `account.opened` event only fired the `account.opened` webhook. This gap meant customers couldn't fully test their Connect-to-Account-Opened integration pipeline in dev.

Now, when you simulate `account.opened`, both webhooks fire in sequence:

1. `connect.create` — the Connect session that discovered the account
2. `account.opened` — the account itself becoming available

This enables true end-to-end testing of workflows that listen for Connect completion and then act on the resulting accounts.

```json POST /simulate/events theme={null}
{
  "type": "account.opened",
  "entity_id": "ent_au22b1FBFJbp8",
  "account_id": "acc_Dz3E8r4mJ7xKn"
}
```

For more information, visit the [Simulations API](/reference/simulations/events/create) documentation.


# May Updates
Source: https://docs.methodfi.com/changelog/2026/may



## New Features

### Snapshot Delinquency Data

[Updates](/reference/accounts/updates/overview) with `source: "snapshot"` now include a comprehensive set of delinquency fields sourced from the credit report. These fields give you a full picture of a borrower's delinquency status without pulling a separate credit report for the user.

* **Delinquency Status & Period**: `delinquent_status`, `delinquent_period`, and `delinquent_start_date` indicate the current delinquency state, severity bucket (`less_than_30`, `30`, `60`, `90`, `120`, `over_120`), and when the delinquency began.
* **Delinquent Actions**: `delinquent_action` surfaces servicer-level actions such as `charge_off`, `foreclosure`, `repossession`, `chapter_7`, `chapter_13`, `wage_garnishment`, `payment_agreement`, and `bankruptcy`.
* **Delinquent Amount**: `delinquent_amount` returns the dollar amount currently reported as delinquent.
* **Delinquency History**: `delinquent_history` provides a time-series array of historical delinquency periods, each with `start_date`, `end_date`, `status`, `period`, and `action`, enabling trend analysis across multiple reporting cycles.

Delinquency fields are available on snapshot Updates for `credit_card`, `auto_loan`, `personal_loan`, `mortgage`, and `student_loan` liability types. These fields are not included on Updates with `source: "direct"`.

For more information, visit the [Updates API](/reference/accounts/updates/overview) documentation.

### Receive Reversals via Wire

You can now receive payment reversals via wire. This functionality allows customers to quickly and easily access funds from reversed payments that previously could not run on ACH rails (such as inbound wire transfers via payment instrument).

<Note>These accounts are receive-only and do not support outbound payments.</Note>

For more information, visit the [Accounts API](/reference/accounts/overview) documentation.

### Dashboard: Webhook Management

The [Method Dashboard](https://dashboard.methodfi.com) now supports full webhook lifecycle management. You can create, view, update, and delete webhook endpoints directly from the UI, with no API calls or support requests required.

* Register new webhook endpoints with custom event filters and authentication
* View all active webhooks and their status
* Update endpoint URLs and configuration in place
* Delete webhooks that are no longer needed

For more information, visit the [Method Dashboard](https://dashboard.methodfi.com).

## Improvements

### Rate Limiting

To protect platform stability and ensure consistent performance across all customers, all API requests are now subject to published, tiered rate limits. Documented limits mean your engineering team can design around known thresholds rather than hitting undefined behavior during peak operations.

* Rate limits are applied per API key within a 60-second rolling window, organized into tiers based on operation type.
* Each tier tracks independently, so usage against one tier does not affect capacity in another.
* Customers with high-volume integrations can request custom limits through their customer success manager.

For more information, visit the [Rate Limiting](/reference/rate-limiting) documentation.

### Webhooks

**Delivery Rate Limiting**

Outbound webhook deliveries are now rate-limited to 15 deliveries per second per webhook registration. This smooths delivery during high-volume events (e.g., bulk Connect completions or batch Update subscriptions) and reduces the likelihood of triggering rate-limit responses on your infrastructure.

**Failure Handling**

An individual webhook delivery is now retried up to 5 times before it is marked as failed, rather than remaining in a retry loop indefinitely. After 5 consecutive delivery failures, the webhook `status` is set to `disabled`, consistent with the documented automatic-disabling behavior. You can reactivate a disabled webhook from the Dashboard or via the [Update a Webhook](/reference/webhooks/update) endpoint once the underlying issue is resolved.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Payments API

**Destination Processing Window**

The destination processing window has been updated to 4:00 PM CT (5:00 PM ET). Payments submitted before this cutoff can be processed the same-day; payments submitted after are queued for next-business-day processing.

For more information, visit the [Payments API](/reference/payments/overview) documentation.

### Simulations API

**Account Closed Event**

The `POST /simulate/events` endpoint for `account.closed` events now also triggers the `account.update` webhook as part of the simulation, matching production behavior. This enables more complete end-to-end testing of account lifecycle workflows in the development environment.

```json POST /simulate/events theme={null}
{
  "type": "account.closed",
  "entity_id": "ent_au22b1FBFJbp8",
  "account_id": "acc_Dz3E8r4mJ7xKn"
}
```

When simulating `account.closed`, both webhooks now fire in sequence:

1. `account.update`: the account snapshot is updated with the closed status
2. `account.closed`: the account itself transitions to closed

For more information, visit the [Simulations API](/reference/simulations/events/create) documentation.

### Development Environment

**Mock Credit Reports for Connect**

Mock raw credit reports are now available for [Connect](/opal/connect/overview) flows in the development environment, enabling end-to-end testing of credit report-based account discovery without live bureau data.

<Warning>This feature is available in the development environment only.</Warning>

**Payment Destination Details in Responses**

The development environment `POST /payments` response now includes the `destination_payment_method` field, aligning dev responses with production behavior. This field indicates how the payment is delivered to the recipient, either `electronic` or `paper`.

```json theme={null}
{
  "id": "pmt_rPrDPEwyCVUcm",
  "status": "pending",
  "source": "acc_JMJZT6r7iHi8e",
  "destination": "acc_AXthnzpBnxxWP",
  "destination_payment_method": "electronic"
}
```

For more information, visit the [Payments API](/reference/payments/overview) documentation.


# Introducing API v2
Source: https://docs.methodfi.com/changelog/api-versions/2024-04-04



<img alt="title" />

We are excited to announce the launch of API v2 (release `2024-04-04`), the highly anticipated second version of Method's API.
Over the past year, our team has been dedicated to gathering feedback and working closely with our clients to create an even more powerful and developer-friendly API.

This release is packed with new features and enhancements that build upon Method's credential-less consumer permissioned financial network.

Expanded integrations with Visa/Mastercard power new features such as real-time credit card transaction notifications, and enabling 1-click checkout experiences for merchants.
This is in addition to our real-time financial institution liability updates, which have been significantly upgraded to provide better accuracy, expanded coverage, and reduced latency.

### Upgrading to 2024-04-04

The new API version is available to all existing teams.
New teams are automatically pinned to the API version `2024-04-04`.
During the transition phase, teams will be allowed to utilize any API version in tandem.

Note that once upgraded manually, it’s not possible to revert to older versions. Contact your Method CSM for more information on upgrade rollbacks.

* **Request Header**: Set `Method-Version` to `2024-04-04`. See [API Versioning](/reference/versioning#api-versioning) for more information.
* **Client Libraries**: For Method Libraries, the version is locked to the dated version of the API. For example, method-node v0.x.x is locked to 2020-12-06, while method-node v1.x.x is locked to 2024-04-04 and onwards.

#### Upgrade Support

Our technical integration team is here to help! Contact your Method CSM for a 1:1 on best practices and support migrating to `2024-04-04`

<Tip>Personalized upgrade guides have been created for enterprise customers. Contact your Method CSM to receive your guide.</Tip>

**✨ Ask Method:** The search bar of our docs now includes a conversational LLM search powered by ChatGPT. Feel free to ask any questions and receive a personalized answer.

*Sample questions:*

> How are auth\_sessions different in the new version of the API?

> What are the new products in 2024-04-04?

## Entities

New endpoints have been introduced for verification sessions, identities, connect operations, credit scores, products, and subscriptions. Several endpoints, including auth session, credit scores, and sensitive information retrieval, have been deprecated.

The connect endpoint now fetches all liability accounts across Method’s network of financial institutions, replacing auth\_session.
The verification sessions endpoint manages methods for verifying an entity's phone and identity, while the identities endpoint retrieves the underlying identity (PII) of an entity.
The products and subscriptions endpoints provide an overview of the products and continuous updates available for entities.

### New Features

#### The Connect endpoint

[Connect](/reference/entities/connect/overview) identifies and connects all the liability accounts (e.g., credit card, mortgage, auto loans, student loans, etc.)
for an entity across Method’s network of 1500+ financial institutions/lenders.

* **The Connect endpoint replaces:**
  * Auth Session: `POST /entities/{ent_id}/auth_session`

See [Connect](/reference/entities/connect/overview) for more information.

***

#### The Credit Scores endpoint

[Credit Scores](/reference/entities/credit-scores/overview) returns the latest credit score and score factors for an entity.

* **The Credit Scores endpoint replaces:**
  * Credit Score: `GET /entities/{ent_id}/credit_score`

See [Credit Scores](/reference/entities/credit-scores/overview) for more information.

***

#### The Verification Sessions Endpoint

[Entity Verification Sessions](/reference/entities/verification-sessions/overview) manage the methods for verifying an entity's phone and identity. Entities need to verify
their identity and/or phone to be used throughout the Method API. The status
of an entity's verification is returned via the `verification` field in the Entity object.

* **The Verification Sessions endpoint replaces:**
  * KBA questions via Auth Session: `POST /entities/{ent_id}/auth_session` is replaced by [kba](/reference/entities/verification-sessions/create-kba) entity verification session.
  * Non-KBA authentication via Auth Session: `POST /entities/{ent_id}/auth_session` is replaced by [byo\_kyc](/reference/entities/verification-sessions/create-byo-kyc) entity verification session.
  * `individual.phone_verification_type` and `individual.phone_verification_timestamp` via the create Entity request are replaced by [byo\_sms](/reference/entities/verification-sessions/create-byo-sms) phone verification requirements.
  * Utilizing `capabilities`, `available_capabilities`, and `pending_capabilities` in the Entity object to verify if an entity's identity has been matched or if more PII is required.
    * This flow is now replaced by `verification.identity.verified` and `verification.identity.matched` in the `verification` field in the Entity object.

* **Upgrade notes:**
  * The `verification` field in the Entity object returns the status of Identity Verification (`verification.identity`) and Phone Verification (`verification.phone`).
  * The `method` key in the `entity.verification` object enumerates the phone and identity verifications available for your entity.
    * Available verification methods differ on a team-by-team basis and are further defined by the PII provided during entity creation. See [PII Requirements](/reference/entities/overview#pii-requirements) for more information.
    * Teams with pre-defined PII requirements can utilize `byo_kyc` to skip KBA, and `byo_sms` to skip phone verification.
  * Teams upgrading from a prior API version might have some verifications auto-generated. Contact your Method CSM for more info.
  * The `status` key in an entity will only transition to `active` when all verification requirements have been completed.

See [Verification Sessions](/reference/entities/verification-sessions/overview) for more information.

***

#### The Identities endpoint

Entity [Identities](/reference/entities/identities/overview) endpoint is used to retrieve the underlying identity (PII) of an Entity.

* **The Identities endpoint replaces:**
  * Entity Sensitive: `GET /entities/{ent_id}/sensitive`

See [Identities](/reference/entities/identities/overview) for more information.

***

#### The Products endpoint

Entity [Products](/reference/entities/products/overview) endpoint outlines the products (*capabilities*) an entity has access to and provides an overview of the status of all the products.

Products are Method endpoints available for an entity. Access to most products requires an entity to be active.
However, some products have restricted access requiring team-by-team enablement. See [List all Products](/reference/entities/products/list) for more information.

**Entity Products:**

| Name           | Use-Case                                                             | Resource Doc                                                |
| -------------- | -------------------------------------------------------------------- | ----------------------------------------------------------- |
| `connect`      | On-Demand comprehensive view of an Entity’s outstanding liabilities. | [Connect](/reference/entities/connect/overview)             |
| `credit_score` | On-Demand view of an Entity’s credit score.                          | [Credit Scores](/reference/entities/credit-scores/overview) |
| `identity`     | On-Demand retrieval of the full Identity (PII) for any Entity        | [Identities](/reference/entities/identities/overview)       |

* **The Products endpoint replaces:**
  * Utilizing `capabilities`, `available_capabilities`, and `pending_capabilities` in the Entity object to determine the capabilities an entity has access to.
    These fields have been deprecated from the Entity object and removed in favor of:
    * `products` (products available for this entity)
    * `restricted_products` (products not currently available, but can be made available)

See [Products](/reference/entities/products/overview) for more information.

***

#### The Subscriptions endpoint

Entity [Subscriptions](/reference/entities/subscriptions/overview) endpoint controls the state of all subscriptions for an entity. Subscriptions are products that can provide continuous updates via webhooks (e.g., *Credit Score Subscription provides updates on an entity’s credit score*).

**Entity Subscriptions:**

| Name           | Use-Case                                                                                                            | Resource Doc                                                |
| -------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `connect`      | Comprehensive view of an Entity’s outstanding liabilities and continuous near real-time updates on new liabilities. | [Connect](/reference/entities/connect/overview)             |
| `credit_score` | Continuous near real-time updates on an Entity’s credit score.                                                      | [Credit Scores](/reference/entities/credit-scores/overview) |

* **The Subscriptions endpoint replaces:**
  * Custom configuration for continuous credit report pulls via your Method CSM. This has been deprecated and replaced by [Create a Subscription](/reference/entities/subscriptions/create) endpoint.

See [Subscriptions](/reference/entities/subscriptions/overview) for more information.

***

### Breaking Changes

#### Entity object changes

* ✨ Corporation entity types have been simplified to `corporation` during [Create a Corporation](/reference/entities/create-corporation) entity.
  * `c_corporation`, `s_corporation`, `llc`, `partnership`, and `sole_proprietorship` have been deprecated and removed in favor of `corporation`

* ✨ Providing SSN is now supported during [Create an Individual](/reference/entities/create-individual) entity.
  * `individual.ssn`, and `individual.ssn_4`

* ✨ Entity verification status is now returned by the Entity object. See [Entity object](/reference/entities/overview) for more information.
  * `verification`

* ✨ Products and subscription status are now returned by the Entity object. See [Entity object](/reference/entities/overview) for more information.
  * `products`
  * `restricted_products`
  * `subscriptions`
  * `available_subscriptions`
  * `restricted_subscriptions`

* ⛔ Phone verification has been replaced and no longer returned by the Entity object.
  * `individual.phone_verification_type`, and `individual.phone_verification_timestamp` have been deprecated and removed in favor of [Entity Verification Sessions](/reference/entities/verification-sessions/overview)

* ⛔ Entity capabilities have been deprecated and removed from the Entity object.
  * `capabilities`, `available_capabilities`, and `pending_capabilities` have been deprecated and removed in favor of [Products](/reference/entities/products/overview), [Subscriptions](/reference/entities/subscriptions/overview), and [Entity Verification Sessions](/reference/entities/verification-sessions/overview)
    * The `verification` field in the Entity object returns the status of Identity Verification (`verification.identity`) and Phone Verification (`verification.phone`).
    * The `products` array returns the products the entity has access to, replacing `capabilities`.
    * The `restricted_products` array returns the products the entity does not have access to, replacing `pending_capabilities`.
    * The [Entity Products](#) endpoint outlines the products (*capabilities*) an entity has access to and provides an overview of the status of all the products.

* The following fields have been modified in the [Entity object](/reference/entities/overview):

  <AccordionGroup>
    <Accordion title="Fields removed from Entity" icon="circle-minus">
      * `individual.phone_verification_type`
      * `individual.phone_verification_timestamp`
      * `capabilities`
      * `available_capabilities`
      * `pending_capabilities`
    </Accordion>

    <Accordion title="Fields added to Entity" icon="circle-plus">
      * `individual.ssn`
      * `individual.ssn_4`
      * `verification`
      * `products`
      * `restricted_products`
      * `subscriptions`
      * `available_subscriptions`
      * `restricted_subscriptions`
    </Accordion>
  </AccordionGroup>

#### Deprecated endpoints

The following endpoints have been deprecated and removed in `2024-04-04`

* Auth Session: `/entities/{ent_id}/auth_session` removed in favor of [Connect](/reference/entities/connect/overview)
* Credit Score: `/entities/{ent_id}/credit_score` removed in favor of [Credit Scores](/reference/entities/credit-scores/overview)
* Entity Sensitive: `/entities/{ent_id}/sensitive` removed in favor of [Identities](/reference/entities/identities/overview)
* Refresh Capabilities: `/entities/{ent_id}/refresh_capabilities` is no longer supported in `2024-04-04`
* Manual Auth Session: `/entities/{ent_id}/manual_auth_session` is no longer supported in `2024-04-04`
* Entity Vehicles: `/entities/{ent_id}/vehicles` is no longer supported in `2024-04-04`

## Accounts

New endpoints have been introduced for updates, card brands, payoffs, transactions, balances, verification sessions, and sensitive information. Several endpoints, including account syncs, account verification, and sensitive information retrieval, have been deprecated.

The updates endpoint now provides real-time account data directly from financial institutions, replacing syncs, and making liability account data available through the updates endpoint.

The verification process for ACH and liability accounts has been streamlined with Account Verification Sessions.

### New Features

#### The Updates endpoint

[Updates](/reference/accounts/updates/overview) endpoint retrieves in real-time account data including balance, due dates, APRs, directly from the account’s financial institution.
Updates is Method's flagship endpoint and replaces the `sync` endpoint by enabling push notifications directly from the financial institution.

As part of the `2024-04-04` release the Account object has been modified, and most Account data is now returned by an Update object. See [Account object changes](/changelog/api-versions/2024-04-04#account-object-changes) for more information.

* **The Updates endpoint replaces:**
  * Syncing an account using `/accounts/{acc_id}/syncs` has been deprecated and removed in favor of [Create an Update](/reference/accounts/updates/create)
  * Enrolling in auto syncs using `/accounts/{acc_id}/sync_enrollment` or via your Method CSM has been deprecated and removed in favor of [Updates](/reference/accounts/updates/overview) and [Subscriptions](/reference/accounts/subscriptions/overview)
  * Sync status fields in the Account response have been deprecated and removed in favor of [Updates](/reference/accounts/updates/overview). Removed fields include:
    * `data_status`
    * `data_sync_type`
    * `data_last_successful_sync`
    * `data_status_error`
    * `data_source`
    * `data_updated_at`
  * Enrollment into credit report-based updates via your Method CSM has been deprecated and removed in favor of the `update.snapshot` subscription type. See [Subscriptions](/reference/accounts/subscriptions/overview) for more information.
  * Liability data at the account level (`account.liability.<liability_type>`) has been deprecated and removed in favor of an Update object and an expansion. See [Account](/reference/accounts/overview) for more information.
  * Utilizing `data_status` to determine real-time financial institution coverage has been deprecated and removed in favor of the `products` array including `updates`. See [Updates](/reference/accounts/updates/overview) for more information.

* **Upgrade notes:**
  * New updates sources: `direct` and monthly `snapshot` updates.
    * `direct`: Near real-time account update (balance, due dates, etc.) from the account’s financial institution (replaces a `sync`).
    * `snapshot`: Monthly snapshot update (balance, due dates, etc.) from the account’s financial institution (replaces credit report-based updates).
  * Receiving continuous updates requires a subscription to `update` or `update.snapshot`. See [Subscriptions](/reference/accounts/subscriptions/overview) for more information.
  * Liability data at the account level (`account.liability.<liability_type>`) has been deprecated and removed in favor of an Update object and an expansion. See [Account](/reference/accounts/overview) for more information.
  * Any account connected using Entity Connect will receive an initial `snapshot` update and a `direct` update (when available).
  * Legacy accounts connected via `auth_session` have been migrated with an Update object pre-populated.

See [Updates](/reference/accounts/updates/overview) for more information.

***

#### The Card Brand endpoint

[Card Brand](/reference/accounts/card-brands/overview) endpoint retrieves the associated credit card metadata (Product / Brand Name, Art, etc.) directly from the card issuer.
In the future, card brand webhooks will notify in real-time any card changes (e.g., card downgraded, card lost, etc.)

* **The Card Brand endpoint replaces:**
  * Derived card names in the liability account field `name`. Migrating to card brand will provide accurate names across any Visa / Mastercard card regardless of issuing bank.

See [Card Brand](/reference/accounts/card-brands/overview) for more information.

***

#### The Payoffs endpoint

[Payoffs](/reference/accounts/payoffs/overview) endpoint retrieves a payoff quote in real-time from the Account’s financial institution / lender. Payoffs are currently only available for Auto Loan and Mortgage accounts.

* **The Payoffs endpoint replaces:**
  * `payoff_amount` and `payoff_amount_term` fields within the `auto_loan` Account type response. See [Updates](/reference/accounts/updates/overview) for more information on the Account object changes.

See [Payoffs](/reference/accounts/payoffs/overview) for more information.

***

#### The Transactions endpoint

[Transactions](/reference/accounts/transactions/overview) endpoint retrieves real-time transaction (authorization, clearing, etc) notifications for Credit Card Accounts directly from the card networks (Visa, MC).

Enrollment for transactions requires a subscription and additional consent using Method's `connect` element.

* **The Transactions endpoint replaces:**
  * Enrollment for transactions using the `auth` element has been deprecated and removed in favor of the `connect` element. See [Connect Overview](/elements/connect/overview) for more information.
  * Global transactions endpoint `/transactions` has been deprecated and removed in favor of account-scoped transactions. See [Transactions](/reference/accounts/transactions/overview) for more information.
  * `transaction:stream` capability has been deprecated and removed in favor of the `transactions` product. See [Products](/reference/accounts/products/overview) for more information.

See [Transactions](/reference/accounts/transactions/overview) for more information.

***

#### The Balances endpoint

[Balances](/reference/accounts/balances/overview) endpoint retrieves the real-time balance from the account’s financial institution.
Balance is now available for non-liability accounts such as checking accounts. Contact your Method CSM for early access to expanded Balance coverage.

* **The Balances endpoint replaces:**
  * The `balance` field in `liability.<liability_type>.balance` has been deprecated and removed in favor of:
    * Retrieving `balance` using the [Balances](/reference/accounts/balances/overview) endpoint
    * Retrieving  `balance` and additional liability information using the [Updates](/reference/accounts/updates/overview) endpoint

See [Balances](/reference/accounts/balances/overview) for more information.

***

#### The Verification Sessions endpoint

[Account Verification Sessions](/reference/accounts/verification-sessions/overview) manage the methods for verifying an Account to enable specific products for ACH or Liability accounts. For example,
ACH Accounts require a verified Account Verification Session before they can be used as a source for Payments.

* **The Account Verification Sessions endpoint replaces:**
  * ACH Account verification via `/accounts/{acc_id}/verification` has been deprecated and removed in favor of:
    * An Account Verification Session of one of the available methods: `micro_deposits`, `plaid`, `mx`, or `teller`.
    * Teams with corporate disbursement ACH accounts can skip verification and a verification will be auto-provisioned with the type of `auto_verify`.
    * Teams with managed DDAs can whitelist a routing number to skip verification across all their DDAs (routing / account number pair).
    * See [Verification Types](/reference/accounts/verification-sessions/overview#verification-types) for more information.
      A verification of `trusted_provisioner` will be auto-provisioned. Contact your Method CSM for more information.
  * Liability account number verification for AMEX, Apple Card, etc. is now handled by a `standard` Account Verification Session. See [Update a Standard Verification](/reference/accounts/verification-sessions/update-standard) for more information.
  * Instant Link CVV verification is now handled by a `pre_auth` Account Verification Session. See [Update a Pre-auth Verification](/reference/accounts/verification-sessions/update-preauth) for more information.

* **Upgrade notes:**
  * Teams upgrading from a prior API version might have some verifications auto-generated. Contact your Method CSM for more info.

See [Account Verification Sessions](/reference/accounts/verification-sessions/overview) for more information.

***

#### The Sensitive endpoint

[Sensitive](/reference/accounts/sensitive/overview) endpoint returns underlying sensitive account information (e.g., PAN, CVV, account number).
This product is only available for liabilities and requires verification on a team-by-team basis.

* **The Sensitive endpoint replaces:**
  * `GET /accounts/{acc_id}/sensitive` is deprecated and removed in favor of [Create a Sensitive](/reference/accounts/sensitive/create).

See [Sensitive](/reference/accounts/sensitive/overview) for more information.

***

#### The Products endpoint

Account [Products](/reference/accounts/products/overview) endpoint outlines the products (*capabilities*) an account has access to and provides an overview of the status of all the products.

Products are Method endpoints available for an account. Most products are accessible by default.
However, some products have restricted access requiring team-by-team enablement and elevated account verification.

**Account Products:**

| Name         | Use-Case                                                                                                    | Supported Types | Resource Doc                                           |
| ------------ | ----------------------------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------ |
| `update`     | On-Demand real-time account update (balance, due dates, etc.) from the account's financial institution      | All liabilities | [Updates](/reference/accounts/updates/overview)        |
| `balance`    | On-Demand real-time balance from the account's financial institution                                        | All liabilities | [Balances](/reference/accounts/balances/overview)      |
| `card_brand` | On-Demand retrieval of credit card metadata (Product / Brand Name, Art, etc.) directly from the card issuer | Credit Cards    | [Card Brand](/reference/accounts/card-brands/overview) |
| `payoff`     | On-Demand retrieval of auto loan payoff (amount, per diem, etc.) from the account's financial institution   | Auto Loans      | [Payoffs](/reference/accounts/payoffs/overview)        |
| `payment`    | Next day electronic push payments to the account's financial institution                                    | All liabilities | [Payments](/reference/payments/overview)               |
| `sensitive`  | On-Demand retrieval of underlying sensitive account information (PAN, CVV, account number)                  | All liabilities | [Sensitive](/reference/accounts/sensitive/overview)    |

* **The Products endpoint replaces:**
  * Utilizing `capabilities`, `available_capabilities`, and `pending_capabilities` in the Account object to determine the capabilities an account has access to.
    These fields have been deprecated from the Account object and removed in favor of:
  * `products` (products available for this Entity)
  * `restricted_products` (products not currently available, but can be made available)

See [Products](/reference/accounts/products/overview) for more information.

***

#### The Subscriptions endpoint

Account [Subscriptions](/reference/accounts/subscriptions/overview) endpoint controls the state of all subscriptions for an account. Subscriptions are products that can provide continuous updates via Webhooks.
(*e.g., Transaction Subscription provides real-time updates on a Credit Card’s transactions*).

**Account Subscriptions:**

| Name              | Use-Case                                                                                          | Supported Types | Resource Doc                                              |
| ----------------- | ------------------------------------------------------------------------------------------------- | --------------- | --------------------------------------------------------- |
| `transactions`    | Real-time transaction (authorization, purchases, etc.) notifications for credit card accounts     | Credit Cards    | [Transactions](/reference/accounts/transactions/overview) |
| `update`          | Near real-time account update (balance, due dates, etc.) from the account's financial institution | All liabilities | [Updates](/reference/accounts/updates/overview)           |
| `update.snapshot` | Monthly account snapshot update (balance, due dates, etc.) from the credit bureau                 | All liabilities | [Updates](/reference/accounts/updates/overview)           |

* **The Subscriptions endpoint replaces:**
  * Custom configuration for continuous syncs via your Method CSM. This has been deprecated and replaced by [Create a Subscription](/reference/accounts/subscriptions/create) endpoint.
  * Account Sync Enrollment `/accounts/{acc_id}/sync_enrollment` for enrollment in auto syncs. This has been deprecated and replaced with an Updates subscription. See [Updates](/reference/accounts/updates/overview) and [Create a Subscription](/reference/accounts/subscriptions/create) for more information.
  * `data_sync_type` has been removed from the Account endpoint. See [Updates](/reference/accounts/updates/overview) and [List all Subscriptions](/reference/accounts/subscriptions/list) for more information.

See Account [Subscriptions](/reference/accounts/subscriptions/overview) for more information.

***

### Breaking Changes

#### Account object changes

* ✨ Product properties are now included in the Account object. By default, the ID of the latest product resource is returned and can be
  expanded in-line using the `expand` query param. See [Expanding Resources](/reference/expanding) for more information.
  * `latest_verification_session`
  * `update`
  * `balance`
  * `card_brand`
  * `payoff`

* ✨ Products and Subscription status are now returned by the Account object. See [Account object](/reference/accounts/overview) for more information.
  * `products`
  * `restricted_products`
  * `subscriptions`
  * `available_subscriptions`
  * `restricted_subscriptions`

* ✨ Liability name and fingerprint are now returned by the Account object. See [Account object](/reference/accounts/overview) for more information.
  * `liability.name`
  * `liability.fingerprint`

* ✨ New account liability types are now supported and returned by the Account object. See [Account Liability Types](/reference/accounts/overview#account-liability-types) for more information.

* ⛔ Liability data under the `account.liability.<liability_type>` property has been deprecated and removed in favor of [Updates](/reference/accounts/updates/overview)
  * The `updates` field returns the ID of the latest update and can be expanded to return liability account data in-line using the `expand` query param. See [Expanding Resources](/reference/expanding) for more information.

* ⛔ Syncing liability data using `/accounts/{acc_id}/syncs` has been deprecated and removed in favor of [Updates](/reference/accounts/updates/overview)
  * Additionally, data sync status fields at the account liability object have been deprecated and removed in favor of status fields within an [Update](/reference/accounts/updates/overview)
  * `liability.data_status`, `liability.data_sync_type`, `liability.data_sync_type`, `liability.data_last_successful_sync`, `liability.data_source`,
    `liability.data_updated_at`, `liability.data_updated_at`, `liability.data_status_error`

* ⛔ Account capabilities have been deprecated and removed from the Account object.
  * `capabilities`, `available_capabilities`, and `pending_capabilities` have been deprecated and removed in favor of [Products](/reference/accounts/products/overview), [Subscriptions](/reference/accounts/subscriptions/overview), and [Account Verification Sessions](/reference/accounts/verification-sessions/overview)
    * The `products` array returns the products the account has access to, replacing `capabilities`.
    * The `restricted_products` array returns the products the account does not have access to, replacing `pending_capabilities`.
    * The account [Products](/reference/accounts/products/overview) endpoint outlines the products (*capabilities*) an account has access to and provides an overview of the status of all the products.

* ⛔ Account payment status (`liability.payment_status`) has been deprecated and removed in favor of [Products](/reference/accounts/products/overview)

* ⛔ Account clearing (`clearing`) and liability hash (`liability.hash`) has been deprecated and removed in `2024-04-04`

* The following fields have been modified in the [Account object](/reference/accounts/overview):

  <AccordionGroup>
    <Accordion title="Fields removed from Account" icon="circle-minus">
      * `liability.payment_status`
      * `liability.data_status`
      * `liability.data_sync_type`
      * `liability.data_last_successful_sync`
      * `liability.data_source`
      * `liability.data_updated_at`
      * `liability.data_status_error`
      * `liability._liability_type_` - where `liability_type` is any of the [Account Liability Types](/reference/accounts/overview#account-liability-types).
      * `liability.hash`
      * `clearing`
      * `capabilities`
      * `available_capabilities`
      * `pending_capabilities`
    </Accordion>

    <Accordion title="Fields added to Account" icon="circle-plus">
      * `liability.name`
      * `liability.fingerprint`
      * `latest_verification_session`
      * `update`
      * `balance`
      * `card_brand`
      * `payoff`
      * `products`
      * `restricted_products`
      * `subscriptions`
      * `available_subscriptions`
      * `restricted_subscriptions`
    </Accordion>
  </AccordionGroup>

#### Deprecated endpoints

* Account Syncs: `/accounts/{acc_id}/syncs` removed in favor of [Updates](/reference/accounts/updates/overview)
* Account Sync Enrollment: `/accounts/{acc_id}/sync_enrollment` removed in favor of [Updates](/reference/accounts/updates/overview) and [Subscriptions](/reference/accounts/subscriptions/overview)
* Account Verification: `/accounts/{acc_id}/verification` removed in favor of [Account Verification Sessions](/reference/accounts/verification-sessions/overview)
* Account Sensitive: `/accounts/{acc_id}/sensitive` removed in favor of [Sensitive](/reference/accounts/sensitive/overview)
* Account Card: `/accounts/{acc_id}/card` removed in favor of [Card Brand](/reference/accounts/card-brands/overview), [Sensitive](/reference/accounts/sensitive/overview) and Credit Card [Account Verification Sessions](/reference/accounts/verification-sessions/overview)
* Account Payment History: `/accounts/{acc_id}/payment_history` is no longer supported in `2024-04-04`
* Account Details: `/accounts/{acc_id}/details` is no longer supported in `2024-04-04`
* Bulk Sensitive: `/accounts/{acc_id}/bulk_sensitive` is no longer supported in `2024-04-04`
* Bulk Sync: `/accounts/{acc_id}/bulk_sync` is no longer supported in `2024-04-04`
* Account Vehicle: `/accounts/{acc_id}/match_vehicle` is no longer supported in `2024-04-04`
* Routing Numbers: `/routing_numbers` is no longer supported in `2024-04-04`
* BINs: `/bins` is no longer supported in `2024-04-04`

## Additional Changes

### Expand Parameter

New `expand` query parameter for expanding certain properties from an ID to their respective objects in-line in the response body.

Applicable to both Entities and Accounts, allowing expansion of fields such as `connect`, `credit_score`, `update`, `balance`, `payoff`, `sensitive`, `transactions`, `card_brand`, and `latest_verification_session`.

See [Expanding Resources](/reference/expanding) for more information.

### Elements

Introducing the [Connect element](/elements/connect/overview) as the primary way to connect user accounts and complete necessary verifications.

The Auth element has been deprecated in favor of Connect.

See [Connect guide](/elements/connect/overview) for step-by-step instructions on leveraging Connect.


# Introducing API Version 2025-07-04
Source: https://docs.methodfi.com/changelog/api-versions/2025-07-04



We're excited to announce the release of **API version `2025-07-04`**, featuring key improvements to our **Card Brand** model and the introduction of the new **Card Products API**.
This version enhances data consistency across card networks, issuers, and products — enabling more structured integrations and cleaner brand experiences for your users.

***

## What’s New

### Card Brand API

<img alt="Card Brands" />

The [Card Brand API](/reference/accounts/card-brands/overview) has been expanded with a **richer, more structured object**.
This change makes it easier to **identify, display, and integrate** specific card products while ensuring consistent metadata across networks and issuers.

**Key improvements:**

* Brand data is now **fully nested**, encapsulating `network`, `issuer`, and visual assets under each brand.
* New fields such as `card_product_id`, `description`, and `type` provide more granular control when mapping and displaying cards.
* Removed legacy fields (`last4`, `shared`) for a cleaner, product-centric response format.

<Note>Available when passing `Method-Version: 2025-07-04` in the request header.</Note>

<Accordion title="Previous Response">
  ```json theme={null}
  {
    "id": "cbrd_eVMDNUPfrFk3e",
    "account_id": "acc_yVf3mkzbhz9tj",
    "network": "visa",
    "issuer": "Chase",
    "last4": "8623",
    "brands": [
      {
        "id": "brand_AMxtjQzAfDCRP",
        "name": "Chase Sapphire Reserve",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
      }
    ],
    "status": "completed",
    "shared": false,
    "source": "network",
    "error": null,
    "created_at": "2024-03-19T01:05:37.247Z",
    "updated_at": "2024-03-19T01:05:37.247Z"
  }
  ```
</Accordion>

<Accordion title="New Response">
  ```json theme={null}
  {
    "id": "cbrd_Accm7P6t6mYQP",
    "account_id": "acc_LxwEqNicr66yP",
    "brands": [
      {
        "id": "pdt_15_brd_1",
        "card_product_id": "pdt_15",
        "description": "Chase Sapphire Reserve",
        "name": "Chase Sapphire Reserve",
        "issuer": "Chase",
        "network": "visa",
        "network_tier": "infinite",
        "type": "specific",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
      }
    ],
    "status": "completed",
    "source": "method",
    "error": null,
    "created_at": "2025-08-12T00:56:50.139Z",
    "updated_at": "2025-08-12T00:56:50.139Z"
  }
  ```
</Accordion>

***

### Card Products API

We’re introducing the new [Card Products API](/reference/card-products/overview) — a **directory of card products** that allows you to retrieve all associated `Card Brand` objects for a given product.

This endpoint gives developers a unified way to reference and display card metadata (art, network, tier, and issuer) across all variants of a card family.

<Note>Available when passing `Method-Version: 2025-07-04` in the request header.</Note>

<Accordion title="Example Request">
  ```bash theme={null}
  curl https://production.methodfi.com/card_products/pdt_17 \
    -H "Method-Version: 2025-07-04" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```
</Accordion>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "pdt_17",
    "name": "Chase Freedom",
    "issuer": "Chase",
    "type": "specific",
    "brands": [
      {
        "id": "pdt_17_brd_1",
        "description": "Chase Freedom",
        "network": "visa",
        "network_tier": "signature",
        "default_image": "https://static.methodfi.com/card_brands/fb5fbd6a5d45b942752b9dc641b93d1f.png"
      },
      {
        "id": "pdt_17_brd_2",
        "description": "Chase Freedom",
        "network": "visa",
        "network_tier": "standard",
        "default_image": "https://static.methodfi.com/card_brands/6cb697528b0771f982f7c0e8b8869de3.png"
      }
    ]
  }
  ```
</Accordion>

***

## Breaking Changes

* **Card Brand response shape updated**

  * `network` and `issuer` are now nested under each `brand`.
  * New fields: `card_product_id`, `description`, `type`.
  * Removed fields: `last4`, `shared`.

***

## Why It Matters

This release unifies how card data is modeled and consumed across the Method platform.
By standardizing the `Card Brand` object and introducing a canonical `Card Products` directory, developers can now:

* Reliably map and display card details across networks and issuers
* Build consistent card selection and branding experiences in their apps
* Reduce dependency on ad-hoc naming or inferred card data

***

## Upgrading to 2025-07-04

The new API version is available to all existing teams. New teams are automatically pinned to **`2025-07-04`**.

* **Request Header:** Set `Method-Version` to `2025-07-04`. See [API Versioning](/reference/versioning#api-versioning) for more information.
* **Client Libraries:** `method-node` and `method-python` **v2.0.0+** default to this version.

> Once upgraded, rollbacks to prior API versions are not supported. Contact your Method CSM for upgrade assistance.

***

### Upgrade Support

Our technical integration team is available to guide you through the migration. Contact your Method CSM to schedule a review of your current card integration or to receive a personalized upgrade checklist.


# Introducing API Version 2025-12-01
Source: https://docs.methodfi.com/changelog/api-versions/2025-12-01



We're excited to announce the release of **API version `2025-12-01`**, featuring the new **Payment Instruments API** for inbound funding workflows.
This version enables liability accounts to receive direct payments via ACH or wire transfer — allowing third parties to send funds directly to liability accounts without requiring explicit Payment creation.

***

## What's New

### Payment Instruments API

Method now supports **inbound funding workflows** with the introduction of a new `PaymentInstrument` type: `inbound_achwire_payment`.
This feature allows liability accounts (e.g., loans, credit cards) to receive direct payments via ACH or wire transfer.

**Key features:**

* Provisions a unique virtual account number and routing number linked to a specific Method Account, effectively making the underlying liability routable
* Third parties can send funds directly to these credentials, and Method automatically applies the funds to the associated account, without requiring you to explicitly create a Payment
* Supports use cases such as payroll, refinancing, and other direct payment scenarios

**How it works:**

1. **Create Instrument**: Create a Payment Instrument of type `inbound_achwire_payment` for a specific Method Account
2. **Receive Banking Details**: Method returns unique `account_number` and `routing_number`
3. **Share with a Third Party**: Provide these banking details to a third party (e.g., payroll provider, refinance lender, or another bank)
4. **Inbound Transfer**: When funds are sent to these credentials, Method receives the inbound ACH or wire transfer
5. **Automatic Application**: Method automatically applies the received funds to the associated account

<Note>Available when passing `Method-Version: 2025-12-01` in the request header.</Note>

<Accordion title="Example Request">
  ```bash theme={null}
  curl https://production.methodfi.com/accounts/acc_4m9amk4KFiaQX/payment_instruments \
    -X POST \
    -H "Method-Version: 2025-12-01" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "inbound_achwire_payment"
    }'
  ```
</Accordion>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "pmt_inst_cLbaArHhfDBDf",
    "account_id": "acc_GAzrD99cUqGEN",
    "type": "inbound_achwire_payment",
    "card": null,
    "network_token": null,
    "inbound_achwire_payment": {
      "account_number": "2517228863",
      "routing_number": "026015244"
    },
    "chargeable": true,
    "status": "completed",
    "error": null,
    "created_at": "2025-12-11T00:12:58.639Z",
    "updated_at": "2025-12-11T00:12:58.639Z"
  }
  ```
</Accordion>

See [Payment Instruments](/reference/accounts/payment-instruments/overview) for more information.

***

### Simulate API

The [Simulate API](/reference/simulations/overview) now supports simulating inbound ACH / wire payments for `inbound_achwire_payment` Payment Instruments — making it easier for developers to test inbound payment flows in the development environment.

**[Simulate Inbound ACH/Wire Payments](/reference/simulations/payment_instruments/create)**\
This endpoint allows developers to simulate receiving an inbound payment and triggers the same automatic payment application logic used in production.

<Note>Available when passing `Method-Version: 2025-12-01` in the request header.</Note>

<Warning>This API is available in the development environment only.</Warning>

For more information, visit the [Simulations API](/reference/simulations/overview) documentation.

***

## Breaking Changes

* **Payment Instrument product names changed**

  * The `payment_instrument` product name has been split into three separate product names:
    * `payment_instrument.card`
    * `payment_instrument.network_token`
    * `payment_instrument.inbound_achwire_payment`
  * In previous versions (`2024-04-04`, `2025-07-04`), the Account object's `products`, `restricted_products`, `subscriptions`, `available_subscriptions`, and `restricted_subscriptions` arrays contained the single product name `payment_instrument`.
  * In `2025-12-01`, these arrays now contain the three separate product names instead of the single `payment_instrument` name.

***

## Why It Matters

This release enables new inbound funding workflows that simplify payment collection for liability accounts.
By introducing `inbound_achwire_payment` Payment Instruments, developers can now:

* Enable third parties to send payments directly to liability accounts without explicit Payment creation
* Streamline payroll, refinancing, and other direct payment scenarios
* Automatically apply inbound transfers to the associated account
* Test inbound payment flows more easily with enhanced Simulate API support

***

## Upgrading to 2025-12-01

The new API version is available to all existing teams. New teams are automatically pinned to **`2025-12-01`**.

* **Request Header:** Set `Method-Version` to `2025-12-01`. See [API Versioning](/reference/versioning#api-versioning) for more information
* **Client Libraries:** `method-node` and `method-python` **v2.1.0+** default to this version

> Once upgraded, rollbacks to prior API versions are not supported. Contact your Method CSM for upgrade assistance.

***

### Upgrade Support

Our technical integration team is available to guide you through the migration. Contact your Method CSM to schedule a review of your current payment integration or to receive a personalized upgrade checklist.


# Introducing API Version 2026-03-30
Source: https://docs.methodfi.com/changelog/api-versions/2026-03-30



We're excited to announce the release of **API version `2026-03-30`**, featuring redesigned **Attributes** for both **Entities** and **Accounts**.
This release expands the attributes product with richer computed outputs, a unified per-attribute result shape, and support for asynchronous attribute computation workflows.

***

## What's New

### Entity Attributes

The [Entity Attributes API](/reference/entities/attributes/overview) now returns a broader set of aggregated financial attributes computed across an Entity's connected accounts.
These attributes are organized across categories such as revolving credit cards, personal loans, mortgages, installment balances, and overall utilization.

**Key improvements:**

* Introduces a richer set of financial attributes, including balances, utilization trends, deltas, delinquency signals, and payment behavior metrics
* Returns attributes in a simplified `{ value, error }` shape — `error` uses the standard `{ type, sub_type, code, message }` format when the attribute could not be computed
* Computes all supported entity attributes automatically as part of the request lifecycle
* Supports asynchronous processing so teams can poll or rely on webhook-driven workflows for completion

<Note>Available when passing `Method-Version: 2026-03-30` in the request header.</Note>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "attr_dADraNgLBrhgL",
    "entity_id": "ent_EQ3FCTzDUmmCb",
    "status": "completed",
    "attributes": {
      "revolving_credit_card_balance_total": {
        "value": 968400,
        "error": null
      },
      "credit_limit_total": {
        "value": 8100000,
        "error": null
      },
      "credit_card_utilization": {
        "value": 11.96,
        "error": null
      },
      "overall_utilization": {
        "value": 70.5,
        "error": null
      }
    },
    "error": null,
    "created_at": "2026-04-09T17:02:47.910Z",
    "updated_at": "2026-04-09T17:04:35.220Z"
  }
  ```
</Accordion>

***

### Account Attributes

The [Account Attributes API](/reference/accounts/attributes/overview) has been expanded into a dedicated account-level attributes product.
Returned attributes now vary by liability type, including support for credit cards, personal loans, and mortgages.

**Key improvements:**

* Adds account-level financial attributes such as utilization trends, delinquency flags, and installment estimates
* Returns attributes in a simplified `{ value, error }` shape with standardized error objects
* Supports asynchronous attribute computation workflows for account requests
* Adds webhook support for account attribute lifecycle events

<Note>Available when passing `Method-Version: 2026-03-30` in the request header.</Note>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "acc_attr_cWBKqwVP87kim",
    "account_id": "acc_4m9amk4KFiaQX",
    "status": "completed",
    "attributes": {
      "type": {
        "value": "credit_card",
        "error": null
      },
      "usage_pattern": {
        "value": "revolver",
        "error": null
      },
      "delinquency_flag": {
        "value": false,
        "error": null
      },
      "utilization": {
        "value": 11.96,
        "error": null
      }
    },
    "error": null,
    "created_at": "2026-04-09T17:02:47.910Z",
    "updated_at": "2026-04-09T17:04:35.220Z"
  }
  ```
</Accordion>

***

### Account Attribute Subscriptions

Accounts can now be enrolled in an `attribute` [Subscription](/reference/accounts/subscriptions/overview) for
continuous monitoring of an Account's financial attributes. Once enrolled, Method automatically computes new
[Account Attributes](/reference/accounts/attributes/overview) and notifies your team via webhooks as they change.

```bash theme={null}
curl https://production.methodfi.com/accounts/{acc_id}/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "enroll": "attribute"
  }'
```

* Available for credit card, personal loan, and mortgage accounts
* The `attribute` subscription appears in an Account's `available_subscriptions` once eligible

<Note>Available when passing `Method-Version: 2026-03-30` in the request header.</Note>

***

### New Webhook Events

This version adds webhook coverage for the new account attribute resource lifecycle.

**New events:**

* `entity_attribute.create`
* `entity_attribute.update`
* `account_attribute.create`
* `account_attribute.update`

See [Webhooks](/reference/webhooks/overview) for the complete event list.

***

## Breaking Changes

* **Entity Attributes request semantics changed**

  * `POST /entities/{ent_id}/attributes` now computes all supported attributes automatically
  * The legacy request body for selecting specific `credit_health_*` attributes is no longer documented for `2026-03-30`

* **Entity Attributes response shape changed**

  * Legacy attribute payloads that returned `value` and `rating` have been replaced with a simplified `{ value, error }` shape
  * On success, `error` is `null`. On failure, `error` contains a standard `{ type, sub_type, code, message }` object (e.g. `ENTITY_ATTRIBUTE_INSUFFICIENT_DATA` code `27001` for entity attributes, `ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA` code `28001` for account attributes)
  * Attribute names now reflect the new attribute model

* **Account Attributes response shape changed**

  * Account attribute responses now use the same simplified `{ value, error }` result structure
  * Attribute availability now depends on the account's liability type

* **Attributes create endpoints are asynchronous**

  * Create requests now return an in-progress resource that must be polled or observed via webhook until completion

***

## Why It Matters

This release makes the attributes product more useful for underwriting, servicing, monitoring, and decisioning workflows.
With this release, developers can:

* Retrieve a richer set of entity- and account-level financial signals
* Build against a consistent result format across attributes
* Handle unavailable computations explicitly using standardized `error` objects with `type`, `sub_type`, `code`, and `message`
* Use asynchronous workflows that better fit long-running computations

***

## Upgrading to 2026-03-30

The new API version is available to all existing teams. New teams are automatically pinned to **`2026-03-30`**.

* **Request Header:** Set `Method-Version` to `2026-03-30`. See [API Versioning](/reference/versioning#api-versioning) for more information.
* **Client Libraries:** Check your Method SDK version and upgrade guidance before moving production traffic to the new API version.

> Once upgraded, rollbacks to prior API versions are not supported. Contact your Method CSM for upgrade assistance.

***

### Upgrade Support

Our technical integration team is available to help review your current usage of Attributes and plan a migration to `2026-03-30`. Contact your Method CSM for upgrade support.


# Create a Connect Element Token
Source: https://docs.methodfi.com/elements/connect/create_connect_token



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

To start using Connect, you will first need to create a [Connect Element Token](/reference/elements/tokens).
There are a few different use cases that will determine what you pass to the endpoint.

### New Entities

If you do not have any identity information about your users, you will likely create a token using a payload similar to this:

```json theme={null}
{
  "type": "connect",
  "connect": {
    "products": ["balance"],
    "entity": {
      "type": "individual",
      "individual": {}
    }
  }
}
```

This will return a token that you can use to create a new entity and connect their accounts. Fill in the `products` array with a list of the different products you want to connect (for example `["balance", "card"]`).

### New Entities with Partial Information

If you have some information already about a given user (such as their name), you can pass that information into the `individual` object:

```json theme={null}
{
  "type": "connect",
  "connect": {
    "products": ["balance"],
    "entity": {
      "type": "individual",
      "individual": {
        "first_name": "Kevin",
        "last_name": "Doyle"
      }
    }
  }
}
```

You can also pass in a user's phone number, address, DOB, or the last 4 digits of their SSN to make the identity verification process faster.

### Using with Existing Entities

You can also pass in an existing entity\_id:

```json theme={null}
{
  "type": "connect",
  "entity_id": "ent_au22b1fbFJbp8",
  "connect": {
    "products": ["balance"]
  }
}
```

### Using with Existing Accounts

If you also have specific accounts you'd like to connect, you can pass the account ids:

```json theme={null}
{
  "type": "connect",
  "entity_id": "ent_au22b1fbFJbp8",
  "connect": {
    "products": ["balance"],
    "accounts": ["acc_k8LAKDnED7kti", "acc_KUaFnxn7eUAeH"]
  }
}
```

<RequestExample>
  ```bash cURL theme={null}
  curl https://dev.methodfi.com/elements/token \
    -X POST \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "connect",
      "connect": {
        "products": ["balance"],
        "entity": {
          "type": "individual",
          "individual": {
            "first_name": "Kevin",
            "last_name": "Doyle"
          }
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const token = await method.elements.token.create({
    type: "connect",
    connect: {
      products: ["balance"],
      entity: {
        type: "individual",
        individual: {
          first_name: "Kevin",
          last_name: "Doyle"
        }
      }
    }
  });
  ```

  ```python Python theme={null}
  token = method.elements.token.create({
    'type': "connect",
    'connect': {
      'products': ["balance"],
      'entity': {
        'type': "individual",
        'individual': {
          'first_name': "Kevin",
          'last_name': "Doyle"
        }
      }
    }
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "element_token": "pk_elem_qPmypE9wwphr3WL3yTj7JhxjrPzAmK8G"
  }
  ```
</ResponseExample>


# Getting Connect Results
Source: https://docs.methodfi.com/elements/connect/get_results



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

In addition to [listening for the success event](/elements/events/overview), the result of the Connect session can also be retrieved by calling the `results` endpoint with the element token for that session.

```bash theme={null}
GET /elements/token/{element_token}/results
```

See [Retrieve Element Results](/reference/elements/results) for more information about this endpoint.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/elements/token/pk_elem_dDe4r9M6X3Ad9zjpbgYpzLNtRCXfhPYR/results \
    -X GET \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .elements
    .token
    .results('pk_elem_dDe4r9M6X3Ad9zjpbgYpzLNtRCXfhPYR');
  ```

  ```python Python theme={null}
  response = method
    .elements
    .token
    .results('pk_elem_dDe4r9M6X3Ad9zjpbgYpzLNtRCXfhPYR')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "authenticated": true,
    "cxn_id": "cxn_xr86xHEcWmpmB",
    "accounts": [
      "acc_jPXLFqd6KzH3N",
      "acc_DALLeLrj3TH8h"
    ],
    "entity_id": "ent_GWKYtnFyE79db",
    "events": [
      {
        "type": "open",
        "metadata": {
          "element_type": "connect",
          "op": "open"
        },
        "timestamp": "2024-04-25T02:35:28.097Z"
      },
      {
        "type": "success",
        "metadata": {
          "entity_id": "ent_GWKYtnFyE79db",
          "accounts": [
            "acc_jPXLFqd6KzH3N",
            "acc_DALLeLrj3TH8h"
          ],
          "element_type": "connect",
          "op": "success"
        },
        "timestamp": "2024-04-25T02:35:57.120Z"
      },
      {
        "type": "exit",
        "metadata": {
          "element_type": "connect",
          "op": "exit"
        },
        "timestamp": "2024-04-25T02:35:57.138Z"
      }
    ]
  }
  ```
</ResponseExample>


# Launching a Connect Session
Source: https://docs.methodfi.com/elements/connect/launch_connect



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

After creating a Connect Element token, you can launch a Connect session in a webview.

## Initializing the Connect Element

The Connect Element is optimized to work within Webviews, including on iOS and Android. Open a webview in your app to your desired environment using the `element_token` you generated.

Example:

Using the [Element SDK](/elements/libraries) (recommended):

```javascript theme={null}
method.open('pk_elem_BtzySdrQGFmLdAPw5gXSQNCxQkhCkT3K');
```

Without SDK:

```bash theme={null}
https://elements.production.methodfi.com/
  ?token=pk_elem_4PpMTPcchb49VBjwP3bREKhMN93hrQHR
```


# Connect Overview
Source: https://docs.methodfi.com/elements/connect/overview



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Connect is the primary way to leverage Method Elements to connect your users' liabilities. Connect allows you to verify a user's identity, gather their consent, and complete any needed verifications to ensure their accounts are connected to the desired Method [Products](/reference/accounts/products/overview).

The Connect element itself consists of two main steps:

<Steps>
  <Step title="Auth">
    Verify the user's identity and connect their accounts. If no entity
    information is provided when creating the Connect element token, the user
    will be asked to provide identity information such as name, phone, last 4
    digits of SSN, DOB, or address.
  </Step>

  <Step title="Account Verification">
    Request any additional information needed from the user to connect their
    accounts and leverage specific products.
  </Step>
</Steps>


# Environments
Source: https://docs.methodfi.com/elements/environments



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Elements are available in each of our three [Environments](/reference/environments):

```
https://elements.dev.methodfi.com (Development)
https://elements.sandbox.methodfi.com (Sandbox)
https://elements.production.methodfi.com (Production)
```

## Considerations for Connect

When using the [Connect Element](/elements/connect/overview), there are a few
things to keep in mind related to the different environments.

### Development Environment

In dev, you can use the following phone numbers to ensure your entity gets verified:

```bash theme={null}
Phone        | Required Fields
------------------------------
+15121231111 | Name, Phone
+15121231112 | Name, Phone, DOB (Date of Birth)
+15121231113 | Name, Phone, DOB (Date of Birth), Address
```

You can either pass in the required fields on token creation or during the Connect session.

**Note**: If you do not use one of the above phone numbers, your dev entities will not be verified.


# General Events
Source: https://docs.methodfi.com/elements/events/general_events



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

## Open

The open event is triggered when an element has successfully launched. No additional data is passed at this time.

```bash theme={null}
methodelements://general
  ?op=open
  &element_type=connect
```

The event payload will have the following form:

<ParamList />

## Error

The error event is sent for any element that encounters any error while it's active.

```bash theme={null}
methodelements://general
  ?op=error
  &element_type=unknown
  &type=INVALID_REQUEST
  &sub_type=EXPIRED_TOKEN
  &message=The public element token is no longer valid. Element tokens are short lived and can only be used once. Request a new element token and try your request again.
  &code=400
```

The event payload will have the following form:

<ParamList />

## Exit

The exit event is the last event in the element flow, at this point your app should no longer present the Method Element. Exit is triggered after an error, a user requested exit or a successful element event.

```bash theme={null}
methodelements://general
  ?op=exit
  &element_type=connect
```

The event payload will have the following form:

<ParamList />


# Events Overview
Source: https://docs.methodfi.com/elements/events/overview



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Communication between the Element and your app can be handled either by PostMessage communication or via HTTP redirects.

## Listening to Events

We strongly recommend using one of the [Element SDKs](/elements/libraries) to make listening to events easy. They provide you with callback functions that are invoked every time a specific type of event occurs (such as `open`, `success`, `exit`, etc).

Each type of Element will emit its own events. See [General Events](/elements/events/general_events) and [Element Specific Events](/elements/events/specific_events) for more information about the events that are emitted.

### PostMessage without SDK

To receive events via PostMessage, pass the query parameter `event_channel=message` to the Elements url. For example:

```bash theme={null}
https://elements.production.methodfi.com
  ?token=pk_elem_4PpMTPcchb49VBjwP3bREKhMN93hrQHR
  &event_channel=message
```

To listen to the emitted events, add an event listener onto the window object:

```javascript theme={null}
window.addEventListener('message', function(event) {
  const { payload, type } = event.data;
  console.log('Received event!', type, payload);
});
```

### Redirects

Redirects are the default way of listening to element events if you are not using one of the SDKs. Your webview / app should intercept the redirects in order to react accordingly to state changes. All redirect URLs will have the scheme ("prefix") `methodelements`. The event source will be the URL host and the payload will be query strings.

HTTP redirects from Method Elements are in the following format:

```bash theme={null}
methodelements://{event_source}?{event_data}
```


# Element Specific Events
Source: https://docs.methodfi.com/elements/events/specific_events



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

## Connect

Connect will emit a `success` event when the user has successfully completed all required authentication and verification:

```bash theme={null}
methodelements://connect
  ?op=success
  &element_type=connect
  &entity_id=ent_WyDmJnQgaxVRH
  &accounts=["acc_PFUNazUbpUpfm","acc_gjWr4Cb8H7TLz"]
```

When parsed, will result in the following JSON

```json theme={null}
{
  "op": "success",
  "element_type": "connect",
  "entity_id": "ent_WyDmJnQgaxVRH",
  "accounts": ["acc_PFUNazUbpUpfm","acc_gjWr4Cb8H7TLz"]
}
```

This will list all of the accounts that were consented and connected to at least one of the products passed into the Element token creation (Note: Some accounts are ineligible for some products).

## Other Events

For more granular information about specific actions a user is taking, `auth` and `account_verification` will emit the following events.

### Auth

Auth will emit a variety of events that describe how the user is progressing through the authentication process. Most events are of the following form:

```bash theme={null}
AUTH_{STEP}_{ACTION}
```

STEP will reference a step during the auth process: `INTRO`, `NAME`, `PHONE`, `PHONE_VERIFY`, `DOB`, `ADDRESS`, `SSN4`, `SECQ`, and `CONSENT`.

ACTION will refer to the action the user took: `OPEN`, `CONTINUE`, `SUBMIT`, and `CLOSE`.

**Note**: Not all steps will have all actions, and that there are a few actions that do not follow this pattern

For example, if the user was prompted for the last 4 of their SSN, then submitted their info and was directed to the DOB page, you would see the following events:

```bash theme={null}
AUTH_SSN4_OPEN
AUTH_SSN4_CONTINUE
AUTH_DOB_OPEN
```

### Account Verification

Account Verification will emit a variety of events using a similar structure to auth:

```bash theme={null}
AVF_{STEP}_{ACTION}
```

STEP will reference a step during the account verification process: `ACCOUNT_LIST`, `LEARN_MORE`, and `ACCOUNT_VERIFY`.

ACTION will refer to the action the user took: `OPEN`, `CONTINUE`, `SUBMIT`, `SKIP`, and `CLOSE`.

For example, if the user was prompted to verify their credit card, then submitted their info and was directed to the success screen, you would see the following events:

```bash theme={null}
AVF_ACCOUNT_VERIFY_OPEN
AVF_ACCOUNT_VERIFY_SUBMIT
AVF_SUCCESS_OPEN
```


# Element SDKs
Source: https://docs.methodfi.com/elements/libraries



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Method offers a variety of libraries for your frontend application to make integrating
with Elements easy and simple. We also offer [backend libraries](TODO:Where_is_link)
to help manage token creation and using the API more broadly.

## Frontend Libraries

Depending on your application, Method offers three different frontend libraries to help you integrate with Element:

1. [method-js](https://docs.methodfi.com/libraries/js-sdk), for vanilla JavaScript applications
2. [react-method-elements](https://github.com/MethodFi/react-method-elements), for React applications
3. [react-native-method-elements](https://github.com/MethodFi/react-native-method-elements), for React Native applications


# Overview
Source: https://docs.methodfi.com/elements/overview



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Method Elements is a collection of embeddable UI components that make it easy to
integrate Method's API into your experience. Using Method Elements, you can
securely identify your users, connect their liabilities, and move money across
accounts.

## Using Method Elements

<Steps>
  <Step title="Create Element Token">
    Your app's backend will generate an `element_token` by hitting the
    [/elements/token](/reference/elements/tokens) endpoint.
  </Step>

  <Step title="Initialize Element">
    Using the `element_token`, Method Elements will be
    [initialized](/elements/libraries) with the intended Element for your user.
  </Step>

  <Step title="Handling Element Events">
    While your user interacts with an Element,
    [events](/elements/events/overview) will be triggered for your app to
    handle.
  </Step>
</Steps>

### Authentication

Ensure you have an [API key created](/reference/authentication) for your organization in order to request an Element token.


# Handling Account Edge Cases
Source: https://docs.methodfi.com/guides/accounts/edge-cases

How to handle verification requirements, product limitations, and status changes.

## Handling Account Edge Cases

### 1. Accounts Requiring Verification

Some liability accounts discovered through [Connect](/guides/connect/overview) may appear in `restricted_products` with capabilities that require elevated verification (e.g., an account verification session). This is common for payment-capable accounts where Method needs additional confirmation. Create an [Account Verification Session](/reference/accounts/verification-sessions/create) to unlock these products.

### 2. Product Limitations by Account Type

Not all accounts support all products. Credit cards support [Card Brand](/reference/accounts/card-brands/overview) and [Payment Instruments](/reference/accounts/payment-instruments/overview); auto loans support [Payoffs](/reference/accounts/payoffs/overview); most liability types support [Updates](/guides/updates/overview) and [Balances](/reference/accounts/balances/overview). Always check the `products` array. See the [Liability Types](/guides/accounts/liability-types) page for a breakdown.

### 3. Status Changes Mid-Operation

If an account transitions to `disabled` or `closed` while you have in-flight operations (a pending payment, an in-progress update), those operations may fail. Design your flows to:

* Check account status before initiating operations
* Handle `account.disabled` and `account.closed` [webhooks](/reference/webhooks/overview) gracefully
* Show appropriate UI messages when an account is no longer available

See the [Account Lifecycle](/guides/accounts/lifecycle) guide for status transitions and webhook details.

### 4. Duplicate Accounts

[Connect](/guides/connect/overview) may discover the same underlying account multiple times if the user has accounts reported under slightly different names or through different credit bureaus. Method does attempt to de-duplicate these liability accounts, however instances do occur. Reach out to your CSM if this uncommon event occurs for one of your users.

### 5. Authorized User Accounts

Connect discovers all accounts on a user's credit report, including accounts where they are an authorized user (not the primary holder). The `liability.ownership` field indicates the relationship: `primary`, `authorized`, `joint`, or `unknown`. Consider whether your product should treat authorized-user accounts differently (e.g., payments on authorized-user cards may not be appropriate for [debt consolidation flows](/guides/use-cases/lending/debt-consolidation)).

### 6. Closed / Paid-Off Accounts

Accounts with zero balance or closed status at the financial institution may still appear in Connect results (they remain on the credit report). These accounts will have `status: closed` and limited [product](/reference/accounts/products/overview) availability. Filter them in your UI if they're not relevant to your use case.

### 7. Consent and Data Retention

When an Entity's consent is withdrawn (via the [Consent endpoint](/reference/accounts/consent/withdraw)), their accounts are disabled and data access is revoked. Your application should handle this gracefully — remove the accounts from active views and inform the user.

***

The key principle: design your application to check account status and product availability dynamically, and listen for [webhook notifications](/reference/webhooks/overview) about status changes. Accounts are living objects, and your application should respond to their state changes in real time rather than assuming a static state.

For the full Accounts API, see the [Accounts reference](/reference/accounts/overview).


# Funding Accounts
Source: https://docs.methodfi.com/guides/accounts/funding

Setting up and verifying your corporate payment source.

## Funding Accounts — Setting Up Payment Sources

Before payments can flow through Method, your platform needs a verified funding source — an ACH account that serves as the origin for all outbound payments. This is typically your company's corporate checking account, not an account belonging to your end users.

Your platform creates the funding account by [calling the Accounts API](/reference/accounts/create) with the routing number and account number for your corporate bank account:

```bash theme={null}
curl https://production.methodfi.com/accounts \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "holder_id": "ent_y1a9e1fbnJ1f3",
    "ach": {
      "routing": "021000021",
      "number": "1234567890",
      "type": "checking"
    }
  }'
```

The account must then be verified to confirm your organization controls it. Once verified, this single funding account can serve as the payment source across all of your users' liability payments.

<Note>
  Funding accounts are set up by your team (the platform integrating with Method), not by your end users. End users interact with liability accounts discovered through Connect — your corporate funding account is the source that powers payments to those liabilities.
</Note>

Method supports several verification approaches for funding accounts:

<CardGroup>
  <Card title="Micro-Deposits" icon="coins">
    The traditional verification method. Method sends two small deposits (typically a few cents each) to your corporate bank account. Your team confirms the deposit amounts, proving control of the account. This is universally supported but introduces a 1–2 business day delay while deposits settle.
  </Card>

  <Card title="Plaid" icon="bolt">
    Instant verification through Plaid's bank linking flow. If your platform already uses Plaid, this is a natural fit — authenticate with your bank through Plaid, and the verified account details are passed to Method. No waiting for micro-deposits.
  </Card>

  <Card title="MX" icon="bolt">
    Similar instant verification through MX's bank connectivity platform. Choose this if your platform uses MX for bank account linking.
  </Card>

  <Card title="Teller" icon="bolt">
    Another instant verification path through Teller's banking API. Like Plaid and MX, this eliminates the micro-deposit delay by verifying the account through direct bank authentication.
  </Card>
</CardGroup>

<Note>
  For most teams, instant verification (via Plaid, MX, or Teller) is strongly preferred because it eliminates the multi-day delay of micro-deposits and simplifies initial setup. If you don't have an existing relationship with any of these providers, Plaid is the most widely adopted option.
</Note>

## Verification Flow

1. Create the funding account ([`POST /accounts`](/reference/accounts/create))
2. Create a verification session ([`POST /accounts/{id}/verification_sessions`](/reference/accounts/verification-sessions/create)) specifying your preferred method
3. Complete the verification:
   * **Micro-deposits**: Wait 1–2 business days, then [update the session](/reference/accounts/verification-sessions/update-microdeposits) with the deposit amounts
   * **Plaid / MX / Teller**: Pass the processor token from your aggregator to the update endpoint ([Plaid](/reference/accounts/verification-sessions/update-plaid), [MX](/reference/accounts/verification-sessions/update-mx), [Teller](/reference/accounts/verification-sessions/update-teller))
4. Listen for the `account.active` [webhook](/reference/webhooks/overview) — the account is now ready for payments

See the [Account Verification Sessions reference](/reference/accounts/verification-sessions/overview) for full API details.

<Warning>
  If verification fails (wrong micro-deposit amounts, invalid aggregator token), the verification session moves to a `failed` status. You can create a new verification session to retry. After 3 failed micro-deposit attempts, the account may require a fresh set of deposits.
</Warning>

<Note>
  Your team can have multiple verified funding accounts. When [creating a payment](/reference/payments/create), you specify which funding account to use as the source. Most teams use a single corporate checking account, but you can set up additional funding accounts if your business requires separate payment sources.
</Note>


# Supported Liability Types
Source: https://docs.methodfi.com/guides/accounts/liability-types

The full range of consumer debt types Method supports.

## The Breadth of Supported Liability Types

Method supports an extensive range of liability types, reflecting the diversity of consumer debt in the real world. Supported types include:

* Credit cards — `credit_card` (from major national issuers to regional and community banks)
* Auto loans — `auto_loan` (from captive lenders like GM Financial and Toyota Motor Credit to banks and credit unions)
* Federal and private student loans — `student_loans`
* Personal and installment loans — `personal_loan`
* Mortgages and home equity lines of credit (HELOCs) — `mortgage`
* Collections accounts — `collection`
* Medical debt — `medical`
* Insurance premium obligations — `insurance`
* Utility accounts — `utility`
* Buy Now Pay Later (BNPL) accounts — `bnpl`
* Credit builder accounts — `credit_builder`
* Fintech-originated loans — `fintech`
* Other loan types — `loan`

The values above are the possible `liability.type` enum values on an Account. The `liability.sub_type` field provides additional granularity (e.g., `federal` vs. `private` for student loans, `heloc` for home equity lines). See the [Account reference](/reference/accounts/overview) for the complete list.

## How Liability Type Affects the Data Model

Each liability type also determines what enrichment data is available:

* **Credit cards**: Card brand name and visual art (via [Card Brands](/reference/accounts/card-brands/overview)), tokenized card credentials (via [Payment Instruments](/reference/accounts/payment-instruments/overview))
* **Auto loans**: Payoff quotes (via [Payoffs](/reference/accounts/payoffs/overview)), vehicle details including VIN, make, model (via [Vehicles](/reference/entities/vehicles/overview) on the Entity)
* **Student loans**: Federal vs. private distinction, servicer information
* **All types**: Credit health attributes (via [Attributes](/reference/accounts/attributes/overview)) where credit bureau data exists

<Note>
  Not every liability type supports every Method product. For example, Payments may be available for credit cards and auto loans but not for certain utility or collections accounts. Card Brand data is only relevant for credit cards. Payoff quotes are specific to auto loans. Each account carries a list of available [products](/reference/accounts/products/overview) so your application can adapt its UI and functionality based on what's supported for each specific account.
</Note>


# Account Lifecycle
Source: https://docs.methodfi.com/guides/accounts/lifecycle

Account statuses, available products, and state transitions.

## Account Lifecycle and Status

Accounts move through a defined set of statuses that reflect their current state:

| Status         | Description                                                                                                                                                                                                                                                 |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Active**     | The account is fully connected, verified (if applicable), and ready for use. All supported products are available. This is the normal operating state for most accounts.                                                                                    |
| **Processing** | The account is being set up or verified. For liability accounts, this may be a brief transitional state during discovery. For funding accounts, this typically means verification is in progress (e.g., waiting for micro-deposit confirmation).            |
| **Disabled**   | The account has been deactivated within Method. The account may still be active at the financial institution, but Method will not perform new operations on it. This can happen if the account is flagged for an issue or explicitly disabled by your team. |
| **Closed**     | Method has detected that the account is closed at the financial institution. The debt may have been paid off, the card may have been canceled, or the loan may have been settled. No new operations are available, but historical data remains accessible.  |

<Warning>
  **Common causes of Disabled status:** the Entity's [consent](/reference/accounts/consent/withdraw) was withdrawn, the Entity's verification expired or was revoked, the account was flagged by Method's risk monitoring, or your team explicitly disabled it via the API. Check the account's `error` field for the specific reason.
</Warning>

## State Transitions

* **Processing → Active**: Account setup or verification completes successfully
* **Active → Disabled**: Account is flagged for an issue or explicitly disabled. May be reversible — listen for `account.active` webhooks
* **Active → Closed**: Method detects the account is closed at the financial institution (debt paid off, card canceled, loan settled)
* **Disabled → Active**: The issue is resolved and the account is re-enabled
* **Closed** is terminal — closed accounts do not reopen

<Note>
  **Webhook tip:** Subscribe to `account.active`, `account.disabled`, and `account.closed` [webhook events](/reference/webhooks/overview) to handle transitions in real time rather than polling.
</Note>

### Key Webhooks

* `account.active`: Account transitioned to Active
* `account.disabled`: Account was disabled
* `account.closed`: Account was closed
* `account.update.completed`: An [Update](/guides/updates/overview) finished (balance/data refreshed)

## Subscriptions: Automatic Data Refresh

Instead of manually requesting [Updates](/guides/updates/overview) or [Balances](/reference/accounts/balances/overview), you can subscribe an account to automatic refresh. When subscribed, Method periodically fetches fresh data and notifies you via webhook. See [Update Subscriptions](/guides/updates/subscriptions) for details.

The `subscriptions` and `available_subscriptions` arrays on each Account show what's currently active and what can be enabled.

## Products and the Lifecycle

Each account carries a `products` array — the list of Method capabilities currently available for that account. Products include: `update` (refresh balances/data), `balance` (real-time balance), `payment` (send funds to creditor), `card_brand` (card art and product name), `payoff` (auto loan payoff quotes), `sensitive` (full account numbers), `attribute` (credit health metrics), and `payment_instrument` (card tokenization).

Product availability depends on three factors:

1. **Account type**: `card_brand` only applies to credit cards, `payoff` only to auto loans (see [Liability Types](/guides/accounts/liability-types))
2. **Account status**: Disabled and Closed accounts lose most products
3. **Team configuration**: Some products require team-level enablement (check `restricted_products`)

Always check the `products` array before attempting an operation. Attempting an operation not in `products` will return an error. See the [Products reference](/reference/accounts/products/overview) for the full list.


# Accounts
Source: https://docs.methodfi.com/guides/accounts/overview

Liability and funding accounts — the financial objects at the heart of your product.

<Note>
  **Using Opal?** If you're using [Opal](/guides/opal), Method's embedded UI, liability account discovery is handled for you — users complete a soft credit pull and see their accounts inside Opal's Connect flow. You'll still work with the resulting `Account` objects in your backend for payments, monitoring, and ongoing display in your app. Funding accounts are always configured by your team via the API. The rest of this section is most relevant if you're building a custom integration or want to understand the underlying data model.
</Note>

## What a Method Account Represents

An Account in Method is a connected financial account that belongs to one of your users ([Entities](/guides/entities/overview)). Accounts are the objects your product primarily interacts with. You pull data from accounts, monitor accounts for changes, make payments to accounts, and build your user-facing displays around account information.

Every Account belongs to an [Entity](/guides/entities/overview), the person whose financial life you're working with. An Entity can have many Accounts (a typical consumer has 5–15 liability accounts). You'll interact with Accounts through the Entity that owns them: create an Entity, verify their identity, run [Connect](/guides/connect/overview) to discover their liabilities, then work with the resulting Account objects.

Every account in Method falls into one of two categories, and understanding this distinction is essential for designing your product's payment and data flows:

<Tabs>
  <Tab title="Liability Accounts">
    Represent debts and financial obligations. These are the credit cards, auto loans, other obligations that your users owe money on. Liability accounts are typically discovered automatically through [Connect](/guides/connect/overview) and serve as the destination for payments, this is where money goes when your user pays down debt.
  </Tab>

  <Tab title="Funding Accounts">
    Represent the bank account your platform pays from. This is typically your corporate checking or savings account linked via ACH that serves as the source of funds for all payments. Funding accounts are created by your team by providing routing and account number details, and must be verified before they can be used.
  </Tab>
</Tabs>

In payment flows, the model is simple: money flows from your platform's funding account (source) to a liability account (destination). Your corporate bank account funds the payment; the end user's creditor receives it.

## How Accounts Are Created

Liability accounts are typically discovered automatically through [Connect](/guides/connect/overview). When you run Connect for an Entity, Method pulls their credit report and creates `Account` objects for every discovered liability. You can also [create liability accounts manually via the API](/reference/accounts/create) if you have the account details.

Funding accounts are created by your team through the API by providing a routing number and account number. See [Funding Accounts](/guides/accounts/funding) for setup and verification details.

## Account Products: What You Can Do With an Account

Every Account carries two arrays that control what operations are available:

* `products`: Capabilities currently available (e.g., `balance`, `payment`, `update`, `card_brand`, `payoff`, `sensitive`, `payment_instrument`)
* `restricted_products`: Capabilities the account could support but require additional steps (like elevated verification or team-level enablement), or capabilities the account does not currently support

Always check `products` before attempting an operation. For example, not all liability types support `payment` — attempting to create a payment on an account without `payment` in its `products` list will fail. See the [Products reference](/reference/accounts/products/overview) for the full list.

***

For the full Accounts API, including all fields, endpoints, and expandable resources, see the [Accounts reference](/reference/accounts/overview).


# Core Concepts
Source: https://docs.methodfi.com/guides/concepts

The mental model for Method's platform — objects, relationships, and data flow.

This section provides a bird's-eye view of Method's core concepts and how they relate to each other. Think of it as the mental model you'll carry throughout the rest of this guide, every section that follows goes deeper on one of these concepts.

## The Core Platform Objects

<CardGroup>
  <Card title="Entity" icon="user" href="/guides/entities/overview">
    A user's identity in Method. An Entity represents one individual (or business) and serves as the root object for all accounts, verifications, and transactions. Each user in your application maps to exactly one Entity.
  </Card>

  <Card title="Identity Verification (IDV)" icon="shield-check" href="/guides/identity-verification/overview">
    Verifies that a user is who they claim to be before Method can access credit data or process payments. IDV includes phone verification and identity verification and acts as a one-time gate that unlocks downstream products.
  </Card>

  <Card title="Connect" icon="link" href="/guides/connect/overview">
    Discovers what a user owes. Using a verified Entity, Connect performs a soft credit pull to automatically identify liabilities across financial institutions, giving your application visibility into a user's full debt profile.
  </Card>

  <Card title="Accounts" icon="building-columns" href="/guides/accounts/overview">
    The financial objects your application interacts with. Accounts include discovered liabilities (credit cards, loans, etc.) and funding sources used for payments. They are the objects you monitor, update, and pay against.
  </Card>

  <Card title="Updates" icon="arrows-rotate" href="/guides/updates/overview">
    Provides fresh data about accounts. Updates deliver the latest balances, due dates, minimum payments, interest rates, and more through credit report snapshots or direct institutional connections.
  </Card>

  <Card title="Payments" icon="money-bill-transfer" href="/guides/payments/overview">
    Moves money to pay down liabilities. You initiate a payment from a verified funding source, and Method handles the full lifecycle: submission, processing, delivery to the creditor, and confirmation.
  </Card>
</CardGroup>

## The Dependency Chain

These concepts build on each other in a natural progression. Not every integration uses every product, a monitoring-only product might skip Payments entirely, while a paydown-focused product might use all of them. But the dependency chain means you always start with an Entity, verify their identity, and connect their accounts before you can take action.

### Typical End-to-End Flows

| Flow               | Path                                                         |
| ------------------ | ------------------------------------------------------------ |
| **Debt discovery** | Entity → IDV → Connect → Accounts → Updates                  |
| **Debt paydown**   | Entity → IDV → Connect → Accounts → Payments → Updates       |
| **Monitoring**     | Entity → IDV → Connect → Accounts → Subscriptions → Webhooks |

<Note>
  **Using Opal?** Opal handles Entity creation, identity verification, and account discovery in a single embedded flow. If you're using Opal, you don't build the first three steps yourself — Opal orchestrates them for you, and your integration picks up at the Accounts stage.
</Note>

## Additional Products

Beyond the six core concepts, Method offers specialized products that enrich the data and capabilities available on connected accounts.

### Commonly Used

<CardGroup>
  <Card title="Credit Score" icon="chart-line" href="/guides/additional-products/credit-scores">
    Credit score retrieval and monitoring, essential for financial wellness products that want to show users their score alongside their debt profile.
  </Card>

  <Card title="Attributes" icon="chart-pie" href="/guides/additional-products/attributes">
    Delivers structured credit health metrics (e.g., credit card usage, payment history), useful for building personalized insights, recommendations, or risk assessments.
  </Card>

  <Card title="Card Brand" icon="credit-card" href="/guides/additional-products/card-brand">
    Retrieves the specific card product name and card art (e.g., "Chase Sapphire Preferred" with the actual card image), great for building visually rich account displays.
  </Card>
</CardGroup>

### Specialized

<CardGroup>
  <Card title="Vehicles" icon="car" href="/guides/additional-products/vehicles">
    Enriches auto loan accounts with vehicle details (make, model, VIN), valuable for auto-focused lending or insurance products.
  </Card>

  <Card title="Sensitive" icon="lock" href="/guides/additional-products/sensitive">
    Provides gated access to full account numbers and other sensitive data, available by approval only, for use cases that require raw account credentials.
  </Card>

  <Card title="Payment Instruments" icon="wallet" href="/guides/payments/instruments">
    Creates reusable payment configurations (card credentials, ACH details, network tokens), enables repeated payment scenarios without re-collecting credentials each time.
  </Card>
</CardGroup>

Most integrations use a subset of these products. A basic debt discovery app needs only Entities, IDV, Connect, and Updates. A payment-focused product adds Payments and a Funding Account. Start with what your use case requires — you can enable additional products as your product evolves.

<CardGroup>
  <Card title="API Reference" icon="code" href="/reference/introduction">
    Full endpoint documentation for every object described above.
  </Card>
</CardGroup>


# Errors and Edge Cases
Source: https://docs.methodfi.com/guides/connect/errors

Common Connect errors and how to handle them.

## Common Connect Errors

### Request errors (returned immediately)

* **`ENTITY_VERIFICATION_MISSING`**: Entity must be fully verified before Connect. Complete both phone and identity verification first. See [Identity Verification](/guides/identity-verification/overview).
* **`TEAM_CAPABILITY_RESTRICTED`**: Your team doesn't have access to Connect. Contact your CSM.
* **`ACCOUNT_CONSENT_UNAVAILABLE`**: Account consent isn't available for your organization.

### Async errors (returned after processing)

* **`THIN_CREDIT_FILE`**: No tradelines found. The user has no credit history reportable to bureaus.
* **`CREDIT_FREEZE`**: The user has a credit freeze in place. The user must lift their freeze before discovery can complete.
* **`PRODUCT_EXECUTION_FAILED`**: A downstream product (balance, update, etc.) failed to execute on connected accounts. The Connect itself succeeded, but some product data may be missing.

<Warning>
  **Credit freeze messaging.** If a user hits `CREDIT_FREEZE`, surface a clear message explaining they need to lift their credit freeze.
</Warning>

For the full list of Connect error codes, see the [Connect Errors reference](/reference/errors/connect-errors).


# How Connect Works
Source: https://docs.methodfi.com/guides/connect/how-it-works

Soft-pull credit reports, auto vs manual discovery, and coverage.

## How Discovery Works

Connect uses the verified Entity's personally identifying information and the user's consent to perform a soft-pull credit report. A soft pull is fundamentally different from a hard credit inquiry — it has zero impact on the user's credit score and leaves no visible mark on their credit report. This is important messaging for your users, who may be hesitant about anything that touches their credit.

The credit report reveals the user's open liabilities across financial institutions. Method parses this data, matches it against its network of 15,000+ supported institutions, and creates account objects for each discovered liability. These accounts are immediately available in your application for data retrieval, monitoring, and (where supported) payment processing.

<Tip>
  **Processing time.** Connect typically completes within seconds for most users. Users with extensive credit histories (many open accounts) may take slightly longer.
</Tip>

<Tip>
  **Account matching.** Method matches each tradeline on the credit report against its network of 15,000+ financial institutions. When a match is found, Method creates an Account object with the appropriate `products` array based on what's supported for that merchant and liability type. Unmatched tradelines (institutions not in Method's network) are not returned.
</Tip>

## Complete Connect Flow

### Step 1: Create a Connect

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "products": ["balance", "update"],
    "subscriptions": ["update"]
  }'
```

### Step 2: Wait for completion

Connect processes asynchronously when products or subscriptions are specified, or when the `Prefer: respond-async` header is set. Listen for the `connect.update` webhook to know when discovery is complete:

```json theme={null}
{
  "id": "cxn_4ewMmBbjYDMR4",
  "type": "connect.update",
  "path": "/entities/ent_au22b1fbFJbp8/connect/cxn_4ewMmBbjYDMR4"
}
```

### Step 3: Retrieve results

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect/cxn_4ewMmBbjYDMR4 \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

<Tip>
  **Expand for efficiency.** Use the `expand` query parameter to include full Account objects, balances, card brands, or other data in the Connect response, avoiding additional API calls: `?expand=accounts,accounts.balance,accounts.card_brand`
</Tip>

## Synchronous vs Asynchronous Processing

A bare Connect request (no products, no subscriptions, no `Prefer: respond-async` header) processes synchronously — the response includes the completed results immediately.

When you include `products`, `subscriptions`, or the `Prefer: respond-async` header, Connect processes asynchronously. The response returns immediately with `status: pending` or `status: in_progress`, and you'll receive a `connect.update` webhook when processing completes.

<Note>
  **Recommendation:** Always set up webhooks for Connect. Even synchronous requests can take several seconds for users with many liabilities, and products/subscriptions always trigger async processing.
</Note>

## Requesting Products and Subscriptions at Connect Time

Connect can automatically execute products and set up subscriptions on all discovered accounts in a single call. This eliminates the need to iterate over accounts and make individual product requests after discovery.

**Available products:**

* `balance`: Retrieve balances for all discovered accounts
* `update`: Pull real-time data from source institutions
* `card_brand`: Retrieve card brand art and product names
* `attribute`: Pull structured credit health metrics
* `payoff`: Get payoff quotes (auto loans)

**Available subscriptions:**

* `update`: Subscribe to real-time data refreshes
* `update.snapshot`: Subscribe to periodic snapshot updates
* `card_brand`: Subscribe to card brand changes
* `transaction`: Subscribe to new transaction events

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "products": ["balance", "card_brand"],
    "subscriptions": ["update"]
  }'
```

<Note>
  Products and subscriptions are only executed on accounts where they're available. If an account doesn't support a product, requesting it won't cause an error — it simply won't apply to that account.
</Note>

## Connect Statuses

* `pending`: The Connect request is queued for processing
* `in_progress`: Discovery is actively running (soft pull being performed, accounts being matched)
* `completed`: Discovery finished successfully, accounts are available
* `failed`: Discovery failed (see error object for details)

Poll the Connect status or listen for `connect.update` webhooks to track progress.

## Connect vs. Manual Connect

Connect is the automatic discovery path — Method finds the accounts for you. But there are scenarios where you already have account data from another source (a prior data pull, user input, a partner integration) and want to register those accounts in Method without re-discovering them. That's what Manual Connect is for.

Manual Connect creates account objects from data you provide, bypassing the credit report discovery step. This is useful for: migrating existing users from a legacy system, supplementing discovered accounts with additional accounts the user provides manually, or connecting accounts that aren't reported to credit bureaus (and therefore wouldn't be discovered through Connect).

<Tabs>
  <Tab title="Connect (Auto Discovery)">
    Method performs a soft-pull credit report and automatically discovers the user's liabilities.

    **Use when:**

    * Onboarding new users
    * You want the broadest possible account discovery
    * Users don't know all their account details

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```
  </Tab>

  <Tab title="Manual Connect">
    You provide raw credit report tradeline data and Method creates account objects from it, bypassing the soft-pull step.

    **Use when:**

    * Migrating existing users from a legacy system where you already have their bureau data
    * Ingesting tradelines pulled directly from Equifax or TransUnion via your own bureau relationship
    * Backfilling historical tradeline data for an Entity

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/manual_connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "bureau": "transunion",
        "tradelines": [
          {
            "type_code": "18",
            "portfolio_type_code": "revolving",
            "designator_code": "individual",
            "number": "5555555555555555",
            "creditor_name": "CAPITAL ONE",
            "creditor_code": "01DTV001",
            "balance": 500000,
            "highest_balance": 750000,
            "credit_limit": 1000000,
            "term": null,
            "next_payment_minimum_amount": 15000,
            "last_payment_amount": 20000,
            "payment_history": ["1", "1", "1"],
            "past_due_amount": 0,
            "delinquency_charge_off_amount": 0,
            "opened_at": "2016-11-25",
            "last_activity_date": "2024-05-01",
            "reported_date": "2024-05-01",
            "next_payment_due_date": "2024-06-01",
            "last_payment_date": "2024-05-01",
            "delinquency_first_start_date": null,
            "narrative_codes": [
              { "code": "FE", "description": "CREDIT CARD" }
            ]
          }
        ]
      }'
    ```

    <Note>
      Manual Connect ingests **raw bureau tradelines** — it expects the full schema your bureau returns (creditor codes, payment history, delinquency dates, narrative codes, etc.). It is not a lightweight "user enters a missing account" flow. See the [Manual Connect reference](/reference/entities/manual-connect/create) for the full tradeline schema.
    </Note>
  </Tab>
</Tabs>

## Coverage — What Gets Discovered

Connect's coverage spans the broad spectrum of consumer liabilities, including:

<Accordion title="Supported liability types">
  * Credit cards from major issuers and regional banks
  * Auto loans from captive lenders and financial institutions
  * Federal and private student loans
  * Personal and installment loans
  * Mortgages and home equity lines of credit (HELOCs)
  * Collections accounts
  * Medical debt
  * Insurance payment obligations
  * Utility accounts
  * Buy Now Pay Later (BNPL) obligations
  * Credit builder accounts
  * Fintech-originated loans
</Accordion>

<Note>
  **Coverage notes:**

  * Credit cards, auto loans, and student loans have the broadest coverage across issuers
  * Collections accounts are reported inconsistently across bureaus — some may not appear
  * BNPL and utility accounts have growing but variable coverage
  * Closed accounts are included in the first Connect call but may have limited product availability
  * Coverage varies by specific institution, not just liability type. A major bank's credit cards will have broader product support than a small regional lender's
</Note>

## Expanding Connect Results

Use the `expand` query parameter to include full Account objects and their sub-resources directly in the Connect response, eliminating additional API calls:

```
POST /entities/{ent_id}/connect?expand=accounts,accounts.balance,accounts.card_brand
```

Available expansions: `accounts`, `accounts.balance`, `accounts.card_brand`, `accounts.attribute`, `accounts.update`, `accounts.payment_instrument`, `accounts.latest_verification_session`. If you expand a sub-field, the parent `accounts` expansion is applied automatically.


# Connect — Account Discovery
Source: https://docs.methodfi.com/guides/connect/overview

How Method discovers your users' complete liability picture.

<Frame>
  <img alt="Connect" />
</Frame>

<Note>
  **Using Opal?** If you're using Method's embedded UI, Opal handles account discovery as part of its managed flow — you don't need to call the Connect API directly. See the [Opal guide](/opal/overview) for details. The rest of this section is for custom API integrations.
</Note>

## What Connect Does

Connect discovers and links all of a user's financial liabilities in a single API call. Using the Entity's verified identity, Connect performs a soft-pull credit report and matches the results against Method's network of 15,000+ supported financial institutions. Each discovered liability becomes an Account object in your application, immediately available for data retrieval, monitoring, and payments where applicable.

## When to Use Connect

Connect is the standard path for any product that needs a comprehensive view of a user's debts: debt management, financial wellness, lending (pre-qualification, consolidation, portfolio monitoring), and bill pay. If your product involves consumer liabilities, Connect is almost certainly how you'll discover them.

## Prerequisites

Before calling Connect, the Entity must be fully verified (both phone and identity verification completed). Attempting Connect on an unverified Entity returns `ENTITY_VERIFICATION_MISSING`. See [Identity Verification](/guides/identity-verification/overview) for details.

## What Comes Back

A successful Connect returns a list of Account IDs representing the user's discovered liabilities. Each Account includes the merchant (who the debt is owed to), the liability type (credit card, auto loan, mortgage, etc.), and the `products` array indicating what Method can do with that account (balance retrieval, real-time updates, payments).

```json theme={null}
{
  "id": "cxn_4ewMmBbjYDMR4",
  "entity_id": "ent_qKNBB68bfHGNA",
  "status": "completed",
  "accounts": [
    "acc_eKKmrXDpJBKgw",
    "acc_GV8WbmJW7KGRy",
    "acc_MLPKh9gQDDbT8"
  ],
  "requested_products": [],
  "requested_subscriptions": [],
  "error": null,
  "created_at": "2024-04-12T14:56:46.645Z",
  "updated_at": "2024-04-12T14:56:46.645Z"
}
```

<Tip>
  **First Connect vs. subsequent calls.** The first Connect for an Entity returns all discovered liabilities (active and closed). Subsequent Connect calls for the same Entity only return *new* accounts that weren't in previous results. This is important for re-discovery flows — you won't get duplicates.
</Tip>

## Understanding Account Products

Each Account returned from Connect has a `products` array indicating what Method supports for that merchant:

* `balance`: retrieve the current balance
* `update`: pull real-time data (balances, rates, due dates) directly from the institution
* `payment`: send payments to this account through Method
* `sensitive`: access full account numbers (gated, requires approval)

Not every account supports every product. A credit card from a major issuer will likely have `balance`, `update`, and `payment`. A collections account may only have `balance`. Check `products` before building flows that assume full coverage.

## Next Steps

* [How Connect Works](/guides/connect/how-it-works): Soft pulls, auto vs manual discovery, coverage details
* [Handling Partial Results](/guides/connect/partial-results): Designing for incomplete discovery
* [Connect Subscriptions](/guides/connect/subscriptions): Monitoring for new liabilities over time
* [Connect API Reference](/reference/entities/connect/overview): Full endpoint documentation


# Handling Partial Results
Source: https://docs.methodfi.com/guides/connect/partial-results

Designing for incomplete discovery results.

# Handling Partial Results

<Note>
  Connect may not discover every liability a user has. Design your product to treat partial results as the normal case.
</Note>

## Why Results May Be Incomplete

**Not all liabilities appear on credit reports.** Some debts (private loans between individuals, certain employer-provided benefits, some BNPL arrangements) are never reported to credit bureaus and won't be found by Connect.

**Reporting delays.** New accounts may not appear on a credit report for 30–60 days after opening. A user who just opened a credit card last week won't see it in Connect results yet.

**Unmatched institutions.** Method's network covers 15,000+ institutions, but some smaller or newer creditors may not yet be supported. The tradeline exists on the credit report, but Method can't create an actionable Account from it because the institution isn't in Method's network.

**Closed accounts.** The first Connect returns both open and closed accounts. Closed accounts may have limited product availability (e.g., no payments, no updates).

## Recommended Patterns

### Show what was found, supplement where possible

After Connect completes, display the discovered accounts. If you have access to additional bureau data the user, you can supplement the discovered set by ingesting raw credit report tradelines via [Manual Connect](/reference/entities/manual-connect/create):

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/manual_connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "bureau": "transunion",
    "tradelines": [
      {
        "type_code": "18",
        "portfolio_type_code": "revolving",
        "designator_code": "individual",
        "number": "5555555555555555",
        "creditor_name": "CAPITAL ONE",
        "creditor_code": "01DTV001",
        "balance": 500000,
        "highest_balance": 750000,
        "credit_limit": 1000000,
        "term": null,
        "next_payment_minimum_amount": 15000,
        "last_payment_amount": 20000,
        "payment_history": ["1", "1", "1"],
        "past_due_amount": 0,
        "delinquency_charge_off_amount": 0,
        "opened_at": "2016-11-25",
        "last_activity_date": "2024-05-01",
        "reported_date": "2024-05-01",
        "next_payment_due_date": "2024-06-01",
        "last_payment_date": "2024-05-01",
        "delinquency_first_start_date": null,
        "narrative_codes": [
          { "code": "FE", "description": "CREDIT CARD" }
        ]
      }
    ]
  }'
```

<Note>
  Manual Connect requires the full bureau tradeline schema (creditor codes, payment history, delinquency dates, narrative codes, etc.) — it is not a lightweight "user enters a missing account" flow. If you need that pattern, talk to your CSM about the right approach for your use case.
</Note>

### Enable Connect subscriptions for ongoing discovery

New liabilities that appear on future credit reports will be automatically discovered. See [Connect Subscriptions](/guides/connect/subscriptions).

### Handle zero results gracefully

If Connect returns zero accounts (thin credit file), don't show an empty state. Explain that the credit report didn't contain tradelines and offer Manual Connect as the path forward.

### Account-level product gaps

Even when an account is discovered, it may not support all products. Always check the `products` array before making assumptions:

```javascript theme={null}
const account = await method.accounts.retrieve('acc_eKKmrXDpJBKgw');

if (account.products.includes('payment')) {
  // Safe to initiate payments
} else {
  // Data-only — can retrieve balances but can't send money
}
```

For the full Connect API, see the [Connect reference](/reference/entities/connect/overview).


# Raw Credit Reports
Source: https://docs.methodfi.com/guides/connect/raw-credit-reports

Receive the raw bureau credit report behind a Connect as downloadable files.

Connect discovers liabilities using the user's credit report. Teams with raw credit report access enabled can also receive that underlying bureau report itself, as a downloadable raw credit report JSON and/or credit report PDF returned as [Files](/reference/files/overview). Files give you a durable copy of the report (e.g. for compliance archives or underwriting reviews) that can be re-downloaded at any time.

## Prerequisites

* Raw credit report features are enabled on a case-by-case basis. Contact Method to enable these.
* The Entity must be verified and must not have [withdrawn consent](/reference/entities/consent/withdraw).

## Requesting the raw report

<Steps>
  <Step title="Create a Connect with artifacts">
    Pass `bureau` and `artifacts` when [creating a Connect](/reference/entities/connect/create):

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "bureau": "transunion",
        "artifacts": ["raw_credit_report", "credit_report_pdf"]
      }'
    ```

    | Field       | Type    | Notes                                                                                                                              |
    | ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
    | `bureau`    | enum    | `transunion` or `equifax`. Required whenever `artifacts` is set. Method will work with your team to set which bureaus are allowed. |
    | `artifacts` | enum\[] | Any of `raw_credit_report`, `credit_report_pdf`. Each becomes a downloadable File on the Connect.                                  |

    <Note>
      Each Connect pulls from a single bureau. To receive credit reports from both bureaus, you will need to make 2 separate Connect calls.
    </Note>
  </Step>

  <Step title="Read the response">
    The Connect response includes the requested artifacts in `files`:

    ```json theme={null}
    {
      "id": "cxn_4ewMmBbjYDMR4",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "completed",
      "accounts": ["acc_eKKmrXDpJBKgw", "acc_GV8WbmJW7KGRy"],
      "requested_products": [],
      "requested_subscriptions": [],
      "files": [
        {
          "id": "file_jZWkPMhXPeYAn",
          "type": "raw_credit_report",
          "bureau": "transunion",
          "mime_type": "application/json"
        },
        {
          "id": "file_qTnUv7DdKcRW2",
          "type": "credit_report_pdf",
          "bureau": "transunion",
          "mime_type": "application/pdf"
        }
      ],
      "error": null,
      "created_at": "2026-07-06T18:00:00.000Z",
      "updated_at": "2026-07-06T18:00:12.000Z"
    }
    ```
  </Step>

  <Step title="Download the file artifacts">
    Note the `file_id`s in the above response and use [Retrieve a File](/reference/files/retrieve) to get the File's metadata, including a temporary `download_url` to its contents:

    ```bash theme={null}
    curl https://production.methodfi.com/files/file_jZWkPMhXPeYAn \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    Fetch the `download_url`. A new URL is generated on every retrieve and expires at `download_expires_at`.

    Additionally, you can stream a File's contents directly with [Download a File](/reference/files/download):

    ```bash theme={null}
    curl https://production.methodfi.com/files/file_jZWkPMhXPeYAn/download \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -o raw_credit_report.json
    ```
  </Step>
</Steps>

## Retrieving the raw report later

Files persist after the Connect completes. [Retrieve the Connect](/reference/entities/connect/retrieve) at any time to read its `files` array, then download the contents via the [Files API](/reference/files/overview).

## Webhooks

Connects with products or subscriptions (or the `Prefer: respond-async` header) process asynchronously. Listen for `connect.available` to know when an async Connect (including its artifacts) is ready, and `connect.create` for synchronous completions. See [Connect webhooks](/guides/connect/subscriptions).

## Errors

| `sub_type`                              | Cause                                                         |
| --------------------------------------- | ------------------------------------------------------------- |
| `CONNECT_BUREAU_REQUIRED_FOR_ARTIFACTS` | `artifacts` sent without `bureau`                             |
| `CONNECT_BUREAU_NOT_CONFIGURED`         | No bureaus have been configured for your team                 |
| `CONNECT_BUREAU_NOT_ENABLED`            | The requested bureau is not in your team's allowed bureaus    |
| `CONNECT_RAW_REPORT_NOT_ENABLED`        | The `raw_credit_report` artifact is not enabled for your team |
| `CONNECT_CREDIT_REPORT_PDF_NOT_ENABLED` | The `credit_report_pdf` artifact is not enabled for your team |

See [Connect errors](/reference/errors/connect-errors) and [File errors](/reference/errors/file-errors) for the full list.

<Note>
  **Handling sensitive data.** The raw credit report contains the consumer's full bureau file. Treat it as highly sensitive: store it encrypted, restrict access, and only retain it as long as your compliance obligations require.
</Note>

For the full API surface, see the [Connect reference](/reference/entities/connect/overview) and the [Files reference](/reference/files/overview).


# Connect Subscriptions
Source: https://docs.methodfi.com/guides/connect/subscriptions

Monitoring for new liabilities over time.

## Connect Subscriptions — Monitoring for New Liabilities

A user's liability profile isn't static. They open new credit cards, take out new loans, and accumulate new obligations over time. Connect Subscriptions monitor for these changes by periodically checking the Entity's credit report for new liabilities.

When a new account is discovered, Method creates it and notifies you via webhook. This enables your product to surface new debts automatically, keep the user's liability picture complete without requiring them to re-run discovery, and trigger workflows when new accounts appear (e.g., automatically requesting updates for newly discovered accounts).

The typical pattern is to enable a Connect subscription after the initial Connect completes, creating a continuous discovery pipeline that keeps your application's view of the user's liabilities current over time.

## Creating a Connect Subscription

Use the [Entity Subscriptions endpoint](/reference/entities/subscriptions/create) to enroll an Entity in ongoing Connect monitoring:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{ "enroll": "connect" }'
```

<Note>
  The Connect endpoint's `subscriptions` body parameter is for *account-level* subscriptions (`update`, `card_brand`, etc.) that apply to discovered accounts. To subscribe to ongoing *discovery* of new liabilities, use the Entity Subscriptions endpoint with `"enroll": "connect"` as shown above.
</Note>

<Tip>
  **Subscription frequency.** Connect subscriptions periodically perform soft-pull credit checks to detect new tradelines.
</Tip>

## Webhooks

Connect fires the following webhook events:

* `connect.create`: Connect request was created
* `connect.update`: Connect status changed (use this to detect completion)
* `connect.available`: New accounts are available (fired by Connect subscriptions when new liabilities are detected)

```json theme={null}
{
  "id": "cxn_4ewMmBbjYDMR4",
  "type": "connect.update",
  "path": "/entities/ent_au22b1fbFJbp8/connect/cxn_4ewMmBbjYDMR4"
}
```

Set up webhooks via the [Webhooks API](/reference/webhooks/overview) to receive real-time notifications.

## Receiving New Account Notifications

When a Connect subscription discovers new liabilities, Method fires a `connect.available` webhook:

```json theme={null}
{
  "id": "cxn_new123",
  "type": "connect.available",
  "path": "/entities/ent_au22b1fbFJbp8/connect/cxn_new123"
}
```

Retrieve the Connect object to see the newly discovered Account IDs. Only new accounts are included — previously discovered accounts are not repeated.

## Managing Subscriptions

To unsubscribe from Connect monitoring:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/subscriptions/sub_abc123 \
  -X DELETE \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

See [Entity Subscriptions](/reference/entities/subscriptions/overview) for the full subscription management API.

## When to Use Connect Subscriptions

<Tip>
  **When to use Connect subscriptions:**

  * Debt management / financial wellness apps where the user's liability picture must stay current
  * Portfolio monitoring where new liabilities impact risk assessment
  * Lending products that need to detect new debts after origination

  **When you may not need them:**

  * One-time Connect for a loan application (discovery is a point-in-time event)
</Tip>


# Testing Connect
Source: https://docs.methodfi.com/guides/connect/testing

How to test Connect in development.

## Testing Connect in Development

Use the simulation endpoint to queue Connect behaviors in your development environment:

```bash theme={null}
curl https://dev.methodfi.com/simulate/entities/{entity_id}/connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "behaviors": ["new_credit_card_account", "new_auto_loan_account"] }'
```

Each behavior is consumed the next time Connect runs for that Entity. Maximum 5 behaviors per Entity.

**Available behaviors:** `new_credit_card_account`, `new_auto_loan_account`, `new_mortgage_account`, `new_student_loan_account`, `new_personal_loan_account`.

<Note>
  **Simulation limitations.** Simulated accounts won't have real institution data. Use them to test your integration flow (webhooks, UI rendering, product execution), not data accuracy.
</Note>

For the full simulation API, see the [Simulate Connect reference](/reference/simulations/connect/create).


# Entity Errors — What Can Go Wrong and How to Handle It
Source: https://docs.methodfi.com/guides/entities/errors

What can go wrong during Entity creation and how to handle it.

## Entity Errors and Edge Cases

The most common issues during Entity creation stem from missing or incorrectly formatted user information. Understanding these helps you design an onboarding flow that minimizes friction and handles errors gracefully.

* **Missing required fields**: Entity creation requires certain identifying information (at minimum, a name and phone number for individuals). If required fields are omitted, the creation will fail. In your user experience, this typically means your onboarding form should collect all necessary fields upfront and validate completeness before submission. If you're collecting information across multiple screens, ensure the full set is available when you create the Entity.
* **Invalid formats**: PII fields must meet specific format requirements, phone numbers must be valid US numbers, dates of birth must be real dates, and so on. Customer-side validation catches most of these issues before they reach Method's API. Design your input fields with appropriate format masks, validation rules, and helpful error messages so users can correct issues immediately rather than encountering failures downstream.

### Immutable PII Fields

Once a PII field has been set to a non-null value on an Entity (name, phone, DOB, SSN), it **cannot be changed**. If a user enters incorrect information and it gets submitted to Method, you cannot correct it via the API.

**How to handle it:**

* For fields that are still `null`, you can update them at any time via the [Update endpoint](/reference/entities/update-entity)
* For genuine corrections (e.g., legal name change), contact Method support
* You may need to create a new Entity for that user

### Operations on Disabled Entities

If an Entity transitions to `disabled` (via consent withdrawal or a compliance event), any attempt to initiate new operations — connecting accounts, creating payments, requesting products — will fail. Existing data remains readable.

**How to handle it:** Check the Entity's `status` before initiating operations. If `disabled`, display a clear message and prevent actions that would fail. See [Entity Lifecycle](/guides/entities/lifecycle) for more on state transitions.

### Phone Number Formatting

Phone numbers must be in **E.164 format** (e.g., `+15121234567`). Common issues:

* Missing country code (`5121234567` instead of `+15121234567`)
* Including formatting characters (`(512) 123-4567` instead of `+15121234567`)
* Non-US numbers (Method currently supports US numbers only)

Validate and normalize phone numbers on your end before submitting to Method.

### Common Error Responses

When Entity creation or updates fail, Method returns structured error responses. Here are the most common:

**Missing required field:**

```json theme={null}
{
  "error": {
    "type": "INVALID_REQUEST",
    "sub_type": "INVALID_REQUEST",
    "message": "Field \"individual\" is required. Verify your request and try again."
  }
}
```

**Invalid phone format:**

```json theme={null}
{
  "error": {
    "type": "INVALID_REQUEST",
    "sub_type": "INVALID_REQUEST",
    "message": "Field \"individual.phone\" is in an invalid format. Verify your request and try again."
  }
}
```

**Attempting to update an immutable field:**

```json theme={null}
{
  "error": {
    "type": "INVALID_REQUEST",
    "sub_type": "ENTITY_UPDATE_INVALID",
    "message": "Updates are only allowed on fields that have not been set. Verify your request and try again."
  }
}
```

For the complete list of Entity error codes, see [Entity Errors](/reference/errors/entity-errors) in the API Reference.

### When Issues Persist

If Entity creation consistently fails, first check the `error` field on the API response — it contains structured details about what went wrong. Most issues can be resolved by fixing input data and retrying.

If the error is unclear or you believe it's incorrect, contact Method support with:

* The Entity ID (`ent_...`) if one was created
* The full error response
* The request payload that triggered the error

<Note>
  Entity errors should be handled as a normal part of your onboarding flow,
  not as exceptional failures. Validate input early, provide clear error
  messaging, and allow users to correct and retry without starting over.
  For engineering teams: see the full error codes and response formats in the
  <a href="/reference/errors/entity-errors">Entity Errors reference</a>.
</Note>

<CardGroup>
  <Card title="Identity Verification Guide" icon="shield-check" href="/guides/identity-verification/overview">
    Next: verify your user's identity to unlock products.
  </Card>

  <Card title="Entity Errors Reference" icon="code" href="/reference/errors/entity-errors">
    Full list of error codes, types, and sub-types.
  </Card>
</CardGroup>


# Entity Lifecycle — From Creation to Active Use
Source: https://docs.methodfi.com/guides/entities/lifecycle

From creation to active use — understanding Entity states and transitions.

## Entity Lifecycle — From Creation to Active Use

### Lifecycle States

Every Entity in Method exists in one of three states, and understanding these states helps you design the right user experience at each stage of your onboarding flow:

* **Incomplete:** The Entity has been created in Method, but the user hasn't completed all required steps to unlock the platform's capabilities. This is the starting state for every new Entity. In practical terms, your application knows who this person is, but Method hasn't yet verified their identity or connected their accounts. Most products are unavailable in this state. Your application should guide the user through the remaining setup steps (typically identity verification) and clearly indicate that setup isn't finished.
* **Active:** The Entity is fully set up and ready for use. Identity verification is complete, and the full range of eligible products is available. This is the steady state for most of your users. Your application can connect accounts, request updates, initiate payments, and enable monitoring. The user should experience the full value of your product.
* **Disabled:** The Entity has been deactivated and can no longer be used for new operations. This may happen because your team withdrew consent via the [Consent endpoint](/reference/entities/consent/withdraw), because Method disabled the Entity for compliance reasons, or because the user requested account closure through your application.
  No new operations can be initiated, but existing data, accounts, payment history, updates — remains accessible for reference and reporting.

### Common Lifecycle Transitions

**incomplete → active**
Triggered when the Entity completes all verification requirements configured for your team. For most teams, this means both phone and identity verification. The transition happens automatically — once the final verification session succeeds, the Entity's status updates and products become available.

**active → disabled**
Can be triggered by:

* Your team withdrawing consent via the [Consent endpoint](/reference/entities/consent/withdraw)
* A compliance event (e.g., a payment reversal triggers a policy review)
* Method disabling the Entity for policy reasons

This transition is permanent — disabled Entities cannot be reactivated. To re-onboard the user, create a new Entity.

**What about abandoned onboarding?**
Entities that stay in `incomplete` (the user never finished verification) don't expire. Build a resume flow that picks up where the user left off rather than creating a new Entity on their next visit.

Entities must be `active` before they can be `disabled`. An `incomplete` Entity that's no longer needed can simply be left in place — it doesn't incur cost or require cleanup.

### Reacting to State Changes

Entity state changes trigger `entity.update` webhooks. Subscribe to these to react in real time — for example, unlocking features when an Entity transitions to `active`, or displaying a deactivation notice when it becomes `disabled`. See [Webhooks](/reference/webhooks/overview).

### Designing Around Lifecycle States

Your user experiences should reflect the Entity's state:

* For incomplete Entities, show a clear onboarding progress indicator. Let the user know what steps remain (e.g., "Verify your identity to see your accounts"). Avoid showing empty states that suggest the product is broken — the user is mid-setup, not experiencing an error.
* For active Entities, provide full access to your product's features. This is your core experience.
* For disabled Entities, display a clear, non-alarming message explaining that the account is no longer active. Allow the user to view historical data if appropriate, but prevent any actions that would fail (payment initiation, account connection, etc.)

<CardGroup>
  <Card title="Errors & Edge Cases" icon="triangle-exclamation" href="/guides/entities/errors">
    What can go wrong during Entity creation and how to handle it.
  </Card>

  <Card title="Entity API Reference" icon="code" href="/reference/entities/overview">
    See the full Entity object including status, verification, products, and subscriptions.
  </Card>
</CardGroup>


# Entities — The Foundation of Every Integration
Source: https://docs.methodfi.com/guides/entities/overview

What an Entity represents, why it matters, and how it maps to your users.

## Entities — The Foundation of Every Integration

### The Entity Model

An Entity is Method's representation of a person or business in your system — a persistent profile that anchors everything Method knows about your user. Their verified identity, discovered accounts, payment history, and active subscriptions all connect through a single Entity. Every operation your application performs through Method — identity verification, account discovery, payments, monitoring — flows through the user's Entity.

### Why the Entity Model Matters

* **Persistent verification:** Once verified, the Entity carries that status forward. You don't re-verify for every operation.
* **Single reference point:** All accounts, payments, and updates for a user are scoped to their Entity. This also enforces authorization boundaries — one Entity's operations can't affect another.
* **Lifecycle management:** The Entity's status tracks the user's journey from onboarding through active use to potential deactivation, enforcing appropriate constraints at each stage.

### Entity vs End User

Your application has users; Method has Entities. These map one-to-one. Each end user in your application corresponds to exactly one Entity in Method, and that relationship persists throughout the user's lifecycle. You'll typically store the Method Entity ID alongside your internal user ID so you can bridge between the two systems seamlessly.

<Warning>
  Method does not automatically deduplicate Entities. If your application
  creates two Entities for the same person, both will exist independently
  with separate accounts and data. Your application should enforce uniqueness
  (typically by phone number) before creating new Entities.
</Warning>

### Individual vs Corporation Entities

Method supports two types of Entities, corresponding to the two types of financial actors:

<Tabs>
  <Tab title="Individual">
    Individual Entities represent people. To create one, you provide identifying information,  typically at minimum a name and phone number, with additional fields (date of birth, address, SSN) required for identity verification and access to downstream products. Individual Entities are by far the most common type and support the full range of Method's products.

    ```bash theme={null}
    curl https://production.methodfi.com/entities \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "individual",
        "individual": {
          "first_name": "John",
          "last_name": "Doe",
          "phone": "+15121234567"
        }
      }'
    ```
  </Tab>

  <Tab title="Corporation">
    Corporation Entity represents any business, regardless of its legal structure. Corporation Entities go through a business-specific verification process (KYB) and have their own product eligibility path.

    Corporation Entities support a different subset of capabilities than Individuals. They are primarily used for payment origination scenarios and do not have the same product catalog (no credit scores, Connect, or individual-specific features). If your use case involves both consumers and businesses, your architecture will need to account for this difference.

    ```bash theme={null}
    curl https://production.methodfi.com/entities \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "corporation",
        "corporation": {
          "name": "Acme Inc.",
          "ein": "123456789"
        }
      }'
    ```
  </Tab>
</Tabs>

### What Information Do You Need to Collect?

At minimum, most teams need a user's **name and phone number** to create an Individual Entity. However, additional PII (date of birth, SSN or last 4 of SSN, email, address) is typically required to complete identity verification and unlock products like Connect and Credit Score.

Your specific PII requirements are configured during onboarding. A common pattern is to create the Entity early with minimal information, then progressively update it as you collect more data during your onboarding flow. Contact your Method CSM if you're unsure about your team's requirements.

<CardGroup>
  <Card title="Entity Lifecycle" icon="arrows-spin" href="/guides/entities/lifecycle">
    Understand Entity states and how users transition from onboarding to active use.
  </Card>

  <Card title="Errors & Edge Cases" icon="triangle-exclamation" href="/guides/entities/errors">
    What can go wrong during Entity creation and how to design around it.
  </Card>

  <Card title="Identity Verification" icon="shield-check" href="/guides/identity-verification/overview">
    The next step after Entity creation — verifying your user's identity.
  </Card>

  <Card title="Entity API Reference" icon="code" href="/reference/entities/overview">
    Full Entity object schema, CRUD endpoints, and field details.
  </Card>
</CardGroup>


# IDV Errors & Edge Cases
Source: https://docs.methodfi.com/guides/identity-verification/errors

Common verification errors, failure modes, and how to handle edge cases.

## IDV Errors & Edge Cases

### Phone Verification Failures

| Error                                                    | Cause                                                             | Resolution                                                                                                                           |
| -------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `VERIFICATION_SESSION_EXPIRED` (19001)                   | Session not completed within the 10-minute window                 | Create a new verification session. Consider adding a timer or progress indicator to your UX.                                         |
| `VERIFICATION_SESSION_FAILED_INCORRECT_SMS_CODE` (19002) | User entered the wrong SMS code                                   | Create a new verification session. Confirm the user is entering the code from the most recent SMS.                                   |
| `VERIFICATION_SESSION_FAILED_SNA` (19003)                | User not on a mobile device, or on an unsupported carrier/network | Fall back to SMS verification. SNA access attempts are limited to 5 per session.                                                     |
| `ENTITY_PHONE_VERIFICATION_MAX_ATTEMPTS`                 | Too many verification attempts for this Entity's phone number     | The underlying SMS provider has rate-limited this phone number. Wait before retrying, and surface appropriate messaging to the user. |

### Identity Verification Failures

| Error                                                | Cause                                                                                           | Resolution                                                                                                                                                                               |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MISSING_IDENTITY_MATCH`                             | Method couldn't correlate the Entity's PII to a known identity — insufficient or incorrect PII  | [Update the Entity](/reference/entities/update-entity) with additional fields (DOB, SSN, address) and retry. See [Maximizing Success](/guides/identity-verification/maximizing-success). |
| `VERIFICATION_SESSION_FAILED_INVALID_ANSWER` (19004) | User answered one or more KBA questions incorrectly, or a question was missing from the request | Create a new verification session — a fresh set of questions will be generated. Confirm the user is answering carefully.                                                                 |
| `VERIFICATION_SESSION_EXPIRED` (19001)               | Session not completed within the 10-minute window                                               | Create a new verification session.                                                                                                                                                       |

### Request Errors

| Error                              | Cause                                                                                        | Resolution                                                                        |
| ---------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `MISSING_PHONE_VERIFICATION`       | Attempted to create an identity verification session before phone verification was completed | Complete phone verification first, then create the identity verification session. |
| `EXISTING_VERIFIED_SESSION`        | The Entity has already completed verification for that type (phone or identity)              | No action needed — the Entity is already verified for that step.                  |
| `INVALID_ENTITY_TYPE`              | Attempted to create a verification session on a corporation Entity                           | Verification sessions are only available for Entities of type `individual`.       |
| `UNAUTHORIZED_VERIFICATION_METHOD` | The team is not authorized to use the requested verification method                          | Contact your Method CSM to enable the method (e.g., `byo_sms`, `byo_kyc`).        |

### Edge Cases

<Accordion title="User needs a different phone number mid-flow">
  An Entity's phone number cannot be changed once it has been set. If the user entered the wrong phone number, you'll need to create a new Entity with the correct phone number and start the verification process from the beginning.
</Accordion>

<Accordion title="Same phone number across multiple Entities">
  Multiple Entities can share the same phone number, but each Entity must complete its own verification independently.
</Accordion>

<Accordion title="Re-verification after Entity was previously verified">
  Attempting to create a verification session for an already-verified type will return `EXISTING_VERIFIED_SESSION`. Verification is persistent and does not need to be repeated.
</Accordion>

<Accordion title="Attempting verification on a disabled Entity">
  Verification sessions cannot be created for Entities that have been disabled. Ensure the Entity is in an active state before initiating verification.
</Accordion>

<Accordion title="Corporation Entity">
  Verification sessions are only available for individual Entities. Attempting to create a session on a corporation Entity will return `INVALID_ENTITY_TYPE`.
</Accordion>

### Error Code Reference

For the full list of error codes with response bodies, see the [Entity Verification Session Errors](/reference/errors/entity-verification-session-errors) reference.


# Maximizing Verification Success
Source: https://docs.methodfi.com/guides/identity-verification/maximizing-success

How to improve match rates and verification success through better data collection.

## Maximizing Verification Success

Not all PII fields are required for every verification method, but providing more data significantly improves match rates and verification success. At minimum, you need a name and phone number, but including date of birth, address, and SSN (last 4 or full) dramatically increases the likelihood of a successful match. Design your onboarding flow to collect as much PII as practical without creating excessive friction.

| Field                | Impact   | Why it matters                                            |
| -------------------- | -------- | --------------------------------------------------------- |
| First + Last name    | Required | Baseline identity anchor                                  |
| Phone number         | Required | Links to carrier records and Method's network             |
| Date of birth        | High     | Disambiguates common names, strong identity signal        |
| Address              | High     | Confirms geographic identity, helps with thin files       |
| Email                | Moderate | Secondary signal, helps when primary fields are ambiguous |
| SSN (last 4 or full) | Highest  | Strongest single identity signal, near-guaranteed match   |

### Common Pitfalls

* **Phone number without country code** — Method only accepts US phone numbers at this time, and they must include the `+1` country code (e.g., `+15551234567`)
* **Abbreviated names vs. legal names** — use the name on their credit file, not nicknames (e.g., "William" not "Bill")
* **PO Box instead of physical address** — physical addresses match better against identity records
* **Stale or outdated address** — use the user's current address, not a previous one

<Note>
  For platform availability details, see the [IDV Overview](/guides/identity-verification/overview).
</Note>

<CardGroup>
  <Card title="Verification Outcomes" icon="circle-check" href="/guides/identity-verification/outcomes">
    When data collection is maximized but matching still fails.
  </Card>

  <Card title="Verification Sessions API" icon="code" href="/reference/entities/verification-sessions/overview">
    Full API reference for verification session endpoints.
  </Card>
</CardGroup>


# Verification Methods
Source: https://docs.methodfi.com/guides/identity-verification/methods

Choosing the right phone and identity verification approach for your integration.

## Verification Methods

<Warning>
  All verification sessions expire **10 minutes** after creation. If the user doesn't complete verification within that window, you'll need to create a new session. Design your UX to guide users through verification promptly and handle the expired session error gracefully. See [Errors & Edge Cases](/guides/identity-verification/errors) for details.
</Warning>

Phone verification must be completed before identity verification can begin. Choose one method from each step below. Most teams use the same approach (Opal, API-driven, or BYO) for both steps, but you can mix — for example, SNA for phone and KBA for identity.

### Choosing Your Phone Verification Method

<Tabs>
  <Tab title="Opal (Recommended)">
    Phone verification is handled entirely within the Opal embedded UI. The user enters their phone number, receives a verification code, and enters it — all within a polished, pre-built interface. This is the fastest path to implementation and provides the most consistent user experience.
  </Tab>

  <Tab title="SMS Verification">
    Method sends a verification code to the user's phone, and your application collects and submits the code. Choose this if you want to integrate phone verification into your own custom UI while still having Method handle the SMS delivery.

    ```bash theme={null}
    # 1. Create SMS verification session
    curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "sms",
        "sms": {}
      }'

    # 2. Submit the code the user received
    curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "sms",
        "sms": {
          "sms_code": "123456"
        }
      }'
    ```
  </Tab>

  <Tab title="Silent Network Auth (SNA)">
    The phone is verified in the background using carrier-level network signals, with no user interaction required. This provides the best user experience (the user doesn't have to do anything), but availability depends on the user's carrier and network conditions. Consider SNA as a primary method with SMS as a fallback.

    <Warning>
      SNA requires the user to be on a mobile device connected to a supported carrier's network. It does not work on landlines, VoIP numbers, or most prepaid/MVNO carriers. The returned URLs must be opened via background request or the device's mobile browser. Always implement SMS as a fallback — SNA failures may be silent and your application needs to detect them (via session status polling or webhook) and offer an alternative. SNA access attempts are limited to 5 per session before the session fails.
    </Warning>
  </Tab>

  <Tab title="BYO SMS">
    You handle SMS delivery and verification entirely on your side and report the result to Method. Choose this if you already have a robust SMS verification system and want to maintain a single verification flow across your application.

    <Note>
      BYO SMS requires your team to be pre-authorized during onboarding. You'll create a verification session with method `byo_sms` and provide the `byo_sms.timestamp` field — the ISO 8601 timestamp of when you verified the phone number. Contact your Method CSM to enable this method.
    </Note>

    ```bash theme={null}
    curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "byo_sms",
        "byo_sms": {
          "timestamp": "2026-04-10T12:00:00.000Z"
        }
      }'
    ```
  </Tab>
</Tabs>

#### Choosing a Phone Method

| Method      | User Experience            | Implementation                | Reliability                  | Best For                                 |
| ----------- | -------------------------- | ----------------------------- | ---------------------------- | ---------------------------------------- |
| **Opal**    | Polished, pre-built        | Minimal (embed SDK)           | High                         | Most teams                               |
| **SMS**     | Standard (enter code)      | Medium (collect + submit)     | High                         | Custom UI with Method SMS delivery       |
| **SNA**     | Invisible (no user action) | Medium (background URL calls) | Variable (carrier-dependent) | Mobile-first products, with SMS fallback |
| **BYO SMS** | Your existing flow         | Low (report result)           | Depends on your provider     | Teams with existing SMS verification     |

**Recommended pattern:** Use SNA as primary with SMS as automatic fallback. This gives the best conversion rate while ensuring every user can complete verification.

<Note>
  Phone verification has a maximum attempt limit enforced by the underlying SMS provider. If the limit is reached, the error `ENTITY_PHONE_VERIFICATION_MAX_ATTEMPTS` is returned and you'll need to wait before retrying. Design your flow to inform users of the limit and avoid excessive retries.
</Note>

### Choosing Your Identity Verification Method

<Tabs>
  <Tab title="Opal (Recommended)">
    Identity verification is handled within the Opal embedded UI. The user is guided through the KYC process in a managed, tested flow. This is the simplest path and ensures the verification experience is optimized for completion.
  </Tab>

  <Tab title="KBA">
    The user answers a set of identity questions generated from their credit and public record history (e.g., "Which of these addresses have you lived at?"). Your application presents the questions and collects answers. KBA is widely supported but can be frustrating for users if questions are obscure or ambiguous.

    ```bash theme={null}
    # 1. Create KBA verification session (returns questions)
    curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "identity",
        "method": "kba",
        "kba": {}
      }'

    # 2. Submit answers to the questions
    curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "identity",
        "method": "kba",
        "kba": {
          "answers": [
            { "question_id": "qtn_xxx", "answer_id": "ans_xxx" },
            { "question_id": "qtn_yyy", "answer_id": "ans_yyy" }
          ]
        }
      }'
    ```
  </Tab>

  <Tab title="BYO KYC">
    You perform identity verification on your side using your own KYC provider and report the outcome to Method. Choose this if you already have a KYC integration and want to consolidate verification into a single flow, or if you need to meet specific compliance requirements that require a particular KYC vendor.

    <Note>
      BYO KYC requires your team to be pre-authorized during onboarding. By creating this session, you're asserting that your external KYC process has passed for this user. Method trusts your KYC result — there are no constraints on which KYC vendor you use. Contact your Method CSM to enable this method.
    </Note>

    ```bash theme={null}
    curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_xxx" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "identity",
        "method": "byo_kyc",
        "byo_kyc": {}
      }'
    ```

    The response will include `byo_kyc: { authenticated: true }` confirming the verification was recorded.
  </Tab>
</Tabs>

#### Choosing an Identity Method

| Method      | User Experience     | Implementation                              | Best For                                   |
| ----------- | ------------------- | ------------------------------------------- | ------------------------------------------ |
| **Opal**    | Guided, pre-built   | Minimal                                     | Most teams                                 |
| **KBA**     | Multi-question quiz | Medium (present questions, collect answers) | API-only integrations without existing KYC |
| **BYO KYC** | Your existing flow  | Low (report result)                         | Teams with existing KYC provider           |

<Note>
  **About `element` and `method_verified` methods:** The API also lists `element` and `method_verified` as valid verification methods. `element` is the predecessor to Opal — new integrations should use Opal instead. `method_verified` is an internal method used by Method and is not available for external use.
</Note>


# Verification Outcomes
Source: https://docs.methodfi.com/guides/identity-verification/outcomes

Understanding the difference between Matched and Verified states.

## Verification Outcomes

### Understanding Verification Outcomes: Matched vs. Verified

Method distinguishes between two verification states, and understanding the difference matters:

| State                        | Meaning                                                        | Unlocks products? |
| ---------------------------- | -------------------------------------------------------------- | ----------------- |
| Neither matched nor verified | Entity created, not yet verified                               | No                |
| Matched only                 | Method identified the person, but they haven't proven identity | No                |
| Matched + Verified           | Full identity confirmation complete                            | Yes               |

An Entity cannot reach Verified status without first being Matched. If matching fails, verification cannot proceed.

In practical terms: matched means "we know who you are," and verified means "you've proven you're that person." Both are required.

### How Matching Works

When you create or update an Entity with PII (name, DOB, SSN, address, phone), Method attempts to correlate that information against its identity records. If the PII matches a known identity, the Entity becomes `matched`. This happens automatically when the Entity's PII is processed — you don't call a separate endpoint for matching.

The Entity's `matched` status is then checked when you create an identity verification session. If the Entity is not yet matched, the session creation will fail with `MISSING_IDENTITY_MATCH`.

Matching can fail if:

* The PII is incomplete (name + phone only, no DOB or SSN)
* The PII has typos or formatting issues
* The person has a thin file (limited credit/identity history)

See [Maximizing Verification Success](/guides/identity-verification/maximizing-success) for how to improve match rates.

### When Matching Fails

If Method cannot match the Entity's PII to a known identity, creating an identity verification session will return a `MISSING_IDENTITY_MATCH` error. Your options:

1. **Collect more PII:** Update the Entity with additional fields (DOB, SSN, address) and retry. More PII dramatically improves match rates.
2. **Verify the data:** Check for typos, name variations (maiden names, Jr/Sr suffixes), or incorrect phone numbers.

<Warning>
  Match failures are not the same as verification failures. A match failure means Method couldn't identify the person at all. A verification failure (KBA wrong answers, SMS wrong code) means the person was identified but couldn't prove they're that person.

  You will need to create a new Entity if a user fails identity verification (e.g., incorrect KBA answers). The failed Entity cannot be reused for identity verification.
</Warning>

### Checking Verification Status

The Entity object includes a `verification` field that reflects the current state:

```json theme={null}
"verification": {
  "identity": {
    "verified": true,
    "matched": true,
    "latest_verification_session": "evf_xxx",
    "methods": []
  },
  "phone": {
    "verified": true,
    "latest_verification_session": "evf_yyy",
    "methods": []
  }
}
```

When verification is incomplete, the `methods` arrays will contain the available verification methods for that step (e.g., `["sms", "sna"]` for phone, `["kba"]` for identity). Once a step is completed, its `methods` array becomes empty.

Use these fields to determine what actions are available for the Entity. See the [Entity API Reference](/reference/entities/overview) for full field documentation.

<CardGroup>
  <Card title="Maximizing Success" icon="chart-line" href="/guides/identity-verification/maximizing-success">
    Improve match rates through better data collection.
  </Card>

  <Card title="Verification Sessions API" icon="code" href="/reference/entities/verification-sessions/overview">
    Full API reference for verification session endpoints.
  </Card>
</CardGroup>


# Identity Verification (IDV)
Source: https://docs.methodfi.com/guides/identity-verification/overview

Why identity verification matters and how the two-step process works.

<Frame>
  <img alt="Identity Verification" />
</Frame>

## Proving Your Users Are Who They Claim to Be

<Warning>
  Method currently supports identity verification for US-based individuals only. Users without a US credit history or US phone number cannot complete verification.
</Warning>

### Why IDV Matters

Identity verification is the gateway to Method's platform. Before Method will discover a user's accounts, retrieve their credit data, or process payments on their behalf, the user must prove they are who they claim to be. It's a fundamental fraud prevention and compliance requirement that protects both your users and your platform.

For your product, IDV is typically the first meaningful interaction a user has after signing up. The verification experience directly impacts your onboarding conversion rate: a smooth, fast verification flow keeps users engaged, while a clunky or confusing one creates drop-off. Choosing the right verification approach is one of the most impactful product decisions you'll make in your Method integration.

IDV gates access to every downstream product: [Connect](/guides/connect/overview) (account discovery), [Updates](/guides/updates/overview) (fresh balances), [Payments](/guides/payments/overview), [Credit Scores](/guides/additional-products/credit-scores), [Attributes](/guides/additional-products/attributes), and more. An Entity that hasn't completed IDV stays in `incomplete` status with no product access. For most integrations, IDV is the single highest-impact step to optimize — every percentage point of verification conversion translates directly to users who can access your product's core features.

<Info>
  **Using Opal?** If you're using Method's embedded UI, Opal handles both phone verification and identity verification in a single, managed flow. You don't need to build verification screens or manage session state — Opal orchestrates the entire process. The rest of this section is relevant if you're building a custom integration or want to understand what Opal is doing under the hood. See the [Opal guide](/opal/identity/overview) for details.
</Info>

### The Two-Step Process

IDV consists of two sequential steps, each serving a distinct purpose:

<Steps>
  <Step title="Phone Verification">
    Confirms that the user controls the phone number associated with their identity. This is the "something you have" factor — it proves the person filling out your form actually possesses the phone number they provided.

    <Warning>
      Phone verification must be completed before identity verification can begin. Attempting to create an identity verification session for an Entity without phone verification will fail with `MISSING_PHONE_VERIFICATION`.
    </Warning>
  </Step>

  <Step title="Identity Verification">
    Confirms that the user's provided information matches a real person's identity through a KYC (Know Your Customer) process — it proves they are who they claim to be, not just someone who has access to a phone number.
  </Step>
</Steps>

Both steps must be completed for an Entity to be fully verified and gain access to downstream products.

### What Happens After Verification

Once both steps are complete, the Entity's status updates to `active` and the Entity becomes both `matched` and `verified`, unlocking downstream products: [Connect](/guides/connect/overview) (account discovery), [Credit Scores](/guides/additional-products/credit-scores), [Payments](/guides/payments/overview), and more. The verification is persistent — you don't need to re-verify for subsequent operations. See [Entity Lifecycle](/guides/entities/lifecycle) for how verification status affects what you can do.

<CardGroup>
  <Card title="Verification Methods" icon="list-check" href="/guides/identity-verification/methods">
    Choose the right phone and identity verification approach.
  </Card>

  <Card title="Verification Outcomes" icon="circle-check" href="/guides/identity-verification/outcomes">
    Understand the difference between Matched and Verified.
  </Card>

  <Card title="Maximizing Success" icon="chart-line" href="/guides/identity-verification/maximizing-success">
    Improve match rates through better data collection.
  </Card>

  <Card title="Verification Sessions API" icon="code" href="/reference/entities/verification-sessions/overview">
    Full API reference for verification session endpoints.
  </Card>
</CardGroup>


# The Verification Flow
Source: https://docs.methodfi.com/guides/identity-verification/verification-flow

Step-by-step verification sequence, state transitions, webhooks, and code walkthroughs.

## The Verification Flow

### Step-by-Step Sequence

<Steps>
  <Step title="Create Entity with PII">
    Create an Entity with at minimum a name and phone number. If you're using the API-driven flow (not Opal), providing more PII (DOB, SSN, address) significantly improves match rates. Opal collects PII directly from the user during its flow, so upfront PII is less critical when using Opal. See [Maximizing Success](/guides/identity-verification/maximizing-success).
  </Step>

  <Step title="Check available verification methods">
    Inspect `entity.verification.phone.methods` and `entity.verification.identity.methods` to see which verification methods are available for this Entity.
  </Step>

  <Step title="Create phone verification session">
    Choose a phone verification method (SMS, SNA, or BYO SMS) and create a verification session.
  </Step>

  <Step title="Complete phone verification">
    Complete the phone verification using the method-specific flow (submit SMS code, process SNA URLs, or report BYO result).
  </Step>

  <Step title="Create identity verification session">
    Once phone is verified, create an identity verification session (KBA or BYO KYC). This will fail with `MISSING_PHONE_VERIFICATION` if phone verification is not complete, or `MISSING_IDENTITY_MATCH` if Method couldn't match the Entity's PII.
  </Step>

  <Step title="Complete identity verification">
    Complete the identity verification using the method-specific flow (submit KBA answers or report BYO KYC result).
  </Step>

  <Step title="Entity is verified">
    Entity is now matched + verified. Proceed to [Connect](/guides/connect/overview), [Payments](/guides/payments/overview), or other products.
  </Step>
</Steps>

### State Diagram

```
[Entity created] → [Phone: unverified] → [Phone: verified] → [Identity: unverified] → [Identity: matched + verified] → [Products unlocked]
```

Each verification session goes through its own lifecycle:

```
pending → in_progress → verified (success)
                       → failed (expired, incorrect code/answer, SNA failure)
```

### Webhooks

Subscribe to verification session events to track progress:

* **`entity_verification_session.create`** — Fired when a new verification session is created.
* **`entity_verification_session.update`** — Fired when a session's status changes (e.g., `pending` → `verified`, `pending` → `failed`).

These events allow you to build reactive flows — for example, unlocking the next step of your onboarding when phone verification completes.

### Code Walkthroughs

#### SMS + KBA (most common API-driven path)

```bash theme={null}
# 1. Create an Entity
curl -X POST https://production.methodfi.com/entities \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "individual": {
      "first_name": "Jane",
      "last_name": "Doe",
      "phone": "+15551234567",
      "dob": "1990-01-15"
    }
  }'

# 2. Create SMS phone verification session
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sms",
    "sms": {}
  }'

# 3. User receives SMS code, submit it
curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sms",
    "sms": { "sms_code": "123456" }
  }'

# 4. Create KBA identity verification session (returns questions)
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity",
    "method": "kba",
    "kba": {}
  }'

# 5. Present questions to user, then submit answers
curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_yyy \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity",
    "method": "kba",
    "kba": {
      "answers": [
        { "question_id": "qtn_aaa", "answer_id": "ans_bbb" },
        { "question_id": "qtn_ccc", "answer_id": "ans_ddd" }
      ]
    }
  }'

# Entity is now verified — proceed to Connect or other products
```

#### SNA + KBA (best UX path)

```bash theme={null}
# 1. Create Entity (same as above)

# 2. Create SNA phone verification session
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sna",
    "sna": {}
  }'
# Response includes SNA URLs — open them via background request on the user's device

# 3. Update SNA session to check verification status
curl -X PUT https://production.methodfi.com/entities/ent_xxx/verification_sessions/evf_xxx \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "sna",
    "sna": {}
  }'
# If SNA fails, fall back to SMS (create a new session with method "sms")

# 4-5. Proceed with KBA identity verification (same as above)
```

#### BYO SMS + BYO KYC (existing infrastructure path)

```bash theme={null}
# 1. Create Entity (same as above)

# 2. Report BYO SMS phone verification
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "phone",
    "method": "byo_sms",
    "byo_sms": {
      "timestamp": "2026-04-10T12:00:00.000Z"
    }
  }'

# 3. Report BYO KYC identity verification
curl -X POST https://production.methodfi.com/entities/ent_xxx/verification_sessions \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "identity",
    "method": "byo_kyc",
    "byo_kyc": {}
  }'

# Entity is now verified
```


# Opal
Source: https://docs.methodfi.com/guides/opal

Method's embedded UI for identity verification, account discovery, and more.

## What Opal Is and Why It Matters

Opal is Method's embedded UI, a set of pre-built, white-labeled screens and flows that you drop into your application to handle the complex, multi-step processes of identity verification, account discovery, and more. Instead of designing, building, testing, and maintaining these flows yourself, you launch Opal and let it guide your users through the process in a polished, tested experience.

Opal represents a significant acceleration of your roadmap. Building identity verification and account linking flows from scratch typically takes weeks of engineering time, plus ongoing maintenance as edge cases, error states, and accessibility requirements emerge. Opal compresses this to days, your engineering team creates a session token, launches the component, and listens for completion events. Everything in between is handled by Method.

Opal is also designed for conversion. The flows are optimized for completion rates, with clear progress indicators, helpful error messaging, and the ability for users to resume interrupted sessions without starting over. When a user's phone dies mid-verification or they need to step away, their progress is saved.

## Opal Modes — What Your Users Experience

Opal operates in distinct modes, each handling a specific part of the user journey. You can launch these independently depending on where the user is in your flow:

<CardGroup>
  <Card title="Identity Verification" icon="shield-check" href="/opal/identity/overview">
    Guides the user through Method's two-step verification process. First, the user confirms their phone number (via SMS code, silent network auth, or other methods). Then, they complete identity verification through a KYC process. From the user's perspective, this feels like a simple onboarding step, enter some information, confirm a code, answer a few questions, and they're verified. Behind the scenes, Opal is orchestrating phone verification, identity matching, and KYC compliance.
  </Card>

  <Card title="Connect" icon="link" href="/opal/connect/overview">
    After verification, the user consents to a soft credit pull, and Opal displays the discovered liability accounts, credit cards, loans, mortgages, and more, in a clear, organized interface. The user can see what was found and proceed to the next step in your flow. This is often the "wow moment" in a debt management product: the user sees their complete liability picture for the first time, surfaced automatically without manual entry.
  </Card>

  <Card title="Card Connect" icon="credit-card" href="/opal/card_connect/overview">
    Handles the specific case where a user needs to verify and connect a particular card for payment flows. This is useful when your product needs to work with a specific card rather than discovering all liabilities.
  </Card>

  <Card title="Account Verification" icon="building-columns" href="/opal/account_verification/overview">
    Confirms ownership of a specific account. This is used when you need to verify that a user controls a particular financial account before enabling certain operations.
  </Card>
</CardGroup>

Each mode can be launched independently depending on where the user is in your flow.

## How Opal Integrates Into Your Flow

<Steps>
  <Step title="Request a session token">
    Your backend requests a session token from Method, scoped to a specific user (Entity) and a specific mode
  </Step>

  <Step title="Load the SDK">
    Your frontend application loads Opal using one of Method's client SDKs (available for web, React, and React Native)
  </Step>

  <Step title="User interacts with Opal">
    The user interacts with Opal directly, filling in information, confirming codes, reviewing discovered accounts
  </Step>

  <Step title="Receive webhook events">
    Your backend listens for webhook events that signal progress and completion, triggering whatever comes next in your application flow
  </Step>
</Steps>

Sessions are persistent, meaning users can leave and return without losing progress. This is particularly important for mobile users who may be interrupted by notifications, phone calls, or simply needing to come back later.

## Customization and Branding

Opal is designed to feel like a native part of your application, not a third-party widget. Customization options include:

* Brand colors and accent colors
* Typography and font choices
* Logo placement and branding elements
* Light/dark mode support

The goal is that your users never feel like they've been handed off to a different product. Refer to the [Opal documentation](/opal/overview) for the full range of theming options and accessibility compliance details.

## When to Consider API-Only

Opal covers the vast majority of integration scenarios, but there are cases where building directly against Method's APIs may be a better fit:

* Your product has an existing onboarding flow that users are already familiar with, and you need the verification steps to feel native to that flow's design language
* Your compliance or security requirements demand that PII collection happens entirely within your own infrastructure
* You need fine-grained control over the verification step ordering or conditional logic that Opal's session model doesn't support

If you're unsure, start with Opal. You can always migrate specific steps to API-only later without rebuilding everything.

<Warning>
  Elements was Method's previous embedded UI, deprecated on December 31, 2025. All new integrations should use Opal. If your team is still using Elements, plan your migration using the [Opal migration guide](/opal/migration_guide).
</Warning>

## What's Next

<CardGroup>
  <Card title="Opal Quickstart" icon="rocket" href="/opal/quickstart">
    Get Opal running in your application in minutes.
  </Card>

  <Card title="Opal Libraries" icon="book" href="/opal/libraries">
    SDK installation and setup for web, React, and React Native.
  </Card>

  <Card title="Opal Sessions" icon="key" href="/opal/sessions">
    Session management, token creation, and lifecycle.
  </Card>

  <Card title="Opal Events" icon="bell" href="/opal/events">
    Event handling and completion callbacks.
  </Card>

  <Card title="Opal API Reference" icon="code" href="/reference/opal/overview">
    Token creation, session management, and event types.
  </Card>
</CardGroup>


# What is Method
Source: https://docs.methodfi.com/guides/overview

Method is the infrastructure layer for consumer liability data and payments.

In a financial ecosystem where liability information is fragmented across thousands of institutions, reported inconsistently, and often weeks out of date, Method provides a single, unified platform that brings structure and reliability to this fragmented landscape.

<Note>
  These Guides cover concepts and product decisions. For implementation details and code, see the [API Reference](/reference/introduction).
</Note>

## How Method Works

Unlike aggregators that require users to share their bank login credentials, Method uses a fundamentally different approach. When a user verifies their identity, Method performs a soft credit pull (no impact to the user's credit score) to automatically discover all of their liabilities, without any manual account entry or credential sharing.

Once accounts are discovered, Method can retrieve real-time data directly from financial institutions for supported accounts, giving you current balances, due dates, interest rates, and payment amounts. For accounts where direct connections aren't available, Method falls back to credit report data as a reliable baseline.

This two-source model, credit report discovery paired with direct institutional access, means your product gets both breadth (visibility into virtually every liability) and depth (real-time data where it matters most).

## What Method Does

<CardGroup>
  <Card title="Discover and connect consumer liabilities at scale" icon="magnifying-glass">
    Method connects to 15,000+ financial institutions, from major banks to regional lenders. When a user links their identity, you gain visibility into their full liability picture — credit cards, auto loans, student loans, mortgages, personal loans, and more.
  </Card>

  <Card title="Keep liability data fresh and normalized" icon="arrows-rotate">
    Liability data arrives from institutions in inconsistent formats and update cycles. Method standardizes balances, due dates, interest rates, payment amounts, and limits into a clean, consistent data model accessible through a single API.
  </Card>

  <Card title="Move money to pay down debts" icon="money-bill-transfer">
    Method enables payments directly to connected liability accounts. Initiate paydowns from a verified funding source while Method handles submission, processing, delivery to the creditor, and confirmation.
  </Card>

  <Card title="Monitor changes over time for your users" icon="bell">
    Financial accounts constantly change — balances update, payments post, and accounts open or close. Method's subscription system keeps your application synced with these updates through near-real-time notifications.
  </Card>
</CardGroup>

## Who Method Is Built For

### Commerce

Commerce and card-linked platforms that need to connect to consumers' card accounts for transaction data, card-on-file verification, or payment instrument provisioning to power checkout, rewards, and card-linked offer experiences.

<CardGroup>
  <Card title="Wallet Onboarding" icon="wallet" href="/guides/use-cases/commerce/wallet-onboarding">
    Connect every credit card a customer owns in a single flow, then enrich and tokenize for checkout.
  </Card>

  <Card title="Preauth Signals" icon="signal" href="/guides/use-cases/commerce/preauth-signals">
    Evaluate payment readiness before authorization and retry failed payments at the optimal time.
  </Card>
</CardGroup>

### Lending

Lenders and underwriters that need verified, up-to-date liability data to make credit decisions, calculate debt-to-income ratios, verify existing obligations, and enable debt consolidation through structured plans, lump-sum payments, or automated recurring transfers.

<CardGroup>
  <Card title="Application & Qualification" icon="clipboard-check" href="/guides/use-cases/lending/application-prefill">
    Pre-fill loan applications with verified liability data and assess risk with credit health attributes.
  </Card>

  <Card title="Debt Consolidation" icon="money-bill-transfer" href="/guides/use-cases/lending/debt-consolidation">
    Discover eligible accounts, verify current balances, and disburse funds directly to creditors.
  </Card>

  <Card title="Portfolio Intelligence" icon="chart-line" href="/guides/use-cases/lending/portfolio-monitoring">
    Monitor borrower liability, utilization, and delinquency signals continuously after origination.
  </Card>
</CardGroup>

### Personal Finance & Financial Wellness

Personal finance and financial wellness applications that want to give users a comprehensive view of their liabilities alongside their assets, track progress over time, and provide actionable insights about credit health.

<CardGroup>
  <Card title="Onboarding & Discovery" icon="magnifying-glass" href="/guides/use-cases/pfm/onboarding-discovery">
    Identity verification options, liability discovery via Connect, and vehicle enrichment for auto loans.
  </Card>

  <Card title="Dashboard & Insights" icon="chart-mixed" href="/guides/use-cases/pfm/monitoring-insights">
    Build real-time debt dashboards with account updates, card brand art, credit scores, and financial health attributes.
  </Card>

  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Stream credit card transactions for spend management and initiate bill payments to your users' creditors.
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/guides/quickstart">
    Most integrations follow this four-step pattern, though the exact flow may vary depending on your product and use case.
  </Card>

  <Card title="Core Concepts" icon="diagram-project" href="/guides/concepts">
    Understand Method's object model and how everything connects.
  </Card>

  <Card title="Opal" icon="window" href="/guides/opal">
    Drop-in embedded UI that handles identity verification, account discovery, and more — get to value in days, not weeks.
  </Card>

  <Card title="API Reference" icon="code" href="/reference/introduction">
    Dive into the full API documentation.
  </Card>
</CardGroup>


# Payment Lifecycle
Source: https://docs.methodfi.com/guides/payments/lifecycle

What your users should see as payments move through the system.

## Payment Lifecycle — What Your Users Should See

Every payment moves through a defined lifecycle, and each stage should map to a clear user-facing status in your product:

| Method Status           | User-Facing Copy                        | Description                                                                 |
| ----------------------- | --------------------------------------- | --------------------------------------------------------------------------- |
| **Pending**             | "Payment scheduled" or "Payment queued" | The payment has been created and is waiting for the next processing window. |
| **Canceled**            | "Payment canceled"                      | The payment was canceled before it was processed.                           |
| **Processing**          | "Payment in progress"                   | The payment is actively being processed through the banking system.         |
| **Sent**                | "Payment sent to your creditor"         | Funds have been initiated and sent to the creditor.                         |
| **Posted**              | "Payment complete"                      | The creditor has confirmed the payment has been applied to the account.     |
| **Failed**              | "Payment couldn't be processed"         | An error occurred — see failure details.                                    |
| **Reversal Processing** | "Reversal in progress"                  | A reversal has been approved and is being processed.                        |
| **Reversed**            | "Payment returned"                      | A previously sent payment was returned.                                     |

Design your product to show clear status transitions as webhook events arrive. Users should feel confident that their money is moving and that the system is working, ambiguity about payment status is one of the fastest ways to erode trust.

### Handling Reversals and Failures

Payments can fail or be reversed, and your product should be able to handle these scenarios gracefully:

**Failed Payments**

Failed payments can occur at various stages due to insufficient funds in the funding account, invalid or closed account details, or creditor rejection. When a payment fails, Method emits a webhook event with the failure details. Your product should notify the user clearly, explain what happened in plain language, and provide a path to retry if applicable.

**Reversed Payments**

Reversals occur when a payment that was already sent is returned, for example, if the funding account has insufficient funds after the payment was initiated, or if the creditor returns the payment for any reason. Reversals are tracked as separate objects with their own lifecycle and webhook events. Your product should notify the user, explain the reversal, and update any progress displays that reflected the original payment.

<Warning>
  In both cases, avoid technical jargon. Users don't need to know about ACH return codes or processing windows, they need to know what happened, why, and what to do next.
</Warning>

### Settlement Timing

Settlement and posting timing varies by creditor and payment rail. Do not make hard assumptions about when a payment will post.


# Payments
Source: https://docs.methodfi.com/guides/payments/overview

How Method moves money to pay down debt.

## Payments — Moving Money to Pay Down Debt

### What Payments Enable

Payments are where Method's platform closes the loop from data to action. After discovering a user's liabilities and retrieving their current account data, Payments enable your application to actually move money — initiating paydowns from your platform's corporate funding account to your users' creditors.

This is the capability that transforms Method from a data platform into a complete debt management infrastructure. Without Payments, you can show users what they owe. With Payments, you can help them do something about it.

### What's Required Before a Payment Can Be Made

<Steps>
  <Step title="A verified Entity">
    The user must have completed [identity verification](/guides/identity-verification/overview). This is a non-negotiable compliance and fraud prevention requirement.
  </Step>

  <Step title="A destination liability account">
    The credit card, loan, or other debt being paid down, typically discovered through [Connect](/guides/connect/overview). This is where the money goes.
  </Step>

  <Step title="A verified funding source">
    Your platform's corporate bank account (checking or savings), linked via ACH and [verified](/guides/accounts/funding) through micro-deposits, Plaid, MX, or Teller. This is where the money comes from.
  </Step>

  <Step title="Webhook handling">
    Because payment processing is asynchronous (it takes time for money to move through the banking system), your application must listen for [webhook](/guides/platform-fundamentals#real-time-notifications-via-webhooks) notifications to track the payment's progress through its lifecycle.
  </Step>
</Steps>

### Payment Processing and Timing

Method supports electronic push payments to liability accounts. When a payment is submitted, funds are initiated from your platform's verified funding account and delivered to the creditor.

Processing typically takes 2–3 business days, though the exact timing varies by institution. Payments are processed in defined windows throughout the business day, so the time you submit a payment relative to the next processing window affects when it begins moving. Payments submitted outside of processing windows are held until the next window.

Settlement and posting times are ultimately controlled by the receiving creditor, not by Method. Some creditors apply payments same-day upon receipt; others may take additional time. This means your product should set user expectations appropriately: "Your payment has been sent and will be applied by your creditor, typically within a few business days." Avoid making hard promises about exact posting dates.


# Platform Fundamentals
Source: https://docs.methodfi.com/guides/platform-fundamentals

Environments, authentication, data flow patterns, and webhooks.

## Environments

Method provides three isolated environments, each serving a distinct purpose in your integration lifecycle:

<CardGroup>
  <Card title="Development" icon="wrench">
    Mocked responses. No real institutions contacted, no payments processed.
  </Card>

  <Card title="Sandbox" icon="flask-vial">
    Simulated flows with test data. Mimics real account discovery, payment timelines, and error states.
  </Card>

  <Card title="Production" icon="rocket">
    Live environment. Real institutions, real data, real money.
  </Card>
</CardGroup>

<Warning>
  Each environment uses separate API credentials and data does not cross environments. This allows you to test safely in Development and Sandbox without affecting Production users or data.
</Warning>

## Authentication and API Keys

Method uses API keys for authentication. Include your key in the `Authorization` header of every request. Each environment under each team has its own unique API key.

```bash theme={null}
curl https://production.methodfi.com/entities \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Method-Version: 2026-03-30"
```

The `Method-Version` header pins your requests to a specific API version, ensuring your integration behaves consistently even as Method's API evolves. When a new version is released, you can migrate on your own timeline. If the header is omitted, your team's default version is used. See [Versioning](/reference/versioning) in the API Reference for details.

See the [Authentication](/reference/authentication) reference for details.

## How Data Flows: On-Demand vs Subscriptions

Method offers two complementary models for accessing data, and understanding when to use each is important for designing your product experience.

<Tabs>
  <Tab title="On-Demand">
    On-demand access means you request data when you need it. For example, when a user opens their dashboard, you might request a fresh balance update for their accounts at that moment. On-demand is best for user-initiated actions, one-time data pulls, or situations where you need specific data at a specific time.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates \
      -X POST \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Method-Version: 2026-03-30" \
      -H "Content-Type: application/json" \
      -d '{"type": "direct"}'
    ```
  </Tab>

  <Tab title="Subscriptions">
    Subscription-based access means Method continuously monitors for changes and delivers new data to you automatically. For example, you might subscribe to balance updates for all of a user's accounts, and Method will notify you whenever new data is available, whether that's daily, weekly, or whenever the financial institution reports. Subscriptions are best for keeping dashboards current, triggering automated workflows, and monitoring for changes without requiring user action.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions \
      -X POST \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Method-Version: 2026-03-30" \
      -H "Content-Type: application/json" \
      -d '{"enroll": "update"}'
    ```
  </Tab>
</Tabs>

<Note>
  Not all products support both modes. Refer to each product's documentation for availability.
</Note>

## Real-Time Notifications via Webhook Events

Method's platform is fundamentally asynchronous, when you request an account update or initiate a payment, the result isn't always available immediately. Instead, Method notifies your system when something happens through webhook events: real-time HTTP notifications sent to an endpoint you configure.

For your product team, the key implication is this: your application should be designed around event-driven updates rather than polling or refresh buttons. When a payment posts, when new account data is available, when a user's credit score changes, Method tells you. This event-driven model enables responsive, real-time user experiences without the complexity and cost of constant polling.

The typical webhook handling pattern looks like this:

1. Method sends an HTTP POST to your configured endpoint with event details
2. Your backend acknowledges receipt (return a 2xx response promptly)
3. Your backend fetches the updated resource using the IDs in the event payload
4. Your application updates its local state and, if needed, refreshes the user's UI

This pattern applies to virtually every webhook: payment status changes, new account data, completed discovery, credit score updates, and more.

<Warning>
  Return your 2xx response before processing the event. If your endpoint takes too long to respond, Method will retry the delivery, which can cause duplicate processing. Deduplicate deliveries using the `method-webhook-delivery-id` request header and make your processing idempotent; see [Handling duplicate deliveries](/reference/webhooks/overview#handling-duplicate-deliveries).
</Warning>

Nearly every product creates and updates events, so webhooks are the primary mechanism for keeping your system in sync with Method.

Common webhook events include:

| Event                 | Description                             |
| --------------------- | --------------------------------------- |
| `payment.update`      | A payment's status has changed          |
| `account.create`      | A new account was discovered or created |
| `connect.completed`   | Account discovery finished              |
| `update.completed`    | Fresh account data is available         |
| `credit_score.update` | A credit score has changed              |

See the [Webhooks](/reference/webhooks/overview) reference for setup instructions and the [Events](/reference/events/overview) reference for the full list of event types.

## Reliability and Safety

Method's platform includes built-in mechanisms to ensure reliability. Your engineering team will handle implementation details, but at a product level the key guarantees are:

* **Idempotency keys:** Duplicate operations are prevented automatically (so a network hiccup doesn't create two payments). See [Idempotency](/reference/idempotency).
* **Rate limits:** Requests are rate-limited to maintain platform stability, and operations can be safely retried without unintended side effects. See [Rate Limiting](/reference/rate-limiting) in the API Reference for details.
* **Versioned APIs:** Method maintains versioned APIs so integrations remain stable as the platform evolves. New capabilities are introduced without breaking existing implementations.
* **Paginated list endpoints:** All list endpoints return paginated results, ensuring predictable performance regardless of data volume. See [Pagination](/reference/pagination) in the API Reference for details.
* **Reliable updates:** Changes to liabilities and payments are delivered through subscriptions and webhooks, ensuring your application stays in sync with real account activity.

These aren't features you need to design around, they're guardrails Method provides out of the box.

<CardGroup>
  <Card title="Authentication Reference" icon="key" href="/reference/authentication">
    API keys, headers, and request setup.
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.methodfi.com/guides/quickstart

Get up and running with Method's four-step integration process.

Getting up and running with Method follows a predictable path, whether you're building a debt repayment app, a financial wellness dashboard, or an embedded lending experience.

## The Four-Step Integration Process

Most integrations follow the same high-level pattern, regardless of your specific use case:

<Steps>
  <Step title="Represent your user">
    Every end user in your application maps to an [Entity](/guides/entities/overview) in Method. This is the foundational object that everything else, verification, accounts, payments, attaches to. You provide basic identifying information (name, phone number, and optionally additional PII), and Method creates a persistent identity that follows the user throughout their lifecycle in your product.
  </Step>

  <Step title="Verify their identity">
    Before Method can discover a user's accounts or process payments on their behalf, the user must complete [identity verification](/guides/identity-verification/overview). This is a two-part process: first confirming they control their phone number, then verifying their identity through a KYC process.

    Method supports multiple verification approaches (SMS, silent network auth, KBA, and BYO options). Method will partner with your team to help determine which methods are best suited for your use case and user demographics.
  </Step>

  <Step title="Discover their accounts">
    Once verified, Method can discover the user's financial liabilities using a soft-pull credit report (no impact to their credit score). This is the moment where your product goes from knowing who a user is to knowing what they owe — and to whom. [Accounts](/guides/accounts/overview) are automatically created in Method as they're discovered, giving you immediate access to liability data across credit cards, loans, mortgages, and more.

    Each discovered account comes with the data reported to the credit bureau, including balance, credit limit, payment status, account type, and the financial institution that holds the account. From there, you can request real-time [Updates](/guides/updates/overview) to get current balances, due dates, minimum payments, interest rates, and more directly from the institution.
  </Step>

  <Step title="Take action">
    With accounts connected, you can now do the things that make your product valuable: pull fresh balance and payment data ([Updates](/guides/updates/overview)), initiate paydowns and bill pay ([Payments](/guides/payments/overview)), monitor for changes over time, and present your users with a clear, actionable picture of their financial obligations.

    Updates return structured, normalized fields — balances, due dates, minimum payments, interest rates, credit limits, and more — in a consistent format regardless of the underlying financial institution.
  </Step>
</Steps>

## Choosing Your Integration Approach

Method offers two primary integration approaches, and understanding the tradeoff early saves significant time:

<Tabs>
  <Tab title="Opal (Embedded UI)">
    **Best for most teams.** [Opal](/guides/opal) is Method's pre-built, white-labeled UI that handles identity verification, account discovery, and more. It's designed to drop into your application with minimal frontend work while providing a polished, tested user experience.

    *Choose Opal if you want to move fast, minimize custom UI development, and leverage Method's UX expertise. Most teams start here.*
  </Tab>

  <Tab title="API-Only">
    **Best for teams with specific UX requirements.** If you have an existing in-app flow, a highly customized user experience, or specific design requirements that Opal can't accommodate, you can integrate directly with Method's APIs.

    *This gives you complete control over the user experience but requires more frontend development and ongoing maintenance.*
  </Tab>
</Tabs>

## Example Integration Paths

To make the integration journey concrete, here are three common paths mapped to real product scenarios:

<AccordionGroup>
  <Accordion title="Debt Discovery (e.g., a financial wellness dashboard)">
    Your user signs up → you create an Entity and verify their identity → Method discovers all their liabilities → you display a comprehensive debt overview with balances, interest rates, and payment schedules → you subscribe to updates to keep the dashboard current.

    *Timeline to first value: the user sees their complete debt picture within minutes of completing verification.*
  </Accordion>

  <Accordion title="Debt Paydown (e.g., a debt repayment lender)">
    Your user signs up → identity verification → account discovery → you link your corporate account as a funding source → your user flow presents a paydown strategy → payments are initiated through Method → you track each payment from submission to posting and update the user's progress.

    *This is the full end-to-end loop that turns data into action.*
  </Accordion>

  <Accordion title="Ongoing Monitoring (e.g., a credit health tool)">
    Your user completes the initial setup → you subscribe to account updates and credit score monitoring → Method notifies you when balances change, payments post, credit scores shift, or new accounts appear → your app surfaces these changes as alerts, insights, or progress updates.

    *The user gets continuous value without ever repeating the setup process.*
  </Accordion>

  <Accordion title="Card Linking (e.g., a card-linked offers platform)">
    Your user signs up → you create an Entity and verify their identity → Method discovers their credit card accounts → you retrieve card brand details (card art, product name) and tokenize card credentials via Payment Instruments → your platform uses these tokens for checkout, rewards enrollment, or transaction monitoring.

    *This flow connects your product to the user's existing cards without manual entry or credential sharing.*
  </Accordion>
</AccordionGroup>

## What's Next

<CardGroup>
  <Card title="Platform Fundamentals" icon="gear" href="/guides/platform-fundamentals">
    Environments, authentication, webhooks, and data flow patterns.
  </Card>

  <Card title="Core Concepts" icon="diagram-project" href="/guides/concepts">
    Understand Method's object model and dependency chain.
  </Card>

  <Card title="Opal" icon="window" href="/guides/opal">
    Drop-in embedded UI for identity verification and account discovery.
  </Card>

  <Card title="API Reference" icon="code" href="/reference/introduction">
    Dive into the full API documentation.
  </Card>
</CardGroup>


# Billing Lifecycle and Data Availability
Source: https://docs.methodfi.com/guides/updates/billing-lifecycle

How a cardholder's billing stage determines which fields come back in an Update.

## Billing Lifecycle and Data Availability

Financial institutions determine which data fields are returned for Updates based on the cardholder's billing lifecycle stage. The four common cardholder states:

* **Bill Created**: A new statement has been generated. All billing fields are available.
* **Bill Due**: A payment is owed. Balance, minimum payment, and due date are present, but no last payment information has been reported yet.
* **Bill Paid**: A payment has been made. Last payment amount and date are available, but the next due date has not yet been generated.
* **Dormant**: The account is open but shows minimal activity. Typically only balance (and sometimes available credit) is returned.

| Field                          | Created | Due | Paid | Dormant |
| ------------------------------ | :-----: | :-: | :--: | :-----: |
| available\_credit              |    ✓    |  ✓  |   ✓  |    ✓    |
| balance                        |    ✓    |  ✓  |   ✓  |    ✓    |
| last\_payment\_amount          |    ✓    |     |   ✓  |         |
| last\_payment\_date            |    ✓    |     |   ✓  |         |
| next\_payment\_minimum\_amount |    ✓    |  ✓  |   ✓  |         |
| next\_payment\_due\_date       |    ✓    |  ✓  |      |         |

*Approximate distribution across states: Bill Created 28%, Bill Due 10%, Bill Paid 31%, Dormant 10%, Other 20%.*

The distribution across these states varies significantly by issuer. Each financial institution presents data differently, resulting in different extraction profiles.


# Handling Update Failures
Source: https://docs.methodfi.com/guides/updates/failures

Recommended patterns for handling stale data and failed refreshes.

## Common Failure Modes

Direct Updates can fail for several reasons. In the Update response, direct retrieval failures currently surface through a canonical `error` object:

| Failure Mode                                           | Where it surfaces                                                                      | Recommended Action                                                                                          |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Institution unreachable or temporarily unavailable     | Update `error.code: 21001`; account `data_status_error` is usually `15004` or `15006`. | Retry after a delay. These are usually transient.                                                           |
| Account not supported                                  | Account `data_status_error: 15009`.                                                    | Check the account's `products` array, then rely on snapshot Updates from an `update.snapshot` subscription. |
| Account closed, paid off, transferred, or consolidated | Account `data_status_error` is `15001`, `15002`, `15003`, or `15010`.                  | Update your local records. Re-discover via Connect when appropriate.                                        |
| Authentication or account detail mismatch              | Account `data_status_error` is `15005` or `15007`.                                     | Refresh identity or account details, then re-enroll or re-discover the account.                             |
| Delinquent or disabled liability                       | Account `data_status_error` is `15008` or `15011`.                                     | Surface the state to the user or contact support if unexpected.                                             |

```json theme={null}
{
  "id": "upt_NYV5kfjskTTCJ",
  "status": "failed",
  "error": {
    "type": "UPDATE_FAILED",
    "sub_type": "UPDATE_TEMPORARILY_UNAVAILABLE",
    "code": 21001,
    "message": "Update is temporarily unavailable for this account."
  }
}
```

For the granular reason, read the underlying account liability's `data_status_error`. These are the codes exposed by the API:

| Code    | Reason                     | What it means                                                                                                                                                | Recommended action                                                        |
| ------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `15001` | Closed                     | The account has been closed at the institution.                                                                                                              | Update your local records. Don't retry.                                   |
| `15002` | Paid in full               | The liability has been paid off.                                                                                                                             | Update your local records. Don't retry.                                   |
| `15003` | No longer serviced         | The institution no longer services this account (e.g. transferred or sold).                                                                                  | Update your local records. Don't retry.                                   |
| `15004` | Unauthorized / sync failed | Catch-all for transient and connection-level failures (institution timeouts, technical issues, outside-hours, internal errors, repeated failure throttling). | Retry after a delay. If persistent, contact support.                      |
| `15005` | Invalid holder details     | The institution rejected the holder details Method has on file (e.g., DOB, postal code, KYC).                                                                | Refresh the entity's identity data and re-enroll.                         |
| `15006` | Temporarily unavailable    | Generic temporary failure.                                                                                                                                   | Retry after a delay.                                                      |
| `15007` | Invalid account number     | The account number Method has is no longer valid at the institution.                                                                                         | Re-discover the account via Connect.                                      |
| `15008` | Delinquent                 | The account is in a delinquent state at the institution.                                                                                                     | Surface this to the user. Don't retry until resolved.                     |
| `15009` | Unsupported merchant       | The institution doesn't support real-time data connections for this account type.                                                                            | Rely on snapshot Updates delivered via an `update.snapshot` subscription. |
| `15010` | Consolidated loan          | The student loan has been consolidated into a different loan.                                                                                                | Re-discover via Connect.                                                  |
| `15011` | Liability disabled         | Updates have been disabled for this liability.                                                                                                               | Don't retry. Contact support if unexpected.                               |

<Note>
  Rate limiting is not currently exposed as a distinct Update failure code. Repeated failure throttling may appear under the catch-all sync failed reason (`15004`).
</Note>

## Retry Strategy

```
1. First retry: wait 5 minutes
2. Second retry: wait 30 minutes
3. Third retry: wait 2 hours
4. After 3 failures: display the most recent snapshot data and alert your CSM
```

Use [idempotency keys](/reference/idempotency) when retrying to avoid duplicate requests.

## Fallback Pattern: Direct to Snapshot

When direct Updates aren't available or keep failing, snapshot data provides a reliable baseline. Note that `POST /accounts/{acc_id}/updates` always creates a direct Update; you cannot request a snapshot Update on demand. Snapshot Updates are produced by `update.snapshot` [subscriptions](/guides/updates/subscriptions) and delivered via webhook.

To fall back to snapshot data, list the account's existing Updates and use the most recent one whose `source` is `snapshot`:

```bash theme={null}
curl "https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates?source=snapshot" \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

If no snapshot Update exists yet, create an `update.snapshot` subscription so future bureau refreshes are delivered automatically:

```bash theme={null}
curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{"enroll": "update.snapshot"}'
```

## UX Recommendations

* **Always show the most recent known data**, even if it's stale. A balance from last week is better than a blank screen.
* **Indicate freshness.** Show the `data_as_of` timestamp so users know how current the data is: "Balance as of March 20, 2024."
* **Show refresh state.** When an Update is in progress, show a loading indicator alongside the existing data.
* **Don't block on failures.** If a direct Update fails, display the last snapshot data and retry in the background.

## Subscription Failures

For failed subscription executions, Method requeues the subscription execution for retry. The subscription queue retries failed executions daily up to three times, then schedules the next run according to the subscription's normal cadence.

Monitor `update.update` webhooks for failed Updates to detect persistent issues with specific accounts or institutions and to drive your own fallback (e.g., showing snapshot data, prompting the user to reconnect for `15005`/`15007`).

## Fields by Liability Type

The data returned in an Update depends on the account type. Common patterns:

| Liability Type | Key Fields                                                                                          |
| -------------- | --------------------------------------------------------------------------------------------------- |
| Credit Card    | balance, available\_credit, credit\_limit, interest\_rate (min/max/type), payment info, opened\_at  |
| Auto Loan      | balance, interest\_rate, original\_loan\_amount, term\_length, expected\_payoff\_date, payment info |
| Student Loan   | balance, original\_loan\_amount, term\_length, payment info                                         |
| Mortgage       | balance, interest\_rate, original\_loan\_amount, term\_length, expected\_payoff\_date, payment info |
| Personal Loan  | balance, available\_credit, interest\_rate, original\_loan\_amount, term\_length, payment info      |

All types share: `balance`, `last_payment_amount`, `last_payment_date`, `next_payment_due_date`, `next_payment_minimum_amount`, `opened_at`, `closed_at`.

For the full Updates API, see the [Updates reference](/reference/accounts/updates/overview).


# Update Lifecycle
Source: https://docs.methodfi.com/guides/updates/lifecycle

The stages of an Update request and how to track them.

## Update Lifecycle

### Status Transitions

```
Created -> Processing -> Completed -> Failed
```

| Status       | Description                                                                      | What to do                                                                                      |
| ------------ | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `pending`    | Request submitted, queued for processing.                                        | Wait for webhook or poll.                                                                       |
| `processing` | Method is actively retrieving data from the source.                              | Wait. Direct Updates typically complete within seconds to minutes depending on the institution. |
| `completed`  | Data is available. The liability-type object (e.g., `credit_card`) is populated. | Read the data, update your local store, display to user.                                        |
| `failed`     | Retrieval was unsuccessful. The `error` object is populated with details.        | See [Handling Failures](/guides/updates/failures).                                              |

### Timing Expectations

* **Snapshot Updates:** Return synchronously in the POST response. No lifecycle to track. The response is immediately `completed` (or `failed`).
* **Direct Updates:** Asynchronous. Typical completion time varies by institution. Most complete within seconds, some may take up to a few minutes. Design your UI to show a loading state and handle the webhook.

### Webhook Events

| Event           | When it fires                                                                                 |
| --------------- | --------------------------------------------------------------------------------------------- |
| `update.create` | An Update has been created (status: `pending`).                                               |
| `update.update` | An Update's status has changed (typically `pending` to `completed` or `pending` to `failed`). |

Subscribe to `update.update` to react when data is ready. The webhook payload includes the path to retrieve the full Update object.

### Idempotency

If you need to retry a failed Update, use [idempotency keys](/reference/idempotency) to avoid creating duplicate requests.


# Updates
Source: https://docs.methodfi.com/guides/updates/overview

How Method keeps account data fresh, snapshot vs direct sources.

## Keeping Account Data Fresh and Accurate

### What an Update Is

An Update is the mechanism through which Method delivers the latest state of a connected account: current balance, payment due date, minimum payment amount, interest rate, credit limit, and other relevant fields depending on the account type. If [Connect](/guides/connect/overview) is how you discover accounts, Updates are how you keep those accounts' data current over time.

The freshness and accuracy of your account data directly impacts the quality of your product experience. A debt repayment app that shows last month's balance feels broken. A payment scheduler that uses stale due dates risks missed payments. Updates are how you ensure your product reflects financial reality, not an outdated snapshot.

### Two Sources of Truth: Snapshot vs. Direct

Updates come from two fundamentally different data sources, and choosing between them is an important product decision:

## Checking Update Availability

Before requesting an Update, check the account's `products` array:

* `update` in `products` means direct Updates are available (real-time data from the institution).

If `update` is in `restricted_products` instead of `products`, direct Updates require additional steps (e.g., account verification). If `update` does not appear, data retrieval isn't currently available for this account.

<Tabs>
  <Tab title="Snapshot">
    Pull data from the user's credit report. Credit reports are compiled by the major bureaus and updated when creditors submit their reporting data, typically on a monthly cycle. Snapshot data is available for the broadest range of accounts, but it's only as fresh as the most recent creditor report.

    | Attribute     | Detail                                                                  |
    | ------------- | ----------------------------------------------------------------------- |
    | **Freshness** | Monthly (credit report cycle)                                           |
    | **Delivery**  | Produced by an `update.snapshot` subscription and delivered via webhook |
    | **Coverage**  | Broadest, works for virtually every account                             |

    **Best for:** Building account overview screens, displaying general balance trends, monitoring credit health over time, showing account summaries where approximate data is acceptable, or when you need data for account types where direct connections aren't available. Snapshot Updates are your reliable baseline. They work for virtually every discovered account and provide a good-enough picture for many use cases.

    Snapshot Updates cannot be created on demand. Subscribe to `update.snapshot` so Method delivers a fresh snapshot whenever the bureau reports new data, then retrieve the most recent snapshot from the list endpoint:

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{"enroll": "update.snapshot"}'

    curl "https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates?source=snapshot" \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```
  </Tab>

  <Tab title="Direct">
    Pull data directly from the financial institution in real time. This means the data reflects the account's current state as of the moment the institution responds, including very recent payments, daily interest accrual, and same-day balance changes. Direct Updates are asynchronous (you submit a request and receive the result via webhook when it completes) and take longer, but the data is significantly more current.

    | Attribute     | Detail                                   |
    | ------------- | ---------------------------------------- |
    | **Freshness** | Real-time (as of institution response)   |
    | **Response**  | Async (webhook delivery)                 |
    | **Coverage**  | Narrower, depends on institution support |

    **Best for:** Confirming a balance before initiating a payment, displaying exact payment due dates or minimum payment amounts, current interest rate or APR information, verifying that a recent payment has posted, or when accuracy is critical to your product's core value proposition.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{"type": "direct"}'
    ```
  </Tab>
</Tabs>

<Note>
  Many products use both: snapshot data as the default display, with direct Updates triggered when the user takes an action that requires current data (like preparing to make a payment).
</Note>

## The Update Flow

<Accordion title="On-demand direct Update walkthrough">
  ### On-Demand (Direct) Update

  **Step 1: Request a direct Update**

  ```bash theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{"type": "direct"}'
  ```

  The response returns immediately with `status: pending`:

  ```json theme={null}
  {
    "id": "upt_NYV5kfjskTTCJ",
    "status": "pending",
    "account_id": "acc_yVf3mkzbhz9tj",
    "source": "direct",
    "type": "credit_card",
    "credit_card": null,
    "error": null,
    "created_at": "2024-03-20T04:43:21.434Z",
    "updated_at": "2024-03-20T04:43:21.655Z"
  }
  ```

  ### Step 2: Wait for completion

  Listen for the `update.update` webhook:

  ```json theme={null}
  {
    "type": "update.update",
    "path": "/accounts/acc_yVf3mkzbhz9tj/updates/upt_NYV5kfjskTTCJ"
  }
  ```

  ### Step 3: Retrieve the completed Update

  ```bash theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/updates/upt_NYV5kfjskTTCJ \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  The completed Update contains the account's current data:

  ```json theme={null}
  {
    "id": "upt_NYV5kfjskTTCJ",
    "status": "completed",
    "account_id": "acc_yVf3mkzbhz9tj",
    "source": "direct",
    "type": "credit_card",
    "data_as_of": "2024-03-20T04:43:21.434Z",
    "credit_card": {
      "available_credit": 120000,
      "balance": 80000,
      "credit_limit": 200000,
      "interest_rate_percentage_max": 23.5,
      "interest_rate_percentage_min": 12.0,
      "interest_rate_type": "variable",
      "last_payment_amount": 5000,
      "last_payment_date": "2024-04-05",
      "next_payment_due_date": "2024-05-01",
      "next_payment_minimum_amount": 4000,
      "opened_at": "2018-10-30"
    },
    "error": null,
    "created_at": "2024-03-20T04:43:21.434Z",
    "updated_at": "2024-03-20T04:43:21.655Z"
  }
  ```
</Accordion>

## Reading the Update Response

The Update response wraps the account data inside a liability-type object. The key fields:

| Field              | Description                                                                                                                                                             |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source`           | `snapshot` or `direct`, which data source this Update used.                                                                                                             |
| `type`             | The liability type: `credit_card`, `auto_loan`, `student_loans`, `mortgage`, `personal_loan`, etc.                                                                      |
| `data_as_of`       | Timestamp of when this data was current. For direct, this is the moment the institution responded. For snapshot, this is when the creditor last reported to the bureau. |
| `[liability_type]` | The data object (e.g., `credit_card`, `auto_loan`). Contains the balance, rates, payment info, and dates specific to that account type.                                 |
| `status`           | `pending`, `processing`, `completed`, or `failed`. See [Update Lifecycle](/guides/updates/lifecycle).                                                                   |
| `error`            | Populated if the Update failed. See [Handling Failures](/guides/updates/failures).                                                                                      |

<Note>
  **All monetary amounts are in cents.** A `balance` of `80000` means \$800.00. A `last_payment_amount` of `5000` means \$50.00.
</Note>

## Next Steps

<CardGroup>
  <Card title="Update Subscriptions" icon="arrows-rotate" href="/guides/updates/subscriptions">
    Set up automatic data refreshes without manual requests.
  </Card>

  <Card title="Update Lifecycle" icon="arrows-spin" href="/guides/updates/lifecycle">
    Understand the stages of an Update request.
  </Card>

  <Card title="Handling Failures" icon="triangle-exclamation" href="/guides/updates/failures">
    Design resilient UX around failed or stale data.
  </Card>

  <Card title="Updates API Reference" icon="code" href="/reference/accounts/updates/overview">
    Full endpoint documentation, fields, and error codes.
  </Card>
</CardGroup>


# Update Subscriptions
Source: https://docs.methodfi.com/guides/updates/subscriptions

Set-and-forget monitoring to keep account data current.

## What Update Subscriptions Do

For products that need to keep data current without requiring users to manually refresh, Update Subscriptions provide a set-and-forget monitoring capability.

* A direct Update subscription tells Method to periodically pull fresh data from the financial institution and deliver it to you via webhook as it becomes available. The refresh cadence depends on the institution and account type.
* A snapshot-only subscription delivers new data whenever the credit report refreshes (typically monthly), ensuring your baseline data stays current without manual intervention.

Subscriptions are essential for: dashboards and account overview screens that should always show reasonably current data, alerting systems that detect changes (missed payments, balance spikes, rate changes), progress tracking features that show debt paydown over time, and any feature where the user expects data to be fresh without taking action.

The combination of on-demand Updates for user-initiated actions and subscription-based Updates for background freshness gives you a complete data strategy.

## Creating a Subscription

You can set up subscriptions either at Connect time (recommended for new accounts) or individually on existing accounts.

### At Connect Time (Recommended)

Include `subscriptions` in your Connect request to automatically subscribe all discovered accounts:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriptions": ["update"]
  }'
```

### On an Existing Account

```bash theme={null}
curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{"enroll": "update"}'
```

## Subscription Types

| Type              | What it does                                                                                                                                                     |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `update`          | Periodically pulls real-time data directly from the financial institution and delivers via webhook. Refresh cadence depends on the institution and account type. |
| `update.snapshot` | Delivers new credit report data whenever the bureau refreshes (typically monthly). Lower cost, broader coverage.                                                 |

<Note>
  Check the account's `available_subscriptions` array before creating a subscription. If `update` isn't listed, direct subscriptions aren't available for that account.
</Note>

### Refresh Cadence

<Note>
  The frequency of updates for direct subscriptions depends on the liability type and the individual account. Credit cards generally update more frequently (every 1 to 3 days), while personal loans and mortgages typically refresh every \~30 days, aligning with billing cycles and account activity. Snapshot subscriptions refresh whenever the credit bureau receives updated data from the creditor, usually on a monthly basis.
</Note>

## Receiving Updates via Webhook

When a subscription triggers a refresh, Method sends an `update.create` webhook when the Update is created, followed by an `update.update` webhook when its status changes (typically to `completed` or `failed`):

```json theme={null}
{
  "type": "update.update",
  "path": "/accounts/acc_yVf3mkzbhz9tj/updates/upt_NYV5kfjskTTCJ"
}
```

Retrieve the Update from the path to get the fresh data. Your application should process these webhooks to update its local data store or cache.

## Managing Subscriptions

* **List active subscriptions:** `GET /accounts/{acc_id}/subscriptions`
* **Delete a subscription:** `DELETE /accounts/{acc_id}/subscriptions/{sub_id}`

Subscriptions remain active until explicitly deleted or the account is disabled/closed.

## When to Use Subscriptions vs On-Demand Updates

| Scenario                                      | Approach                          |
| --------------------------------------------- | --------------------------------- |
| Dashboard showing current balances            | Subscription (background refresh) |
| Pre-payment balance confirmation              | On-demand direct Update           |
| Debt paydown progress tracking                | Subscription                      |
| One-time underwriting check                   | On-demand direct Update           |
| Alerting on missed payments or balance spikes | Subscription                      |


# Overview
Source: https://docs.methodfi.com/libraries/overview



Method offers a list of official libraries that help developers easily
interact and build on top of the Method services.

## API client Libraries

Below is a list of libraries for each supported programming language. These
libraries are updated frequently to provide the best developer experience
when interacting with the Method API.

<CardGroup>
  <Card title="Node.js" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/nodejs-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=57e4626e40345a82da3e7effb6ab274a" />} href="https://github.com/MethodFi/method-node" />

  <Card title="Python" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/python-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=2e67dd38fef1f2c7d80ce0e422f6943c" />} href="https://github.com/MethodFi/method-python" />

  <Card title="OpenAPI" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/openapi-logo.svg?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=96448d2076f343383dd60886f7eebc20" />} href="https://github.com/MethodFi/openapi" />
</CardGroup>

## Element client libraries

Method supports a list of frontend libraries to make integrating Element
into your applications more seamless.

<CardGroup>
  <Card title="Javascript" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/js-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=ea0213b8187f61bcb5c5ecb75abd29f8" />} href="/libraries/js-sdk" />

  <Card title="React" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/react-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=9c683655cfe19c265ac9f077575b7a9e" />} href="https://github.com/MethodFi/react-method-elements" />

  <Card title="React Native" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/react-native-logo.svg?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=a3157c02adfdff112505e4c6ed5d91b0" />} href="https://github.com/MethodFi/react-native-method-elements" />
</CardGroup>

## Quickstart and examples

We've built a couple of quickstart applications to help you get started with
seamlessly building on top of Method.

<CardGroup>
  <Card title="Postman" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/postman-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=e23ad5829a5ea39ac00b25fcc1a34b4d" />} href="https://www.postman.com/methodfi/method-api/collection/8d5j00b/method-api-v2" />
</CardGroup>


# Account Verification
Source: https://docs.methodfi.com/opal/account_verification/overview



<Note>Mode: `account_verification`</Note>

Opal Account Verification is a pre-built flow for verifying a specific account. It provides a secure, compliant way to verify a single, known account (for example, a specific credit card).

<img alt="account-verification-hero" />

## What this mode does

Account Verification drives a focused verification flow for a single, known account (for example, a specific credit card). You must pass the target account\_id. Account Verification will automatically be invoked when needed (for example, during card\_connect), or can be used as a standalone module.

## Parameters

<ParamList />

## Create a token

You can create an account verification session token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `account_verification`
* Create new entity: provide `entity` + `mode` + `account_verification`
* Resume session: provide `session_id` only (omit `mode` and `account_verification`)

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "account_verification",
  "account_verification": { "account_id": "acc_..." }
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15125551234"
    }
  },
  "mode": "account_verification",
  "account_verification": { "account_id": "acc_..." }
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "valid_until": "2025-06-10T22:50:53.024Z",
  "session_id": "osess_..."
}
```

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Verify account</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Verify account" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>


# Card Connect
Source: https://docs.methodfi.com/opal/card_connect/overview



<Note>Mode: `card_connect`</Note>

Opal Card Connect is the primary way to connect user credit cards with Method.
This pre-built flow gathers a user's consent, verifies their identity, and completes any needed verifications to ensure their cards are connected to the Method ecosystem.

<img alt="account-verification-hero" />

## What this mode does

Card Connect lets users select and verify credit cards. Configure whether users may select a single card or multiple cards. Verified cards are eligible for payments and transactions.

## Parameters

<ParamList />

## Create a token

You can create a card connect session token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `card_connect`
* Create new entity: provide `entity` + `mode` + `card_connect`
* Resume session: provide `session_id` only (omit `mode` and `card_connect`)

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "card_connect",
  "card_connect": {
    "selection_type": "single",
    "account_filters": {
      "exclude": {
        "mch_ids": ["mch_123"],
        "unverified_account_numbers": true
      }
    }
  }
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15125551234"
    }
  },
  "mode": "card_connect",
  "card_connect": {
    "selection_type": "multiple"
  }
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "valid_until": "2025-06-10T22:50:53.024Z",
  "session_id": "osess_..."
}
```

## Testing in Development

When testing the frontend for Card Connect in the dev environment, use the following test values:

* **Verification code**: When the modal prompts you to enter a six-digit verification code, you can use any six-digit code. For example: `123456`. This applies to any test case (e.g. identity verification, connect, etc.).
* **Card verification**: Select the Chase card ending in `1580` and use `878` as the CVV.

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Connect Card</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Connect Card" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>


# Connect
Source: https://docs.methodfi.com/opal/connect/overview



<Note>Mode: `connect`</Note>

Opal Connect is the primary way to connect user liability accounts with Method.
This pre-built flow gathers a user's consent, verifies their identity, and completes any needed verifications to ensure their accounts are connected to the Method ecosystem.

<img alt="connect-hero" />

## What this mode does

Connect lets users find and connect their liability accounts (credit cards, loans, mortgages, etc.). Configure whether users may select a single account, multiple accounts, or by default select all eligible accounts.

## Parameters

<ParamList />

## Create a token

You can create a connect session token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `connect`
* Create new entity: provide `entity` + `mode` + `connect`
* Resume session: provide `session_id` only (omit `mode` and `connect`)

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "connect",
  "connect": {
    "selection_type": "single",
    "account_filters": {
      "include": {
        "account_types": ["credit_card", "auto_loan"],
        "products": ["balance"]
      }
    }
  }
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15125551234"
    }
  },
  "mode": "connect",
  "connect": {
    "selection_type": "multiple",
    "account_filters": {
      "exclude": {
        "account_types": ["personal_loan"],
        "mch_ids": ["mch_123"],
        "unverified_account_numbers": true
      }
    }
  }
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "valid_until": "2025-06-10T22:50:53.024Z",
  "session_id": "osess_..."
}
```

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Connect Accounts</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Connect Accounts" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>


# Opal Events
Source: https://docs.methodfi.com/opal/events



Communication between Opal and your app is handled through a consistent, mode-aware event system. Events are emitted throughout the user session to indicate progress, completion, errors, and important milestones.

## Listening to Events

We strongly recommend using one of the Opal SDKs to receive typed events and lifecycle callbacks. The SDKs provide `onEvent`, `onOpen`, and `onExit` handlers and expose a small enum of well-known events under `OpalEventType` for convenience (e.g., `SESSION_STARTED`, `SESSION_COMPLETED`).

Each Opal mode (`identity_verification`, `connect`, `card_connect`, `account_verification`, `transactions`) emits a set of mode‑specific events in addition to default session events. See below for structure, a complete list, and examples.

## Event Structure

All Opal events follow a consistent structure:

```json theme={null}
{
  "type": "opal.session.started",
  "mode": "opal",
  "object": "session",
  "action": "started",
  "timestamp": "2025-06-10T22:50:53.024Z",
  "data": null
}
```

### Event fields

| Field       | Type           | Description                                                                                                     |
| ----------- | -------------- | --------------------------------------------------------------------------------------------------------------- |
| `type`      | string         | Fully qualified event name: `<flow>.<object>.<action>` or `opal.session.<action>` for default session events.   |
| `mode`      | string         | The active operational mode (e.g., `connect`, `identity_verification`, `account_verification`, `transactions`). |
| `object`    | string         | The related object (e.g., `session`, `flow`, `step`, `identity`, `card`, `accounts`).                           |
| `action`    | string         | The action that occurred (e.g., `started`, `completed`, `verified`, `errored`).                                 |
| `timestamp` | string         | ISO 8601 timestamp of when the event occurred.                                                                  |
| `data`      | object \| null | Additional context that varies by event type; may be `null` for lifecycle events.                               |

### Possible flows:

* `identity_verification`
* `connect`
* `account_verification`
* `transactions`

## Sample Events

### opal.session.started

```json theme={null}
{
  "type": "opal.session.started",
  "mode": "connect",
  "object": "session",
  "action": "started",
  "timestamp": "2025-06-10T22:50:53.024Z",
  "data": null
}
```

### opal.session.errored

```json theme={null}
{
  "type": "opal.session.errored",
  "mode": "connect",
  "object": "session",
  "action": "errored",
  "timestamp": "2025-06-10T22:50:53.024Z",
  "data": {
    "type": "INVALID_REQUEST",
    "sub_type": "INVALID_SMS_CODE",
    "message": "Invalid request please try again"
  }
}
```

### connect.flow\.completed

```json theme={null}
{
  "type": "connect.flow.completed",
  "mode": "connect",
  "object": "flow",
  "action": "completed",
  "timestamp": "2025-06-10T22:50:53.024Z",
  "data": {
    "accounts": ["acc_ge9hxMTPGdXmQ"],
    "entity_id": "ent_wrDBN43PR8LKC"
  }
}
```

## Event Categories

### Default session events (always available)

* `opal.session.started` - Opal UI opened and session began
* `opal.session.completed` - User completed the flow successfully
* `opal.session.errored` - A recoverable or terminal error occurred
* `opal.session.exited` - User exited or dismissed Opal

### Generic flow and step events

Emitted in addition to the default session events. These mirror the active mode‑specific events but are prefixed with `opal` and can be emitted for any mode.

#### Flow

* `opal.flow.started` - A sub‑flow of Opal started (e.g., identity verification, account selection, verification).
* `opal.flow.completed` - A sub‑flow of Opal completed. This does not always signify the end of the session; use `opal.session.completed` to detect when Opal is fully completed.

#### Step

* `opal.step.started` - A new step started (e.g., phone input, card selection, CVV input).
* `opal.step.completed` - A step completed and the next page is opening.

Notes:

* Additional mode-specific events may be introduced over time. Your handler should use the `OpalEventType` enum to handle the specific cases you need.

## All Event Types

The following table lists all currently supported event types with their `OpalEventType` mapping, and when they are typically emitted.

| Event (OpalEventType - type)                                              | When you might see it                              |
| ------------------------------------------------------------------------- | -------------------------------------------------- |
| `SESSION_STARTED` - `opal.session.started`                                | Opal UI opened and session began.                  |
| `SESSION_COMPLETED` - `opal.session.completed`                            | User completed the overall Opal flow successfully. |
| `SESSION_ERRORED` - `opal.session.errored`                                | A recoverable or terminal error occurred.          |
| `SESSION_EXITED` - `opal.session.exited`                                  | User closed or dismissed Opal before completion.   |
| `FLOW_STARTED` - `opal.flow.started`                                      | A sub-flow (for any mode) started.                 |
| `FLOW_COMPLETED` - `opal.flow.completed`                                  | A sub-flow (for any mode) completed.               |
| `STEP_STARTED` - `opal.step.started`                                      | A step (screen) started.                           |
| `STEP_COMPLETED` - `opal.step.completed`                                  | A step (screen) completed.                         |
| `IDV_FLOW_STARTED` - `identity_verification.flow.started`                 | Identity Verification flow started.                |
| `IDV_STEP_STARTED` - `identity_verification.step.started`                 | A step in Identity Verification started.           |
| `IDV_STEP_COMPLETED` - `identity_verification.step.completed`             | A step in Identity Verification completed.         |
| `IDV_FLOW_COMPLETED` - `identity_verification.flow.completed`             | Identity Verification flow completed.              |
| `IDV_VERIFICATION_COMPLETED` - `identity_verification.identity.completed` | Identity successfully verified (KYC passed).       |
| `CXN_FLOW_STARTED` - `connect.flow.started`                               | Connect flow started.                              |
| `CXN_STEP_STARTED` - `connect.step.started`                               | A step in Connect started.                         |
| `CXN_STEP_COMPLETED` - `connect.step.completed`                           | A step in Connect completed.                       |
| `CXN_FLOW_COMPLETED` - `connect.flow.completed`                           | Connect flow completed.                            |
| `CXN_ACCOUNTS_SELECTED` - `connect.accounts.selected`                     | User selected one or more accounts to connect.     |
| `AVF_FLOW_STARTED` - `account_verification.flow.started`                  | Account Verification flow started.                 |
| `AVF_STEP_STARTED` - `account_verification.step.started`                  | A step in Account Verification started.            |
| `AVF_STEP_COMPLETED` - `account_verification.step.completed`              | A step in Account Verification completed.          |
| `AVF_FLOW_COMPLETED` - `account_verification.flow.completed`              | Account Verification flow completed.               |
| `AVF_CARD_VERIFIED` - `account_verification.card.verified`                | Card verified successfully.                        |
| `TXN_FLOW_STARTED` - `transactions.flow.started`                          | Transactions flow started.                         |
| `TXN_STEP_STARTED` - `transactions.step.started`                          | A step in Transactions started.                    |
| `TXN_STEP_COMPLETED` - `transactions.step.completed`                      | A step in Transactions completed.                  |
| `TXN_FLOW_COMPLETED` - `transactions.flow.completed`                      | Transactions flow completed.                       |
| `TXN_ACCOUNTS_LINKED` - `transactions.accounts.linked`                    | Accounts linked and subscribed for transactions.   |

### Data Payloads

The following events always include a non-null `event.data` payload:

* `identity_verification.identity.completed`
* `connect.accounts.selected`
* `account_verification.card.verified`
* `transactions.accounts.linked`

Use these payloads to retrieve context such as selected accounts, verification results, or linkage details.

## Enhanced Event Handling

### Using the JavaScript SDK

```javascript theme={null}
import { OpalEventType } from '@methodfi/opal-react';

const config = {
  onEvent: (event) => {
    console.log("Event received:", event.type);

    // Handle specific events using the OpalEventType enum
    switch (event.type) {
      case OpalEventType.SESSION_STARTED:
        // Session lifecycle
        break;
      case OpalEventType.SESSION_COMPLETED:
        // Entire Opal session completed successfully
        break;
      case OpalEventType.SESSION_ERRORED:
        // Handle recoverable or terminal error
        console.error("Opal error:", event.data);
        break;
      case OpalEventType.IDV_VERIFICATION_COMPLETED:
        // Identity verification completed; payload contains verification details
        handleIdentityVerified(event.data);
        break;
      case OpalEventType.CXN_ACCOUNTS_SELECTED:
        // User selected accounts in Connect
        handleAccountsSelected(event.data);
        break;
      case OpalEventType.AVF_CARD_VERIFIED:
        // Card verified in Account Verification
        handleCardVerified(event.data);
        break;
      case OpalEventType.TXN_ACCOUNTS_LINKED:
        // Accounts linked for Transactions
        handleAccountsLinked(event.data);
        break;
      default:
        // Optionally handle generic flow/step events
        break;
    }
  },

  // Specific event handlers
  onSuccess: (payload) => {
    // Called for successful completion events
    console.log("Success:", payload);
  },

  onError: (error) => {
    // Enhanced error handling with detailed information
    console.error("Error:", error.code, error.message);
    console.error("Details:", error.details);
  },
};

const opal = new MethodOpal(config);
```

## PostMessage Communication

For applications not using the Opal SDKs, you can listen to events via PostMessage:

### Setup PostMessage Listener

```javascript theme={null}
window.addEventListener("message", function (event) {
  // Verify origin for security
  if (event.origin !== "https://opal.production.methodfi.com") {
    return;
  }

  const opalEvent = event.data;
  console.log("Opal event:", opalEvent.type, opalEvent.data);

  // Handle events
  switch (opalEvent.type) {
    case OpalEventType.SESSION_STARTED:
      console.log("Opal started");
      break;
    case OpalEventType.SESSION_COMPLETED:
      console.log("Opal completed:", opalEvent.data);
      break;
  }
});
```

## Best Practices

### Event Handling

* Always verify event origins for security
* Use event filtering to reduce noise
* Implement proper error handling for all events
* Log events for debugging and analytics

### Security

* Validate all event data before processing
* Never trust client-side events for critical business logic


# Identity Verification
Source: https://docs.methodfi.com/opal/identity/overview



<Note>Mode: `identity_verification`</Note>

Opal Identity Verification is a pre-built flow for verifying user identity. It provides a secure, compliant way to collect and verify personal information like name, date of birth, address, and other identity details needed for KYC/AML requirements.

<img alt="identity-hero" />

## What this mode does

Identity Verification collects, confirms, and verifies a user's identity details (name, DOB, address, phone, SSN if needed). Users must explicitly confirm their details before verification challenges begin. Identity Verification will automatically be invoked when needed, or can be used as a standalone module.

## Parameters

<ParamList />

## Create a token

You can create an identity verification session token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `identity_verification`
* Create new entity: provide `entity` + `mode` + `identity_verification`
* Resume session: provide `session_id` only (omit `mode` and `identity_verification`)

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "identity_verification",
  "identity_verification": {
    "skip_pii": ["name", "dob", "address"]
  }
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15125551234"
    }
  },
  "mode": "identity_verification",
  "identity_verification": {
    "skip_pii": []
  }
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "valid_until": "2025-06-10T22:50:53.024Z",
  "session_id": "osess_..."
}
```

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Verify identity</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Verify identity" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>


# Libraries
Source: https://docs.methodfi.com/opal/libraries



Method offers a variety of libraries for your frontend application to make integrating with Opal easy and simple.

## Frontend Libraries

Depending on your application, Method offers multiple frontend libraries to help you integrate with Opal:

<CardGroup>
  <Card title="JavaScript SDK" icon="js" href="https://static.methodfi.com/opal/v1/stable/init.js">
    For vanilla JavaScript applications
  </Card>

  <Card title="React SDK" icon="react" href="https://www.npmjs.com/package/@methodfi/opal-react">
    For React applications
  </Card>

  <Card title="React Native SDK" icon="mobile" href="https://www.npmjs.com/package/@methodfi/opal-react-native">
    For React Native applications
  </Card>
</CardGroup>

All Opal SDKs provide:

* **Token Management**: Automatic token validation and refresh
* **Event Handling**: Comprehensive event system with typed callbacks
* **Error Management**: Enhanced error handling with detailed error codes
* **Security**: Built-in security features and validation

## Installation

<Tabs>
  <Tab title="JavaScript">
    ```html theme={null}
    <script src="https://static.methodfi.com/opal/v1/stable/init.js"></script>
    ```
  </Tab>

  <Tab title="React">
    ```bash theme={null}
    npm install @methodfi/opal-react
    ```

    ## Quick usage: React (Web)

    ```tsx theme={null}
    import { OpalProvider, useOpal, OpalEventType } from "@methodfi/opal-react";

    export default function App() {
      return (
        <OpalProvider>
          <YourApp />
        </OpalProvider>
      );
    }

    function YourApp() {
      const { open, close, isOpen, error } = useOpal({
        env: "dev",
        onOpen: () => {},
        onExit: () => {},
        onEvent: (event) => {
          switch (event.type) {
            case OpalEventType.SESSION_STARTED:
              // ...
              break;
            case OpalEventType.SESSION_COMPLETED:
              // ...
              break;
            case OpalEventType.SESSION_ERRORED:
              // ...
              break;
            case OpalEventType.SESSION_EXITED:
              // ...
              break;
          }
        },
      });

      const onLaunchOpal = async () => {
        const token = await getOpalToken(); // POST /opal/token
        open({ token });
      };

      return <button onClick={onLaunchOpal}>Launch Opal</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```bash theme={null}
    npm install @methodfi/opal-react-native
    ```

    ## Quick usage: React Native (Mobile)

    ```tsx theme={null}
    import {
      OpalProvider,
      useOpal,
      OpalEventType,
    } from "@methodfi/opal-react-native";

    export default function App() {
      return (
        <OpalProvider>
          <YourScreen />
        </OpalProvider>
      );
    }

    function YourScreen() {
      const { open } = useOpal({
        env: "dev",
        onOpen: () => {},
        onExit: () => {},
        onEvent: (event) => {
          switch (event.type) {
            case OpalEventType.SESSION_STARTED:
              // ...
              break;
            case OpalEventType.SESSION_COMPLETED:
              // ...
              break;
            case OpalEventType.SESSION_ERRORED:
              // ...
              break;
            case OpalEventType.SESSION_EXITED:
              // ...
              break;
          }
        },
      });

      const onLaunchOpal = async () => {
        const token = await getOpalToken(); // POST /opal/token returns otkn_*
        open({ token });
      };

      return <Button title="Launch Opal" onPress={onLaunchOpal} />;
    }
    ```
  </Tab>
</Tabs>

## Testing in Development

When testing the Opal frontend in the dev environment, any modal step that prompts you to enter a six-digit verification code will accept any six-digit code. For example: `123456`.

## Notes

* Event types follow the format `<flow>.<object>.<action>` or `opal.session.<action>` for defaults
* See [Events](/opal/events) for structure and sample payloads


# Migration from Elements
Source: https://docs.methodfi.com/opal/migration_guide



When migrating from Elements to Opal, there are several key changes to consider:

## URL Changes

If you're launching Opal directly from a URL, the process remains similar to Elements, but with updated domains:

* Elements: `elements.{environment}.methodfi.com`
* Opal: `opal.{environment}.methodfi.com`

## New Libraries

We've introduced new SDKs specifically designed for Opal integration:

* [@methodfi/opal-react](https://www.npmjs.com/package/@methodfi/opal-react) for React applications
* [@methodfi/opal-react-native](https://www.npmjs.com/package/@methodfi/opal-react-native) for React Native
* Direct CDN integration via `https://static.methodfi.com/opal/v1/stable/init.js`

See our [libraries documentation](/opal/libraries) for detailed implementation guides.

## Token Generation Changes

When generating tokens for Opal, we've added new parameters that must be provided in order for more flexibility and control over the user experience. The token generation process has been streamlined in Opal.

### Elements

```json theme={null}
POST /elements/token
{
  "type": "connect",
  "connect": {
    "entity_id": "ent_au22b1fbFJbp8",
    "products": ["balance"],
    "redirect_url": "https://example.com/callback"
  }
}
```

### Opal

```json theme={null}
POST /opal/token
{
  "mode": "connect",
  "entity_id": "ent_au22b1fbFJbp8",
  "connect": {
    "selection_type": "single",
    "account_filters": {
      "include": {
        "account_types": ["credit_card", "auto_loan"],
        "products": ["balance"]
      }
    }
  }
}
```

In Elements, product filtering was a top-level field (`connect.products`). In Opal, product filtering is done via `connect.account_filters.include.products`. Allowed values: `balance`, `sensitive`, `payoff`, `update`, `payment`.

See Opal [Identity](/opal/identity/overview), [Connect](/opal/connect/overview), [Card Connect](/opal/card_connect/overview), and [Account Verification](/opal/account_verification/overview) guides for more info on token generation.


# Overview
Source: https://docs.methodfi.com/opal/overview

Method Opal - Next-generation embeddable financial components

Method Opal is the single embeddable UI component that provides enhanced
financial connectivity and user experience. Opal serves as a modern replacement
for Method Elements, offering improved performance, better customization, and
advanced features for integrating Method's API into your application.

<img alt="title" />

## What is Opal?

Method's embedded financial platform, with built-in orchestration of
identity, account connection, verification, and transaction streaming- all
in one cohesive experience for end-users.

## Using Method Opal

<Steps>
  <Step title="Create an Entity">
    Create an entity for your user using the
    [Entities](/reference/entities/overview) endpoint.
  </Step>

  <Step title="Create Opal Token">
    Generate an Opal Token by using the [Create Token](/reference/opal/create_token#create-token)
    endpoint.
  </Step>

  <Step title="Launch Opal">
    Using the Opal Token, launch Opal with one of our
    [libraries](/opal/libraries) to launch the intended Opal component for your
    user. Method will handle the rest!
  </Step>

  <Step title="Optional: Handle Opal Events">
    While your user interacts with an Opal component,
    [events](/opal/events) will be triggered for your app to handle.
  </Step>
</Steps>

## Opal Modes

Opal provides several pre-built modes for different use cases:

### [Identity Verification](/opal/identity/overview)

Collect and verify user identity only.

### [Connect](/opal/connect/overview)

Connect user liability accounts.

### [Card Connect](/opal/card_connect/overview)

Verify and connect cards for access to payments.

### [Account Verification](/opal/account_verification/overview)

Verify account ownership with real-time verification.

### [Transactions](/opal/transactions/overview)

Stream transactions for a user's credit cards.

## Understanding Modes and Flows

Opal Modes are typically made up of one or more flows. Modes are the different types of Opal components that can be launched, while flows are the different stages within a mode. For example, the Card Connect mode has a flow for identity verification (`identity_verification`), account selection (`connect`), and verification (`account_verification`).

## Getting Started

Ready to integrate Opal into your application? Start with our [Opal Libraries](/opal/libraries) to choose the right SDK for your platform!

<CardGroup>
  <Card title="Opal Libraries" href="/opal/libraries">
    Choose the right SDK for your platform
  </Card>

  <Card title="API Reference" href="/reference/opal/overview">
    Complete API documentation for Opal endpoints
  </Card>

  <Card title="Events Guide" href="/opal/events">
    Learn how to handle Opal events in your application
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.methodfi.com/opal/quickstart

Get started with Method Opal in minutes

This quickstart guide will help you integrate Method Opal into your application in just a few steps. Opal provides enhanced performance, better security, and advanced features compared to Elements.

## Prerequisites

Before you begin, make sure you have:

* A Method account with API access
* Your Method API key
* A web application or development environment

## Step 1: Install the Opal SDK

Choose the appropriate SDK for your application:

<CodeGroup>
  ```html JavaScript (CDN) theme={null}
  <script src="https://static.methodfi.com/opal/v1/stable/init.js"></script>
  ```

  ```bash React theme={null}
  npm install @methodfi/opal-react
  ```

  ```bash React Native theme={null}
  npm install @methodfi/opal-react-native
  ```
</CodeGroup>

## Step 2: Create an Entity

First, create an entity for your user:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "individual",
      "individual": {
        "first_name": "John",
        "last_name": "Doe",
        "phone": "+15121234567",
        "email": "john.doe@example.com"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const entity = await method.entities.create({
    type: "individual",
    individual: {
      first_name: "John",
      last_name: "Doe",
      phone: "+15121234567",
      email: "john.doe@example.com",
    },
  });
  ```

  ```python Python theme={null}
  entity = method.entities.create({
    'type': 'individual',
    'individual': {
      'first_name': 'John',
      'last_name': 'Doe',
      'phone': '+15121234567',
      'email': 'john.doe@example.com'
    }
  })
  ```
</CodeGroup>

## Step 3: Create an Opal Token

Create an Opal token for the Connect component:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/opal/token \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "entity_id": "ent_fc92i43kc34",
      "mode": "connect",
      "connect": {
        "selection_type": "single",
        "account_filters": {
          "include": {
            "account_types": ["credit_card", "auto_loan"]
          }
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const { token, valid_until, session_id } = await method.opal.token.create({
    entity_id: entity.id,
    mode: "connect",
    connect: {
      selection_type: "single",
      account_filters: {
        include: {
          account_types: ["credit_card", "auto_loan"],
        },
      },
    },
  });
  ```

  ```python Python theme={null}
  res = method.opal.token.create({
    'entity_id': entity.id,
    'mode': 'connect',
    'connect': {
      'selection_type': 'single',
      'account_filters': {
        'include': {
          'account_types': ['credit_card', 'auto_loan']
        }
      }
    }
  })
  ```
</CodeGroup>

## Step 4: Initialize Opal in Your Frontend

<CodeGroup>
  ```html JavaScript (CDN) theme={null}
  <script src="https://static.methodfi.com/opal/v1/stable/init.js"></script>

  <button id="connect-button">Connect Your Account</button>

  <script>
    document
      .getElementById("connect-button")
      .addEventListener("click", async () => {
        // Get token from Method
        const response = await fetch(`${baseURL}/opal/token`, {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({
            entity_id: "ent_fc92i43kc34",
            mode: "connect",
            connect: {
              selection_type: "single",
              account_filters: {
                include: {
                  account_types: ["credit_card", "auto_loan"],
                },
              },
            },
          }),
        });
        const { token } = await response.json();

        // Open iframe with token
        const iframe = document.createElement("iframe");
        iframe.src = `https://opal.${env}$.methodfi.com?token=${token}`;
        iframe.style.width = "100%";
        iframe.style.height = "600px";
        iframe.style.border = "none";
        document.body.appendChild(iframe);
      });
  </script>
  ```

  ```jsx React theme={null}
  import { OpalProvider, useOpal } from "@methodfi/opal-react";

  function App() {
    return (
      <OpalProvider>
        <ConnectButton />
      </OpalProvider>
    );
  }

  function ConnectButton() {
    const { open } = useOpal();

    const handleConnect = async () => {
      // Get token from Method
      const response = await fetch(`${baseURL}/opal/token`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          entity_id: "ent_fc92i43kc34",
          mode: "connect",
          connect: {
            selection_type: "single",
            account_filters: {
              include: {
                account_types: ["credit_card", "auto_loan"],
              },
            },
          },
        }),
      });
      const { token } = await response.json();

      // Launch Opal
      open({ token });
    };

    return <button onClick={handleConnect}>Connect Your Account</button>;
  }
  ```

  ```jsx React Native theme={null}
  import { OpalProvider, useOpal } from "@methodfi/opal-react-native";
  import { Button } from "react-native";

  function App() {
    return (
      <OpalProvider>
        <ConnectButton />
      </OpalProvider>
    );
  }

  function ConnectButton() {
    const { open } = useOpal();

    const handleConnect = async () => {
      // Get token from Method
      const response = await fetch(`${baseURL}/opal/token`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          entity_id: "ent_fc92i43kc34",
          mode: "connect",
          connect: {
            selection_type: "single",
            account_filters: {
              include: {
                account_types: ["credit_card", "auto_loan"],
              },
            },
          },
        }),
      });
      const { token } = await response.json();

      // Launch Opal
      open({ token });
    };

    return <Button title="Connect Your Account" onPress={handleConnect} />;
  }
  ```
</CodeGroup>

## Next Steps

Now that you have Opal working, explore these advanced features:

<CardGroup>
  <Card title="Advanced Configuration" href="/opal/connect/overview">
    Learn about advanced Opal Connect features and configuration options
  </Card>

  <Card title="Event Handling" href="/opal/events">
    Master Opal's comprehensive event system
  </Card>

  <Card title="Migration Guide" href="/opal/migration_guide">
    Migrate from Elements to Opal
  </Card>
</CardGroup>

### Getting Help

* **Documentation**: [Complete Opal Documentation](/opal/overview)
* **API Reference**: [Opal API Reference](/reference/opal/overview)
* **Support**: Contact your Method CSM


# Sessions
Source: https://docs.methodfi.com/opal/sessions

Maintain state and user data across Opal interactions.

Opal Sessions are long-lived stateful connections between your app and Opal.
They allow you to store user data, resume user sessions, and retrieve data later.
Sessions are created when you create an Opal Token, and when passed into Opal,
they are automatically resumed.

## Creating a new session

First, create a new Opal Token with your desired configuration. This will create a new session.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/opal/token \
    -X POST \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "mode": "card_connect",
      "entity_id": "ent_fc92i43kc34",
      "card_connect": {
        "selection_type": "single"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "token": "otkn_THpBacqVBBrDkfqUf9htjm4QWAEJLY9a",
      "valid_until": "2025-05-08T22:21:40.312Z",
      "session_id": "osess_zde3mW34pEHqV"
    },
    "message": null
  }
  ```
</ResponseExample>

## Resuming an existing session

To resume an existing session, create a new token by passing the `session_id` from a previous session

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/opal/token \
    -X POST \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "session_id": "osess_zde3mW34pEHqV"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "token": "otkn_THpBacqVBBrDkfqUf9htjm4QWAEJLY9a",
      "valid_until": "2025-05-08T22:21:40.312Z",
      "session_id": "osess_zde3mW34pEHqV"
    },
    "message": null
  }
  ```
</ResponseExample>


# Transactions
Source: https://docs.methodfi.com/opal/transactions/overview



<Note>Mode: `transactions`</Note>

Opal Transactions is the primary way to obtain consent and subscribe to real-time transactions.
This pre-built flow gathers a user's consent, verifies their identity, and prompts them to select the accounts eligible to be subscribed to.

<img alt="transactions-hero" />

## What this mode does

Transactions will provide a seamless experience for a user to subscribe to real-time transaction updates for supported accounts.
Eligible accounts will be automatically determined by Method, including your team's eligibility criteria.

For details on how to receive transaction updates via [Webhooks](/reference/webhooks/create). Make sure you are subscribed to the relevant webhook events to receive real-time transaction data. Note that you will only receive updates for events that occur after your subscription is active.

Please reach out to your CSM to enable access to this mode!

## Create a token

You can create a transactions token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `transactions`
* Create new entity: provide `entity` + `mode` + `transactions`

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "transactions",
  "transactions": {}
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {}
  },
  "mode": "transactions",
  "transactions": {}
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "session_id": "osess_...",
  "valid_until": "2025-06-10T22:50:53.024Z"
}
```

## Resuming a session

Want to link more cards? In this mode, simply create another token with the same `entity_id` and Method will intelligently pick up where your user left off. They won't ever be asked to link a card twice!

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({
        env: "dev",
        onEvent: (e) => {},
        onExit: (e) => {},
      });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Link Transactions</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({
        env: "dev",
        onEvent: (e) => {},
        onExit: (e) => {},
      });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Link Transactions" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>


# Card Brand
Source: https://docs.methodfi.com/guides/additional-products/card-brand

Card product names, visual card art, and card details for trust and engagement.

For credit card accounts, Method can retrieve the specific card product name, visual card art, and structured card details, including APRs, fees, rewards, and promotional offers. Instead of displaying a generic "Visa credit card" line item, your product can show "Chase Sapphire Reserve" with the actual card image and card details.

<Frame>
  <img alt="Card Brand enrichment" />
</Frame>

This seemingly small detail has an outsized impact on user trust and engagement. When users see their actual card names and artwork in your product, it signals accuracy and builds confidence that the data is real and current.

<Warning>
  Card Brand is available only to partners processing payments using the PaymentInstrument endpoint. Contact your Method CSM for more information.
</Warning>

## How It Works

Card Brand is available as a Product (on-demand) or Subscription (continuous updates). Create a Card Brand request for a credit card account, and Method returns a `brands` array containing:

* **name:** The card product name (e.g., "Chase Sapphire Reserve")
* **network:** The card network (e.g., `visa`, `mastercard`)
* **network\_tier:** The network tier (e.g., `infinite`, `signature`)
* **url:** A hosted URL for the card art image
* **type:** Brand match quality: `specific` (exact match with card art), `generic` (general metadata, no specific FI offering), or `in_review` (undergoing verification)
* **details:** Structured card details: `card_category`, purchase & cash-advance APRs, annual & late fees, `rewards` (type, program, and earn categories), and `promotions` (with the sign-up bonus). Available on version `2025-07-04` and later; see the [Card Brand reference](/reference/accounts/card-brands/overview).

The `source` field on the response indicates where the data came from (`method` or `network`).

## Quick Start

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/card_brands \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const cardBrand = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .cardBrands
    .create();
  ```

  ```python Python theme={null}
  card_brand = method
    .accounts('acc_yVf3mkzbhz9tj')
    .card_brands
    .create()
  ```
</CodeGroup>

## Supported Cards

Card Brand is available for credit card accounts on Visa and Mastercard networks. Requesting Card Brand for a non-credit-card account or an unsupported network returns a `PRODUCT_UNAVAILABLE` error.

## Error Handling

* `PRODUCT_UNAVAILABLE`: Account isn't a credit card, or the network isn't Visa/Mastercard.
* `TEAM_CAPABILITY_RESTRICTED`: Your team doesn't have access to Card Brand.
* `CARD_BRANDS_NOT_FOUND`: The card's brand could not be found or doesn't exist.

<Card title="Card Brand API Reference" icon="credit-card" href="/reference/accounts/card-brands/overview">
  Full API documentation for Card Brand.
</Card>


# Credit Scores
Source: https://docs.methodfi.com/guides/additional-products/credit-scores

Credit score retrieval and monitoring for financial wellness products.

For financial wellness products, few data points are as universally understood and valued as the credit score. Method can retrieve credit scores for verified Entities, giving your product the ability to show users their score, track changes over time, and alert them to increases or decreases.

## How It Works

Credit Scores are available as a Product (on-demand) or Subscription (continuous updates via webhooks). Requests are asynchronous: you'll get an immediate response with `status: "pending"` and `scores: null`, then a webhook when the score is ready.

The response includes a `scores` array. Each score object contains:

* **score:** The numeric credit score
* **source:** The credit bureau (`equifax`, `experian`, or `transunion`)
* **model:** The scoring model (`vantage_3` for VantageScore 3.0 or `vantage_4` for VantageScore 4.0)
* **factors:** An array of factor objects (each with `code` and `description`) explaining what's influencing the score, e.g., "Total of all balances on bankcard or revolving accounts is too high"

## Quick Start

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/credit_scores \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const creditScore = await method
    .entities('ent_au22b1fbFJbp8')
    .creditScores
    .create();
  ```

  ```python Python theme={null}
  credit_score = method
    .entities('ent_au22b1fbFJbp8')
    .credit_scores
    .create()
  ```
</CodeGroup>

## Subscriptions

Scores can be retrieved on-demand (pull the current score when the user opens your app) or monitored via subscriptions (get notified automatically when the score changes). Webhook events (`credit_score.create`, `credit_score.update`, `credit_score.available`) tell you when a score becomes available or changes, enabling features like "Your credit score went up 12 points this month!" notifications that drive engagement and retention.

## Prerequisites

The Entity must be fully verified before you can request credit scores. Attempting to request scores for an unverified Entity returns an `ENTITY_VERIFICATION_MISSING` error.

## Error Handling

Request errors:

* `ENTITY_VERIFICATION_MISSING`: Entity must be fully verified first.
* `TEAM_CAPABILITY_RESTRICTED`: Your team doesn't have access to Credit Scores.

Resource errors (set on the Credit Score's `error` property):

* `CREDIT_SCORE_FAILED_TEMPORARILY_UNAVAILABLE`: Issue with the credit score provider, request could not be completed.

<Card title="Credit Scores API Reference" icon="chart-line" href="/reference/entities/credit-scores/overview">
  Full API documentation for Credit Scores.
</Card>


# Sensitive
Source: https://docs.methodfi.com/guides/additional-products/sensitive

Gated access to full account numbers and sensitive account data.

Sensitive is a specially gated product that provides access to full account numbers and other sensitive account data. This is not enabled by default; access requires explicit approval from Method.

<Warning>
  Sensitive data requires explicit enablement for your team. Access may require additional review, agreements, and approval from Method. Not all accounts or account types support Sensitive data retrieval.
</Warning>

## How It Works

Unlike most Method products, Sensitive requests are *synchronous*. You'll get the data back immediately in the response.

When creating a Sensitive request, you must specify an `expand` array indicating which fields you want. Available fields depend on the account's liability type:

**Credit Cards:**

* `credit_card.number`: Full card number (PAN)
* `credit_card.exp_month`: Expiration month
* `credit_card.exp_year`: Expiration year
* `credit_card.cvv`: Card CVV
* `credit_card.billing_zip_code`: Billing zip code

**All other liability types** (auto loan, mortgage, personal loan, collection, student loans, credit builder, BNPL, fintech, loan):

* `{type}.number`: Full account number (e.g., `auto_loan.number`, `mortgage.number`)

## Supported Account Types

Sensitive supports: credit card, auto loan, mortgage, personal loan, collection, student loans, credit builder, BNPL, fintech, and loan accounts.

## Quick Start

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/accounts/acc_yVf3mkzbhz9tj/sensitive \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "expand": [
        "credit_card.number",
        "credit_card.exp_month",
        "credit_card.exp_year",
        "credit_card.cvv"
      ]
    }'
  ```

  ```javascript Node.js theme={null}
  const sensitive = await method
    .accounts('acc_yVf3mkzbhz9tj')
    .sensitive
    .create({
      expand: [
        'credit_card.number',
        'credit_card.exp_month',
        'credit_card.exp_year',
        'credit_card.cvv'
      ],
    });
  ```

  ```python Python theme={null}
  sensitive = method
    .accounts('acc_yVf3mkzbhz9tj')
    .sensitive
    .create({
      'expand': [
        'credit_card.number',
        'credit_card.exp_month',
        'credit_card.exp_year',
        'credit_card.cvv'
      ]
    })
  ```
</CodeGroup>

## Security Requirements

If your use case requires full account numbers (for example, to initiate payments through external systems or to populate forms on behalf of users), you'll need to request Sensitive access from Method. If approved, you're expected to follow strict security practices:

* Apply the principle of least privilege, only request sensitive data when needed
* Store secrets and sensitive data securely using encryption at rest and in transit
* Maintain audit logging on your side for all access to sensitive data
* PCI compliance is required

<Card title="Sensitive API Reference" icon="lock" href="/reference/accounts/sensitive/overview">
  Full API documentation for Sensitive.
</Card>


# Vehicles
Source: https://docs.methodfi.com/guides/additional-products/vehicles

Auto loan enrichment with VIN, make, model, and vehicle details.

For applications that deal with auto loans, whether that's auto refinancing, insurance, fleet management, or vehicle valuation, Method can enrich an Entity's profile with detailed vehicle information.

## How It Works

Vehicles is an Entity-level product: you request it against an Entity, not an individual Account. This means a single request returns all vehicles associated with that person. The response is synchronous, you'll get the data back immediately.

The `vehicles` array in the response contains one object per vehicle, each with:

* **vin:** Vehicle Identification Number
* **year:** Make year (e.g., "2021")
* **make:** Manufacturer (e.g., "honda")
* **model:** Model (e.g., "accord")
* **series:** Series/Trim/Category (e.g., "lx", "ex"), may be `null`
* **major\_color:** Primary color (e.g., "black")
* **style:** Body style (e.g., "sedan/saloon", "crew\_pickup", "sport\_utility\_vehicle")

This transforms an abstract "auto loan" line item into a concrete vehicle identity. Instead of showing "Auto Loan: \$18,450 balance," your product can display "2022 Honda Civic LX: \$18,450 remaining." This enrichment dramatically improves the user experience and enables vehicle-specific features like valuation estimates, equity calculations, and insurance comparisons.

## Quick Start

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/vehicles \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const vehicles = await method
    .entities('ent_au22b1fbFJbp8')
    .vehicles
    .create();
  ```

  ```python Python theme={null}
  vehicles = method
    .entities('ent_au22b1fbFJbp8')
    .vehicles
    .create()
  ```
</CodeGroup>

## Multiple Vehicles

An Entity can have multiple vehicles. The response `vehicles` array will contain all of them. This is useful for presenting a vehicle selector in your UI or for fleet management use cases.

<Card title="Vehicles API Reference" icon="car" href="/reference/entities/vehicles/overview">
  Full API documentation for Vehicles.
</Card>


# Payment Errors and Constraints
Source: https://docs.methodfi.com/guides/payments/errors

Processing windows, posting timing, return codes, and idempotency.

## Payment Errors and Constraints

* Payments submitted outside of processing windows will be held until the next window.
* Posting timing depends on the creditor and is outside Method's control.
* Return codes may be provided when a payment fails or is returned.
* Duplicate payments can be prevented using [idempotency keys](/reference/idempotency).


# Payment Instruments
Source: https://docs.methodfi.com/guides/payments/instruments

Reusable payment configurations for recurring and repeated payments.

## Payment Instruments — Reusable Payment Configurations

For products that involve recurring or repeated payments (e.g., a monthly debt paydown plan), Payment Instruments provide a convenience layer. Instead of collecting and submitting payment details for every transaction, you create a Payment Instrument once, capturing the card credentials, ACH details, or network token, and reference it for subsequent payments.

Think of a Payment Instrument as a saved payment method. The user sets it up once, and your product can initiate payments against it repeatedly without re-collecting credentials. Instruments remain valid until explicitly closed or the underlying account changes.

Method supports three types of Payment Instruments:

| Type                 | Description                                                         |
| -------------------- | ------------------------------------------------------------------- |
| **Card**             | Card credentials for payment                                        |
| **Inbound ACH/Wire** | Routing and account details for ACH or wire payments to a liability |
| **Network Token**    | Tokenized card credentials for secure, network-level transactions   |

<Note>
  Not all accounts support all instrument types, check the account's available products before attempting to create an instrument. And listen for webhook events about instrument status changes, as instruments may become invalid if the underlying account is closed or credentials expire.
</Note>

For the full Payments API, see the [Payments reference](/reference/payments/overview). For Payment Instruments, see the [Payment Instruments reference](/reference/accounts/payment-instruments/overview).


# Getting Started
Source: https://docs.methodfi.com/guides/use-cases/commerce/getting-started

Create an entity, verify identity, and connect credit cards — the foundational 3-step flow for every commerce integration.

Every commerce integration begins the same way: represent your customer, verify their identity, and discover their credit cards. This 3-step flow is the shared foundation for [Wallet Onboarding](/guides/use-cases/commerce/wallet-onboarding), [Preauth Signals](/guides/use-cases/commerce/preauth-signals), and [Wallet Intelligence](/guides/use-cases/commerce/wallet-intelligence).

<Steps>
  <Step title="Create an Entity">
    Every end user maps to an [Entity](/guides/entities/overview) in Method. Create one with the user's full name and phone number, and provide additional identity information such as date of birth, email address, or SSN when available to improve match rates. This is the foundational object that verification, card discovery, and all downstream products attach to.

    ```bash theme={null}
    curl https://production.methodfi.com/entities \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "individual",
        "individual": {
          "first_name": "Emily",
          "last_name": "Park",
          "phone": "+13105550789",
          "email": "emily.park@email.com",
          "dob": "1995-11-08"
        },
        "address": {
          "line1": "789 Sunset Blvd",
          "line2": null,
          "city": "Los Angeles",
          "state": "CA",
          "zip": "90028"
        }
      }'
    ```

    ```json theme={null}
    {
      "id": "ent_BzirqpLEm3BW7",
      "type": "individual",
      "individual": {
        "first_name": "Emily",
        "last_name": "Park",
        "phone": "+13105550789",
        "dob": "1995-11-08",
        "email": "emily.park@email.com",
        "ssn_4": null,
        "ssn": null
      },
      "error": null,
      "address": {
        "line1": "789 Sunset Blvd",
        "line2": null,
        "city": "Los Angeles",
        "state": "CA",
        "zip": "90028"
      },
      "status": "incomplete",
      "verification": {
        "identity": {
          "verified": false,
          "matched": false,
          "latest_verification_session": null,
          "methods": [
            "element",
            "kba"
          ]
        },
        "phone": {
          "verified": false,
          "latest_verification_session": null,
          "methods": [
            "sms",
            "sna",
            "byo_sms"
          ]
        }
      },
      "connect": null,
      "credit_score": null,
      "products": [
        "identity"
      ],
      "restricted_products": [
        "connect",
        "credit_score",
        "attribute"
      ],
      "subscriptions": [],
      "available_subscriptions": [
        "connect",
        "credit_score"
      ],
      "restricted_subscriptions": [],
      "metadata": null,
      "created_at": "2025-12-10T14:22:31.024Z",
      "updated_at": "2025-12-10T14:22:31.024Z"
    }
    ```

    The Entity is created in `incomplete` status. Before you can discover Emily's credit cards, you need to verify her identity.
  </Step>

  <Step title="Verify Identity">
    Method requires phone verification before card discovery. Verify the customer's phone number using either **Method OTP** (Method sends and verifies the one-time passcode) or **Bring Your Own OTP** (you verify the phone number yourself and provide the verification result to Method). The example below initiates a Method-sent SMS verification session, which sends a one-time code to Emily's phone number on record.

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/verification_sessions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "sms",
        "sms": {}
      }'
    ```

    ```json theme={null}
    {
      "id": "evf_nKLp7WzQdR4mF",
      "entity_id": "ent_BzirqpLEm3BW7",
      "status": "in_progress",
      "type": "phone",
      "method": "sms",
      "sms": {},
      "error": null,
      "created_at": "2025-12-10T14:23:12.271Z",
      "updated_at": "2025-12-10T14:23:12.271Z"
    }
    ```

    After Emily receives and submits the SMS code, the verification session transitions to `verified`. Once both phone and identity verification are complete, the Entity status updates to `active` and Connect becomes available.

    <Note>
      For a complete overview of all verification methods (SMS, SNA, BYO-SMS, KBA), see the [Identity Verification](/guides/identity-verification/overview) guide.
    </Note>
  </Step>

  <Step title="Connect Credit Cards">
    With verification complete, call Connect to discover Emily's credit cards via a soft-pull credit report. This has no impact on the user's credit score.

    For commerce use cases, the key discovery is **credit cards**: these are the accounts you'll use for wallet onboarding, preauth signals, and wallet intelligence.

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    ```json theme={null}
    {
      "id": "cxn_7hTmRvXkYpN3w",
      "entity_id": "ent_BzirqpLEm3BW7",
      "status": "completed",
      "accounts": [
        "acc_LxwEqNicr66yP",
        "acc_4m9amk4KFiaQX",
        "acc_XtKTpHLGhD9Qn",
        "acc_GAzrD99cUqGEN"
      ],
      "requested_products": [],
      "requested_subscriptions": [],
      "error": null,
      "created_at": "2025-12-10T14:24:45.645Z",
      "updated_at": "2025-12-10T14:24:45.645Z"
    }
    ```

    Method discovered 4 credit card accounts for Emily:

    | Account ID          | Card                            |
    | ------------------- | ------------------------------- |
    | `acc_LxwEqNicr66yP` | Chase Sapphire Preferred (Visa) |
    | `acc_4m9amk4KFiaQX` | Amex Gold (Amex)                |
    | `acc_XtKTpHLGhD9Qn` | Citi Double Cash (Mastercard)   |
    | `acc_GAzrD99cUqGEN` | Capital One Venture X (Visa)    |

    These accounts are now ready for every Commerce use case.
  </Step>
</Steps>

## What's Next

<CardGroup>
  <Card title="Wallet Onboarding" icon="wallet" href="/guides/use-cases/commerce/wallet-onboarding">
    Enrich cards with brand art and retrieve payment credentials to render a complete wallet.
  </Card>

  <Card title="Preauth Signals" icon="signal" href="/guides/use-cases/commerce/preauth-signals">
    Evaluate payment readiness before authorization and optimize payment retries.
  </Card>

  <Card title="Wallet Intelligence" icon="lightbulb" href="/guides/use-cases/commerce/wallet-intelligence">
    Retrieve wallet-level insights to personalize customer experiences.
  </Card>
</CardGroup>


# Commerce
Source: https://docs.methodfi.com/guides/use-cases/commerce/overview

Connect customers' credit cards, reduce failed payments, and personalize customer experiences with Method's Commerce APIs.

## What This Section Covers

Learn how to use Method's Commerce APIs to:

* **Connect every credit card** a customer owns in a single flow.
* **Evaluate payment readiness** before authorizing a transaction.
* **Retry failed payments at the optimal time** to improve recovery.
* **Personalize customer experiences** using wallet intelligence.

Whether you're building a wallet, improving payment success, or personalizing customer experiences, every Commerce integration follows the same core workflow.

```mermaid theme={null}
flowchart TD
    A[Create Entity] --> B[Verify Identity]
    B --> C[Connect Credit Cards]
    C --> D[Wallet Onboarding]
    C --> E[Preauth Signals]
    C --> F[Wallet Intelligence]
    style C fill:#00B29D,color:#fff
```

## Commerce Use Cases

| Use case                                                                  | Core endpoints                                  | Use when you want to                                                                                                           |
| ------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| [**Wallet Onboarding**](/guides/use-cases/commerce/wallet-onboarding)     | Entity-Connect, Card Brand, Payment Instruments | Reduce onboarding friction by letting customers connect all their credit cards in one flow                                     |
| [**Preauth Signals**](/guides/use-cases/commerce/preauth-signals)         | Entity-Connect, Preauth Signals                 | Increase payment success by evaluating payment readiness before authorization and retrying failed payments at the optimal time |
| [**Wallet Intelligence**](/guides/use-cases/commerce/wallet-intelligence) | Entity-Connect, Attributes                      | Personalize offers and product experiences based on customers' credit cards                                                    |

## Two Integration Paths

<Tabs>
  <Tab title="API-Only">
    Integrate directly with Method's APIs for entity creation, identity verification, Connect, and all downstream card operations. You build the user-facing flow and have full control over the UX.

    PCI compliance is not required: by default, tokenization returns network tokens that don't expose raw card credentials.
  </Tab>

  <Tab title="Embedded UI (Opal)">
    Use [Opal Card Connect](/opal/card_connect/overview) as a drop-in UI for identity verification and card discovery. Opal handles the user-facing flow while you use the API for card brand enrichment, payment instruments, and wallet attributes.
  </Tab>
</Tabs>

## Get Started

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="/guides/use-cases/commerce/getting-started">
    The 3-step setup: create an entity, verify identity, and connect credit cards.
  </Card>

  <Card title="Wallet Onboarding" icon="wallet" href="/guides/use-cases/commerce/wallet-onboarding">
    Connect every credit card without manual entry, then enrich and tokenize for checkout.
  </Card>

  <Card title="Preauth Signals" icon="signal" href="/guides/use-cases/commerce/preauth-signals">
    Evaluate payment readiness before authorization and optimize payment retries.
  </Card>

  <Card title="Wallet Intelligence" icon="lightbulb" href="/guides/use-cases/commerce/wallet-intelligence">
    Retrieve wallet-level insights to personalize customer experiences.
  </Card>
</CardGroup>


# Preauth Signals
Source: https://docs.methodfi.com/guides/use-cases/commerce/preauth-signals

Evaluate payment readiness before authorization and retry failed payments at the optimal time.

Evaluate payment readiness before authorization and optimize payment retries. After your customer has connected their credit cards, evaluate each card before attempting a payment. Method returns behavioral signals used to estimate payment readiness and recommends when to retry failed payments.

<Note>
  **Public preview.** Preauth Signals is in public preview. Contact your Method CSM to request access.
</Note>

## Prerequisites

Before using Preauth Signals, complete the [Getting Started](/guides/use-cases/commerce/getting-started) flow:

* Entity created
* Identity verified
* Credit cards connected

## Why Use It?

* **Reduce involuntary churn:** Identify the best time to retry failed payments.
* **Increase authorization rates:** Know a payment's likelihood of success before sending it to the network.

## How It Works

Before attempting a payment, create a Preauth Signals assessment for the card, then retrieve the result to decide whether to authorize now or retry later.

```mermaid theme={null}
flowchart TD
    A["Create Preauth Signals<br/>POST /preauth"] --> B["Retrieve Preauth Signals<br/>GET /preauth/{preauth_id}"]
    B --> C[Authorize now]
    B --> D[Retry later]
    style C fill:#00B29D,color:#fff
```

<Steps>
  <Step title="Create Preauth Signals">
    Create a Preauth Signals assessment with `POST /preauth`. Provide either an authenticated Method `account_id` or a `card` object to identify the payment method. You can also include `purchase` context, such as the transaction amount or merchant category code (MCC), to improve the assessment.

    ```bash theme={null}
    curl https://production.methodfi.com/preauth \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "account_id": "acc_4m9amk4KFiaQX",
        "purchase": {
          "amount": 9999,
          "mcc": "4511"
        }
      }'
    ```
  </Step>

  <Step title="Retrieve Preauth Signals">
    Retrieve the completed assessment with `GET /preauth/{preauth_id}` to determine whether to authorize the payment immediately or retry later.

    ```bash theme={null}
    curl https://production.methodfi.com/preauth/preauth_qV7kRaFm4JNxw \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    ```json theme={null}
    {
      "id": "preauth_qV7kRaFm4JNxw",
      "account_id": "acc_4m9amk4KFiaQX",
      "status": "completed",
      "verified_ownership": "match",
      "card_standing": "open",
      "success_likelihood": 0.87,
      "optimal_retry_date": "2026-06-02",
      "error": null,
      "metadata": null,
      "created_at": "2026-05-28T14:00:00.000Z",
      "updated_at": "2026-05-28T14:00:00.180Z"
    }
    ```

    | Field                | Description                                               |
    | -------------------- | --------------------------------------------------------- |
    | `success_likelihood` | Estimated likelihood that the payment will authorize.     |
    | `optimal_retry_date` | Recommended retry date if the payment does not authorize. |

    Use `success_likelihood` to choose the best card for a payment, and `optimal_retry_date` to schedule retries for failed payments.
  </Step>
</Steps>

## What's Next

<CardGroup>
  <Card title="Wallet Intelligence" icon="lightbulb" href="/guides/use-cases/commerce/wallet-intelligence">
    Retrieve wallet-level insights to personalize customer experiences.
  </Card>

  <Card title="Preauth Signals API Reference" icon="signal" href="/reference/preauth/overview">
    Full API documentation for Preauth Signals.
  </Card>
</CardGroup>


# Wallet Intelligence
Source: https://docs.methodfi.com/guides/use-cases/commerce/wallet-intelligence

Retrieve wallet-level behavioral attributes to power recommendations, segmentation, and personalized product experiences.

Retrieve wallet-level insights to personalize customer experiences. After connecting a customer's credit cards, retrieve wallet-level behavioral attributes to power recommendations, segmentation, and personalized product experiences.

## Prerequisites

Before using Wallet Intelligence, complete the [Getting Started](/guides/use-cases/commerce/getting-started) flow:

* Entity created
* Identity verified
* Credit cards connected

## Why Use It?

* **Reach the right audience:** Identify the customers most likely to benefit from every offer.
* **Power partner offers:** Deliver issuer and partner offers only to eligible customers.
* **Design better experiences:** Understand wallet trends and customer behavior to inform product decisions.
* **Complete customer profiles:** Enrich the customer data you already have.

## How It Works

Retrieve the attributes of the customer's wallet with a single request: `POST /entities/{ent_id}/attributes`. Method returns behavioral attributes computed across every connected credit card in the customer's wallet, including:

* Overall utilization
* Credit card utilization
* Usage patterns
* Payment behavior
* Balance trends

```bash theme={null}
curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/attributes \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

This endpoint is asynchronous. The initial response returns `status: in_progress`. Retrieve the completed attributes by subscribing to the `entity_attribute.create` webhook or polling the [retrieve endpoint](/reference/entities/attributes/retrieve).

Below is an example of a completed response:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "attr_dADraNgLBrhgL",
    "entity_id": "ent_BzirqpLEm3BW7",
    "status": "completed",
    "attributes": {
      "usage_pattern":           { "value": "transactor", "error": null, "metadata": null },
      "credit_card_utilization": { "value": 11.96, "error": null, "metadata": null },
      "overall_utilization":     { "value": 18.4, "error": null, "metadata": null }
    },
    "error": null,
    "created_at": "2026-04-09T17:02:47.910Z",
    "updated_at": "2026-04-09T17:04:35.220Z"
  }
}
```

Each attribute returns `{ value, error }`. When data is insufficient (for example, not enough history for a 60-day delta), `value` is `null` and `error` is populated with details.

Use these attributes to build better experiences, personalize offers, segment customers, and improve targeting.

## What's Next

<CardGroup>
  <Card title="Attributes API Reference" icon="chart-line" href="/reference/entities/attributes/overview">
    Full API documentation for Entity Attributes.
  </Card>

  <Card title="Wallet Onboarding" icon="wallet" href="/guides/use-cases/commerce/wallet-onboarding">
    Connect every credit card without manual entry.
  </Card>
</CardGroup>


# Wallet Onboarding
Source: https://docs.methodfi.com/guides/use-cases/commerce/wallet-onboarding

Connect every credit card a customer owns without manual entry, then enrich and tokenize the cards to render a complete wallet.

Connect every credit card without manual entry. Using a customer's name and phone number, Method discovers the credit cards they own, verifies ownership, and returns the metadata needed to render a complete wallet.

## Why Use It?

* **Faster onboarding:** Connect every credit card in one simple and seamless flow.
* **Frictionless checkout:** Let customers pay instantly with any of their credit cards, with no manual entry.
* **Rewards activation:** Enable customers to connect all their credit cards and start earning rewards across every eligible purchase.
* **Payment resilience:** Keep multiple credit cards on file to automatically recover failed payments and reduce churn.

## How It Works

```mermaid theme={null}
flowchart TD
    A["Create Entity<br/>POST /entities"] --> B["Verify Identity<br/>POST /verification_sessions"]
    B --> C["Discover Credit Cards<br/>POST /connect"]
    C --> D["Enrich Cards<br/>POST /card_brands"]
    D --> E["Retrieve Payment Cards<br/>POST /payment_instruments"]
    E --> F[Complete Wallet]
    style F fill:#00B29D,color:#fff
```

<Steps>
  <Step title="Create an Entity">
    Create an [Entity](/guides/entities/overview) to represent your customer. Include their full name and phone number, and provide additional identity information such as date of birth, email address, or SSN when available to improve match rates.
  </Step>

  <Step title="Verify the Customer's Identity">
    Verify the customer's phone number using either **Method OTP** (Method sends and verifies the one-time passcode) or **Bring Your Own OTP** (you verify the phone number yourself and provide the verification result to Method). See the [Identity Verification](/guides/identity-verification/overview) guide for all supported methods.
  </Step>

  <Step title="Discover the Customer's Credit Cards">
    Call [Connect](/guides/connect/overview) to discover the credit card accounts your customer holds via a soft-pull credit report, with no impact on their credit score.

    <Note>
      Steps 1-3 are the same foundational flow used by every Commerce use case. See [Getting Started](/guides/use-cases/commerce/getting-started) for full request and response examples.
    </Note>
  </Step>

  <Step title="Enrich the Discovered Cards">
    For each account returned by Connect, call [Card Brand](/guides/additional-products/card-brand) to retrieve enriched card metadata, including the issuer, card network, card product, card artwork, and rewards program. Use this metadata to render your customer's wallet with recognizable card visuals.

    Here's a card brand request for Emily's Chase Sapphire Preferred (`acc_LxwEqNicr66yP`):

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_LxwEqNicr66yP/card_brands \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    ```json theme={null}
    {
      "id": "cbrd_Accm7P6t6mYQP",
      "account_id": "acc_LxwEqNicr66yP",
      "brands": [
        {
          "id": "pdt_27_brd_1",
          "card_product_id": "pdt_27",
          "description": "Chase Sapphire Preferred",
          "name": "Chase Sapphire Preferred",
          "issuer": "Chase",
          "network": "visa",
          "network_tier": "signature",
          "type": "specific",
          "url": "https://static.methodfi.com/card_brands/7d2f8a1bc3e5f094a6d831e5c7b29f04.png"
        }
      ],
      "status": "completed",
      "source": "method",
      "error": null,
      "created_at": "2025-12-10T14:30:12.139Z",
      "updated_at": "2025-12-10T14:30:12.139Z"
    }
    ```

    The `brands` array contains the card product details. Use `name` for display, `url` for the card art image, `issuer` for the bank name, and `network` / `network_tier` for routing decisions.

    <Note>
      Card Brand is an asynchronous operation. The response above shows a completed request; in practice, subscribe to the `card_brand.completed` webhook to know when brand data is ready.
    </Note>
  </Step>

  <Step title="Retrieve Available Payment Cards">
    For each account returned by Connect, create a [Payment Instrument](/reference/accounts/payment-instruments/overview) to retrieve the card credentials required for checkout.

    Request a `network_token` Payment Instrument to receive a network-provisioned token instead of the raw card number. No raw card credentials are exposed to your systems, so you don't need PCI compliance, and network tokens typically yield better authorization rates.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_GAzrD99cUqGEN/payment_instruments \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "network_token"
      }'
    ```

    If your processor requires raw card data, request a `card` Payment Instrument instead to receive the full credentials: number, expiration date, CVV, and billing zip code. This approach exposes PAN data to your systems and requires PCI compliance.

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_GAzrD99cUqGEN/payment_instruments \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "card"
      }'
    ```

    ```json theme={null}
    {
      "success": true,
      "data": {
        "id": "pmt_inst_pd788hPVhLT37",
        "account_id": "acc_GAzrD99cUqGEN",
        "type": "card",
        "card": {
          "number": "4000120000001154",
          "exp_month": "09",
          "exp_year": "2028",
          "cvv": "878",
          "billing_zip_code": "90028"
        },
        "network_token": null,
        "inbound_achwire_payment": null,
        "chargeable": true,
        "status": "completed",
        "error": null,
        "created_at": "2025-12-10T14:35:22.039Z",
        "updated_at": "2025-12-10T14:35:22.039Z"
      },
      "message": null
    }
    ```

    <Warning>
      Payment Instruments is a gated product that requires approval. Contact your Method representative to enable access.
    </Warning>
  </Step>
</Steps>

<Note>
  **Alternative path:** If you don't need complete control over the onboarding experience, [Opal](/opal/overview) provides an embedded flow that handles identity verification and card discovery for you.
</Note>

## What's Next

<CardGroup>
  <Card title="Preauth Signals" icon="signal" href="/guides/use-cases/commerce/preauth-signals">
    Evaluate payment readiness before authorizing a transaction.
  </Card>

  <Card title="Card Brand API Reference" icon="credit-card" href="/reference/accounts/card-brands/overview">
    Full API documentation for Card Brand.
  </Card>

  <Card title="Payment Instruments API Reference" icon="key" href="/reference/accounts/payment-instruments/overview">
    Full API documentation for Payment Instruments.
  </Card>
</CardGroup>


# Mortgage & HELOC
Source: https://docs.methodfi.com/guides/use-cases/lending/mortgage-heloc

Top-of-funnel qualification through portfolio targeting for secured-lending teams.

*Top-of-funnel qualification through portfolio targeting for secured-lending teams.*

Pull a borrower's full liability picture before pre-approval, size HELOC and refi offers against real-time balances and APRs, and continuously surface existing customers who are in the market for a HELOC or new mortgage. From nothing more than a name and phone, Method discovers every liability a borrower holds (mortgages, HELOCs, credit cards, auto, student, and personal loans), pulls current balances, APRs, and payment behavior directly from each financial institution, and keeps that picture refreshed after the borrower is in the book. The same data fabric powers two motions: origination (pre-qualification and HELOC/refi sizing) and portfolio intelligence (continuous monitoring to surface HELOC- and mortgage-ready customers before they shop elsewhere).

## How it works

Create the borrower Entity, verify them, run Connect to discover their liabilities, then subscribe to the v2 attribute set for a continuous, real-time view. All examples use `Method-Version: 2026-03-30`. Monetary values are in **cents** (`1420000` = \$14,200.00); utilization is a percentage (`37.4` = 37.4%); deltas are percentage points.

<Steps>
  <Step title="Create the Entity">
    `POST /entities`. You only need `first_name`, `last_name`, and `phone`. An Entity can be created minimally and enriched later; passing `dob` and `ssn_4` when you have them measurably improves match rates during account discovery, so include them in production where available. The Entity returns `status: "incomplete"` with `connect`, `credit_score`, and `attribute` in `restricted_products` until verification completes.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{
          "type": "individual",
          "individual": {
            "first_name": "Maya",
            "last_name": "Chen",
            "phone": "+13105550147"
          }
        }'
      ```

      ```json theme={null}
      {
        "id": "ent_BzirqpLEm3BW7",
        "type": "individual",
        "individual": {
          "first_name": "Maya",
          "last_name": "Chen",
          "phone": "+13105550147"
        },
        "status": "incomplete",
        "products": ["identity"],
        "restricted_products": ["connect", "credit_score", "attribute"],
        "available_subscriptions": ["connect", "credit_score"]
      }
      ```
    </Expandable>
  </Step>

  <Step title="Verify the borrower (BYO SMS + BYO KYC)">
    Verification must complete before Connect, credit, and attribute products unlock. The lending flows in these guides use BYO SMS and BYO KYC, which let you assert results you already captured in your own onboarding. Both require your team to be pre-authorized, so contact your Method CSM to enable them. For other verification methods, see [Verification Methods](/guides/identity-verification/methods). Once both sessions complete, the Entity moves to `status: "active"` and `connect`, `credit_score`, and `attribute` move from `restricted_products` into `products`. For the full walkthrough, see the [Getting Started](/guides/use-cases/lending/getting-started) guide.

    <Expandable title="phone and identity requests">
      Verify the phone with BYO SMS, passing the ISO 8601 timestamp of when you verified the number:

      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/verification_sessions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "type": "phone", "method": "byo_sms", "byo_sms": { "timestamp": "2026-03-30T12:00:00.000Z" } }'
      ```

      Then assert identity with BYO KYC (you're confirming your external KYC process passed for this borrower):

      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/verification_sessions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "type": "identity", "method": "byo_kyc", "byo_kyc": {} }'
      ```
    </Expandable>
  </Step>

  <Step title="Run Connect">
    `POST /entities/{ent_id}/connect`. Connect performs a soft credit pull (no score impact) and returns the account IDs Method created for each liability. The first Connect returns all liability accounts, both active and closed; subsequent calls return only newly discovered accounts.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/connect \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "cxn_4ewMmBbjYDMR4",
        "entity_id": "ent_BzirqpLEm3BW7",
        "status": "completed",
        "accounts": [
          "acc_RGACQH7XdfYhC",
          "acc_TmGPLxkz7Nrh6",
          "acc_WqNhMRNVZjbKg",
          "acc_YXDrjADGjC76U"
        ],
        "error": null
      }
      ```
    </Expandable>
  </Step>

  <Step title="List the discovered accounts">
    `GET /accounts`. Filter to `type=liability` and `status=active` to work with live debt only. Narrow with `liability.type` (e.g. `mortgage`, `credit_card`) to isolate the secured-debt picture that matters for a HELOC decision. For decision-time accuracy, pull a fresh `POST /accounts/{acc_id}/updates` on the accounts that drive the decision (balances on revolving and mortgage debt shift daily).

    <Expandable title="request & response">
      ```bash theme={null}
      curl "https://production.methodfi.com/accounts?holder_id=ent_BzirqpLEm3BW7&type=liability&status=active" \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "data": [
          {
            "id": "acc_RGACQH7XdfYhC",
            "holder_id": "ent_BzirqpLEm3BW7",
            "status": "active",
            "type": "liability",
            "liability": {
              "mch_id": "mch_300012",
              "mask": "8842",
              "ownership": "primary",
              "type": "mortgage",
              "name": "Rocket Mortgage Home Loan"
            },
            "products": ["balance", "update"],
            "restricted_products": ["attribute", "sensitive"]
          },
          {
            "id": "acc_WqNhMRNVZjbKg",
            "holder_id": "ent_BzirqpLEm3BW7",
            "status": "active",
            "type": "liability",
            "liability": {
              "mch_id": "mch_302086",
              "mask": "1580",
              "ownership": "primary",
              "type": "credit_card",
              "name": "Chase Sapphire Reserve Credit Card"
            },
            "products": ["balance", "update", "card_brand"],
            "restricted_products": ["attribute", "sensitive"]
          }
        ]
      }
      ```
    </Expandable>
  </Step>

  <Step title="Enroll the entity in the attribute subscription">
    `POST /entities/{ent_id}/subscriptions` with `enroll: attribute`. Method computes credit-health attributes (utilization, balances, APRs, trends, payment behavior, delinquency flags) at both the entity level and the account level. Pass the `portfolio_intelligence` bundle to onboard the full PI attribute set in one call, plus any HELOC/mortgage-specific attributes you want explicitly. Once enrolled, every account on the entity is eligible for attribute generation; you do not enroll accounts individually. Portfolio Intelligence (`portfolio_intelligence`) is separately enabled, so ask your Method CSM to turn it on first.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{
          "enroll": "attribute",
          "payload": {
            "attributes": {
              "bundles": ["portfolio_intelligence"],
              "requested_attributes": [
                "mortgage_balance_total",
                "heloc_balance_total",
                "heloc_utilization",
                "overall_utilization",
                "revolving_credit_card_balance_total",
                "weighted_average_apr_credit_card",
                "delinquency_flag_credit_cards"
              ]
            }
          }
        }'
      ```

      ```json theme={null}
      {
        "id": "sub_Tm8qNnLx5RjWk",
        "name": "attribute",
        "status": "active",
        "latest_request_id": null,
        "created_at": "2026-04-09T17:00:12.218Z",
        "updated_at": "2026-04-09T17:00:12.218Z"
      }
      ```
    </Expandable>

    Once `status` is `active`, Method begins pulling directly from the borrower's institutions and attribute generation starts.
  </Step>

  <Step title="(Optional) Enroll accounts in Update subscriptions">
    `POST /accounts/{acc_id}/subscriptions` with `enroll: update`. Adds a near-real-time balance/payment event stream on a specific account, on top of the entity attribute layer, useful when you want a webhook the moment a tracked mortgage or card balance moves.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_WqNhMRNVZjbKg/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "update" }'
      ```
    </Expandable>
  </Step>

  <Step title="Pull the entity attribute set">
    `POST /entities/{ent_id}/attributes`. Asynchronous: it returns immediately with `status: "in_progress"` and `attributes: null`, then fires an `entity_attribute.create` webhook when computation completes. Retrieve the finished object via `GET /entities/{ent_id}/attributes/{attr_id}`. Attributes that can't be computed (e.g. a trend with insufficient history, or HELOC attributes for a borrower with no HELOC) return `value: null` with an `error` object rather than failing the whole response.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_BzirqpLEm3BW7/attributes \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "attr_Qk9nPmRw3LjTx",
        "entity_id": "ent_BzirqpLEm3BW7",
        "status": "completed",
        "attributes": {
          "mortgage_balance_total":               { "value": 31200000, "error": null, "metadata": null },
          "heloc_balance_total":                  { "value": 0, "error": null, "metadata": null },
          "heloc_utilization":                    { "value": null, "error": { "type": "ENTITY_ATTRIBUTE_INSUFFICIENT_DATA", "code": 27001, "message": "Insufficient data to compute this entity attribute." }, "metadata": null },
          "overall_utilization":                  { "value": 41.8, "error": null, "metadata": null },
          "revolving_credit_card_balance_total":  { "value": 1840000, "error": null, "metadata": null },
          "credit_card_utilization":              { "value": 63.0, "error": null, "metadata": null },
          "weighted_average_apr_credit_card":     { "value": 23.4, "error": null, "metadata": null },
          "usage_pattern":                        { "value": "revolver", "error": null, "metadata": null },
          "payment_to_minimum_ratio_avg_credit_cards": { "value": 1.6, "error": null, "metadata": null },
          "delinquency_flag_credit_cards":        { "value": "on_time", "error": null, "metadata": null }
        }
      }
      ```
    </Expandable>
  </Step>
</Steps>

**Webhooks.** A PI-enrolled entity fires `entity_attribute.create` on the first computation and `entity_attribute.update` thereafter whenever new values are surfaced; account-level signals fire `account_attribute.create` / `account_attribute.update`. Subscribe to these to drive monitoring workflows without polling.

A primer on the full attribute set, entity-vs-account availability, and webhook payloads lives in the [Portfolio Intelligence guide](/guides/use-cases/lending/portfolio-monitoring).

## Pre-qualification

Run the create-and-Connect flow at intake, then read the entity attribute set to qualify before the borrower invests in a full application. Because the data comes straight from each institution rather than a weeks-old bureau snapshot, the pre-approval decision rests on what the borrower actually owes today.

*Key attributes:* `overall_utilization`, `credit_card_utilization`, `usage_pattern`, `delinquency_flag_credit_cards`, `payment_to_minimum_ratio_avg_credit_cards`.

## HELOC expansion

For a HELOC offer, the secured picture and the borrower's revolving leverage drive both eligibility and sizing. Method surfaces the existing mortgage and HELOC balances directly, alongside the unsecured debt that informs capacity.

*Key attributes:* `mortgage_balance_total`, `heloc_balance_total`, `heloc_utilization`, `overall_utilization`, `revolving_credit_card_balance_total`.

## Debt consolidation / refi

A borrower carrying high-APR revolving balances is a consolidation candidate. Method shows the blended rate they're actually paying, so the savings you quote are priced against real debt, not an estimated rate band. The example borrower above carries \$18,400 in revolving balances at a 23.4% blended APR, a clear consolidation target a HELOC or refi will retire. When the borrower accepts, Direct Pay (the Payments API) routes the verified payoff straight to the incumbent creditor.

*Key attributes:* `weighted_average_apr_credit_card`, `revolving_credit_card_balance_total`, `credit_card_utilization`, `personal_loan_monthly_installments_estimate`.

## Portfolio Intelligence: HELOC / mortgage targeting

Enroll existing customers in the attribute subscription and let the continuous attribute stream surface who is in the market. Watch for the signals that indicate HELOC or new-mortgage intent (sustained revolving paydown that frees capacity, rising high-APR balances that a HELOC will consolidate, or an improving overall profile) and trigger a targeted offer before they shop a competitor.

*Key attributes:* `revolving_credit_card_balance_change_30d/60d/90d`, `overall_utilization_delta_90d`, `overall_utilization_trend_90d`, `weighted_average_apr_credit_card`, `mortgage_balance_total`.


# Portfolio Intelligence: Grow
Source: https://docs.methodfi.com/guides/use-cases/lending/portfolio-monitoring-grow

Post-origination monitoring for refi, 2nd loan, CLI, and cross-sell.

*Post-origination monitoring for refi, 2nd loan, CLI, cross-sell.*

After a loan funds, most lenders lose visibility into their borrowers. Method's Portfolio Intelligence monitors the full liability picture continuously after origination, surfacing 91 real-time signals across 8 categories, so growth, retention, risk, and servicing teams reach their best borrowers before competitors do.

## How it works

Funded loans are enrolled in Attributes v2 + Update + Credit Score Subscriptions, Method continuously monitors the borrower's full liability picture across 15,000+ institutions, improvement signals trigger CLI / 2nd-loan / refi workflows, and Direct Pay retires competitor balances when the borrower accepts.

<Steps>
  <Step title="Enroll the entity in the Attributes v2 subscription">
    `POST /entities/{ent_id}/subscriptions` with `enroll: attribute`. Pass the `portfolio_intelligence` bundle to onboard the full PI attribute set in one call. Every account on the entity then becomes eligible for attribute generation, and Method pushes recomputed values as the underlying data changes. Portfolio Intelligence (`portfolio_intelligence`) is a separately enabled product, so ask your Method CSM to turn it on first.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "attribute", "payload": { "attributes": { "bundles": ["portfolio_intelligence"] } } }'
      ```
    </Expandable>
  </Step>

  <Step title="Enroll the borrower's accounts in Update Subscriptions">
    `POST /accounts/{acc_id}/subscriptions` with `enroll: update`.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_TmGPLxkz7Nrh6/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "update" }'
      ```
    </Expandable>
  </Step>

  <Step title="Enroll the entity in Credit Score Subscriptions">
    `POST /entities/{ent_id}/subscriptions` with `enroll: credit_score`.

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "credit_score" }'
      ```
    </Expandable>
  </Step>
</Steps>

For Portfolio Intelligence: Grow workflows, the readiness, offer-targeting, consolidation, and LTV sub-flows below pull from this same v2 attribute set.

## Identify readiness

Score every borrower against their live liability picture: who's revolving, who's approaching payoff, who has a balance worth consolidating. Bureau snapshots are already weeks old at the moment of intent.

*Key v2 attributes:* `usage_pattern`, `overall_utilization`, `credit_card_utilization`, `revolving_credit_card_balance_total`, `revolving_credit_card_balance_change_30d`.

## Target with the right offer

Method surfaces APR ranges and live balances. Offers are priced against the rate the borrower is actually paying, not a bureau-estimated rate band.

*Key v2 attributes:* `weighted_average_apr_credit_card`, `revolving_credit_card_balance_total`, `next_payment_minimum_total_credit_cards`, `credit_limit_total`.

## Execute the consolidation

When the borrower accepts, Direct Pay routes a verified payoff directly to the incumbent issuer. Consolidated payoffs cut delinquency up to \~50% vs. cash-to-borrower disbursement.

*Driven by Direct Pay (Payments API) rather than the Attributes endpoint. See the [Direct Pay](/guides/use-cases/lending/debt-consolidation) use case for the payment-initiation flow.*

## Post-origination LTV: 2nd loan and CLI

\~33% of personal-loan customers take a second loan within 6 to 12 months. Continuous monitoring surfaces who's a renewal candidate, and detects when a borrower's external profile improves enough to support a proactive CLI before they shop competitors.

*Key v2 attributes:* `revolving_credit_card_balance_change_90d`, `overall_utilization_delta_90d`, `overall_utilization_trend_90d`, `revolving_credit_card_utilization_delta_90d`, `revolving_credit_card_utilization_trend_90d`.


# Portfolio Intelligence: Protect
Source: https://docs.methodfi.com/guides/use-cases/lending/portfolio-monitoring-protect

Early warning, line decreases, and real-time delinquency and autopay signals.

*Early warning, line decreases, real-time delinquency and autopay signals.*

Bureau won't tell you a borrower just turned off autopay, opened a balance transfer card, or stacked debt, until it's already on your balance sheet. Method catches all three weeks earlier, with direct evidence from the FI. Same data fabric as PI: Grow, applied to loss prevention.

## How it works

Same subscription setup as PI: Grow, with the attribute bundle tuned to distress signals. Distress events (autopay off, DPD progression, balance stacking) fire as webhooks; risk and servicing teams trigger early intervention.

<Steps>
  <Step title="Enroll funded-loan accounts in Update Subscriptions">
    Enroll with `enroll: update` (`POST /accounts/{acc_id}/subscriptions`).

    <Expandable title="request">
      ```bash theme={null}
      curl https://production.methodfi.com/accounts/acc_TmGPLxkz7Nrh6/subscriptions \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
        -H "Content-Type: application/json" \
        -d '{ "enroll": "update" }'
      ```
    </Expandable>
  </Step>

  <Step title="Pull the v2 attribute set tuned for distress signals">
    `POST /entities/{ent_id}/attributes`. Method computes the full set automatically. Consume the delinquency flags, the balance-change deltas, and the payment-to-minimum ratio for distress detection. For continuous monitoring, enroll in the Entity Attributes subscription (`entity_attribute.create` webhook); Method pushes recomputed attributes as the underlying account data changes.

    <Expandable title="request & response">
      ```bash theme={null}
      curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/attributes \
        -X POST \
        -H "Method-Version: 2026-03-30" \
        -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
      ```

      ```json theme={null}
      {
        "id": "attr_dADraNgLBrhgL",
        "entity_id": "ent_qKNBB68bfHGNA",
        "status": "completed",
        "attributes": {
          "delinquency_flag_credit_cards":              { "value": "overdue", "error": null, "metadata": null },
          "any_delinquent_flag":                        { "value": true, "error": null, "metadata": null },
          "serious_delinquent_flag":                    { "value": false, "error": null, "metadata": null },
          "delinquency_worst_dpd_bucket":               { "value": "30_dpd", "error": null, "metadata": null },
          "delinquency_accounts_count":                 { "value": 2, "error": null, "metadata": null },
          "delinquent_balance_total":                   { "value": 41200, "error": null, "metadata": { "partial": true, "accounts_with_data": 1, "accounts_total": 2 } },
          "delinquency_progression_flag":               { "value": true, "error": null, "metadata": null },
          "delinquency_recently_cured_flag":            { "value": false, "error": null, "metadata": null },
          "delinquent_outcome":                         { "value": "current", "error": null, "metadata": null },
          "payment_to_minimum_ratio_avg_credit_cards":  { "value": 0.85, "error": null, "metadata": null },
          "revolving_credit_card_balance_change_30d":   { "value": 381700, "error": null, "metadata": null },
          "revolving_credit_card_utilization_delta_30d":{ "value": 8.4, "error": null, "metadata": null },
          "revolving_credit_card_utilization_trend_30d":{ "value": "increasing", "error": null, "metadata": null },
          "credit_card_utilization":                    { "value": 74.2, "error": null, "metadata": null },
          "installment_balance_change_30d":             { "value": 250000, "error": null, "metadata": null }
        }
      }
      ```
    </Expandable>
  </Step>
</Steps>

## Early delinquency detection

Flag delinquency progression weeks before bureau refresh; act on early-cure or workout opportunities while the borrower still has capacity.

*Key v2 attributes:* `delinquency_flag_credit_cards`, `any_delinquent_flag`, `serious_delinquent_flag`, `delinquency_worst_dpd_bucket`, `delinquency_progression_flag`, `delinquent_outcome`, `delinquency_recently_cured_flag`, `delinquency_accounts_count`, `delinquent_balance_total`, `payment_to_minimum_ratio_avg_credit_cards`, `next_payment_minimum_total_credit_cards`.

## Payment-behavior leading indicators

A declining payment-to-minimum ratio flags borrowers before the first missed payment. (Autopay-specific signals such as autopay disablement detection and autopay-enabled counts surface through Account Updates and account-level attributes rather than entity attributes today.)

*Key v2 attributes:* `payment_to_minimum_ratio_avg_credit_cards`.

## Line decreases on stress signals

Detect borrower distress: utilization spikes, balance stacking, rising aggregate utilization. Act on lines before losses materialize.

*Key v2 attributes:* `revolving_credit_card_balance_change_30d`, `revolving_credit_card_utilization_delta_30d`, `revolving_credit_card_utilization_trend_30d`, `credit_card_utilization`, `overall_utilization_delta_30d`.

## Debt stacking and settlement detection

Surface borrowers taking on new debt across institutions before bureau catches up. Use change-over-time attributes across credit cards and installment accounts to detect stacking patterns through the cross-account view.

*Key v2 attributes:* `delinquency_flag_credit_cards`, `installment_balance_change_30d`, `installment_balance_change_60d`, `revolving_credit_card_balance_change_30d`, `revolving_credit_card_balance_change_60d`.


# Getting Started
Source: https://docs.methodfi.com/guides/use-cases/pfm/getting-started

The universal 3-step flow for PFM integrations: create an entity, verify identity, and connect liabilities.

Every PFM integration begins with the same three steps: represent your user as an Entity, verify their identity, and discover their liabilities through Connect. Once these steps are complete, every product in Method's platform becomes available.

This guide walks through the full API flow using a single user, Sarah Chen, whose data threads through the rest of the PFM guides.

<Steps>
  <Step title="Create an Entity">
    An [Entity](/guides/entities/overview) is Method's representation of your end user. You provide their PII, and Method creates a persistent identity that everything else — verification, accounts, payments — attaches to.

    ```bash theme={null}
    curl https://production.methodfi.com/entities \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "individual",
        "individual": {
          "first_name": "Sarah",
          "last_name": "Chen",
          "phone": "+14155550123",
          "email": "sarah.chen@email.com",
          "dob": "1992-07-15"
        },
        "address": {
          "line1": "123 Main St",
          "line2": null,
          "city": "San Francisco",
          "state": "CA",
          "zip": "94102"
        }
      }'
    ```

    The Entity is created with `status: "incomplete"` because identity verification hasn't happened yet. Products like Connect and Credit Scores remain in `restricted_products` until verification is complete.

    ```json theme={null}
    {
      "id": "ent_au22b1fbFJbp8",
      "type": "individual",
      "individual": {
        "first_name": "Sarah",
        "last_name": "Chen",
        "phone": "+14155550123",
        "dob": "1992-07-15",
        "email": "sarah.chen@email.com",
        "ssn_4": null,
        "ssn": null
      },
      "error": null,
      "address": {
        "line1": "123 Main St",
        "line2": null,
        "city": "San Francisco",
        "state": "CA",
        "zip": "94102"
      },
      "status": "incomplete",
      "verification": {
        "identity": {
          "verified": false,
          "matched": false,
          "latest_verification_session": null,
          "methods": [
            "element",
            "kba"
          ]
        },
        "phone": {
          "verified": false,
          "latest_verification_session": null,
          "methods": [
            "sms",
            "sna"
          ]
        }
      },
      "connect": null,
      "credit_score": null,
      "products": [
        "identity"
      ],
      "restricted_products": [
        "connect",
        "credit_score",
        "attribute"
      ],
      "subscriptions": [],
      "available_subscriptions": [
        "connect",
        "credit_score"
      ],
      "restricted_subscriptions": [],
      "metadata": null,
      "created_at": "2025-09-15T14:30:00.000Z",
      "updated_at": "2025-09-15T14:30:00.000Z"
    }
    ```
  </Step>

  <Step title="Verify the User">
    Before Method can discover Sarah's accounts, she must complete [identity verification](/guides/identity-verification/overview). This is a two-part process: first confirming she controls her phone number, then verifying her identity.

    ### Phone Verification (SMS)

    Start by verifying Sarah's phone number. This sends an SMS code to `+14155550123`.

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/verification_sessions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "phone",
        "method": "sms",
        "sms": {}
      }'
    ```

    ```json theme={null}
    {
      "id": "evf_3VT3bHTCnPbrm",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "in_progress",
      "type": "phone",
      "method": "sms",
      "sms": {},
      "error": null,
      "created_at": "2025-09-15T14:31:00.000Z",
      "updated_at": "2025-09-15T14:31:00.000Z"
    }
    ```

    After the user provides the SMS code and completes identity verification (via [KBA](/reference/entities/verification-sessions/create-kba) or [Opal](/guides/opal)), the Entity transitions to `status: "active"` and products are unlocked.

    <Note>
      **Recommended: Use [Opal](/guides/opal)** for identity verification. Opal is Method's pre-built, white-labeled UI that handles both phone verification and identity verification in a single drop-in component. Most teams start here.
    </Note>

    ### After Verification

    Once verified, the Entity's `products` array expands and `restricted_products` clears:

    ```json theme={null}
    {
      "id": "ent_au22b1fbFJbp8",
      "status": "active",
      "verification": {
        "identity": {
          "verified": true,
          "matched": true,
          "latest_verification_session": "evf_9kR2fGhLmNpQ4",
          "methods": []
        },
        "phone": {
          "verified": true,
          "latest_verification_session": "evf_3VT3bHTCnPbrm",
          "methods": []
        }
      },
      "products": [
        "identity",
        "connect",
        "credit_score",
        "attribute"
      ],
      "restricted_products": [],
      "available_subscriptions": [
        "connect",
        "credit_score"
      ],
      "restricted_subscriptions": []
    }
    ```
  </Step>

  <Step title="Connect Liabilities">
    With Sarah verified, you can now discover her complete liability picture using [Connect](/guides/connect/overview). This performs a soft-pull credit report (no impact to her credit score) and returns all discovered accounts.

    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/connect \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```

    Connect discovers all of Sarah's open liabilities and returns them as account IDs:

    ```json theme={null}
    {
      "id": "cxn_iYGhvTRDnE4y7",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "completed",
      "accounts": [
        "acc_eKKmrXDpJBKgw",
        "acc_GV8WbmJW7KGRy",
        "acc_MLPKh9gQDDbT8",
        "acc_LbXE8wVYJLrKt",
        "acc_J3P9fayDFjpAy",
        "acc_eFFRV9zmpLREK"
      ],
      "requested_products": [],
      "requested_subscriptions": [],
      "error": null,
      "created_at": "2025-09-15T14:35:00.000Z",
      "updated_at": "2025-09-15T14:35:00.000Z"
    }
    ```

    ### What Was Discovered

    Each account ID maps to a liability that Method found on Sarah's credit report. You can retrieve any account to see its details:

    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    ```json theme={null}
    {
      "id": "acc_eKKmrXDpJBKgw",
      "holder_id": "ent_au22b1fbFJbp8",
      "type": "liability",
      "liability": {
        "mch_id": "mch_302086",
        "type": "credit_card",
        "name": "Chase Sapphire Reserve"
      },
      "status": "active",
      "products": [
        "update",
        "payment",
        "card_brand",
        "transaction"
      ],
      "created_at": "2025-09-15T14:35:00.000Z",
      "updated_at": "2025-09-15T14:35:00.000Z"
    }
    ```

    Here's what Sarah's full liability picture looks like:

    | Account ID          | Creditor               | Type          |
    | ------------------- | ---------------------- | ------------- |
    | `acc_eKKmrXDpJBKgw` | Chase Sapphire Reserve | Credit Card   |
    | `acc_GV8WbmJW7KGRy` | Citi Double Cash       | Credit Card   |
    | `acc_MLPKh9gQDDbT8` | Capital One            | Auto Loan     |
    | `acc_LbXE8wVYJLrKt` | Navient                | Student Loan  |
    | `acc_J3P9fayDFjpAy` | SoFi                   | Personal Loan |
    | `acc_eFFRV9zmpLREK` | Wells Fargo            | Mortgage      |
  </Step>
</Steps>

## What's Next

With Sarah's entity created, verified, and her liabilities discovered, you're ready to build the core PFM experience. Each of the following guides picks up where this setup leaves off.

<CardGroup>
  <Card title="Onboarding & Discovery" icon="magnifying-glass" href="/guides/use-cases/pfm/onboarding-discovery">
    Deep dive into identity verification options, connect subscriptions for ongoing discovery, and vehicle enrichment for auto loans.
  </Card>

  <Card title="Dashboard & Insights" icon="chart-mixed" href="/guides/use-cases/pfm/monitoring-insights">
    Pull real-time balances, credit scores, card brand art, and entity-level financial health attributes.
  </Card>

  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Stream credit card transactions and initiate bill payments to your users' creditors.
  </Card>
</CardGroup>


# Debt Dashboard & Credit Insights
Source: https://docs.methodfi.com/guides/use-cases/pfm/monitoring-insights

Build real-time debt dashboards with account updates, card brand art, credit scores, and financial health attributes.

Once a user's liabilities are connected, the next step is turning that raw data into a useful dashboard. This guide covers pulling real-time account data, enriching cards with brand art, monitoring balances over time, and surfacing credit health insights.

All examples use Sarah Chen's accounts from the [Getting Started](/guides/use-cases/pfm/getting-started) guide.

## Debt Dashboard & Real-Time Monitoring

### Requesting an Account Update

[Updates](/guides/updates/overview) pull real-time data — balance, credit limit, APR, due dates, payment history — directly from the financial institution. This is the core data feed for any debt dashboard.

Request an update for Sarah's Chase Sapphire Reserve card:

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/updates \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "upt_NYV5kfjskTTCJ",
      "status": "completed",
      "account_id": "acc_eKKmrXDpJBKgw",
      "source": "direct",
      "type": "credit_card",
      "credit_card": {
        "available_credit": 1920000,
        "balance": 80000,
        "closed_at": null,
        "credit_limit": 2000000,
        "interest_rate_percentage_max": 22.49,
        "interest_rate_percentage_min": 22.49,
        "interest_rate_type": "variable",
        "last_payment_amount": 15000,
        "last_payment_date": "2025-08-28",
        "next_payment_due_date": "2025-10-01",
        "next_payment_minimum_amount": 2500,
        "opened_at": "2022-03-15",
        "sub_type": "flexible_spending",
        "usage_pattern": "transactor"
      },
      "data_as_of": "2025-09-15T14:45:00.000Z",
      "error": null,
      "created_at": "2025-09-15T14:45:00.000Z",
      "updated_at": "2025-09-15T14:45:00.312Z"
    }
    ```
  </Tab>
</Tabs>

Sarah's Chase card has an \$800.00 balance on a \$20,000.00 limit (4% utilization), with a minimum payment of \$25.00 due on October 1st. Her last payment of \$150.00 was made on August 28th, and her `usage_pattern` is `transactor` — she pays in full each month.

### Subscribing to Continuous Updates

Rather than polling for updates, subscribe to receive them automatically. When the financial institution reports new data, Method delivers it via webhook.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/subscriptions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "enroll": "update"
      }'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "sub_xM4VcfRWcJP8D",
      "name": "update",
      "status": "active",
      "payload": null,
      "latest_request_id": "upt_NYV5kfjskTTCJ",
      "created_at": "2025-09-15T15:10:00.000Z",
      "updated_at": "2025-09-15T15:10:00.000Z"
    }
    ```
  </Tab>
</Tabs>

With the subscription active, Method will fire `update.create` and `update.update` webhook events whenever new data is available. Your app can refresh the dashboard in real time without the user taking any action.

### Card Brand Art

For credit card accounts, [Card Brand](/guides/additional-products/card-brand) retrieves the card's product name, issuer, network, and card art image. This lets your wallet UI display the actual card visual instead of a generic placeholder.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/card_brands \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "cbrd_Accm7P6t6mYQP",
      "account_id": "acc_eKKmrXDpJBKgw",
      "brands": [
        {
          "id": "pdt_15_brd_1",
          "card_product_id": "pdt_15",
          "description": "Chase Sapphire Reserve",
          "name": "Chase Sapphire Reserve",
          "issuer": "Chase",
          "network": "visa",
          "network_tier": "infinite",
          "type": "specific",
          "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
        }
      ],
      "status": "completed",
      "source": "method",
      "error": null,
      "created_at": "2025-09-15T15:15:00.000Z",
      "updated_at": "2025-09-15T15:15:00.000Z"
    }
    ```
  </Tab>
</Tabs>

The `url` field provides a direct link to the card's art image, which you can render in your wallet or dashboard UI.

### Entity-Level Attributes

[Attributes](/guides/additional-products/attributes) provide entity-level financial health metrics aggregated across all of a user's accounts. These power features like credit health dashboards, utilization alerts, and financial wellness scores.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/attributes \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    <Note>
      Attribute requests are asynchronous and compute all available attributes automatically. The initial response will have `status: "in_progress"` and `attributes: null`. You'll receive a webhook when the attributes are ready.
    </Note>
  </Tab>

  <Tab title="Response (completed)">
    ```json theme={null}
    {
      "id": "attr_nrPjaahMX4yRA",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "completed",
      "attributes": {
        "revolving_credit_card_balance_total": {
          "value": 550000,
          "error": null,
          "metadata": null
        },
        "credit_limit_total": {
          "value": 2500000,
          "error": null,
          "metadata": null
        },
        "credit_card_utilization": {
          "value": 22.0,
          "error": null,
          "metadata": null
        },
        "weighted_average_apr_credit_card": {
          "value": 21.24,
          "error": null,
          "metadata": null
        },
        "usage_pattern": {
          "value": "transactor",
          "error": null,
          "metadata": null
        },
        "overall_utilization": {
          "value": 22.0,
          "error": null,
          "metadata": null
        }
      },
      "error": null,
      "created_at": "2025-09-15T15:20:00.000Z",
      "updated_at": "2025-09-15T15:20:30.000Z"
    }
    ```
  </Tab>
</Tabs>

Sarah's attributes show 22% aggregate credit card utilization ($5,500.00 in revolving balances against $25,000.00 in combined limits), a weighted average card APR of 21.24%, and a `transactor` usage pattern (she pays in full each month). These data points map directly to the factors that credit scoring models weigh most heavily. Each attribute is returned as an object with `value`, `error`, and `metadata` fields; if an attribute cannot be computed, `value` is `null` and `error` explains why.

***

## Credit Building & Score Insights

### Retrieving Credit Scores

[Credit Scores](/guides/additional-products/credit-scores) retrieve the user's credit score sourced from Equifax using the VantageScore 4.0 model. The response includes contributing factors that explain what's helping or hurting the score.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/credit_scores \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```

    <Note>
      Credit score requests are asynchronous. The initial response will have `status: "pending"` and `scores: null`. You'll receive a webhook when the score is ready.
    </Note>
  </Tab>

  <Tab title="Response (completed)">
    ```json theme={null}
    {
      "id": "crs_pn4ca33GXFaCE",
      "entity_id": "ent_au22b1fbFJbp8",
      "status": "completed",
      "scores": [
        {
          "score": 734,
          "source": "equifax",
          "model": "vantage_4",
          "factors": [
            "Length of time accounts have been established",
            "Too few accounts currently paid as agreed",
            "Lack of recent installment loan information",
            "Proportion of balances to credit limits is too high on bank revolving or other revolving accounts"
          ],
          "created_at": "2025-09-15T15:25:00.000Z"
        }
      ],
      "error": null,
      "created_at": "2025-09-15T15:25:00.000Z",
      "updated_at": "2025-09-15T15:25:30.000Z"
    }
    ```
  </Tab>
</Tabs>

Sarah's VantageScore 4.0 is 734 ("Good" tier). The factors array explains what's influencing her score — you can surface these directly in your app to help users understand what actions would improve their score.

### Credit Score Subscriptions

To monitor Sarah's credit score over time, enroll her in a credit score subscription. Method will automatically check for score changes and send webhook events when her score increases or decreases.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/subscriptions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "enroll": "credit_score"
      }'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "sub_c3a7hVjHCJzF3",
      "name": "credit_score",
      "status": "active",
      "payload": null,
      "latest_request_id": null,
      "created_at": "2025-09-15T15:30:00.000Z",
      "updated_at": "2025-09-15T15:30:00.000Z"
    }
    ```
  </Tab>
</Tabs>

With the subscription active, your app can power features like monthly score reports, trend charts, and push notifications ("Your credit score went up 12 points this month!") that drive engagement and retention.

### Combining Scores and Attributes

The most effective credit building experiences combine credit scores with attributes. The score tells users *where they stand*, while attributes tell them *why* and *what to do about it*:

| Attribute                             | Sarah's Value | What to Surface                                                             |
| ------------------------------------- | ------------- | --------------------------------------------------------------------------- |
| `credit_card_utilization`             | 22%           | "Your utilization is healthy. Keep it under 30%"                            |
| `usage_pattern`                       | `transactor`  | "You pay your cards in full each month. Keep it up!"                        |
| `weighted_average_apr_credit_card`    | 21.24%        | "Your average card APR is 21.24%. A balance transfer could reduce interest" |
| `revolving_credit_card_balance_total` | \$5,500.00    | "Your total card balances across all accounts"                              |

<Card title="Attributes API Reference" icon="chart-bar" href="/reference/entities/attributes/create">
  Full documentation for all available attribute types and their value, error, and metadata fields.
</Card>

## What's Next

<CardGroup>
  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Stream credit card transactions for spend management and initiate bill payments.
  </Card>

  <Card title="Update Subscriptions Guide" icon="rotate" href="/guides/updates/subscriptions">
    Deep dive into update subscription types, frequencies, and webhook payloads.
  </Card>
</CardGroup>


# Onboarding & Liability Discovery
Source: https://docs.methodfi.com/guides/use-cases/pfm/onboarding-discovery

Identity verification options, liability discovery via Connect, ongoing connect subscriptions, and vehicle enrichment for auto loans.

This guide covers the onboarding layer of a PFM integration: how users get verified, how their liabilities are discovered, how to detect new liabilities over time, and how to enrich auto loan accounts with vehicle details.

If you haven't completed the [Getting Started](/guides/use-cases/pfm/getting-started) steps (creating and verifying Sarah Chen's Entity, and running Connect), start there first.

## Identity Verification with Opal

[Opal](/guides/opal) is Method's pre-built, white-labeled UI component that handles the entire verification flow — phone verification and identity verification — in a single drop-in experience. It's the fastest path to getting users verified and is recommended for most integrations.

<Tabs>
  <Tab title="Opal (Recommended)">
    Opal handles phone verification (SMS or SNA) and identity verification (KBA) in a single embedded flow. Your user completes the process in your app, and you receive a webhook when verification is complete.

    **Advantages:**

    * Minimal frontend development
    * Tested, optimized UX for conversion
    * Handles edge cases (retries, fallbacks, error states)
    * White-labeled to match your brand

    <Card title="Opal Integration Guide" icon="window" href="/guides/opal">
      Full guide for embedding Opal in your application.
    </Card>
  </Tab>

  <Tab title="BYO Identity Verification">
    If you have an existing identity verification flow or need complete control over the UX, you can use Method's API directly. This involves separate calls for [phone verification](/reference/entities/verification-sessions/create-sms) and [identity verification](/reference/entities/verification-sessions/create-kba).

    **When to use BYO:**

    * You already have a KYC/IDV provider and want to pass results to Method
    * Your UX requires a custom verification flow
    * You need to integrate verification into an existing onboarding funnel

    <Card title="Identity Verification Methods" icon="shield-check" href="/guides/identity-verification/methods">
      All available verification methods and when to use each.
    </Card>
  </Tab>
</Tabs>

## Liability Discovery via Connect

Once Sarah is verified, [Connect](/guides/connect/overview) performs a soft-pull credit report to discover her liabilities. The [Getting Started](/guides/use-cases/pfm/getting-started) guide showed the Connect call that discovered all 6 of her accounts.

Here's what Connect found for Sarah:

| Account ID          | Creditor               | Type          | What Your App Shows            |
| ------------------- | ---------------------- | ------------- | ------------------------------ |
| `acc_eKKmrXDpJBKgw` | Chase Sapphire Reserve | Credit Card   | Card balance, APR, due date    |
| `acc_GV8WbmJW7KGRy` | Citi Double Cash       | Credit Card   | Card balance, APR, due date    |
| `acc_MLPKh9gQDDbT8` | Capital One            | Auto Loan     | Loan balance, payment schedule |
| `acc_LbXE8wVYJLrKt` | Navient                | Student Loan  | Loan balance, disbursements    |
| `acc_J3P9fayDFjpAy` | SoFi                   | Personal Loan | Balance, term, rate            |
| `acc_eFFRV9zmpLREK` | Wells Fargo            | Mortgage      | Balance, rate, payoff date     |

<Note>
  Connect discovers both open and closed liabilities on the first call. Subsequent Connect calls for the same Entity only return newly opened accounts.
</Note>

## Connect Subscriptions

A user's liability picture changes over time — they open new credit cards, take out loans, or consolidate debt. Connect subscriptions automatically re-run discovery on a recurring basis and notify you via webhook when new accounts are found.

Enroll the Entity in a connect subscription:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "enroll": "connect"
  }'
```

```json theme={null}
{
  "id": "sub_Wm3FJkqV8hpDR",
  "name": "connect",
  "status": "active",
  "payload": null,
  "latest_request_id": null,
  "created_at": "2025-09-15T15:00:00.000Z",
  "updated_at": "2025-09-15T15:00:00.000Z"
}
```

When Method detects a new liability for Sarah, you'll receive a webhook event with the new Connect result containing the newly discovered account IDs. Your app can then automatically add these to her dashboard without any user action.

## Vehicle Enrichment

For auto loan accounts like Sarah's Capital One loan (`acc_MLPKh9gQDDbT8`), Method can retrieve the associated vehicle details — VIN, year, make, model, and style. This transforms a generic "Auto Loan: \$18,450 balance" into "2021 Honda CR-V EX: \$18,450 remaining."

Request vehicle data for Sarah's Entity:

```bash theme={null}
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/vehicles \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

```json theme={null}
{
  "id": "evhl_QnT4mKxBfVpJ8",
  "entity_id": "ent_au22b1fbFJbp8",
  "vehicles": [
    {
      "vin": "7FARW2H83ME012345",
      "year": "2021",
      "make": "honda",
      "model": "cr-v",
      "series": null,
      "major_color": "blue",
      "style": "sport_utility_vehicle"
    }
  ],
  "status": "completed",
  "error": null,
  "created_at": "2025-09-15T15:05:00.000Z",
  "updated_at": "2025-09-15T15:05:00.000Z"
}
```

With vehicle data, your PFM app can display rich auto loan details, enable equity calculations (comparing vehicle value against remaining balance), and power features like insurance comparison or refinancing recommendations.

<Card title="Vehicles API Reference" icon="car" href="/reference/entities/vehicles/create">
  Full API documentation for the Vehicles endpoint.
</Card>

## What's Next

<CardGroup>
  <Card title="Dashboard & Insights" icon="chart-mixed" href="/guides/use-cases/pfm/monitoring-insights">
    Pull real-time balances, credit scores, card brand art, and financial health attributes.
  </Card>

  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Stream credit card transactions and initiate bill payments.
  </Card>
</CardGroup>


# Digital Engagement & PFM
Source: https://docs.methodfi.com/guides/use-cases/pfm/overview

Build comprehensive personal financial management experiences with Method's liability data, credit insights, and payment infrastructure.

## What This Section Covers

Products and APIs that enable comprehensive personal financial management experiences — from discovering a user's complete debt picture to monitoring changes in real time, surfacing credit insights, and enabling bill pay directly from your app.

If you're building any product that helps consumers understand, manage, or pay down their financial obligations, this is where to start.

### Example Use Cases

* **Digital wallets** that display card balances, brand art, and recent transactions
* **Spend management apps** that categorize liability transactions and track spending patterns
* **Financial wellness platforms** that surface credit scores, debt-to-income insights, and payoff strategies
* **Neobanks** that embed bill pay and debt repayment into the core banking experience

## How Method Enables End-to-End PFM

Every PFM integration follows the same high-level journey: discover the user's liabilities, enrich them with real-time data, surface insights, and enable action.

| Stage        | What Happens                                                               | Method Products                                                                                                                           |
| ------------ | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Connect**  | Discover the user's complete liability picture via soft-pull credit report | [Entity](/guides/entities/overview), [Identity Verification](/guides/identity-verification/overview), [Connect](/guides/connect/overview) |
| **Data**     | Pull real-time balances, APRs, due dates, card art, and transactions       | [Updates](/guides/updates/overview), [Card Brand](/guides/additional-products/card-brand)                                                 |
| **Insights** | Surface credit scores, payment history, utilization, and attributes        | [Credit Scores](/guides/additional-products/credit-scores), [Attributes](/guides/additional-products/attributes)                          |
| **Pay**      | Initiate payments from your platform's funding account to users' creditors | [Payments](/guides/payments/overview)                                                                                                     |

## Get Started

<CardGroup>
  <Card title="Getting Started" icon="rocket" href="/guides/use-cases/pfm/getting-started">
    The universal 3-step setup: create an entity, verify identity, and connect liabilities.
  </Card>

  <Card title="Onboarding & Discovery" icon="magnifying-glass" href="/guides/use-cases/pfm/onboarding-discovery">
    Identity verification, liability discovery, connect subscriptions, and vehicle enrichment.
  </Card>

  <Card title="Dashboard & Insights" icon="chart-mixed" href="/guides/use-cases/pfm/monitoring-insights">
    Real-time balances, credit scores, card brands, and entity-level attributes.
  </Card>

  <Card title="Transactions & Payments" icon="money-bill-transfer" href="/guides/use-cases/pfm/transactions-payments">
    Transaction streaming, spend management, bill pay, and debt repayment.
  </Card>
</CardGroup>


# Transactions & Bill Pay
Source: https://docs.methodfi.com/guides/use-cases/pfm/transactions-payments

Stream credit card transactions for spend management and initiate bill payments to your users' creditors.

This guide covers the action layer of a PFM integration: streaming transaction data for spend management, and initiating payments from your platform's corporate funding account to pay down user liabilities.

All examples use Sarah Chen's accounts from the [Getting Started](/guides/use-cases/pfm/getting-started) guide.

## Transaction Stream & Spend Management

### Listing Transactions

Transactions provide transaction-level detail for connected Visa and Mastercard credit card accounts. Once subscribed, you can query historical transactions and receive new ones in real time via webhooks.

Retrieve recent transactions for Sarah's Chase Sapphire Reserve card:

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl "https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/transactions?from_date=2025-09-01&to_date=2025-09-15" \
      -X GET \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "data": [
        {
          "id": "txn_t73AdHRFYwhT9",
          "account_id": "acc_eKKmrXDpJBKgw",
          "status": "posted",
          "descriptor": "SQ *BLUE BOTTLE COFF",
          "merchant": {
            "name": "Blue Bottle Coffee",
            "logo": null
          },
          "merchant_category_code": "5814",
          "amount": 675,
          "auth_amount": 675,
          "currency_code": "USD",
          "transaction_amount": 675,
          "transaction_auth_amount": 675,
          "transaction_currency_code": "USD",
          "transacted_at": "2025-09-14T08:22:00.000Z",
          "posted_at": "2025-09-15T05:00:00.000Z",
          "voided_at": null,
          "original_txn_id": null,
          "created_at": "2025-09-14T08:22:00.000Z",
          "updated_at": "2025-09-15T05:00:00.000Z"
        },
        {
          "id": "txn_kP4mRvTnBcWx2",
          "account_id": "acc_eKKmrXDpJBKgw",
          "status": "posted",
          "descriptor": "WHOLE FOODS MKT #1042",
          "merchant": {
            "name": "Whole Foods Market",
            "logo": null
          },
          "merchant_category_code": "5411",
          "amount": 8743,
          "auth_amount": 8743,
          "currency_code": "USD",
          "transaction_amount": 8743,
          "transaction_auth_amount": 8743,
          "transaction_currency_code": "USD",
          "transacted_at": "2025-09-12T18:45:00.000Z",
          "posted_at": "2025-09-13T05:00:00.000Z",
          "voided_at": null,
          "original_txn_id": null,
          "created_at": "2025-09-12T18:45:00.000Z",
          "updated_at": "2025-09-13T05:00:00.000Z"
        },
        {
          "id": "txn_qN7jWvHmDfRa5",
          "account_id": "acc_eKKmrXDpJBKgw",
          "status": "posted",
          "descriptor": "SHELL OIL 57442",
          "merchant": {
            "name": "Shell",
            "logo": null
          },
          "merchant_category_code": "5541",
          "amount": 5218,
          "auth_amount": 5218,
          "currency_code": "USD",
          "transaction_amount": 5218,
          "transaction_auth_amount": 5218,
          "transaction_currency_code": "USD",
          "transacted_at": "2025-09-10T14:30:00.000Z",
          "posted_at": "2025-09-11T05:00:00.000Z",
          "voided_at": null,
          "original_txn_id": null,
          "created_at": "2025-09-10T14:30:00.000Z",
          "updated_at": "2025-09-11T05:00:00.000Z"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

Sarah's recent transactions show \$6.75 at Blue Bottle Coffee, \$87.43 at Whole Foods, and \$52.18 at Shell. All amounts are in cents. The `merchant_category_code` enables spend categorization (5814 = restaurants, 5411 = grocery, 5541 = gas stations).

### Subscribing to Transactions

Transaction data requires an active subscription. Enroll Sarah's Chase card to receive transaction events in real time:

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/subscriptions \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "enroll": "transaction"
      }'
    ```
  </Tab>

  <Tab title="Response">
    ```json theme={null}
    {
      "id": "sub_P8c4bjj6xajxF",
      "name": "transaction",
      "status": "active",
      "payload": null,
      "latest_request_id": null,
      "created_at": "2025-09-15T15:40:00.000Z",
      "updated_at": "2025-09-15T15:40:00.000Z"
    }
    ```
  </Tab>
</Tabs>

With the subscription active, Method fires webhook events for both authorization events (when Sarah swipes her card) and settlement events (when the transaction clears). This enables real-time spend alerts, budget tracking, and transaction feeds.

<Warning>
  Transaction streaming is available for Visa and Mastercard credit cards. Not all card accounts will support transactions — check the account's `products` array to confirm `transaction` is available.
</Warning>

***

## Bill Pay & Debt Repayment

### Getting a Fresh Balance Before Payment

Before initiating a payment, pull the latest balance to ensure accuracy. If you've already subscribed to updates (covered in the [Dashboard & Insights](/guides/use-cases/pfm/monitoring-insights) guide), you'll have recent data. Otherwise, request an on-demand update:

```bash theme={null}
curl https://production.methodfi.com/accounts/acc_eKKmrXDpJBKgw/updates \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
```

The completed update confirms Sarah's Chase card balance is \$800.00 (`80000` cents) with a minimum payment of \$25.00 due on October 1st. She decides to pay \$500.00 toward the balance.

### Creating a Payment

[Payments](/guides/payments/overview) move money from your platform's verified funding account (ACH) to a liability account. Your corporate funding account `acc_hmap9mbgfLcf9` serves as the payment source for all user payments.

<Tabs>
  <Tab title="Request">
    ```bash theme={null}
    curl https://production.methodfi.com/payments \
      -X POST \
      -H "Method-Version: 2026-03-30" \
      -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 50000,
        "source": "acc_hmap9mbgfLcf9",
        "destination": "acc_eKKmrXDpJBKgw",
        "description": "Chase Pmt"
      }'
    ```
  </Tab>

  <Tab title="Response (pending)">
    ```json theme={null}
    {
      "id": "pmt_VeCfmkwGKb",
      "source": "acc_hmap9mbgfLcf9",
      "destination": "acc_eKKmrXDpJBKgw",
      "amount": 50000,
      "description": "Chase Pmt",
      "status": "pending",
      "estimated_completion_date": "2025-09-18",
      "source_trace_id": null,
      "source_settlement_date": "2025-09-16",
      "source_status": "pending",
      "destination_trace_id": null,
      "destination_settlement_date": "2025-09-18",
      "destination_payment_method": "paper",
      "destination_status": "pending",
      "reversal_id": null,
      "error": null,
      "metadata": null,
      "created_at": "2025-09-15T16:00:00.000Z",
      "updated_at": "2025-09-15T16:00:00.000Z"
    }
    ```
  </Tab>
</Tabs>

The payment is created with `status: "pending"` and an estimated completion date of September 18th. The `description` field (max 10 characters) appears on the user's bank statement.

<Note>
  All amounts are in **cents**. `50000` = \$500.00. The `description` field has a maximum length of 10 characters.
</Note>

### Payment Lifecycle

Payments move through a lifecycle from creation to settlement. Track progress via webhook events:

Once the payment settles, the status transitions to `posted`:

```json theme={null}
{
  "id": "pmt_VeCfmkwGKb",
  "source": "acc_hmap9mbgfLcf9",
  "destination": "acc_eKKmrXDpJBKgw",
  "amount": 50000,
  "description": "Chase Pmt",
  "status": "posted",
  "estimated_completion_date": "2025-09-18",
  "source_trace_id": "203942084920",
  "source_settlement_date": "2025-09-16",
  "source_status": "posted",
  "destination_trace_id": "304820184832",
  "destination_settlement_date": "2025-09-18",
  "destination_payment_method": "paper",
  "destination_status": "posted",
  "reversal_id": null,
  "error": null,
  "metadata": null,
  "created_at": "2025-09-15T16:00:00.000Z",
  "updated_at": "2025-09-18T12:00:00.000Z"
}
```

## Putting It All Together

With transactions and payments, Sarah's PFM experience is complete:

| Capability         | Product                                                    | Example                                           |
| ------------------ | ---------------------------------------------------------- | ------------------------------------------------- |
| View all debts     | [Connect](/guides/connect/overview)                        | 6 liabilities discovered automatically            |
| Real-time balances | [Updates](/guides/updates/overview)                        | Chase card: \$800.00 balance, \$25.00 minimum due |
| Card visuals       | [Card Brand](/guides/additional-products/card-brand)       | Chase Sapphire Reserve card art                   |
| Credit score       | [Credit Scores](/guides/additional-products/credit-scores) | VantageScore 4.0: 734                             |
| Financial health   | [Attributes](/guides/additional-products/attributes)       | 22% utilization, 100% payment history             |
| Spending activity  | Transactions                                               | Coffee, groceries, gas — categorized in real time |
| Bill pay           | [Payments](/guides/payments/overview)                      | \$500 payment to Chase, settled in 3 days         |

<CardGroup>
  <Card title="Payments Lifecycle" icon="arrows-spin" href="/guides/payments/lifecycle">
    Deep dive into payment states, timing, and error handling.
  </Card>

  <Card title="Payment Errors" icon="triangle-exclamation" href="/guides/payments/errors">
    Understanding and handling payment failures and reversals.
  </Card>
</CardGroup>


# December Updates
Source: https://docs.methodfi.com/changelog/2024/december



## New Features

### New Method Dashboard

<img alt="title" />

We’re thrilled to announce early access to the **all-new Method Dashboard**, purposefully redesigned to harness the full potential of our API’s V2 capabilities.

This intuitive interface is crafted to empower both technical and non-technical team members with:

* Role-based access control
* Advanced data visualization
* Custom reporting capabilities
* Universal search functionality
* Self-service team management
* Key rotation tools
* SSO and Passkey authentication

Everyone across your team can now use the new Method Dashboard:

* **CX** – monitor and troubleshoot any issues associated with end-user data.
* **Engineering** – create API keys and monitor webhooks.
* **Finance** – view high-level metrics to better understand billing.

**How to access?**
Dashboard v2 is available for all teams, including existing ones, ensuring a seamless transition to the new interface.
Log in with your email at [app.methodfi.com](https://app.methodfi.com) to explore the new features!

### Vehicles API

<img alt="title" />

The [Vehicles API](https://docs.methodfi.com/reference/entities/vehicles/overview) enables your application to access detailed vehicle information with minimal PII. This data can help you unlock valuable insights and drive better decision-making.

**Key Use Cases**

* **Increase conversion** with pre-filled vehicle details by optimizing loan repayment terms using the vehicle's depreciation curve.
* **Enhance credit risk underwriting** by leveraging vehicle ownership details.
* **Enable personalized financial management** by correlating vehicle data with user behavior insights.

For example, you can retrieve data such as the vehicle's `VIN`, `year`, `make`, `model`, `color`, and `style`.

The Vehicles API is now available to all teams on Method’s V2 API (version: 2024-04-04). Contact your Method CSM to get access!

***

## Improvements

### Account Verification Limits

To bolster system security and performance, we've introduced new verification limits:

* **Account Verification Session limits**: Up to 10 failed attempts per session.
* **Account-level verification limits**:
  * Maximum of 5 sessions per verification type.
  * Maximum of 10 total sessions across all types.

For more details, visit [Account Verification Sessions Errors](https://docs.methodfi.com/reference/errors/account-verification-session-errors).

***

## SDK Updates

* Released [version 1.1.5](https://github.com/MethodFi/method-python/releases/tag/v1.1.5) of `method-python`.
  * [Vehicles API](https://docs.methodfi.com/reference/entities/vehicles/overview) is now available in `method-python`.
* Released [version 1.1.6](https://github.com/MethodFi/method-node/releases/tag/v1.1.6) of `method-node`.
  * [Vehicles API](https://docs.methodfi.com/reference/entities/vehicles/overview) is now available in `method-node`.


# November Updates
Source: https://docs.methodfi.com/changelog/2024/november



## New Features

### Payment Posted Confirmation

<img alt="title" />

We’re excited to announce [`posted`](https://docs.methodfi.com/reference/payments/overview#possible-enum-values:~:text=The%20Payment%20has%20been%20posted%20to%20the%20destination%20Account), a new payment status that closes the loop on payments by confirming when they have successfully landed in your users’ accounts.

With **real-time account data**, Method now provides a level of visibility that was previously unavailable in the U.S. financial system. By knowing if and when a payment has been applied, you can deliver timely and actionable updates to your users—boosting confidence and creating a seamless payment experience.

**Key highlights:**

* **Enabled for all payments**: The feature is live for all teams and payments processed via Method’s V2 API (version: `2024-04-04`) going forward.
* **No action required**: Start using this feature immediately—just consume the new status in your integration.
* **75% coverage**: We expect approximately 75% visibility into posted status, with improved coverage as more accounts are subscribed to updates.
* **Unlock new use cases**: Use the posted status to notify users via push notifications, emails, or in-app messages, keeping them informed and engaged.
* **Account subscription required**: In a future release, the posted status will only be available for accounts subscribed to updates.

### New Method Brand

<img alt="title" />

We’re excited to introduce Method’s new visual identity, marking a new chapter in our journey under the same thesis we had on day one: consumer financial data is a walled garden, and we’re going to be the ones to open it up.

The updated design features:

* A new icon and wordmark
* A refined color palette centered around Method Opal: a bold, fresh, and vibrant cyan
* A new [website](https://methodfi.com/)

Read more about the redesign [here](https://methodfi.com/blog/rebranding-method).

***

## Improvements

### Detailed Webhook Errors

[Webhook Errors](https://docs.methodfi.com/reference/errors/webhook-errors) now includes detailed explanations of issues that caused your webhook to be disabled.

Webhook objects now feature an `error` field following the common Method error format. The error codes for webhook errors are:

* 25001 – `WEBHOOK_DISABLED_FAILED_OTHER`: Indicates five consecutive failures not classified as 4XX, 5XX, or timeouts.
* 25002 – `WEBHOOK_DISABLED_RECEIVED_4XX_ERROR`: The endpoint returned client errors (4XX) five times.
* 25003 – `WEBHOOK_DISABLED_RECEIVED_5XX_ERROR`: The endpoint returned server errors (5XX) five times.
* 25004 – `WEBHOOK_DISABLED_TIMEOUT_ON_RESPONSE`: No valid response received within 5 seconds for five consecutive attempts.

### New List Endpoints

We’ve expanded our API capabilities by introducing list functionality for the following resources, allowing you to retrieve comprehensive collections, such as all updates or credit scores, for a specific account or entity.

* [Attributes](https://docs.methodfi.com/reference/entities/attributes/list)
* [Credit Scores](https://docs.methodfi.com/reference/entities/credit-scores/list)
* [Connects](https://docs.methodfi.com/reference/entities/connect/list)
* [Identities](https://docs.methodfi.com/reference/entities/identities/list)
* [Entity Verification Sessions](https://docs.methodfi.com/reference/entities/verification-sessions/list)
* [Card Brands](https://docs.methodfi.com/reference/accounts/card-brands/list)
* [Account Updates](https://docs.methodfi.com/reference/accounts/updates/list)
* [Payoffs](https://docs.methodfi.com/reference/accounts/payoffs/list)
* [Sensitive](https://docs.methodfi.com/reference/accounts/sensitive/list)
* [Account Balances](https://docs.methodfi.com/reference/accounts/balances/list)
* [Account Verification Sessions](https://docs.methodfi.com/reference/accounts/verification-sessions/list)

### Elements API

* Removed the ability to pass in `card_brand` in the `products` array when creating an [Element Token](https://docs.methodfi.com/reference/elements/tokens).

***

## SDK Updates

* Released [version 1.1.4](https://github.com/MethodFi/method-python/releases/tag/v1.1.4) of Method Python client (`method-python`).
  * All new `list` endpoints are now available in the Python client.
  * Added `posted` as an enum value for the `payment.status` field.
* Released [version 1.1.5](https://github.com/MethodFi/method-node/releases/tag/v1.1.5) of Method Node.js client (`method-node`).
  * All new `list` endpoints are now available in the Node.js client.
  * Added `posted` as an enum value for the `payment.status` field.


# October Updates
Source: https://docs.methodfi.com/changelog/2024/october



## New Products

### Events API

<img alt="title" />

The [Events API](https://docs.methodfi.com/reference/events/overview) allows your application to monitor specific changes to Method resources.

* For example, you can now be notified when an entity's credit score increases (event type: `credit_score.increased`)
  or if new derogatory marks appear (event type: `attribute.credit_health_derogatory_marks.increased`)

* Events deliver detailed and actionable notifications across all Method products and resources, making webhooks more targeted and specific.
  This ensures you receive alerts for the updates that matter to your application and users.

* Events are classified into two types:
  * Literal changes: Direct updates to a specific field in a resource.
  * Computed changes: Interpreted states derived from multiple field changes or comparisons across different records.

* The Events API is now available to all teams on Method’s V2 API (version: 2024-04-04). This launch includes 10 initial events, with over 100 additional events planned for release in the coming weeks.

### Attributes API

<img alt="title" />

The [Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview) offers a powerful summary of financial profile metrics across all Method API resources.

* For example, it provides real-time indicators on credit utilization, payment reliability, account age, and derogatory marks, allowing developers to access these metrics directly without piecing together data from multiple endpoints.

* Powered by Method’s real-time data integrations, it provides up-to-date insights ensuring your application accesses the most current data for faster, more informed decisions.

* This initial release emphasizes credit health attributes, offering a holistic view of financial stability and risk.

* For information on accessing the Attributes API, please reach out to your Method CSM.

***

## Improvements

### Card Brands API

* Improved our card network integrations (Visa and Mastercard) to deliver lower latencies on Card Brands API requests.
* Expanded coverage across all card products, including providing a reliable unique ID associated with each card product (for example all Chase Sapphire Reserve's across all entities will return the same brand ID)
  * Brand ID is returned within `card_brand.brands[x].id` in the format `brand_*`.

### Credit Scores API

* We've upgraded our Credit Scores API to use VantageScore 4.0, the latest version of the scoring model.
* VantageScore 4.0 provides more predictive scoring by incorporating machine learning techniques and trended credit data, which analyzes credit behaviors over time rather than just a snapshot.
* This upgrade enables more accurate credit risk assessment, especially for consumers with limited credit history.

***

## SDK Updates

* Released [version 1.1.2](https://github.com/MethodFi/method-python/releases/tag/v1.1.2) of Method Python client (`method-python`).
  * [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview) is now available in the Python client.
  * [Events API](https://docs.methodfi.com/reference/events/overview) is now available in the Python client.
* Released [version 1.1.3](https://github.com/MethodFi/method-node/releases/tag/v1.1.3) of Method Node.js client (`method-node`).
  * [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview) is now available in the Node.js client.
  * [Events API](https://docs.methodfi.com/reference/events/overview) is now available in the Node.js client.
* Released [version 2 of Method API Postman Collection](https://www.postman.com/methodfi/method-api/collection/8d5j00b/method-api-v2).


# September Updates
Source: https://docs.methodfi.com/changelog/2024/september



## Improvements

### Performance & Infrastructure

* Improved idempotency locking mechanism to handle simultaneous idempotent requests received across different regions / PoP.
* Under-the-hood liability payment rail improvements to faster settlement time across all major FIs.
* Card Brand has been optimized for increased success speed.
* Expanded checks for invalid update payload from upstream data providers.

### Payment Coverage

* Released new integration with SoFi Personal Loans for near real-time payment settlement speed.
* Payment channels for Sallie Mae, US Bank, and AMEX have been revamped and optimized for speed of posting.
* Additional personal loan payment channels have been enabled - improving payment coverage and speed to posting.
* BMO Harris credit cards are now fully payable when account is connected via Method Connect.

### Developer Experience

* `micro_deposits` verification sessions are now simulatable in dev.
* Speed of `micro_deposists` simulation in dev environment has been increased.
* Expanded Card Brand simulated response in dev environment.
* Improved Student Loans [updates](https://docs.methodfi.com/reference/accounts/updates/overview) documentation for dev environment responses.
* Element now throws an error if any of the requested products are not enabled for the requesting team.

### Account Connectivity

* Improved account update stability for Quicken Loans, Home Depot (Citi), Credit One, and other major FIs.
* "Instant Link" verification was optimized across all networks.
* Visual interaction during the manual Connect Element flow have been streamlined to optimize for conversion.

### Reporting

* Daily emailed reconciliation reports now include the team name in the subject line.
  * e.g. (`Method: Daily ACH Report`) -> (`Method: Daily ACH Report for ${team_name}`)

***

## SDK Updates

* Released [version 1.1.0](https://github.com/MethodFi/method-python/releases/tag/v1.1.0) of Method Python client (`method-python`).
  * [Request ID](/reference/request-id) is now easily accessible via the `last_response` property - we highly recommend logging the request ID for faster issue resolution.
  * This update also includes security updates and test coverage expansion.
* Released [version 1.1.1](https://github.com/MethodFi/method-node/releases/tag/v1.1.1) of Method Node.js client (`method-node`).
  * [Request ID](/reference/request-id) is now easily accessible via the `last_response` property - we highly recommend logging the request ID for faster issue resolution.
  * This update also includes security updates and test coverage expansion.


# April Updates
Source: https://docs.methodfi.com/changelog/2025/april



## New Features

### Dashboard Updates

<img alt="sso" />

We're continuing to improve the Dashboard experience with a few powerful updates:

* **SSO Support** – You can now log in using Single Sign-On. Reach out to your Method CSM to enable SSO for your team.
* **Multi-Team Search** – If you're a member of multiple teams, you can now quickly search and switch between them with ease.
* **PDF Export** – It is now possible to download Entity and Account details as a PDF. Contact your Method CSM to get access to this feature.

## Improvements

### Entity Attribute Handling

We've updated how Entity Attributes are requested. You must now explicitly specify which attributes you'd like to retrieve using a new payload format.

<Warning>Some attributes are restricted by default. Reach out to your Method CSM to get access to these attributes.</Warning>

<Accordion title="Previous">
  ```js theme={null}
  const response = await method
      .entities('ent_TYHMaRJUUeJ7U')
      .attributes
      .create();
  ```
</Accordion>

<Accordion title="New">
  ```js theme={null}
  const response = await method
      .entities('ent_TYHMaRJUUeJ7U')
      .attributes
      .create({
          attributes: [
              "credit_health_credit_card_usage",
              "credit_health_derogatory_marks",
              "credit_health_hard_inquiries",
              "credit_health_soft_inquiries",
              "credit_health_total_accounts",
              "credit_health_credit_age",
              "credit_health_payment_history",
              "credit_health_open_accounts",
              "credit_health_entity_delinquent"
          ]
      });
  ```
</Accordion>

For more details, refer to the [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/create).

### Entity Subscription Creation

Entity subscription creation has been updated to support a new payload format.

<Accordion title="Previous">
  ```js theme={null}
  const response = await method
    .entities('ent_TYHMaRJUUeJ7U')
    .subscriptions
    .create('credit_score');
  ```
</Accordion>

<Accordion title="New">
  ```js theme={null}
  const response = await method
    .entities('ent_TYHMaRJUUeJ7U')
    .subscriptions
    .create({
      enroll: 'credit_score',
    });
  ```
</Accordion>

To enroll in an Entity Attribute subscription, use this format:

```js theme={null}
const response = await method
  .entities('ent_TYHMaRJUUeJ7U')
  .subscriptions
  .create({
    enroll: 'attribute',
    payload: {
      attributes: {
        requested_attributes: [
            'credit_health_credit_card_usage', 
            'credit_health_derogatory_marks'
        ]
      }
    }
  });
```

For more details, refer to the [Entity Subscriptions API](https://docs.methodfi.com/reference/entities/subscriptions/create).

## SDK Updates

* Released [version 1.1.14](https://github.com/MethodFi/method-node/releases/tag/v1.1.14) of `method-node`
* Released [version 1.1.13](https://github.com/MethodFi/method-python/releases/tag/v1.1.13) of `method-python`


# August Updates
Source: https://docs.methodfi.com/changelog/2025/august



## New Features

### Opal

<img alt="opal" />

We're excited to introduce [Opal](/opal/overview), our new embedded UI that can easily be dropped into your existing onboarding flow, enabling a white-labeled, seamless connection to Method. It replaces our current Element UI, allowing you to customize the copy, themes, and other UI components to maintain continuity in your interface and prevent users from feeling like they are moving to a third-party app.

Opal has four different components:

* **Identity Verification (IDV):** collects, confirms, and verifies a user’s identity
* **Connect (CXN):** surfaces all of a user's liability accounts
* **Account Verification (AVF):** verifies credit card details and tokenizes them for payments and checkout use cases
* **Transactions (TXN):** enables users to select cards that they wish to link transaction data

**How it works:**

* Opal is a drop-in SDK, designed for quick and easy integration with minimal effort to implement
* Launch with a single token that’s generated with a mode (e.g., connect, card connect, etc.) and whatever additional parameters you choose
* Once launched, Method handles all of the business logic of the flow, automatically orchestrating all of the information the user needs to provide and determining what part of the flow to route the user to next
* Tokens are persistent - users can pick up exactly where they dropped off
* UI is embedded via JavaScript, React, or React Native

For more information, please visit the [Opal Quickstart](/opal/quickstart) page.


# December Updates
Source: https://docs.methodfi.com/changelog/2025/december



## New features

### Payment Instruments API

Method now supports inbound funding workflows. We’ve added a new `PaymentInstrument` type: `inbound_achwire_payment` which allows liability accounts (e.g., loans, credit cards) to receive direct payments via ACH or wire transfer.

* This feature provisions a unique virtual account number and routing number linked to a specific Method Account, effectively making the underlying liability routable. Third parties can send funds directly to these credentials, and Method automatically applies the funds to the associated account, without requiring you to explicitly create a Payment.

**How it works:**

1. **Create Instrument**: Create a Payment Instrument of type `inbound_achwire_payment` for a specific Method Account
2. **Receive Banking Details**: Method returns unique `account_number` and `routing_number`
3. **Share with a Third Party**: Provide these banking details to a third party (e.g., payroll provider, refinance lender, or another bank)
4. **Inbound Transfer**: When funds are sent to these credentials, Method receives the inbound ACH or wire transfer
5. **Automatic Application**: Method automatically applies the received funds to the associated account

<Note>Available when passing `Method-Version: 2025-12-01` in the request header.</Note>

## Improvements

### Simulate API

The [Simulate API](/reference/simulations/overview) now supports retrieving micro-deposit amounts and simulating inbound ACH / wire payments for inbound\_achwire\_payment Payment Instruments — making it easier for developers to test account verification and inbound payment flows in the development environment.

**[Retrieve Micro-deposit Amounts](/reference/simulations/verification-sessions/get-microdeposit-amounts)**

* This endpoint enables developers to retrieve the exact micro-deposit amounts required to complete ACH account verification flows in the development environment.

**[Simulate Inbound ACH/Wire Payments](/reference/simulations/payment_instruments/create)**

* This endpoint allows developers to simulate receiving an inbound payment and triggers the same automatic payment application logic used in production.

<Warning>This API is available in the development environment only.</Warning>

For more information, visit the [Simulations API](/reference/simulations/overview) documentation.

### Webhooks

We added support for a new webhook event type: `account.number.update`.

* This account-level webhook is triggered when an account number has been updated, allowing developers to be notified of account number changes without polling.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Entities API

The Entities API now supports updating `metadata` via `PUT /entities/{ent_id}`.

* This enables developers to update an Entity's metadata without recreating the Entity, simplifying lifecycle management.

For more information, please refer to the [Update an Entity](/reference/entities/update-entity) documentation.


# February Updates
Source: https://docs.methodfi.com/changelog/2025/february



## New Features

### Dashboard Payment Details Page

<img alt="payment details" />

We've upgraded the Payments experience with a brand-new dedicated Payment Details Page

Now, you get more insights and control than ever before:

* **Payment Timeline** –> Track the full journey of your payments, end to end.
* **Enhanced Payment Info** –> Quickly see whether a payment was made via electronic or paper.
* **Check Images** –> For paper payments, view the check image (if available) directly within the details page.

## Improvements

### Payments API

We've added two new fields to the Payments API to provide better visibility into payment details:

* `destination_payment_method`: Indicates how the payment was delivered to the recipient - either `electronic` or `paper`
* `destination_status`: New status `cashed` available to track when paper checks have been processed

For more information, see our [Payments API documentation](https://docs.methodfi.com/reference/payments/overview).

## SDK Updates

* Released [version 1.1.9](https://github.com/MethodFi/method-python/releases/tag/v1.1.9) of `method-python`
* Released [version 1.1.10](https://github.com/MethodFi/method-node/releases/tag/v1.1.10) of `method-node`


# January Updates
Source: https://docs.methodfi.com/changelog/2025/january



## New Features

### Account Attributes API

<img alt="account attributes" />

We've released a brand new [Account Attributes API](https://docs.methodfi.com/reference/accounts/attributes/overview) that's powered by Method's real-time data integrations for up-to-date insights. It provides:

* Real-time indicators for individual account usage patterns
* Account utilization metrics
* Account standing information
* Delinquency data (period, outcome, and amount)

For access to the Account Attributes API, please contact your Method CSM.

## Improvements

### Entity Attributes API

We've enhanced the [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview) with two new attributes:

* `credit_health_open_accounts`: Total number of open accounts
* `credit_health_entity_delinquent`: Entity delinquency status, rating and a list of delinquent accounts

**Pro tip**: Leverage both the Account Attributes API and the Entity Attributes API to get a holistic view of an entity's credit health.

### Method Dashboard

We've made significant performance and usability improvements to the [Method Dashboard](https://app.methodfi.com):

* Pages load 3x faster. We also made navigating between pages feel a lot better.
* Charts load 2x faster. We also fixed hovering over the bars so it works well.
* Universal Search is now keyboard navigable. You can use your up/down arrows and hit enter.
* Added the ability to right click on a table row and open it in a new tab.
* Created better financial account logos. We will continue to fix bad ones.
* Changed the layout of information on details pages to make reading easier.

Please reach out in Slack with any feedback. We will put your requests at the top of our to-do list.

### Payment Dry-run

We've added a new `dry_run` boolean flag to the `POST /payments` endpoint. When enabled, it will simulate a payment without triggering the actual payment flow. You'll receive accurate information about the payment timeline, helping you preview the payment flow and communicate accurate timing to your users before initiating an actual payment. For more information, see our [Payments API](https://docs.methodfi.com/reference/payments/overview).

## SDK Updates

* Released [version 1.1.8](https://github.com/MethodFi/method-python/releases/tag/v1.1.8) of `method-python`
* Released [version 1.1.9](https://github.com/MethodFi/method-node/releases/tag/v1.1.9) of `method-node`


# July Updates
Source: https://docs.methodfi.com/changelog/2025/july



## New Features

### Message-Level Encryption (MLE)

<img alt="MLE" />

We’ve added support for end-to-end encryption of sensitive data transmitted between your application and Method’s API, available to everyone. Here’s what’s new:

* **Hybrid Encryption:** Uses AES-GCM (for payload encryption) and RSA-OAEP-256 (for key encryption) to ensure confidentiality even if network traffic is intercepted.

* **Public Key Registration:** Register your RSA public key with Method via a `.well-known` endpoint or direct upload.

* **Encrypted Requests & Responses:** Send encrypted payloads using the `Method-MLE: jwe` header; Method encrypts responses using your public key.

* **Key Management:** Support for key rotation, deprecation, deletion, and webhook notifications for Method key changes.

You can find a [quickstart guide here](/reference/message-level-encryption#quickstart). For more information, please refer to the [Message Level Encryption documentation](/reference/message-level-encryption).

### Card Brand API

<img alt="Card Brands" />

We’ve expanded the Card Brand object to provide a more structured format with richer brand details — making it easier to identify, display, and integrate specific card products with consistent issuer, network, and branding data.

<Note>Available when passing `Method-Version: 2025-07-04` in the request header.</Note>

<Accordion title="Previous">
  ```json theme={null}
  {
    "id": "cbrd_eVMDNUPfrFk3e",
    "account_id": "acc_yVf3mkzbhz9tj",
    "network": "visa",
    "issuer": "Chase",
    "last4": "8623",
    "brands": [
      {
        "id": "brand_AMxtjQzAfDCRP",
        "name": "Chase Sapphire Reserve",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
      }
    ],
    "status": "completed",
    "shared": false,
    "source": "network",
    "error": null,
    "created_at": "2024-03-19T01:05:37.247Z",
    "updated_at": "2024-03-19T01:05:37.247Z"
  }
  ```
</Accordion>

<Accordion title="New">
  ```json theme={null}
  {
    "id": "cbrd_Accm7P6t6mYQP",
    "account_id": "acc_LxwEqNicr66yP",
    "brands": [
      {
        "id": "pdt_15_brd_1",
        "card_product_id": "pdt_15",
        "description": "Chase Sapphire Reserve",
        "name": "Chase Sapphire Reserve",
        "issuer": "Chase",
        "network": "visa",
        "network_tier": "infinite",
        "type": "specific",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
      }
    ],
    "status": "completed",
    "source": "method",
    "error": null,
    "created_at": "2025-08-12T00:56:50.139Z",
    "updated_at": "2025-08-12T00:56:50.139Z"
  }
  ```
</Accordion>

**Key Changes**:

* `network` and `issuer` are now nested inside each brand object.
* Added `card_product_id`, `description`, and `type` fields.
* Removed `last4` and `shared` fields.

For more information, please refer to the [Card Brand API](/reference/accounts/card-brands/overview).

### Card Products API

We've added a new `Card Products` directory accesible via our API allowing you to retrieve all `Card Brand` objects associated with a given `Card Product`.

<Note>Available when passing `Method-Version: 2025-07-04` in the request header.</Note>

<Accordion title="Example Request">
  ```bash cURL theme={null}
  curl https://production.methodfi.com/card_products/pdt_17 \
    -H "Method-Version: 2025-07-04" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```
</Accordion>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "pdt_17",
    "name": "Chase Freedom",
    "issuer": "Chase",
    "type": "specific",
    "brands": [
      {
          "id": "pdt_17_brd_1",
          "description": "Chase Freedom",
          "network": "visa",
          "network_tier": "signature",
          "default_image": "https://static.methodfi.com/card_brands/fb5fbd6a5d45b942752b9dc641b93d1f.png"
      },
      {
        "id": "pdt_17_brd_2",
        "description": "Chase Freedom",
        "network": "visa",
        "network_tier": "standard",
        "default_image": "https://static.methodfi.com/card_brands/6cb697528b0771f982f7c0e8b8869de3.png"
      }
    ]
  }
  ```
</Accordion>

For more information, please refer to the [Card Products API](/reference/card-products/overview).

## Improvements

### Connect API

We now support asynchronous Connect requests. You'll receive a `connect.available` webhook when an Async Connect is completed. Async Connect requests can be created by either:

* Setting the `Prefer: respond-async` header
* Specifying `products` and / or `subscriptions` in the request body

The Connect object will now include `requested_products` and `requested_subscriptions` fields in the response body.

<Accordion title="Example Request">
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities/ent_qKNBB68bfHGNA/connect \
    -X POST \
    -H "Prefer: respond-async" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -d '{
      "requested_products": ["card_brand"],
      "requested_subscriptions": ["card_brand"]
    }'
  ```
</Accordion>

<Accordion title="Example Response after Connect is completed">
  ```json theme={null}
  {
    "id": "cxn_4ewMmBbjYDMR4",
    "entity_id": "ent_qKNBB68bfHGNA",
    "status": "completed",
    "accounts": [
      "acc_eKKmrXDpJBKgw",
      "acc_GV8WbmJW7KGRy",
      "acc_MLPKh9gQDDbT8",
      "acc_LbXE8wVYJLrKt",
      "acc_J3P9fayDFjpAy",
      "acc_eFFRV9zmpLREK"
    ],
    "requested_products": ["card_brand"],
    "requested_subscriptions": ["card_brand"],
    "error": null,
    "created_at": "2024-04-12T14:56:46.645Z",
    "updated_at": "2024-04-12T14:56:46.645Z"
  }
  ```
</Accordion>

For more information, please refer to the [Connect API](/reference/entities/connect/overview).

### Webhook API

We've added a new `refs` object to webhook payloads. This object contains the `entity` ID of the Entity that the webhook is related to.

<Accordion title="Example Webhook Payload">
  ```json theme={null}
  {
    "webhook_id": "whk_cSGjA6d9N8y8R",
    "id": "pmt_zR3nJG3c99P3X",
    "type": "payment.update",
    "op": "update",
    "path": "/payments/pmt_zR3nJG3c99P3X",
    "event": "evt_knqJgxKUnqDVJ",
    "refs": {
      "entity": "ent_qKNBB68bfHGNA"
    }
  }
  ```
</Accordion>

We have also added the following new webhooks:

* `card_brand.available`
* `connect.available`
* `method_jwk.create`
* `method_jwk.update`

For more information, please refer to the [Webhooks API](/reference/webhooks/overview).

### Entity and Account Products

The `product_id` field in the `Product` object and the Retrieve endpoint are now deprecated. We've added the `latest_successful_request_id` field to the `Product` object. This field will contain the ID of the most recently successful Product resource.

For more information, please refer to the [Entity Products API](/reference/entities/products/overview) and [Account Products API](/reference/accounts/products/overview).


# June Updates
Source: https://docs.methodfi.com/changelog/2025/june



## New Features

### Webhook HMAC Signature Verification

We’ve added support for HMAC-SHA256 signatures to further secure your webhook integrations. Here's what's new:

* **Signed Webhooks:** When you provide an `hmac_secret` during webhook registration, Method now includes a `method-webhook-signature` header on each webhook request. This signature is an HMAC-SHA256 digest, computed using your `hmac_secret` as the shared secret and the message format `${method-webhook-timestamp}:${raw_payload}`.

* **Timestamp Header:** Every webhook request now includes a `method-webhook-timestamp` header (UNIX timestamp in seconds), allowing you to validate the freshness of requests and prevent replay attacks.

* **Verification:** You can verify the webhook by recreating the HMAC digest locally and comparing it using a timing-safe equality check.

For more information, please refer to the [Webhook API](/reference/webhooks/overview).

## Improvements

### Connect API

* **Automatic Execution of Account Products and Subscriptions:** You can now optionally include `products` and `subscriptions` arrays in the request body when creating a `Connect` for an entity. These will automatically execute upon a successful connection.

* **Expand Query Parameter:** A new `expand` query parameter has been added to the `Connect` object, allowing you to include additional properties within the `accounts` object.

<Accordion title="Example Request">
  ```js theme={null}
  const connect = await method
      .entities('ent_TYHMaRJUUeJ7U')
      .connect
      .create(
          {
              products: ['attribute', 'card_brand'],
              subscriptions: ['card_brand', 'transaction'],
          }, 
          {
              expand: ['accounts.update']
          }
      );
  ```
</Accordion>

For more information, please refer to the [Connect API](https://docs.methodfi.com/reference/entities/connect/overview) and [Expanding Resources](/reference/expanding).

## SDK Updates

* Released [version 1.2.4](https://github.com/MethodFi/method-node/releases/tag/v1.2.4) of `method-node`
* Released [version 1.2.4](https://github.com/MethodFi/method-python/releases/tag/v1.2.4) of `method-python`


# March Updates
Source: https://docs.methodfi.com/changelog/2025/march



## New Features

### Transactions API

<img alt="transactions" />

We’re excited to launch our new [Transactions API](https://docs.methodfi.com/reference/accounts/transactions/overview) which gives real-time notifications directly from the card networks on credit/debit card purchases. Key benefits include:

* **Real-Time Alerts** -> Instantly notify users about new charges.
* **Intelligent Categorization** -> Automatically categorize spending using merchant category codes (MCCs).
* **Enhanced Security** -> Flag unusual transactions and identify spending in unfamiliar locations.
* **Multi-Currency Support** -> Monitor transactions in both USD and foreign currencies.
* **Refund Visibility** -> Gain complete insight into refund statuses.

For access to the Transactions API, please contact your Method CSM.

### Payment Instruments API

Our new [Payment Instruments API](https://docs.methodfi.com/reference/accounts/payment-instruments/overview) enables you to create and retrieve card credentials for checkout processes. This API provides seamless access to card details and network tokens, streamlining payment experiences across your app or platform.

For access to the Payment Instruments API, please contact your Method CSM.

### Simulate Credit Scores API

In `development` environments, you can now leverage the [Simulate Credit Scores API](https://docs.methodfi.com/reference/simulations/credit-scores/create) to simulate custom credit scores. This feature lets you:

* Simulate scores for test entities.
* Customize score values, sources, and models.
* Include contributing factor data for more realistic testing scenarios.

## Improvements

### Entity Attributes API

We've made significant improvements to the [Entity Attributes API](https://docs.methodfi.com/reference/entities/attributes/overview).

* **Credit Health Hard Inquiries**: The `credit_health_hard_inquiries` attribute now includes two additional fields in its metadata history:
  * `institution_name`: Identifies the institution that performed the inquiry.
  * `inquiry_date`: Provides the date the inquiry occurred.
* **New Soft Inquiries Attribute**: A new `credit_health_soft_inquiries` attribute has been added. It mirrors the structure of hard inquiries to consistently track soft credit checks along with the associated institution name and inquiry date.

### Updates API

The [Updates API](https://docs.methodfi.com/reference/accounts/updates/overview) response now includes a new field:

* `data_as_of`: A timestamp indicating when the data in the record was last confirmed to be accurate, providing clear insight into the freshness and reliability of the information returned.

### Card Brands API

The [Card Brands API](https://docs.methodfi.com/reference/accounts/card-brands/overview) is now subscribable. This enhancement allows your system to automatically receive updated card brand information in real time. For example, if a user loses their card and receives a new one, the API will promptly reflect these changes, ensuring that your records are always accurate and up to date.

### Accounts API

We've expanded the [Accounts API](https://docs.methodfi.com/reference/accounts/overview) to support additional account types:

* `BNPL` (Buy Now, Pay Later)
* `Fintech`

### Account Verification Sessions API

The [Account Verification Sessions API](https://docs.methodfi.com/reference/accounts/verification-sessions/overview) now supports the `network` verification type. For more information, please see the [Network Verification Sessions API reference](https://docs.methodfi.com/reference/accounts/verification-sessions/update-network).

## SDK Updates

* Released [version 1.1.13](https://github.com/MethodFi/method-node/releases/tag/v1.1.13) of `method-node`
* Released [version 1.1.12](https://github.com/MethodFi/method-python/releases/tag/v1.1.12) of `method-python`


# May Updates
Source: https://docs.methodfi.com/changelog/2025/may



## Improvements

### Transactions API

A new `merchant` property has been added to the `Transaction` object. This field provides the merchant name and logo associated with each transaction.

<Warning>This property is not available by default. You can enable it by contacting your Method CSM.</Warning>

For more information, please refer to the [Transactions API](https://docs.methodfi.com/reference/accounts/transactions/overview).

### Card Brand API

The `CardBrand` object now includes a `source` property. Possible values are:

* `method` – sourced from Method’s internal systems

* `network` – retrieved directly from the card network

* `null` – source is unavailable

For more information, please refer to the [Card Brand API](https://docs.methodfi.com/reference/accounts/card-brands/overview).

## SDK Updates

* Released [version 1.2.2](https://github.com/MethodFi/method-node/releases/tag/v1.2.2) of `method-node`
* Released [version 1.2.2](https://github.com/MethodFi/method-python/releases/tag/v1.2.2) of `method-python`


# November Updates
Source: https://docs.methodfi.com/changelog/2025/november



## Improvements

### Simulate API

The [Simulate API](/reference/simulations/overview) now supports simulating Card Brand subscription behaviors.

**[Simulate Card Brand API](/reference/simulations/card-brands/create)**

* Card Brand simulations let developers designate a card brand for an account with an active Card Brand Subscription by specifying a `brand_id`. This triggers a `card_brand.available` webhook containing the ID of the designated card brand, allowing developers to test card brand-driven workflows in the development environment.

<Warning>This API is available in the development environment only.</Warning>

For more information, visit the [Simulations API](/reference/simulations/overview) and [Card Brand API](/reference/accounts/card-brands/overview) documentation.


# October Updates
Source: https://docs.methodfi.com/changelog/2025/october



## Improvements

### Accounts API

The [Accounts API](/reference/accounts/overview) now includes a new `sub_type` field under the `liability` object. This field provides additional context about a liability account by specifying its sub-type (for example, distinguishing between a `secured` and `unsecured` `personal_loan`).

For more information, please see <a href="/reference/accounts/overview#account-liability-sub-types">Account Liability Sub-Types.</a>

## SDK Updates

* Released [version 2.0.0](https://github.com/MethodFi/method-node/releases/tag/v2.0.0) of `method-node`
* Released [version 2.0.0](https://github.com/MethodFi/method-python/releases/tag/v2.0.0) of `method-python`

These major releases include default support for the **`2025-07-04` API version**, which introduces the new [Card Products API](/changelog/api-versions/2025-07-04) and updated [Card Brand schema](/changelog/api-versions/2025-07-04#card-brand-api).

See the [2025-07-04 API Version](/changelog/api-versions/2025-07-04) for more details.


# September Updates
Source: https://docs.methodfi.com/changelog/2025/september



## New Features

### Dashboard Updates

**Card Brands Directory**

<img alt="card brands directory" />

We released a new tab in the Method Dashboard – Card Brands – displaying Method's proprietary catalog of credit card brands and metadata. This dataset underpins the Card Brands API, which enables exact 1:1 product matching for each credit card in a user’s wallet, meaning you can identify the specific card brand a user is holding. For example, instead of just knowing a user holds a Chase Visa, you can determine if they hold a Chase Sapphire Reserve, Freedom Unlimited, or any co-branded product.

For access to the Card Brands Directory, please contact your Method CSM.

**New Role: Restricted Member**

You can now invite teammates as a Restricted Member. This role is the same as the Member role, except Restricted Members have no access to view end-users PII.

## Improvements

### Simulate API

The [Simulate API](/reference/simulations/overview) now supports simulating Connect and Attributes behaviors for an entity — making it easier for developers to test how Method responds to various data changes without needing to trigger them in production.

**[Simulate Connect API](https://docs.methodfi.com/reference/simulations/connect/create)**

* You can now configure Connect behaviors such as new\_credit\_card\_account. This is useful when testing account-creation flows or verifying how your system handles new data returned from a subsequent Connect. For example, after configuring this behavior, the next time you execute Connect for that entity, a new credit card account will appear in the response — helping you simulate real-world user events like a customer opening a new card.

**[Simulate Attributes API](https://docs.methodfi.com/reference/simulations/attributes/create)**

* Similarly, you can configure Attribute behaviors such as new\_soft\_inquiry to test how your system reacts to changing credit attributes. On the next Attributes request for that entity, the configured behavior will be applied (e.g., a new soft inquiry will be present).

<Warning>This API is available in the development environment only.</Warning>

These new simulation capabilities give you greater control when testing entity lifecycle scenarios and verifying downstream logic — without needing real production data or user actions.

For more information, visit the [Simulations API](/reference/simulations/overview) documentation.


# April Updates
Source: https://docs.methodfi.com/changelog/2026/april



## New Features

### Attributes V2: Entity & Account Attributes

A new version of the [Attributes API](/reference/entities/attributes/overview) introduces 50+ new computed attributes across both Entities and Accounts, giving you a more complete, up-to-date picture of a user's financial health:

* **Utilization & Credit Health**: See a user's credit utilization broken out by account type, with 30/60/90-day trend lines and delta calculations that show whether utilization is rising or falling over time. Includes delinquency flags and payment-to-minimum ratios that help identify users who may be falling behind.
* **Balance & Debt Movement**: Track how balances are changing across a user's full liability portfolio with 30/60/90-day balance change attributes. Understand whether a user is paying down debt or accumulating it, across credit cards, personal loans, mortgages, and installment accounts.
* **Cost of Debt**: Weighted average APR calculations across liability types help you understand what a user is actually paying in interest, useful for refinance targeting, rate optimization, and cross-sell opportunities.
* **Payment Behavior**: Monthly installment estimates, minimum payment totals, and autopay detection give visibility into how a user is managing their obligations and whether they're likely to stay current.

V2 attributes are available at both the Entity level (aggregated across all of a user's accounts) and the Account level (per-account metrics). V2 attributes support webhook delivery and subscriptions, and can be simulated in the development environment via the [Simulations API](/reference/simulations/attributes/create).

For more information, visit the [Attributes API](/reference/entities/attributes/overview) documentation.

### Opal Embeddable Mode

[Opal](/opal/overview) now supports a fully embeddable rendering mode for JavaScript and React integrations. The new embeddable mode allows Opal to be rendered inline within your application's DOM rather than in a modal overlay, giving you full control over layout and positioning.

* **React SDK**: The `@methodfi/opal-react` package has been updated to v1.5.0 with embeddable mode support.
* **JavaScript SDK**: Native JavaScript integrations can now pass `mode: "embeddable"` when initializing Opal.

For more information, visit the [Opal Libraries](/opal/libraries) documentation.

### Managed Accounts API

A new [Managed Accounts API](/reference/managed-accounts/overview) provides programmatic access to Method-managed FBO accounts. You can now retrieve managed account balance information and list transactions for reconciliation:

* `GET /managed_accounts` — list all Managed Accounts on your team
* `GET /managed_accounts/{macc_id}` — retrieve a specific Managed Account
* `GET /managed_accounts/{macc_id}/transactions` — list transactions for a Managed Account

For more information, visit the [Managed Accounts API](/reference/managed-accounts/overview) documentation.

## Improvements

### Opal UI

* **CVV Autofill Detection**: Browsers that autofill CVV fields were sometimes causing silent submission failures because Opal didn't detect the autofilled value. This is now handled correctly, so users who rely on password managers or browser autofill won't hit unexpected errors.
* **Input Trimming**: Whitespace is now automatically stripped from user inputs before submission. This catches a common issue where users copy-paste account numbers or card details with trailing spaces, which would previously cause validation failures.

For more information, visit the [Opal](/opal/overview) documentation.

### Webhooks

**Improved Duplicate Detection**

Previously, webhooks with the same endpoint URL and different authentication credentials (for example, separate webhook configs for staging and production that share a URL) were treated as duplicates, delivering to only one of them. Deduplication now accounts for authentication configuration, so each distinct webhook registration receives its own deliveries as expected.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.


# February Updates
Source: https://docs.methodfi.com/changelog/2026/february



## New Features

### Forwarding Requests: Entity Bindings

The [Forwarding Requests API](/reference/forwarding-requests/overview) now supports `entity` as a binding type. Previously, the `bindings` object only accepted `payment_instrument` and `secret` resource IDs. You can now bind an Entity and reference its data in your forwarding request templates using the `{{entity.field}}` syntax.

This enables use cases where an individual's first and last name need to be forwarded to third-party services alongside the associated account number, without exposing raw PII to your system.

```json Sample Request theme={null}
{
  "bindings": {
    "payment_instrument": "pmt_inst_7TNTTRQwQxWc",
    "secret": "sec_au22b1fbFrmfp",
    "entity": "ent_au22b1FBFJbp8"
  },
  "url": "https://sample-url/v1/tokens",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{secret.value}}"
  },
  "body": "{\"first_name\":\"{{entity.individual.first_name}}\",\"last_name\":\"{{entity.individual.last_name}}\",\"number\":\"{{payment_instrument.card.number}}\"}"
}
```

For more information, visit the [Forwarding Requests API](/reference/forwarding-requests/overview) documentation.

### Credit Score Simulations

The [Simulate API](/reference/simulations/overview) now supports direct event creation for Credit Score simulations.

* **New endpoint**: `POST /simulate/events` with `type` set to `credit_score.increased` or `credit_score.decreased`
* This endpoint allows developers to trigger credit score change events for an Entity with an active Credit Score subscription in the development environment, streamlining the testing of credit score-driven workflows

<Warning>This API is available in the development environment only.</Warning>

For more information, visit the [Simulations API](/reference/simulations/events/create) documentation.

## Improvements

### Updates API

**Student Loan — Opened At**

The [Updates API](/reference/accounts/updates/overview) now surfaces the `opened_at` field for `student_loan` liability accounts when `source` is `direct`. This field returns the date the student loan was originally opened, providing additional context for loan lifecycle analysis, refinance eligibility assessments, and portfolio segmentation.

For more information, visit the [Updates API](/reference/accounts/updates/overview) documentation.

### Webhooks

**New Accounts Surfaced Event**

The `entity.new_accounts_pending_consent` webhook fires when a previously undiscovered liability account surfaces after a user progresses through [Connect](/opal/connect/overview), but only for users who haven't opted into automatic consent for future accounts. For customers using Opal or the Element, this enables you to surface the new account to your end user for explicit consent, and optionally offer them the ability to auto-consent to future accounts going forward. This removes the need to poll the [Accounts API](/reference/accounts/overview) to discover new accounts.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Connect API

**Filter Accounts by Product**

You can now filter accounts by product type when using [Connect](/opal/connect/overview). This allows you to scope a Connect session to only surface accounts relevant to a specific product (e.g., only accounts eligible for payments or only accounts with update subscriptions), reducing noise and improving the end-user experience in targeted workflows.

For more information, visit the [Connect API](/opal/connect/overview) documentation.

### Payment Instruments API

**Card Billing Zip Code**

A new `billing_zip_code` field is now available on `card` type [Payment Instruments](/reference/accounts/payment-instruments/overview). This field is returned as part of the `card` object when retrieving a Payment Instrument.

* `card.billing_zip_code`: The billing zip code associated with the card

This addition supports address verification (AVS) workflows and reduces payment failures caused by billing address mismatches when forwarding card details to third-party processors.

For more information, visit the [Payment Instruments API](/reference/accounts/payment-instruments/overview) documentation.

### Payments API

**Inbound ACH/Wire Trace Numbers & Metadata**

Inbound ACH and wire payments received via `inbound_achwire_payment` [Payment Instruments](/reference/accounts/payment-instruments/overview) now include trace number and metadata fields on the [Payment](/reference/payments/overview) object.

* `source_trace_id`: enables end-to-end payment tracking and reconciliation for inbound transfers
* `destination_trace_id`: provides the underlying bank transaction ID on the destination Account for outbound reconciliation
* `metadata`: allows clients to associate custom reference information with incoming transactions (e.g., you can now add internal reference IDs, ​​customer IDs, and notes in the metadata)

For more information, see the [Payments API](/reference/payments/overview) documentation.

### Versioned API Reference Docs

The API Reference documentation now supports **version-aware navigation**. A version dropdown in the navigation bar lets you switch between API versions (`2025-12-01`, `2025-07-04`, `2024-04-04`) to view the documentation specific to your pinned API version.

Each version renders its own copy of the API Reference with version-specific request examples, response schemas, and available fields — so the docs you see always match the behavior of the API version you're using.

For more information, visit the [Versioning](/reference/versioning) documentation.


# January Updates
Source: https://docs.methodfi.com/changelog/2026/january



## New Features

### Forwarding Requests API

The [Forwarding Requests API](/reference/forwarding-requests/overview) allows you to securely proxy sensitive data (such as card details) to third-party services without your system ever handling the raw data. This enables use cases like payment processing, tokenization, and partner integrations while maintaining the PCI compliance of existing solutions.

**Key capabilities:**

* **Secure data transmission**: Send templated HTTP requests to whitelisted third-party endpoints.
* **Dynamic data injection**: Use template placeholders (e.g., `{{my_binding.card.number}}`) instead of raw values.
* **Binding resolution**: Bind placeholders to Method resources (currently [Payment Instruments](/reference/accounts/payment-instruments/overview)), allowing Method to securely append the underlying data without ever touching your company database.
* **Destination whitelisting**: Requests can only be sent to pre-approved URLs to prevent data exfiltration.
* **Transparent responses**: The third-party response is forwarded directly back to your application without requiring you to make changes to the way you ingest third-party response data.

For more information, visit the [Forwarding Requests API](/reference/forwarding-requests/overview) documentation.

### Secrets API

The [Secrets API](/reference/secrets/overview) allows you to securely store sensitive configuration values (such as API keys or credentials) for use within Method. Secrets are encrypted at rest and never exposed back to client applications.

**Key capabilities:**

* **Encrypted storage**: Store sensitive values and receive a Secret ID (`sec_...`) in return.
* **No client exposure**: Secret values are never returned in API responses.
* **Forwarding integration**: Secrets can be inserted into [Forwarding Requests](/reference/forwarding-requests/overview) for authenticating with third-party services.

For more information, visit the [Secrets API](/reference/secrets/overview) documentation.

### Opal Appearance Customization

You can now customize the visual appearance of [Opal](/opal/overview), Method's embeddable UI, to better match your application's branding or autofit to your users' devices.

When opening Opal with the client SDK, specify an `appearance` option with one of the following values:

* `light`: Standard light theme (default)
* `dark`: Dark theme for low-light environments
* `system`: Automatically matches the user's device settings

If no appearance is specified, Opal defaults to the `light` theme.

For more information, visit the [Opal Libraries](/opal/libraries) documentation.

## Improvements

### Payment Instruments API

This release introduces several improvements to the [Payment Instruments](/reference/accounts/payment-instruments/overview) product, focused on lifecycle management and subscription control.

**Lifecycle Management for Inbound ACH/Wire**

A new endpoint allows you to close inbound ACH/Wire payment instruments when they are no longer needed. This is useful for decommissioning payment routes after a refinance completes or when a funding relationship ends.

* **New endpoint**: `DELETE /accounts/:accountId/payment_instruments/:pmtInsId`
* **Behavior**: Supported only for `inbound_achwire_payment` instruments. Updates instrument status to `closed` and sets `chargeable` to `false`.

For more information, see the [Payment Instruments API](/reference/accounts/payment-instruments/overview) documentation.

**Granular Subscription Types**

The `payment_instrument` [subscription](/reference/accounts/subscriptions/overview) has been split into two more specific subscription types, giving you more flexibility in determining which webhook events you receive:

* `payment_instrument.card`: Triggered for card-level updates (e.g., PAN changed, expiration updated)
* `payment_instrument.network_token`: Triggered for network token updates (e.g., token provisioned, status changed)

<Note>For API version `2025-12-01`+, clients must use the new specific subscription names.</Note>

### Accounts API

**Collection Account Support**

The [Account Sensitive](/reference/accounts/sensitive/overview) product now supports the `collection` account type. This enables you to retrieve sensitive account details (such as account numbers) for accounts that have been sent to collections, expanding coverage for debt management and recovery workflows.

### Attributes API

**Support for Closed Accounts**

You can now retrieve [Account Attributes](/reference/accounts/attributes/overview) for closed liability accounts. Previously, querying Attributes for a closed account would return an error. With this update, derived financial insights (such as payment history summaries and balance trends) remain accessible even after an account has been closed—useful for historical reporting and analytics.


# July Updates
Source: https://docs.methodfi.com/changelog/2026/july



## New Features

### Raw Credit Report Artifacts and Files API

Teams with raw credit report access can now request the bureau report underlying a Connect as downloadable JSON or PDF artifacts. This gives lenders the full bureau file behind a Connect, so underwriting, risk, and compliance logic can run against the same source data Method used.

Pass `bureau` and `artifacts` when creating a Connect. Equifax and TransUnion are supported:

```json theme={null}
{
  "bureau": "transunion",
  "artifacts": ["raw_credit_report", "credit_report_pdf"]
}
```

The completed Connect returns each artifact in its `files` array. The new Files API provides two ways to access them:

* `GET /files/{file_id}` returns File metadata and a temporary download URL
* `GET /files/{file_id}/download` streams the original file directly

Files remain available after the Connect completes, allowing lenders to run their existing underwriting and risk logic on the same raw credit report output without maintaining a separate bureau integration. Raw credit report access is enabled per team; contact your Method CSM to get started.

For implementation details, visit the [Raw Credit Reports guide](/guides/connect/raw-credit-reports) and [Files API](/reference/files/overview) documentation.

### Estimated Statement Attribute

Account Attributes can now return the upcoming payment due date and minimum amount due for supported accounts through the new `statement` bundle:

* `next_payment_due_date`: the upcoming payment due date
* `next_payment_minimum_amount`: the upcoming minimum amount due, in cents

Previously this required maintaining an Update subscription and waiting for a refreshed Update to land, and between statement cycles the values were frequently missing altogether. Teams can now schedule autopay and reminders against a real due date, size a payment that reliably clears the minimum, and sequence payments across a user's accounts by what comes due first.

When current statement data is unavailable, Method estimates both values from account history and identifies them with `metadata.estimated: true`. When a value cannot be determined, the attribute returns an `ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA` error rather than a fabricated fallback.

```json theme={null}
{
  "bundles": ["statement"]
}
```

For more information, visit the [Account Attributes](/reference/accounts/attributes/overview) API documentation.

### Estimated Credit Card APR

Account Attributes can now return a single `estimated_apr` for supported credit card accounts with qualifying account history.

Card issuers rarely expose an account-level APR through any programmatic channel, which has left teams either asking the end user for their rate or assuming one. Estimated APR lets teams size interest savings, rank refinance and balance transfer offers, and prioritize outreach to the highest-rate balances in a user's profile, without asking the end user for anything.

Every value is identified with `metadata.estimated: true` and carries a `metadata.confidence` of `medium` or `high` based on the depth of available history, so teams can set their own threshold for acting on it. When an APR cannot be inferred with sufficient confidence, the attribute returns an `ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA` error rather than a fabricated fallback.

```json theme={null}
{
  "estimated_apr": {
    "value": 19.5,
    "error": null,
    "metadata": {
      "estimated": true,
      "confidence": "high"
    }
  }
}
```

For more information, visit the [Account Attributes](/reference/accounts/attributes/overview) API documentation.

## Changes

### Payment Processing Windows

Payment processing windows have been updated. Payments using the Method Debit Model are now processed at 1:30 PM CT, and payments using the Prefunded Model are now processed at 3:30 PM CT. Payments submitted before the applicable cutoff are processed same-day; payments submitted after are queued for next-business-day processing.

For more information, visit the [Payments API](/reference/payments/overview) documentation.

## Improvements

### Idempotency and Stuck-Request Recovery

Improvements to Method's idempotency system eliminated persistent `INTERNAL_BAD_STATE` errors on retried requests. Dropped connections now recover automatically on retry, previously stuck requests self-heal rather than remaining locked, and orphaned in-flight requests are released after a short interval.

End users no longer become locked mid-flow after a dropped connection. Requests already stuck in `INTERNAL_BAD_STATE` also recover automatically the next time the end user retries, and no integration changes are required.

For more information, visit the [API Idempotency](/reference/idempotency) documentation.

### Dashboard Navigation and Search

The [Method Dashboard](https://dashboard.methodfi.com) now includes:

* A responsive, collapsible sidebar with improved mobile support
* Faster global search with a more compact results experience
* Faster switching between development and production environments
* Persistence of the most recently used environment across sessions
* FIS trace IDs on sent and posted payments in the payments view

Users with the Developer role can also create API keys and webhook registrations directly from the Dashboard, consistent with their existing permissions. Together these reduce the time spent locating a request, entity, or payment when responding to a customer question.

### Payability Check at Account Creation

Method now runs a payability check when an account is created, so teams learn whether an account can be paid at the point of creation rather than discovering it at payment time. This prevents users from attempting a payment that was never going to succeed.

### Webhook Reliability

Outbound webhook delivery now includes stronger duplicate-delivery protection and prevents queued deliveries from being sent to disabled webhook registrations. Delivery and replay handling have also been hardened to reduce the risk of events being lost during transient service failures.

This means fewer events to deduplicate on your side and less reconciliation work after a transient failure, with no change to how you consume webhooks.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Development Environment

Manual Connect flows can now be configured dynamically, and payments can be simulated against payment instruments without production dependencies. Teams can therefore test a full Connect-to-payment path, including failure cases, before touching a live account.

For more information, visit the [Development Environment](/reference/environments) documentation.


# June Updates
Source: https://docs.methodfi.com/changelog/2026/june



## New Features

### Card Brand Details

The Card Brands endpoint now returns a structured `details` object on each brand, giving you the full marketing-level terms behind a user's card, including APRs, fees, rewards, and promotional offers.

* **APRs**: Purchase and cash-advance APR ranges via `purchase_apr_min` / `purchase_apr_max` and `cash_advance_apr_min` / `cash_advance_apr_max`.
* **Fees**: `annual_fee` and `late_payment_fee`.
* **Rewards**: A full rewards object with program name, reward type (for example, `cash_back`, `points`, `miles`), and per-category earn rates (dining, travel, groceries, gas, and more), including the base-rate category for all other purchases.
* **Promotions**: A `promotions` array covering sign-up bonuses, intro APR offers, statement credits, and more, each with value, spend requirement, qualifying period, and expiration.
* **Classification and freshness**: `card_category` classifies the card (for example, `travel`, `cash_back`, `store`), and `data_as_of` tells you when the details were last captured.

**Key Use Cases**

* Power balance-transfer and refinance offers with accurate rate and promotion data.
* Enrich PFM experiences by showing users the detailed terms and benefits of the cards they carry.
* Optimize checkout and reward experiences by auto-routing purchases to the top-earning card.

Card Brands is available as both a Product (on-demand) and a Subscription (near real-time updates), and the details object is available on API version `2025-07-04` and later. The endpoint is available to partners processing payments through the Payment Instruments endpoint. Contact your Method CSM to enable it. See the [Card Brands reference](/reference/accounts/card-brands/overview) to get started.

### Dashboard: Check Payment Management

Admins can now manage check payments directly from the payment detail page in the [Method Dashboard](https://dashboard.methodfi.com).

* **Stop payment**: Place a stop on a paper check that has been sent but not yet cashed. The check is stopped and funds are reversed to the source.
* **Check endorsement image**: View the front and back endorsed image of a check once it has been cashed.
* **Source & destination status**: The payment detail page now surfaces source status and destination status alongside the existing payment status for better visibility into where a payment is in its lifecycle.

<Note>Stop payment and check image viewing are available to admin users only.</Note>

For more information, visit the [Method Dashboard](https://dashboard.methodfi.com).

### Preauth Signals

The new Preauth Signals endpoint returns the predicted likelihood that a transaction will succeed, alongside verified ownership of the card and recommended retry timing. Built for merchants and commerce platforms looking to optimize payment performance.

**Key Use Cases**

* Predict whether a card payment will go through before attempting the charge to reduce false declines at checkout.
* Identify the best date to retry a payment for recurring charges.

This endpoint is currently in Public Preview. Reach out to your Method CSM for access and documentation.

### New Attributes: Delinquency, HELOC & Available Credit

New entity-level and account-level attributes give you a more complete, real-time picture of borrower risk and capacity.

* **Delinquency signals**: Aggregate borrower-level risk with the worst days-past-due bucket across accounts, whether delinquency is progressing or recently cured, total delinquent balance, and the highest-severity outcome (charge-off, collections, foreclosure, and more).
* **HELOC-specific attributes**: You can now separate out attributes related to HELOCs from mortgages and personal loans to isolate appetite for a new HELOC, CLI, or refi.
* **Available credit**: Understand a borrower's total credit headroom in near real time to assess their riskiness and eligibility for new products.
* **Direct Pay enrichment**: Completed attribute responses now include Method Direct Pay history (recency, amount, and trailing 12-month count), providing a clearer picture of a borrower's risk profile and appetite for debt consolidation.

For more information, visit the [Entity Attributes](/reference/entities/attributes/overview) and [Account Attributes](/reference/accounts/attributes/overview) API documentation.

### Account Attribute Subscriptions

Method now triggers events whenever an account's attributes change, so you can react to balance, utilization, and delinquency shifts in real time instead of polling. Subscribe to the attributes you care about and Method delivers updates to your configured webhooks as they occur.

* Manage what you listen to through the [Subscriptions endpoint](/reference/accounts/subscriptions/overview).
* Receive changes through [Events](/reference/events/overview) and webhooks.

This pairs naturally with continuous, post-origination portfolio monitoring use cases.

### Team IP Allowlisting

Teams can now restrict API access to a defined set of IP addresses. Once an allowlist is configured, requests from outside the approved ranges are rejected, with enforcement backed by a 24-hour cache for low-latency checks. See [IP Whitelisting](/reference/ip-whitelisting) to configure.

## Improvements

### Payments

* **More accurate estimated completion dates**: The `estimated_completion_date` returned on a payment now always shows the correct date or a slightly conservative estimate, especially for same-day ACH source payments.
* **Destination posted date**: The `destination_posted_date` field is now populated once the destination posts, giving you a precise reconciliation signal that is distinct from the estimated completion date.

For more information, visit the [Payments API](/reference/payments/overview) documentation.

### Payment Limits

To protect platform safety and stability, per-transaction and 24-hour limits are now enforced on payment volumes.

A new Limits tab under Dashboard Settings surfaces your team's money-movement capabilities and associated limits in one place. You can now see at a glance what your team is permitted to send and receive, and where caps apply.

Contact your customer success manager to learn more about your team's limits.


# March Updates
Source: https://docs.methodfi.com/changelog/2026/march



## New Features

### [API Guides](/guides/overview)

A new API Guides section is now available in Method's documentation. This comprehensive, concept-first companion to the API Docs helps product and business teams understand how Method's platform works and how best to configure Method's APIs for their use case. The API Guides include:

* **How Method Works**: How Method leverages multiple data sources to power identity verification, account discovery, and data retrieval.
* **Core Products**: In-depth guides for each product area, covering payload details, subscription behaviors, error handling, and edge cases.
* **Use Case Guides**: Implementation frameworks for the most common use cases: debt consolidation and balance transfers for lenders, card linking and checkout for commerce platforms, and liability dashboards and bill pay for personal finance apps, with step-by-step flows mapping Method products to each stage of the customer journey.

These guides are designed to complement the existing API Reference documentation by providing the conceptual foundation and product context that teams need to plan and build their integrations effectively.

### [OpenAPI Specification](https://github.com/MethodFi/openapi)

Method now publishes an official OpenAPI specification for the Method API. The spec enables you to:

* **Generate typed API clients** in any language using OpenAPI-compatible code generators
* **Import endpoints** directly into tools like Postman or Insomnia
* **Integrate with any toolchain** that supports the OpenAPI standard

For more information, visit the [Libraries](/libraries/overview) documentation.

## Improvements

### Webhook Idempotency Headers

You can now easily deduplicate retried or replayed webhook deliveries. All outbound webhooks now include a `method-webhook-delivery-id` header, containing a unique identifier for each webhook delivery. If your endpoint receives the same delivery twice (due to network timeouts, retries, or replays), the `method-webhook-delivery-id` value will be identical, letting you skip duplicate processing with a simple lookup.

```json Sample Headers theme={null}
{
  "method-webhook-delivery-id": "obwh_yBaCP3DQxJ4",
  "content-type": "application/json"
}
```

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Simulations API

**Connect Webhook in Account Opened Simulation**

The `POST /simulate/events` endpoint for `account.opened` events now also sends the `connect.create` webhook as part of the simulation, aligned with the endpoint's production behavior.

Previously, simulating an `account.opened` event only fired the `account.opened` webhook. This gap meant customers couldn't fully test their Connect-to-Account-Opened integration pipeline in dev.

Now, when you simulate `account.opened`, both webhooks fire in sequence:

1. `connect.create` — the Connect session that discovered the account
2. `account.opened` — the account itself becoming available

This enables true end-to-end testing of workflows that listen for Connect completion and then act on the resulting accounts.

```json POST /simulate/events theme={null}
{
  "type": "account.opened",
  "entity_id": "ent_au22b1FBFJbp8",
  "account_id": "acc_Dz3E8r4mJ7xKn"
}
```

For more information, visit the [Simulations API](/reference/simulations/events/create) documentation.


# May Updates
Source: https://docs.methodfi.com/changelog/2026/may



## New Features

### Snapshot Delinquency Data

[Updates](/reference/accounts/updates/overview) with `source: "snapshot"` now include a comprehensive set of delinquency fields sourced from the credit report. These fields give you a full picture of a borrower's delinquency status without pulling a separate credit report for the user.

* **Delinquency Status & Period**: `delinquent_status`, `delinquent_period`, and `delinquent_start_date` indicate the current delinquency state, severity bucket (`less_than_30`, `30`, `60`, `90`, `120`, `over_120`), and when the delinquency began.
* **Delinquent Actions**: `delinquent_action` surfaces servicer-level actions such as `charge_off`, `foreclosure`, `repossession`, `chapter_7`, `chapter_13`, `wage_garnishment`, `payment_agreement`, and `bankruptcy`.
* **Delinquent Amount**: `delinquent_amount` returns the dollar amount currently reported as delinquent.
* **Delinquency History**: `delinquent_history` provides a time-series array of historical delinquency periods, each with `start_date`, `end_date`, `status`, `period`, and `action`, enabling trend analysis across multiple reporting cycles.

Delinquency fields are available on snapshot Updates for `credit_card`, `auto_loan`, `personal_loan`, `mortgage`, and `student_loan` liability types. These fields are not included on Updates with `source: "direct"`.

For more information, visit the [Updates API](/reference/accounts/updates/overview) documentation.

### Receive Reversals via Wire

You can now receive payment reversals via wire. This functionality allows customers to quickly and easily access funds from reversed payments that previously could not run on ACH rails (such as inbound wire transfers via payment instrument).

<Note>These accounts are receive-only and do not support outbound payments.</Note>

For more information, visit the [Accounts API](/reference/accounts/overview) documentation.

### Dashboard: Webhook Management

The [Method Dashboard](https://dashboard.methodfi.com) now supports full webhook lifecycle management. You can create, view, update, and delete webhook endpoints directly from the UI, with no API calls or support requests required.

* Register new webhook endpoints with custom event filters and authentication
* View all active webhooks and their status
* Update endpoint URLs and configuration in place
* Delete webhooks that are no longer needed

For more information, visit the [Method Dashboard](https://dashboard.methodfi.com).

## Improvements

### Rate Limiting

To protect platform stability and ensure consistent performance across all customers, all API requests are now subject to published, tiered rate limits. Documented limits mean your engineering team can design around known thresholds rather than hitting undefined behavior during peak operations.

* Rate limits are applied per API key within a 60-second rolling window, organized into tiers based on operation type.
* Each tier tracks independently, so usage against one tier does not affect capacity in another.
* Customers with high-volume integrations can request custom limits through their customer success manager.

For more information, visit the [Rate Limiting](/reference/rate-limiting) documentation.

### Webhooks

**Delivery Rate Limiting**

Outbound webhook deliveries are now rate-limited to 15 deliveries per second per webhook registration. This smooths delivery during high-volume events (e.g., bulk Connect completions or batch Update subscriptions) and reduces the likelihood of triggering rate-limit responses on your infrastructure.

**Failure Handling**

An individual webhook delivery is now retried up to 5 times before it is marked as failed, rather than remaining in a retry loop indefinitely. After 5 consecutive delivery failures, the webhook `status` is set to `disabled`, consistent with the documented automatic-disabling behavior. You can reactivate a disabled webhook from the Dashboard or via the [Update a Webhook](/reference/webhooks/update) endpoint once the underlying issue is resolved.

For more information, visit the [Webhooks API](/reference/webhooks/overview) documentation.

### Payments API

**Destination Processing Window**

The destination processing window has been updated to 4:00 PM CT (5:00 PM ET). Payments submitted before this cutoff can be processed the same-day; payments submitted after are queued for next-business-day processing.

For more information, visit the [Payments API](/reference/payments/overview) documentation.

### Simulations API

**Account Closed Event**

The `POST /simulate/events` endpoint for `account.closed` events now also triggers the `account.update` webhook as part of the simulation, matching production behavior. This enables more complete end-to-end testing of account lifecycle workflows in the development environment.

```json POST /simulate/events theme={null}
{
  "type": "account.closed",
  "entity_id": "ent_au22b1FBFJbp8",
  "account_id": "acc_Dz3E8r4mJ7xKn"
}
```

When simulating `account.closed`, both webhooks now fire in sequence:

1. `account.update`: the account snapshot is updated with the closed status
2. `account.closed`: the account itself transitions to closed

For more information, visit the [Simulations API](/reference/simulations/events/create) documentation.

### Development Environment

**Mock Credit Reports for Connect**

Mock raw credit reports are now available for [Connect](/opal/connect/overview) flows in the development environment, enabling end-to-end testing of credit report-based account discovery without live bureau data.

<Warning>This feature is available in the development environment only.</Warning>

**Payment Destination Details in Responses**

The development environment `POST /payments` response now includes the `destination_payment_method` field, aligning dev responses with production behavior. This field indicates how the payment is delivered to the recipient, either `electronic` or `paper`.

```json theme={null}
{
  "id": "pmt_rPrDPEwyCVUcm",
  "status": "pending",
  "source": "acc_JMJZT6r7iHi8e",
  "destination": "acc_AXthnzpBnxxWP",
  "destination_payment_method": "electronic"
}
```

For more information, visit the [Payments API](/reference/payments/overview) documentation.


# Introducing API v2
Source: https://docs.methodfi.com/changelog/api-versions/2024-04-04



<img alt="title" />

We are excited to announce the launch of API v2 (release `2024-04-04`), the highly anticipated second version of Method's API.
Over the past year, our team has been dedicated to gathering feedback and working closely with our clients to create an even more powerful and developer-friendly API.

This release is packed with new features and enhancements that build upon Method's credential-less consumer permissioned financial network.

Expanded integrations with Visa/Mastercard power new features such as real-time credit card transaction notifications, and enabling 1-click checkout experiences for merchants.
This is in addition to our real-time financial institution liability updates, which have been significantly upgraded to provide better accuracy, expanded coverage, and reduced latency.

### Upgrading to 2024-04-04

The new API version is available to all existing teams.
New teams are automatically pinned to the API version `2024-04-04`.
During the transition phase, teams will be allowed to utilize any API version in tandem.

Note that once upgraded manually, it’s not possible to revert to older versions. Contact your Method CSM for more information on upgrade rollbacks.

* **Request Header**: Set `Method-Version` to `2024-04-04`. See [API Versioning](/reference/versioning#api-versioning) for more information.
* **Client Libraries**: For Method Libraries, the version is locked to the dated version of the API. For example, method-node v0.x.x is locked to 2020-12-06, while method-node v1.x.x is locked to 2024-04-04 and onwards.

#### Upgrade Support

Our technical integration team is here to help! Contact your Method CSM for a 1:1 on best practices and support migrating to `2024-04-04`

<Tip>Personalized upgrade guides have been created for enterprise customers. Contact your Method CSM to receive your guide.</Tip>

**✨ Ask Method:** The search bar of our docs now includes a conversational LLM search powered by ChatGPT. Feel free to ask any questions and receive a personalized answer.

*Sample questions:*

> How are auth\_sessions different in the new version of the API?

> What are the new products in 2024-04-04?

## Entities

New endpoints have been introduced for verification sessions, identities, connect operations, credit scores, products, and subscriptions. Several endpoints, including auth session, credit scores, and sensitive information retrieval, have been deprecated.

The connect endpoint now fetches all liability accounts across Method’s network of financial institutions, replacing auth\_session.
The verification sessions endpoint manages methods for verifying an entity's phone and identity, while the identities endpoint retrieves the underlying identity (PII) of an entity.
The products and subscriptions endpoints provide an overview of the products and continuous updates available for entities.

### New Features

#### The Connect endpoint

[Connect](/reference/entities/connect/overview) identifies and connects all the liability accounts (e.g., credit card, mortgage, auto loans, student loans, etc.)
for an entity across Method’s network of 1500+ financial institutions/lenders.

* **The Connect endpoint replaces:**
  * Auth Session: `POST /entities/{ent_id}/auth_session`

See [Connect](/reference/entities/connect/overview) for more information.

***

#### The Credit Scores endpoint

[Credit Scores](/reference/entities/credit-scores/overview) returns the latest credit score and score factors for an entity.

* **The Credit Scores endpoint replaces:**
  * Credit Score: `GET /entities/{ent_id}/credit_score`

See [Credit Scores](/reference/entities/credit-scores/overview) for more information.

***

#### The Verification Sessions Endpoint

[Entity Verification Sessions](/reference/entities/verification-sessions/overview) manage the methods for verifying an entity's phone and identity. Entities need to verify
their identity and/or phone to be used throughout the Method API. The status
of an entity's verification is returned via the `verification` field in the Entity object.

* **The Verification Sessions endpoint replaces:**
  * KBA questions via Auth Session: `POST /entities/{ent_id}/auth_session` is replaced by [kba](/reference/entities/verification-sessions/create-kba) entity verification session.
  * Non-KBA authentication via Auth Session: `POST /entities/{ent_id}/auth_session` is replaced by [byo\_kyc](/reference/entities/verification-sessions/create-byo-kyc) entity verification session.
  * `individual.phone_verification_type` and `individual.phone_verification_timestamp` via the create Entity request are replaced by [byo\_sms](/reference/entities/verification-sessions/create-byo-sms) phone verification requirements.
  * Utilizing `capabilities`, `available_capabilities`, and `pending_capabilities` in the Entity object to verify if an entity's identity has been matched or if more PII is required.
    * This flow is now replaced by `verification.identity.verified` and `verification.identity.matched` in the `verification` field in the Entity object.

* **Upgrade notes:**
  * The `verification` field in the Entity object returns the status of Identity Verification (`verification.identity`) and Phone Verification (`verification.phone`).
  * The `method` key in the `entity.verification` object enumerates the phone and identity verifications available for your entity.
    * Available verification methods differ on a team-by-team basis and are further defined by the PII provided during entity creation. See [PII Requirements](/reference/entities/overview#pii-requirements) for more information.
    * Teams with pre-defined PII requirements can utilize `byo_kyc` to skip KBA, and `byo_sms` to skip phone verification.
  * Teams upgrading from a prior API version might have some verifications auto-generated. Contact your Method CSM for more info.
  * The `status` key in an entity will only transition to `active` when all verification requirements have been completed.

See [Verification Sessions](/reference/entities/verification-sessions/overview) for more information.

***

#### The Identities endpoint

Entity [Identities](/reference/entities/identities/overview) endpoint is used to retrieve the underlying identity (PII) of an Entity.

* **The Identities endpoint replaces:**
  * Entity Sensitive: `GET /entities/{ent_id}/sensitive`

See [Identities](/reference/entities/identities/overview) for more information.

***

#### The Products endpoint

Entity [Products](/reference/entities/products/overview) endpoint outlines the products (*capabilities*) an entity has access to and provides an overview of the status of all the products.

Products are Method endpoints available for an entity. Access to most products requires an entity to be active.
However, some products have restricted access requiring team-by-team enablement. See [List all Products](/reference/entities/products/list) for more information.

**Entity Products:**

| Name           | Use-Case                                                             | Resource Doc                                                |
| -------------- | -------------------------------------------------------------------- | ----------------------------------------------------------- |
| `connect`      | On-Demand comprehensive view of an Entity’s outstanding liabilities. | [Connect](/reference/entities/connect/overview)             |
| `credit_score` | On-Demand view of an Entity’s credit score.                          | [Credit Scores](/reference/entities/credit-scores/overview) |
| `identity`     | On-Demand retrieval of the full Identity (PII) for any Entity        | [Identities](/reference/entities/identities/overview)       |

* **The Products endpoint replaces:**
  * Utilizing `capabilities`, `available_capabilities`, and `pending_capabilities` in the Entity object to determine the capabilities an entity has access to.
    These fields have been deprecated from the Entity object and removed in favor of:
    * `products` (products available for this entity)
    * `restricted_products` (products not currently available, but can be made available)

See [Products](/reference/entities/products/overview) for more information.

***

#### The Subscriptions endpoint

Entity [Subscriptions](/reference/entities/subscriptions/overview) endpoint controls the state of all subscriptions for an entity. Subscriptions are products that can provide continuous updates via webhooks (e.g., *Credit Score Subscription provides updates on an entity’s credit score*).

**Entity Subscriptions:**

| Name           | Use-Case                                                                                                            | Resource Doc                                                |
| -------------- | ------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `connect`      | Comprehensive view of an Entity’s outstanding liabilities and continuous near real-time updates on new liabilities. | [Connect](/reference/entities/connect/overview)             |
| `credit_score` | Continuous near real-time updates on an Entity’s credit score.                                                      | [Credit Scores](/reference/entities/credit-scores/overview) |

* **The Subscriptions endpoint replaces:**
  * Custom configuration for continuous credit report pulls via your Method CSM. This has been deprecated and replaced by [Create a Subscription](/reference/entities/subscriptions/create) endpoint.

See [Subscriptions](/reference/entities/subscriptions/overview) for more information.

***

### Breaking Changes

#### Entity object changes

* ✨ Corporation entity types have been simplified to `corporation` during [Create a Corporation](/reference/entities/create-corporation) entity.
  * `c_corporation`, `s_corporation`, `llc`, `partnership`, and `sole_proprietorship` have been deprecated and removed in favor of `corporation`

* ✨ Providing SSN is now supported during [Create an Individual](/reference/entities/create-individual) entity.
  * `individual.ssn`, and `individual.ssn_4`

* ✨ Entity verification status is now returned by the Entity object. See [Entity object](/reference/entities/overview) for more information.
  * `verification`

* ✨ Products and subscription status are now returned by the Entity object. See [Entity object](/reference/entities/overview) for more information.
  * `products`
  * `restricted_products`
  * `subscriptions`
  * `available_subscriptions`
  * `restricted_subscriptions`

* ⛔ Phone verification has been replaced and no longer returned by the Entity object.
  * `individual.phone_verification_type`, and `individual.phone_verification_timestamp` have been deprecated and removed in favor of [Entity Verification Sessions](/reference/entities/verification-sessions/overview)

* ⛔ Entity capabilities have been deprecated and removed from the Entity object.
  * `capabilities`, `available_capabilities`, and `pending_capabilities` have been deprecated and removed in favor of [Products](/reference/entities/products/overview), [Subscriptions](/reference/entities/subscriptions/overview), and [Entity Verification Sessions](/reference/entities/verification-sessions/overview)
    * The `verification` field in the Entity object returns the status of Identity Verification (`verification.identity`) and Phone Verification (`verification.phone`).
    * The `products` array returns the products the entity has access to, replacing `capabilities`.
    * The `restricted_products` array returns the products the entity does not have access to, replacing `pending_capabilities`.
    * The [Entity Products](#) endpoint outlines the products (*capabilities*) an entity has access to and provides an overview of the status of all the products.

* The following fields have been modified in the [Entity object](/reference/entities/overview):

  <AccordionGroup>
    <Accordion title="Fields removed from Entity" icon="circle-minus">
      * `individual.phone_verification_type`
      * `individual.phone_verification_timestamp`
      * `capabilities`
      * `available_capabilities`
      * `pending_capabilities`
    </Accordion>

    <Accordion title="Fields added to Entity" icon="circle-plus">
      * `individual.ssn`
      * `individual.ssn_4`
      * `verification`
      * `products`
      * `restricted_products`
      * `subscriptions`
      * `available_subscriptions`
      * `restricted_subscriptions`
    </Accordion>
  </AccordionGroup>

#### Deprecated endpoints

The following endpoints have been deprecated and removed in `2024-04-04`

* Auth Session: `/entities/{ent_id}/auth_session` removed in favor of [Connect](/reference/entities/connect/overview)
* Credit Score: `/entities/{ent_id}/credit_score` removed in favor of [Credit Scores](/reference/entities/credit-scores/overview)
* Entity Sensitive: `/entities/{ent_id}/sensitive` removed in favor of [Identities](/reference/entities/identities/overview)
* Refresh Capabilities: `/entities/{ent_id}/refresh_capabilities` is no longer supported in `2024-04-04`
* Manual Auth Session: `/entities/{ent_id}/manual_auth_session` is no longer supported in `2024-04-04`
* Entity Vehicles: `/entities/{ent_id}/vehicles` is no longer supported in `2024-04-04`

## Accounts

New endpoints have been introduced for updates, card brands, payoffs, transactions, balances, verification sessions, and sensitive information. Several endpoints, including account syncs, account verification, and sensitive information retrieval, have been deprecated.

The updates endpoint now provides real-time account data directly from financial institutions, replacing syncs, and making liability account data available through the updates endpoint.

The verification process for ACH and liability accounts has been streamlined with Account Verification Sessions.

### New Features

#### The Updates endpoint

[Updates](/reference/accounts/updates/overview) endpoint retrieves in real-time account data including balance, due dates, APRs, directly from the account’s financial institution.
Updates is Method's flagship endpoint and replaces the `sync` endpoint by enabling push notifications directly from the financial institution.

As part of the `2024-04-04` release the Account object has been modified, and most Account data is now returned by an Update object. See [Account object changes](/changelog/api-versions/2024-04-04#account-object-changes) for more information.

* **The Updates endpoint replaces:**
  * Syncing an account using `/accounts/{acc_id}/syncs` has been deprecated and removed in favor of [Create an Update](/reference/accounts/updates/create)
  * Enrolling in auto syncs using `/accounts/{acc_id}/sync_enrollment` or via your Method CSM has been deprecated and removed in favor of [Updates](/reference/accounts/updates/overview) and [Subscriptions](/reference/accounts/subscriptions/overview)
  * Sync status fields in the Account response have been deprecated and removed in favor of [Updates](/reference/accounts/updates/overview). Removed fields include:
    * `data_status`
    * `data_sync_type`
    * `data_last_successful_sync`
    * `data_status_error`
    * `data_source`
    * `data_updated_at`
  * Enrollment into credit report-based updates via your Method CSM has been deprecated and removed in favor of the `update.snapshot` subscription type. See [Subscriptions](/reference/accounts/subscriptions/overview) for more information.
  * Liability data at the account level (`account.liability.<liability_type>`) has been deprecated and removed in favor of an Update object and an expansion. See [Account](/reference/accounts/overview) for more information.
  * Utilizing `data_status` to determine real-time financial institution coverage has been deprecated and removed in favor of the `products` array including `updates`. See [Updates](/reference/accounts/updates/overview) for more information.

* **Upgrade notes:**
  * New updates sources: `direct` and monthly `snapshot` updates.
    * `direct`: Near real-time account update (balance, due dates, etc.) from the account’s financial institution (replaces a `sync`).
    * `snapshot`: Monthly snapshot update (balance, due dates, etc.) from the account’s financial institution (replaces credit report-based updates).
  * Receiving continuous updates requires a subscription to `update` or `update.snapshot`. See [Subscriptions](/reference/accounts/subscriptions/overview) for more information.
  * Liability data at the account level (`account.liability.<liability_type>`) has been deprecated and removed in favor of an Update object and an expansion. See [Account](/reference/accounts/overview) for more information.
  * Any account connected using Entity Connect will receive an initial `snapshot` update and a `direct` update (when available).
  * Legacy accounts connected via `auth_session` have been migrated with an Update object pre-populated.

See [Updates](/reference/accounts/updates/overview) for more information.

***

#### The Card Brand endpoint

[Card Brand](/reference/accounts/card-brands/overview) endpoint retrieves the associated credit card metadata (Product / Brand Name, Art, etc.) directly from the card issuer.
In the future, card brand webhooks will notify in real-time any card changes (e.g., card downgraded, card lost, etc.)

* **The Card Brand endpoint replaces:**
  * Derived card names in the liability account field `name`. Migrating to card brand will provide accurate names across any Visa / Mastercard card regardless of issuing bank.

See [Card Brand](/reference/accounts/card-brands/overview) for more information.

***

#### The Payoffs endpoint

[Payoffs](/reference/accounts/payoffs/overview) endpoint retrieves a payoff quote in real-time from the Account’s financial institution / lender. Payoffs are currently only available for Auto Loan and Mortgage accounts.

* **The Payoffs endpoint replaces:**
  * `payoff_amount` and `payoff_amount_term` fields within the `auto_loan` Account type response. See [Updates](/reference/accounts/updates/overview) for more information on the Account object changes.

See [Payoffs](/reference/accounts/payoffs/overview) for more information.

***

#### The Transactions endpoint

[Transactions](/reference/accounts/transactions/overview) endpoint retrieves real-time transaction (authorization, clearing, etc) notifications for Credit Card Accounts directly from the card networks (Visa, MC).

Enrollment for transactions requires a subscription and additional consent using Method's `connect` element.

* **The Transactions endpoint replaces:**
  * Enrollment for transactions using the `auth` element has been deprecated and removed in favor of the `connect` element. See [Connect Overview](/elements/connect/overview) for more information.
  * Global transactions endpoint `/transactions` has been deprecated and removed in favor of account-scoped transactions. See [Transactions](/reference/accounts/transactions/overview) for more information.
  * `transaction:stream` capability has been deprecated and removed in favor of the `transactions` product. See [Products](/reference/accounts/products/overview) for more information.

See [Transactions](/reference/accounts/transactions/overview) for more information.

***

#### The Balances endpoint

[Balances](/reference/accounts/balances/overview) endpoint retrieves the real-time balance from the account’s financial institution.
Balance is now available for non-liability accounts such as checking accounts. Contact your Method CSM for early access to expanded Balance coverage.

* **The Balances endpoint replaces:**
  * The `balance` field in `liability.<liability_type>.balance` has been deprecated and removed in favor of:
    * Retrieving `balance` using the [Balances](/reference/accounts/balances/overview) endpoint
    * Retrieving  `balance` and additional liability information using the [Updates](/reference/accounts/updates/overview) endpoint

See [Balances](/reference/accounts/balances/overview) for more information.

***

#### The Verification Sessions endpoint

[Account Verification Sessions](/reference/accounts/verification-sessions/overview) manage the methods for verifying an Account to enable specific products for ACH or Liability accounts. For example,
ACH Accounts require a verified Account Verification Session before they can be used as a source for Payments.

* **The Account Verification Sessions endpoint replaces:**
  * ACH Account verification via `/accounts/{acc_id}/verification` has been deprecated and removed in favor of:
    * An Account Verification Session of one of the available methods: `micro_deposits`, `plaid`, `mx`, or `teller`.
    * Teams with corporate disbursement ACH accounts can skip verification and a verification will be auto-provisioned with the type of `auto_verify`.
    * Teams with managed DDAs can whitelist a routing number to skip verification across all their DDAs (routing / account number pair).
    * See [Verification Types](/reference/accounts/verification-sessions/overview#verification-types) for more information.
      A verification of `trusted_provisioner` will be auto-provisioned. Contact your Method CSM for more information.
  * Liability account number verification for AMEX, Apple Card, etc. is now handled by a `standard` Account Verification Session. See [Update a Standard Verification](/reference/accounts/verification-sessions/update-standard) for more information.
  * Instant Link CVV verification is now handled by a `pre_auth` Account Verification Session. See [Update a Pre-auth Verification](/reference/accounts/verification-sessions/update-preauth) for more information.

* **Upgrade notes:**
  * Teams upgrading from a prior API version might have some verifications auto-generated. Contact your Method CSM for more info.

See [Account Verification Sessions](/reference/accounts/verification-sessions/overview) for more information.

***

#### The Sensitive endpoint

[Sensitive](/reference/accounts/sensitive/overview) endpoint returns underlying sensitive account information (e.g., PAN, CVV, account number).
This product is only available for liabilities and requires verification on a team-by-team basis.

* **The Sensitive endpoint replaces:**
  * `GET /accounts/{acc_id}/sensitive` is deprecated and removed in favor of [Create a Sensitive](/reference/accounts/sensitive/create).

See [Sensitive](/reference/accounts/sensitive/overview) for more information.

***

#### The Products endpoint

Account [Products](/reference/accounts/products/overview) endpoint outlines the products (*capabilities*) an account has access to and provides an overview of the status of all the products.

Products are Method endpoints available for an account. Most products are accessible by default.
However, some products have restricted access requiring team-by-team enablement and elevated account verification.

**Account Products:**

| Name         | Use-Case                                                                                                    | Supported Types | Resource Doc                                           |
| ------------ | ----------------------------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------ |
| `update`     | On-Demand real-time account update (balance, due dates, etc.) from the account's financial institution      | All liabilities | [Updates](/reference/accounts/updates/overview)        |
| `balance`    | On-Demand real-time balance from the account's financial institution                                        | All liabilities | [Balances](/reference/accounts/balances/overview)      |
| `card_brand` | On-Demand retrieval of credit card metadata (Product / Brand Name, Art, etc.) directly from the card issuer | Credit Cards    | [Card Brand](/reference/accounts/card-brands/overview) |
| `payoff`     | On-Demand retrieval of auto loan payoff (amount, per diem, etc.) from the account's financial institution   | Auto Loans      | [Payoffs](/reference/accounts/payoffs/overview)        |
| `payment`    | Next day electronic push payments to the account's financial institution                                    | All liabilities | [Payments](/reference/payments/overview)               |
| `sensitive`  | On-Demand retrieval of underlying sensitive account information (PAN, CVV, account number)                  | All liabilities | [Sensitive](/reference/accounts/sensitive/overview)    |

* **The Products endpoint replaces:**
  * Utilizing `capabilities`, `available_capabilities`, and `pending_capabilities` in the Account object to determine the capabilities an account has access to.
    These fields have been deprecated from the Account object and removed in favor of:
  * `products` (products available for this Entity)
  * `restricted_products` (products not currently available, but can be made available)

See [Products](/reference/accounts/products/overview) for more information.

***

#### The Subscriptions endpoint

Account [Subscriptions](/reference/accounts/subscriptions/overview) endpoint controls the state of all subscriptions for an account. Subscriptions are products that can provide continuous updates via Webhooks.
(*e.g., Transaction Subscription provides real-time updates on a Credit Card’s transactions*).

**Account Subscriptions:**

| Name              | Use-Case                                                                                          | Supported Types | Resource Doc                                              |
| ----------------- | ------------------------------------------------------------------------------------------------- | --------------- | --------------------------------------------------------- |
| `transactions`    | Real-time transaction (authorization, purchases, etc.) notifications for credit card accounts     | Credit Cards    | [Transactions](/reference/accounts/transactions/overview) |
| `update`          | Near real-time account update (balance, due dates, etc.) from the account's financial institution | All liabilities | [Updates](/reference/accounts/updates/overview)           |
| `update.snapshot` | Monthly account snapshot update (balance, due dates, etc.) from the credit bureau                 | All liabilities | [Updates](/reference/accounts/updates/overview)           |

* **The Subscriptions endpoint replaces:**
  * Custom configuration for continuous syncs via your Method CSM. This has been deprecated and replaced by [Create a Subscription](/reference/accounts/subscriptions/create) endpoint.
  * Account Sync Enrollment `/accounts/{acc_id}/sync_enrollment` for enrollment in auto syncs. This has been deprecated and replaced with an Updates subscription. See [Updates](/reference/accounts/updates/overview) and [Create a Subscription](/reference/accounts/subscriptions/create) for more information.
  * `data_sync_type` has been removed from the Account endpoint. See [Updates](/reference/accounts/updates/overview) and [List all Subscriptions](/reference/accounts/subscriptions/list) for more information.

See Account [Subscriptions](/reference/accounts/subscriptions/overview) for more information.

***

### Breaking Changes

#### Account object changes

* ✨ Product properties are now included in the Account object. By default, the ID of the latest product resource is returned and can be
  expanded in-line using the `expand` query param. See [Expanding Resources](/reference/expanding) for more information.
  * `latest_verification_session`
  * `update`
  * `balance`
  * `card_brand`
  * `payoff`

* ✨ Products and Subscription status are now returned by the Account object. See [Account object](/reference/accounts/overview) for more information.
  * `products`
  * `restricted_products`
  * `subscriptions`
  * `available_subscriptions`
  * `restricted_subscriptions`

* ✨ Liability name and fingerprint are now returned by the Account object. See [Account object](/reference/accounts/overview) for more information.
  * `liability.name`
  * `liability.fingerprint`

* ✨ New account liability types are now supported and returned by the Account object. See [Account Liability Types](/reference/accounts/overview#account-liability-types) for more information.

* ⛔ Liability data under the `account.liability.<liability_type>` property has been deprecated and removed in favor of [Updates](/reference/accounts/updates/overview)
  * The `updates` field returns the ID of the latest update and can be expanded to return liability account data in-line using the `expand` query param. See [Expanding Resources](/reference/expanding) for more information.

* ⛔ Syncing liability data using `/accounts/{acc_id}/syncs` has been deprecated and removed in favor of [Updates](/reference/accounts/updates/overview)
  * Additionally, data sync status fields at the account liability object have been deprecated and removed in favor of status fields within an [Update](/reference/accounts/updates/overview)
  * `liability.data_status`, `liability.data_sync_type`, `liability.data_sync_type`, `liability.data_last_successful_sync`, `liability.data_source`,
    `liability.data_updated_at`, `liability.data_updated_at`, `liability.data_status_error`

* ⛔ Account capabilities have been deprecated and removed from the Account object.
  * `capabilities`, `available_capabilities`, and `pending_capabilities` have been deprecated and removed in favor of [Products](/reference/accounts/products/overview), [Subscriptions](/reference/accounts/subscriptions/overview), and [Account Verification Sessions](/reference/accounts/verification-sessions/overview)
    * The `products` array returns the products the account has access to, replacing `capabilities`.
    * The `restricted_products` array returns the products the account does not have access to, replacing `pending_capabilities`.
    * The account [Products](/reference/accounts/products/overview) endpoint outlines the products (*capabilities*) an account has access to and provides an overview of the status of all the products.

* ⛔ Account payment status (`liability.payment_status`) has been deprecated and removed in favor of [Products](/reference/accounts/products/overview)

* ⛔ Account clearing (`clearing`) and liability hash (`liability.hash`) has been deprecated and removed in `2024-04-04`

* The following fields have been modified in the [Account object](/reference/accounts/overview):

  <AccordionGroup>
    <Accordion title="Fields removed from Account" icon="circle-minus">
      * `liability.payment_status`
      * `liability.data_status`
      * `liability.data_sync_type`
      * `liability.data_last_successful_sync`
      * `liability.data_source`
      * `liability.data_updated_at`
      * `liability.data_status_error`
      * `liability._liability_type_` - where `liability_type` is any of the [Account Liability Types](/reference/accounts/overview#account-liability-types).
      * `liability.hash`
      * `clearing`
      * `capabilities`
      * `available_capabilities`
      * `pending_capabilities`
    </Accordion>

    <Accordion title="Fields added to Account" icon="circle-plus">
      * `liability.name`
      * `liability.fingerprint`
      * `latest_verification_session`
      * `update`
      * `balance`
      * `card_brand`
      * `payoff`
      * `products`
      * `restricted_products`
      * `subscriptions`
      * `available_subscriptions`
      * `restricted_subscriptions`
    </Accordion>
  </AccordionGroup>

#### Deprecated endpoints

* Account Syncs: `/accounts/{acc_id}/syncs` removed in favor of [Updates](/reference/accounts/updates/overview)
* Account Sync Enrollment: `/accounts/{acc_id}/sync_enrollment` removed in favor of [Updates](/reference/accounts/updates/overview) and [Subscriptions](/reference/accounts/subscriptions/overview)
* Account Verification: `/accounts/{acc_id}/verification` removed in favor of [Account Verification Sessions](/reference/accounts/verification-sessions/overview)
* Account Sensitive: `/accounts/{acc_id}/sensitive` removed in favor of [Sensitive](/reference/accounts/sensitive/overview)
* Account Card: `/accounts/{acc_id}/card` removed in favor of [Card Brand](/reference/accounts/card-brands/overview), [Sensitive](/reference/accounts/sensitive/overview) and Credit Card [Account Verification Sessions](/reference/accounts/verification-sessions/overview)
* Account Payment History: `/accounts/{acc_id}/payment_history` is no longer supported in `2024-04-04`
* Account Details: `/accounts/{acc_id}/details` is no longer supported in `2024-04-04`
* Bulk Sensitive: `/accounts/{acc_id}/bulk_sensitive` is no longer supported in `2024-04-04`
* Bulk Sync: `/accounts/{acc_id}/bulk_sync` is no longer supported in `2024-04-04`
* Account Vehicle: `/accounts/{acc_id}/match_vehicle` is no longer supported in `2024-04-04`
* Routing Numbers: `/routing_numbers` is no longer supported in `2024-04-04`
* BINs: `/bins` is no longer supported in `2024-04-04`

## Additional Changes

### Expand Parameter

New `expand` query parameter for expanding certain properties from an ID to their respective objects in-line in the response body.

Applicable to both Entities and Accounts, allowing expansion of fields such as `connect`, `credit_score`, `update`, `balance`, `payoff`, `sensitive`, `transactions`, `card_brand`, and `latest_verification_session`.

See [Expanding Resources](/reference/expanding) for more information.

### Elements

Introducing the [Connect element](/elements/connect/overview) as the primary way to connect user accounts and complete necessary verifications.

The Auth element has been deprecated in favor of Connect.

See [Connect guide](/elements/connect/overview) for step-by-step instructions on leveraging Connect.


# Introducing API Version 2025-07-04
Source: https://docs.methodfi.com/changelog/api-versions/2025-07-04



We're excited to announce the release of **API version `2025-07-04`**, featuring key improvements to our **Card Brand** model and the introduction of the new **Card Products API**.
This version enhances data consistency across card networks, issuers, and products — enabling more structured integrations and cleaner brand experiences for your users.

***

## What’s New

### Card Brand API

<img alt="Card Brands" />

The [Card Brand API](/reference/accounts/card-brands/overview) has been expanded with a **richer, more structured object**.
This change makes it easier to **identify, display, and integrate** specific card products while ensuring consistent metadata across networks and issuers.

**Key improvements:**

* Brand data is now **fully nested**, encapsulating `network`, `issuer`, and visual assets under each brand.
* New fields such as `card_product_id`, `description`, and `type` provide more granular control when mapping and displaying cards.
* Removed legacy fields (`last4`, `shared`) for a cleaner, product-centric response format.

<Note>Available when passing `Method-Version: 2025-07-04` in the request header.</Note>

<Accordion title="Previous Response">
  ```json theme={null}
  {
    "id": "cbrd_eVMDNUPfrFk3e",
    "account_id": "acc_yVf3mkzbhz9tj",
    "network": "visa",
    "issuer": "Chase",
    "last4": "8623",
    "brands": [
      {
        "id": "brand_AMxtjQzAfDCRP",
        "name": "Chase Sapphire Reserve",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
      }
    ],
    "status": "completed",
    "shared": false,
    "source": "network",
    "error": null,
    "created_at": "2024-03-19T01:05:37.247Z",
    "updated_at": "2024-03-19T01:05:37.247Z"
  }
  ```
</Accordion>

<Accordion title="New Response">
  ```json theme={null}
  {
    "id": "cbrd_Accm7P6t6mYQP",
    "account_id": "acc_LxwEqNicr66yP",
    "brands": [
      {
        "id": "pdt_15_brd_1",
        "card_product_id": "pdt_15",
        "description": "Chase Sapphire Reserve",
        "name": "Chase Sapphire Reserve",
        "issuer": "Chase",
        "network": "visa",
        "network_tier": "infinite",
        "type": "specific",
        "url": "https://static.methodfi.com/card_brands/1b7ccaba6535cb837f802d968add4700.png"
      }
    ],
    "status": "completed",
    "source": "method",
    "error": null,
    "created_at": "2025-08-12T00:56:50.139Z",
    "updated_at": "2025-08-12T00:56:50.139Z"
  }
  ```
</Accordion>

***

### Card Products API

We’re introducing the new [Card Products API](/reference/card-products/overview) — a **directory of card products** that allows you to retrieve all associated `Card Brand` objects for a given product.

This endpoint gives developers a unified way to reference and display card metadata (art, network, tier, and issuer) across all variants of a card family.

<Note>Available when passing `Method-Version: 2025-07-04` in the request header.</Note>

<Accordion title="Example Request">
  ```bash theme={null}
  curl https://production.methodfi.com/card_products/pdt_17 \
    -H "Method-Version: 2025-07-04" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```
</Accordion>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "pdt_17",
    "name": "Chase Freedom",
    "issuer": "Chase",
    "type": "specific",
    "brands": [
      {
        "id": "pdt_17_brd_1",
        "description": "Chase Freedom",
        "network": "visa",
        "network_tier": "signature",
        "default_image": "https://static.methodfi.com/card_brands/fb5fbd6a5d45b942752b9dc641b93d1f.png"
      },
      {
        "id": "pdt_17_brd_2",
        "description": "Chase Freedom",
        "network": "visa",
        "network_tier": "standard",
        "default_image": "https://static.methodfi.com/card_brands/6cb697528b0771f982f7c0e8b8869de3.png"
      }
    ]
  }
  ```
</Accordion>

***

## Breaking Changes

* **Card Brand response shape updated**

  * `network` and `issuer` are now nested under each `brand`.
  * New fields: `card_product_id`, `description`, `type`.
  * Removed fields: `last4`, `shared`.

***

## Why It Matters

This release unifies how card data is modeled and consumed across the Method platform.
By standardizing the `Card Brand` object and introducing a canonical `Card Products` directory, developers can now:

* Reliably map and display card details across networks and issuers
* Build consistent card selection and branding experiences in their apps
* Reduce dependency on ad-hoc naming or inferred card data

***

## Upgrading to 2025-07-04

The new API version is available to all existing teams. New teams are automatically pinned to **`2025-07-04`**.

* **Request Header:** Set `Method-Version` to `2025-07-04`. See [API Versioning](/reference/versioning#api-versioning) for more information.
* **Client Libraries:** `method-node` and `method-python` **v2.0.0+** default to this version.

> Once upgraded, rollbacks to prior API versions are not supported. Contact your Method CSM for upgrade assistance.

***

### Upgrade Support

Our technical integration team is available to guide you through the migration. Contact your Method CSM to schedule a review of your current card integration or to receive a personalized upgrade checklist.


# Introducing API Version 2025-12-01
Source: https://docs.methodfi.com/changelog/api-versions/2025-12-01



We're excited to announce the release of **API version `2025-12-01`**, featuring the new **Payment Instruments API** for inbound funding workflows.
This version enables liability accounts to receive direct payments via ACH or wire transfer — allowing third parties to send funds directly to liability accounts without requiring explicit Payment creation.

***

## What's New

### Payment Instruments API

Method now supports **inbound funding workflows** with the introduction of a new `PaymentInstrument` type: `inbound_achwire_payment`.
This feature allows liability accounts (e.g., loans, credit cards) to receive direct payments via ACH or wire transfer.

**Key features:**

* Provisions a unique virtual account number and routing number linked to a specific Method Account, effectively making the underlying liability routable
* Third parties can send funds directly to these credentials, and Method automatically applies the funds to the associated account, without requiring you to explicitly create a Payment
* Supports use cases such as payroll, refinancing, and other direct payment scenarios

**How it works:**

1. **Create Instrument**: Create a Payment Instrument of type `inbound_achwire_payment` for a specific Method Account
2. **Receive Banking Details**: Method returns unique `account_number` and `routing_number`
3. **Share with a Third Party**: Provide these banking details to a third party (e.g., payroll provider, refinance lender, or another bank)
4. **Inbound Transfer**: When funds are sent to these credentials, Method receives the inbound ACH or wire transfer
5. **Automatic Application**: Method automatically applies the received funds to the associated account

<Note>Available when passing `Method-Version: 2025-12-01` in the request header.</Note>

<Accordion title="Example Request">
  ```bash theme={null}
  curl https://production.methodfi.com/accounts/acc_4m9amk4KFiaQX/payment_instruments \
    -X POST \
    -H "Method-Version: 2025-12-01" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "inbound_achwire_payment"
    }'
  ```
</Accordion>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "pmt_inst_cLbaArHhfDBDf",
    "account_id": "acc_GAzrD99cUqGEN",
    "type": "inbound_achwire_payment",
    "card": null,
    "network_token": null,
    "inbound_achwire_payment": {
      "account_number": "2517228863",
      "routing_number": "026015244"
    },
    "chargeable": true,
    "status": "completed",
    "error": null,
    "created_at": "2025-12-11T00:12:58.639Z",
    "updated_at": "2025-12-11T00:12:58.639Z"
  }
  ```
</Accordion>

See [Payment Instruments](/reference/accounts/payment-instruments/overview) for more information.

***

### Simulate API

The [Simulate API](/reference/simulations/overview) now supports simulating inbound ACH / wire payments for `inbound_achwire_payment` Payment Instruments — making it easier for developers to test inbound payment flows in the development environment.

**[Simulate Inbound ACH/Wire Payments](/reference/simulations/payment_instruments/create)**\
This endpoint allows developers to simulate receiving an inbound payment and triggers the same automatic payment application logic used in production.

<Note>Available when passing `Method-Version: 2025-12-01` in the request header.</Note>

<Warning>This API is available in the development environment only.</Warning>

For more information, visit the [Simulations API](/reference/simulations/overview) documentation.

***

## Breaking Changes

* **Payment Instrument product names changed**

  * The `payment_instrument` product name has been split into three separate product names:
    * `payment_instrument.card`
    * `payment_instrument.network_token`
    * `payment_instrument.inbound_achwire_payment`
  * In previous versions (`2024-04-04`, `2025-07-04`), the Account object's `products`, `restricted_products`, `subscriptions`, `available_subscriptions`, and `restricted_subscriptions` arrays contained the single product name `payment_instrument`.
  * In `2025-12-01`, these arrays now contain the three separate product names instead of the single `payment_instrument` name.

***

## Why It Matters

This release enables new inbound funding workflows that simplify payment collection for liability accounts.
By introducing `inbound_achwire_payment` Payment Instruments, developers can now:

* Enable third parties to send payments directly to liability accounts without explicit Payment creation
* Streamline payroll, refinancing, and other direct payment scenarios
* Automatically apply inbound transfers to the associated account
* Test inbound payment flows more easily with enhanced Simulate API support

***

## Upgrading to 2025-12-01

The new API version is available to all existing teams. New teams are automatically pinned to **`2025-12-01`**.

* **Request Header:** Set `Method-Version` to `2025-12-01`. See [API Versioning](/reference/versioning#api-versioning) for more information
* **Client Libraries:** `method-node` and `method-python` **v2.1.0+** default to this version

> Once upgraded, rollbacks to prior API versions are not supported. Contact your Method CSM for upgrade assistance.

***

### Upgrade Support

Our technical integration team is available to guide you through the migration. Contact your Method CSM to schedule a review of your current payment integration or to receive a personalized upgrade checklist.


# Introducing API Version 2026-03-30
Source: https://docs.methodfi.com/changelog/api-versions/2026-03-30



We're excited to announce the release of **API version `2026-03-30`**, featuring redesigned **Attributes** for both **Entities** and **Accounts**.
This release expands the attributes product with richer computed outputs, a unified per-attribute result shape, and support for asynchronous attribute computation workflows.

***

## What's New

### Entity Attributes

The [Entity Attributes API](/reference/entities/attributes/overview) now returns a broader set of aggregated financial attributes computed across an Entity's connected accounts.
These attributes are organized across categories such as revolving credit cards, personal loans, mortgages, installment balances, and overall utilization.

**Key improvements:**

* Introduces a richer set of financial attributes, including balances, utilization trends, deltas, delinquency signals, and payment behavior metrics
* Returns attributes in a simplified `{ value, error }` shape — `error` uses the standard `{ type, sub_type, code, message }` format when the attribute could not be computed
* Computes all supported entity attributes automatically as part of the request lifecycle
* Supports asynchronous processing so teams can poll or rely on webhook-driven workflows for completion

<Note>Available when passing `Method-Version: 2026-03-30` in the request header.</Note>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "attr_dADraNgLBrhgL",
    "entity_id": "ent_EQ3FCTzDUmmCb",
    "status": "completed",
    "attributes": {
      "revolving_credit_card_balance_total": {
        "value": 968400,
        "error": null
      },
      "credit_limit_total": {
        "value": 8100000,
        "error": null
      },
      "credit_card_utilization": {
        "value": 11.96,
        "error": null
      },
      "overall_utilization": {
        "value": 70.5,
        "error": null
      }
    },
    "error": null,
    "created_at": "2026-04-09T17:02:47.910Z",
    "updated_at": "2026-04-09T17:04:35.220Z"
  }
  ```
</Accordion>

***

### Account Attributes

The [Account Attributes API](/reference/accounts/attributes/overview) has been expanded into a dedicated account-level attributes product.
Returned attributes now vary by liability type, including support for credit cards, personal loans, and mortgages.

**Key improvements:**

* Adds account-level financial attributes such as utilization trends, delinquency flags, and installment estimates
* Returns attributes in a simplified `{ value, error }` shape with standardized error objects
* Supports asynchronous attribute computation workflows for account requests
* Adds webhook support for account attribute lifecycle events

<Note>Available when passing `Method-Version: 2026-03-30` in the request header.</Note>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "id": "acc_attr_cWBKqwVP87kim",
    "account_id": "acc_4m9amk4KFiaQX",
    "status": "completed",
    "attributes": {
      "type": {
        "value": "credit_card",
        "error": null
      },
      "usage_pattern": {
        "value": "revolver",
        "error": null
      },
      "delinquency_flag": {
        "value": false,
        "error": null
      },
      "utilization": {
        "value": 11.96,
        "error": null
      }
    },
    "error": null,
    "created_at": "2026-04-09T17:02:47.910Z",
    "updated_at": "2026-04-09T17:04:35.220Z"
  }
  ```
</Accordion>

***

### Account Attribute Subscriptions

Accounts can now be enrolled in an `attribute` [Subscription](/reference/accounts/subscriptions/overview) for
continuous monitoring of an Account's financial attributes. Once enrolled, Method automatically computes new
[Account Attributes](/reference/accounts/attributes/overview) and notifies your team via webhooks as they change.

```bash theme={null}
curl https://production.methodfi.com/accounts/{acc_id}/subscriptions \
  -X POST \
  -H "Method-Version: 2026-03-30" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "enroll": "attribute"
  }'
```

* Available for credit card, personal loan, and mortgage accounts
* The `attribute` subscription appears in an Account's `available_subscriptions` once eligible

<Note>Available when passing `Method-Version: 2026-03-30` in the request header.</Note>

***

### New Webhook Events

This version adds webhook coverage for the new account attribute resource lifecycle.

**New events:**

* `entity_attribute.create`
* `entity_attribute.update`
* `account_attribute.create`
* `account_attribute.update`

See [Webhooks](/reference/webhooks/overview) for the complete event list.

***

## Breaking Changes

* **Entity Attributes request semantics changed**

  * `POST /entities/{ent_id}/attributes` now computes all supported attributes automatically
  * The legacy request body for selecting specific `credit_health_*` attributes is no longer documented for `2026-03-30`

* **Entity Attributes response shape changed**

  * Legacy attribute payloads that returned `value` and `rating` have been replaced with a simplified `{ value, error }` shape
  * On success, `error` is `null`. On failure, `error` contains a standard `{ type, sub_type, code, message }` object (e.g. `ENTITY_ATTRIBUTE_INSUFFICIENT_DATA` code `27001` for entity attributes, `ACCOUNT_ATTRIBUTE_INSUFFICIENT_DATA` code `28001` for account attributes)
  * Attribute names now reflect the new attribute model

* **Account Attributes response shape changed**

  * Account attribute responses now use the same simplified `{ value, error }` result structure
  * Attribute availability now depends on the account's liability type

* **Attributes create endpoints are asynchronous**

  * Create requests now return an in-progress resource that must be polled or observed via webhook until completion

***

## Why It Matters

This release makes the attributes product more useful for underwriting, servicing, monitoring, and decisioning workflows.
With this release, developers can:

* Retrieve a richer set of entity- and account-level financial signals
* Build against a consistent result format across attributes
* Handle unavailable computations explicitly using standardized `error` objects with `type`, `sub_type`, `code`, and `message`
* Use asynchronous workflows that better fit long-running computations

***

## Upgrading to 2026-03-30

The new API version is available to all existing teams. New teams are automatically pinned to **`2026-03-30`**.

* **Request Header:** Set `Method-Version` to `2026-03-30`. See [API Versioning](/reference/versioning#api-versioning) for more information.
* **Client Libraries:** Check your Method SDK version and upgrade guidance before moving production traffic to the new API version.

> Once upgraded, rollbacks to prior API versions are not supported. Contact your Method CSM for upgrade assistance.

***

### Upgrade Support

Our technical integration team is available to help review your current usage of Attributes and plan a migration to `2026-03-30`. Contact your Method CSM for upgrade support.


# Create a Connect Element Token
Source: https://docs.methodfi.com/elements/connect/create_connect_token



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

To start using Connect, you will first need to create a [Connect Element Token](/reference/elements/tokens).
There are a few different use cases that will determine what you pass to the endpoint.

### New Entities

If you do not have any identity information about your users, you will likely create a token using a payload similar to this:

```json theme={null}
{
  "type": "connect",
  "connect": {
    "products": ["balance"],
    "entity": {
      "type": "individual",
      "individual": {}
    }
  }
}
```

This will return a token that you can use to create a new entity and connect their accounts. Fill in the `products` array with a list of the different products you want to connect (for example `["balance", "card"]`).

### New Entities with Partial Information

If you have some information already about a given user (such as their name), you can pass that information into the `individual` object:

```json theme={null}
{
  "type": "connect",
  "connect": {
    "products": ["balance"],
    "entity": {
      "type": "individual",
      "individual": {
        "first_name": "Kevin",
        "last_name": "Doyle"
      }
    }
  }
}
```

You can also pass in a user's phone number, address, DOB, or the last 4 digits of their SSN to make the identity verification process faster.

### Using with Existing Entities

You can also pass in an existing entity\_id:

```json theme={null}
{
  "type": "connect",
  "entity_id": "ent_au22b1fbFJbp8",
  "connect": {
    "products": ["balance"]
  }
}
```

### Using with Existing Accounts

If you also have specific accounts you'd like to connect, you can pass the account ids:

```json theme={null}
{
  "type": "connect",
  "entity_id": "ent_au22b1fbFJbp8",
  "connect": {
    "products": ["balance"],
    "accounts": ["acc_k8LAKDnED7kti", "acc_KUaFnxn7eUAeH"]
  }
}
```

<RequestExample>
  ```bash cURL theme={null}
  curl https://dev.methodfi.com/elements/token \
    -X POST \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "connect",
      "connect": {
        "products": ["balance"],
        "entity": {
          "type": "individual",
          "individual": {
            "first_name": "Kevin",
            "last_name": "Doyle"
          }
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const token = await method.elements.token.create({
    type: "connect",
    connect: {
      products: ["balance"],
      entity: {
        type: "individual",
        individual: {
          first_name: "Kevin",
          last_name: "Doyle"
        }
      }
    }
  });
  ```

  ```python Python theme={null}
  token = method.elements.token.create({
    'type': "connect",
    'connect': {
      'products': ["balance"],
      'entity': {
        'type': "individual",
        'individual': {
          'first_name': "Kevin",
          'last_name': "Doyle"
        }
      }
    }
  })
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "element_token": "pk_elem_qPmypE9wwphr3WL3yTj7JhxjrPzAmK8G"
  }
  ```
</ResponseExample>


# Getting Connect Results
Source: https://docs.methodfi.com/elements/connect/get_results



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

In addition to [listening for the success event](/elements/events/overview), the result of the Connect session can also be retrieved by calling the `results` endpoint with the element token for that session.

```bash theme={null}
GET /elements/token/{element_token}/results
```

See [Retrieve Element Results](/reference/elements/results) for more information about this endpoint.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/elements/token/pk_elem_dDe4r9M6X3Ad9zjpbgYpzLNtRCXfhPYR/results \
    -X GET \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
  ```

  ```javascript Node.js theme={null}
  const response = await method
    .elements
    .token
    .results('pk_elem_dDe4r9M6X3Ad9zjpbgYpzLNtRCXfhPYR');
  ```

  ```python Python theme={null}
  response = method
    .elements
    .token
    .results('pk_elem_dDe4r9M6X3Ad9zjpbgYpzLNtRCXfhPYR')
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "authenticated": true,
    "cxn_id": "cxn_xr86xHEcWmpmB",
    "accounts": [
      "acc_jPXLFqd6KzH3N",
      "acc_DALLeLrj3TH8h"
    ],
    "entity_id": "ent_GWKYtnFyE79db",
    "events": [
      {
        "type": "open",
        "metadata": {
          "element_type": "connect",
          "op": "open"
        },
        "timestamp": "2024-04-25T02:35:28.097Z"
      },
      {
        "type": "success",
        "metadata": {
          "entity_id": "ent_GWKYtnFyE79db",
          "accounts": [
            "acc_jPXLFqd6KzH3N",
            "acc_DALLeLrj3TH8h"
          ],
          "element_type": "connect",
          "op": "success"
        },
        "timestamp": "2024-04-25T02:35:57.120Z"
      },
      {
        "type": "exit",
        "metadata": {
          "element_type": "connect",
          "op": "exit"
        },
        "timestamp": "2024-04-25T02:35:57.138Z"
      }
    ]
  }
  ```
</ResponseExample>


# Launching a Connect Session
Source: https://docs.methodfi.com/elements/connect/launch_connect



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

After creating a Connect Element token, you can launch a Connect session in a webview.

## Initializing the Connect Element

The Connect Element is optimized to work within Webviews, including on iOS and Android. Open a webview in your app to your desired environment using the `element_token` you generated.

Example:

Using the [Element SDK](/elements/libraries) (recommended):

```javascript theme={null}
method.open('pk_elem_BtzySdrQGFmLdAPw5gXSQNCxQkhCkT3K');
```

Without SDK:

```bash theme={null}
https://elements.production.methodfi.com/
  ?token=pk_elem_4PpMTPcchb49VBjwP3bREKhMN93hrQHR
```


# Connect Overview
Source: https://docs.methodfi.com/elements/connect/overview



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Connect is the primary way to leverage Method Elements to connect your users' liabilities. Connect allows you to verify a user's identity, gather their consent, and complete any needed verifications to ensure their accounts are connected to the desired Method [Products](/reference/accounts/products/overview).

The Connect element itself consists of two main steps:

<Steps>
  <Step title="Auth">
    Verify the user's identity and connect their accounts. If no entity
    information is provided when creating the Connect element token, the user
    will be asked to provide identity information such as name, phone, last 4
    digits of SSN, DOB, or address.
  </Step>

  <Step title="Account Verification">
    Request any additional information needed from the user to connect their
    accounts and leverage specific products.
  </Step>
</Steps>


# Environments
Source: https://docs.methodfi.com/elements/environments



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Elements are available in each of our three [Environments](/reference/environments):

```
https://elements.dev.methodfi.com (Development)
https://elements.sandbox.methodfi.com (Sandbox)
https://elements.production.methodfi.com (Production)
```

## Considerations for Connect

When using the [Connect Element](/elements/connect/overview), there are a few
things to keep in mind related to the different environments.

### Development Environment

In dev, you can use the following phone numbers to ensure your entity gets verified:

```bash theme={null}
Phone        | Required Fields
------------------------------
+15121231111 | Name, Phone
+15121231112 | Name, Phone, DOB (Date of Birth)
+15121231113 | Name, Phone, DOB (Date of Birth), Address
```

You can either pass in the required fields on token creation or during the Connect session.

**Note**: If you do not use one of the above phone numbers, your dev entities will not be verified.


# General Events
Source: https://docs.methodfi.com/elements/events/general_events



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

## Open

The open event is triggered when an element has successfully launched. No additional data is passed at this time.

```bash theme={null}
methodelements://general
  ?op=open
  &element_type=connect
```

The event payload will have the following form:

<ParamList />

## Error

The error event is sent for any element that encounters any error while it's active.

```bash theme={null}
methodelements://general
  ?op=error
  &element_type=unknown
  &type=INVALID_REQUEST
  &sub_type=EXPIRED_TOKEN
  &message=The public element token is no longer valid. Element tokens are short lived and can only be used once. Request a new element token and try your request again.
  &code=400
```

The event payload will have the following form:

<ParamList />

## Exit

The exit event is the last event in the element flow, at this point your app should no longer present the Method Element. Exit is triggered after an error, a user requested exit or a successful element event.

```bash theme={null}
methodelements://general
  ?op=exit
  &element_type=connect
```

The event payload will have the following form:

<ParamList />


# Events Overview
Source: https://docs.methodfi.com/elements/events/overview



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Communication between the Element and your app can be handled either by PostMessage communication or via HTTP redirects.

## Listening to Events

We strongly recommend using one of the [Element SDKs](/elements/libraries) to make listening to events easy. They provide you with callback functions that are invoked every time a specific type of event occurs (such as `open`, `success`, `exit`, etc).

Each type of Element will emit its own events. See [General Events](/elements/events/general_events) and [Element Specific Events](/elements/events/specific_events) for more information about the events that are emitted.

### PostMessage without SDK

To receive events via PostMessage, pass the query parameter `event_channel=message` to the Elements url. For example:

```bash theme={null}
https://elements.production.methodfi.com
  ?token=pk_elem_4PpMTPcchb49VBjwP3bREKhMN93hrQHR
  &event_channel=message
```

To listen to the emitted events, add an event listener onto the window object:

```javascript theme={null}
window.addEventListener('message', function(event) {
  const { payload, type } = event.data;
  console.log('Received event!', type, payload);
});
```

### Redirects

Redirects are the default way of listening to element events if you are not using one of the SDKs. Your webview / app should intercept the redirects in order to react accordingly to state changes. All redirect URLs will have the scheme ("prefix") `methodelements`. The event source will be the URL host and the payload will be query strings.

HTTP redirects from Method Elements are in the following format:

```bash theme={null}
methodelements://{event_source}?{event_data}
```


# Element Specific Events
Source: https://docs.methodfi.com/elements/events/specific_events



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

## Connect

Connect will emit a `success` event when the user has successfully completed all required authentication and verification:

```bash theme={null}
methodelements://connect
  ?op=success
  &element_type=connect
  &entity_id=ent_WyDmJnQgaxVRH
  &accounts=["acc_PFUNazUbpUpfm","acc_gjWr4Cb8H7TLz"]
```

When parsed, will result in the following JSON

```json theme={null}
{
  "op": "success",
  "element_type": "connect",
  "entity_id": "ent_WyDmJnQgaxVRH",
  "accounts": ["acc_PFUNazUbpUpfm","acc_gjWr4Cb8H7TLz"]
}
```

This will list all of the accounts that were consented and connected to at least one of the products passed into the Element token creation (Note: Some accounts are ineligible for some products).

## Other Events

For more granular information about specific actions a user is taking, `auth` and `account_verification` will emit the following events.

### Auth

Auth will emit a variety of events that describe how the user is progressing through the authentication process. Most events are of the following form:

```bash theme={null}
AUTH_{STEP}_{ACTION}
```

STEP will reference a step during the auth process: `INTRO`, `NAME`, `PHONE`, `PHONE_VERIFY`, `DOB`, `ADDRESS`, `SSN4`, `SECQ`, and `CONSENT`.

ACTION will refer to the action the user took: `OPEN`, `CONTINUE`, `SUBMIT`, and `CLOSE`.

**Note**: Not all steps will have all actions, and that there are a few actions that do not follow this pattern

For example, if the user was prompted for the last 4 of their SSN, then submitted their info and was directed to the DOB page, you would see the following events:

```bash theme={null}
AUTH_SSN4_OPEN
AUTH_SSN4_CONTINUE
AUTH_DOB_OPEN
```

### Account Verification

Account Verification will emit a variety of events using a similar structure to auth:

```bash theme={null}
AVF_{STEP}_{ACTION}
```

STEP will reference a step during the account verification process: `ACCOUNT_LIST`, `LEARN_MORE`, and `ACCOUNT_VERIFY`.

ACTION will refer to the action the user took: `OPEN`, `CONTINUE`, `SUBMIT`, `SKIP`, and `CLOSE`.

For example, if the user was prompted to verify their credit card, then submitted their info and was directed to the success screen, you would see the following events:

```bash theme={null}
AVF_ACCOUNT_VERIFY_OPEN
AVF_ACCOUNT_VERIFY_SUBMIT
AVF_SUCCESS_OPEN
```


# Element SDKs
Source: https://docs.methodfi.com/elements/libraries



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Method offers a variety of libraries for your frontend application to make integrating
with Elements easy and simple. We also offer [backend libraries](TODO:Where_is_link)
to help manage token creation and using the API more broadly.

## Frontend Libraries

Depending on your application, Method offers three different frontend libraries to help you integrate with Element:

1. [method-js](https://docs.methodfi.com/libraries/js-sdk), for vanilla JavaScript applications
2. [react-method-elements](https://github.com/MethodFi/react-method-elements), for React applications
3. [react-native-method-elements](https://github.com/MethodFi/react-native-method-elements), for React Native applications


# Overview
Source: https://docs.methodfi.com/elements/overview



<Warning>
  Method Elements will no longer be supported or maintained beginning December
  31st, 2025. We recommend using [Method Opal](/opal/overview) for all new
  integrations. If you are currently using Elements, please reach out to your
  CSM to discuss your migration options.
</Warning>

Method Elements is a collection of embeddable UI components that make it easy to
integrate Method's API into your experience. Using Method Elements, you can
securely identify your users, connect their liabilities, and move money across
accounts.

## Using Method Elements

<Steps>
  <Step title="Create Element Token">
    Your app's backend will generate an `element_token` by hitting the
    [/elements/token](/reference/elements/tokens) endpoint.
  </Step>

  <Step title="Initialize Element">
    Using the `element_token`, Method Elements will be
    [initialized](/elements/libraries) with the intended Element for your user.
  </Step>

  <Step title="Handling Element Events">
    While your user interacts with an Element,
    [events](/elements/events/overview) will be triggered for your app to
    handle.
  </Step>
</Steps>

### Authentication

Ensure you have an [API key created](/reference/authentication) for your organization in order to request an Element token.


# Overview
Source: https://docs.methodfi.com/libraries/overview



Method offers a list of official libraries that help developers easily
interact and build on top of the Method services.

## API client Libraries

Below is a list of libraries for each supported programming language. These
libraries are updated frequently to provide the best developer experience
when interacting with the Method API.

<CardGroup>
  <Card title="Node.js" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/nodejs-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=57e4626e40345a82da3e7effb6ab274a" />} href="https://github.com/MethodFi/method-node" />

  <Card title="Python" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/python-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=2e67dd38fef1f2c7d80ce0e422f6943c" />} href="https://github.com/MethodFi/method-python" />

  <Card title="OpenAPI" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/openapi-logo.svg?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=96448d2076f343383dd60886f7eebc20" />} href="https://github.com/MethodFi/openapi" />
</CardGroup>

## Element client libraries

Method supports a list of frontend libraries to make integrating Element
into your applications more seamless.

<CardGroup>
  <Card title="Javascript" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/js-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=ea0213b8187f61bcb5c5ecb75abd29f8" />} href="/libraries/js-sdk" />

  <Card title="React" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/react-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=9c683655cfe19c265ac9f077575b7a9e" />} href="https://github.com/MethodFi/react-method-elements" />

  <Card title="React Native" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/react-native-logo.svg?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=a3157c02adfdff112505e4c6ed5d91b0" />} href="https://github.com/MethodFi/react-native-method-elements" />
</CardGroup>

## Quickstart and examples

We've built a couple of quickstart applications to help you get started with
seamlessly building on top of Method.

<CardGroup>
  <Card title="Postman" icon={<img src="https://mintcdn.com/methodfinancial/jNDQclcryTYLBNlO/images/libraries/postman-logo.png?fit=max&auto=format&n=jNDQclcryTYLBNlO&q=85&s=e23ad5829a5ea39ac00b25fcc1a34b4d" />} href="https://www.postman.com/methodfi/method-api/collection/8d5j00b/method-api-v2" />
</CardGroup>


# Account Verification
Source: https://docs.methodfi.com/opal/account_verification/overview



<Note>Mode: `account_verification`</Note>

Opal Account Verification is a pre-built flow for verifying a specific account. It provides a secure, compliant way to verify a single, known account (for example, a specific credit card).

<img alt="account-verification-hero" />

## What this mode does

Account Verification drives a focused verification flow for a single, known account (for example, a specific credit card). You must pass the target account\_id. Account Verification will automatically be invoked when needed (for example, during card\_connect), or can be used as a standalone module.

## Parameters

<ParamList />

## Create a token

You can create an account verification session token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `account_verification`
* Create new entity: provide `entity` + `mode` + `account_verification`
* Resume session: provide `session_id` only (omit `mode` and `account_verification`)

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "account_verification",
  "account_verification": { "account_id": "acc_..." }
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15125551234"
    }
  },
  "mode": "account_verification",
  "account_verification": { "account_id": "acc_..." }
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "valid_until": "2025-06-10T22:50:53.024Z",
  "session_id": "osess_..."
}
```

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Verify account</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Verify account" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>


# Card Connect
Source: https://docs.methodfi.com/opal/card_connect/overview



<Note>Mode: `card_connect`</Note>

Opal Card Connect is the primary way to connect user credit cards with Method.
This pre-built flow gathers a user's consent, verifies their identity, and completes any needed verifications to ensure their cards are connected to the Method ecosystem.

<img alt="account-verification-hero" />

## What this mode does

Card Connect lets users select and verify credit cards. Configure whether users may select a single card or multiple cards. Verified cards are eligible for payments and transactions.

## Parameters

<ParamList />

## Create a token

You can create a card connect session token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `card_connect`
* Create new entity: provide `entity` + `mode` + `card_connect`
* Resume session: provide `session_id` only (omit `mode` and `card_connect`)

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "card_connect",
  "card_connect": {
    "selection_type": "single",
    "account_filters": {
      "exclude": {
        "mch_ids": ["mch_123"],
        "unverified_account_numbers": true
      }
    }
  }
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15125551234"
    }
  },
  "mode": "card_connect",
  "card_connect": {
    "selection_type": "multiple"
  }
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "valid_until": "2025-06-10T22:50:53.024Z",
  "session_id": "osess_..."
}
```

## Testing in Development

When testing the frontend for Card Connect in the dev environment, use the following test values:

* **Verification code**: When the modal prompts you to enter a six-digit verification code, you can use any six-digit code. For example: `123456`. This applies to any test case (e.g. identity verification, connect, etc.).
* **Card verification**: Select the Chase card ending in `1580` and use `878` as the CVV.

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Connect Card</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Connect Card" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>


# Connect
Source: https://docs.methodfi.com/opal/connect/overview



<Note>Mode: `connect`</Note>

Opal Connect is the primary way to connect user liability accounts with Method.
This pre-built flow gathers a user's consent, verifies their identity, and completes any needed verifications to ensure their accounts are connected to the Method ecosystem.

<img alt="connect-hero" />

## What this mode does

Connect lets users find and connect their liability accounts (credit cards, loans, mortgages, etc.). Configure whether users may select a single account, multiple accounts, or by default select all eligible accounts.

## Parameters

<ParamList />

## Create a token

You can create a connect session token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `connect`
* Create new entity: provide `entity` + `mode` + `connect`
* Resume session: provide `session_id` only (omit `mode` and `connect`)

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "connect",
  "connect": {
    "selection_type": "single",
    "account_filters": {
      "include": {
        "account_types": ["credit_card", "auto_loan"],
        "products": ["balance"]
      }
    }
  }
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15125551234"
    }
  },
  "mode": "connect",
  "connect": {
    "selection_type": "multiple",
    "account_filters": {
      "exclude": {
        "account_types": ["personal_loan"],
        "mch_ids": ["mch_123"],
        "unverified_account_numbers": true
      }
    }
  }
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "valid_until": "2025-06-10T22:50:53.024Z",
  "session_id": "osess_..."
}
```

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Connect Accounts</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Connect Accounts" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>


# Opal Events
Source: https://docs.methodfi.com/opal/events



Communication between Opal and your app is handled through a consistent, mode-aware event system. Events are emitted throughout the user session to indicate progress, completion, errors, and important milestones.

## Listening to Events

We strongly recommend using one of the Opal SDKs to receive typed events and lifecycle callbacks. The SDKs provide `onEvent`, `onOpen`, and `onExit` handlers and expose a small enum of well-known events under `OpalEventType` for convenience (e.g., `SESSION_STARTED`, `SESSION_COMPLETED`).

Each Opal mode (`identity_verification`, `connect`, `card_connect`, `account_verification`, `transactions`) emits a set of mode‑specific events in addition to default session events. See below for structure, a complete list, and examples.

## Event Structure

All Opal events follow a consistent structure:

```json theme={null}
{
  "type": "opal.session.started",
  "mode": "opal",
  "object": "session",
  "action": "started",
  "timestamp": "2025-06-10T22:50:53.024Z",
  "data": null
}
```

### Event fields

| Field       | Type           | Description                                                                                                     |
| ----------- | -------------- | --------------------------------------------------------------------------------------------------------------- |
| `type`      | string         | Fully qualified event name: `<flow>.<object>.<action>` or `opal.session.<action>` for default session events.   |
| `mode`      | string         | The active operational mode (e.g., `connect`, `identity_verification`, `account_verification`, `transactions`). |
| `object`    | string         | The related object (e.g., `session`, `flow`, `step`, `identity`, `card`, `accounts`).                           |
| `action`    | string         | The action that occurred (e.g., `started`, `completed`, `verified`, `errored`).                                 |
| `timestamp` | string         | ISO 8601 timestamp of when the event occurred.                                                                  |
| `data`      | object \| null | Additional context that varies by event type; may be `null` for lifecycle events.                               |

### Possible flows:

* `identity_verification`
* `connect`
* `account_verification`
* `transactions`

## Sample Events

### opal.session.started

```json theme={null}
{
  "type": "opal.session.started",
  "mode": "connect",
  "object": "session",
  "action": "started",
  "timestamp": "2025-06-10T22:50:53.024Z",
  "data": null
}
```

### opal.session.errored

```json theme={null}
{
  "type": "opal.session.errored",
  "mode": "connect",
  "object": "session",
  "action": "errored",
  "timestamp": "2025-06-10T22:50:53.024Z",
  "data": {
    "type": "INVALID_REQUEST",
    "sub_type": "INVALID_SMS_CODE",
    "message": "Invalid request please try again"
  }
}
```

### connect.flow\.completed

```json theme={null}
{
  "type": "connect.flow.completed",
  "mode": "connect",
  "object": "flow",
  "action": "completed",
  "timestamp": "2025-06-10T22:50:53.024Z",
  "data": {
    "accounts": ["acc_ge9hxMTPGdXmQ"],
    "entity_id": "ent_wrDBN43PR8LKC"
  }
}
```

## Event Categories

### Default session events (always available)

* `opal.session.started` - Opal UI opened and session began
* `opal.session.completed` - User completed the flow successfully
* `opal.session.errored` - A recoverable or terminal error occurred
* `opal.session.exited` - User exited or dismissed Opal

### Generic flow and step events

Emitted in addition to the default session events. These mirror the active mode‑specific events but are prefixed with `opal` and can be emitted for any mode.

#### Flow

* `opal.flow.started` - A sub‑flow of Opal started (e.g., identity verification, account selection, verification).
* `opal.flow.completed` - A sub‑flow of Opal completed. This does not always signify the end of the session; use `opal.session.completed` to detect when Opal is fully completed.

#### Step

* `opal.step.started` - A new step started (e.g., phone input, card selection, CVV input).
* `opal.step.completed` - A step completed and the next page is opening.

Notes:

* Additional mode-specific events may be introduced over time. Your handler should use the `OpalEventType` enum to handle the specific cases you need.

## All Event Types

The following table lists all currently supported event types with their `OpalEventType` mapping, and when they are typically emitted.

| Event (OpalEventType - type)                                              | When you might see it                              |
| ------------------------------------------------------------------------- | -------------------------------------------------- |
| `SESSION_STARTED` - `opal.session.started`                                | Opal UI opened and session began.                  |
| `SESSION_COMPLETED` - `opal.session.completed`                            | User completed the overall Opal flow successfully. |
| `SESSION_ERRORED` - `opal.session.errored`                                | A recoverable or terminal error occurred.          |
| `SESSION_EXITED` - `opal.session.exited`                                  | User closed or dismissed Opal before completion.   |
| `FLOW_STARTED` - `opal.flow.started`                                      | A sub-flow (for any mode) started.                 |
| `FLOW_COMPLETED` - `opal.flow.completed`                                  | A sub-flow (for any mode) completed.               |
| `STEP_STARTED` - `opal.step.started`                                      | A step (screen) started.                           |
| `STEP_COMPLETED` - `opal.step.completed`                                  | A step (screen) completed.                         |
| `IDV_FLOW_STARTED` - `identity_verification.flow.started`                 | Identity Verification flow started.                |
| `IDV_STEP_STARTED` - `identity_verification.step.started`                 | A step in Identity Verification started.           |
| `IDV_STEP_COMPLETED` - `identity_verification.step.completed`             | A step in Identity Verification completed.         |
| `IDV_FLOW_COMPLETED` - `identity_verification.flow.completed`             | Identity Verification flow completed.              |
| `IDV_VERIFICATION_COMPLETED` - `identity_verification.identity.completed` | Identity successfully verified (KYC passed).       |
| `CXN_FLOW_STARTED` - `connect.flow.started`                               | Connect flow started.                              |
| `CXN_STEP_STARTED` - `connect.step.started`                               | A step in Connect started.                         |
| `CXN_STEP_COMPLETED` - `connect.step.completed`                           | A step in Connect completed.                       |
| `CXN_FLOW_COMPLETED` - `connect.flow.completed`                           | Connect flow completed.                            |
| `CXN_ACCOUNTS_SELECTED` - `connect.accounts.selected`                     | User selected one or more accounts to connect.     |
| `AVF_FLOW_STARTED` - `account_verification.flow.started`                  | Account Verification flow started.                 |
| `AVF_STEP_STARTED` - `account_verification.step.started`                  | A step in Account Verification started.            |
| `AVF_STEP_COMPLETED` - `account_verification.step.completed`              | A step in Account Verification completed.          |
| `AVF_FLOW_COMPLETED` - `account_verification.flow.completed`              | Account Verification flow completed.               |
| `AVF_CARD_VERIFIED` - `account_verification.card.verified`                | Card verified successfully.                        |
| `TXN_FLOW_STARTED` - `transactions.flow.started`                          | Transactions flow started.                         |
| `TXN_STEP_STARTED` - `transactions.step.started`                          | A step in Transactions started.                    |
| `TXN_STEP_COMPLETED` - `transactions.step.completed`                      | A step in Transactions completed.                  |
| `TXN_FLOW_COMPLETED` - `transactions.flow.completed`                      | Transactions flow completed.                       |
| `TXN_ACCOUNTS_LINKED` - `transactions.accounts.linked`                    | Accounts linked and subscribed for transactions.   |

### Data Payloads

The following events always include a non-null `event.data` payload:

* `identity_verification.identity.completed`
* `connect.accounts.selected`
* `account_verification.card.verified`
* `transactions.accounts.linked`

Use these payloads to retrieve context such as selected accounts, verification results, or linkage details.

## Enhanced Event Handling

### Using the JavaScript SDK

```javascript theme={null}
import { OpalEventType } from '@methodfi/opal-react';

const config = {
  onEvent: (event) => {
    console.log("Event received:", event.type);

    // Handle specific events using the OpalEventType enum
    switch (event.type) {
      case OpalEventType.SESSION_STARTED:
        // Session lifecycle
        break;
      case OpalEventType.SESSION_COMPLETED:
        // Entire Opal session completed successfully
        break;
      case OpalEventType.SESSION_ERRORED:
        // Handle recoverable or terminal error
        console.error("Opal error:", event.data);
        break;
      case OpalEventType.IDV_VERIFICATION_COMPLETED:
        // Identity verification completed; payload contains verification details
        handleIdentityVerified(event.data);
        break;
      case OpalEventType.CXN_ACCOUNTS_SELECTED:
        // User selected accounts in Connect
        handleAccountsSelected(event.data);
        break;
      case OpalEventType.AVF_CARD_VERIFIED:
        // Card verified in Account Verification
        handleCardVerified(event.data);
        break;
      case OpalEventType.TXN_ACCOUNTS_LINKED:
        // Accounts linked for Transactions
        handleAccountsLinked(event.data);
        break;
      default:
        // Optionally handle generic flow/step events
        break;
    }
  },

  // Specific event handlers
  onSuccess: (payload) => {
    // Called for successful completion events
    console.log("Success:", payload);
  },

  onError: (error) => {
    // Enhanced error handling with detailed information
    console.error("Error:", error.code, error.message);
    console.error("Details:", error.details);
  },
};

const opal = new MethodOpal(config);
```

## PostMessage Communication

For applications not using the Opal SDKs, you can listen to events via PostMessage:

### Setup PostMessage Listener

```javascript theme={null}
window.addEventListener("message", function (event) {
  // Verify origin for security
  if (event.origin !== "https://opal.production.methodfi.com") {
    return;
  }

  const opalEvent = event.data;
  console.log("Opal event:", opalEvent.type, opalEvent.data);

  // Handle events
  switch (opalEvent.type) {
    case OpalEventType.SESSION_STARTED:
      console.log("Opal started");
      break;
    case OpalEventType.SESSION_COMPLETED:
      console.log("Opal completed:", opalEvent.data);
      break;
  }
});
```

## Best Practices

### Event Handling

* Always verify event origins for security
* Use event filtering to reduce noise
* Implement proper error handling for all events
* Log events for debugging and analytics

### Security

* Validate all event data before processing
* Never trust client-side events for critical business logic


# Identity Verification
Source: https://docs.methodfi.com/opal/identity/overview



<Note>Mode: `identity_verification`</Note>

Opal Identity Verification is a pre-built flow for verifying user identity. It provides a secure, compliant way to collect and verify personal information like name, date of birth, address, and other identity details needed for KYC/AML requirements.

<img alt="identity-hero" />

## What this mode does

Identity Verification collects, confirms, and verifies a user's identity details (name, DOB, address, phone, SSN if needed). Users must explicitly confirm their details before verification challenges begin. Identity Verification will automatically be invoked when needed, or can be used as a standalone module.

## Parameters

<ParamList />

## Create a token

You can create an identity verification session token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `identity_verification`
* Create new entity: provide `entity` + `mode` + `identity_verification`
* Resume session: provide `session_id` only (omit `mode` and `identity_verification`)

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "identity_verification",
  "identity_verification": {
    "skip_pii": ["name", "dob", "address"]
  }
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15125551234"
    }
  },
  "mode": "identity_verification",
  "identity_verification": {
    "skip_pii": []
  }
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "valid_until": "2025-06-10T22:50:53.024Z",
  "session_id": "osess_..."
}
```

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Verify identity</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({ env: "dev", onEvent: (e) => {} });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Verify identity" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>


# Libraries
Source: https://docs.methodfi.com/opal/libraries



Method offers a variety of libraries for your frontend application to make integrating with Opal easy and simple.

## Frontend Libraries

Depending on your application, Method offers multiple frontend libraries to help you integrate with Opal:

<CardGroup>
  <Card title="JavaScript SDK" icon="js" href="https://static.methodfi.com/opal/v1/stable/init.js">
    For vanilla JavaScript applications
  </Card>

  <Card title="React SDK" icon="react" href="https://www.npmjs.com/package/@methodfi/opal-react">
    For React applications
  </Card>

  <Card title="React Native SDK" icon="mobile" href="https://www.npmjs.com/package/@methodfi/opal-react-native">
    For React Native applications
  </Card>
</CardGroup>

All Opal SDKs provide:

* **Token Management**: Automatic token validation and refresh
* **Event Handling**: Comprehensive event system with typed callbacks
* **Error Management**: Enhanced error handling with detailed error codes
* **Security**: Built-in security features and validation

## Installation

<Tabs>
  <Tab title="JavaScript">
    ```html theme={null}
    <script src="https://static.methodfi.com/opal/v1/stable/init.js"></script>
    ```
  </Tab>

  <Tab title="React">
    ```bash theme={null}
    npm install @methodfi/opal-react
    ```

    ## Quick usage: React (Web)

    ```tsx theme={null}
    import { OpalProvider, useOpal, OpalEventType } from "@methodfi/opal-react";

    export default function App() {
      return (
        <OpalProvider>
          <YourApp />
        </OpalProvider>
      );
    }

    function YourApp() {
      const { open, close, isOpen, error } = useOpal({
        env: "dev",
        onOpen: () => {},
        onExit: () => {},
        onEvent: (event) => {
          switch (event.type) {
            case OpalEventType.SESSION_STARTED:
              // ...
              break;
            case OpalEventType.SESSION_COMPLETED:
              // ...
              break;
            case OpalEventType.SESSION_ERRORED:
              // ...
              break;
            case OpalEventType.SESSION_EXITED:
              // ...
              break;
          }
        },
      });

      const onLaunchOpal = async () => {
        const token = await getOpalToken(); // POST /opal/token
        open({ token });
      };

      return <button onClick={onLaunchOpal}>Launch Opal</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```bash theme={null}
    npm install @methodfi/opal-react-native
    ```

    ## Quick usage: React Native (Mobile)

    ```tsx theme={null}
    import {
      OpalProvider,
      useOpal,
      OpalEventType,
    } from "@methodfi/opal-react-native";

    export default function App() {
      return (
        <OpalProvider>
          <YourScreen />
        </OpalProvider>
      );
    }

    function YourScreen() {
      const { open } = useOpal({
        env: "dev",
        onOpen: () => {},
        onExit: () => {},
        onEvent: (event) => {
          switch (event.type) {
            case OpalEventType.SESSION_STARTED:
              // ...
              break;
            case OpalEventType.SESSION_COMPLETED:
              // ...
              break;
            case OpalEventType.SESSION_ERRORED:
              // ...
              break;
            case OpalEventType.SESSION_EXITED:
              // ...
              break;
          }
        },
      });

      const onLaunchOpal = async () => {
        const token = await getOpalToken(); // POST /opal/token returns otkn_*
        open({ token });
      };

      return <Button title="Launch Opal" onPress={onLaunchOpal} />;
    }
    ```
  </Tab>
</Tabs>

## Testing in Development

When testing the Opal frontend in the dev environment, any modal step that prompts you to enter a six-digit verification code will accept any six-digit code. For example: `123456`.

## Notes

* Event types follow the format `<flow>.<object>.<action>` or `opal.session.<action>` for defaults
* See [Events](/opal/events) for structure and sample payloads


# Migration from Elements
Source: https://docs.methodfi.com/opal/migration_guide



When migrating from Elements to Opal, there are several key changes to consider:

## URL Changes

If you're launching Opal directly from a URL, the process remains similar to Elements, but with updated domains:

* Elements: `elements.{environment}.methodfi.com`
* Opal: `opal.{environment}.methodfi.com`

## New Libraries

We've introduced new SDKs specifically designed for Opal integration:

* [@methodfi/opal-react](https://www.npmjs.com/package/@methodfi/opal-react) for React applications
* [@methodfi/opal-react-native](https://www.npmjs.com/package/@methodfi/opal-react-native) for React Native
* Direct CDN integration via `https://static.methodfi.com/opal/v1/stable/init.js`

See our [libraries documentation](/opal/libraries) for detailed implementation guides.

## Token Generation Changes

When generating tokens for Opal, we've added new parameters that must be provided in order for more flexibility and control over the user experience. The token generation process has been streamlined in Opal.

### Elements

```json theme={null}
POST /elements/token
{
  "type": "connect",
  "connect": {
    "entity_id": "ent_au22b1fbFJbp8",
    "products": ["balance"],
    "redirect_url": "https://example.com/callback"
  }
}
```

### Opal

```json theme={null}
POST /opal/token
{
  "mode": "connect",
  "entity_id": "ent_au22b1fbFJbp8",
  "connect": {
    "selection_type": "single",
    "account_filters": {
      "include": {
        "account_types": ["credit_card", "auto_loan"],
        "products": ["balance"]
      }
    }
  }
}
```

In Elements, product filtering was a top-level field (`connect.products`). In Opal, product filtering is done via `connect.account_filters.include.products`. Allowed values: `balance`, `sensitive`, `payoff`, `update`, `payment`.

See Opal [Identity](/opal/identity/overview), [Connect](/opal/connect/overview), [Card Connect](/opal/card_connect/overview), and [Account Verification](/opal/account_verification/overview) guides for more info on token generation.


# Overview
Source: https://docs.methodfi.com/opal/overview

Method Opal - Next-generation embeddable financial components

Method Opal is the single embeddable UI component that provides enhanced
financial connectivity and user experience. Opal serves as a modern replacement
for Method Elements, offering improved performance, better customization, and
advanced features for integrating Method's API into your application.

<img alt="title" />

## What is Opal?

Method's embedded financial platform, with built-in orchestration of
identity, account connection, verification, and transaction streaming- all
in one cohesive experience for end-users.

## Using Method Opal

<Steps>
  <Step title="Create an Entity">
    Create an entity for your user using the
    [Entities](/reference/entities/overview) endpoint.
  </Step>

  <Step title="Create Opal Token">
    Generate an Opal Token by using the [Create Token](/reference/opal/create_token#create-token)
    endpoint.
  </Step>

  <Step title="Launch Opal">
    Using the Opal Token, launch Opal with one of our
    [libraries](/opal/libraries) to launch the intended Opal component for your
    user. Method will handle the rest!
  </Step>

  <Step title="Optional: Handle Opal Events">
    While your user interacts with an Opal component,
    [events](/opal/events) will be triggered for your app to handle.
  </Step>
</Steps>

## Opal Modes

Opal provides several pre-built modes for different use cases:

### [Identity Verification](/opal/identity/overview)

Collect and verify user identity only.

### [Connect](/opal/connect/overview)

Connect user liability accounts.

### [Card Connect](/opal/card_connect/overview)

Verify and connect cards for access to payments.

### [Account Verification](/opal/account_verification/overview)

Verify account ownership with real-time verification.

### [Transactions](/opal/transactions/overview)

Stream transactions for a user's credit cards.

## Understanding Modes and Flows

Opal Modes are typically made up of one or more flows. Modes are the different types of Opal components that can be launched, while flows are the different stages within a mode. For example, the Card Connect mode has a flow for identity verification (`identity_verification`), account selection (`connect`), and verification (`account_verification`).

## Getting Started

Ready to integrate Opal into your application? Start with our [Opal Libraries](/opal/libraries) to choose the right SDK for your platform!

<CardGroup>
  <Card title="Opal Libraries" href="/opal/libraries">
    Choose the right SDK for your platform
  </Card>

  <Card title="API Reference" href="/reference/opal/overview">
    Complete API documentation for Opal endpoints
  </Card>

  <Card title="Events Guide" href="/opal/events">
    Learn how to handle Opal events in your application
  </Card>
</CardGroup>


# Quickstart
Source: https://docs.methodfi.com/opal/quickstart

Get started with Method Opal in minutes

This quickstart guide will help you integrate Method Opal into your application in just a few steps. Opal provides enhanced performance, better security, and advanced features compared to Elements.

## Prerequisites

Before you begin, make sure you have:

* A Method account with API access
* Your Method API key
* A web application or development environment

## Step 1: Install the Opal SDK

Choose the appropriate SDK for your application:

<CodeGroup>
  ```html JavaScript (CDN) theme={null}
  <script src="https://static.methodfi.com/opal/v1/stable/init.js"></script>
  ```

  ```bash React theme={null}
  npm install @methodfi/opal-react
  ```

  ```bash React Native theme={null}
  npm install @methodfi/opal-react-native
  ```
</CodeGroup>

## Step 2: Create an Entity

First, create an entity for your user:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/entities \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "individual",
      "individual": {
        "first_name": "John",
        "last_name": "Doe",
        "phone": "+15121234567",
        "email": "john.doe@example.com"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const entity = await method.entities.create({
    type: "individual",
    individual: {
      first_name: "John",
      last_name: "Doe",
      phone: "+15121234567",
      email: "john.doe@example.com",
    },
  });
  ```

  ```python Python theme={null}
  entity = method.entities.create({
    'type': 'individual',
    'individual': {
      'first_name': 'John',
      'last_name': 'Doe',
      'phone': '+15121234567',
      'email': 'john.doe@example.com'
    }
  })
  ```
</CodeGroup>

## Step 3: Create an Opal Token

Create an Opal token for the Connect component:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/opal/token \
    -X POST \
    -H "Method-Version: 2026-03-30" \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "entity_id": "ent_fc92i43kc34",
      "mode": "connect",
      "connect": {
        "selection_type": "single",
        "account_filters": {
          "include": {
            "account_types": ["credit_card", "auto_loan"]
          }
        }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const { token, valid_until, session_id } = await method.opal.token.create({
    entity_id: entity.id,
    mode: "connect",
    connect: {
      selection_type: "single",
      account_filters: {
        include: {
          account_types: ["credit_card", "auto_loan"],
        },
      },
    },
  });
  ```

  ```python Python theme={null}
  res = method.opal.token.create({
    'entity_id': entity.id,
    'mode': 'connect',
    'connect': {
      'selection_type': 'single',
      'account_filters': {
        'include': {
          'account_types': ['credit_card', 'auto_loan']
        }
      }
    }
  })
  ```
</CodeGroup>

## Step 4: Initialize Opal in Your Frontend

<CodeGroup>
  ```html JavaScript (CDN) theme={null}
  <script src="https://static.methodfi.com/opal/v1/stable/init.js"></script>

  <button id="connect-button">Connect Your Account</button>

  <script>
    document
      .getElementById("connect-button")
      .addEventListener("click", async () => {
        // Get token from Method
        const response = await fetch(`${baseURL}/opal/token`, {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({
            entity_id: "ent_fc92i43kc34",
            mode: "connect",
            connect: {
              selection_type: "single",
              account_filters: {
                include: {
                  account_types: ["credit_card", "auto_loan"],
                },
              },
            },
          }),
        });
        const { token } = await response.json();

        // Open iframe with token
        const iframe = document.createElement("iframe");
        iframe.src = `https://opal.${env}$.methodfi.com?token=${token}`;
        iframe.style.width = "100%";
        iframe.style.height = "600px";
        iframe.style.border = "none";
        document.body.appendChild(iframe);
      });
  </script>
  ```

  ```jsx React theme={null}
  import { OpalProvider, useOpal } from "@methodfi/opal-react";

  function App() {
    return (
      <OpalProvider>
        <ConnectButton />
      </OpalProvider>
    );
  }

  function ConnectButton() {
    const { open } = useOpal();

    const handleConnect = async () => {
      // Get token from Method
      const response = await fetch(`${baseURL}/opal/token`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          entity_id: "ent_fc92i43kc34",
          mode: "connect",
          connect: {
            selection_type: "single",
            account_filters: {
              include: {
                account_types: ["credit_card", "auto_loan"],
              },
            },
          },
        }),
      });
      const { token } = await response.json();

      // Launch Opal
      open({ token });
    };

    return <button onClick={handleConnect}>Connect Your Account</button>;
  }
  ```

  ```jsx React Native theme={null}
  import { OpalProvider, useOpal } from "@methodfi/opal-react-native";
  import { Button } from "react-native";

  function App() {
    return (
      <OpalProvider>
        <ConnectButton />
      </OpalProvider>
    );
  }

  function ConnectButton() {
    const { open } = useOpal();

    const handleConnect = async () => {
      // Get token from Method
      const response = await fetch(`${baseURL}/opal/token`, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          entity_id: "ent_fc92i43kc34",
          mode: "connect",
          connect: {
            selection_type: "single",
            account_filters: {
              include: {
                account_types: ["credit_card", "auto_loan"],
              },
            },
          },
        }),
      });
      const { token } = await response.json();

      // Launch Opal
      open({ token });
    };

    return <Button title="Connect Your Account" onPress={handleConnect} />;
  }
  ```
</CodeGroup>

## Next Steps

Now that you have Opal working, explore these advanced features:

<CardGroup>
  <Card title="Advanced Configuration" href="/opal/connect/overview">
    Learn about advanced Opal Connect features and configuration options
  </Card>

  <Card title="Event Handling" href="/opal/events">
    Master Opal's comprehensive event system
  </Card>

  <Card title="Migration Guide" href="/opal/migration_guide">
    Migrate from Elements to Opal
  </Card>
</CardGroup>

### Getting Help

* **Documentation**: [Complete Opal Documentation](/opal/overview)
* **API Reference**: [Opal API Reference](/reference/opal/overview)
* **Support**: Contact your Method CSM


# Sessions
Source: https://docs.methodfi.com/opal/sessions

Maintain state and user data across Opal interactions.

Opal Sessions are long-lived stateful connections between your app and Opal.
They allow you to store user data, resume user sessions, and retrieve data later.
Sessions are created when you create an Opal Token, and when passed into Opal,
they are automatically resumed.

## Creating a new session

First, create a new Opal Token with your desired configuration. This will create a new session.

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/opal/token \
    -X POST \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "mode": "card_connect",
      "entity_id": "ent_fc92i43kc34",
      "card_connect": {
        "selection_type": "single"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "token": "otkn_THpBacqVBBrDkfqUf9htjm4QWAEJLY9a",
      "valid_until": "2025-05-08T22:21:40.312Z",
      "session_id": "osess_zde3mW34pEHqV"
    },
    "message": null
  }
  ```
</ResponseExample>

## Resuming an existing session

To resume an existing session, create a new token by passing the `session_id` from a previous session

<RequestExample>
  ```bash cURL theme={null}
  curl https://production.methodfi.com/opal/token \
    -X POST \
    -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
    -H "Content-Type: application/json" \
    -d '{
      "session_id": "osess_zde3mW34pEHqV"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "success": true,
    "data": {
      "token": "otkn_THpBacqVBBrDkfqUf9htjm4QWAEJLY9a",
      "valid_until": "2025-05-08T22:21:40.312Z",
      "session_id": "osess_zde3mW34pEHqV"
    },
    "message": null
  }
  ```
</ResponseExample>


# Transactions
Source: https://docs.methodfi.com/opal/transactions/overview



<Note>Mode: `transactions`</Note>

Opal Transactions is the primary way to obtain consent and subscribe to real-time transactions.
This pre-built flow gathers a user's consent, verifies their identity, and prompts them to select the accounts eligible to be subscribed to.

<img alt="transactions-hero" />

## What this mode does

Transactions will provide a seamless experience for a user to subscribe to real-time transaction updates for supported accounts.
Eligible accounts will be automatically determined by Method, including your team's eligibility criteria.

For details on how to receive transaction updates via [Webhooks](/reference/webhooks/create). Make sure you are subscribed to the relevant webhook events to receive real-time transaction data. Note that you will only receive updates for events that occur after your subscription is active.

Please reach out to your CSM to enable access to this mode!

## Create a token

You can create a transactions token using one of the supported patterns:

* Existing entity: provide `entity_id` + `mode` + `transactions`
* Create new entity: provide `entity` + `mode` + `transactions`

### Existing Entity

```json theme={null}
{
  "entity_id": "ent_...",
  "mode": "transactions",
  "transactions": {}
}
```

### Create New Entity

```json theme={null}
{
  "entity": {
    "type": "individual",
    "individual": {}
  },
  "mode": "transactions",
  "transactions": {}
}
```

### Response

```json theme={null}
{
  "token": "otkn_...",
  "session_id": "osess_...",
  "valid_until": "2025-06-10T22:50:53.024Z"
}
```

## Resuming a session

Want to link more cards? In this mode, simply create another token with the same `entity_id` and Method will intelligently pick up where your user left off. They won't ever be asked to link a card twice!

## Launch Opal

<Tabs>
  <Tab title="React (Web)">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react";

    function Screen() {
      const { open } = useOpal({
        env: "dev",
        onEvent: (e) => {},
        onExit: (e) => {},
      });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <button onClick={start}>Link Transactions</button>;
    }
    ```
  </Tab>

  <Tab title="React Native">
    ```tsx theme={null}
    import { OpalProvider, useOpal } from "@methodfi/opal-react-native";

    function Screen() {
      const { open } = useOpal({
        env: "dev",
        onEvent: (e) => {},
        onExit: (e) => {},
      });
      const start = async () => {
        const { token } = await getTokenFromBackend();
        open({ token });
      };
      return <Button title="Link Transactions" onPress={start} />;
    }
    ```
  </Tab>
</Tabs>