openapi: 3.1.0
info:
  title: Highline API
  description: |
    Highline is a payment solution enabling direct paycheck deductions
    (pay-by-paycheck). This OpenAPI definition is generated best-effort
    from public docs at https://docs.highline.co/.
  version: "1.0.0"
  contact:
    name: Highline
    url: https://docs.highline.co/
servers:
  - url: https://api.highline.co
    description: Production
  - url: https://api.sandbox.highline.co
    description: Sandbox
security:
  - bearerAuth: []
tags:
  - name: Auth
  - name: Users
  - name: Companies
  - name: Products
  - name: Connections
  - name: Employments
  - name: Payment Requests
  - name: Payments
  - name: Settlements
paths:
  /auth/token:
    post:
      tags: [Auth]
      summary: Create Access Token
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                client_id: { type: string }
                client_secret: { type: string }
                grant_type: { type: string, example: client_credentials }
              required: [client_id, client_secret, grant_type]
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Token" }
  /auth/refresh-token:
    post:
      tags: [Auth]
      summary: Refresh Access Token
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                refresh_token: { type: string }
              required: [refresh_token]
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Token" }
  /users/{user-id}:
    get:
      tags: [Users]
      summary: Get A User
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema: { $ref: "#/components/schemas/User" }
  /users/match:
    post:
      tags: [Users]
      summary: Check User Eligibility
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email: { type: string }
                phone: { type: string }
                first_name: { type: string }
                last_name: { type: string }
      responses:
        "200":
          description: OK
  /users/simulate-identity:
    post:
      tags: [Users]
      summary: Simulate a new user identity (sandbox)
      responses:
        "200": { description: OK }
  /users/{user-id}/simulate-incoming-transfer:
    post:
      tags: [Users]
      summary: Simulate Receiving Payroll Deposit (sandbox)
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        "200": { description: OK }
  /companies/{company-id}:
    get:
      tags: [Companies]
      summary: Get a Company
      parameters:
        - name: company-id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: OK
  /products:
    get:
      tags: [Products]
      summary: List Products
      responses:
        "200": { description: OK }
  /products/{product-id}:
    get:
      tags: [Products]
      summary: Get a Product
      parameters:
        - name: product-id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200": { description: OK }
  /products/{product-id}/members:
    get:
      tags: [Products]
      summary: Get Product Members
      parameters:
        - name: product-id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200": { description: OK }
  /products/{product-id}/simulate-settlement:
    post:
      tags: [Products]
      summary: Simulate Settlement (sandbox)
      parameters:
        - name: product-id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200": { description: OK }
  /connections:
    get:
      tags: [Connections]
      summary: List Connections
      responses:
        "200": { description: OK }
  /connections/{connection-id}:
    get:
      tags: [Connections]
      summary: Get a Connection
      parameters:
        - $ref: "#/components/parameters/ConnectionId"
      responses:
        "200": { description: OK }
    delete:
      tags: [Connections]
      summary: Remove a Connection
      parameters:
        - $ref: "#/components/parameters/ConnectionId"
      responses:
        "204": { description: Removed }
  /employments:
    get:
      tags: [Employments]
      summary: List Employments
      responses:
        "200": { description: OK }
  /payment-requests:
    get:
      tags: [Payment Requests]
      summary: List Payment Requests
      responses:
        "200": { description: OK }
  /payment-requests/{payment-request-id}:
    get:
      tags: [Payment Requests]
      summary: Get a Payment Request
      parameters:
        - $ref: "#/components/parameters/PaymentRequestId"
      responses:
        "200": { description: OK }
    put:
      tags: [Payment Requests]
      summary: Update a Payment Request
      parameters:
        - $ref: "#/components/parameters/PaymentRequestId"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PaymentRequest" }
      responses:
        "200": { description: OK }
    delete:
      tags: [Payment Requests]
      summary: Cancel a Payment Request
      parameters:
        - $ref: "#/components/parameters/PaymentRequestId"
      responses:
        "204": { description: Cancelled }
  /connections/{connection-id}/payment-requests:
    post:
      tags: [Payment Requests]
      summary: Create Payment Requests
      parameters:
        - $ref: "#/components/parameters/ConnectionId"
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/PaymentRequest" }
      responses:
        "201": { description: Created }
  /payment-requests/{payment-request-id}/simulate-due-date:
    post:
      tags: [Payment Requests]
      summary: Simulate Due Date (sandbox)
      parameters:
        - $ref: "#/components/parameters/PaymentRequestId"
      responses:
        "200": { description: OK }
  /payments:
    get:
      tags: [Payments]
      summary: List Payments
      responses:
        "200": { description: OK }
  /payments/{payment-id}:
    get:
      tags: [Payments]
      summary: Get a Payment
      parameters:
        - name: payment-id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200": { description: OK }
  /payment-requests/{payment-request-id}/payments:
    get:
      tags: [Payments]
      summary: List Payments for Request
      parameters:
        - $ref: "#/components/parameters/PaymentRequestId"
      responses:
        "200": { description: OK }
  /settlements:
    get:
      tags: [Settlements]
      summary: List Settlements
      responses:
        "200": { description: OK }
  /settlements/{settlement-id}:
    get:
      tags: [Settlements]
      summary: Get a Settlement
      parameters:
        - $ref: "#/components/parameters/SettlementId"
      responses:
        "200": { description: OK }
  /settlements/{settlement-id}/report:
    get:
      tags: [Settlements]
      summary: Get Settlement Report
      parameters:
        - $ref: "#/components/parameters/SettlementId"
      responses:
        "200": { description: OK }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    UserId:
      name: user-id
      in: path
      required: true
      schema: { type: string }
    ConnectionId:
      name: connection-id
      in: path
      required: true
      schema: { type: string }
    PaymentRequestId:
      name: payment-request-id
      in: path
      required: true
      schema: { type: string }
    SettlementId:
      name: settlement-id
      in: path
      required: true
      schema: { type: string }
  schemas:
    Token:
      type: object
      properties:
        access_token: { type: string }
        token_type: { type: string, example: Bearer }
        expires_in: { type: integer }
        refresh_token: { type: string }
    User:
      type: object
      properties:
        id: { type: string }
        email: { type: string }
        first_name: { type: string }
        last_name: { type: string }
    PaymentRequest:
      type: object
      properties:
        connection_id: { type: string }
        amount: { type: integer, description: Amount in cents }
        currency: { type: string, example: USD }
        start_date: { type: string, format: date }
        due_date: { type: string, format: date }