openapi: 3.1.0
info:
  title: Quorum Land Management API
  description: >-
    Quorum Land Management API provides access to land records, lease management,
    tract data, division order information, and document management for upstream
    oil and gas exploration and production companies. Quorum is a leading provider
    of software solutions for the upstream oil and gas industry.
  version: 1.0.0
  contact:
    name: Quorum Support
    url: https://community.quorumsoftware.com
  license:
    name: Quorum Software Terms of Service
    url: https://www.quorumsoftware.com/terms-and-conditions/
servers:
  - url: https://api.quorumsoftware.com/v1
    description: Quorum API

security:
  - oauth2: []

tags:
  - name: DivisionOrders
    description: Division order management
  - name: Leases
    description: Oil and gas lease management
  - name: Owners
    description: Mineral interest owner management

  - name: Tracts
    description: Land tract records
  - name: Wells
    description: Well master data
paths:
  /leases:
    get:
      operationId: listLeases
      summary: List leases
      description: Returns oil and gas leases with status, terms, and acreage information.
      tags:
        - Leases
      parameters:
        - name: status
          in: query
          description: Filter by lease status
          schema:
            type: string
            enum: [ACTIVE, EXPIRED, SURRENDERED, HELD_BY_PRODUCTION, PRODUCING, SHUT_IN]
        - name: county
          in: query
          description: Filter by county name
          schema:
            type: string
        - name: state
          in: query
          description: Filter by state (2-letter abbreviation)
          schema:
            type: string
            maxLength: 2
        - name: updatedSince
          in: query
          schema:
            type: string
            format: date
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
            maximum: 500
      responses:
        '200':
          description: Lease list
          content:
            application/json:
              schema:
                type: object
                properties:
                  leases:
                    type: array
                    items:
                      $ref: '#/components/schemas/Lease'
                  totalCount:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createLease
      summary: Create a lease
      description: Creates a new oil and gas lease record.
      tags:
        - Leases
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeaseCreate'
      responses:
        '201':
          description: Lease created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lease'
        '400':
          $ref: '#/components/responses/BadRequest'

  /leases/{leaseId}:
    get:
      operationId: getLease
      summary: Get a lease
      description: Returns full details for an oil and gas lease.
      tags:
        - Leases
      parameters:
        - $ref: '#/components/parameters/LeaseId'
      responses:
        '200':
          description: Lease details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeaseDetail'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateLease
      summary: Update a lease
      description: Updates lease terms, status, or administrative data.
      tags:
        - Leases
      parameters:
        - $ref: '#/components/parameters/LeaseId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeaseUpdate'
      responses:
        '200':
          description: Lease updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Lease'

  /tracts:
    get:
      operationId: listTracts
      summary: List tracts
      description: Returns land tract records with legal description and acreage data.
      tags:
        - Tracts
      parameters:
        - name: leaseId
          in: query
          description: Filter by associated lease
          schema:
            type: string
        - name: state
          in: query
          schema:
            type: string
            maxLength: 2
        - name: county
          in: query
          schema:
            type: string
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Tract list
          content:
            application/json:
              schema:
                type: object
                properties:
                  tracts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tract'
                  totalCount:
                    type: integer

  /division-orders:
    get:
      operationId: listDivisionOrders
      summary: List division orders
      description: Returns division orders specifying owner decimal interest allocations.
      tags:
        - DivisionOrders
      parameters:
        - name: wellId
          in: query
          description: Filter by well
          schema:
            type: string
        - name: ownerId
          in: query
          description: Filter by owner
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum: [ACTIVE, CANCELLED, SUSPENDED]
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Division order list
          content:
            application/json:
              schema:
                type: object
                properties:
                  divisionOrders:
                    type: array
                    items:
                      $ref: '#/components/schemas/DivisionOrder'
                  totalCount:
                    type: integer

  /wells:
    get:
      operationId: listWells
      summary: List wells
      description: Returns well master data including API numbers, location, and production status.
      tags:
        - Wells
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [PRODUCING, SHUT_IN, ABANDONED, PLUGGED, DRILLING, COMPLETED]
        - name: state
          in: query
          schema:
            type: string
            maxLength: 2
        - name: county
          in: query
          schema:
            type: string
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Well list
          content:
            application/json:
              schema:
                type: object
                properties:
                  wells:
                    type: array
                    items:
                      $ref: '#/components/schemas/Well'
                  totalCount:
                    type: integer

  /wells/{wellId}:
    get:
      operationId: getWell
      summary: Get a well
      description: Returns well master record with API number, location, and status.
      tags:
        - Wells
      parameters:
        - name: wellId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Well details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Well'
        '404':
          $ref: '#/components/responses/NotFound'

  /owners:
    get:
      operationId: listOwners
      summary: List mineral interest owners
      description: Returns mineral interest owners with contact and payment information.
      tags:
        - Owners
      parameters:
        - name: ownerType
          in: query
          schema:
            type: string
            enum: [INDIVIDUAL, COMPANY, TRUST, ESTATE]
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Owner list
          content:
            application/json:
              schema:
                type: object
                properties:
                  owners:
                    type: array
                    items:
                      $ref: '#/components/schemas/Owner'
                  totalCount:
                    type: integer

components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.quorumsoftware.com/oauth2/token
          scopes:
            land.read: Read land management data
            land.write: Write land management data

  parameters:
    LeaseId:
      name: leaseId
      in: path
      required: true
      description: Quorum lease identifier
      schema:
        type: string

  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    Lease:
      type: object
      description: An oil and gas lease
      properties:
        leaseId:
          type: string
          description: Quorum system lease identifier
        leaseName:
          type: string
          description: Lease name or description
        leaseNumber:
          type: string
          description: User-defined lease number
        status:
          type: string
          enum: [ACTIVE, EXPIRED, SURRENDERED, HELD_BY_PRODUCTION, PRODUCING, SHUT_IN]
        effectiveDate:
          type: string
          format: date
          description: Lease effective/commence date
        expirationDate:
          type: string
          format: date
          nullable: true
        primaryTerm:
          type: integer
          description: Primary term in months
        royaltyRate:
          type: number
          format: double
          description: Royalty rate (decimal, e.g., 0.1875 = 18.75%)
        netAcres:
          type: number
          format: double
          description: Net mineral acres
        grossAcres:
          type: number
          format: double
          description: Gross acres in the lease
        county:
          type: string
        state:
          type: string
          maxLength: 2
        lessor:
          type: string
          description: Mineral rights grantor name
        lessee:
          type: string
          description: Oil company leaseholder
        hbpStatus:
          type: boolean
          description: Held by production status
        createDatetime:
          type: string
          format: date-time
        lastUpdateDatetime:
          type: string
          format: date-time

    LeaseCreate:
      type: object
      required:
        - leaseName
        - effectiveDate
        - royaltyRate
        - netAcres
        - county
        - state
        - lessor
      properties:
        leaseName:
          type: string
        leaseNumber:
          type: string
        effectiveDate:
          type: string
          format: date
        primaryTerm:
          type: integer
        royaltyRate:
          type: number
          format: double
        netAcres:
          type: number
          format: double
        grossAcres:
          type: number
          format: double
        county:
          type: string
        state:
          type: string
          maxLength: 2
        lessor:
          type: string
        lessee:
          type: string

    LeaseUpdate:
      type: object
      properties:
        status:
          type: string
          enum: [ACTIVE, EXPIRED, SURRENDERED, HELD_BY_PRODUCTION, PRODUCING, SHUT_IN]
        expirationDate:
          type: string
          format: date
        royaltyRate:
          type: number
          format: double
        hbpStatus:
          type: boolean

    LeaseDetail:
      allOf:
        - $ref: '#/components/schemas/Lease'
        - type: object
          properties:
            tracts:
              type: array
              items:
                $ref: '#/components/schemas/Tract'
            wells:
              type: array
              items:
                type: object
                properties:
                  wellId:
                    type: string
                  wellName:
                    type: string
                  apiNumber:
                    type: string

    Tract:
      type: object
      description: A land tract with legal description
      properties:
        tractId:
          type: string
        leaseId:
          type: string
        tractNumber:
          type: string
        legalDescription:
          type: string
          description: Full legal land description (section/township/range/meridian)
        section:
          type: string
        township:
          type: string
        range:
          type: string
        meridian:
          type: string
        county:
          type: string
        state:
          type: string
          maxLength: 2
        netAcres:
          type: number
          format: double
        grossAcres:
          type: number
          format: double
        ownershipType:
          type: string
          enum: [MINERAL, SURFACE, ROYALTY, WORKING_INTEREST]
        latitude:
          type: number
          format: double
          nullable: true
        longitude:
          type: number
          format: double
          nullable: true

    DivisionOrder:
      type: object
      description: A division order specifying owner decimal interest allocation
      properties:
        divisionOrderId:
          type: string
        wellId:
          type: string
        ownerId:
          type: string
        ownerName:
          type: string
        status:
          type: string
          enum: [ACTIVE, CANCELLED, SUSPENDED]
        effectiveDate:
          type: string
          format: date
        interestType:
          type: string
          enum: [WORKING_INTEREST, ROYALTY, OVERRIDING_ROYALTY, NET_PROFITS, PRODUCTION_PAYMENT]
        decimalInterest:
          type: number
          format: double
          description: Decimal fraction of production (e.g., 0.0625 = 6.25%)
          minimum: 0
          maximum: 1
        paymentMethod:
          type: string
          enum: [CHECK, ACH, WIRE]
        taxId:
          type: string
          description: Owner tax identification number (masked)

    Well:
      type: object
      description: An oil and gas well
      properties:
        wellId:
          type: string
        wellName:
          type: string
        apiNumber:
          type: string
          description: American Petroleum Institute well number (10 or 14 digits)
        status:
          type: string
          enum: [PRODUCING, SHUT_IN, ABANDONED, PLUGGED, DRILLING, COMPLETED]
        wellType:
          type: string
          enum: [OIL, GAS, OIL_AND_GAS, WATER_INJECTION, WATER_DISPOSAL, DRY_HOLE]
        county:
          type: string
        state:
          type: string
          maxLength: 2
        latitude:
          type: number
          format: double
          nullable: true
        longitude:
          type: number
          format: double
          nullable: true
        spudDate:
          type: string
          format: date
          nullable: true
        completionDate:
          type: string
          format: date
          nullable: true
        totalDepth:
          type: number
          format: double
          description: Total depth in feet
        formation:
          type: string
          description: Primary producing formation

    Owner:
      type: object
      description: A mineral interest owner
      properties:
        ownerId:
          type: string
        ownerName:
          type: string
        ownerType:
          type: string
          enum: [INDIVIDUAL, COMPANY, TRUST, ESTATE]
        address1:
          type: string
        address2:
          type: string
        city:
          type: string
        state:
          type: string
          maxLength: 2
        zip:
          type: string
        country:
          type: string
          maxLength: 3
        email:
          type: string
          format: email
        phone:
          type: string
        taxId:
          type: string
          description: Masked tax ID (last 4 only)
        paymentMethod:
          type: string
          enum: [CHECK, ACH, WIRE]
        active:
          type: boolean

    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string