openapi: 3.1.0
info:
    title: Nova Credit Cash Atlas V2 API
    description: "This is a sample Nova Credit server for the Cash Atlas V2 API. You can find out more about Nova Credit's API through our [API docs](https://docs.novacredit.com/) and [Quickstart Guide](/cash-atlas-quickstart). \n\n\n Quick Notes Before Getting Started: \n\n\n 1. Select the appropriate server you would like to use. \n\n 2. Enter your credentials. When passing in an access token, be sure to [base64 encode](https://www.base64encode.org/) the token. \n\n 3. Be sure to select the appropriate user environment for each endpoint."
    termsOfService: https://novacredit.com/terms/
    version: 2.0.6

servers:
    - url: https://api.novacredit.com/connect
      description: 'Production server (uses production data)'
    - url: https://api.sandbox.novacredit.com/connect
      description: 'Sandbox server (uses sandbox data)'

tags:
    - name: accesstoken
      description: 'Generate an access token.'
    - name: cash-atlas
      description: 'Retrieve a Cash Atlas V2 report.'
    - name: bank-accounts
      description: 'Retrieve ACH details for a bank account.'
    - name: status
      description: 'Retrieve the status of a report.'
    - name: invite
      description: 'Send email to applicants to invite them to complete the NovaConnect journey.'
    - name: inviteLink
      description: 'Generate a link to invite an applicant to complete the NovaConnect journey.'
    - name: consumers
      description: 'Create, update, and retrieve consumers.'
    - name: initialize
      description: 'Initialize a Nova Credit session and return a JWT.'
    - name: jwkset
      description: 'Retrieve the JSON Web Key Set (JWKS) for payload encryption and signature verification.'

paths:
    /accesstoken:
        get:
            tags:
                - accesstoken
            description: 'Fetch an access token using your credentials. You will need to retrieve a new access token each time you intend to retrieve a Cash Atlas report. Access tokens are time-scoped to 5 minutes to prevent malicious usage should someone obtain one. If you do not retrieve the Cash Atlas report before the access token expires, you will need to request a new access token.'
            operationId: getAccessToken
            security:
                - BasicAuth: []
            parameters:
                - $ref: '#/components/parameters/environmentHeader'
            responses:
                200:
                    description: 'Successful response'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AccessTokenSuccess'
                400:
                    description: 'Bad Request'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BadRequestError'
                            examples:
                                malformedHeaders:
                                    $ref: '#/components/examples/MalformedHeaders'
                401:
                    description: 'Expired Credentials'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ExpiredKeyError'
                403:
                    description: 'Forbidden'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ForbiddenError'
                500:
                    description: 'Internal Error'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InternalError'

    /cash-atlas/v2/json:
        get:
            tags:
                - cash-atlas
            description: "The Cash Atlas V2 report includes an applicant's bank transaction data, account details, computed attributes, and cash flow scores. Data is sourced from bank aggregator connections made through NovaConnect."
            operationId: getCashAtlasJSONv2
            security:
                - BearerAuth: []
            parameters:
                - $ref: '#/components/parameters/environmentHeader'
                - $ref: '#/components/parameters/publicTokenHeader'
                - $ref: '#/components/parameters/externalIdHeader'
                - $ref: '#/components/parameters/publicIdHeader'
            responses:
                200:
                    description: 'Successfully retrieved Cash Atlas V2 JSON report'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CashAtlasJSONv2'
                            example:
                                meta:
                                    public_token: 'e3f60d3a-8a22-4940-9d1e-50f4f9878503'
                                    user_args: '22bbd586-12b9-4876-8ec0-d210d081f4a1|email@test.com'
                                    created_at: '2024-01-13T11:07:46.51Z'
                                    api_version: '2.0.0'
                                    nova_report_revision: '1'
                                    nova_report_revision_created_at: '2024-01-13T11:07:46.51Z'
                                    external_id: 'd167c6bb-225c-461c-be63-f0bc3a1f62ea'
                                    status: 'SUCCESS'
                                    consumer_id: 'b281e335-9d19-4aa7-b559-e74d08a05cf4'
                                    consumer_external_id: '472cbdc9-cf31-4117-a095-e27e2db054e5'
                                product:
                                    name: 'Pascoe Gardens Sandbox'
                                    product_id: 'c3a37c41-7c62-11e7-8141-19157d9a48c7'
                                    inquiry_type: 'TENANT'
                                sources:
                                    - source_id: 'USA_FIN'
                                      source_type: 'BANK_TRANSACTION'
                                      status: 'SUCCESS'
                                    - source_id: 'CONSUMER_INPUT'
                                      source_type: 'MANUAL'
                                      status: 'SUCCESS'
                                identities:
                                    - source_id: 'CONSUMER_INPUT'
                                      first_name: 'Raymond'
                                      last_name: 'Marshal'
                                      full_name: 'Raymond Marshal'
                                      emails:
                                          - 'raymond@email.com'
                                account_details:
                                    - source_id: 'USA_FIN'
                                      account_id: '36139831-0a91-4d1f-bc3e-edc908a978c6'
                                      months_available: 6
                                      owner_full_name: 'John Doe'
                                      institution_name: 'CHASE'
                                      account_name: 'PERSONAL CHECKING ACCOUNT'
                                      account_type: 'CASH_EQUIVALENT'
                                      account_subtype: 'CHECKING'
                                      date_opened: '2015-05-01'
                                      truncated_account_number: '1234'
                                      responsibility: 'INDIVIDUAL'
                                      last_statement_end_date: '2015-05-30'
                                      addresses:
                                          - address_id: '80421b7e-7918-4963-b5fb-85055c2994b7'
                                            address: '225 Valencia St.'
                                            street: 'Valencia St.'
                                            city: 'San Francisco'
                                            zipcode: '94103'
                                            state: 'CA'
                                      current_balance: 45971.23
                                attributes:
                                    - name: 'EXPENSES_COUNT_3_MONTH_AVG'
                                      description: 'Average count of expenses over the last 3 months'
                                      node: 'EXPENSE'
                                      source_ids:
                                          - 'USA_FIN'
                                      adverse_action_code: '76'
                                      value: 10
                                    - name: 'ASSETS_CASH_EQUIVALENT_BALANCE'
                                      description: 'Current cash equivalent balance on assets'
                                      node: 'ASSET'
                                      source_ids:
                                          - 'USA_FIN'
                                      adverse_action_code: '21'
                                      value: 3200
                                scores:
                                    - source_ids:
                                          - 'USA_FIN'
                                      score_type: 'NOVA_SCORE_CASH_FLOW'
                                      score_version: 'v1.0'
                                      value: 600
                                      adverse_action_codes:
                                          - code: '21'
                                            description: 'Cash equivalent account balance is too low'
                                    - source_ids:
                                          - 'USA_FIN'
                                      score_type: 'NOVA_SCORE_CASH_FLOW'
                                      score_version: 'v2.0'
                                      value: 650
                                      adverse_action_codes:
                                          - code: '32'
                                            description: 'Amount of deposits is too low'
                                consumer_data_properties:
                                    - field_name: TOTAL_TRANSACTION_COUNT
                                      value: 142
                                    - field_name: TOTAL_HISTORY_LENGTH_DAYS
                                      value: 365
                                    - field_name: LOW_ACCOUNT_ACTIVITY_INDICATOR
                                      value: false
                                    - field_name: LIMITED_DATA_AVAILABLE_INDICATOR
                                      value: false
                400:
                    description: 'Bad Request'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BadRequestError'
                            examples:
                                malformedHeaders:
                                    $ref: '#/components/examples/MalformedHeaders'
                401:
                    description: 'Expired Credentials'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ExpiredKeyError'
                403:
                    description: 'Forbidden'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ForbiddenError'
                404:
                    description: 'Not Found'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InvalidTokenError'
                            examples:
                                invalidToken:
                                    $ref: '#/components/examples/InvalidToken'
                                invalidExternalId:
                                    $ref: '#/components/examples/InvalidExternalId'
                500:
                    description: 'Internal Error'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InternalError'

    /cash-atlas/v2/files:
        get:
            tags:
                - cash-atlas
            description: 'Retrieve a list of files associated with an application. This list is available even if there is no report yet.'
            operationId: getCashAtlasFilesv2
            security:
                - BearerAuth: []
            parameters:
                - $ref: '#/components/parameters/environmentHeader'
                - $ref: '#/components/parameters/publicTokenHeader'
                - $ref: '#/components/parameters/externalIdHeader'
                - $ref: '#/components/parameters/publicIdHeader'
            responses:
                200:
                    description: 'Successfully retrieved list of files'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CashAtlasFileList'
                400:
                    description: 'Bad Request'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BadRequestError'
                            examples:
                                malformedHeaders:
                                    $ref: '#/components/examples/MalformedHeaders'
                401:
                    description: 'Expired credentials'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ExpiredKeyError'
                403:
                    description: 'Forbidden'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ForbiddenError'
                404:
                    description: 'Not Found'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InvalidTokenError'
                            examples:
                                invalidToken:
                                    $ref: '#/components/examples/InvalidToken'
                                invalidExternalId:
                                    $ref: '#/components/examples/InvalidExternalId'
                500:
                    description: 'Internal Error'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InternalError'

    /cash-atlas/v2/files/{publicToken}/{filename}:
        get:
            tags:
                - cash-atlas
            description: "Retrieve a specific file associated with an applicant's Cash Atlas report."
            operationId: getCashAtlasFilev2
            security:
                - BearerAuth: []
            parameters:
                - $ref: '#/components/parameters/environmentHeader'
                - $ref: '#/components/parameters/publicTokenHeader'
                - $ref: '#/components/parameters/externalIdHeader'
                - $ref: '#/components/parameters/publicIdHeader'
                - name: publicToken
                  in: path
                  required: true
                  description: 'The public token of the application.'
                  schema:
                      type: string
                      format: uuid
                      minLength: 36
                      maxLength: 36
                      example: 'e3f60d3a-8a22-4940-9d1e-50f4f9878503'
                - name: filename
                  in: path
                  required: true
                  description: 'The filename of the file to retrieve.'
                  schema:
                      type: string
                      minLength: 1
                      maxLength: 64
                      example: '162539c6-7052-49c6-b6cd-0b4c113cb5cc.pdf'
            responses:
                200:
                    description: 'Successfully retrieved file. Body may be empty if the file is not found.'
                    content:
                        application/octet-stream:
                            schema:
                                type: string
                                format: binary
                400:
                    description: 'Bad Request'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BadRequestError'
                            examples:
                                malformedHeaders:
                                    $ref: '#/components/examples/MalformedHeaders'
                401:
                    description: 'Expired Credentials'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ExpiredKeyError'
                403:
                    description: 'Forbidden'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ForbiddenError'
                404:
                    description: 'Not Found'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InvalidTokenError'
                            examples:
                                invalidToken:
                                    $ref: '#/components/examples/InvalidToken'
                                invalidExternalId:
                                    $ref: '#/components/examples/InvalidExternalId'
                500:
                    description: 'Internal Server Error'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InternalError'

    /status:
        get:
            tags:
                - status
            description: 'Retrieve the status of a report. The status returned can be a non-terminal status such as PENDING, or a final outcome status such as SUCCESS or ERROR.'
            operationId: getCashAtlasStatusv2
            security:
                - BearerAuth: []
            parameters:
                - $ref: '#/components/parameters/environmentHeader'
                - $ref: '#/components/parameters/publicTokenHeader'
                - $ref: '#/components/parameters/externalIdHeader'
                - $ref: '#/components/parameters/publicIdHeader'
            responses:
                200:
                    description: 'Successfully retrieved Cash Atlas status'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CashAtlasStatusv2'
                400:
                    description: 'Bad Request'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BadRequestError'
                            examples:
                                malformedHeaders:
                                    $ref: '#/components/examples/MalformedHeaders'
                401:
                    description: 'Expired Credentials'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ExpiredKeyError'
                403:
                    description: 'Forbidden'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ForbiddenError'
                404:
                    description: 'Not Found'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InvalidTokenError'
                            examples:
                                invalidToken:
                                    $ref: '#/components/examples/InvalidToken'
                                invalidExternalId:
                                    $ref: '#/components/examples/InvalidExternalId'
                500:
                    description: 'Internal Error'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InternalError'

    /bank-accounts/{bankAccountId}/ach-details:
        get:
            tags:
                - bank-accounts
            description: 'Retrieve the full routing number and account number for a selected bank account after a consumer has successfully connected a bank account and a report has been generated. The initial call must occur before the 14-day data retention window has passed. After calling this endpoint once for a given account, it can be continuously called beyond the 14-day window until access is revoked or expired. Must be enabled by a Nova Credit Representative.'
            operationId: getAchDetails
            security:
                - BearerAuth: []
            parameters:
                - $ref: '#/components/parameters/environmentHeader'
                - name: bankAccountId
                  in: path
                  required: true
                  description: 'The unique identifier for the bank account. Obtained from the `account_id` field in the `account_details` node of the Cash Atlas report.'
                  schema:
                      type: string
                      format: uuid
                      minLength: 36
                      maxLength: 36
                      example: '36139831-0a91-4d1f-bc3e-edc908a978c6'
                - $ref: '#/components/parameters/publicTokenHeader'
                - $ref: '#/components/parameters/externalIdHeader'
                - $ref: '#/components/parameters/publicIdHeader'
            responses:
                200:
                    description: 'Successfully retrieved ACH details'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AchDetails'
                            example:
                                fullAccountNumber: '123456789012'
                                routingNumber: '123456789'
                400:
                    description: 'Bad Request'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BadRequestError'
                            examples:
                                malformedHeaders:
                                    $ref: '#/components/examples/MalformedHeaders'
                                notFound:
                                    value:
                                        error: 'NOT_FOUND'
                                        terminated: 'true'
                                consentNotProvided:
                                    value:
                                        error: 'CONSENT_NOT_PROVIDED'
                                        terminated: 'true'
                                accountSourceNotSupported:
                                    value:
                                        error: 'ACCOUNT_SOURCE_NOT_SUPPORTED'
                                        terminated: 'true'
                                supplierBadRequest:
                                    value:
                                        error: 'SUPPLIER_BAD_REQUEST'
                                        terminated: 'true'
                401:
                    description: 'Expired Credentials'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ExpiredKeyError'
                403:
                    description: 'Forbidden'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ForbiddenError'
                404:
                    description: 'Not Found'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InvalidTokenError'
                            examples:
                                invalidToken:
                                    $ref: '#/components/examples/InvalidToken'
                                invalidExternalId:
                                    $ref: '#/components/examples/InvalidExternalId'
                500:
                    description: 'Internal Error'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InternalError'

    /invite:
        post:
            tags:
                - invite
            operationId: invite
            security:
                - BasicAuth: []
            description: 'Send an email to an applicant to invite them to complete the NovaConnect journey.'
            parameters:
                - $ref: '#/components/parameters/environmentHeader'
                - $ref: '#/components/parameters/publicIdHeader'
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/InviteBody'
                        examples:
                            piiOption:
                                summary: 'PII Option'
                                value:
                                    emailTemplate: 'INVITE_CFUW'
                                    applicantFirstName: 'Raymond'
                                    applicantLastName: 'Marshal'
                                    applicantEmail: 'raymond@email.com'
                                    productId: '3c2da600-17ee-11e8-8a0e-5158039db37e'
                                    externalId: '3f59e253-01a6-40e8-be40-d3a500d03e48'
                                    userArgs: 'custom_id:3c2da600'
                            consumerOption:
                                summary: 'Consumer Option'
                                value:
                                    emailTemplate: 'INVITE_CFUW'
                                    productId: '3c2da600-17ee-11e8-8a0e-5158039db37e'
                                    consumerId: '987fcdeb-51a2-43d7-8f9e-123456789abc'
                required: true
            responses:
                200:
                    description: 'Successful - invite has been received and sent.'
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    applicationId:
                                        type: string
                                        format: uuid
                                        minLength: 36
                                        maxLength: 36
                                        example: '342abb30-04d4-482b-9860-6d5d1b40b681'
                                    visitId:
                                        type: string
                                        format: uuid
                                        minLength: 36
                                        maxLength: 36
                                        example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
                400:
                    description: 'Bad Request'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InviteBadRequestError'
                401:
                    description: 'Expired credentials'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ExpiredKeyError'
                403:
                    description: 'Forbidden'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InviteForbiddenError'
                500:
                    description: 'Internal Error'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InternalError'
            x-codegen-request-body-name: body

    /invite-link:
        post:
            tags:
                - inviteLink
            operationId: inviteLink
            security:
                - BasicAuth: []
            description: 'Generate a link to invite an applicant to complete the NovaConnect journey.'
            parameters:
                - $ref: '#/components/parameters/environmentHeader'
                - $ref: '#/components/parameters/publicIdHeader'
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/InviteBody'
                        examples:
                            piiOption:
                                summary: 'PII Option'
                                value:
                                    emailTemplate: 'INVITE_CFUW'
                                    applicantFirstName: 'Raymond'
                                    applicantLastName: 'Marshal'
                                    applicantEmail: 'raymond@email.com'
                                    productId: '3c2da600-17ee-11e8-8a0e-5158039db37e'
                                    externalId: '3f59e253-01a6-40e8-be40-d3a500d03e48'
                                    userArgs: 'custom_id:3c2da600'
                            consumerOption:
                                summary: 'Consumer Option'
                                value:
                                    emailTemplate: 'INVITE_CFUW'
                                    productId: '3c2da600-17ee-11e8-8a0e-5158039db37e'
                                    consumerId: '987fcdeb-51a2-43d7-8f9e-123456789abc'
                required: true
            responses:
                200:
                    description: 'Successful - invite link has been generated.'
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    applicationId:
                                        type: string
                                        format: uuid
                                        minLength: 36
                                        maxLength: 36
                                        example: '342abb30-04d4-482b-9860-6d5d1b40b681'
                                    visitId:
                                        type: string
                                        format: uuid
                                        minLength: 36
                                        maxLength: 36
                                        example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
                                    inviteLink:
                                        type: string
                                        minLength: 1
                                        maxLength: 255
                                        example: 'https://api.novacredit.com/r/12345'
                400:
                    description: 'Bad Request'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InviteBadRequestError'
                401:
                    description: 'Expired credentials'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ExpiredKeyError'
                403:
                    description: 'Forbidden'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InviteForbiddenError'
                500:
                    description: 'Internal Error'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InternalError'
            x-codegen-request-body-name: body

    /initialization:
        post:
            tags:
                - initialize
            operationId: postInitialization
            description: 'Initialize a Nova Credit session. Returns a JWT and public token for use in the NovaConnect widget. Accepts either a plaintext or JWE-encrypted request body.'
            security:
                - BasicAuth: []
            parameters:
                - $ref: '#/components/parameters/environmentHeader'
                - name: X-PUBLIC-ID
                  in: header
                  description: 'Your unique public_id.'
                  required: true
                  schema:
                      type: string
                      format: uuid
                      minLength: 36
                      maxLength: 36
                      example: '786fbcbc-0c90-47e9-9d0e-19428e68848f'
                - $ref: '#/components/parameters/productIdHeader'
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            oneOf:
                                - $ref: '#/components/schemas/InitializationRequest'
                                - $ref: '#/components/schemas/InitializationEncryptedRequest'
                        examples:
                            plaintext:
                                summary: 'Plaintext request with prefill'
                                value:
                                    token: JWT
                                    prefill:
                                        firstName: Raymond
                                        lastName: Marshal
                                        email: raymond@email.com
                                        dob: '1990-01-15'
                                        address: 225 Valencia St
                                        city: San Francisco
                                        state: CA
                                        zip: '94105'
                            encrypted:
                                summary: 'Encrypted request (JWE)'
                                value:
                                    encryptedValue: eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0...
                            plaintextWithConsumerId:
                                summary: 'Plaintext request with consumerId'
                                value:
                                    token: JWT
                                    consumerId: 987fcdeb-51a2-43d7-8f9e-123456789abc
                                    externalId: unique-internal-id-123
                                    userArgs: custom_id:3c2da600
            responses:
                200:
                    description: 'Successfully initialized session'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InitializationResponse'
                400:
                    description: 'Bad Request'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InitializationBadRequestError'
                401:
                    description: 'Expired Credentials'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ExpiredKeyError'
                403:
                    description: 'Forbidden'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ForbiddenError'
                404:
                    description: 'Not Found'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BadRequestError'
                            example:
                                error: INVALID_PRODUCT
                                terminated: 'true'
                                errorDisplay: Received productId is not a UUID
                500:
                    description: 'Internal Error'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InternalError'
    /consumers:
        post:
            tags:
                - consumers
            description: 'Create a Consumer object. You can then pass the returned `consumerId` to the NovaConnect widget, initialization endpoint, or invite endpoints. This allows you to group multiple visits by the same user.'
            operationId: createConsumer
            security:
                - BasicAuth: []
            parameters:
                - $ref: '#/components/parameters/environmentHeader'
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ConsumerCreateRequest'
                        example:
                            firstName: 'Arthur'
                            lastName: 'Cohen'
                            email: 'arthur@email.com'
                            dob: '1990-01-15'
                            address: '123 Main St'
                            city: 'New York'
                            state: 'NY'
                            zip: '10001'
                            phone: '+15555555555'
                            consumerExternalId: 'your-internal-id-123'
                            statedAnnualIncome: 75000
                            statedEmployerNames:
                                - 'Acme Corp'
                                - 'Acme Inc'
            responses:
                200:
                    description: 'Consumer successfully created'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ConsumerCreateResponse'
                            example:
                                consumerId: '987fcdeb-51a2-43d7-8f9e-123456789abc'
                400:
                    description: 'Bad Request'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ConsumerCreateBadRequestError'
                401:
                    description: 'Expired Credentials'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ExpiredKeyError'
                403:
                    description: 'Forbidden'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BasicAuthForbiddenError'
                500:
                    description: 'Internal Server Error'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InternalError'
            x-codegen-request-body-name: body

    /consumers/{consumerId}:
        patch:
            tags:
                - consumers
            description: 'Update an existing Consumer. All body fields are optional — you can update any combination of the fields. The response will be an empty object if the consumer is updated successfully.'
            operationId: updateConsumer
            security:
                - BasicAuth: []
            parameters:
                - $ref: '#/components/parameters/environmentHeader'
                - name: consumerId
                  in: path
                  required: true
                  description: 'The unique identifier for the consumer to update.'
                  schema:
                      type: string
                      format: uuid
                      minLength: 36
                      maxLength: 36
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ConsumerUpdateRequest'
                        example:
                            firstName: 'Arthur'
                            lastName: 'Cohen'
            responses:
                200:
                    description: 'Consumer successfully updated'
                    content:
                        application/json:
                            schema:
                                type: object
                            example: {}
                400:
                    description: 'Bad Request'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ConsumerBadRequestError'
                401:
                    description: 'Expired Credentials'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ExpiredKeyError'
                403:
                    description: 'Forbidden'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BasicAuthForbiddenError'
                500:
                    description: 'Internal Server Error'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InternalError'
            x-codegen-request-body-name: body

        get:
            tags:
                - consumers
            description: 'Retrieve the PII and visits of an existing Consumer.'
            operationId: getConsumer
            security:
                - BasicAuth: []
            parameters:
                - $ref: '#/components/parameters/environmentHeader'
                - name: consumerId
                  in: path
                  required: true
                  description: 'The unique identifier for the consumer.'
                  schema:
                      type: string
                      format: uuid
                      minLength: 36
                      maxLength: 36
            responses:
                200:
                    description: 'Consumer successfully retrieved'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ConsumerGetResponse'
                            example:
                                consumerId: '987fcdeb-51a2-43d7-8f9e-123456789abc'
                                firstName: 'Arthur'
                                lastName: 'Cohen'
                                email: 'arthur@email.com'
                                dob: '1990-01-15'
                                address: '123 Main St'
                                city: 'New York'
                                state: 'NY'
                                zip: '10001'
                                phone: '+15555555555'
                                consumerExternalId: 'your-internal-id-123'
                                statedAnnualIncome: 75000
                                statedEmployerNames:
                                    - 'Acme Corp'
                                    - 'Acme Inc'
                                visits:
                                    - publicToken: '36128cc3-bde6-4026-8abd-4cbb790d82d2'
                400:
                    description: 'Bad Request'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ConsumerBadRequestError'
                401:
                    description: 'Expired Credentials'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ExpiredKeyError'
                403:
                    description: 'Forbidden'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BasicAuthForbiddenError'
                404:
                    description: 'Not Found'
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    error:
                                        type: string
                                        minLength: 1
                                        maxLength: 64
                                        example: 'INVALID_CONSUMER_ID'
                                    description:
                                        type: string
                                        minLength: 1
                                        maxLength: 255
                500:
                    description: 'Internal Server Error'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InternalError'

    /jwkset:
        get:
            tags:
                - jwkset
            operationId: getJWKSet
            description: 'Retrieve the JSON Web Key Set (JWKS) containing the public RSA key used to encrypt initialization request payloads or verify JWT signatures. Use the `payloadEncrRsa` key to encrypt your request body and pass it as the encryptedValue field on the /initialization endpoint. Note that this endpoint should be called each time a payload is to be encrypted, since we will regularly rotate keys. Note: in the future we may support additional encryption methods, which could result in additional keys being returned with different field values and structure.'
            security: []
            parameters:
                - $ref: '#/components/parameters/environmentHeader'
                - name: Content-Type
                  in: header
                  schema:
                      type: string
                      enum:
                          - application/json
                  example: application/json
            responses:
                200:
                    description: 'Successfully retrieved JWK Set'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/JWKSetResponse'
                            example:
                                keys:
                                    - kid: payloadEncrRsa
                                      kty: RSA
                                      alg: RSA-OAEP-256
                                      use: enc
                                      n: 7kZDkQB78iYrQOhW7BZrtrnUNbYQMuEwrLXtLLCmH4WJjPyccZuOAHQJIgS3qluXnJbVZKwF52P73nF3v7AB8L1MVqRp94t5QlA5ysHscvDa_lXjcN6DSREY66LzQkita-zU0de9_6v1DVfbjn7OiPA_gbQVKMM3vPzToYInz6RnSJTG1bLbcRM_4YBDEqxphAJmEywP-E4xCwGn05Sdw5trJquWKIKPLMK9XWRiWifqeS8v2dZg_pbLjg_zPNXy0BcIIrci2K1TbuEXoAGFbjbuFN7WQPkclcP9dP2jE1OEWxMzg5FoSQo6QKCBIz3lkkPhqg4MQz_VhHgQvX_KrmO_pIHebvkc_473yf5J7YUOq5ze97OH67JflVSh0aFk7k6Yd8dgQCQID_6LaQHFTitTZScy3Cyl0gD34ifo8DnAX-BrbqBP92makSH1VuYQ0ejbMpz-Ayln4h1nGX-85XL_rgWF4bIPYlP2hnZKNpAr_Fa7uICH5mzsilnFybUIgQjDZ2KhKYe1ayNDPf7lvdPUw1SWAqdnz0glKfOC7CHQtSkU7n8sSBUl8KA24fZggNydKt9-VEL6si-wcR8OJ2IUfe2Ut5VE339V-C-zTh-iVoujinBGpmP-iIyJzRTTmHHwhOy7yRFRO1wQkVz02QFYi8f-sF7Mntm3rzC8RwM
                                      e: AQAB
                                    - kid: payloadSignRsa
                                      kty: RSA
                                      alg: RS256
                                      use: sig
                                      n: l1kvWUzu107GrXPI3i1mlosGcJCQXcjO9Xockxm6zaguK1qzq5LhNRuWW7IKwIX8xkWwbuZWSEAwLgsHe3C8KDgotGK9oNqKax4WaYTt8bal7IrB32qydVB8u0tjgaoZgQGIKaWLOyXAkHI6AZ9qpG9ONJ2bMMHUPrJfEtguxPxvd0MQ2F5kKR7eh6vXyuCwiA7M1fCcMcCnK7S4bpCbviQXvEsIEb8UKBmWUJuxLg2n1WVhFrMlARyorooo6WxCDEVJ0fX398bDxwdVwccyBIQcb4pF7NIJLiUZgyuFtjUmnPFDC4COt7BT5nRI7JJEqTUzAaCrcZNfOzT7rUYdDDoVuIlRuUjFoQMg-o4a8XG3xGy7DUzNdFTWsLlWJjQeIMpi3KxTHvsRwDCrIu3akZBsIYJ2HDfoWfdCg42E-_Ux35uYq3wBF-uJBiGmB1Z6tKNgSIU1BxTpNbNWw7aYdplBk_NXcGpwvIRf9XE0LtPyH7MSYcOsvIRu1ac2H8WYNF6qh_1u2zHrG0y2HcK8ze5R-eBA0drHDbN8vTxg8ktW-HtVy2FZDCXxkl1FGvzE-tImqmId8g6ItX0wEkDPY3K_5Ji7r7DB_7o-9Nbrab7oTnVbEaKrqD1pCIT7EElB5ij_IRe2tfsOaTSmbljhblxmmLdTrw8ZevoHszCo4b0
                                      e: AQAB
                400:
                    description: 'Bad Request'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BadRequestError'
                500:
                    description: 'Internal Error'
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/InternalError'

security:
    - BasicAuth: []
    - BearerAuth: []

webhooks:
    visitStatus:
        post:
            summary: 'Visit status'
            description: "We make a POST API call to the webhook callback URL that you provide for each NovaConnect widget interaction. Webhooks are sent during consumer visits to provide information about consumer's actions, such as starting or finishing a visit. Webhooks can be managed in the Developer tab on the Nova Credit Dashboard, where you must set your callback URL and can toggle your various event subscriptions on and off. Some events or statuses are subscribed to by default. Return a 200 response to acknowledge receipt."
            parameters:
                - name: X-Timestamp
                  in: header
                  description: 'Timestamp of request generation. Present when webhook signatures are enabled (contact your Nova Credit account manager to enable).'
                  required: false
                  schema:
                      type: string
                - name: X-Nova-Signature
                  in: header
                  description: 'SHA256 HMAC digest of the request timestamp and payload, period-delimited. Verified using your Webhook Signatures Secret Key found in the Developer tab of your Nova Credit Dashboard. Present when webhook signatures are enabled (contact your Nova Credit account manager to enable).'
                  required: false
                  schema:
                      type: string
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/WebhookBody'
            responses:
                200:
                    description: 'Webhook received successfully.'

components:
    parameters:
        environmentHeader:
            name: X-ENVIRONMENT
            in: header
            description: 'User environment'
            required: false
            deprecated: true
            schema:
                type: string
                minLength: 7
                maxLength: 10
                enum:
                    - production
                    - sandbox
        publicTokenHeader:
            name: X-PUBLIC-TOKEN
            in: header
            description: 'Unique identifier of the Cash Atlas report you are retrieving. Required if no X-EXTERNAL-ID header is provided.'
            required: false
            schema:
                type: string
                format: uuid
                minLength: 36
                maxLength: 36
                example: 'e3f60d3a-8a22-4940-9d1e-50f4f9878503'
        externalIdHeader:
            name: X-EXTERNAL-ID
            in: header
            description: 'External ID of the Cash Atlas report you are retrieving. Required if no X-PUBLIC-TOKEN header is provided.'
            required: false
            schema:
                type: string
                minLength: 1
                maxLength: 64
                example: 'c5cf34e0-50eb-4075-9b1a-8494e0ba8663'
        publicIdHeader:
            name: X-PUBLIC-ID
            in: header
            description: 'Your unique public_id. Required if X-EXTERNAL-ID header is provided and report belongs to a managed account.'
            required: false
            schema:
                type: string
                format: uuid
                minLength: 36
                maxLength: 36
                example: '786fbcbc-0c90-47e9-9d0e-19428e68848f'

        productIdHeader:
            name: X-PRODUCT-ID
            in: header
            description: 'Unique identifier of the product.'
            required: true
            schema:
                type: string
                format: uuid
                minLength: 36
                maxLength: 36
                example: '3c2da600-17ee-11e8-8a0e-5158039db37e'

    securitySchemes:
        BasicAuth:
            type: http
            scheme: basic
        BearerAuth:
            type: http
            scheme: bearer
            bearerFormat: 'Contains the base64 encoded string of the access token retrieved from the /accesstoken endpoint.'

    examples:
        MalformedHeaders:
            value:
                error: 'MALFORMED_HEADERS'
                terminated: 'true'
        InvalidToken:
            value:
                error: 'INVALID_TOKEN'
                terminated: 'true'
        InvalidExternalId:
            value:
                error: 'INVALID_EXTERNAL_ID'
                terminated: 'true'

    schemas:
        AchDetails:
            type: object
            required:
                - routingNumber
                - fullAccountNumber
            properties:
                fullAccountNumber:
                    description: 'The full bank account number.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: '123456789012'
                routingNumber:
                    description: 'The bank routing number.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: '123456789'

        AccessTokenSuccess:
            type: object
            required:
                - accessToken
                - exp
            properties:
                accessToken:
                    description: 'Access token you can now use to retrieve a Cash Atlas report. Be sure to base64 encode your access token.'
                    type: string
                    minLength: 1
                    maxLength: 550
                    example: '<your_access_token>'
                exp:
                    description: 'Unix timestamp of when the access token will expire.'
                    type: integer
                    format: int32
                    example: 1607471945

        CashAtlasJSONv2:
            type: object
            properties:
                meta:
                    description: 'Information specific to the report that has been returned.'
                    allOf:
                        - $ref: '#/components/schemas/Meta'
                product:
                    description: 'Details about the product the applicant applied for.'
                    allOf:
                        - $ref: '#/components/schemas/Product'
                sources:
                    description: "List of data sources used to build the applicant's Cash Atlas report."
                    type: array
                    items:
                        $ref: '#/components/schemas/CashAtlasSource'
                identities:
                    description: "The applicant's personal identity information reported from each data source."
                    type: array
                    items:
                        $ref: '#/components/schemas/CashAtlasIdentity'
                account_details:
                    description: 'Details about each bank account connected by the applicant. The array can have zero objects, and there is no upper bound.'
                    type: array
                    items:
                        $ref: '#/components/schemas/AccountDetail'
                attributes:
                    description: 'Analytical values derived from the underlying bank transaction data. Returned in an array; the array can have zero objects, and there is no upper bound. Please consider an approach that permits adding and removing attributes without incurring additional integration work. It is particularly important that you discuss the mechanics of your attributes integration if it relies on a fixed ordering or maximum number of attributes.'
                    type: array
                    items:
                        $ref: '#/components/schemas/Attribute'
                scores:
                    description: "Information specific to the applicant's Nova Score. Scores are returned in an array; multiple score versions may be returned sorted semantically by version in ascending order. The array can have zero objects, and there is no upper bound."
                    type: array
                    items:
                        $ref: '#/components/schemas/CashScore'
                consumer_data_properties:
                    description: 'Data quality indicators used as inputs to the Nova Score v2.0 model. Only returned when a Nova Score v2.0 is included in the report.'
                    type: array
                    items:
                        $ref: '#/components/schemas/ConsumerDataProperty'
                document_uploads:
                    description: 'Bank statement document uploads submitted by the applicant, including irregularity detection results. Only present when document uploads exist for the report.'
                    type: array
                    items:
                        $ref: '#/components/schemas/DocumentUpload'

        Meta:
            type: object
            properties:
                public_token:
                    description: 'The unique identifier of this report.'
                    type: string
                    format: uuid
                    minLength: 36
                    maxLength: 36
                    example: 'e3f60d3a-8a22-4940-9d1e-50f4f9878503'
                user_args:
                    description: 'The input of the userArgs function in NovaConnect. Can be null.'
                    type:
                        - string
                        - 'null'
                    minLength: 1
                    maxLength: 255
                    example: '22bbd586-12b9-4876-8ec0-d210d081f4a1|email@test.com'
                created_at:
                    description: "The date the consumer's data was retrieved."
                    type: string
                    format: date-time
                    minLength: 20
                    maxLength: 35
                    example: '2024-01-13T11:07:46.51Z'
                api_version:
                    description: 'The API version used to generate this report.'
                    type: string
                    minLength: 1
                    maxLength: 10
                    example: '2.0.0'
                nova_report_revision:
                    description: 'The revision name for this report. This field will be null if this report has never been revised.'
                    type:
                        - string
                        - 'null'
                    minLength: 1
                    maxLength: 10
                    example: '1'
                nova_report_revision_created_at:
                    description: 'The date the report revision was created. This field will be null if this report has never been revised.'
                    type:
                        - string
                        - 'null'
                    format: date-time
                    minLength: 20
                    maxLength: 35
                    example: '2024-01-13T11:07:46.51Z'
                external_id:
                    description: 'The unique applicant identifier of the report from your system. Can be null if not provided.'
                    type:
                        - string
                        - 'null'
                    minLength: 1
                    maxLength: 64
                    example: 'd167c6bb-225c-461c-be63-f0bc3a1f62ea'
                status:
                    description: 'The status for this report. If a report is available, the status will be SUCCESS.'
                    type: string
                    minLength: 1
                    maxLength: 64
                    example: 'SUCCESS'
                substatus:
                    description: 'The substatus for the report. Can be null.'
                    type:
                        - string
                        - 'null'
                    minLength: 1
                    maxLength: 64
                    example: 'MFA_REQUIRED_ON_FETCH'
                consumer_id:
                    description: 'The unique identifier of the consumer associated with this report. Can be null.'
                    type:
                        - string
                        - 'null'
                    format: uuid
                    minLength: 36
                    maxLength: 36
                    example: 'b281e335-9d19-4aa7-b559-e74d08a05cf4'
                consumer_external_id:
                    description: 'The unique identifier from your system of the consumer associated with this report. Can be null.'
                    type:
                        - string
                        - 'null'
                    minLength: 1
                    maxLength: 64
                    example: '472cbdc9-cf31-4117-a095-e27e2db054e5'

        Product:
            type: object
            properties:
                name:
                    description: 'Product name.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'Village Communities'
                product_id:
                    description: 'The unique identifier for the product.'
                    type: string
                    format: uuid
                    minLength: 36
                    maxLength: 36
                    example: 'c3a37c41-7c62-11e7-8141-19157d9a48c7'
                inquiry_type:
                    description: 'The type of inquiry. See inquiry_type values.'
                    type: string
                    minLength: 1
                    maxLength: 64
                    enum:
                        - COMMERCIAL
                        - CONSUMER
                        - CREDIT_CARD
                        - MONITORING
                        - MORTGAGE
                        - OTHER
                        - PERSONAL
                        - STUDENT
                        - TELCO
                        - TENANT
                        - UTILITY
                        - VEHICLE_AUTO
                        - VEHICLE_OTHER
                    example: 'TENANT'

        CashAtlasSource:
            type: object
            properties:
                source_id:
                    description: 'A human-readable identifier for the source, unique within the context of the report.'
                    type: string
                    minLength: 1
                    maxLength: 64
                    enum:
                        - CONSUMER_INPUT
                        - CUSTOMER_INPUT
                        - OCROLUS
                        - USA_AKOYA
                        - USA_FIN
                        - USA_MX
                        - USA_RAI
                    example: 'USA_FIN'
                source_type:
                    description: 'The type of data source.'
                    type: string
                    minLength: 1
                    maxLength: 64
                    enum:
                        - BANK_TRANSACTION
                        - EMPLOYMENT
                        - PAYROLL
                        - MANUAL
                        - FRAUD
                    example: 'BANK_TRANSACTION'
                status:
                    description: 'The final status for the source.'
                    type: string
                    minLength: 1
                    maxLength: 64
                    enum:
                        - SUCCESS
                    example: 'SUCCESS'

        CashAtlasIdentity:
            type: object
            properties:
                source_id:
                    description: 'The identifier for the source that reported the identity information.'
                    type: string
                    minLength: 1
                    maxLength: 64
                    enum:
                        - CONSUMER_INPUT
                        - CUSTOMER_INPUT
                        - OCROLUS
                        - USA_AKOYA
                        - USA_FIN
                        - USA_MX
                        - USA_RAI
                    example: 'CONSUMER_INPUT'
                first_name:
                    description: 'The first name of the applicant.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'Raymond'
                last_name:
                    description: 'The last name of the applicant.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'Marshal'
                full_name:
                    description: 'The full name of the applicant.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'Raymond Marshal'
                emails:
                    description: 'A list of emails associated to the applicant.'
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 255
                    example:
                        - 'raymond@email.com'
                matching:
                    description: 'Information about sources which have matching and conflicting values to a particular identity. Only present if more than one identity exists.'
                    allOf:
                        - $ref: '#/components/schemas/IdentityMatching'

        IdentityMatching:
            type: object
            properties:
                full_name:
                    description: 'Matched and unmatched sources for the full name of the applicant.'
                    allOf:
                        - $ref: '#/components/schemas/MatchingField'

        MatchingField:
            type: object
            properties:
                matched_sources:
                    description: 'List of sources which have a value that matches this identity. The array can have zero objects, and there is no upper bound.'
                    type: array
                    items:
                        $ref: '#/components/schemas/MatchingSource'
                unmatched_sources:
                    description: 'A list of sources which have a value that conflicts with this identity. The array can have zero objects, and there is no upper bound.'
                    type: array
                    items:
                        $ref: '#/components/schemas/MatchingSource'

        MatchingSource:
            type: object
            properties:
                source_id:
                    description: 'The identifier for the source.'
                    type: string
                    minLength: 1
                    maxLength: 64
                    enum:
                        - CONSUMER_INPUT
                        - CUSTOMER_INPUT
                        - OCROLUS
                        - USA_AKOYA
                        - USA_FIN
                        - USA_MX
                        - USA_RAI
                    example: 'USA_FIN'

        AccountDetail:
            type: object
            properties:
                source_id:
                    description: 'The identifier for the source that reported the account details.'
                    type: string
                    minLength: 1
                    maxLength: 64
                    enum:
                        - CONSUMER_INPUT
                        - CUSTOMER_INPUT
                        - OCROLUS
                        - USA_AKOYA
                        - USA_FIN
                        - USA_MX
                        - USA_RAI
                    example: 'USA_FIN'
                account_id:
                    description: 'Unique identifier for the account.'
                    type: string
                    format: uuid
                    minLength: 36
                    maxLength: 36
                    example: '36139831-0a91-4d1f-bc3e-edc908a978c6'
                months_available:
                    description: 'Number of months of transaction data available on the report. Up to 3 digits.'
                    type: integer
                    example: 6
                owner_full_name:
                    description: 'Full name of the owner of the account.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'John Doe'
                institution_name:
                    description: 'Name of institution such as Chase or Bank of America.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'CHASE'
                account_name:
                    description: 'Name of the account within the bank.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'PERSONAL CHECKING ACCOUNT'
                account_type:
                    description: 'Type of the account within the bank.'
                    type: string
                    minLength: 1
                    maxLength: 64
                    enum:
                        - CASH_EQUIVALENT
                    example: 'CASH_EQUIVALENT'
                account_subtype:
                    description: 'For cash-equivalent accounts, whether the account is checking or savings (`CHECKING`, `SAVINGS`, or `OTHER` when it is neither); null for all other account types.'
                    type:
                        - string
                        - 'null'
                    minLength: 1
                    maxLength: 64
                    enum:
                        - CHECKING
                        - SAVINGS
                        - OTHER
                    example: 'CHECKING'
                date_opened:
                    description: 'Date the account was opened. May not be returned in all cases.'
                    type: string
                    format: date
                    minLength: 10
                    maxLength: 10
                    example: '2015-05-01'
                truncated_account_number:
                    description: 'If available, the last four digits of the account number.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: '1234'
                responsibility:
                    description: 'Indicates whether the applicant is individually or jointly responsible for the account.'
                    type: string
                    minLength: 1
                    maxLength: 64
                    enum:
                        - INDIVIDUAL
                        - JOINT
                    example: 'INDIVIDUAL'
                last_statement_end_date:
                    description: 'End date of the most recent statement.'
                    type: string
                    format: date
                    minLength: 10
                    maxLength: 10
                    example: '2015-05-30'
                addresses:
                    description: 'A history of contact information attached to this account. The array can have zero objects, and there is no upper bound.'
                    type: array
                    items:
                        $ref: '#/components/schemas/AccountAddress'
                current_balance:
                    description: 'Current balance of the account. Monetary value accurate to 2 decimal places (scale = 2). Up to 20 digits.'
                    type: number
                    format: double
                    example: 45971.23

        AccountAddress:
            type: object
            properties:
                address_id:
                    description: 'Unique identifier for the address.'
                    type: string
                    format: uuid
                    minLength: 36
                    maxLength: 36
                    example: '80421b7e-7918-4963-b5fb-85055c2994b7'
                address:
                    description: 'The full mailing address of the account owner.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: '225 Valencia St., San Francisco, CA 94103'
                street:
                    description: 'The street address where the account owner is located.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'Valencia St.'
                neighborhood:
                    description: 'The neighborhood where the account owner is located.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'Mission District'
                district:
                    description: 'The district where the account owner is located.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'District 9'
                city:
                    description: 'The city where the account owner is located.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'San Francisco'
                zipcode:
                    description: 'The zip code where the account owner is located.'
                    type: string
                    minLength: 5
                    maxLength: 10
                    example: '94103'
                state:
                    description: 'The state where the account owner is located.'
                    type: string
                    minLength: 2
                    maxLength: 2
                    example: 'CA'

        Attribute:
            type: object
            properties:
                name:
                    description: 'The name of the attribute.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'EXPENSES_COUNT_3_MONTH_AVG'
                description:
                    description: 'Human readable description of the attribute.'
                    type: string
                    minLength: 1
                    maxLength: 500
                    example: 'Average count of expenses over the last 3 months'
                node:
                    description: 'Select top level nodes from the report body that are associated with an attribute or categorization of an attribute. Not all node types may be available at the top level of the report.'
                    type: string
                    minLength: 1
                    maxLength: 64
                    enum:
                        - ASSET
                        - EXPENSE
                        - RATIO
                        - TOTAL
                        - CADENCE
                        - CASHFLOW
                        - INFLOW
                    example: 'EXPENSE'
                source_ids:
                    description: 'A list of IDs of the sources utilized to generate this attribute.'
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 64
                        enum:
                            - CONSUMER_INPUT
                            - CUSTOMER_INPUT
                            - OCROLUS
                            - USA_AKOYA
                            - USA_FIN
                            - USA_MX
                            - USA_RAI
                    example:
                        - 'USA_FIN'
                value:
                    description: |-
                        Value of the attribute. Up to 20 digits. If the attribute cannot be calculated due to configured transaction depth (number of months of data to pull that is configured by your Nova representative), it is omitted from the `attributes` array entirely. If the attribute cannot be calculated due to no usable records or values, a placeholder value is returned instead of null, indicating one of two conditions:

                        - No usable records: no relevant records were found (e.g. no accounts connected, or no transactions found across any connected account).
                        - No usable values: records exist for the node, but the records do not match a constraint such as time frame.

                        The placeholder value depends on the underlying value type of the attribute:

                        | Type | Min Raw / Floored Value | Max Raw / Capped Value | No Usable Records | No Usable Values |
                        | :--- | :--- | :--- | :--- | :--- |
                        | Dollar Amounts | -9,999,999.99 | 9999995 | 9,999,998 | 9,999,996 |
                        | Float | -9,999,999.99999 | 9999995.00000 | 9,999,998 | 9,999,996 |
                        | Short Integer | 0 | 9,995 | 9,998 | 9,996 |

                    type: number
                    example: 10
                adverse_action_code:
                    description: |-
                        Numeric code between 00 and 100, exclusive. '25' is the default code, returned when there is insufficient information on or a lack of accounts. Each code always corresponds to the same description, listed below. These are the current values as of this writing; more codes are subject to be added.

                        | Code | Description |
                        | :--- | :--- |
                        | `11` | Time since lowest balance on deposit accounts is too short |
                        | `12` | Time since highest balance on deposit accounts is too long |
                        | `13` | Too many days with low balance on asset accounts |
                        | `14` | Too many irregular debt repayment |
                        | `17` | Time since last deposit on deposit accounts is too long |
                        | `18` | Time since last high value deposit on deposit accounts is too long |
                        | `19` | Time since last high value withdraw on deposit accounts is too short |
                        | `21` | Cash equivalent account balance is too low |
                        | `24` | Ratio of expenses to account balance is too high |
                        | `25` | Insufficient information on or lack of accounts |
                        | `30` | Amount of withdrawals is too high |
                        | `32` | Amount of deposits is too low |
                        | `34` | Ratio of withdrawal amount to deposit amount is too high |
                        | `40` | BNPL payment amount is too high |
                        | `41` | BNPL utilization is too high |
                        | `50` | Debt repayment amount too high |
                        | `54` | Ratio of debt repayment to account balance is too high |
                        | `55` | Ratio of debt repayment to deposits is too high |
                        | `60` | Housing payment amount is too high |
                        | `64` | Ratio of withdrawal to account balance is too high |
                        | `70` | Loan deposit amount is too high |
                        | `74` | Ratio of expense to deposits is too high |
                        | `76` | Expense transaction amount is too high |
                    type: string
                    minLength: 2
                    maxLength: 2
                    enum:
                        - '11'
                        - '12'
                        - '13'
                        - '14'
                        - '17'
                        - '18'
                        - '19'
                        - '21'
                        - '24'
                        - '25'
                        - '30'
                        - '32'
                        - '34'
                        - '40'
                        - '41'
                        - '50'
                        - '54'
                        - '55'
                        - '60'
                        - '64'
                        - '70'
                        - '74'
                        - '76'
                    example: '76'

        CashScore:
            type: object
            properties:
                source_ids:
                    description: 'A list of ids of the sources utilized to generate this score.'
                    type: array
                    items:
                        type: string
                        minLength: 1
                        maxLength: 64
                        enum:
                            - CONSUMER_INPUT
                            - CUSTOMER_INPUT
                            - OCROLUS
                            - USA_AKOYA
                            - USA_FIN
                            - USA_MX
                            - USA_RAI
                    example:
                        - 'USA_FIN'
                score_type:
                    description: 'The type of score.'
                    type: string
                    minLength: 1
                    maxLength: 64
                    enum:
                        - NOVA_SCORE_CASH_FLOW
                    example: 'NOVA_SCORE_CASH_FLOW'
                score_version:
                    description: "Version string with required 'v' prefix (e.g., 'v1.0', 'v2.1.3')."
                    type: string
                    minLength: 4
                    maxLength: 10
                    example: 'v1.0'
                value:
                    description: 'Value of the score. Up to 4 digits.'
                    type:
                        - integer
                        - 'null'
                    example: 600
                adverse_action_codes:
                    description: "Key factors affecting the consumer's score. Always returns at least one element."
                    type: array
                    items:
                        $ref: '#/components/schemas/AdverseActionCode'

        ConsumerDataProperty:
            type: object
            properties:
                field_name:
                    description: 'Value of field name.'
                    type: string
                    minLength: 1
                    maxLength: 64
                    enum:
                        - TOTAL_TRANSACTION_COUNT
                        - TOTAL_HISTORY_LENGTH_DAYS
                        - LOW_ACCOUNT_ACTIVITY_INDICATOR
                        - LIMITED_DATA_AVAILABLE_INDICATOR
                value:
                    description: 'Numeric or boolean values. Up to 10 digits.'
                    oneOf:
                        - type: integer
                        - type: boolean
                    examples:
                        integer:
                            value: 142
                        boolean:
                            value: true

        AdverseActionCode:
            type: object
            properties:
                code:
                    description: |-
                        Numeric code between 00 and 100, exclusive. '25' is the default code, returned when there is insufficient information on or a lack of accounts. Each code always corresponds to the same description, listed below. These are the current values as of this writing; more codes are subject to be added.

                        | Code | Description |
                        | :--- | :--- |
                        | `13` | Too many days with low balance on asset accounts |
                        | `21` | Cash equivalent account balance is too low |
                        | `24` | Ratio of expenses to account balance is too high |
                        | `32` | Amount of deposits is too low |
                        | `34` | Ratio of withdrawal amount to deposit amount is too high |
                        | `40` | BNPL payment amount is too high |
                        | `64` | Ratio of withdrawal to account balance is too high |
                        | `70` | Loan deposit amount is too high |
                        | `74` | Ratio of expense to deposits is too high |
                        | `76` | Expense transaction amount is too high |
                    type: string
                    minLength: 2
                    maxLength: 2
                    enum:
                        - '11'
                        - '12'
                        - '13'
                        - '14'
                        - '17'
                        - '18'
                        - '19'
                        - '21'
                        - '24'
                        - '25'
                        - '30'
                        - '32'
                        - '34'
                        - '40'
                        - '41'
                        - '50'
                        - '54'
                        - '55'
                        - '60'
                        - '64'
                        - '70'
                        - '74'
                        - '76'
                    example: '21'
                description:
                    description: 'Human readable description. Always matches the `code` field above one-to-one; see the table on `code` for the full mapping.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'Cash equivalent account balance is too low'

        DocumentUpload:
            type: object
            properties:
                document_upload_id:
                    description: 'Unique identifier for the document upload.'
                    type: string
                    format: uuid
                    minLength: 36
                    maxLength: 36
                    example: '6e5cd9e0-6e60-11f0-922e-3334b39972c3'
                source_filepath:
                    description: 'Path to the uploaded document file, in the format {public_token}/{filename}.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: '3f03512e-9d1a-4d54-873c-739a1863a61a/162539c6-7052-49c6-b6cd-0b4c113cb5cc'
                irregularity_detection:
                    description: 'Fraud detection results for the uploaded document. Only present when fraud detection was performed.'
                    allOf:
                        - $ref: '#/components/schemas/IrregularityDetection'

        IrregularityDetection:
            type: object
            properties:
                status:
                    description: 'The overall fraud detection status for the document.'
                    type: string
                    minLength: 1
                    maxLength: 64
                    enum:
                        - DETECTED
                        - NOT_DETECTED
                        - REVIEW
                    example: 'NOT_DETECTED'
                reasons:
                    description: 'List of reasons contributing to the fraud detection status. Present when one or more fraud signals were detected.'
                    type: array
                    items:
                        $ref: '#/components/schemas/IrregularityReason'
                version:
                    description: 'The version of the fraud detection model used.'
                    type: string
                    minLength: 1
                    maxLength: 10
                    example: '3.1'
                genuine_pdf:
                    description: 'Indicates the document is a genuine, unaltered PDF as confirmed by both RAI and Ocrolus. Only present when the document is confirmed genuine.'
                    type: boolean
                    example: true

        IrregularityReason:
            type: object
            properties:
                reason:
                    description: 'Human-readable description of the detected irregularity.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'Unusual Document Source Detected'
                severity:
                    description: 'Severity level of the detected irregularity.'
                    type: string
                    minLength: 1
                    maxLength: 64
                    example: 'High Risk'

        CashAtlasFileList:
            description: 'A list of uploaded documents. The array can have zero objects, and there is no upper bound.'
            type: array
            items:
                type: object
                required:
                    - document_upload_type
                    - document_upload_id
                    - source_id
                    - source_filepath
                properties:
                    document_upload_type:
                        description: 'The type of the uploaded document.'
                        type: string
                        minLength: 1
                        maxLength: 64
                        example: 'BANK_STATEMENT'
                    document_upload_id:
                        description: 'A unique identifier for the uploaded document.'
                        type: string
                        minLength: 36
                        maxLength: 36
                        format: uuid
                        example: '4aee9138-19ee-472f-a96b-272e2fd673b8'
                    source_id:
                        description: 'The data source that processed the document.'
                        type: string
                        minLength: 1
                        maxLength: 64
                        enum:
                            - CONSUMER_INPUT
                            - CUSTOMER_INPUT
                            - OCROLUS
                            - USA_AKOYA
                            - USA_FIN
                            - USA_MX
                            - USA_RAI
                        example: 'OCROLUS'
                    source_filepath:
                        description: 'The filepath used to retrieve the document via the files endpoint.'
                        type: string
                        minLength: 1
                        maxLength: 255
                        example: '8288a4d4-5235-4bc8-9eee-70edf7441d74/b6655a45-9850-4e38-b387-b0e4cda485a7.pdf'

        CashAtlasStatusv2:
            type: object
            required:
                - status
            properties:
                status:
                    description: |
                        The status of a Cash Atlas report.

                        * `INVITED` - The applicant has been sent an invite but has not yet started.
                        * `INITIALIZED` - The `/connect/initialization` endpoint has been used.
                        * `PENDING` - A visit has been initialized upon opening the NovaConnect widget.
                        * `SUCCESS` - The data source has successfully provided information on the applicant.
                        * `EXPIRED` - The visit has expired before the applicant was able to complete the flow.
                        * `NOT_AUTHENTICATED` - The applicant was unable to link a valid financial account through NovaConnect with their external financial institution, or did not upload supported bank statement documents, within the allowed retry attempts.
                        * `ERROR` - An error occurred and the Cash Atlas report could not be compiled.
                        * `SUPPLIER_UNRESPONSIVE` - The applicant has encountered a data supplier outage while going through the widget.
                    type: string
                    example: 'SUCCESS'
                    minLength: 1
                    maxLength: 64
                    enum:
                        - INVITED
                        - INITIALIZED
                        - PENDING
                        - SUCCESS
                        - EXPIRED
                        - NOT_AUTHENTICATED
                        - ERROR
                        - SUPPLIER_UNRESPONSIVE
                substatus:
                    type: string
                    description: |
                        Whenever possible, the Nova Credit API will return additional context about the status in a substatus field. This field is only present when a substatus exists; it is omitted entirely otherwise.

                        Substatuses with ERROR status:
                        * `INVALID_PREFILLS_PII_MISSING` - Must provide firstName, lastName, email, and DOB or full address.
                        * `INVALID_PREFILL_KEY` - A prefill field has been passed in that is not supported for the current API version.
                        * `INVALID_PREFILL_ADDRESS` - The address sent via prefill must be a string with max length 100 and contain a valid street address.
                        * `INVALID_PREFILL_CITY` - The city sent via prefill must be a string with max length 100.
                        * `INVALID_PREFILL_DOB` - The birthday sent via prefill is missing or not in YYYY-MM-DD format.
                        * `INVALID_PREFILL_EMAIL` - The email sent via prefill must be a valid email with max length 100.
                        * `INVALID_PREFILL_FIRST_NAME` - The first name sent via prefill must be a string less than 255 characters.
                        * `INVALID_PREFILL_LAST_NAME` - The last name sent via prefill must be a string less than 255 characters.
                        * `INVALID_PREFILL_INCOME` - The stated annual income sent via prefill must be an integer between 0 and 2147483647.
                        * `INVALID_PREFILL_PHONE` - The phone number sent via prefill must be a string with max length 255.
                        * `INVALID_PREFILL_STATE` - The state sent via prefill is missing or not a valid two letter US state or territory code.
                        * `INVALID_PREFILL_ZIP` - The zip code sent via prefill must be a string with a valid USA zip code.

                        Substatuses with NOT_AUTHENTICATED status:
                        * `MFA_REQUIRED_ON_FETCH` - Multi-factor authentication failed or was required but not completed.
                        * `INCOMPATIBLE_ACCOUNT_TYPES_SUBMITTED` - The applicant only connected debt accounts (e.g. credit card).
                        * `E_BANKING_NOT_SUPPORTED` - The connected bank does not support e-banking features.
                    minLength: 1
                    maxLength: 64
                    enum:
                        - INVALID_PREFILLS_PII_MISSING
                        - INVALID_PREFILL_KEY
                        - INVALID_PREFILL_ADDRESS
                        - INVALID_PREFILL_CITY
                        - INVALID_PREFILL_DOB
                        - INVALID_PREFILL_EMAIL
                        - INVALID_PREFILL_FIRST_NAME
                        - INVALID_PREFILL_LAST_NAME
                        - INVALID_PREFILL_INCOME
                        - INVALID_PREFILL_PHONE
                        - INVALID_PREFILL_STATE
                        - INVALID_PREFILL_ZIP
                        - E_BANKING_NOT_SUPPORTED
                        - MFA_REQUIRED_ON_FETCH
                        - INCOMPATIBLE_ACCOUNT_TYPES_SUBMITTED
                    example: 'MFA_REQUIRED_ON_FETCH'

        InviteBody:
            description: |
                Request body for the invite endpoints. Supports two usage patterns:

                **PII Option:** Provide applicant PII fields (`applicantFirstName`, `applicantLastName`, `applicantEmail` are required in addition to `emailTemplate` and a product identifier).

                **Consumer Option:** Provide a `consumerId` instead of PII fields (only `consumerId`, `emailTemplate`, and a product identifier are required).

                **Product identifier:** Exactly one of `productId`, `productIdAlias`, or `productName` must be provided. `productName` requires `accountName` to also be provided.
            required:
                - emailTemplate
            type: object
            properties:
                emailTemplate:
                    description: 'The email template to use for the invite. Use `INVITE_CFUW` for the standard Cash Atlas invite.'
                    type: string
                    minLength: 1
                    maxLength: 64
                    enum:
                        - INVITE_CFUW
                    example: 'INVITE_CFUW'
                productId:
                    description: 'Product id associated with the product the applicant is applying for. Exactly one of `productId`, `productIdAlias`, or `productName` must be provided.'
                    type: string
                    format: uuid
                    minLength: 36
                    maxLength: 36
                    example: '3c2da600-17ee-11e8-8a0e-5158039db37e'
                productIdAlias:
                    description: 'An alias for the product ID that you use internally to identify the product. Use this instead of `productId` if you have been configured with ID aliases by your Nova Credit Account Manager. Exactly one of `productId`, `productIdAlias`, or `productName` must be provided.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'my-product-alias'
                productName:
                    description: 'The external name of the product the applicant is applying for. Use this instead of `productId` when managing multiple Child accounts as a Parent. When `productName` is provided, `accountName` is also required. Exactly one of `productId`, `productIdAlias`, or `productName` must be provided.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'My Product Name'
                accountName:
                    description: 'The name of the Child customer account. Used by Parent accounts — when provided, you do not need to pass `X-PUBLIC-ID` in the header. Required when `productName` is provided.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'My Account Name'
                publicIdAlias:
                    description: 'An alias for the public ID that you use internally to identify each one of your Child customer accounts. Use this instead of passing `X-PUBLIC-ID` in the header if you have been configured with ID aliases by your Nova Credit Account Manager.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'my-account-alias'
                consumerId:
                    description: 'The unique identifier of an existing Consumer. Use this as an alternative to providing applicant PII fields.'
                    type: string
                    format: uuid
                    minLength: 36
                    maxLength: 36
                    example: '987fcdeb-51a2-43d7-8f9e-123456789abc'
                applicantFirstName:
                    description: 'Applicant first name. Required when not using consumerId. Must be less than 255 characters and contain only alphabetical, unicode, dots, apostrophes and dashes. May not contain numbers.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'Raymond'
                applicantLastName:
                    description: 'Applicant last name. Required when not using consumerId. Must be less than 255 characters and contain only alphabetical, unicode, dots, apostrophes and dashes. May not contain numbers.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'Marshal'
                applicantEmail:
                    description: 'Applicant email. Required when not using consumerId.'
                    type: string
                    format: email
                    minLength: 1
                    maxLength: 100
                    example: 'raymond@email.com'
                applicantDateOfBirth:
                    description: "The applicant's date of birth in the format YYYY-MM-DD. Must be between 1 and 110 years old."
                    type: string
                    format: date
                    minLength: 10
                    maxLength: 10
                    example: '1995-10-01'
                applicantAddress:
                    description: 'The street address of the applicant.'
                    type: string
                    minLength: 1
                    maxLength: 100
                    example: '123 Main St'
                applicantCity:
                    description: 'The city where the applicant lives.'
                    type: string
                    minLength: 1
                    maxLength: 100
                    example: 'New York'
                applicantState:
                    description: 'The two letter US state or territory code where the applicant lives.'
                    type: string
                    minLength: 2
                    maxLength: 2
                    example: 'NY'
                applicantZipCode:
                    description: 'The US postal zip code where the applicant lives.'
                    type: string
                    pattern: '^\d{5}(-\d{4})?$'
                    minLength: 5
                    maxLength: 10
                    example: '10001'
                applicantPhone:
                    description: 'The phone number of the applicant.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: '+15555555555'
                applicantStatedAnnualIncome:
                    description: 'The annual income in dollars as stated by the applicant. Must be between 0 and 2147483647.'
                    type: integer
                    format: int32
                    minimum: 0
                    example: 75000
                applicantStatedEmployerName:
                    description: "The name of the applicant's current employer."
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'Acme Corp'
                externalId:
                    description: 'Unique identifier you can pass in for your own records.'
                    type: string
                    minLength: 1
                    maxLength: 64
                    example: '3f59e253-01a6-40e8-be40-d3a500d03e48'
                userArgs:
                    description: 'Additional information you can pass in for your own records.'
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'custom_id:3c2da600'

        ##### CONSUMERS #######
        ConsumerFields:
            type: object
            properties:
                firstName:
                    type: string
                    minLength: 1
                    maxLength: 255
                    description: 'The first name of the consumer. Must be less than 255 characters and contain only alphabetical, unicode, dots, apostrophes and dashes. May not contain numbers.'
                    example: 'Arthur'
                lastName:
                    type: string
                    minLength: 1
                    maxLength: 255
                    description: 'The last name of the consumer. Must be less than 255 characters and contain only alphabetical, unicode, dots, apostrophes and dashes. May not contain numbers.'
                    example: 'Cohen'
                email:
                    type: string
                    format: email
                    minLength: 1
                    maxLength: 100
                    description: 'The email address of the consumer.'
                    example: 'arthur@email.com'
                dob:
                    type: string
                    format: date
                    minLength: 10
                    maxLength: 10
                    description: "The consumer's date of birth in the format YYYY-MM-DD. Must be between 1 and 110 years old."
                    example: '1990-01-15'
                address:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'The street address of the consumer.'
                    example: '123 Main St'
                city:
                    type: string
                    minLength: 1
                    maxLength: 100
                    description: 'The city where the consumer lives.'
                    example: 'New York'
                state:
                    type: string
                    minLength: 2
                    maxLength: 2
                    description: 'The two letter US state or territory code where the consumer lives.'
                    example: 'NY'
                zip:
                    type: string
                    pattern: '^\d{5}(-\d{4})?$'
                    minLength: 5
                    maxLength: 10
                    description: 'The US postal zip code where the consumer lives.'
                    example: '10001'
                phone:
                    type: string
                    minLength: 1
                    maxLength: 255
                    description: 'The phone number of the consumer.'
                    example: '+15555555555'
                consumerExternalId:
                    type: string
                    minLength: 1
                    maxLength: 64
                    description: 'A unique internal identifier for your own records. Must be unique across all Consumers associated with your account and must not include any consumer PII.'
                    example: 'your-internal-id-123'
                statedAnnualIncome:
                    type: integer
                    format: int32
                    minimum: 0
                    description: 'The annual income in dollars as stated by the consumer. Must be between 0 and 2147483647.'
                    example: 75000
                statedEmployerName:
                    type: string
                    minLength: 1
                    maxLength: 255
                    description: "The name of the consumer's current employer."
                    example: 'Acme Corp'
                    deprecated: true
                statedEmployerNames:
                    type: array
                    description: "List of the consumer's current employer names. Mutually exclusive with statedEmployerName — if provided, statedEmployerName is cleared."
                    minItems: 1
                    maxItems: 6
                    items:
                        type: string
                        minLength: 1
                        maxLength: 255
                    example:
                        - 'Acme Corp'

        ConsumerCreateRequest:
            allOf:
                - $ref: '#/components/schemas/ConsumerFields'
            required:
                - firstName
                - lastName
                - email

        ConsumerUpdateRequest:
            allOf:
                - $ref: '#/components/schemas/ConsumerFields'

        ConsumerCreateResponse:
            type: object
            required:
                - consumerId
            properties:
                consumerId:
                    type: string
                    format: uuid
                    minLength: 36
                    maxLength: 36
                    description: 'The unique identifier for the created consumer.'
                    example: '987fcdeb-51a2-43d7-8f9e-123456789abc'

        ConsumerGetResponse:
            allOf:
                - $ref: '#/components/schemas/ConsumerFields'
            required:
                - consumerId
            properties:
                consumerId:
                    type: string
                    format: uuid
                    minLength: 36
                    maxLength: 36
                    description: 'The unique identifier for the consumer.'
                    example: '987fcdeb-51a2-43d7-8f9e-123456789abc'
                visits:
                    type: array
                    description: 'List of NovaConnect visits associated with this consumer. The array can have zero objects, and there is no upper bound.'
                    items:
                        type: object
                        properties:
                            publicToken:
                                type: string
                                format: uuid
                                minLength: 36
                                maxLength: 36
                                description: 'The unique identifier for the visit.'
                                example: '36128cc3-bde6-4026-8abd-4cbb790d82d2'

        ConsumerCreateBadRequestError:
            type: object
            properties:
                error:
                    type: string
                    minLength: 1
                    maxLength: 64
                    enum:
                        - MALFORMED_HEADERS
                        - MALFORMED_BODY
                        - DUPLICATE_CONSUMER_EXTERNAL_ID
                    example: 'MALFORMED_BODY'
                description:
                    type: string
                    minLength: 1
                    maxLength: 255

        ConsumerBadRequestError:
            type: object
            properties:
                error:
                    type: string
                    minLength: 1
                    maxLength: 64
                    enum:
                        - BAD_REQUEST
                        - MALFORMED_BODY
                        - DUPLICATE_CONSUMER_EXTERNAL_ID
                        - INVALID_CONSUMER_ID
                    example: 'INVALID_CONSUMER_ID'
                description:
                    type: string
                    minLength: 1
                    maxLength: 255

        BasicAuthForbiddenError:
            description: 'Credentials are not recognized. Returned by Basic Auth endpoints.'
            type: object
            properties:
                error:
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'UNAUTHORIZED'
                terminated:
                    $ref: '#/components/schemas/TerminatedType'
                errorDisplay:
                    type: string
                    minLength: 1
                    maxLength: 255

        InviteForbiddenError:
            description: 'Credentials are not recognized. terminated is always a string on this Basic Auth endpoint.'
            type: object
            properties:
                error:
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'UNAUTHORIZED'
                terminated:
                    $ref: '#/components/schemas/TerminatedBooleanType'

        InviteBadRequestError:
            description: 'Invalid request.'
            type: object
            properties:
                error:
                    type: string
                    minLength: 1
                    maxLength: 64
                    example: 'MALFORMED_HEADERS'
                description:
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'The productId provided is invalid'
                terminated:
                    $ref: '#/components/schemas/TerminatedType'

        ##### ERRORS #######
        TerminatedBooleanType:
            description: 'Boolean indicating whether process terminated. Always a string on this endpoint.'
            type: string
            minLength: 4
            maxLength: 5
            enum:
                - 'true'
                - 'false'

        TerminatedType:
            description: 'Indicates whether the process terminated. May be a boolean or a string depending on which layer produced the error.'
            oneOf:
                - type: boolean
                - type: string
                  minLength: 4
                  maxLength: 5

        ExpiredKeyError:
            description: 'Expired credentials'
            type: object
            properties:
                error:
                    type: string
                    minLength: 1
                    maxLength: 64
                    example: 'EXPIRED_SECRET_KEY'
                terminated:
                    $ref: '#/components/schemas/TerminatedType'

        ForbiddenError:
            description: 'Credentials are not recognized.'
            type: object
            properties:
                error:
                    type: string
                    minLength: 1
                    maxLength: 64
                    example: 'UNAUTHORIZED'
                terminated:
                    $ref: '#/components/schemas/TerminatedType'
                errorDisplay:
                    type: string
                    minLength: 1
                    maxLength: 255

        InitializationBadRequestError:
            description: 'Invalid request to the /initialization endpoint.'
            type: object
            properties:
                error:
                    type: string
                    minLength: 1
                    maxLength: 64
                    example: 'MALFORMED_BODY'
                description:
                    type: string
                    description: 'Human-readable description of the error.'
                    minLength: 1
                    maxLength: 255
                    example: 'prefill is missing from the JSON request body'
        BadRequestError:
            description: 'Invalid request.'
            type: object
            properties:
                error:
                    type: string
                    minLength: 1
                    maxLength: 64
                    example: 'MALFORMED_HEADERS'
                terminated:
                    $ref: '#/components/schemas/TerminatedType'
                errorDisplay:
                    type: string
                    minLength: 1
                    maxLength: 255
                    example: 'Additional details about the error'

        InvalidTokenError:
            description: 'Provided token is not valid for reasons other than expiration.'
            type: object
            properties:
                error:
                    type: string
                    minLength: 1
                    maxLength: 64
                    example: 'INVALID_TOKEN'
                terminated:
                    $ref: '#/components/schemas/TerminatedType'

        InternalError:
            description: 'Internal error has occurred.'
            type: object
            properties:
                error:
                    type: string
                    minLength: 1
                    maxLength: 64
                    example: 'INTERNAL_ERROR'
                terminated:
                    $ref: '#/components/schemas/TerminatedType'
        InitializationPrefill:
            type: object
            description: 'Optional prefill data to pre-populate the NovaConnect widget. Mutually exclusive with consumerId. firstName, lastName, and email are required. Either full address (address, city, state, zip) or dob must also be provided. Full address is recommended over dob as it is less sensitive.'
            required:
                - firstName
                - lastName
                - email
            properties:
                firstName:
                    type: string
                    description: 'First name. Must contain only alphabetical, unicode, dots, apostrophes and dashes.'
                    minLength: 1
                    maxLength: 255
                    example: Raymond
                lastName:
                    type: string
                    description: 'Last name. Must contain only alphabetical, unicode, dots, apostrophes and dashes.'
                    minLength: 1
                    maxLength: 255
                    example: Marshal
                email:
                    type: string
                    format: email
                    minLength: 3
                    maxLength: 100
                    example: raymond@email.com
                dob:
                    type: string
                    format: date
                    minLength: 10
                    maxLength: 10
                    example: '1990-01-15'
                address:
                    type: string
                    minLength: 1
                    maxLength: 100
                    example: '225 Valencia St'
                city:
                    type: string
                    minLength: 1
                    maxLength: 100
                    example: 'San Francisco'
                state:
                    type: string
                    minLength: 2
                    maxLength: 2
                    example: CA
                zip:
                    type: string
                    minLength: 5
                    maxLength: 10
                    example: '94105'
        InitializationRequest:
            type: object
            description: 'Plaintext initialization request body. Either prefill or consumerId must be provided, but not both.'
            required:
                - token
            properties:
                token:
                    type: string
                    description: 'Must be set to "JWT" to indicate that a token should be returned.'
                    enum:
                        - JWT
                    example: JWT
                prefill:
                    $ref: '#/components/schemas/InitializationPrefill'
                consumerId:
                    type: string
                    description: 'UUID of an existing Nova Credit consumer. Mutually exclusive with prefill.'
                    format: uuid
                    minLength: 36
                    maxLength: 36
                    example: 987fcdeb-51a2-43d7-8f9e-123456789abc
                externalId:
                    type: string
                    description: 'Your internal identifier for this applicant.'
                    minLength: 1
                    maxLength: 64
                    example: your-internal-id-123
                userArgs:
                    type: string
                    description: 'Custom string passed through to the report and webhook.'
                    minLength: 1
                    maxLength: 255
                    example: custom_id:3c2da600
        InitializationEncryptedRequest:
            type: object
            description: 'Encrypted initialization request body using JWE Compact Serialization. Mutually exclusive with all other body fields.'
            required:
                - encryptedValue
            properties:
                encryptedValue:
                    type: string
                    description: 'JWE Compact Serialization of the plaintext request body, encrypted with the public key from GET /jwkset.'
                    example: eyJhbGciOiJSU0EtT0FFUC0yNTYiLCJlbmMiOiJBMjU2R0NNIn0...
        InitializationResponse:
            type: object
            properties:
                token:
                    type: string
                    description: 'HS256 JWT for use in the NovaConnect widget.'
                    minLength: 250
                    maxLength: 300
                    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
                publicToken:
                    type: string
                    description: 'UUID public token for retrieving the Cash Atlas report.'
                    format: uuid
                    minLength: 36
                    maxLength: 36
                    example: e3f60d3a-8a22-4940-9d1e-50f4f9878503
                consumerId:
                    type: string
                    description: 'The consumer ID associated with this session. Reflects the value passed in the request, or one auto-created by Nova if none was provided.'
                    format: uuid
                    minLength: 36
                    maxLength: 36
                    example: f412af74-a2d4-4c6c-8fed-7275d55939b4
        JWKKey:
            type: object
            description: 'A JSON Web Key (JWK).'
            properties:
                kid:
                    type: string
                    description: 'Key ID.'
                    minLength: 1
                    maxLength: 64
                    example: payloadEncrRsa
                kty:
                    type: string
                    description: 'Key type (e.g. RSA, EC).'
                    minLength: 1
                    maxLength: 64
                    example: RSA
                alg:
                    type: string
                    description: 'Algorithm intended for use with this key.'
                    minLength: 1
                    maxLength: 64
                    example: RSA-OAEP-256
                use:
                    type: string
                    description: 'Intended use of the key. Current possible vaues are enc (encryption) and sig (signature verification).'
                    minLength: 1
                    maxLength: 64
                    example: enc
                n:
                    type: string
                    description: 'RSA modulus (base64url-encoded). Present for RSA keys.'
                    minLength: 1
                    maxLength: 2000
                    example: 7kZDkQB78iYrQOhW7BZrtrnUNbYQMuEwrLXtLLCmH4WJjPyccZuOAHQJIgS3qluXnJbVZKwF52P73nF3v7AB8L1MVqRp94t5QlA5ysHscvDa_lXjcN6DSREY66LzQkita-zU0de9_6v1DVfbjn7OiPA_gbQVKMM3vPzToYInz6RnSJTG1bLbcRM_4YBDEqxphAJmEywP-E4xCwGn05Sdw5trJquWKIKPLMK9XWRiWifqeS8v2dZg_pbLjg_zPNXy0BcIIrci2K1TbuEXoAGFbjbuFN7WQPkclcP9dP2jE1OEWxMzg5FoSQo6QKCBIz3lkkPhqg4MQz_VhHgQvX_KrmO_pIHebvkc_473yf5J7YUOq5ze97OH67JflVSh0aFk7k6Yd8dgQCQID_6LaQHFTitTZScy3Cyl0gD34ifo8DnAX-BrbqBP92makSH1VuYQ0ejbMpz-Ayln4h1nGX-85XL_rgWF4bIPYlP2hnZKNpAr_Fa7uICH5mzsilnFybUIgQjDZ2KhKYe1ayNDPf7lvdPUw1SWAqdnz0glKfOC7CHQtSkU7n8sSBUl8KA24fZggNydKt9-VEL6si-wcR8OJ2IUfe2Ut5VE339V-C-zTh-iVoujinBGpmP-iIyJzRTTmHHwhOy7yRFRO1wQkVz02QFYi8f-sF7Mntm3rzC8RwM
                e:
                    type: string
                    description: 'RSA public exponent (base64url-encoded). Present for RSA keys.'
                    minLength: 1
                    maxLength: 64
                    example: AQAB
        JWKSetResponse:
            type: object
            properties:
                keys:
                    type: array
                    description: 'Array of JSON Web Keys.'
                    items:
                        $ref: '#/components/schemas/JWKKey'
        WebhookBody:
            type: object
            description: 'The body of the webhook Nova Credit sends to your callback URL after a visit is completed.'
            required:
                - publicToken
                - reportType
                - eventType
                - status
                - eventId
                - eventCreatedTime
            properties:
                publicToken:
                    type: string
                    description: 'UUID public token identifying the report.'
                    format: uuid
                    minLength: 36
                    maxLength: 36
                    example: e3f60d3a-8a22-4940-9d1e-50f4f9878503
                reportType:
                    type: string
                    description: 'The type of Nova Credit report. For Cash Atlas V2 this will always be Cash Flow Underwriting.'
                    enum:
                        - Cash Flow Underwriting
                    minLength: 1
                    maxLength: 64
                    example: Cash Flow Underwriting
                novaReportRevision:
                    type: string
                    description: 'The revision number of the report. Only present for REGENERATED_VISIT event types.'
                    minLength: 1
                    maxLength: 10
                    example: '1'
                consumerId:
                    type: string
                    description: 'UUID of the Nova Credit consumer.'
                    format: uuid
                    minLength: 36
                    maxLength: 36
                    example: b281e335-9d19-4aa7-b559-e74d08a05cf4
                consumerExternalId:
                    type: string
                    description: 'External ID of the Nova Credit consumer.'
                    minLength: 1
                    maxLength: 64
                    example: 472cbdc9-cf31-4117-a095-e27e2db054e5
                publicId:
                    type: string
                    description: 'For resellers, the publicId of the subcustomer that requested the report. Only present for reseller-managed customers.'
                    minLength: 1
                    maxLength: 255
                    example: a84cd30a5e31b318f88ef2b8223b8a472585394763cb3dc594be4c654b4ba444
                publicIdAlias:
                    type: string
                    description: 'For resellers, the publicIdAlias of the subcustomer, if one has been set. Only present for reseller-managed customers.'
                    minLength: 1
                    maxLength: 255
                    example: alias
                externalId:
                    type: string
                    description: 'The external ID passed in at initialization or invite time. Only present if one was provided.'
                    minLength: 1
                    maxLength: 64
                    example: 25ad7063-fe76-437a-b4d8-3662ba4cc9c7
                eventType:
                    type: string
                    description: 'The type of event that triggered this webhook.'
                    enum:
                        - VISIT
                        - REGENERATED_VISIT
                    minLength: 1
                    maxLength: 64
                    example: VISIT
                status:
                    type: string
                    description: 'The status of the report.'
                    minLength: 1
                    maxLength: 64
                    example: SUCCESS
                substatus:
                    type: string
                    description: 'The sub-status of the report.'
                    minLength: 1
                    maxLength: 64
                    example: MFA_REQUIRED_ON_FETCH
                eventId:
                    type: string
                    description: 'UUID uniquely identifying this webhook event.'
                    format: uuid
                    minLength: 36
                    maxLength: 36
                    example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                eventCreatedTime:
                    type: string
                    description: 'ISO 8601 timestamp of when the event was created.'
                    format: date-time
                    example: '2024-01-13T11:07:46.51Z'
                userArgs:
                    type: string
                    description: 'Custom string passed through from initialization or invite.'
                    minLength: 1
                    maxLength: 255
                    example: custom_id:3c2da600
                history:
                    type: array
                    description: 'List of history items for this visit. Always present for VISIT eventTypes but not included for REGENERATED_VISIT eventTypes.'
                    items:
                        $ref: '#/components/schemas/WebhookHistoryItem'
        WebhookHistoryItem:
            type: object
            example:
                eventType: SUPPLIER
                status: PENDING
                companyCode: USA_FIN
                dateAttempted: '2024-01-13T10:47:46.51Z'
            properties:
                eventType:
                    type: string
                    description: 'The type of event. Will always be SUPPLIER for Cash Atlas V2. Note that this field differs from the top level WebhookBody.eventType.'
                    enum:
                        - SUPPLIER
                    minLength: 1
                    maxLength: 64
                    example: SUPPLIER
                status:
                    type: string
                    description: 'The status at the time of this history entry.'
                    minLength: 1
                    maxLength: 64
                    example: SUCCESS
                substatus:
                    type: string
                    description: 'The sub-status at the time of this history entry.'
                    minLength: 1
                    maxLength: 64
                    example: MFA_REQUIRED_ON_FETCH
                companyCode:
                    type: string
                    description: 'Data supplier for this history object.'
                    minLength: 1
                    maxLength: 64
                    example: USA_FIN
                dateAttempted:
                    type: string
                    description: 'ISO 8601 timestamp of when this history entry was recorded.'
                    format: date-time
                    example: '2024-01-13T11:07:46.51Z'
