openapi: 3.0.3
info:
  title: Mobile Check Cashing SDK — Enroll Customer
  version: '1'
  description: |
    Enroll a new customer in the Ingo system. Before enrolling, the
    endpoint checks whether the SSN or email is already in use; if so,
    returns a corresponding error. On success, returns the
    Ingo-assigned `customerId` to pass into `POST /authenticate-obo`.

    Typical call sequence: `/authenticate` → `/find-customer` →
    (if 422 CUSTOMER_NOT_FOUND) → `/enroll-customer` →
    `/authenticate-obo`.

    This endpoint requires an active SDK partner session — call
    `POST /api/v1/partners/authenticate` first to obtain the
    `SessionId` value passed in the request header.
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
    description: Customer lifecycle endpoints.
paths:
  /api/v1/partners/enroll-customer:
    post:
      tags:
        - Customer
      operationId: enrollCustomer
      summary: Enroll a new customer
      description: |
        Creates a new customer record. Returns 400 if the SSN or email
        already exists, or if any required field fails validation.
        On success, returns `customerId` to pass into
        `/authenticate-obo`.
      parameters:
        - $ref: '#/components/parameters/SessionIdHeader'
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrollCustomerRequest'
            example:
              email: 5QY8A9Pr7b@gmail.com
              ssn: '684832266'
              firstName: Roger
              lastName: Rabbit
              middleInitial: R
              title: Mr.
              suffix: ''
              mobileNumber: '6153456789'
              homeNumber: '6153456565'
              addressLine1: 660 Bakers Bridge Lane
              addressLine2: Suite 100
              city: Franklin
              state: TN
              zip: '37067'
              dateOfBirth: 1978-09-11T00:00:00.000Z
              allowTexts: true
      responses:
        '200':
          description: Customer enrolled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrollCustomerResponse'
              example:
                customerId: 333554bf-b273-4d6e-b4f8-d319a1929608
        '400':
          description: |
            Validation error — typically a duplicate SSN/email or a
            malformed field.
          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/enroll-customer
                validationErrors:
                  - key: command.Gender
                    message: Gender cannot exceed 1 character
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
      description: Session identifier from `POST /authenticate`.
    DeviceIdHeader:
      name: DeviceId
      in: header
      required: true
      schema:
        type: string
      description: iovation BlackBox device identifier.
  schemas:
    EnrollCustomerRequest:
      type: object
      required:
        - email
        - ssn
        - firstName
        - lastName
        - mobileNumber
        - addressLine1
        - addressLine2
        - city
        - state
        - zip
        - dateOfBirth
        - allowTexts
      properties:
        email:
          type: string
          format: email
          minLength: 1
          maxLength: 100
          description: |
            Customer's email address. Must contain `@`. Dev-center
            field table lists this as `emailAddress`; the Postman
            collection and request example use `email` — the latter
            is what the live service accepts.
        ssn:
          type: string
          minLength: 1
          maxLength: 9
          pattern: ^[0-9]{1,9}$
          description: |
            9-digit SSN or ITIN, unformatted (no spaces, no dashes).
        firstName:
          type: string
          minLength: 1
          maxLength: 50
        lastName:
          type: string
          minLength: 1
          maxLength: 50
        middleInitial:
          type: string
          minLength: 0
          maxLength: 1
        title:
          type: string
          maxLength: 10
          description: Honorific (Mr, Mrs, etc.).
        suffix:
          type: string
          maxLength: 10
          description: Suffix (Jr, Sr, etc.).
        mobileNumber:
          type: string
          maxLength: 10
          pattern: ^[0-9]{10}$
          description: 10-digit mobile number, no formatting characters.
        homeNumber:
          type: string
          maxLength: 10
          pattern: ^[0-9]{10}$
        addressLine1:
          type: string
          minLength: 1
          maxLength: 50
        addressLine2:
          type: string
          minLength: 1
          maxLength: 50
        city:
          type: string
          minLength: 1
          maxLength: 50
        state:
          type: string
          minLength: 1
          maxLength: 2
          description: Two-character US state code.
        zip:
          type: string
          minLength: 5
          maxLength: 5
          pattern: ^[0-9]{5}$
        dateOfBirth:
          type: string
          minLength: 10
          maxLength: 10
          description: |
            Customer's date of birth. Accepted formats: `MM/DD/YYYY`,
            `MM-DD-YYYY`, `YYYY/MM/DD`, or `YYYY-MM-DD`.
        countryOfOrigin:
          type: string
          description: Country of origin for optional OFAC checking.
        gender:
          type: string
          maxLength: 1
          enum:
            - M
            - F
        allowTexts:
          type: boolean
          description: |
            Whether the user accepts text messages. (The system does
            not currently communicate via text.)
        referrerCode:
          type: string
          maxLength: 50
    EnrollCustomerResponse:
      type: object
      required:
        - customerId
      properties:
        customerId:
          type: string
          format: uuid
          description: |
            Ingo-assigned customer identifier (GUID). Pass to
            `/authenticate-obo`. Note: dev-center sample shows
            `CustomerId` capitalized; field name on the wire is
            lowercase `customerId`.
    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