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 income/' 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: /income/verification/create: x-plaid-business-unit-context: BUSINESS_UNIT_PLAID post: summary: Plaid (Deprecated) Create an income verification instance tags: - Plaid deprecated: true externalDocs: url: /api/products/income/#incomeverificationcreate operationId: incomeVerificationCreate responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/IncomeVerificationCreateResponse' examples: example-1: value: income_verification_id: f2a826d7-25cf-483b-a124-c40beb64b732 request_id: lMjeOeu9X1VUh1F description: >- `/income/verification/create` begins the income verification process by returning an `income_verification_id`. You can then provide the `income_verification_id` to `/link/token/create` under the `income_verification` parameter in order to create a Link instance that will prompt the user to go through the income verification flow. Plaid will fire an `INCOME` webhook once the user completes the Payroll Income flow, or when the uploaded documents in the Document Income flow have finished processing. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IncomeVerificationCreateRequest' /income/verification/paystubs/get: x-plaid-business-unit-context: BUSINESS_UNIT_PLAID post: summary: >- Plaid (Deprecated) Retrieve information from the paystubs used for income verification deprecated: true tags: - Plaid externalDocs: url: /api/products/income/#incomeverificationpaystubsget operationId: incomeVerificationPaystubsGet responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/IncomeVerificationPaystubsGetResponse' examples: example-1: value: document_metadata: - doc_id: 2jkflanbd doc_type: DOCUMENT_TYPE_PAYSTUB name: paystub.pdf status: DOCUMENT_STATUS_PROCESSING_COMPLETE paystubs: - deductions: breakdown: - current_amount: 123.45 description: taxes iso_currency_code: USD unofficial_currency_code: ytd_amount: 246.9 total: current_amount: 123.45 iso_currency_code: USD unofficial_currency_code: ytd_amount: 246.9 doc_id: 2jkflanbd earnings: breakdown: - canonical_description: REGULAR PAY current_amount: 200.22 description: salary earned hours: 80 iso_currency_code: USD rate: unofficial_currency_code: ytd_amount: 400.44 - canonical_desription: BONUS current_amount: 100 description: bonus earned hours: iso_currency_code: USD rate: unofficial_currency_code: ytd_amount: 100 total: current_amount: 300.22 hours: 160 iso_currency_code: USD unofficial_currency_code: ytd_amount: 500.44 employee: address: city: SAN FRANCISCO country: US postal_code: '94133' region: CA street: 2140 TAYLOR ST name: ANNA CHARLESTON marital_status: single taxpayer_id: id_type: SSN id_mask: '3333' employer: name: PLAID INC address: city: SAN FRANCISCO country: US postal_code: '94111' region: CA street: 1098 HARRISON ST net_pay: current_amount: 123.34 description: TOTAL NET PAY iso_currency_code: USD unofficial_currency_code: ytd_amount: 253.54 pay_period_details: check_amount: 1490.21 distribution_breakdown: - account_name: Big time checking bank_name: bank of plaid current_amount: 176.77 iso_currency_code: USD mask: '1223' type: checking unofficial_currency_code: end_date: '2020-12-15' gross_earnings: 4500 pay_date: '2020-12-15' start_date: '2020-12-01' pay_frequency: PAY_FREQUENCY_BIWEEKLY request_id: 2pxQ59buGdsHRef requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IncomeVerificationPaystubsGetRequest' description: '' description: >- `/income/verification/paystubs/get` returns the information collected from the paystubs that were used to verify an end user's income. It can be called once the status of the verification has been set to `VERIFICATION_STATUS_PROCESSING_COMPLETE`, as reported by the `INCOME: verification_status` webhook. Attempting to call the endpoint before verification has been completed will result in an error. This endpoint has been deprecated; new integrations should use `/credit/payroll_income/get` instead. /income/verification/documents/download: x-plaid-business-unit-context: BUSINESS_UNIT_PLAID post: deprecated: true summary: >- Plaid (Deprecated) Download the original documents used for income verification tags: - Plaid externalDocs: url: /api/products/income/#incomeverificationdocumentsdownload operationId: incomeVerificationDocumentsDownload responses: '200': description: >- A ZIP file containing source documents(s) used as the basis for income verification. content: application/zip: schema: type: string format: binary description: >- `/income/verification/documents/download` provides the ability to download the source documents associated with the verification. If Document Income was used, the documents will be those the user provided in Link. For Payroll Income, the most recent files available for download from the payroll provider will be available from this endpoint. The response to `/income/verification/documents/download` is a ZIP file in binary data. If a `document_id` is passed, a single document will be contained in this file. If not, the response will contain all documents associated with the verification. The `request_id` is returned in the `Plaid-Request-ID` header. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IncomeVerificationDocumentsDownloadRequest' parameters: [] /income/verification/taxforms/get: x-plaid-business-unit-context: BUSINESS_UNIT_PLAID post: deprecated: true tags: - Plaid summary: >- Plaid (Deprecated) Retrieve information from the tax documents used for income verification externalDocs: url: /api/products/income/#incomeverificationtaxformsget operationId: incomeVerificationTaxformsGet description: >- `/income/verification/taxforms/get` returns the information collected from forms that were used to verify an end user''s income. It can be called once the status of the verification has been set to `VERIFICATION_STATUS_PROCESSING_COMPLETE`, as reported by the `INCOME: verification_status` webhook. Attempting to call the endpoint before verification has been completed will result in an error. This endpoint has been deprecated; new integrations should use `/credit/payroll_income/get` instead. responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/IncomeVerificationTaxformsGetResponse' examples: example-1: value: document_metadata: - doc_id: q5Ypbbr03p doc_type: DOCUMENT_TYPE_US_TAX_W2 name: my_w2.pdf status: DOCUMENT_STATUS_PROCESSING_COMPLETE request_id: 73W7sz8nIP8Mgck taxforms: - document_type: W2 w2: allocated_tips: '1000' box_12: - amount: '200' code: AA box_9: box9 dependent_care_benefits: '1000' employee: address: city: San Francisco country: US postal_code: '94103' region: CA street: 1234 Grand St name: Josie Georgia Harrison marital_status: single taxpayer_id: id_type: SSN id_mask: '1234' employer: address: city: New York country: US postal_code: '10010' region: NY street: 456 Main St name: Acme Inc employee_id_number: 12-1234567 federal_income_tax_withheld: '1000' medicare_tax_withheld: '1000' medicare_wages_and_tips: '1000' nonqualified_plans: '1000' other: other retirement_plan: CHECKED social_security_tax_withheld: '1000' social_security_tips: '1000' social_security_wages: '1000' state_and_local_wages: - employer_state_id_number: 11111111111AAA local_income_tax: '200' local_wages_tips: '200' locality_name: local state: UT state_income_tax: '200' state_wages_tips: '200' statutory_employee: CHECKED tax_year: '2020' third_party_sick_pay: CHECKED wages_tips_other_comp: '1000' default: description: Error response. content: application/json: schema: $ref: '#/components/schemas/PlaidError' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IncomeVerificationTaxformsGetRequest' description: '' /income/verification/precheck: x-plaid-business-unit-context: BUSINESS_UNIT_PLAID post: deprecated: true summary: >- Plaid (Deprecated) Check digital income verification eligibility and optimize conversion tags: - Plaid operationId: incomeVerificationPrecheck externalDocs: url: /api/products/income/#incomeverificationprecheck responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/IncomeVerificationPrecheckResponse' examples: example-1: value: request_id: lMjeOeu9X1VUh1F precheck_id: n9elqYlvYm confidence: HIGH description: >- `/income/verification/precheck` is an optional endpoint that can be called before initializing a Link session for income verification. It evaluates whether a given user is supportable by digital income verification and returns a `precheck_id` that can be provided to `/link/token/create`. If the user is eligible for digital verification, providing the `precheck_id` in this way will generate a Link UI optimized for the end user and their specific employer. If the user cannot be confirmed as eligible, the `precheck_id` can still be provided to `/link/token/create` and the user can still use the income verification flow, but they may be required to manually upload a paystub to verify their income. While all request fields are optional, providing either `employer` or `transactions_access_tokens` data will increase the chance of receiving a useful result. This endpoint has been deprecated; new integrations should use `/credit/payroll_income/precheck` instead. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IncomeVerificationPrecheckRequest' /sandbox/income/fire_webhook: x-plaid-business-unit-context: BUSINESS_UNIT_PLAID post: summary: Plaid Manually fire an Income webhook tags: - Plaid externalDocs: url: /api/sandbox/#sandboxincomefire_webhook operationId: sandboxIncomeFireWebhook responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SandboxIncomeFireWebhookResponse' examples: example-1: value: request_id: mdqfuVxeoza6mhu default: description: Error response content: application/json: schema: $ref: '#/components/schemas/PlaidError' description: >- Use the `/sandbox/income/fire_webhook` endpoint to manually trigger a Payroll or Document Income webhook in the Sandbox environment. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SandboxIncomeFireWebhookRequest' components: schemas: IncomeVerificationCreateResponse: title: IncomeVerificationCreateResponse type: object additionalProperties: true description: >- IncomeVerificationCreateResponse defines the response schema for `/income/verification/create`. properties: income_verification_id: type: string description: >- ID of the verification. This ID is persisted throughout the lifetime of the verification. request_id: $ref: '#/components/schemas/RequestID' required: - income_verification_id - request_id IncomeVerificationPaystubsGetResponse: title: IncomeVerificationPaystubsGetResponse type: object additionalProperties: true description: >- IncomeVerificationPaystubsGetResponse defines the response schema for `/income/verification/paystubs/get`. properties: document_metadata: description: Metadata for an income document. type: array items: $ref: '#/components/schemas/DocumentMetadata' paystubs: type: array items: $ref: '#/components/schemas/Paystub' error: $ref: '#/components/schemas/PlaidError' request_id: $ref: '#/components/schemas/RequestID' required: - paystubs - request_id IncomeVerificationTaxformsGetResponse: title: IncomeVerificationTaxformsGetResponse type: object additionalProperties: true description: >- IncomeVerificationTaxformsGetResponse defines the response schema for `/income/verification/taxforms/get` properties: request_id: $ref: '#/components/schemas/RequestID' document_metadata: type: array items: $ref: '#/components/schemas/DocumentMetadata' taxforms: type: array description: A list of forms. items: $ref: '#/components/schemas/Taxform' error: $ref: '#/components/schemas/PlaidError' required: - taxforms - document_metadata 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 IncomeVerificationPrecheckResponse: title: IncomeVerificationPrecheckResponse additionalProperties: true type: object description: >- IncomeVerificationPrecheckResponse defines the response schema for `/income/verification/precheck`. properties: precheck_id: type: string description: >- ID of the precheck. Provide this value when calling `/link/token/create` in order to optimize Link conversion. request_id: $ref: '#/components/schemas/RequestID' confidence: $ref: '#/components/schemas/IncomeVerificationPrecheckConfidence' required: - precheck_id - confidence - request_id SandboxIncomeFireWebhookResponse: title: SandboxIncomeFireWebhookResponse additionalProperties: true type: object description: >- SandboxIncomeFireWebhookResponse defines the response schema for `/sandbox/income/fire_webhook` properties: request_id: $ref: '#/components/schemas/RequestID' required: - request_id