BuildWorkPro Signature Requests API

openapi: 3.2.0
info:
  title: BuildWorkPro Signature Requests API
  version: 1.0.0
  description: Construction project management, CRM, and workflows — public REST API.
  contact:
    name: BuildWorkPro Developers
    email: developers@buildworkpro.com
  license:
    name: Proprietary
    url: https://buildworkpro.com/terms
servers:
- url: https://app.buildworkpro.com/api/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: SignatureRequests
  description: E-signature requests raised against bids and change orders.
paths:
  /signature-requests:
    get:
      summary: List e-signature requests
      description: Signature requests across bids and change orders, newest first. The recipient token is never returned; the signing URL requires signatures:send and an active request.
      security:
      - bearerAuth:
        - signatures:read
      tags:
      - SignatureRequests
      parameters:
      - schema:
          type: string
          enum:
          - bid
          - change_order
        required: false
        name: entityType
        in: query
      - schema:
          type:
          - integer
          - 'null'
        required: false
        name: entityId
        in: query
      - schema:
          type: string
        required: false
        name: status
        in: query
      - schema:
          type: integer
          minimum: 1
          maximum: 100
        required: false
        name: limit
        in: query
      - schema:
          type:
          - integer
          - 'null'
        required: false
        name: cursor
        in: query
      responses:
        '200':
          description: Signature requests page
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/SignatureRequest'
                  meta:
                    $ref: '#/components/schemas/ResponseMeta'
                required:
                - data
                - meta
        '400':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '403':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: getSignatureRequests
      x-rate-limit-cost: 1
  /signature-requests/{id}:
    get:
      summary: Get an e-signature request
      security:
      - bearerAuth:
        - signatures:read
      tags:
      - SignatureRequests
      parameters:
      - schema:
          type: integer
        required: true
        name: id
        in: path
      responses:
        '200':
          description: Signature request
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SignatureRequest'
                required:
                - data
        '403':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: getSignatureRequestsById
      x-rate-limit-cost: 1
  /signature-requests/{id}/resend:
    post:
      summary: Resend an e-signature request
      description: Re-emails the SAME signing link. No new document is created. 409s when the request is not pending or sent. Shares the app's resend budget (20 per hour per organization and user); 429 past it.
      security:
      - bearerAuth:
        - signatures:send
      tags:
      - SignatureRequests
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      - schema:
          type: integer
        required: true
        name: id
        in: path
      responses:
        '200':
          description: Resend result
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      emailSent:
                        type: boolean
                    required:
                    - emailSent
                required:
                - data
        '403':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '429':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: postSignatureRequestsByIdResend
      x-rate-limit-cost: 5
  /signature-requests/{id}/void:
    post:
      summary: Void an e-signature request
      description: Cancels an active request and kills its signing link. The stored row is the source of truth; cancelling the remote document is best-effort.
      security:
      - bearerAuth:
        - signatures:send
      tags:
      - SignatureRequests
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      - schema:
          type: integer
        required: true
        name: id
        in: path
      responses:
        '200':
          description: Voided
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/SignatureRequest'
                required:
                - data
        '403':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '409':
          description: Error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
      operationId: postSignatureRequestsByIdVoid
      x-rate-limit-cost: 5
components:
  schemas:
    PaginationMeta:
      type: object
      properties:
        cursor:
          type:
          - string
          - 'null'
          description: Opaque cursor for the next page; null when no more results
        has_more:
          type: boolean
          description: Whether more pages are available after this one
        count:
          type: integer
          description: Items in this page
      required:
      - cursor
      - has_more
      - count
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          format: uri
          description: URL identifying the problem type
        title:
          type: string
          description: Short human-readable summary
        status:
          type: integer
          description: HTTP status code
        detail:
          type: string
          description: Human-readable explanation
        request_id:
          type: string
          description: Server-generated request identifier
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                description: Field path that failed validation
              code:
                type: string
                description: Validation error code
              message:
                type: string
                description: Human-readable validation message
            required:
            - field
            - code
            - message
          description: Validation error array (422 only)
      required:
      - type
      - title
      - status
    SignatureRequest:
      type: object
      properties:
        id:
          type: integer
        entityType:
          type: string
          enum:
          - bid
          - change_order
        entityId:
          type: integer
        status:
          type: string
        signerName:
          type:
          - string
          - 'null'
        signerEmail:
          type:
          - string
          - 'null'
        sentAt:
          anyOf:
          - type: string
            format: date-time
          - type: string
          - type: 'null'
        signedAt:
          anyOf:
          - type: string
            format: date-time
          - type: string
          - type: 'null'
        signedDocumentId:
          type:
          - integer
          - 'null'
        signingUrl:
          type:
          - string
          - 'null'
          description: Present only for callers holding signatures:send, and only while the request is pending or sent.
      required:
      - id
      - entityType
      - entityId
      - status
      - signerName
      - signerEmail
      - sentAt
      - signedAt
      - signedDocumentId
    ResponseMeta:
      type: object
      properties:
        request_id:
          type: string
          description: Server-generated request identifier
        pagination:
          $ref: '#/components/schemas/PaginationMeta'
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: 'Idempotent retry key for mutating operations. The first request with a given key executes normally and BuildWorkPro caches the response. Replaying the same key with the same request body (method + path + JSON body, SHA-256 hashed) returns the cached response without re-executing the mutation. Replaying with a DIFFERENT body returns `409 idempotency_key_reused`. The cache TTL is 24 hours; after expiry the key is treated as a new operation. Keys are tenant-scoped. Recommended: a fresh UUID v4 per logical operation.'
      schema:
        type: string
        format: uuid
        maxLength: 255
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: bwp_live_... or bwp_test_...
      description: Long-lived tenant-wide API key. Provision in Settings → Developer → API Keys.
    oauth2:
      type: oauth2
      description: OAuth 2.1 per-user token. Available in Phase 4.
      flows:
        authorizationCode:
          authorizationUrl: https://app.buildworkpro.com/api/v1/oauth/authorize
          tokenUrl: https://app.buildworkpro.com/api/v1/oauth/token
          refreshUrl: https://app.buildworkpro.com/api/v1/oauth/token
          scopes: {}