openapi: 3.2.0
info:
  title: Firma Partner Signer Terms API
  description: RESTful API for document signing and template management.
  version: 01.38.00
  contact:
    name: API Support
    url: https://firma.com/support
servers:
- url: https://api.firma.dev/functions/v1/signing-request-api
  description: Production API - Recommended (Current)
- url: https://api.firma.dev/api/v1
  description: Production API - Planned
security:
- ApiKeyAuth: []
tags:
- name: Signer Terms
  description: Custom signer terms-of-service / consent statements, company-level with per-language workspace overrides
paths:
  /company/signer-terms:
    get:
      summary: List company signer terms
      description: Retrieve all company-level signer terms. Company signer terms serve as defaults for workspaces without workspace-specific signer terms.
      tags:
      - Signer Terms
      security:
      - ApiKeyAuth: []
      responses:
        '200':
          description: Company signer terms retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignerTermsListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/RateLimitError'
      operationId: listCompanySignerTerms
      x-codeSamples:
      - lang: TypeScript
        label: '@firma-dev/sdk'
        source: 'import { FirmaClient } from "@firma-dev/sdk";


          const firma = new FirmaClient({ apiKey: "YOUR_API_KEY" });


          const response = await firma.signerTerms.listCompanySignerTerms();

          console.log(response);'
  /company/signer-terms/{language}:
    put:
      summary: Create or update company signer terms
      description: Create or update company-level signer terms for a specific language. The submitted statement is sanitized before storage.
      tags:
      - Signer Terms
      security:
      - ApiKeyAuth: []
      parameters:
      - name: language
        in: path
        required: true
        schema:
          type: string
          enum:
          - en
          - es
          - it
          - pt
          - fr
          - de
          - el
          - ru
          - pl
          - cs
          - sv
          - nl
          - ro
          - nb
          - ca
        description: Language code
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - statement_text
              properties:
                statement_text:
                  type: string
                  description: Signer consent statement as HTML. Sanitized before storage.
                terms_url:
                  type:
                  - string
                  - 'null'
                  format: uri
                  description: Optional external terms link
      responses:
        '200':
          description: Company signer terms updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignerTermsUpdateResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '429':
          $ref: '#/components/responses/RateLimitError'
      operationId: updateCompanySignerTerms
      x-codeSamples:
      - lang: TypeScript
        label: '@firma-dev/sdk'
        source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signerTerms.updateCompanySignerTerms({\n    language: \"en\",\n    statement_text: \"statement_text\"\n});\nconsole.log(response);"
    delete:
      summary: Delete company signer terms
      description: Delete company-level signer terms for a specific language.
      tags:
      - Signer Terms
      security:
      - ApiKeyAuth: []
      parameters:
      - name: language
        in: path
        required: true
        schema:
          type: string
          enum:
          - en
          - es
          - it
          - pt
          - fr
          - de
          - el
          - ru
          - pl
          - cs
          - sv
          - nl
          - ro
          - nb
          - ca
        description: Language code
      responses:
        '200':
          description: Company signer terms deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignerTermsDeleteResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
      operationId: deleteCompanySignerTerms
      x-codeSamples:
      - lang: TypeScript
        label: '@firma-dev/sdk'
        source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signerTerms.deleteCompanySignerTerms({\n    language: \"en\"\n});\nconsole.log(response);"
  /workspace/{workspace_id}/signer-terms:
    get:
      summary: List workspace signer terms
      description: Retrieve all custom signer terms for a workspace
      tags:
      - Signer Terms
      security:
      - ApiKeyAuth: []
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Workspace ID
      responses:
        '200':
          description: Workspace signer terms retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignerTermsListResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
      operationId: listWorkspaceSignerTerms
      x-codeSamples:
      - lang: TypeScript
        label: '@firma-dev/sdk'
        source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signerTerms.listWorkspaceSignerTerms({\n    workspace_id: \"workspace_id\"\n});\nconsole.log(response);"
  /workspace/{workspace_id}/signer-terms/{language}:
    put:
      summary: Create or update workspace signer terms
      description: Create or update workspace-level signer terms for a specific language. The submitted statement is sanitized before storage.
      tags:
      - Signer Terms
      security:
      - ApiKeyAuth: []
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Workspace ID
      - name: language
        in: path
        required: true
        schema:
          type: string
          enum:
          - en
          - es
          - it
          - pt
          - fr
          - de
          - el
          - ru
          - pl
          - cs
          - sv
          - nl
          - ro
          - nb
          - ca
        description: Language code
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - statement_text
              properties:
                statement_text:
                  type: string
                  description: Signer consent statement as HTML. Sanitized before storage.
                terms_url:
                  type:
                  - string
                  - 'null'
                  format: uri
                  description: Optional external terms link
      responses:
        '200':
          description: Workspace signer terms updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignerTermsUpdateResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
      operationId: updateWorkspaceSignerTerms
      x-codeSamples:
      - lang: TypeScript
        label: '@firma-dev/sdk'
        source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signerTerms.updateWorkspaceSignerTerms({\n    workspace_id: \"workspace_id\",\n    language: \"en\",\n    statement_text: \"statement_text\"\n});\nconsole.log(response);"
    delete:
      summary: Delete workspace signer terms
      description: Delete workspace-level signer terms for a specific language.
      tags:
      - Signer Terms
      security:
      - ApiKeyAuth: []
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Workspace ID
      - name: language
        in: path
        required: true
        schema:
          type: string
          enum:
          - en
          - es
          - it
          - pt
          - fr
          - de
          - el
          - ru
          - pl
          - cs
          - sv
          - nl
          - ro
          - nb
          - ca
        description: Language code
      responses:
        '200':
          description: Workspace signer terms deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignerTermsDeleteResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
      operationId: deleteWorkspaceSignerTerms
      x-codeSamples:
      - lang: TypeScript
        label: '@firma-dev/sdk'
        source: "import { FirmaClient } from \"@firma-dev/sdk\";\n\nconst firma = new FirmaClient({ apiKey: \"YOUR_API_KEY\" });\n\nconst response = await firma.signerTerms.deleteWorkspaceSignerTerms({\n    workspace_id: \"workspace_id\",\n    language: \"en\"\n});\nconsole.log(response);"
components:
  responses:
    RateLimitError:
      description: Too Many Requests - Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Maximum requests per minute
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Requests remaining
        X-RateLimit-Reset:
          schema:
            type: integer
          description: Unix timestamp of reset
        Retry-After:
          schema:
            type: integer
          description: Seconds until retry allowed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Rate Limit Exceeded
            message: Too many requests. Please wait before retrying.
            details:
              retry_after: 45
    UnauthorizedError:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
            message: Invalid API key
    ValidationError:
      description: Bad Request - Validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Validation Error
            message: Invalid input data
            details:
              name: Name is required
              email: Invalid email format
    NotFoundError:
      description: Not Found - Resource does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not Found
            message: The requested resource was not found
    ForbiddenError:
      description: Forbidden - Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Forbidden
            message: You do not have permission to access this resource
  schemas:
    SignerTerms:
      type: object
      properties:
        language:
          type: string
          enum:
          - en
          - es
          - it
          - pt
          - fr
          - de
          - el
          - ru
          - pl
          - cs
          - sv
          - nl
          - ro
          - nb
          - ca
        statement_text:
          type: string
          description: Sanitized HTML consent statement
        terms_url:
          type:
          - string
          - 'null'
          format: uri
          description: Optional external terms link
        updated_at:
          type: string
          format: date-time
      required:
      - language
      - statement_text
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
        code:
          type: string
          description: 'Machine-readable error code Seal-related codes: SEALS_DISABLED, SEAL_ALREADY_REVOKED, SEAL_CREATION_DISABLED_EDGE, SEAL_ERASE_NOT_ELIGIBLE, SEAL_IMAGE_INVALID, SEAL_MUTATION_NOT_ALLOWED, SEAL_NOT_FOUND, SEAL_ORDER_COLLISION, SEAL_PAUSED, SEAL_SCOPE_FORBIDDEN, SEAL_UNAVAILABLE'
        errors:
          type: array
          description: All validation errors when multiple failures are reported together. The top-level error repeats the first item for backward compatibility.
          items:
            type: object
            required:
            - message
            properties:
              message:
                type: string
        message:
          type: string
          description: Detailed error description
        details:
          type: object
          description: Additional error details
          additionalProperties: true
      required:
      - error
      description: '


        Organization Seal error codes: SEALS_DISABLED, SEAL_ALREADY_REVOKED, SEAL_CREATION_DISABLED_EDGE, SEAL_ERASE_NOT_ELIGIBLE, SEAL_IMAGE_INVALID, SEAL_MUTATION_NOT_ALLOWED, SEAL_NOT_FOUND, SEAL_ORDER_COLLISION, SEAL_PAUSED, SEAL_SCOPE_FORBIDDEN, SEAL_UNAVAILABLE'
    SignerTermsUpdateResponse:
      type: object
      properties:
        ok:
          type: boolean
        storedHtml:
          type: string
          description: The sanitized HTML actually stored
        changed:
          type: boolean
          description: Whether sanitization altered the submitted statement
      description: Signer terms update result
      required:
      - ok
    SignerTermsDeleteResponse:
      type: object
      properties:
        message:
          type: string
        language:
          type: string
      description: Signer terms deletion confirmation
      required:
      - message
      - language
    SignerTermsListResponse:
      type: object
      properties:
        terms:
          type: array
          items:
            $ref: '#/components/schemas/SignerTerms'
      description: List of signer terms by language
      required:
      - terms
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key for authentication. Use your API key directly without any prefix (e.g., 'your-api-key'). Bearer prefix is optional but not required.