---
title: "List Link Identity Match attempts"
method: POST
path: "/identity/match/list"
tags: ["plaid"]
---

# List Link Identity Match attempts

`POST /identity/match/list`

Returns a chronological history of Link-originated Identity Match attempts for a client, ordered by creation time with the oldest attempt first.

Results are retained for up to one year. Attempts for deleted Items are omitted.

## Request body

- IdentityMatchListRequest — IdentityMatchListRequest defines the request schema for `/identity/match/list`
  - `client_id` string — Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body.
  - `secret` string — Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body.
  - `start_time` string, date-time, required — Inclusive start of the query window in RFC 3339 format.
  - `end_time` string, date-time, required — Inclusive end of the query window in RFC 3339 format.
  - `count` integer — Maximum number of attempts to return in one page.
  - `cursor` string — Opaque pagination cursor. Omit on the first request. For subsequent requests, set this field to the `next_cursor` from the previous response and use the same `start_time` and `end_time`.

## Response `200`

OK

- IdentityMatchListResponse — IdentityMatchListResponse defines the response schema for `/identity/match/list`
  - `identity_match_attempts` IdentityMatchListAttempt[], required — Page of Link-originated Identity Match attempts ordered by creation time, oldest first.
    - `attempt_id` string, required — Identifier for the Identity Match attempt.
    - `item_id` string, required — The `item_id` of the Item associated with this webhook, warning, or error
    - `created_at` string, date-time, required — Time at which the attempt was created.
    - `link_session_id` string, required — Link session that produced the attempt.
    - `link_customization_name` string, required — Link customization that supplied the ruleset.
    - `ruleset_revision` integer, required — Revision of the Identity Match ruleset that was applied.
    - `outcome` 'PASS' | 'FAIL' | 'UNKNOWN', required — Link outcome for the Identity Match attempt.
    - `outcome_account_id` string, nullable, required — Account ID associated with a `PASS` outcome. Null for `FAIL` or `UNKNOWN` outcomes.
    - `scores` IdentityMatchListAttemptScore[], required — Per-account match scores. Empty if the attempt data is unavailable.
      - `account_id` string, required — Plaid account ID for the account that was scored.
      - `legal_name` NameMatchScore, required — Score found by matching name provided by the API with the name on the account at the financial institution. If the account contains multiple owners, the maximum match score is filled.
        - `score` integer, nullable, required — Match score for name. 100 is a perfect score, 99-85 means a strong match, 84-70 is a partial match, any score less than 70 is a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the name is missing from either the API or financial institution, this is null.
        - `is_first_name_or_last_name_match` boolean, nullable, required — first or last name completely matched, likely a family member
        - `is_nickname_match` boolean, nullable, required — nickname matched, example Jennifer and Jenn.
        - `is_business_name_detected` boolean, nullable, required — Is `true` if the name on either of the names that was matched for the score contained strings indicative of a business name, such as "CORP", "LLC", "INC", or "LTD". A `true` result generally indicates that an account's name is a business name. However, a `false` result does not mean the account name is not a business name, as some businesses do not use these strings in the names used for their financial institution accounts.
      - `phone_number` PhoneNumberMatchScore, required — Score found by matching phone number provided by the API with the phone number on the account at the financial institution. 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled.
        - `score` integer, nullable, required — Match score for normalized phone number. 100 is a perfect match, 99-70 is a partial match (matching the same phone number with extension against one without extension, etc.), anything below 70 is considered a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the phone number is missing from either the API or financial institution, this is null.
      - `email_address` EmailAddressMatchScore, required — Score found by matching email provided by the API with the email on the account at the financial institution. 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled.
        - `score` integer, nullable, required — Match score for normalized email. 100 is a perfect match, 99-70 is a partial match (matching the same email with different '+' extensions), anything below 70 is considered a mismatch. Typically, the match threshold should be set to a score of 70 or higher. If the email is missing from either the API or financial institution, this is null.
      - `address` AddressMatchScore, required — Score found by matching address provided by the API with the address on the account at the financial institution. The score can range from 0 to 100 where 100 is a perfect match and 0 is a no match. If the account contains multiple owners, the maximum match score is filled.
        - `score` integer, nullable, required — Match score for address. 100 is a perfect match, 99-90 is a strong match, 89-70 is a partial match, anything below 70 is considered a weak match. Typically, the match threshold should be set to a score of 70 or higher. If the address is missing from either the API or financial institution, this is null.
        - `is_postal_code_match` boolean, nullable, required — postal code was provided for both and was a match
  - `next_cursor` string, nullable, required — Cursor for the next page. Null when there are no more pages.
  - `has_more` boolean, required — Whether more attempts remain in the query window.
  - `request_id` string, required — A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.

## Other responses

- `default` — Error response

---

[API](https://skmtc.net/plaid/apis/the-plaid-api.md) · [All operations](https://skmtc.net/plaid/apis/the-plaid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/plaid/the-plaid-api/revisions/e536704a333f/schema)