Details

openapi: 3.0.0 info: version: "0.0" title: Documents description: documents listing retrieval disclosures and settings servers: - url: 'https://{API_ENVIRONMENT}/a/consumer/api/v0' variables: API_ENVIRONMENT: default: digital.garden-fi.com description: FI specific hostname tags: - name: Documents description: Document retrieval and listing. - name: Settings description: Document delivery and notification settings. - name: Institution description: Institution Settings for Documents. - name: Disclosure description: Document terms of use. paths: "/users/{userId}/documents/all": get: tags: - Documents description: > List metadata about documents for all of a user's accounts. If the institution uses perAccount enrollment, the listing will only contain docs for enrolled accounts. Currently the route only handles a max of 20 accounts per request. More than 20 accounts will cause the endpoint to 400. security: - OpenID_Connect: - 'https://api.banno.com/consumer/auth/documents.readwrite' - 'https://api.banno.com/consumer/auth/documents.readonly' parameters: - in: path name: userId description: id of the user required: true schema: type: string format: uuid - in: query name: startDate description: Inclusive date to list documents from. Uses yyyy-mm-dd format. required: true schema: type: string format: date example: "2024-01-01" - in: query name: endDate description: Inclusive date to list documents to. Defaults to now. Uses yyyy-mm-dd format. required: false schema: type: string format: date example: "2024-01-01" - in: query name: accountId description: > Filter used to only return a subset of account documents. required: false schema: type: array items: type: string format: uuid responses: "200": description: > Successful Request - Returns a documents field with an empty list if the query was well formed and no documents were found. content: application/json: schema: $ref: "#/components/schemas/userDocumentListingResponse" "400": description: Bad Request - e.g. Invalid User Id content: application/json: schema: $ref: "#/components/schemas/errorResponse" "403": description: User abilities disabled or not found. content: application/json: schema: $ref: "#/components/schemas/errorResponse" "404": description: Not Found - e.g. User not found. content: application/json: schema: $ref: "#/components/schemas/errorResponse" "/users/{userId}/documents/accounts/{accountId}": get: tags: - Documents description: List metadata about documents. security: - OpenID_Connect: - 'https://api.banno.com/consumer/auth/documents.readwrite' - 'https://api.banno.com/consumer/auth/documents.readonly' parameters: - in: path name: userId description: Id of the user. required: true schema: type: string format: uuid - in: path name: accountId description: Id of the account. required: true schema: type: string format: uuid - in: query name: startDate description: Inclusive date to list documents from. Uses yyyy-mm-dd format. required: true schema: type: string format: date example: "2024-01-01" - in: query name: endDate description: Inclusive date to list documents to. Defaults to now. Uses yyyy-mm-dd format. required: false schema: type: string format: date example: "2024-01-01" responses: "200": description: > Successful Request - Contains a documents field with an empty list instead of a 404 if the query was well formed and no documents were found. content: application/json: schema: $ref: "#/components/schemas/documentListingResponse" "400": description: Bad Request - e.g. Invalid Account Id. content: application/json: schema: $ref: "#/components/schemas/errorResponse" "403": description: User abilities disabled or not found. content: application/json: schema: $ref: "#/components/schemas/errorResponse" "404": description: Not Found - e.g. Account not found. content: application/json: schema: $ref: "#/components/schemas/errorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/errorResponse" "/users/{userId}/documents/{documentId}": get: tags: - Documents description: Download a pdf version of a document. Also, This comes back as a chunked response. security: - OpenID_Connect: - 'https://api.banno.com/consumer/auth/documents.readwrite' - 'https://api.banno.com/consumer/auth/documents.readonly' parameters: - in: path name: userId description: Id of the user. required: true schema: type: string format: uuid - in: path name: documentId description: Unique identifier for the document. required: true schema: type: string - in: query name: filename description: When present, adds a content-disposition header with the provided filename. required: false schema: type: string responses: "200": description: Successful Request - A pdf document headers: Content-Disposition: schema: description: attachment type: string content: application/pdf: {} "400": description: Bad Request - e.g. Invalid Account Id content: application/json: schema: $ref: "#/components/schemas/errorResponse" "403": description: User abilities disabled or not found. content: application/json: schema: $ref: "#/components/schemas/errorResponse" "404": description: Not Found - e.g. Document/user not found content: application/json: schema: $ref: "#/components/schemas/errorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/errorResponse" "/users/{userId}/documents/settings/per-account": get: tags: - Settings description: List document delivery and notification settings for a user - used when enrollmentFlow is perAccount. security: - OpenID_Connect: - 'https://api.banno.com/consumer/auth/documents.readwrite' - 'https://api.banno.com/consumer/auth/documents.readonly' parameters: - in: path name: userId description: Id of the user. required: true schema: type: string format: uuid responses: "200": description: Successful Request - A list of document delivery and notification settings a user. content: application/json: schema: $ref: "#/components/schemas/documentSettingsPerAccountWithPrompt" "400": description: Bad Request - e.g. Invalid User Id content: application/json: schema: $ref: "#/components/schemas/errorResponse" "403": description: User abilities disabled or not found. content: application/json: schema: $ref: "#/components/schemas/errorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/errorResponse" put: tags: - Settings description: Update document delivery and notification settings for a list of accounts - used when enrollmentFlow is perAccount. security: - OpenID_Connect: - 'https://api.banno.com/consumer/auth/documents.readwrite' parameters: - in: path name: userId description: Id of the user. required: true schema: type: string format: uuid requestBody: description: The DocumentSettings to update. Only send accounts on which enrollment changes have been made. required: true content: application/json: schema: $ref: "#/components/schemas/documentSettingsPerAccount" responses: "200": description: Successful Request - The changes were submitted successfully. "400": description: Bad Request - e.g. Invalid User Id content: application/json: schema: $ref: "#/components/schemas/errorResponse" "403": description: User abilities disabled or not found. content: application/json: schema: $ref: "#/components/schemas/errorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/errorResponse" "/users/{userId}/documents/settings/all-accounts": get: tags: - Settings description: Get document delivery and notification settings for a user - used when enrollmentFlow is allOrNone. security: - OpenID_Connect: - 'https://api.banno.com/consumer/auth/documents.readwrite' - 'https://api.banno.com/consumer/auth/documents.readonly' parameters: - in: path name: userId description: Id of the user. required: true schema: type: string format: uuid responses: "200": description: Successful Request - Document delivery and notification settings for a user. content: application/json: schema: $ref: "#/components/schemas/documentSettingsAllAccounts" "400": description: Bad Request - e.g. Invalid User Id content: application/json: schema: $ref: "#/components/schemas/errorResponse" "403": description: user abilities disabled or not found. content: application/json: schema: $ref: "#/components/schemas/errorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/errorResponse" put: tags: - Settings description: Update document delivery and notification settings for a user - used when enrollmentFlow is allOrNone. security: - OpenID_Connect: - 'https://api.banno.com/consumer/auth/documents.readwrite' parameters: - in: path name: userId description: Id of the user. required: true schema: type: string format: uuid requestBody: description: The DocumentSettings to update. required: true content: application/json: schema: $ref: "#/components/schemas/documentSettingsAllAccounts" responses: "200": description: Successful Request - The changes were submitted successfully. "400": description: Bad Request - e.g. Invalid User Id content: application/json: schema: $ref: "#/components/schemas/errorResponse" "403": description: User abilities disabled or not found. content: application/json: schema: $ref: "#/components/schemas/errorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/errorResponse" "/users/{userId}/documents/settings/fi-enroll": put: tags: - Settings description: Confirm or decline FI enrollment when `fiEnrollmentPrompt` from per-account settings is true. security: - OpenID_Connect: - 'https://api.banno.com/consumer/auth/documents.readwrite' parameters: - in: path name: userId description: Id of the user. required: true schema: type: string format: uuid requestBody: description: User acceptance or rejection of automatic FI enrollment for documents. required: true content: application/json: schema: $ref: "#/components/schemas/fiEnrollmentConfirmation" responses: "204": description: Successful Request - The changes were submitted successfully. "400": description: Bad Request - e.g. Invalid User Id content: application/json: schema: $ref: "#/components/schemas/errorResponse" "403": description: User abilities disabled or not found. content: application/json: schema: $ref: "#/components/schemas/errorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/errorResponse" "/users/{userId}/documents/settings/institution": get: tags: - Institution description: Get the Institution's Documents Settings (can be overridden per user). security: - OpenID_Connect: - 'https://api.banno.com/consumer/auth/documents.readwrite' - 'https://api.banno.com/consumer/auth/documents.readonly' parameters: - in: path name: userId description: Id of the user, required: true schema: type: string format: uuid responses: "200": description: Successful Request - A Settings Response. content: application/json: schema: $ref: "#/components/schemas/settingsResponse" "400": description: Bad Request - e.g. Invalid User Id. content: application/json: schema: $ref: "#/components/schemas/errorResponse" "404": description: Not Found - e.g. User not found. content: application/json: schema: $ref: "#/components/schemas/errorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/errorResponse" "/users/{userId}/documents/disclosures/current": get: tags: - Disclosure description: Retrieve current disclosure for an institution. security: - OpenID_Connect: - 'https://api.banno.com/consumer/auth/documents.readwrite' - 'https://api.banno.com/consumer/auth/documents.readonly' parameters: - in: path name: userId description: Id of the user. required: true schema: type: string format: uuid responses: "200": description: Successful Request - Returns a disclosure. content: application/json: schema: $ref: "#/components/schemas/disclosureResponse" "400": description: Invalid userId, institutionId, or the query is not wellformed. content: application/json: schema: $ref: "#/components/schemas/errorResponse" "403": description: User abilities disabled or not found. content: application/json: schema: $ref: "#/components/schemas/errorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/errorResponse" "/users/{userId}/documents/disclosures/acceptance": get: tags: - Disclosure description: Retrieve user disclosure acceptance for an institution. security: - OpenID_Connect: - 'https://api.banno.com/consumer/auth/documents.readwrite' - 'https://api.banno.com/consumer/auth/documents.readonly' parameters: - in: path name: userId description: Id of the user. required: true schema: type: string format: uuid responses: "200": description: Successful Request - An optional userAcceptance if the query was found. content: application/json: schema: $ref: "#/components/schemas/acceptanceResponse" "400": description: Invalid userId, or the query is not wellformed. content: application/json: schema: $ref: "#/components/schemas/errorResponse" "403": description: User abilities disabled or not found. content: application/json: schema: $ref: "#/components/schemas/errorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/errorResponse" put: tags: - Disclosure description: Update/create user disclosure acceptance for an institution. security: - OpenID_Connect: - 'https://api.banno.com/consumer/auth/documents.readwrite' parameters: - in: path name: userId description: Id of the user required: true schema: type: string format: uuid requestBody: description: The disclosureId of the disclosure a user accepted. required: true content: application/json: schema: $ref: "#/components/schemas/acceptanceParams" responses: "200": description: | Successful Request - Contains an updated userAcceptance. content: application/json: schema: $ref: "#/components/schemas/acceptanceResponse" "400": description: Invalid userId, or the query is not wellformed. content: application/json: schema: $ref: "#/components/schemas/errorResponse" "500": description: Internal Server Error content: application/json: schema: $ref: "#/components/schemas/errorResponse" "/users/{userId}/documents/disclosures/{disclosureId}": get: tags: - Disclosure description: Returns a disclosure for a disclosureId. security: - OpenID_Connect: - 'https://api.banno.com/consumer/auth/documents.readwrite' - 'https://api.banno.com/consumer/auth/documents.readonly' parameters: - name: userId in: path description: id of the user required: true schema: type: string format: Uuid - name: disclosureId in: path description: id of the disclosures required: true schema: type: string format: Uuid responses: "200": description: Successful Request - Returns a disclosure. content: application/json: schema: $ref: "#/components/schemas/disclosure" "500": description: Internal Server Error. components: securitySchemes: OpenID_Connect: type: openIdConnect description: OpenID Connect - Discovery endpoint will be institution specific openIdConnectUrl: >- https://digital.garden-fi.com/a/consumer/api/v0/oidc/.well-known/openid-configuration schemas: documentType: type: string enum: - statement - notice - tax documentInfoWithAccountIds: type: object required: - documentId - accountIds - documentType - documentTitle - documentFilename - date properties: documentId: type: string format: uuid accountIds: type: array items: type: string format: uuid description: AccountId's that are linked to a documentId. documentType: $ref: "#/components/schemas/documentType" documentTitle: type: string description: type: string date: type: string format: date documentFilename: type: string documentInfo: type: object required: - documentId - documentType - documentTitle - documentFilename - date properties: documentId: type: string documentType: $ref: "#/components/schemas/documentType" documentTitle: type: string description: type: string date: type: string format: date documentFilename: type: string documentListingResponse: type: object required: - documents properties: documents: type: array items: $ref: "#/components/schemas/documentInfo" userDocumentListingResponse: type: object required: - documents properties: documents: type: array items: $ref: "#/components/schemas/documentInfoWithAccountIds" documentSettingsPerAccount: type: object required: - settings properties: settings: type: array items: allOf: - type: object required: - accountId properties: accountId: type: string format: uuid - $ref: "#/components/schemas/documentSettings" documentSettingsPerAccountWithPrompt: allOf: - type: object properties: fiEnrollmentPrompt: type: boolean description: > If true, the user is pre-enrolled by the FI, but needs to acknowledge it. This is intended to be a blocking choice. This field is only present for ESI, otherwise it is null. - $ref: "#/components/schemas/documentSettingsPerAccount" documentSettingsAllAccounts: type: object required: - settings properties: settings: $ref: "#/components/schemas/documentSettings" documentSettings: type: object description: > The required fields differ if this object is used for a PUT or GET * PUT: notifications is required if deliveryMethod is not paper * GET: notifications may not exist due to external provider API calls outside of our control required: - deliveryMethod properties: deliveryMethod: $ref: "#/components/schemas/deliveryMethod" notifications: type: object description: The notificationMethod and at least its counterpart (unless notificationMethod is noNotify) are required required: - notificationMethod properties: notificationMethod: $ref: "#/components/schemas/notificationMethod" email: type: string phone: type: string restrictEnroll: type: boolean description: flag to allow clients to know if the account can be enrolled in documents. restrictUnenroll: type: boolean description: flag to allow clients to know if the account can be unenrolled in documents. settingsResponse: type: object required: - settings properties: settings: $ref: "#/components/schemas/institutionSettings" institutionSettings: type: object required: - supportedNotificationMethods - documentTypes - documentStartDate - documentsNativeEnrollmentSSO - documentsTitle - maximumConcurrentAccounts properties: deliverySettings: type: object description: Optional object that contains fields pertaining to the eDocuments enrollment flow. If not present, the user is not allowed to change their delivery settings and can go straight to viewing documents without being enrolled. required: - supportedDeliveryMethods - enrollmentFlow - enrollmentMessage properties: supportedDeliveryMethods: type: array description: >- A non-empty list of the possible methods the user is allowed to choose for their documents delivery. * paper: if present, user is allowed to unenroll from edocs if they are currently enrolled * electronic: if present, user is allowed to enroll in edocs * bothPaperAndElectronic: if present, user is allowed to enroll in edocs while also continuing to receive paper documents items: $ref: "#/components/schemas/deliveryMethod" enrollmentFlow: type: string enum: - perAccount - allOrNone description: >- The type of enrollment flow to use (if enrollment is enabled) * perAccount: user can choose which accounts to enroll - clients should use the /users/{userId}/documents/settings/per-account endpoint * allOrNone: enrollment means enrolling all accounts or none of them - clients should use the /users/{userId}/documents/settings/all-accounts endpoint enrollmentMessage: type: string description: Message displayed to users when enrolling in documents example: Go paperless with your account's statements and documents. You'll be notified when new documents are available. paperDeliveryFee: type: string description: An optional fee for receiving paper documents example: "4.99" enrollmentPrompt: type: boolean deprecated: true description: Returned for technical reasons, but not intended to be used supportedNotificationMethods: type: array description: >- Methods the user can choose for receiving document notifications. If empty, notifications are not supported, and no selection should be shown. * email: if present, user can choose to receive document notifications via email * phone: if present, user can choose to receive document notifications via phone * noNotify: if present, user can choose to opt out of receiving document notifications items: $ref: "#/components/schemas/notificationMethod" documentTypes: type: array items: $ref: "#/components/schemas/documentType" documentStartDate: type: string format: date documentsNativeEnrollmentSSO: type: boolean description: If this value is true, then the institution uses an SSO for documents with native eStatement enrollment. documentsTitle: type: string description: Title displayed anywhere "Documents" are referred to. Defaults to 'Documents'. Clients should display as-is, without changing the casing. example: eStatements maximumConcurrentAccounts: type: integer example: 20 description: If the user has more documents-enabled accounts than `maximumConcurrentAccounts`, then documents should not be fetched for all accounts at once. In other words, the GET /documents/all endpoint should only be called with `accountId` query params. displayEnrollmentPrompt: type: string enum: - Show - Hide description: Show if client should display a popup nudging users to enroll in E-statements. deliveryMethod: type: string enum: - paper - electronic - bothPaperAndElectronic notificationMethod: type: string enum: - email - phone - noNotify disclosure: type: object required: - disclosureId - terms - createdDate - createdBy properties: disclosureId: type: string format: uuid terms: type: string createdDate: type: string format: date-time createdBy: type: string format: uuid description: The institution user that created the terms. disclosureResponse: type: object properties: disclosure: $ref: "#/components/schemas/disclosure" disclosureAcceptance: type: object required: - disclosureId - date properties: disclosureId: type: string format: uuid date: type: string format: date-time acceptanceResponse: type: object properties: disclosureAcceptance: $ref: "#/components/schemas/disclosureAcceptance" acceptanceParams: type: object required: - disclosureId properties: disclosureId: type: string format: uuid fiEnrollmentConfirmation: type: object description: Confirmation or decline of FI documents enrollment. required: - fiEnrollment properties: fiEnrollment: type: string enum: - Confirm - Decline errorResponse: type: object required: - error properties: error: type: string