> ## 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 identities endpoint

export const identity_name = "Identity";

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 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
  items={[
get_common_parameters(identity_name).id,
get_common_parameters().entity_id,
get_common_parameters(identity_name).status(
  [
    {
      name: "pending",
      description: `The ${identity_name} is queued to be retrieved.`,
    },
    {
      name: "in_progress",
      description: `The ${identity_name} is being retrieved.`,
    },
    {
      name: "completed",
      description: `The ${identity_name} has successfully been retrieved.`,
    },
    {
      name: "failed",
      description: `The ${identity_name} failed to be retrieved.`,
    },
  ]
),
{
  name: "identities",
  type: "object[] | null",
  description: "An array of identity objects.",
  items: [
    {
      name: "identities.first_name",
      type: "string",
      description: "The legal first name of the identity.",
    },
    {
      name: "identities.last_name",
      type: "string",
      description: "The legal last name of the identity.",
    },
    {
      name: "identities.dob",
      type: "string",
      description: "The identity's date of birth in ISO 8601 format.",
    },
    {
      name: "identities.ssn",
      type: "string",
      description: "The identity's SSN.",
    },
    {
      name: "identities.phone",
      type: "string",
      description:
        "Mobile phone number of the identity in E.164 format. The number will only be used for KYC / AML verification.",
    },
    {
      name: "identities.address",
      type: "object | null",
      description: "The identity's address.",
      items: [
        {
          name: "identities.address.address",
          type: "string",
          description: "The number and street of the identity's address.",
        },
        {
          name: "identities.address.city",
          type: "string",
          description: "The city of the identity's address.",
        },
        {
          name: "identities.address.postal_code",
          type: "string",
          description: "The postal code of the identity's address.",
        },
        {
          name: "identities.address.state",
          type: "string",
          description:
            "The two-letter abbreviation for the state of the identity's address.",
        },
      ],
    },
  ],
},
get_common_parameters(identity_name).error,
get_common_parameters(identity_name).created_at,
get_common_parameters(identity_name).updated_at,
]}
/>

<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>