openapi: 3.2.0 info: title: Open Finance Verify Income and Employment API description: 'OpenAPI specification for Finicity APIs. Open Finance (formerly Open Banking) solutions in the US are provided by Finicity, a Mastercard company.' contact: name: API Support email: apisupport@mastercard.com url: https://developer.mastercard.com/open-finance-us/documentation/support/ version: 1.43.0 servers: - url: https://api.finicity.com description: Production security: - FinicityAppKey: [] FinicityAppToken: [] tags: - name: Verify Income and Employment description: Generate income and employment reports asynchronously paths: /decisioning/v2/customers/{customerId}/voi: post: tags: - Verify Income and Employment summary: Generate VOI Report for the Customer description: 'Generate a Verification of Income (VOI) report for all checking, savings, and money market accounts for the given customer. This service retrieves up to two years of transaction history for each account and uses this information to generate the VOI report. This is a premium service. The billing rate is the variable rate for Verification of Income under the current subscription plan. The billable event is the successful generation of a VOI report. If no account of type checking, savings, or money market is found, the service will return HTTP 400 Bad Request. _Supported regions_: ![🇺🇸](https://flagcdn.com/20x15/us.png)' operationId: GenerateVOIReport parameters: - $ref: '#/components/parameters/CustomerIdParameter' - $ref: '#/components/parameters/ReportCallbackUrlParameter' requestBody: $ref: '#/components/requestBodies/GenerateVOIReportRequest' responses: '202': $ref: '#/components/responses/GenerateVOIReportResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/SecurityFreezeErrorResponse' '404': $ref: '#/components/responses/ResourceNotFoundErrorResponse' /decisioning/v2/customers/{customerId}/voePayroll: post: tags: - Verify Income and Employment summary: Generate VOE - Payroll Report for the Customer description: 'Generate or refresh a VOE - Payroll report. Often used as a complementary report to the VOIE-Payroll report to fulfill the pre-close VOE requirements. It retrieves the customer''s employment details and employment status through the payroll source without any income information. This is a premium service. The billable event is the successful generation of a VOE - Payroll report. _Supported regions_: ![🇺🇸](https://flagcdn.com/20x15/us.png)' operationId: GenerateVOEPayrollReport parameters: - $ref: '#/components/parameters/CustomerIdParameter' - $ref: '#/components/parameters/ReportCallbackUrlParameter' requestBody: $ref: '#/components/requestBodies/GeneratePayrollReportRequest' responses: '202': $ref: '#/components/responses/GenerateVOEPayrollReportResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/SecurityFreezeErrorResponse' '404': $ref: '#/components/responses/ResourceNotFoundErrorResponse' /decisioning/v2/customers/{customerId}/voeTransactions: post: tags: - Verify Income and Employment summary: Generate VOE - Transactions Report for the Customer description: 'Premium Service: A billable event when the API response is successful. MVS-Direct integration developers only. Used as a complimentary report to the VOA with Income and VOIE - Paystub (with TXVerify) reports and used to fulfill the pre-close VOE requirements. Retrieve the latest credit transaction information from the borrower''s connected bank accounts and groups them into income streams so that you can view their payment history to ensure a direct deport was made within the expected cadence. The report displays transaction descriptions without any dollar amounts so that income re-verification isn''t necessary. _Supported regions_: ![🇺🇸](https://flagcdn.com/20x15/us.png)' operationId: GenerateVOETransactionsReport parameters: - $ref: '#/components/parameters/CustomerIdParameter' - $ref: '#/components/parameters/ReportCallbackUrlParameter' requestBody: $ref: '#/components/requestBodies/GenerateVOETransactionsReportRequest' responses: '202': $ref: '#/components/responses/GenerateVOETransactionsReportResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/SecurityFreezeErrorResponse' '404': $ref: '#/components/responses/ResourceNotFoundErrorResponse' /decisioning/v2/customers/{customerId}/payStatement: post: tags: - Verify Income and Employment summary: Generate Pay Statement Report for the Customer description: 'Generate Pay Statement Extraction Report for the given customer. This service accepts asset IDs of the stored pay statements to generate a Pay Statement Extraction Report. This is a premium service. The billing rate is the variable rate for Pay Statement Extraction Report under the current subscription plan. The billable event is the successful generation of a Pay Statement Extraction Report. _Supported regions_: ![🇺🇸](https://flagcdn.com/20x15/us.png)' operationId: GeneratePayStatementReport parameters: - $ref: '#/components/parameters/CustomerIdParameter' - $ref: '#/components/parameters/ReportCallbackUrlParameter' requestBody: $ref: '#/components/requestBodies/GeneratePayStatementReportRequest' responses: '202': $ref: '#/components/responses/GeneratePayStatementReportResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/SecurityFreezeErrorResponse' '404': $ref: '#/components/responses/ResourceNotFoundErrorResponse' /decisioning/v2/customers/{customerId}/voieTxVerify/withInterview: post: tags: - Verify Income and Employment summary: Generate VOIE Paystub (With TXVerify) Report for the Customer description: 'Generate a VOIE - Paystub (with TXVerify) report for all checking and savings under the given customer. This service retrieves up to two years of transaction history for the given accounts. It then uses this information as well as the provided paystub(s), which are passed into the request body as asset IDs (generated using the Store Customer Pay Statement API) to generate the VOIE - Paystub (with TXVerify) report. Note: if you are using this API to refresh the bank transactions, use the same asset ID from the first report. A new paystub is not required unless the paystub is too old for underwriting requirements. Using the same asset ID that was on the original report and the previously extracted details will be used to speed up report generation response time. This is a premium service. The billing rate is the variable rate for VOIE TXVerify under the current subscription plan. The billable event is the successful generation of a VOIE TXVerify Report. _Supported regions_: ![🇺🇸](https://flagcdn.com/20x15/us.png)' operationId: GenerateVOIEPaystubWithTXVerifyReport parameters: - $ref: '#/components/parameters/CustomerIdParameter' - $ref: '#/components/parameters/ReportCallbackUrlParameter' requestBody: $ref: '#/components/requestBodies/GenerateVOIEPaystubWithTXVerifyReportRequest' responses: '202': $ref: '#/components/responses/GenerateVOIEPaystubWithTXVerifyReportResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/SecurityFreezeErrorResponse' '404': $ref: '#/components/responses/ResourceNotFoundErrorResponse' /decisioning/v2/customers/{customerId}/voieTxVerify/withStatement: post: tags: - Verify Income and Employment summary: Generate VOIE - Paystub Report for the Customer description: 'Generate a VOIE - Paystub report. This service uses the provided paystub(s), which are passed into the request body as asset IDs (generated using the Store Customer Pay Statement API) to generate the VOIE - Paystub report with digitized paystub details. This is a premium service. The billing rate is the variable rate for VOIE - Paystub under the current subscription plan. The billable event is the successful generation of a VOIE - Paystub Report. _Supported regions_: ![🇺🇸](https://flagcdn.com/20x15/us.png)' operationId: GenerateVOIEPaystubReport parameters: - $ref: '#/components/parameters/CustomerIdParameter' - $ref: '#/components/parameters/ReportCallbackUrlParameter' requestBody: $ref: '#/components/requestBodies/GenerateVOIEPaystubReportRequest' responses: '202': $ref: '#/components/responses/GenerateVOIEPaystubReportResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/SecurityFreezeErrorResponse' '404': $ref: '#/components/responses/ResourceNotFoundErrorResponse' /decisioning/v2/customers/{customerId}/voiePayroll: post: tags: - Verify Income and Employment summary: Generate VOIE - Payroll Report for the Customer description: 'Generate or refresh a VOIE - Payroll report. For clients using the product via a consumer permissioning experience via Connect, the original VOIE - Payroll report generates when the consumer completes the Data Connect experience, and this API is only used for future report refreshes without reengaging the consumer. This is a premium service. The billable event is the successful generation of a VOIE - Payroll report. _Supported regions_: ![🇺🇸](https://flagcdn.com/20x15/us.png)' operationId: RefreshVOIEPayrollReport parameters: - $ref: '#/components/parameters/CustomerIdParameter' - $ref: '#/components/parameters/ReportCallbackUrlParameter' requestBody: $ref: '#/components/requestBodies/GeneratePayrollReportRequest' responses: '202': $ref: '#/components/responses/RefreshVOIEPayrollReportResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/UnauthorizedErrorResponse' '403': $ref: '#/components/responses/SecurityFreezeErrorResponse' '404': $ref: '#/components/responses/ResourceNotFoundErrorResponse' components: examples: MissingFinicityAppKeyExample: value: code: '10026' message: Missing parameter (Finicity-App-Key) ResellerNoReportForPartnerExample: value: code: '10100' message: Cannot find resellerBilling reports with id 2445581559892. ResellerInvalidDateRangeGreaterThan31DaysExample: value: code: '10100' message: 'RESELLER_BILLING_REPORT: Invalid date range - It is more than 31 days' ResellerInvalidDateRangeGreaterThanEndDateExample: value: code: '10100' message: 'RESELLER_BILLING_REPORT: Invalid date range - startDate is greaterThan endDate' GeneratePayStatementReportResponseExample: value: id: y0ejausptjg1-paystatement portfolioId: spd8aehuw63i-10-port customerType: active customerId: 1003413624 requestId: 8wy5htqg8u requesterName: Decisioning API endUser: name: ABC Apartments address: 123 Main St city: Murray state: UT zip: '84123' phone: 555-2106 email: customerservice@example.com url: example.com createdDate: 1588350269 title: Mastercard Open Banking Pay Statement Extraction Report consumerId: 4089f408963dd6b90b28a935e9903c0e consumerSsn: '6789' consumerDetails: id: 3f7ff2cf0ffb3d0cd59875e070c9b1d4 firstName: John middleName: Doe lastName: Jane address: 123 Marple Street city: Anytown state: PA zip: '17101' phone: '5551234567' ssn: '1234' email: john.doe@example.com constraints: paystatementReport: assetIds: - 6f8fb0a0-e882-4f57-b672-cf53f1397581 extractEarnings: true extractDeductions: false extractDirectDeposit: true reportCustomFields: - label: loanID value: '12345' shown: true - label: trackingID value: '5555' shown: true - label: loanType value: car shown: false - label: vendorID value: 1613aa23 shown: true - label: vendorName value: PSC Finance shown: false type: paystatement status: inProgress SecurityFreezeErrorExample: value: code: '10405' status: '403' message: The active security freeze for this consumer exists. BothCraAndFtcPurposeTrueExample: value: code: '10100' status: '400' message: forCRAPurpose and forFTCPurpose may not both be TRUE. GenerateVOETransactionsReportRequestExample: value: reportId: j7k8qbgwsa7d-voietxverify accountIds: '123456789' fromDate: 1580558400 reportCustomFields: - label: loanID value: '12345' shown: true - label: trackingID value: '5555' shown: true - label: loanType value: car shown: false - label: vendorID value: 1613aa23 shown: true - label: vendorName value: PSC Finance shown: false incomeStreamConfidenceMinimum: 50 MissingFieldExample: value: code: '10005' message: Missing parameter (partnerId) ResellerInvalidDateRangeLessThanZeroExample: value: code: '10100' message: 'RESELLER_BILLING_REPORT: Invalid date range - start or end date less than or equal to zero' GeneratePayStatementReportRequestExample: value: paystatementReport: assetIds: - 6f8fb0a0-e882-4f57-b672-cf53f1397581 extractEarnings: true extractDeductions: false extractDirectDeposit: true reportCustomFields: - label: loanID value: '12345' shown: true - label: trackingID value: '5555' shown: true - label: loanType value: car shown: false - label: vendorID value: 1613aa23 shown: true - label: vendorName value: PSC Finance shown: false InvalidConsumerEmailExample: value: code: '10100' message: Invalid format for field consumer.email. GenerateVOETransactionsReportResponseExample: value: id: u4hstny1k25g-voetransactions portfolioId: dyr6weqd2yhb-2-port customerType: active customerId: 1000006677 requestId: sfb7x1we9w requesterName: Decisioning API endUser: name: ABC Apartments address: 123 Main St city: Murray state: UT zip: '84123' phone: 555-2106 email: customerservice@example.com url: example.com createdDate: 1588350269 title: Mastercard Open Banking Verification Employment - Transactions consumerId: ac39e237c7619a4ecf014b8d399c0696 consumerSsn: '6789' consumerDetails: id: 3f7ff2cf0ffb3d0cd59875e070c9b1d4 firstName: John middleName: Doe lastName: Jane address: 123 Marple Street city: Anytown state: PA zip: '17101' phone: '5551234567' ssn: '1234' email: john.doe@example.com constraints: reportId: j7k8qbgwsa7d-voietxverify reportCustomFields: - label: loanID value: '12345' shown: true - label: trackingID value: '5555' shown: true - label: loanType value: car shown: false - label: vendorID value: 1613aa23 shown: true - label: vendorName value: PSC Finance shown: false type: voeTransactions status: inProgress BadCredentialsExample: value: code: '24302' message: Bad credentials GenerateVOIReportRequestExample: value: accountIds: 1000535275 1000535276 fromDate: 1577986990 reportCustomFields: - label: loanID value: '12345' shown: true - label: trackingID value: '5555' shown: true - label: loanType value: car shown: false - label: vendorID value: 1613aa23 shown: true - label: vendorName value: PSC Finance shown: false incomeStreamConfidenceMinimum: 50 InvalidForesightReportRequestExample: value: code: '10100' message: At least one of customerId or externalCustomerId must be provided; both are also allowed. GenerateVOIEPaystubWithTXVerifyReportResponseExample: value: id: 2f3z55zuwewm-voietxverify customerId: 1275320 consumerId: 3f7ff2cf0ffb3d0cd59875e070c9b1d4 consumerSsn: '6789' consumerDetails: id: 3f7ff2cf0ffb3d0cd59875e070c9b1d4 firstName: John middleName: Doe lastName: Jane address: 123 Marple Street city: Anytown state: PA zip: '17101' phone: '5551234567' ssn: '1234' email: john.doe@example.com requesterName: Decisioning API endUser: name: ABC Apartments address: 123 Main St city: Murray state: UT zip: '84123' phone: 555-2106 email: customerservice@example.com url: example.com requestId: 7a7qyps2iy type: voieTxVerify status: inProgress createdDate: 1579819592 constraints: accountIds: - '1000535275' voieWithInterviewData: txVerifyInterview: - assetId: 6f8fb0a0-e882-4f57-b672-cf53f1397581 accounts: [] extractEarnings: true extractDeductions: false extractDirectDeposit: true reportCustomFields: - label: loanID value: '123456' shown: true customerType: active title: Finicity Verification of Income and Employment - Paystub (with TXVerify) portfolioId: 9qud7dtuzbew-2-port NoRegisteredApplicationExample: value: code: '50051' message: No registered partner applications found. ExpiredFinicityAppTokenExample: value: code: '10023' message: Expired (Finicity-App-Token) InvalidFieldExample: value: code: '10010' status: '400' message: Customer ID does not exist or does not belong to this partner user_message: One or more of the fields could not be validated. Please ensure you have entered the correct data. tags: '' InvalidValueExample: value: code: '1618' message: Negative or invalid value entered. Please use positive numbers only. InvalidConsumerSSNExample: value: code: '10100' message: Invalid format for field consumer.ssn. Required format is 9 digits. InvalidFinicityAppTokenExample: value: code: '10022' message: Invalid (Finicity-App-Token) NoAccountForInstitutionLoginIdExample: value: code: '38007' message: Customer does not have any accounts associated with institutionLoginId. CustomerNotFoundExample: value: code: '14001' message: Customer not found. ResellerNoDataForPartnerExample: value: code: '10100' message: 'RESELLER_BILLING_REPORT: Reports not found 2445583947903 resellerBilling reports' ExpiredTokenExample: value: code: '10023' message: Expired (Finicity-App-Token) GenerateVOIReportResponseExample: value: id: u4hstnnaewetr-voi portfolioId: dyr6qvqd2erw-1-port customerType: active customerId: 1000006677 requestId: sfb7xp4wer requesterName: Decisioning API endUser: name: ABC Apartments address: 123 Main St city: Murray state: UT zip: '84123' phone: 555-2106 email: customerservice@example.com url: example.com createdDate: 1588350269 title: Mastercard Open Banking Verification of Income consumerId: ac39e237c7619a4ecf014b8d399c0696 consumerSsn: '6789' consumerDetails: id: 3f7ff2cf0ffb3d0cd59875e070c9b1d4 firstName: John middleName: Doe lastName: Jane address: 123 Marple Street city: Anytown state: PA zip: '17101' phone: '5551234567' ssn: '1234' email: john.doe@example.com constraints: accountIds: - '1000535275' - '1000535276' fromDate: 1577986990 reportCustomFields: - label: loanID value: '12345' shown: true - label: trackingID value: '5555' shown: true - label: loanType value: car shown: false - label: vendorID value: 1613aa23 shown: true - label: vendorName value: PSC Finance shown: false type: voi status: inProgress ResellerInvalidDateRangeExample: value: code: '10100' message: 'RESELLER_BILLING_REPORT: Invalid date range - start or end date is empty or null' ResourceNotFoundExample: value: code: '14001' message: Resource not found. ConsumerNotFoundExample: value: code: '10100' message: Cannot find consumer with id 1234. RefreshVOIEPayrollReportResponseExample: value: id: 123456789012-voiepayroll customerId: 1011140000 consumerId: 656cf7083c5c06e0c125a698579f0000 consumerSsn: '6789' consumerDetails: id: 3f7ff2cf0ffb3d0cd59875e070c9b1d4 firstName: John middleName: Doe lastName: Jane address: 123 Marple Street city: Anytown state: PA zip: '17101' phone: '5551234567' ssn: '1234' email: john.doe@example.com requesterName: Decisioning API endUser: name: ABC Apartments address: 123 Main St city: Murray state: UT zip: '84123' phone: 555-2106 email: customerservice@example.com url: example.com requestId: 7a7qyps2iy type: voiePayroll reportStyle: credentialedPayroll status: inProgress createdDate: 1579819592 constraints: payrollData: payrollAccountIds: - 018b8f10-fdf8-0ef7-ded5-34a17c34d86f reportCustomFields: - label: loanID value: '12345' shown: true customerType: active title: Mastercard Open Banking Verification of Income and Employment - Payroll portfolioId: 9qud7dtuzbew-2-port GenerateVOIEPaystubReportRequestExample: value: voieWithStatementData: assetIds: - d50ed92f-543b-431c-8286-c8b8f6556679 reportCustomFields: - label: loanID value: '123456' shown: true - label: trackingID value: '5555' shown: true GenericBadRequestExample: value: code: '14020' message: Bad request. GenerateVOIEPaystubReportResponseExample: value: id: 2f3z55zuwewm-voietxverify portfolioId: 9qud7dtuzbew-13-port customerType: active customerId: 1275320 requestId: 7a7qyps2iy requesterName: Decisioning API endUser: name: ABC Apartments address: 123 Main St city: Murray state: UT zip: '84123' phone: 555-2106 email: customerservice@example.com url: example.com createdDate: 1579819592 title: Verification of Income and Employment - Paystub consumerId: 3f7ff2cf0ffb3d0cd59875e070c9b1d4 consumerSsn: '6789' consumerDetails: id: 3f7ff2cf0ffb3d0cd59875e070c9b1d4 firstName: John middleName: Doe lastName: Jane address: 123 Marple Street city: Anytown state: PA zip: '17101' phone: '5551234567' ssn: '1234' email: john.doe@example.com constraints: voieWithStatementData: assetIds: - d50ed92f-543b-431c-8286-c8b8f6556679 extractEarnings: true extractDeductions: false extractDirectDeposit: true reportCustomFields: - label: loanID value: '123456' shown: true - label: trackingID value: '5555' shown: true type: voieTxVerify status: inProgress InvalidConsumerPhoneExample: value: code: '10100' message: Invalid format for field consumer.phone. AccountTypeNotSupportedExample: value: code: '14020' message: Bad request. (Account type not supported). PermissiblePurposeCodeExample: value: code: '10100' status: '400' message: Permissible Purpose Code is required GenerateVOEPayrollReportResponseExample: value: id: 41h4nzppn47u-voepayroll portfolioId: 9qud7dtuzbew-1-port customerType: active customerId: 1011140000 requestId: 7a7qyps2iy type: voePayroll reportStyle: directAPIPayroll requesterName: Decisioning API endUser: name: ABC Apartments address: 123 Main St city: Murray state: UT zip: '84123' phone: 555-2106 email: customerservice@example.com url: example.com createdDate: 1579819592 title: Mastercard Open Banking Verification of Employment - Payroll consumerId: 656cf7083c5c06e0c125a698579f0000 consumerSsn: '6789' consumerDetails: id: 3f7ff2cf0ffb3d0cd59875e070c9b1d4 firstName: John middleName: Doe lastName: Jane address: 123 Marple Street city: Anytown state: PA zip: '17101' phone: '5551234567' ssn: '1234' email: john.doe@example.com constraints: payrollData: payrollDataRetrievalId: uvhjy7pwa1t5 payrollAccountIds: - 018bf5c9-b542-c2ba-8f92-c5c7be6be515 reportCustomFields: - label: loanID value: '12345' shown: true status: inProgress ResellerPartnerNotAuthorizedExample: value: code: '10100' message: 'RESELLER_BILLING_REPORT: Partner is not authorized to access resellerBilling reports for partnerId 2445583947903' GenerateVOIEPaystubWithTXVerifyReportRequestExample: value: accountIds: '1028361677' voieWithInterviewData: txVerifyInterview: - assetId: 7eb57060-6d98-4449-992d-4dd4490448f3-1236011097 reportCustomFields: - label: loanID value: '123456' shown: true CustomerReportLimitExceedExample: value: code: '20400' message: The max report generation limit was exceeded for this customer. GeneratePayrollReportRequestExample: value: payrollData: ssn: '999990000' dob: '315576000' reportId: abcdefghijkl-voiepayroll reportCustomFields: - label: loanID value: '12345' shown: true payStatementsFromDate: 1580558400 marketSegment: Mortgage purpose: '31' InvalidExperienceFieldExample: value: code: '10010' status: '400' message: '"experience" must be a valid GUID' user_message: One or more of the fields could not be validated. Please ensure you have entered the correct data. tags: '' NoConsumerForCustomerExample: value: code: '10100' message: Cannot find consumer for customer with id 5011115315." MissingFinicityAppTokenExample: value: code: '10024' message: Missing parameter (Finicity-App-Token) schemas: SecurityFreezeErrorMessage: required: - code - message type: object properties: code: type: integer description: 'An error code for security freeze. Useful links: [API Errors](https://developer.mastercard.com/open-finance-us/documentation/errors/), [Aggregation Status Codes](https://developer.mastercard.com/open-finance-us/documentation/products/manage/aggregation-status-codes/).' format: int32 example: 10405 status: type: string description: A status code example: '403' message: type: string description: An error message example: The active security freeze for this consumer exists. EndUserUrl: type: string description: Reseller end user URL minLength: 2 maximum: 999 example: testurl.com ReportType: description: 'A report type. Possible values: * `voi` * `voa` * `voaHistory` * `history` * `voieTxVerify` * `voieWithReport` * `voieWithInterview` * `voieWithStatement` * `paystatement` * `preQualVoa` * `assetSummary` * `voie` * `transactions` * `statement` * `voiePayroll` * `voeTransactions` * `farpbfnoncra` * `voePayroll` * `cfrp` * `cfrb` * `barpcra` * `barpnoncra` * `barbcra` * `barbftc` * `barbnoncra` * `cfrpcra` * `cfrpnoncra` * `cracfrbcra` * `cfrbnoncra` * `cfrbftc` * `phrbcra` * `phrbnoncra` * `phrbftc` * `sbcaanalyticsnoncra` * `sbcabenchmarksnoncra` * `pripcra` * `pripnoncra` * `pribcra` * `pribnoncra` * `pribftc` ' type: string example: voi ZipCode: type: string description: A ZIP code example: '84123' ReportCustomField: type: object properties: label: type: string description: The name of the custom field example: loanID value: type: string description: The value of the custom field example: '123456' shown: type: boolean description: If the custom field will show on the PDF or not example: true PayStatementsFromDate: type: integer description: 'Limits the pay statement history in the VOIE - Payroll report income record. Pay statements are only included if the payDate of the statement is equal to or greater than the start date requested. Date should be in Unix epoch time (in seconds). See: Handling Epoch Dates and Times.' format: int64 example: 1607450357 VOIReportConstraintsOut: type: object properties: accountIds: $ref: '#/components/schemas/ReportAccountIds' reportCustomFields: $ref: '#/components/schemas/ReportCustomFields' fromDate: $ref: '#/components/schemas/UnixDate' incomeStreamConfidenceMinimum: $ref: '#/components/schemas/IncomeStreamConfidenceMinimum' NumericCustomerId: type: integer format: int64 description: A customer ID represented as a number. See Add Customer API for how to create a customer ID. example: 1005061234 TransactionsReportConstraintsOut: type: object properties: accountIds: $ref: '#/components/schemas/ReportAccountIds' fromDate: $ref: '#/components/schemas/UnixDate' toDate: $ref: '#/components/schemas/UnixDate' includePending: $ref: '#/components/schemas/IncludePending' reportCustomFields: $ref: '#/components/schemas/ReportCustomFields' findTransaction: $ref: '#/components/schemas/FindTransactionConstraints' ConsumerId: type: string description: A consumer ID. See Create Consumer API for how to create a consumer ID. example: 0bf46322c167b562e6cbed9d40e19a4c BaseReportAckWithPortfolioId: description: Properties shared by all generated reports having a portfolio ID allOf: - $ref: '#/components/schemas/BaseReportAck' - type: object properties: portfolioId: $ref: '#/components/schemas/PortfolioId' PayStatementData: description: Data to be included within the pay statement report required: - assetIds type: object properties: assetIds: description: A list of pay statement asset IDs type: array items: $ref: '#/components/schemas/AssetId' extractEarnings: $ref: '#/components/schemas/ExtractEarnings' extractDeductions: $ref: '#/components/schemas/ExtractDeductions' extractDirectDeposit: $ref: '#/components/schemas/ExtractDirectDeposit' EmailAddress: type: string description: An email address example: myname@mycompany.com VOAIncomeReportIncomeFromDate: type: integer description: 'A date in Unix epoch time (in seconds). See: [Handling Epoch Dates and Times](https://developer.mastercard.com/open-finance-us/documentation/errors/best-practices/). By default, the income history is set to 24 months, however, a partner can change the transaction history by setting the `incomeFromDate` parameter.' format: int64 example: 1607450357 ConsumerDateOfBirth: type: integer description: 'The consumer''s date of birth in Unix epoch time (in seconds). See: Handling Epoch Dates and Times. The timestamp should be set at the start of day of birth.' format: int64 example: 1607450357 FindTransactionDescriptionMemo: type: string description: "A string to return transactions that have an exact match to Description/Memo.
\n- Description/Memo
\n - Found in the PDF report for reach transactions.
\n - A combination of **description** and **memo** from the JSON version\nof the report.
\n" example: Paycheck FindTransactionAmountTo: type: number description: 'A decimal value to return transactions with **amount** less than or equal to **findTransactionAmountTo**.
- If both **findTransactionAmountFrom** and **findTransactionAmountTo** are present. Then transactions with **amount** between (inclusive) both values will be returned. ' example: 100 PayrollData: type: object properties: ssn: $ref: '#/components/schemas/SSNPayroll' dob: $ref: '#/components/schemas/ConsumerDateOfBirth' reportId: $ref: '#/components/schemas/OriginalPayrollReportId' payrollAccountIds: type: array items: $ref: '#/components/schemas/PayrollAccountId' Age: type: integer description: Age is an optional parameter. This data is used to determine the age band the customer falls into. format: int64 example: 25 minimum: 0 maximum: 125 GeoLocation: type: array items: $ref: '#/components/schemas/GeoLocationItems' description: Geolocation array of objects; TimeIntervalType: description: Possible values for strategies in which attributes may be aggregated and reported across varying time intervals. Allowed Values - MONTHLY_CALENDAR - MONTHLY_ROLLING_30 example: MONTHLY_CALENDAR type: string default: MONTHLY_CALENDAR PayStatementReportConstraints: required: - paystatementReport type: object properties: paystatementReport: $ref: '#/components/schemas/PayStatementData' reportCustomFields: $ref: '#/components/schemas/ReportCustomFields' VOAReportConstraintsOut: type: object properties: accountIds: $ref: '#/components/schemas/ReportAccountIds' reportCustomFields: $ref: '#/components/schemas/ReportCustomFields' toDate: $ref: '#/components/schemas/UnixDate' showNsf: $ref: '#/components/schemas/ShowNsf' fromDate: $ref: '#/components/schemas/UnixDate' AddressLine1: type: string description: Address line 1 example: 434 W Ascension Way PortfolioId: type: string description: A unique identifier that will be consistent across all reports created for the same customer example: y4zsgccj4xpw-6-port ReportAccountIds: description: An array of account IDs to be included in the report (all accounts will be included if not set) type: array items: $ref: '#/components/schemas/AccountId' example: - '5011648377' - '5011648378' - '5011648379' PrequalificationReportConstraintsOut: type: object properties: accountIds: $ref: '#/components/schemas/ReportAccountIds' reportCustomFields: $ref: '#/components/schemas/ReportCustomFields' showNsf: $ref: '#/components/schemas/ShowNsf' fromDate: $ref: '#/components/schemas/UnixDate' VOETransactionsReportConstraints: type: object properties: reportId: $ref: '#/components/schemas/ReportId' accountIds: $ref: '#/components/schemas/ReportAccountIdsString' reportCustomFields: $ref: '#/components/schemas/ReportCustomFields' fromDate: $ref: '#/components/schemas/UnixDate' incomeStreamConfidenceMinimum: $ref: '#/components/schemas/IncomeStreamConfidenceMinimum' VOETransactionsReportAck: description: A VOE Transactions report being generated required: - id - portfolioId - customerType - customerId - requestId - requesterName - createdDate - title - consumerId - consumerSsn - type - status - constraints allOf: - $ref: '#/components/schemas/BaseReportAckWithPortfolioId' - type: object properties: constraints: $ref: '#/components/schemas/VOETransactionsReportConstraintsOut' VOIEWithStatementData: required: - assetIds type: object properties: assetIds: description: A list of pay statement asset IDs type: array items: $ref: '#/components/schemas/AssetId' extractEarnings: $ref: '#/components/schemas/ExtractEarnings' extractDeductions: $ref: '#/components/schemas/ExtractDeductions' extractDirectDeposit: $ref: '#/components/schemas/ExtractDirectDeposit' IncomeStreamConfidenceMinimum: type: integer description: Include income streams in the report, based on the income stream's confidence score. For example, Use the value 50 to include only income streams with a confidence score of 50 or higher. format: int32 example: 50 MiddleName: type: string description: The middle name of the account holder example: L StatementReportConstraints: required: - statementReportData type: object properties: statementReportData: $ref: '#/components/schemas/StatementData' reportCustomFields: $ref: '#/components/schemas/ReportCustomFields' IncludePending: type: boolean description: If pending transactions must be included example: true default: false PhoneNumber: type: string description: A phone number (max length 15). example: 1-801-984-4200 ForesightAnalyticsReportData: description: Parameters supplied by the client requesting the analytics. properties: forCraPurpose: type: boolean description: Field to indicate if the requested report is for CRA or NONCRA. For small business lending or other similar business use cases, pass the value as “true” for purposes of this field. example: true segments: type: object description: Requested segments for attribute values. properties: geolocation: $ref: '#/components/schemas/GeoLocation' analytics: description: Analytics information for the requested report. The allowed values are benchmarking & forecasting. If it is null, default to benchmarking and forecasting example: - benchmarking - forecasting minItems: 2 maxItems: 2 items: $ref: '#/components/schemas/AnalyticsType' type: array timeIntervalTypes: description: Requested time interval for attribute values. example: - MONTHLY_CALENDAR maxItems: 2 items: $ref: '#/components/schemas/TimeIntervalType' type: array income: $ref: '#/components/schemas/Income' age: $ref: '#/components/schemas/Age' type: object ErrorMessage: required: - code type: object properties: code: type: object description: 'An error code (can be returned as a number or a string). Useful links: [Common API Status Codes](https://developer.mastercard.com/open-finance-us/documentation/errors/best-practices/#common-api-status-codes), [Aggregation Status Codes](https://developer.mastercard.com/open-finance-us/documentation/products/manage/account-aggregation/#aggregation-status-codes).' example: '10001' status: type: string description: A status code example: '401' title: type: string description: A title for the error example: Connecting accounts error level: type: string description: An error level example: error message: type: string description: An error message example: Invalid authorization credentials user_message: type: string description: Some more details about the error example: The session has expired or is invalid assetId: $ref: '#/components/schemas/AssetId' accountId: $ref: '#/components/schemas/AccountId' externalTransactionId: type: string description: A unique identifier for the transaction that assists in linking data back to your systems. example: MAC1005061234 minLength: 1 maxLength: 100 tags: type: string description: Categories that the error belongs to example: AGG GeoLocationItems: type: object properties: label: type: string description: The name of the Geolocation details. Possible values are POSTAL_CODE example: POSTAL_CODE value: type: string description: The value of the Geolocation field example: '85123' SocialSecurityNumberLastDigits: type: string description: Last 4 digits of a SSN example: '9999' ReportCustomFields: type: array items: $ref: '#/components/schemas/ReportCustomField' description: 'The `reportCustomFields` parameter is used when experiences are associated with a credit decisioning report. Designate up to 5 custom fields that you''d like associated with the report when it''s generated. Every custom field consists of three variables: `label`, `value`, and `shown`. The `shown` variable is "true" or "false". * "true": (default) display the custom field in the PDF report * "false": don''t display the custom field in the PDF report For an experience that generates multiple reports, the `reportCustomFields` parameter gets passed to all reports. All custom fields display in the Reseller Billing API.' ShowNsf: type: boolean description: 'Include the non-sufficient funds (NSF) summary JSON and the NSF summary PDF section in the report. Data included: * Account * Total number of NSF funds * Days since the most recent NFS funds fee' example: false AccountId: type: string description: An account ID example: '5011648377' PayrollDataRetrievalId: type: string description: An ID to identify the data retrieved from the payroll providers for the report. example: hahvhe2k0000 VOAWithIncomeReportConstraintsOut: type: object properties: accountIds: $ref: '#/components/schemas/ReportAccountIds' reportCustomFields: $ref: '#/components/schemas/ReportCustomFields' showNsf: $ref: '#/components/schemas/ShowNsf' fromDate: $ref: '#/components/schemas/UnixDate' incomeFromDate: $ref: '#/components/schemas/VOAIncomeReportIncomeFromDate' voaiPdfDepositView: type: - boolean - 'null' description: Provide an alternate PDF view of deposit transactions group by income stream in PDF. example: true incomeStreamConfidenceMinimum: $ref: '#/components/schemas/IncomeStreamConfidenceMinimum' ReportRequestId: type: string description: Finicity indicator to track all activity associated with this report example: cjqm4wtdcn EmploymentId: type: string description: This is a Mastercard assigned ID to the employment record. It remains consistent for that employment record, even if the report is refreshed. It can be used to limit the employment records that are returned in the report. example: 123v3bv2s5n ExtractDeductions: type: boolean description: Field to indicate whether to extract the deductions on all pay statements default: false example: true ReportStyle: type: string example: credentialedPayroll description: A report style. Possible values are directAPIPayroll, credentialedPayroll, paystatement, voieWithInterview, voieWithStatement, voieWithReport OriginalPayrollReportId: type: string description: The report ID of the original payroll report for refresh use cases. If used, only the employment records from the original report will be included in the refreshed report response. example: u4hstnnak45g-voiepayroll VOIEWithTXVerifyReportConstraintsOut: required: - voieWithInterviewData type: object properties: accountIds: $ref: '#/components/schemas/ReportAccountIds' voieWithInterviewData: $ref: '#/components/schemas/VOIEWithInterviewData' reportCustomFields: $ref: '#/components/schemas/ReportCustomFields' fromDate: $ref: '#/components/schemas/UnixDate' incomeStreamConfidenceMinimum: $ref: '#/components/schemas/IncomeStreamConfidenceMinimum' CashFlowReportConstraintsOut: type: object properties: accountIds: $ref: '#/components/schemas/ReportAccountIds' reportCustomFields: $ref: '#/components/schemas/ReportCustomFields' showNsf: $ref: '#/components/schemas/ShowNsf' fromDate: $ref: '#/components/schemas/UnixDate' incomeStreamConfidenceMinimum: $ref: '#/components/schemas/IncomeStreamConfidenceMinimum' AnalyticsReportData: description: Parameters supplied by the client requesting the analytics. properties: forCraPurpose: type: boolean description: Field to indicate if the requested report is for CRA or NONCRA. For small business lending or other similar business use cases, pass the value as “true” for purposes of this field. example: true applicantIsPersonalGuarantor: type: boolean description: Field to indicate if the business owner will personally guarantee the loan. If true, a consumer record will be required. example: true forFtcPurpose: type: boolean description: Field to indicate if the requested report is for FTC purpose. Only applicable to business reports. example: false timeIntervalTypes: description: Requested time interval for attribute values. example: - MONTHLY_CALENDAR maxItems: 2 items: $ref: '#/components/schemas/TimeIntervalType' type: array type: object FindTransactionAmountFrom: type: number description: 'A decimal value to return transactions with **amount** greater than or equal to **findTransactionAmountFrom**.
- If both **findTransactionAmountFrom** and **findTransactionAmountTo** are present. Then transactions with **amount** between (inclusive) both values will be returned. ' example: 100 LastName: type: string description: The last name of the account holder example: Smith Income: type: integer description: "Income is an optional parameter. It is the dollar amount for the customer's annual\n household income and is used to determine the income band the\ncustomer falls into." format: int64 example: 1000 minimum: 0 TxVerifyInterview: required: - assetId type: object properties: assetId: $ref: '#/components/schemas/AssetId' accounts: $ref: '#/components/schemas/ReportAccountIds' VOETransactionsReportConstraintsOut: type: object properties: reportId: $ref: '#/components/schemas/ReportId' accountIds: $ref: '#/components/schemas/ReportAccountIds' reportCustomFields: $ref: '#/components/schemas/ReportCustomFields' fromDate: $ref: '#/components/schemas/UnixDate' incomeStreamConfidenceMinimum: $ref: '#/components/schemas/IncomeStreamConfidenceMinimum' PayrollDataOut: type: object properties: payrollDataRetrievalId: $ref: '#/components/schemas/PayrollDataRetrievalId' payrollAggregatorResponseId: $ref: '#/components/schemas/PayrollDataRetrievalId' consentMethod: type: string description: Client-collected consent payroll report tagging. example: Written Generic - Finicity Set employmentIds: type: array description: An array of employmentIds items: $ref: '#/components/schemas/EmploymentId' payrollAccountIds: type: array description: An array of payrollAccountIds items: $ref: '#/components/schemas/PayrollAccountId' reportId: $ref: '#/components/schemas/ReportId' VOIReportAck: description: A VOI report being generated required: - id - portfolioId - customerType - customerId - requestId - requesterName - createdDate - title - consumerId - consumerSsn - type - status - constraints allOf: - $ref: '#/components/schemas/BaseReportAckWithPortfolioId' - type: object properties: constraints: $ref: '#/components/schemas/VOIReportConstraintsOut' ConsumerEndUser: description: Reseller end user information. This is populated only when the report requires a consumer record to be generated and the consumer object includes end user details. The partner is expected to include endUser details when creating a consumer if the end user of the consumer reports is another entity than the partner generating the report. required: - name - address - city - state - zip - phone type: object properties: name: $ref: '#/components/schemas/FirstName' address: $ref: '#/components/schemas/AddressLine1' city: $ref: '#/components/schemas/City' state: $ref: '#/components/schemas/State' zip: $ref: '#/components/schemas/ZipCode' phone: $ref: '#/components/schemas/PhoneNumber' email: $ref: '#/components/schemas/EmailAddress' url: $ref: '#/components/schemas/EndUserUrl' FindTransactionConstraints: description: Parameters used to return transactions matching the given criteria. The presence of multiple parameters will be treated as an **AND** function. type: object properties: findTransactionDescriptionMemo: $ref: '#/components/schemas/FindTransactionDescriptionMemo' findTransactionAmountFrom: $ref: '#/components/schemas/FindTransactionAmountFrom' findTransactionAmountTo: $ref: '#/components/schemas/FindTransactionAmountTo' findTransactionCategory: $ref: '#/components/schemas/FindTransactionCategory' PayrollReportAck: description: A Payroll report being generated required: - id - portfolioId - customerType - customerId - requestId - requesterName - createdDate - title - consumerId - consumerSsn - type - status - constraints allOf: - $ref: '#/components/schemas/BaseReportAckWithPortfolioId' - type: object properties: reportStyle: $ref: '#/components/schemas/ReportStyle' constraints: $ref: '#/components/schemas/PayrollReportConstraintsOut' DisputeStatement: description: A consumer-provided statement describing the nature of an unresolved dispute. This field is populated only if a consumer dispute remains unresolved, and the consumer has requested that a statement be included in their report. type: string minLength: 1 maxLength: 2000 example: Statement dispute text ReportStatus: type: string description: 'A report generation status. Possible values: * `inProgress` * `success` * `failure` ' example: inProgress VOIEPaystubReportAck: description: A VOIE Paystub report being generated required: - id - portfolioId - customerType - customerId - requestId - requesterName - createdDate - title - consumerId - consumerSsn - type - status - constraints type: object allOf: - $ref: '#/components/schemas/BaseReportAckWithPortfolioId' - type: object properties: constraints: $ref: '#/components/schemas/VOIEReportConstraints' VOIReportConstraints: type: object properties: accountIds: $ref: '#/components/schemas/ReportAccountIdsString' reportCustomFields: $ref: '#/components/schemas/ReportCustomFields' fromDate: $ref: '#/components/schemas/UnixDate' incomeStreamConfidenceMinimum: $ref: '#/components/schemas/IncomeStreamConfidenceMinimum' AssetId: type: string description: An asset ID. Generated by Data Connect or by using the Store Customer Pay Statement API. example: 097545c5-1c2a-4f20-a5ef-77f0820344c9-2018601178 AnalyticsType: description: Analytics type. Allowed Values are benchmarking and forecasting. example: benchmarking type: string ForesightAnalyticsReportConstraints: type: object properties: analyticsReportData: $ref: '#/components/schemas/ForesightAnalyticsReportData' accountIds: $ref: '#/components/schemas/ReportAccountIdsString' fromDate: $ref: '#/components/schemas/UnixDate' VOIEWithInterviewData: required: - txVerifyInterview type: object properties: txVerifyInterview: description: An array of `TxVerifyInterview` objects type: array items: $ref: '#/components/schemas/TxVerifyInterview' extractEarnings: $ref: '#/components/schemas/ExtractEarnings' extractDeductions: $ref: '#/components/schemas/ExtractDeductions' extractDirectDeposit: $ref: '#/components/schemas/ExtractDirectDeposit' VOIEPaystubWithTXVerifyReportAck: description: A VOIE Paystub With TXVerify report being generated required: - id - portfolioId - customerType - customerId - requestId - requesterName - createdDate - title - consumerId - consumerSsn - type - status - constraints allOf: - $ref: '#/components/schemas/BaseReportAckWithPortfolioId' - type: object properties: constraints: $ref: '#/components/schemas/VOIEWithTXVerifyReportConstraintsOut' CustomerType: type: string description: The type of customer ("active" or "testing" or "" for all types) example: active NumericAccountId: type: integer format: int64 description: An account ID represented as a number example: 5011648377 ExtractDirectDeposit: type: boolean description: Field to indicate whether to extract the direct deposits on all pay statements default: true example: true PartnerName: type: string description: Name of a Finicity partner example: Finicity Test API PayrollReportConstraintsOut: required: - payrollData type: object properties: payrollData: $ref: '#/components/schemas/PayrollDataOut' reportCustomFields: $ref: '#/components/schemas/ReportCustomFields' payStatementsFromDate: $ref: '#/components/schemas/UnixDate' PurposeCode: type: string description: FCRA required 2-digit Permissible Purpose Code, specifying the reason for retrieving this report. example: '31' VOIEReportConstraints: required: - voieWithStatementData type: object properties: voieWithStatementData: $ref: '#/components/schemas/VOIEWithStatementData' reportCustomFields: $ref: '#/components/schemas/ReportCustomFields' description: The request details from the report generation that were used to generate the report AnalyticsReportConstraintsOut: type: object properties: analyticsReportData: $ref: '#/components/schemas/AnalyticsReportData' accountIds: $ref: '#/components/schemas/ReportAccountIds' reportCustomFields: $ref: '#/components/schemas/ReportCustomFields' fromDate: $ref: '#/components/schemas/UnixDate' FindTransactionCategory: type: array description: 'An array of **categories** to return transactions with an exact match to the array of **category**. Limit of 10. ' maxItems: 10 items: type: string example: - Paycheck - Groceries PayrollAccountId: type: string description: "The payrollAccountIds for the Credentialed Payroll accounts the consumer\n has connected. Will be used to constrain the report to only\ninclude the\n specified accounts. Required if the consumer has connected\ntheir\n accounts previously and report generation was intentionally\ndelayed for\n later." example: 018b8f10-fdf8-0ef7-ded5-34a17c34d86f ConsumerDetails: description: Details about the consumer. Populated if the report requires a consumer record to be generated. type: object properties: id: $ref: '#/components/schemas/ConsumerId' firstName: $ref: '#/components/schemas/FirstName' middleName: $ref: '#/components/schemas/MiddleName' lastName: $ref: '#/components/schemas/LastName' address: $ref: '#/components/schemas/AddressLine1' city: $ref: '#/components/schemas/City' state: $ref: '#/components/schemas/State' zip: $ref: '#/components/schemas/ZipCode' phone: $ref: '#/components/schemas/PhoneNumber' ssn: $ref: '#/components/schemas/SocialSecurityNumberLastDigits' email: $ref: '#/components/schemas/EmailAddress' SSNPayroll: type: string description: The consumer's full SSN without hyphens. Only required for the Direct API Payroll solution, not required for the Credentialed Payroll solution. example: '999999999' ExtractEarnings: type: boolean description: Field to indicate whether to extract the earnings on all pay statements default: true example: true ReportTitle: type: string description: Title of the report example: Finicity Asset Ready Report (CRA) State: type: string description: State example: UT FirstName: type: string description: The first name of the account holder example: John ReportId: type: string description: A report ID example: u4hstnnak45g StatementData: required: - accountId type: object properties: accountId: $ref: '#/components/schemas/NumericAccountId' statementIndex: type: integer description: Index of the statement to include in the report. Request statements from 1-24. By default, 1 is the most recent statement. Increase the index value to count back (by month) and retrieve its most recent statement. format: int32 example: 1 default: 1 maximum: 24 ReportAccountIdsString: type: string description: A whitespace-separated list of account IDs to be included in the report (all accounts will be included if not set) example: 5011648377 5011648378 5011648379 PayStatementReportAck: description: A Pay Statement report being generated required: - id - portfolioId - customerType - customerId - requestId - requesterName - createdDate - title - consumerId - consumerSsn - type - status - constraints allOf: - $ref: '#/components/schemas/BaseReportAckWithPortfolioId' - type: object properties: constraints: $ref: '#/components/schemas/PayStatementReportConstraints' PayrollReportConstraints: required: - payrollData type: object properties: payrollData: $ref: '#/components/schemas/PayrollData' reportCustomFields: $ref: '#/components/schemas/ReportCustomFields' payStatementsFromDate: $ref: '#/components/schemas/PayStatementsFromDate' marketSegment: $ref: '#/components/schemas/MarketSegment' purpose: $ref: '#/components/schemas/PurposeCode' VOIEWithTXVerifyReportConstraints: required: - voieWithInterviewData type: object properties: accountIds: $ref: '#/components/schemas/ReportAccountIdsString' voieWithInterviewData: $ref: '#/components/schemas/VOIEWithInterviewData' reportCustomFields: $ref: '#/components/schemas/ReportCustomFields' fromDate: $ref: '#/components/schemas/UnixDate' incomeStreamConfidenceMinimum: $ref: '#/components/schemas/IncomeStreamConfidenceMinimum' ReportCreatedDate: type: integer description: 'A date in Unix epoch time (in seconds). See: [Handling Epoch Dates and Times](https://developer.mastercard.com/open-finance-us/documentation/errors/best-practices/). Note: If the report is retrieved on a day other than the day it was generated, on the header of the PDF version of the report there will be a "Retrieved Date" populated.' format: int64 example: 1607450357 BaseReportAck: description: Properties shared by all generated reports type: object properties: id: $ref: '#/components/schemas/ReportId' customerType: $ref: '#/components/schemas/CustomerType' customerId: $ref: '#/components/schemas/NumericCustomerId' requestId: $ref: '#/components/schemas/ReportRequestId' requesterName: $ref: '#/components/schemas/PartnerName' endUser: $ref: '#/components/schemas/ConsumerEndUser' createdDate: $ref: '#/components/schemas/ReportCreatedDate' title: $ref: '#/components/schemas/ReportTitle' consumerId: $ref: '#/components/schemas/ConsumerId' consumerSsn: $ref: '#/components/schemas/SocialSecurityNumberLastDigits' consumerDetails: $ref: '#/components/schemas/ConsumerDetails' disputeStatement: $ref: '#/components/schemas/DisputeStatement' type: $ref: '#/components/schemas/ReportType' status: $ref: '#/components/schemas/ReportStatus' constraints: anyOf: - $ref: '#/components/schemas/AnalyticsReportConstraintsOut' - $ref: '#/components/schemas/ForesightAnalyticsReportConstraints' - $ref: '#/components/schemas/CashFlowReportConstraintsOut' - $ref: '#/components/schemas/VOIEWithTXVerifyReportConstraintsOut' - $ref: '#/components/schemas/VOIEReportConstraints' - $ref: '#/components/schemas/StatementReportConstraints' - $ref: '#/components/schemas/TransactionsReportConstraintsOut' - $ref: '#/components/schemas/VOAReportConstraintsOut' - $ref: '#/components/schemas/VOAWithIncomeReportConstraintsOut' - $ref: '#/components/schemas/PrequalificationReportConstraintsOut' - $ref: '#/components/schemas/VOIReportConstraintsOut' - $ref: '#/components/schemas/PayrollReportConstraintsOut' - $ref: '#/components/schemas/VOETransactionsReportConstraintsOut' - $ref: '#/components/schemas/PayStatementReportConstraints' errors: description: In case errors occurred during the report generation type: array items: $ref: '#/components/schemas/ErrorMessage' MarketSegment: title: Market Segment type: string description: 'Use case for requesting the consumer''s data. Current supported enumerations are:
* `Auto`
* `Background`
* `Credit Card`
* `Employment`
* `Government`
* `Identity`
* `KYC`
* `Mortgage`
* `Personal`
* `Tenant`
If your usecase doesn''t match one of these please reach out to your technical point of contact.' example: Mortgage UnixDate: type: integer description: 'A date in Unix epoch time (in seconds). See: [Handling Epoch Dates and Times](https://developer.mastercard.com/open-finance-us/documentation/errors/best-practices/).' format: int64 example: 1607450357 CustomerId: type: string description: A customer ID. See Add Customer API for how to create a customer ID. example: '1005061234' City: type: string description: City example: Murray responses: BadRequestErrorResponse: description: The request was rejected content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: PermissiblePurposeCodeExample: $ref: '#/components/examples/PermissiblePurposeCodeExample' InvalidForesightReportRequestExample: $ref: '#/components/examples/InvalidForesightReportRequestExample' BothCraAndFtcPurposeTrueExample: $ref: '#/components/examples/BothCraAndFtcPurposeTrueExample' MissingFieldExample: $ref: '#/components/examples/MissingFieldExample' InvalidFieldExample: $ref: '#/components/examples/InvalidFieldExample' InvalidExperienceFieldExample: $ref: '#/components/examples/InvalidExperienceFieldExample' GenericBadRequestExample: $ref: '#/components/examples/GenericBadRequestExample' AccountTypeNotSupportedExample: $ref: '#/components/examples/AccountTypeNotSupportedExample' ResellerPartnerNotAuthorizedExample: $ref: '#/components/examples/ResellerPartnerNotAuthorizedExample' ResellerInvalidDateRangeExample: $ref: '#/components/examples/ResellerInvalidDateRangeExample' ResellerInvalidDateRangeLessThanZeroExample: $ref: '#/components/examples/ResellerInvalidDateRangeLessThanZeroExample' ResellerInvalidDateRangeGreaterThanEndDateExample: $ref: '#/components/examples/ResellerInvalidDateRangeGreaterThanEndDateExample' ResellerInvalidDateRangeGreaterThan31DaysExample: $ref: '#/components/examples/ResellerInvalidDateRangeGreaterThan31DaysExample' CustomerReportLimitExceedExample: $ref: '#/components/examples/CustomerReportLimitExceedExample' InvalidConsumerSSNExample: $ref: '#/components/examples/InvalidConsumerSSNExample' InvalidConsumerPhoneExample: $ref: '#/components/examples/InvalidConsumerPhoneExample' InvalidConsumerEmailExample: $ref: '#/components/examples/InvalidConsumerEmailExample' InvalidValue: $ref: '#/components/examples/InvalidValueExample' GenerateVOIEPaystubWithTXVerifyReportResponse: description: 'The report is being generated. When finished, a notification will be sent to the specified callback URL (Report Listener Service) and the report can be fetched using Get Report APIs. If you don''t use a callback URL, Get Report returns a minimal report with the following status: ''inProgress''. Repeat the call every 20 seconds until Get Report returns a different status.' content: application/json: schema: $ref: '#/components/schemas/VOIEPaystubWithTXVerifyReportAck' examples: GenerateVOIEPaystubWithTXVerifyReportResponseExample: $ref: '#/components/examples/GenerateVOIEPaystubWithTXVerifyReportResponseExample' GeneratePayStatementReportResponse: description: 'The report is being generated. When finished, a notification will be sent to the specified callback URL (Report Listener Service) and the report can be fetched using Get Report APIs. If you don''t use a callback URL, Get Report returns a minimal report with the following status: ''inProgress''. Repeat the call every 20 seconds until Get Report returns a different status.' content: application/json: schema: $ref: '#/components/schemas/PayStatementReportAck' examples: GeneratePayStatementReportResponseExample: $ref: '#/components/examples/GeneratePayStatementReportResponseExample' GenerateVOIEPaystubReportResponse: description: 'The report is being generated. When finished, a notification will be sent to the specified callback URL (Report Listener Service) and the report can be fetched using Get Report APIs. If you don''t use a callback URL, Get Report returns a minimal report with the following status: ''inProgress''. Repeat the call every 20 seconds until Get Report returns a different status.' content: application/json: schema: $ref: '#/components/schemas/VOIEPaystubReportAck' examples: GenerateVOIEPaystubReportResponseExample: $ref: '#/components/examples/GenerateVOIEPaystubReportResponseExample' UnauthorizedErrorResponse: description: The request lacks valid authentication credentials. Check "Finicity-App-Key" or "Finicity-App-Token". content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: ExpiredTokenExample: $ref: '#/components/examples/ExpiredTokenExample' MissingFinicityAppKeyExample: $ref: '#/components/examples/MissingFinicityAppKeyExample' MissingFinicityAppTokenExample: $ref: '#/components/examples/MissingFinicityAppTokenExample' InvalidFinicityAppTokenExample: $ref: '#/components/examples/InvalidFinicityAppTokenExample' ExpiredFinicityAppTokenExample: $ref: '#/components/examples/ExpiredFinicityAppTokenExample' BadCredentialsExample: $ref: '#/components/examples/BadCredentialsExample' text/plain: schema: type: string example: Invalid (Finicity-App-Key) ResourceNotFoundErrorResponse: description: The resource doesn't exist content: application/json: schema: $ref: '#/components/schemas/ErrorMessage' examples: ConsumerNotFoundExample: $ref: '#/components/examples/ConsumerNotFoundExample' NoAccountForInstitutionLoginIdExample: $ref: '#/components/examples/NoAccountForInstitutionLoginIdExample' CustomerNotFoundExample: $ref: '#/components/examples/CustomerNotFoundExample' NoConsumerForCustomerExample: $ref: '#/components/examples/NoConsumerForCustomerExample' ResourceNotFoundExample: $ref: '#/components/examples/ResourceNotFoundExample' NoRegisteredApplicationExample: $ref: '#/components/examples/NoRegisteredApplicationExample' ResellerNoDataForPartnerExample: $ref: '#/components/examples/ResellerNoDataForPartnerExample' ResellerNoReportForPartnerExample: $ref: '#/components/examples/ResellerNoReportForPartnerExample' SecurityFreezeErrorResponse: description: The active security freeze for this consumer exists. content: application/json: schema: $ref: '#/components/schemas/SecurityFreezeErrorMessage' examples: SecurityFreezeErrorExample: $ref: '#/components/examples/SecurityFreezeErrorExample' GenerateVOIReportResponse: description: 'The report is being generated. When finished, a notification will be sent to the specified callback URL (Report Listener Service) and the report can be fetched using Get Report APIs. If you don''t use a callback URL, Get Report returns a minimal report with the following status: ''inProgress''. Repeat the call every 20 seconds until Get Report returns a different status.' content: application/json: schema: $ref: '#/components/schemas/VOIReportAck' examples: GenerateVOIReportResponseExample: $ref: '#/components/examples/GenerateVOIReportResponseExample' GenerateVOEPayrollReportResponse: description: 'The report is being generated. When finished, a notification will be sent to the specified callback URL (Report Listener Service) and the report can be fetched using Get Report APIs. If you don''t use a callback URL, Get Report returns a minimal report with the following status: ''inProgress''. Repeat the call every 20 seconds until Get Report returns a different status.' content: application/json: schema: $ref: '#/components/schemas/PayrollReportAck' examples: GenerateVOEPayrollReportResponseExample: $ref: '#/components/examples/GenerateVOEPayrollReportResponseExample' RefreshVOIEPayrollReportResponse: description: 'The report is being generated. When finished, a notification will be sent to the specified callback URL (Report Listener Service) and the report can be fetched using Get Report APIs. If you don''t use a callback URL, Get Report returns a minimal report with the following status: ''inProgress''. Repeat the call every 20 seconds until Get Report returns a different status.' content: application/json: schema: $ref: '#/components/schemas/PayrollReportAck' examples: RefreshVOIEPayrollReportResponseExample: $ref: '#/components/examples/RefreshVOIEPayrollReportResponseExample' GenerateVOETransactionsReportResponse: description: 'The report is being generated. When finished, a notification will be sent to the specified callback URL (Report Listener Service) and the report can be fetched using Get Report APIs. If you don''t use a callback URL, Get Report returns a minimal report with the following status: ''inProgress''. Repeat the call every 20 seconds until Get Report returns a different status.' content: application/json: schema: $ref: '#/components/schemas/VOETransactionsReportAck' examples: GenerateVOETransactionsReportResponseExample: $ref: '#/components/examples/GenerateVOETransactionsReportResponseExample' requestBodies: GenerateVOIReportRequest: required: true content: application/json: schema: $ref: '#/components/schemas/VOIReportConstraints' examples: GenerateVOIReportRequestExample: $ref: '#/components/examples/GenerateVOIReportRequestExample' GenerateVOIEPaystubReportRequest: required: true content: application/json: schema: $ref: '#/components/schemas/VOIEReportConstraints' examples: GenerateVOIEPaystubReportRequestExample: $ref: '#/components/examples/GenerateVOIEPaystubReportRequestExample' GeneratePayStatementReportRequest: required: true content: application/json: schema: $ref: '#/components/schemas/PayStatementReportConstraints' examples: GeneratePayStatementReportRequestExample: $ref: '#/components/examples/GeneratePayStatementReportRequestExample' GeneratePayrollReportRequest: required: true content: application/json: schema: $ref: '#/components/schemas/PayrollReportConstraints' examples: GeneratePayrollReportRequestExample: $ref: '#/components/examples/GeneratePayrollReportRequestExample' GenerateVOETransactionsReportRequest: required: true content: application/json: schema: $ref: '#/components/schemas/VOETransactionsReportConstraints' examples: GenerateVOETransactionsReportRequestExample: $ref: '#/components/examples/GenerateVOETransactionsReportRequestExample' GenerateVOIEPaystubWithTXVerifyReportRequest: required: true content: application/json: schema: $ref: '#/components/schemas/VOIEWithTXVerifyReportConstraints' examples: GenerateVOIEPaystubWithTXVerifyReportRequestExample: $ref: '#/components/examples/GenerateVOIEPaystubWithTXVerifyReportRequestExample' parameters: ReportCallbackUrlParameter: name: callbackUrl in: query required: false description: A Report Listener URL to receive notifications. The webhook must respond to the Finicity API with a 2xx HTTP status code. schema: type: string example: https://finicity-test/webhook CustomerIdParameter: description: A customer ID name: customerId in: path required: true schema: $ref: '#/components/schemas/CustomerId' example: '1005061234' securitySchemes: FinicityAppKey: name: Finicity-App-Key type: apiKey in: header description: The "Finicity-App-Key" from the developer dashboard FinicityAppToken: name: Finicity-App-Token type: apiKey in: header description: A token returned by the `/authentication` API