Retrieve an entity's debts

✨ Method Data allows you to retrieve all of an individual's debts regardless of financial institution using just their phone number.

Liabilities retrieved using Method Data are immediately payable using Method Payments and can receive real-time enhanced data directly from the financial institution or loan servicer using Method Sync

Steps

• Create an individual entity to represent your end-user.
• Create an Auth Element token for the entity to start the identity verification process.
• Launch the Auth Element with the created element token and complete the identity verification flow.
• Handle Auth Element events generated by the identity verification process.
• Retrieve the created liability accounts created from the connection.

---

1. Create an individual entity

First we'll create an individual entity. An entity is a representation of your end-user. To initiate a data retrieve session you'll need to provide, at a minimum, the end-user's first_name, last_name and a verified phone number.

Primer on capabilities

Capabilities are an indicator of an entities' status. For this flow we are interested in the data:retrieve capability. The location of data:retrieve in an entities' capability fields indicates the next steps.

tip

We recommend using Method's Auth Element as it will automatically handle the provisioning / activating of capabilities.

Field	Meaning	Next Steps
pending_capability	We were unable to find the individual using the provided data.	Provide more data using Entity Update endpoint or launch the Auth Element.
available_capability	Entity was successfully matched with the provided data.	Start the auth flow using Entity Auth Session endpoint or launch the Auth Element.
capability	Entity successfully completed the auth flow.	Retrieve all their debts using the Account endpoint.

caution

For building / testing in Method's dev environment, see Auth Element simulate requirements to determine what information should be submitted for an entity.

Request

cURL

POST /entities

curl https://production.methodfi.com/entities \
  -X POST \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "individual",
    "individual": {
      "first_name": "Kevin",
      "last_name": "Doyle",
      "phone": "+15121231111",
    }
  }'

Node.js

POST /entities

const entity = await method.entities.create({
  type: 'individual',
  individual: {
    first_name: 'Kevin',
    last_name: 'Doyle',
    phone: '+15121231111',
  },
});

Python

POST /entities

entity = method.entities.create({
  'type': 'individual',
  'individual': {
    'first_name': 'Kevin',
    'last_name': 'Doyle',
    'phone': '+15121231111'
  }
})

RESPONSE

{
  "id": "ent_au22b1fbFJbp8",
  "type": "individual",
  "individual": {
    "first_name": "Kevin",
    "last_name": "Doyle",
    "phone": "+15121231111",
    "dob": null,
    "email": null
  },
  "capabilities": [
    "payments:receive",
    "payments:send"
  ],
  "available_capabilities": [
    "data:retrieve"
  ],
  "pending_capabilities": [],
  ...
}

---

2. Create an Auth Element token

Now that we have an entity with the data:retrieve capability in either the pending_capabilities or available_capabilities property, we can create an Auth Element token.

💡 As a reminder, the Auth Element handles the provisioning / activating of capabilities it will prompt the user for KBA (knowledge-based authentication) questions and in rare-cases prompt for more information such as dob and address

info

If your organization is enrolled in Method's non-KBA authentication, the Method Auth element will automatically handle authentication without security questions.

This token will be used to launch the Auth Element in the next step.

Request

cURL

POST /elements/token

curl https://production.methodfi.com/elements/token \
  -X POST \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "ent_au22b1fbFJbp8",
    "team_name": "Demo Auth App",
    "type": "auth",
    "auth": {}
  }'

Node.js

POST /elements/token

const token = await method.elements.createToken({
  entity_id: 'ent_au22b1fbFJbp8',
  team_name: 'Demo Auth App',
  type: 'auth',
  auth: {},
});

Python

POST /elements/token

token = method.elements.create_token({
  'entity_id': 'ent_au22b1fbFJbp8',
  'team_name': 'Demo Auth App',
  'type': 'auth',
  'auth': {}
})

RESPONSE

{
  "element_token": "pk_elem_f3TZsKnmP7Q69bX65hRHngBEb8mT8gbG"
}

---

3. Launch the Auth Element

Next we'll launch the Auth Element with the created element_token by opening a webview (iframe) for the URL below. Where ENV refers to the environment in which you created the token (dev, sandbox, or production).

https://elements.{ENV}.methodfi.com?token=pk_elem_f3TZsKnmP7Q69bX65hRHngBEb8mT8gbG

Once launched, the Element will ask for credit-report based knowledge based authentication questions to validate the identity of the entity.

➡️ See launch auth element to learn how to implement the Auth Element within your app.

➡️ Use our client libraries (React + JS) to make integration seamless.

Dev Environment Details

If the token was created in the dev environment, provide the following information when the element prompts for it:

• First Name (any first name): Kevin
• Last Name (any last name): Doyle
• Phone: 5121231111
• Security Questions: Choose any "Correct" option for all questions.

Demo

The interactive demo below shows how the Auth Element flow works. This demo is running in the dev environment, so you can provide the Dev Environment Details mentioned above.

---

4. Handle Auth Element events

Method Elements communicate using callback (if using Method's client libraries) or HTTP redirect (if implemented within an iframe) Your webview / app should intercept the redirects in order to react accordingly to state changes.

When a user has successfully verified their identity, a success event will be sent back to your app.

HTTP / iFrame

methodelements://auth
  ?op=success
  &element_type=auth

React

const method = useMethod({
  env: 'production', 
  onEvent: (payload) => {},
  onSuccess: (payload) => {}, // Invoked when auth has successfully completed.
  onError: (payload) => {},
  onExit: (payload) => {},
  onOpen: (payload) => {},
});

Javascript

const config = {
  env: 'production', // dev | sandbox | production
  onEvent: (event) => {
    // Invoked for every event sent by the element.
    // Event is a native MessageEvent instance.
  },
  onSuccess: (payload) => {
    // Invoked when auth has successfully completed.
  },
  onError: (error) => {
    // Invoked when an error is raised during.
  },
  onExit: (payload) => {
    // Invoked when a user exits any element flow, or
    // immediately after an error is raised.
  },
  onOpen : (payload) => {
    // Invoked when an element has successfully launched.
  },
};

const method = new Method(config);

---

5. Retrieve the created liability accounts

Now we'll retrieve the accounts created from the entity's completed Auth Element / Auth Session endpoint. We'll use the entities' ID to retrieve all of the debts under their name.

The retrieved accounts created from this flow have the following capabilities:

• data:retrieve capability indicating that it was connected as part of this flow (Method Data).
• payments:receive capability indicating that the account is fully setup to be used for payments via Method Payments.
• data:sync capability indicating this liability can receive enhanced data and nightly data updates via Method Sync. ➡️ Learn more here.

Request

cURL

GET /accounts?holder_id={holder_id}

curl "https://production.methodfi.com/accounts?holder_id=ent_au22b1fbFJbp8" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"

Node.js

GET /accounts?holder_id={holder_id}

const accounts = await method.accounts.list({ holder_id: 'ent_au22b1fbFJbp8' });

Python

GET /accounts?holder_id={holder_id}

accounts = method.accounts.list({ 'holder_id': 'ent_au22b1fbFJbp8' })

RESPONSE

[
  {
    "id": "acc_XaDZc8tE4YVeJ",
    "holder_id": "ent_au22b1fbFJbp8",
    "type": "liability",
    "ach": null,
    "liability": {
      "mch_id": "mch_2347",
      "mask": "0966",
      "type": "auto_loan",
      "payment_status": "active",
      "data_status": "active",
      "data_last_successful_sync": "2022-06-14T15:13:02.546Z",
      "data_status_error": null,
      "data_source": "financial_institution",
      "data_updated_at": "2023-01-22T01:23:36.047Z",
      "ownership": "primary",
      "auto_loan": {
        "name": "Volvo Cars Auto Loan",
        "sub_type": "loan",
        "vin": "YV1CZ882XJ1234567",
        "balance": 6083960,
        "principal_balance": 6073960,
        "original_loan_amount": null,
        "opened_at": null,
        "payoff_amount": null,
        "payoff_amount_term": null,
        "last_payment_amount": 88800,
        "last_payment_date": "2022-05-12",
        "next_payment_due_date": "2022-06-01",
        "next_payment_minimum_amount": 88883,
        "term_length": 84,
        "interest_rate_percentage": 5.7,
        "interest_rate_type": "fixed",
        "interest_rate_source": "financial_institution",
        "delinquent_status": null,
        "delinquent_amount": null,
        "delinquent_period": null,
        "delinquent_action": null,
        "delinquent_start_date": null,
        "delinquent_major_start_date": null,
        "delinquent_status_updated_at": null,
        "delinquent_history": [],
        "mileage_allocation": null,
        "per_diem_amount": null,
      }
    },
    "status": "active",
    "capabilities": [
      "payments:receive",
      "data:retrieve"
    ],
    "available_capabilities": [
      "data:sync"
    ],
    "error": null,
    "created_at": "2022-02-16T00:47:32.508Z",
    "updated_at": "2022-02-16T00:47:32.508Z"
  },
  {
    "id": "acc_k5NzziUDg7hTg",
    "holder_id": "ent_au22b1fbFJbp8",
    "type": "liability",
    "liability": {
      "mch_id": "mch_183",
      "mask": "1580",
      "type": "credit_card",
      "payment_status": "active",
      "data_status": "active",
      "data_status_error": null,
      "data_last_successful_sync": "2023-01-22T01:23:36.047Z",
      "data_source": "financial_institution",
      "data_updated_at": "2023-01-22T01:23:36.047Z",
      "ownership": "authorized",
      "credit_card": {
        "name": "Chase Sapphire Reserve",
        "balance": 750014,
        "opened_at": "2016-11-25",
        "last_payment_date": "2022-12-28",
        "last_payment_amount": 451757,
        "next_payment_due_date": "2023-01-27",
        "next_payment_minimum_amount": 6500,
        "last_statement_balance": 650043,
        "remaining_statement_balance": 0,
        "available_credit": 1530000,
        "interest_rate_percentage": 23.5,
        "interest_rate_type": "variable",
        "interest_rate_source": "financial_institution",
        "past_due_status": "unknown",
        "past_due_balance": null,
        "past_due_date": null,
        "auto_pay_status": "unknown",
        "auto_pay_amount": null,
        "auto_pay_date": null,
        "sub_type": "flexible_spending",
        "term_length": null,
        "closed_at": null,
        "credit_limit": 2380000,
        "next_statement_date": "2022-12-02",
        "delinquent_status": null,
        "delinquent_amount": null,
        "delinquent_period": null,
        "delinquent_action": null,
        "delinquent_start_date": null,
        "delinquent_major_start_date": null,
        "delinquent_status_updated_at": null,
        "delinquent_history": []
      }
    },
    "status": "active",
    "capabilities": [
      "payments:receive",
      "data:retrieve"
    ],
    "available_capabilities": [
      "data:sync"
    ],
    "error": null,
    "created_at": "2022-02-16T02:56:19.548Z",
    "updated_at": "2022-02-16T02:56:19.548Z"
  },
  ...
]