> ## Documentation Index
> Fetch the complete documentation index at: https://docs.methodfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The entity verification sessions endpoint

export const entity_verification_session_name = "EntityVerificationSession";

export const get_common_parameters = (resource_name = 'resource') => {
  return {
    id: {
      name: 'id',
      type: "string",
      required: false,
      description: `Unique identifier for the ${resource_name}.`
    },
    entity_id: {
      name: 'entity_id',
      type: 'string',
      required: false,
      description: 'The ID of the associated Entity.'
    },
    account_id: {
      name: 'account_id',
      type: 'string',
      required: false,
      description: 'The ID of the associated Account.'
    },
    error: {
      name: 'error',
      type: 'object | null',
      required: false,
      description: <>
          An object representing an error that occurred while processing
          this {resource_name}. See <a href={`/reference/errors/${resource_name.replace(/^([A-Z])/, function (match) {
        return match.toLowerCase();
      }).replace(/([A-Z])/g, function (match) {
        return "-" + match.toLowerCase();
      })}-errors`}>{resource_name} errors</a>.
        </>
    },
    status_error: {
      name: 'status_error',
      type: 'object | null',
      required: false,
      description: <>
          An object representing an error that occurred while processing
          this {resource_name}. See <a href="/reference/errors/product-errors#status-errors">{resource_name} errors</a>.
        </>
    },
    metadata: {
      name: 'metadata',
      type: 'object | null',
      required: false,
      description: <>
          Additional data provided during creation.
          See <a href="/reference/metadata">metadata</a>
        </>
    },
    created_at: {
      name: 'created_at',
      type: 'string',
      required: false,
      description: `Timestamp of when the ${resource_name} was created.`
    },
    updated_at: {
      name: 'updated_at',
      type: 'string',
      required: false,
      description: `Timestamp of when the ${resource_name} was last updated.`
    },
    status: (enums = []) => ({
      name: 'status',
      type: 'enum',
      required: false,
      description: `Status of the ${resource_name}.`,
      enums
    }),
    type: (enums = []) => ({
      name: 'type',
      type: 'enum',
      required: false,
      description: `The type of ${resource_name}.`,
      enums
    })
  };
};

export const ParamList = ({items = [], is_child = false}) => {
  return items.map(item => {
    const field_props = {
      id: Math.random().toString(),
      body: item.name,
      name: item.name,
      type: item.type,
      required: item.required
    };
    const enums = item.enums || [];
    const items = item.items || [];
    const has_items = items?.length > 0;
    const has_enums = enums?.length > 0;
    const should_default_open = item.defaultOpen || false;
    const render_child_item = () => {
      const child_props = {
        title: has_enums ? "Possible enum values" : "properties"
      };
      if (should_default_open) child_props.defaultOpen = true;
      const has_inline_enums = has_enums && enums.every(enum_item => typeof enum_item === 'string') && enums.map((enum_item, idx) => {
        const is_last = idx === enums.length - 1;
        const is_2nd_to_last = idx === enums.length - 2;
        return <>
            <code>{enum_item}</code>
            {is_last && ''}
            {is_2nd_to_last && ' or '}
            {!is_last && !is_2nd_to_last && ', '}
          </>;
      });
      const enum_list = has_enums && !has_inline_enums && <Accordion {...child_props}>
          {enums.map((enum_item, index) => <div key={`enum-${index}`}>
              <code>{enum_item.name}</code>
              <br />
              <p>{enum_item.description}</p>
            </div>)}
        </Accordion>;
      const item_list = has_items && <Expandable {...child_props}>
          <ParamList items={items || []} is_child />
        </Expandable>;
      return <>
          <p>
            {item.description}
            {has_inline_enums && [has_inline_enums.length > 1 ? ' One of ' : ' Must be ', ...has_inline_enums]}
          </p>

          {enum_list}
          {item_list}
        </>;
    };
    return is_child ? <ResponseField {...field_props}>{render_child_item()}</ResponseField> : <ParamField {...field_props}>{render_child_item()}</ParamField>;
  });
};

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
  items={[
get_common_parameters(entity_verification_session_name).id,
get_common_parameters(entity_verification_session_name).entity_id,
get_common_parameters(entity_verification_session_name).status(
  [
    {
      name: "pending",
      description: `The ${entity_verification_session_name} has been initiated. Method is gathering information to send over to verify the Entity.`,
    },
    {
      name: "in_progress",
      description: `Method has sent over information to verify the Entity and is waiting for a PUT from the client.`,
    },
    {
      name: "verified",
      description: `Method has successfully verified the Entity's phone or identity. The ${entity_verification_session_name} has successfully been completed.`,
    },
    {
      name: "failed",
      description: `The ${entity_verification_session_name} has failed due to either not being able to verify the Entity or session has expired.`,
    },
  ]
),
{
  name: "type",
  type: "enum",
  description: `The type of ${entity_verification_session_name}.`,
  enums: [
    {
      name: "identity",
      description: `The ${entity_verification_session_name} is an identity verification.`,
    },
    {
      name: "phone",
      description: `The ${entity_verification_session_name} is a phone verification.`,
    },
  ],
},
{
  name: "method",
  type: "enum",
  description: (
    <>
      The method being used to verify this Entity's type of{" "}
      {entity_verification_session_name}. Refer to{" "}
      <a href="/2026-03-30/reference/entities/verification-sessions/overview#verification-methods">Verification Methods</a> for more
      information.
    </>
  ),
  enums: [
    {
      name: "sms",
      description: `Verifying the Entity's phone via Method's SMS.`,
    },
    {
      name: "sna",
      description: `Verifying the Entity's phone via Method's Silent Network Authentication (SNA).`,
    },
    {
      name: "byo_sms",
      description: `Verified the Entity's phone via non-Method verification.`,
    },
    {
      name: "byo_kyc",
      description: `Verified the Entity's identity via non-Method verification.`,
    },
    {
      name: "kba",
      description: `Verifying the Entity's identity via Method's Knowledge-Based Authentication (KBA).`,
    },
    {
      name: "element",
      description: `Verifying the Entity's identity via Method's Element.`,
    },
    {
      name: "method_verified",
      description: `Method has already verified the PII provided.`,
    },
  ],
},
get_common_parameters(entity_verification_session_name).error,
get_common_parameters(entity_verification_session_name).created_at,
get_common_parameters(entity_verification_session_name).updated_at,
]}
/>

## Additional Properties based on method

<Tabs>
  <Tab title="sms">
    <ParamList
      items={[
    {
      name: "sms",
      type: "object | null",
      defaultOpen: true,
      description:
        "The sms object being used to store critical information related to the verification.",
      items: [
        {
          name: "sms.timestamp",
          type: "string",
          description: `Timestamp of when the phone was verified via SMS.`,
        },
      ],
    },
  ]}
    />
  </Tab>

  <Tab title="sna">
    <ParamList
      items={[
    {
      name: "sna",
      type: "object | null",
      defaultOpen: true,
      description:
        "The sna object being used to store critical information related to the verification.",
      items: [
        {
          name: "sna.urls",
          type: "string[]",
          description: `The urls that will need to be used to verify the phone.`,
        },
      ],
    },
  ]}
    />
  </Tab>

  <Tab title="byo_sms">
    <ParamList
      items={[
    {
      name: "byo_sms",
      type: "object | null",
      defaultOpen: true,
      description: `The byo_sms object used to store the timestamp that the phone was verified by a non-Method provider.`,
      items: [
        {
          name: "byo_sms.timestamp",
          type: "string",
          description: `Timestamp of when the phone was verified.`,
        },
      ],
    },
  ]}
    />
  </Tab>

  <Tab title="byo_kyc">
    <ParamList
      items={[
    {
      name: "byo_kyc",
      type: "object | null",
      defaultOpen: true,
      description: `The byo_kyc object used to store the authentication status of the Entity which was verified by a non-Method provider.`,
      items: [
        {
          name: "byo_kyc.authenticated",
          type: "boolean",
          description: `Current authentication status of the Entity's identity.`,
        },
      ],
    },
  ]}
    />
  </Tab>

  <Tab title="kba">
    <ParamList
      items={[
    {
      name: "kba",
      type: "object | null",
      defaultOpen: true,
      description:
        "The kba object being used to store critical information related to the verification.",
      items: [
        {
          name: "kba.questions",
          type: "object[]",
          description: `Questions provided by Method to verify an Entity's identity.`,
          items: [
            {
              name: "kba.questions.id",
              type: "string",
              description: `The question ID.`,
            },
            {
              name: "kba.questions.text",
              type: "string",
              description: `The corresponding text of the question.`,
            },
            {
              name: "kba.questions.answers",
              type: "object[]",
              description: `The list of answers to the question.`,
              items: [
                {
                  name: "kba.questions.answers.id",
                  type: "string",
                  description: `The answer ID.`,
                },
                {
                  name: "kba.questions.answers.text",
                  type: "string",
                  description: `The corresponding text of the answer.`,
                },
              ],
            },
          ],
        },
        {
          name: "kba.authenticated",
          type: "boolean",
          description: `Current authentication status of the Entity's identity.`,
        },
      ],
    },
  ]}
    />
  </Tab>

  <Tab title="element">
    <ParamList
      items={[
    {
      name: "element",
      type: "object | null",
      defaultOpen: true,
      description:
        "The element object being used to store critical information related to the verification.",
      items: [
        {
          name: "element.element_token",
          type: "string",
          description: `The associated element_token used to initiate the element session.`,
        },
        {
          name: "element.type",
          type: "string",
          description: `The associated type of element session.`,
        },
        {
          name: "element.timestamp",
          type: "string",
          description: (
            <>
              Timestamp of when the phone was verified via the element
              session.
              <Note>
                This field will only appear if the{" "}
                {entity_verification_session_name} is of type{" "}
                <code>phone</code>
              </Note>
            </>
          ),
        },
        {
          name: "element.questions",
          type: "object[]",
          description: (
            <>
              Questions provided by Method to verify an Entity's identity.
              <Note>
                This field will only appear if the{" "}
                {entity_verification_session_name} is of type{" "}
                <code>identity</code>
              </Note>
            </>
          ),
          items: [
            {
              name: "element.questions.id",
              type: "string",
              description: `The question ID.`,
            },
            {
              name: "element.questions.text",
              type: "string",
              description: `The corresponding text of the question.`,
            },
            {
              name: "element.questions.answers",
              type: "object[]",
              description: `The list of answers to the question.`,
              items: [
                {
                  name: "element.questions.answers.id",
                  type: "string",
                  description: `The answer ID.`,
                },
                {
                  name: "element.questions.answers.text",
                  type: "string",
                  description: `The corresponding text of the answer.`,
                },
              ],
            },
          ],
        },
        {
          name: "element.authenticated",
          type: "boolean",
          description: (
            <>
              Current authentication status of the Entity's identity.
              <Note>
                This field will only appear if the{" "}
                {entity_verification_session_name} is of type{" "}
                <code>identity</code>
              </Note>
            </>
          ),
        },
      ],
    },
  ]}
    />
  </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>