openapi: 3.0.3
info:
  title: Mobile Check Cashing SDK — Add Customer Attributes
  version: '1'
  description: |
    Ancillary method for passing predictive customer data that
    accelerates Ingo's risk decisioning for high-value cardholders.
    Submit an array of name/value attributes covering the customer's
    history with you — tenure, transactions per month, direct deposit
    status, current balance, returned-check history, and so on.

    This endpoint is customer-scoped: it requires the `SessionId` header
    (from `/authenticate`) plus the customer's `customerId` — it does
    NOT require an OBO-scoped session. Because it only needs the
    `customerId` (from find/enroll), call it before `/authenticate-obo`
    in the flow. `CustomerId` must be the first object in the
    `customerAttributes` array.
servers:
  - url: https://check-cashing-uat.spykemobile.net
    description: UAT (Sandbox)
  - url: https://check-cashing.spykemobile.net
    description: Production
security:
  - OAuth2:
      - sdkapi
tags:
  - name: Customer Attributes
    description: Submit predictive risk attributes for a customer.
paths:
  /api/v1/partners/add-customer-attributes:
    post:
      tags:
        - Customer Attributes
      operationId: addCustomerAttributes
      summary: Submit predictive customer attributes
      description: |
        Adds or updates predictive attributes for the customer.
        Attributes feed Ingo's risk algorithms to:

        - Accelerate underwriting approvals for first-time users
        - Increase speed of transaction finalization
        - Improve approval rates based on relationship factors

        See the schema description for the recognized attribute names.
      parameters:
        - $ref: '#/components/parameters/SessionIdHeader'
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddCustomerAttributesRequest'
            example:
              customerAttributes:
                - name: CustomerId
                  value: 87e59d88-c15c-4513-87d0-6bdb49c4b29e
                - name: SSN
                  value: '111224444'
                - name: DirectDeposit
                  value: 'True'
                - name: Tenure
                  value: '18'
                - name: TransactionsPerMonth
                  value: '4'
                - name: NumberOfCards
                  value: '2'
                - name: CurrentBalance
                  value: '3456.76'
                - name: AverageMonthlyLoadAmount
                  value: '6114.25'
      responses:
        '200':
          description: Attributes accepted. Empty response body.
        '400':
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
              example:
                errors: {}
                type: https://tools.ietf.org/html/rfc7231#section-6.5.1
                title: Bad Request
                status: 400
                detail: One or more validation errors occurred.
                instance: /api/v1/partners/add-customer-attributes
                validationErrors:
                  - key: command.CustomerAttributes[7].Value
                    message: The Value field is required.
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.spykemobile.net/connect/token
          scopes:
            sdkapi: Mobile Check Cashing SDK partner methods
  parameters:
    SessionIdHeader:
      name: SessionId
      in: header
      required: true
      schema:
        type: string
    DeviceIdHeader:
      name: DeviceId
      in: header
      required: true
      schema:
        type: string
  schemas:
    AddCustomerAttributesRequest:
      type: object
      required:
        - customerAttributes
      properties:
        customerAttributes:
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/CustomerAttribute'
    CustomerAttribute:
      type: object
      required:
        - name
        - value
      description: >
        Recognized attribute names and their semantics:


        | Name | Required | Description |

        |---|---|---|

        | `CustomerId` | Required | Ingo-assigned customer GUID |

        | `SSN` | Required | 9-digit SSN/ITIN (no spaces or dashes) |

        | `NumberOfCards` | Optional | Number of cards registered |

        | `Tenure` | Optional | Length of customer relationship in months (use
        the longest-tenured card if multiple) |

        | `DirectDeposit` | Optional | `True`/`False` — currently enrolled for
        direct deposit |

        | `CurrentBalance` | Optional | Current card balance, format `DDDDD.CC`
        (average if multiple cards) |

        | `AverageMonthlyLoadAmount` | Optional | Average monthly load amount,
        format `DDDDD.CC` |

        | `TransactionsPerMonth` | Optional | Numeric transactions per month |

        | `CardIssueDate` | Optional | `MM-DD-YYYY` |

        | `NumberOfChecksCashed` | Optional | Checks cashed in last 90 days |

        | `NumberOfChecksReturned` | Optional | Checks returned in last 90 days
        |

        | `BalanceOnReturnedChecks` | Optional | Outstanding debt on returned
        checks, format `DDDDD.CC` |

        | `AverageCheckCashedAmt` | Optional | Average cashed-check amount last
        90 days, format `DDDDD.CC` |

        | `DebitActive` | Optional | `True`/`False` — debit capabilities enabled
        |

        | `LastDebitPurchaseDate` | Optional | `MM-DD-YYYY` |

        | `TotalNumberOfCustomers` | Optional | Total active customers |
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Attribute name from the table above.
        value:
          type: string
          minLength: 1
          maxLength: 200
          description: Attribute value (always serialized as a string).
    ValidationProblemDetails:
      type: object
      required:
        - type
        - title
        - status
      properties:
        errors:
          type: object
          additionalProperties: true
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
        validationErrors:
          type: array
          items:
            type: object
            required:
              - key
              - message
            properties:
              key:
                type: string
              message:
                type: string