Skip to main content

Identity verification

In lieu of using Method's Auth Element, you can use the Auth Session endpoint to automatically retrieve and link all of an individual entity's debts to Method. This additional verification will require the entity to answer a set of security questions that will verify their identity and ownership over those debts.

caution

Only entities with the data:retrieve in available_capabilities can continue with this guide. Refer back to the retrieve data capability section if you wish to follow this guide.

info

If your organization is enrolled in Method's non-KBA authentication, no questions will be returned in the Create Auth Session response.

Create an auth session​

The first step in verifying an entity's identity is creating an auth session. This request returns a list of security questions that the entity must correctly answer.

POST /entities/:entity_id/auth_session
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/auth_session \
  -X POST \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{}'
RESPONSE
{
  "questions": [
    {
      "id": "qtn_ywWqCnXDGGmmg",
      "text": "What is the monthly payment of your most recent auto loan or lease?",
      "answers": [
        {
          "id": "ans_qHLLEUBVpSpTK",
          "text": "$601 - $700"
        },
        {
          "id": "ans_b3xLiwTS8ygMy",
          "text": "$701 - $800"
        },
        {
          "id": "ans_Z5mMMLFy6waMK",
          "text": "$801 - $900"
        },
        {
          "id": "ans_BeSaN5Vj6tRjh",
          "text": "$901 - $1000"
        },
        {
          "id": "ans_74H68MJjqNhk8",
          "text": "None of the Above"
        }
      ]
    }
  ],
  "authenticated": false
}

Update an auth session​

Next we'll provide the answers to the security questions. This request may either return a list of additional security questions, or a authenticated boolean which indicates that the verification was successful.

PUT /entities/:entity_id/auth_session
curl https://production.methodfi.com/entities/ent_au22b1fbFJbp8/auth_session \
  -X PUT \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc" \
  -H "Content-Type: application/json" \
  -d '{
    "answers": [
      {
        "question_id": "qtn_ywWqCnXDGGmmg",
        "answer_id": "ans_74H68MJjqNhk8"
      },
      ...
    ]
  }'
RESPONSE
{
  "questions": [],
  "authenticated": true
}

Response (Verification Successful)​

Once we receive a true authenticated key, we have successfully verified this entity's identity and retrieved their debt accounts.

{
  "questions": [],
  "authenticated": true,
}

Response (Additional Verification Required)​

In some cases, you may need to go through an additional set of security questions to fully verify. Simply repeat the request with answers for the new set of security questions.

{
  "questions": [
    {
      "id" : "qtn_7smgfLrU6M5tt",
      "text" : "Which of the following is a current or previous employer?",
      "answers" : [
        {
          "id" : "ans_ZExAcSeGjgEwS",
          "text" : "Men's Wearhouse"
        },
        {
          "id" : "ans_8MRLxgtQxEmYV",
          "text" : "Target"
        },
        ...
      ]
    },
    ...
  ],
  "authenticated": false
}

Retrieve the created liability accounts​

Now we'll retrieve the accounts created from the entity's completed Auth Element. 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.
GET /accounts?holder_id={holder_id}
curl "https://production.methodfi.com/accounts?holder_id=ent_au22b1fbFJbp8" \
  -H "Authorization: Bearer sk_WyZEWVfTcH7GqmPzUPk65Vjc"
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"
  },
  ...
]