openapi: 3.0.3
info:
  title: Oneflow Public Comments Contracts API
  description: 'The Oneflow Public API is a REST API for the Oneflow contract lifecycle management and e-signature platform. It lets teams programmatically create contracts from templates, add parties and participants, fill data fields and products, publish contracts for signing, download signed files, manage users and workspaces, and subscribe to contract lifecycle events via webhooks.

    Authentication uses two HTTP headers on every request: `x-oneflow-api-token` (an account API token generated in the Oneflow Marketplace) and, for most endpoints, `x-oneflow-user-email` (the email of the acting Oneflow user, used for permission-scoped authorization; omitting it runs the request as an anonymous admin user). API access and webhooks are available on the Business and Enterprise plans.

    Endpoint coverage note: /ping, contract create/get/list/publish, templates, workspaces, and users are confirmed against Oneflow''s public documentation. The remaining paths (contract delete/copy, data fields, parties, participants, webhooks, comments) are modeled from Oneflow''s documented resource models and REST conventions; verify exact shapes against the live reference before production use.'
  version: '1.0'
  contact:
    name: Oneflow
    url: https://developer.oneflow.com
  termsOfService: https://oneflow.com/terms-of-service/
servers:
- url: https://api.oneflow.com/v1
  description: Oneflow Public API (production)
security:
- apiToken: []
  userEmail: []
tags:
- name: Contracts
  description: Create, retrieve, update, publish, copy, and delete contracts.
paths:
  /contracts:
    get:
      operationId: listContracts
      tags:
      - Contracts
      summary: List contracts
      description: Retrieves the list of contracts available to the acting user.
      parameters:
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/limit'
      responses:
        '200':
          description: A list of contracts.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contract'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /contracts/create:
    post:
      operationId: createContract
      tags:
      - Contracts
      summary: Create a contract
      description: Creates a new contract in a workspace from a template. Requires a `workspace_id` and `template_id`, and typically the parties, data fields, and products to populate.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContractCreateRequest'
      responses:
        '200':
          description: The created contract.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /contracts/{contract_id}:
    parameters:
    - $ref: '#/components/parameters/contractId'
    get:
      operationId: getContract
      tags:
      - Contracts
      summary: Get a contract
      description: Retrieves a single contract by its ID.
      responses:
        '200':
          description: The contract.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateContract
      tags:
      - Contracts
      summary: Update a contract
      description: Updates the top-level information of a draft contract (modeled).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: The updated contract.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteContract
      tags:
      - Contracts
      summary: Delete a contract
      description: Deletes a contract (modeled).
      responses:
        '204':
          description: The contract was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /contracts/{contract_id}/publish:
    parameters:
    - $ref: '#/components/parameters/contractId'
    post:
      operationId: publishContract
      tags:
      - Contracts
      summary: Publish a contract
      description: Publishes a draft contract, sending the invitation/signing message to its participants.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublishRequest'
      responses:
        '200':
          description: The published contract.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /contracts/{contract_id}/copy:
    parameters:
    - $ref: '#/components/parameters/contractId'
    post:
      operationId: copyContract
      tags:
      - Contracts
      summary: Copy a contract
      description: Creates a copy of an existing contract (modeled).
      responses:
        '200':
          description: The copied contract.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  parameters:
    offset:
      name: offset
      in: query
      schema:
        type: integer
        minimum: 0
        maximum: 19900
        default: 0
      description: Pagination offset.
    contractId:
      name: contract_id
      in: path
      required: true
      schema:
        type: integer
      description: The ID of the contract.
    limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 100
      description: Maximum number of results to return.
  schemas:
    DataField:
      type: object
      properties:
        id:
          type: integer
        custom_id:
          type: string
        name:
          type: string
        value:
          type: string
    Participant:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email
        phone_number:
          type: string
        signatory:
          type: boolean
        delivery_channel:
          type: string
        _permissions:
          type: object
    Contract:
      type: object
      properties:
        id:
          type: integer
        state:
          type: string
          description: Contract state (e.g. draft, pending, signed, declined).
        template_id:
          type: integer
        workspace_id:
          type: integer
        name:
          type: string
        created_time:
          type: string
          format: date-time
        updated_time:
          type: string
          format: date-time
    ContractCreateRequest:
      type: object
      required:
      - workspace_id
      - template_id
      properties:
        workspace_id:
          type: integer
        template_id:
          type: integer
        parties:
          type: array
          items:
            $ref: '#/components/schemas/Party'
        data_fields:
          type: array
          items:
            $ref: '#/components/schemas/DataField'
    Error:
      type: object
      properties:
        status_code:
          type: integer
        parameter_errors:
          type: object
        errors:
          type: array
          items:
            type: object
    Party:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        country_code:
          type: string
        identification_number:
          type: string
        type:
          type: string
          description: Party type (e.g. company or individual).
        participants:
          type: array
          items:
            $ref: '#/components/schemas/Participant'
    PublishRequest:
      type: object
      properties:
        subject:
          type: string
          description: Subject line of the invitation message.
        message:
          type: string
          description: Body of the invitation message sent to participants.
  responses:
    Unauthorized:
      description: Missing or invalid API token / user email.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was malformed or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiToken:
      type: apiKey
      in: header
      name: x-oneflow-api-token
      description: Account API token generated in the Oneflow Marketplace.
    userEmail:
      type: apiKey
      in: header
      name: x-oneflow-user-email
      description: Email of the acting Oneflow user, used for permission-scoped authorization. Optional on some endpoints; omitting it runs the request as an anonymous admin user.