openapi: 3.0.3
info:
  title: Ingo Check Maker Alert API
  version: '1'
  description: |
    Network-wide intelligence about a check maker (the entity that issues
    the check). Submit an ABA + account number; receive a risk score,
    first/last seen dates across the Ingo network, the most-common check
    type associated with that maker, and a flag indicating whether the
    maker has had a returned check in the last seven days. Check Maker
    Alert is a data service — the client retains the underwriting
    decision.

    **Score interpretation.** Scores range from `0` to `1000`. Lower
    scores indicate higher risk; higher scores indicate lower risk
    (per the published sandbox test data). Use thresholds tuned to your
    own check decisioning model.

    **Authentication.** OAuth 2.0 client credentials grant. Production
    token URL: `https://auth.ingo.money/connect/token`. UAT token URL:
    `https://auth-uat.ingo.money/connect/token`. Required scope:
    `https://apis.ingo.money/auth/insights/check-maker-score`. Access
    tokens are valid for 3600 seconds — cache and reuse the token
    across calls.

    **Connectivity.** TLS 1.2 minimum. Client IPs must be on the
    pre-provisioned allowlist. Client credentials are provisioned by
    Ingo Client Services via PGP-encrypted file.

    **Versioning.** Current API version: `1`. Specify via `apiVersion`
    request header or query string. Defaults to `1` if omitted.

    **Error handling.** All non-success responses follow RFC 7807
    Problem Details. Record `traceId` on failed requests for support
    escalation.
servers:
  - url: https://insights-uat.ingo.money
    description: UAT (Sandbox)
  - url: https://insights.ingo.money
    description: Production
security:
  - OAuth2:
      - https://apis.ingo.money/auth/insights/check-maker-score
tags:
  - name: Check Maker Scoring
    description: Score a check maker by ABA and account number.
paths:
  /check-maker/score:
    post:
      tags:
        - Check Maker Scoring
      operationId: scoreCheckMaker
      summary: Score a check maker
      description: |
        Submit the ABA routing number and account number from a check.
        Returns a numeric risk score, the earliest and most recent dates
        the maker has been seen on the Ingo network, the predominant
        check type associated with this maker, and whether the maker
        has had a returned check in the last seven days.
      parameters:
        - name: apiVersion
          in: header
          required: false
          schema:
            type: string
            default: '1'
          description: |
            API version. Current version is `1`. May also be supplied as
            a query string parameter of the same name.
        - name: apiVersion
          in: query
          required: false
          schema:
            type: string
          description: |
            Alternative to the `apiVersion` header. Same semantics. If
            both the header and query parameter are supplied with
            different values, the API returns 400 AmbiguousApiVersion.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckMakerScoreRequest'
            example:
              aba: '123456789'
              accountNumber: '1002345678'
              correlationData:
                - attributeName: AttributeName1
                  attributeValue: AttributeValue1
                - attributeName: AttributeName2
                  attributeValue: AttributeValue2
      responses:
        '200':
          description: Check maker scored.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckMakerScoreResponse'
              example:
                score: 299
                firstSeenOn: 12-11-2020
                lastSeenOn: 06-24-2021
                checkType: payroll--printed
                hasReturnsInTheLastSevenDays: false
        '400':
          description: |
            Validation, versioning, or other client-side error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              examples:
                inputValidationError:
                  summary: Field validation failure
                  value:
                    type: https://tools.ietf.org/html/rfc7231#section-6.5.1
                    title: InputValidationError
                    status: 400
                    detail: See the errors field for details.
                    instance: /check-maker/score
                    traceId: '|bad4a210-4b51729b279dd00f.'
                    errors:
                      Aba:
                        - '''ABA'' must not be empty.'
                unsupportedApiVersion:
                  summary: Unsupported API version
                  value:
                    type: https://tools.ietf.org/html/rfc7231#section-6.5.1
                    title: UnsupportedApiVersion
                    status: 400
                    detail: >-
                      The HTTP resource that matches the request URI does not
                      support the API version '2'.
                    traceId: '|bad4a211-4b51729b279dd00f.'
                ambiguousApiVersion:
                  summary: Conflicting versions in header and query string
                  value:
                    type: https://tools.ietf.org/html/rfc7231#section-6.5.1
                    title: AmbiguousApiVersion
                    status: 400
                    detail: >-
                      The following API versions were requested: 1, 2. At most,
                      only a single API version may be specified.
                    traceId: '|31f77797-4a8da50f4fd3a851.'
        '401':
          description: Authorization failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://tools.ietf.org/html/rfc7235#section-3.1
                title: Unauthorized
                status: 401
                detail: Authorization failure.
                instance: /check-maker/score
                traceId: '|b56c1133-4c83cf831979499e.'
        '404':
          description: Resource not found at the requested URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://tools.ietf.org/html/rfc7231#section-6.5.4
                title: ResourceNotFound
                status: 404
                detail: Resource '/resource-not-located' not found.
                instance: /resource-not-located
                traceId: '|ddcf5087-4b680597207c67c5.'
        '500':
          description: >-
            Unexpected server error. Contact Ingo Client Services with the
            `traceId`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://tools.ietf.org/html/rfc7231#section-6.6.1
                title: InternalServerError.
                status: 500
                detail: Please contact Ingo money client services.
                instance: /check-maker/score
                traceId: '|c1ecee92-4f4cec828884a904.'
                errors: {}
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: |
        OAuth 2.0 client credentials grant. Production token URL is
        defined below. For UAT, use
        `https://auth-uat.ingo.money/connect/token` instead. Client
        credentials are provisioned by Ingo Client Services via
        PGP-encrypted file. Tokens are valid for 3600 seconds.
      flows:
        clientCredentials:
          tokenUrl: https://auth.ingo.money/connect/token
          scopes:
            https://apis.ingo.money/auth/insights/check-maker-score: Check Maker scoring
  schemas:
    CheckMakerScoreRequest:
      type: object
      required:
        - aba
        - accountNumber
      properties:
        aba:
          type: string
          maxLength: 10
          description: The check ABA routing number.
        accountNumber:
          type: string
          maxLength: 25
          description: The check account number.
        correlationData:
          type: array
          items:
            $ref: '#/components/schemas/CorrelationAttribute'
          description: Optional client-supplied correlation attributes.
    CorrelationAttribute:
      type: object
      required:
        - attributeName
        - attributeValue
      properties:
        attributeName:
          type: string
          maxLength: 75
        attributeValue:
          type: string
          maxLength: 75
    CheckMakerScoreResponse:
      type: object
      required:
        - score
        - firstSeenOn
        - lastSeenOn
        - checkType
        - hasReturnsInTheLastSevenDays
      properties:
        score:
          type: integer
          minimum: 0
          maximum: 1000
          description: |
            Risk score in the range `0`–`1000`. Lower scores indicate
            higher risk; higher scores indicate lower risk. Use
            thresholds tuned to your own decisioning model.
        firstSeenOn:
          type: string
          description: |
            Earliest date this maker (ABA + account number) was observed
            on the Ingo network. `MM-dd-yyyy` or `MM/dd/yyyy` format.
        lastSeenOn:
          type: string
          description: |
            Most recent date this maker was observed on the Ingo
            network. `MM-dd-yyyy` or `MM/dd/yyyy` format.
        checkType:
          type: string
          description: |
            Predominant check type associated with this maker.
          enum:
            - cashiers--official
            - govt--recurring
            - govt--other
            - govt--us-treasury
            - stimulus
            - insurance-attorney
            - loan
            - money-order
            - ohio-cso-loan
            - payroll--handwritten
            - payroll--printed
            - rac-check
            - tax-refund--other
            - tax-refund--us-treasury
            - two-party
            - two-party--business
            - other
        hasReturnsInTheLastSevenDays:
          type: boolean
          description: |
            Whether this maker has had at least one returned check
            within the last seven days across the Ingo network.
    ProblemDetails:
      type: object
      description: |
        RFC 7807 Problem Details. All non-success responses use this
        envelope.
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
        traceId:
          type: string
          description: |
            Tracing identifier. Record this value on failed requests for
            support escalation.
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: |
            Field-level validation error map (populated on 400
            InputValidationError). Keys are field names; values are
            arrays of error messages.