openapi: 3.1.0
info:
  title: Referral API
  description: |-
    RAI Partners Referral API.

    ⚠️ **API version 1.0.8 is scheduled for deprecation on 2027-07-01.** 

    It will continue to function until then; please migrate to 2.x.x.
  license:
    name: Proprietary — © RAI Partners Inc. All rights reserved.
    url: https://www.raipartners.com
  version: 1.0.8
servers:
  - url: https://api.raipartners.com/referral
    description: Production
  - url: https://sandbox.raipartners.com/referral
    description: Sandbox
tags:
  - name: Referral
    description: Referral functions
  - name: Authentication
    description: Authentication functions
paths:
  /application/{product-id}:
    post:
      tags:
        - Referral
      summary: Create an application
      description: Create an application with the provided data
      operationId: createApplication
      parameters:
        - name: product-id
          in: path
          description: The product id provided by RAI.
          required: true
          schema:
            type: string
        - name: API-Version
          in: header
          schema:
            type: string
            enum:
              - 1.0.8
      requestBody:
        description: The information to use for the application.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Application'
        required: true
      responses:
        '200':
          description: The application was handled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicationReply'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Generic invalid data:
                  description: Generic invalid data
                  value:
                    type: >-
                      urn:raipartners:api:referral:errors:validation:invalid-data
                    title: Bad Request
                    status: 400
                    detail: One or more fields are invalid.
                Generic missing data:
                  description: Generic missing data
                  value:
                    type: >-
                      urn:raipartners:api:referral:errors:validation:missing-data
                    title: Bad Request
                    status: 400
                    detail: One or more required fields are missing.
        '404':
          description: not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Not found:
                  description: Not found
                  value:
                    type: urn:raipartners:api:referral:errors:not-found
                    title: Not Found
                    status: 404
                    detail: Resource not found.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Internal server error:
                  description: Internal server error
                  value:
                    type: urn:raipartners:api:referral:errors:internal
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred.
        '503':
          description: Service unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Service unavailable:
                  description: Service unavailable
                  value:
                    type: urn:raipartners:api:referral:errors:internal
                    title: Service unavailable Error
                    status: 503
                    detail: Service is unavailable.
      security:
        - bearer-jwt: []
  /auth/client-secret/rotation:
    post:
      tags:
        - Authentication
      summary: Rotate the client secret
      description: Rotate and returns the client secret
      operationId: rotateClientSecret
      parameters:
        - name: API-Version
          in: header
          schema:
            type: string
            enum:
              - 1.0.8
      responses:
        '200':
          description: The rotated secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RotatedSecret'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Generic invalid data:
                  description: Generic invalid data
                  value:
                    type: >-
                      urn:raipartners:api:referral:errors:validation:invalid-data
                    title: Bad Request
                    status: 400
                    detail: One or more fields are invalid.
                Generic missing data:
                  description: Generic missing data
                  value:
                    type: >-
                      urn:raipartners:api:referral:errors:validation:missing-data
                    title: Bad Request
                    status: 400
                    detail: One or more required fields are missing.
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Unauthorized:
                  description: Unauthorized
                  value:
                    type: >-
                      urn:raipartners:api:referral:errors:authorization:unauthorized
                    title: Unauthorized
                    status: 401
                    detail: You are not authorized to perform this action.
        '403':
          description: Forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Forbidden:
                  description: Forbidden
                  value:
                    type: >-
                      urn:raipartners:api:referral:errors:authorization:forbidden
                    title: Forbidden
                    status: 403
                    detail: You are forbidden to perform this action.
        '404':
          description: not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Not found:
                  description: Not found
                  value:
                    type: urn:raipartners:api:referral:errors:not-found
                    title: Not Found
                    status: 404
                    detail: Resource not found.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Internal server error:
                  description: Internal server error
                  value:
                    type: urn:raipartners:api:referral:errors:internal
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred.
        '503':
          description: Service unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Service unavailable:
                  description: Service unavailable
                  value:
                    type: urn:raipartners:api:referral:errors:internal
                    title: Service unavailable Error
                    status: 503
                    detail: Service is unavailable.
      security:
        - bearer-jwt: []
  /auth/token:
    post:
      tags:
        - Authentication
      summary: Authenticate client
      description: Authenticate a client and retrieve the JWT token
      operationId: authenticateClient
      parameters:
        - name: API-Version
          in: header
          schema:
            type: string
            enum:
              - 1.0.8
      requestBody:
        description: The client credentials.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientTokenRequest'
        required: true
      responses:
        '200':
          description: The JWT token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTClientTokenResponse'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Generic invalid data:
                  description: Generic invalid data
                  value:
                    type: >-
                      urn:raipartners:api:referral:errors:validation:invalid-data
                    title: Bad Request
                    status: 400
                    detail: One or more fields are invalid.
                Generic missing data:
                  description: Generic missing data
                  value:
                    type: >-
                      urn:raipartners:api:referral:errors:validation:missing-data
                    title: Bad Request
                    status: 400
                    detail: One or more required fields are missing.
        '404':
          description: not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Not found:
                  description: Not found
                  value:
                    type: urn:raipartners:api:referral:errors:not-found
                    title: Not Found
                    status: 404
                    detail: Resource not found.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Internal server error:
                  description: Internal server error
                  value:
                    type: urn:raipartners:api:referral:errors:internal
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred.
        '503':
          description: Service unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Service unavailable:
                  description: Service unavailable
                  value:
                    type: urn:raipartners:api:referral:errors:internal
                    title: Service unavailable Error
                    status: 503
                    detail: Service is unavailable.
      security: []
  /spousal-notification-states:
    get:
      tags:
        - Referral
      summary: Get spousal notification states
      description: Retrieve the list of US States requiring spousal notifications
      operationId: getSpousalNotificationStates
      parameters:
        - name: API-Version
          in: header
          schema:
            type: string
            enum:
              - 1.0.8
      responses:
        '200':
          description: The list of states in 2 characters abbreviated form.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  example: WI
                  pattern: ^[A-Z]{2}$
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Generic invalid data:
                  description: Generic invalid data
                  value:
                    type: >-
                      urn:raipartners:api:referral:errors:validation:invalid-data
                    title: Bad Request
                    status: 400
                    detail: One or more fields are invalid.
                Generic missing data:
                  description: Generic missing data
                  value:
                    type: >-
                      urn:raipartners:api:referral:errors:validation:missing-data
                    title: Bad Request
                    status: 400
                    detail: One or more required fields are missing.
        '404':
          description: not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Not found:
                  description: Not found
                  value:
                    type: urn:raipartners:api:referral:errors:not-found
                    title: Not Found
                    status: 404
                    detail: Resource not found.
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Internal server error:
                  description: Internal server error
                  value:
                    type: urn:raipartners:api:referral:errors:internal
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred.
        '503':
          description: Service unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetail'
              examples:
                Service unavailable:
                  description: Service unavailable
                  value:
                    type: urn:raipartners:api:referral:errors:internal
                    title: Service unavailable Error
                    status: 503
                    detail: Service is unavailable.
      security:
        - bearer-jwt: []
components:
  schemas:
    Applicant:
      type: object
      properties:
        identity:
          $ref: '#/components/schemas/Person'
          description: The person applying.
        email:
          type: string
          description: The person's email.
          example: myemail@email.com
        phoneNumber:
          type: string
          description: 10 digits phone number.
          example: '1234567890'
          pattern: \d{10}
        address:
          $ref: '#/components/schemas/Address'
          description: The person's address.
        income:
          $ref: '#/components/schemas/Income'
          description: The applicant's income information.
        expenses:
          $ref: '#/components/schemas/Expenses'
          description: The applicant's expense information.
        maritalStatus:
          type:
            - string
            - 'null'
          default: NotMarried
          description: The applicant's optional marital status.
          enum:
            - Married
            - NotMarried
          example: NotMarried
      required:
        - address
        - email
        - expenses
        - identity
        - income
        - phoneNumber
    Application:
      type: object
      properties:
        applicant:
          $ref: '#/components/schemas/Applicant'
          description: The information of the person applying.
        spouse:
          oneOf:
            - $ref: '#/components/schemas/SpouseInformation'
            - type: 'null'
        consents:
          $ref: '#/components/schemas/Consents'
          description: The applicant's various consents.
        metadata:
          oneOf:
            - $ref: '#/components/schemas/Metadata'
            - type: 'null'
      required:
        - applicant
        - consents
    ClearSSN:
      description: 9 digits social security number.
      example: 123456789
      pattern: \d{9}
    Name:
      type: object
      properties:
        first:
          type: string
          example: John
          pattern: ^(?! )(?![ '.-])[\w\s./'-]{1,29}(?<! )(?<!-)$
        last:
          type: string
          example: Smith
          pattern: ^(?! )(?![ '.-])[\w\s./'-]{1,29}(?<! )(?<!-)$
        middle:
          type:
            - string
            - 'null'
          example: James
          pattern: ^(?! )(?![ '.-])[\w\s./'-]{1,29}(?<! )(?<!-)$
      required:
        - first
        - last
    Person:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/Name'
          description: The person's name.
        birthDate:
          type: string
          format: date
          description: The person's date of birth.
          example: '2000-01-31'
        socialSecurityNumber:
          type: string
          description: Either a clear 9-digit SSN or an encrypted string
          oneOf:
            - $ref: '#/components/schemas/ClearSSN'
            - type: string
              description: >-
                Encrypted social security number if you requested Encrypted SSN
                support.
              example: gAAAAABkX...
      required:
        - birthDate
        - name
        - socialSecurityNumber
    Address:
      type: object
      properties:
        line1:
          type: string
          description: The first line.
          example: 1 Main St
          pattern: ^(?=.*\S).{1,26}$
        line2:
          type:
            - string
            - 'null'
          description: The optional second line.
          example: Apt 35
          pattern: ^(?:[a-zA-Z0-9\s\-.\/,#'']{0,26}|)$
        city:
          type: string
          description: The city name.
          example: Dallas
          pattern: \b[A-Za-z0-9\- ]{2,18}\b
        state:
          type: string
          description: The state abbreviation.
          example: TX
          pattern: ^[A-Z]{2}$
        zipCode:
          type: string
          description: The 5 digit zip code.
          example: '75000'
          pattern: ^(\d{5}(-\d{4})?)|(\d{9})$
      required:
        - city
        - line1
        - state
        - zipCode
    Consents:
      type: object
      properties:
        contact:
          $ref: '#/components/schemas/ContactPreferences'
          description: Contact consents.
        shareDataWithFI:
          type: boolean
          description: Consent to share data with the financial institution.
          example: true
        softPull:
          type: boolean
          description: Consent to perform a soft-pull from the credit bureau.
          example: true
      required:
        - contact
        - shareDataWithFI
        - softPull
    ContactPreferences:
      type: object
      properties:
        allowEmailContact:
          type: boolean
          description: Consent to contact via email.
          example: true
        allowPhoneContact:
          type: boolean
          description: Consent to contact via phone.
          example: true
        allowSmsContact:
          type: boolean
          description: Consent to contact via SMS.
          example: true
      required:
        - allowEmailContact
        - allowPhoneContact
        - allowSmsContact
    Expenses:
      type: object
      properties:
        monthlyHousing:
          type: integer
          format: int32
          description: The monthly housing expense (in whole US Dollar).
          example: 1000
      required:
        - monthlyHousing
    Income:
      type: object
      properties:
        annualIncome:
          type: integer
          format: int32
          description: The annual income (in whole US Dollar).
          example: 30000
          minimum: 100
        source:
          type: string
          description: The income source.
          enum:
            - Employment
            - Inheritance
            - Trust
            - Investment
            - Retirement
            - SocialSecurity
            - Unemployment
            - Other
          example: Employment
      required:
        - annualIncome
        - source
    Metadata:
      type: object
      properties:
        membershipType:
          type:
            - string
            - 'null'
          description: The membership type of the applicant.
          enum:
            - Member
            - NonMember
          example: NonMember
        referralChannel:
          type:
            - string
            - 'null'
          description: The referral channel through which the applicant was referred.
          enum:
            - Web
            - Branch
            - Phone
            - Other
          example: Branch
        creditInquiry:
          type:
            - string
            - 'null'
          description: The credit inquiry type for the applicant.
          enum:
            - Soft
            - Hard
          example: Soft
    SpouseInformation:
      type: object
      properties:
        name:
          $ref: '#/components/schemas/Name'
          description: The person's name.
        email:
          type: string
          description: The person's email.
          example: myemail@email.com
        address:
          $ref: '#/components/schemas/Address'
          description: The person's address.
      required:
        - address
        - email
        - name
    ApplicationReply:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The application id.
          example: 2bb04ce6-daeb-422b-b8fd-686aa09e2c88
        url:
          type: string
          format: uri
          description: The application url to redirect to.
          example: >-
            https://apply.groundworkcard.com/app/wizard/2bb04ce6-daeb-422b-b8fd-686aa09e2c88
        status:
          type: string
          description: The application status.
          enum:
            - Pending
            - Approved
            - Declined
          example: Pending
      required:
        - id
        - status
        - url
    ProblemDetail:
      type: object
      properties:
        type:
          type: string
          format: uri
        title:
          type: string
        status:
          type: integer
          format: int32
        detail:
          type: string
        instance:
          type: string
          format: uri
        properties:
          type: object
          additionalProperties: {}
    RotatedSecret:
      type: object
      properties:
        secret:
          type: string
      required:
        - secret
    ClientTokenRequest:
      type: object
      description: A client token request payload
      properties:
        client_id:
          type: string
          description: The client ID to use for authentication
          example: my-client-id
        client_secret:
          type: string
          description: The client secret to use for authentication
          example: my-super-auth-secret
      required:
        - client_id
        - client_secret
    JWTClientTokenResponse:
      type: object
      properties:
        scope:
          type: string
          description: The token scope as a space delimited set of values.
          example: read:user write:user
        refresh_expires_in:
          type: integer
          format: int32
          description: The refresh token expiry in seconds.
          example: 300
        access_token:
          type: string
          description: The JWT token.
          example: eyo.....
        expires_in:
          type: integer
          format: int32
          description: The token expiry in seconds.
          example: 300
        token_type:
          type: string
          description: The token type.
          example: Bearer
        not-before-policy:
          type: integer
          format: int32
          description: The not before policy in seconds.
          example: 0
      required:
        - access_token
        - expires_in
        - scope
        - token_type
  securitySchemes:
    bearer-jwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
