openapi: 3.0.3
info:
  title: Mobile Check Cashing SDK — Find Customer
  version: '1'
  description: |
    Look up an existing customer in the Ingo system by SSN/ITIN and
    date of birth. Use as the first step after `/authenticate` to
    determine whether a customer is already enrolled. If the customer
    is not found, follow up with `POST /enroll-customer`. If found,
    use the returned `customerId` with `POST /authenticate-obo` to
    bind the partner session to the customer.

    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. The OBO call
    (`/authenticate-obo`) is not required to invoke `find-customer`
    itself, but is required before any customer-scoped endpoint after
    that.
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/find-customer:
    post:
      tags:
        - Customer
      operationId: findCustomer
      summary: Look up an existing customer
      description: |
        Returns the `customerId` for an existing customer identified by
        SSN + date of birth. If the customer is not enrolled, returns
        HTTP 422 with `errorCode: CUSTOMER_NOT_FOUND` — call
        `POST /enroll-customer` to create the customer.
      parameters:
        - $ref: '#/components/parameters/SessionIdHeader'
        - $ref: '#/components/parameters/DeviceIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FindCustomerRequest'
            example:
              ssn: '123456789'
              dateOfBirth: 05/31/1988
      responses:
        '200':
          description: Customer found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindCustomerResponse'
              example:
                customerId: 5cd26e67-66b1-4f12-b9f4-963ce27a03ac
        '422':
          description: Customer not found. Enroll via `/enroll-customer`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
              example:
                type: https://tools.ietf.org/html/rfc4918#section-11.2
                title: Customer Not Found
                status: 422
                detail: >-
                  We're sorry, this customer was not found. Please check SSN and
                  DOB and try again. (A172)
                instance: /api/v1/partners/find-customer
                errorCode: CUSTOMER_NOT_FOUND
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:
    FindCustomerRequest:
      type: object
      required:
        - ssn
        - dateOfBirth
      properties:
        ssn:
          type: string
          minLength: 9
          maxLength: 9
          pattern: ^[0-9]{9}$
          description: |
            9-digit SSN or ITIN, unformatted (e.g., `123456789`).
        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`.
    FindCustomerResponse:
      type: object
      required:
        - customerId
      properties:
        customerId:
          type: string
          format: uuid
          description: |
            Ingo-assigned customer identifier (GUID). Pass to
            `/authenticate-obo` to bind the partner session to this
            customer.
    ProblemDetails:
      type: object
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
        errorCode:
          type: string