OpenAPI Specification
openapi: 3.0.0
servers:
- description: Production
url: https://production.plaid.com
- description: Development
url: https://development.plaid.com
- description: Sandbox
url: https://sandbox.plaid.com
info:
title: 'Plaid identity/'
version: 2020-09-14_1.517.0
description: Needs description.
contact:
name: Plaid Developer Team
url: https://plaid.com
termsOfService: https://plaid.com/legal/
tags:
- name: Plaid
security:
- clientId: []
secret: []
plaidVersion: []
paths:
/identity/get:
x-plaid-business-unit-context: BUSINESS_UNIT_PLAID
post:
tags:
- Plaid
summary: Plaid Retrieve identity data
externalDocs:
url: /api/products/identity/#identityget
operationId: identityGet
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IdentityGetResponse'
examples:
example-1:
value:
accounts:
- account_id: BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp
balances:
available: 100
current: 110
iso_currency_code: USD
limit:
unofficial_currency_code:
mask: '0000'
name: Plaid Checking
official_name: Plaid Gold Standard 0% Interest Checking
owners:
- addresses:
- data:
city: Malakoff
country: US
postal_code: '14236'
region: NY
street: 2992 Cameron Road
primary: true
- data:
city: San Matias
country: US
postal_code: 93405-2255
region: CA
street: 2493 Leisure Lane
primary: false
emails:
- data: [email protected]
primary: true
type: primary
- data: [email protected]
primary: false
type: secondary
- data: >-
extraordinarily.long.email.username.123456@reallylonghostname.com
primary: false
type: other
names:
- Alberta Bobbeth Charleson
phone_numbers:
- data: '1112223333'
primary: false
type: home
- data: '1112224444'
primary: false
type: work
- data: '1112225555'
primary: false
type: mobile
subtype: checking
type: depository
- account_id: 3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr
balances:
available: 200
current: 210
iso_currency_code: USD
limit:
unofficial_currency_code:
mask: '1111'
name: Plaid Saving
official_name: Plaid Silver Standard 0.1% Interest Saving
owners:
- addresses:
- data:
city: Malakoff
country: US
postal_code: '14236'
region: NY
street: 2992 Cameron Road
primary: true
- data:
city: San Matias
country: US
postal_code: 93405-2255
region: CA
street: 2493 Leisure Lane
primary: false
emails:
- data: [email protected]
primary: true
type: primary
- data: [email protected]
primary: false
type: secondary
- data: >-
extraordinarily.long.email.username.123456@reallylonghostname.com
primary: false
type: other
names:
- Alberta Bobbeth Charleson
phone_numbers:
- data: '1112223333'
primary: false
type: home
- data: '1112224444'
primary: false
type: work
- data: '1112225555'
primary: false
type: mobile
subtype: savings
type: depository
item:
available_products:
- balance
- investments
billed_products:
- assets
- auth
- identity
- liabilities
- transactions
consent_expiration_time:
error:
institution_id: ins_3
item_id: eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6
update_type: background
webhook: https://www.genericwebhookurl.com/webhook
request_id: 3nARps6TOYtbACO
description: >-
The `/identity/get` endpoint allows you to retrieve various account
holder information on file with the financial institution, including
names, emails, phone numbers, and addresses. Only name data is
guaranteed to be returned; other fields will be empty arrays if not
provided by the institution.
This request may take some time to complete if identity was not
specified as an initial product when creating the Item. This is because
Plaid must communicate directly with the institution to retrieve the
data.
Note: In API versions 2018-05-22 and earlier, the `owners` object is not
returned, and instead identity information is returned in the top level
`identity` object. For more details, see [Plaid API
versioning](https://plaid.com/docs/api/versioning/#version-2019-05-29).
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IdentityGetRequest'
description: ''
/identity/documents/uploads/get:
x-plaid-business-unit-context: BUSINESS_UNIT_PLAID
x-hidden-from-docs: true
post:
tags:
- Plaid
summary: Plaid Returns uploaded document identity
externalDocs:
url: none
operationId: identityDocumentsUploadsGet
description: >-
Use `/identity/documents/uploads/get` to retrieve document uploaded
identity.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IdentityDocumentsUploadsGetResponse'
examples:
example-1:
value:
accounts:
- account_id: BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp
balances:
available: 100
current: 110
iso_currency_code: USD
limit:
unofficial_currency_code:
mask: '0000'
name: Plaid Checking
official_name: Plaid Gold Standard 0% Interest Checking
owners:
- addresses:
- data:
city: Malakoff
country: US
postal_code: '14236'
region: NY
street: 2992 Cameron Road
primary: true
- data:
city: San Matias
country: US
postal_code: 93405-2255
region: CA
street: 2493 Leisure Lane
primary: false
emails:
- data: [email protected]
primary: true
type: primary
- data: [email protected]
primary: false
type: secondary
- data: >-
extraordinarily.long.email.username.123456@reallylonghostname.com
primary: false
type: other
names:
- Alberta Bobbeth Charleson
phone_numbers:
- data: '1112223333'
primary: false
type: home
- data: '1112224444'
primary: false
type: work
- data: '1112225555'
primary: false
type: mobile
subtype: checking
type: depository
- account_id: 3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr
balances:
available: 200
current: 210
iso_currency_code: USD
limit:
unofficial_currency_code:
mask: '1111'
name: Plaid Saving
official_name: Plaid Silver Standard 0.1% Interest Saving
owners:
- addresses:
- data:
city: Malakoff
country: US
postal_code: '14236'
region: NY
street: 2992 Cameron Road
primary: true
- data:
city: San Matias
country: US
postal_code: 93405-2255
region: CA
street: 2493 Leisure Lane
primary: false
emails:
- data: [email protected]
primary: true
type: primary
- data: [email protected]
primary: false
type: secondary
- data: >-
extraordinarily.long.email.username.123456@reallylonghostname.com
primary: false
type: other
names:
- Alberta Bobbeth Charleson
phone_numbers:
- data: '1112223333'
primary: false
type: home
- data: '1112224444'
primary: false
type: work
- data: '1112225555'
primary: false
type: mobile
subtype: savings
type: depository
item:
available_products:
- balance
- investments
billed_products:
- assets
- auth
- identity
- liabilities
- transactions
consent_expiration_time:
error:
institution_id: ins_3
item_id: eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6
update_type: background
webhook: https://www.genericwebhookurl.com/webhook
request_id: 3nARps6TOYtbACO
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IdentityDocumentsUploadsGetRequest'
/identity/match:
x-plaid-business-unit-context: BUSINESS_UNIT_PLAID
post:
tags:
- Plaid
summary: Plaid Retrieve identity match score
externalDocs:
url: /api/products/identity/#identitymatch
operationId: identityMatch
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IdentityMatchResponse'
examples:
example-1:
value:
accounts:
- account_id: BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp
balances:
available:
current:
iso_currency_code:
limit:
unofficial_currency_code:
mask: '0000'
name: Plaid Checking
official_name: Plaid Gold Standard 0% Interest Checking
legal_name:
score: 90
is_nickname_match: true
is_first_name_or_last_name_match: true
is_business_name_detected: false
phone_number:
score: 100
email_address:
score: 100
address:
score: 100
is_postal_code_match: true
subtype: checking
type: depository
- account_id: 3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr
balances:
available:
current:
iso_currency_code:
limit:
unofficial_currency_code:
mask: '1111'
name: Plaid Saving
official_name: Plaid Silver Standard 0.1% Interest Saving
legal_name:
score: 30
is_first_name_or_last_name_match: false
phone_number:
score: 100
email_address:
address:
score: 100
is_postal_code_match: true
subtype: savings
type: depository
item:
available_products:
- balance
- investments
billed_products:
- assets
- auth
- identity
- liabilities
- transactions
consent_expiration_time:
error:
institution_id: ins_3
item_id: eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6
update_type: background
webhook: https://www.genericwebhookurl.com/webhook
request_id: 3nARps6TOYtbACO
description: >-
The `/identity/match` endpoint generates a match score, which indicates
how well the provided identity data matches the identity information on
file with the account holder's financial institution.
Fields within the `balances` object will always be null when retrieved
by `/identity/match`. Instead, use the free `/accounts/get` endpoint to
request balance cached data, or `/accounts/balance/get` for real-time
data.
This request may take some time to complete if Identity was not
specified as an initial product when creating the Item. This is because
Plaid must communicate directly with the institution to retrieve the
data.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IdentityMatchRequest'
description: ''
/identity/refresh:
x-plaid-business-unit-context: BUSINESS_UNIT_PLAID
post:
tags:
- Plaid
summary: Plaid Refresh identity data
externalDocs:
url: /api/products/identity/#identityrefresh
operationId: identityRefresh
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/IdentityRefreshResponse'
examples:
example-1:
value:
request_id: 1vwmF5TBQwiqfwP
default:
content:
application/json:
schema:
$ref: '#/components/schemas/PlaidError'
description: Error response
description: >-
`/identity/refresh` is an optional endpoint for users of the Identity
product. It initiates an on-demand extraction to fetch the most up to
date Identity information from the Financial Institution. This on-demand
extraction takes place in addition to the periodic extractions that
automatically occur for any Identity-enabled Item. If changes to
Identity are discovered after calling `/identity/refresh`, Plaid will
fire a webhook
[`DEFAULT_UPDATE`](https://plaid.com/docs/api/products/identity/#default_update).
As this endpoint triggers a synchronous request for fresh data, latency
may be higher than for other Plaid endpoints (typically less than 10
seconds, but occasionally up to 30 seconds or more); if you encounter
errors, you may find it necessary to adjust your timeout period when
making requests.
`/identity/refresh` is offered as an add-on to Identity and has a
separate [fee model](/docs/account/billing/#per-request-flat-fee). To
request access to this endpoint, submit a [product access
request](https://dashboard.plaid.com/team/products) or contact your
Plaid account manager.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IdentityRefreshRequest'
/processor/identity/get:
x-plaid-business-unit-context: BUSINESS_UNIT_PLAID
post:
tags:
- Plaid
summary: Plaid Retrieve Identity data
externalDocs:
url: /api/processor-partners/#processoridentityget
operationId: processorIdentityGet
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ProcessorIdentityGetResponse'
examples:
example-1:
value:
account:
account_id: XMGPJy4q1gsQoKd5z9R3tK8kJ9EWL8SdkgKMq
balances:
available: 100
current: 110
iso_currency_code: USD
limit:
unofficial_currency_code:
mask: '0000'
name: Plaid Checking
official_name: Plaid Gold Standard 0% Interest Checking
owners:
- addresses:
- data:
city: Malakoff
country: US
postal_code: '14236'
region: NY
street: 2992 Cameron Road
primary: true
- data:
city: San Matias
country: US
postal_code: 93405-2255
region: CA
street: 2493 Leisure Lane
primary: false
emails:
- data: [email protected]
primary: true
type: primary
- data: [email protected]
primary: false
type: secondary
- data: >-
extraordinarily.long.email.username.123456@reallylonghostname.com
primary: false
type: other
names:
- Alberta Bobbeth Charleson
phone_numbers:
- data: '1112223333'
primary: false
type: home
- data: '1112224444'
primary: false
type: work
- data: '1112225555'
primary: false
type: mobile1
subtype: checking
type: depository
request_id: eOPkBl6t33veI2J
description: >-
The `/processor/identity/get` endpoint allows you to retrieve various
account holder information on file with the financial institution,
including names, emails, phone numbers, and addresses.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProcessorIdentityGetRequest'
/processor/identity/match:
x-plaid-business-unit-context: BUSINESS_UNIT_PLAID
post:
tags:
- Plaid
summary: Plaid Retrieve identity match score
externalDocs:
url: /api/processor-partners/#processoridentitymatch
operationId: processorIdentityMatch
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ProcessorIdentityMatchResponse'
examples:
example-1:
value:
account:
account_id: BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp
balances:
available:
current:
iso_currency_code:
limit:
unofficial_currency_code:
mask: '0000'
name: Plaid Checking
official_name: Plaid Gold Standard 0% Interest Checking
legal_name:
score: 90
is_nickname_match: true
is_first_name_or_last_name_match: true
is_business_name_detected: false
phone_number:
score: 100
email_address:
score: 100
address:
score: 100
is_postal_code_match: true
subtype: checking
type: depository
request_id: 3nARps6TOYtbACO
description: >-
The `/processor/identity/match` endpoint generates a match score, which
indicates how well the provided identity data matches the identity
information on file with the account holder's financial institution.
Fields within the `balances` object will always be null when retrieved
by `/identity/match`. Instead, use the free `/accounts/get` endpoint to
request balance cached data, or `/accounts/balance/get` for real-time
data.
This request may take some time to complete if Identity was not
specified as an initial product when creating the Item. This is because
Plaid must communicate directly with the institution to retrieve the
data.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProcessorIdentityMatchRequest'
description: ''
components:
schemas:
IdentityGetResponse:
type: object
additionalProperties: true
description: IdentityGetResponse defines the response schema for `/identity/get`
properties:
accounts:
type: array
description: The accounts for which Identity data has been requested
items:
$ref: '#/components/schemas/AccountIdentity'
item:
$ref: '#/components/schemas/Item'
request_id:
$ref: '#/components/schemas/RequestID'
required:
- accounts
- item
- request_id
IdentityDocumentsUploadsGetResponse:
type: object
additionalProperties: true
description: >-
IdentityDocumentsUploadsGetResponse defines the response schema for
`/identity/documents/uploads/get`
properties:
accounts:
type: array
description: The accounts for which Identity data has been requested
items:
$ref: '#/components/schemas/AccountIdentityDocumentUpload'
item:
$ref: '#/components/schemas/Item'
request_id:
$ref: '#/components/schemas/RequestID'
required:
- accounts
- item
- request_id
IdentityMatchResponse:
type: object
additionalProperties: true
description: IdentityMatchResponse defines the response schema for `/identity/match`
properties:
accounts:
type: array
description: The accounts for which Identity match has been requested
items:
$ref: '#/components/schemas/AccountIdentityMatchScore'
item:
$ref: '#/components/schemas/Item'
request_id:
$ref: '#/components/schemas/RequestID'
required:
- accounts
- item
- request_id
IdentityRefreshResponse:
type: object
additionalProperties: true
description: >-
IdentityRefreshResponse defines the response schema for
`/identity/refresh`
properties:
request_id:
$ref: '#/components/schemas/RequestID'
required:
- request_id
PlaidError:
description: >-
Errors are identified by `error_code` and categorized by `error_type`.
Use these in preference to HTTP status codes to identify and handle
specific errors. HTTP status codes are set and provide the broadest
categorization of errors: 4xx codes are for developer- or user-related
errors, and 5xx codes are for Plaid-related errors, and the status will
be 2xx in non-error cases. An Item with a non-`null` error object will
only be part of an API response when calling `/item/get` to view Item
status. Otherwise, error fields will be `null` if no error has occurred;
if an error has occurred, an error code will be returned instead.
type: object
additionalProperties: true
title: Error
nullable: true
properties:
error_type:
$ref: '#/components/schemas/PlaidErrorType'
error_code:
description: The particular error code. Safe for programmatic use.
type: string
error_message:
description: >-
A developer-friendly representation of the error code. This may
change over time and is not safe for programmatic use.
type: string
display_message:
description: >-
A user-friendly representation of the error code. `null` if the
error is not related to user action.
This may change over time and is not safe for programmatic use.
type: string
nullable: true
request_id:
type: string
description: >-
A unique ID identifying the request, to be used for troubleshooting
purposes. This field will be omitted in errors provided by webhooks.
causes:
type: array
description: >-
In the Assets product, a request can pertain to more than one Item.
If an error is returned for such a request, `causes` will return an
array of errors containing a breakdown of these errors on the
individual Item level, if any can be identified.
`causes` will only be provided for the `error_type`
`ASSET_REPORT_ERROR`. `causes` will also not be populated inside an
error nested within a `warning` object.
items: {}
status:
type: integer
description: >-
The HTTP status code associated with the error. This will only be
returned in the response body when the error information is provided
via a webhook.
nullable: true
documentation_url:
type: string
description: >-
The URL of a Plaid documentation page with more information about
the error
suggested_action:
type: string
nullable: true
description: Suggested steps for resolving the error
required:
- error_type
- error_code
- error_message
- display_message
ProcessorIdentityGetResponse:
type: object
additionalProperties: true
description: >-
ProcessorIdentityGetResponse defines the response schema for
`/processor/identity/get`
properties:
account:
$ref: '#/components/schemas/AccountIdentity'
request_id:
$ref: '#/components/schemas/RequestID'
required:
- account
- request_id
ProcessorIdentityMatchResponse:
type: object
additionalProperties: true
description: >-
ProcessorIdentityMatchResponse defines the response schema for
`/processor/identity/match`
properties:
accoun
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/plaid/refs/heads/main/openapi/plaid-identity--openapi-original.yml