APISign Templates API

openapi: 3.2.0
info:
  title: Sign Templates API
  description: 'Programmatically create, send, and manage contracts for e-signatures. Contracts are created as drafts and charged when sent ($0.25 per send at the default price; test-mode sends are free). Errors return `{ "error": string }`; request validation errors add a `details` array. API key requests are not rate limited.'
  version: 1.0.0
  contact:
    name: API Sign Support
    url: https://apisign.io
servers:
- url: https://apisign.io/api
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Templates
  description: Manage reusable contract templates
paths:
  /template/create:
    post:
      summary: Create a template
      description: Create a template. Only `name` and `content` are read; set field definitions with `/template/update`.
      operationId: createTemplate
      tags:
      - Templates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTemplateRequest'
      responses:
        '200':
          description: Template created
          content:
            application/json:
              schema:
                type: object
                properties:
                  template:
                    $ref: '#/components/schemas/Template'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  /template/get:
    get:
      summary: Get a template
      description: 'Retrieve a template by ID, including archived templates. Returns 200 with `template: null` when no template with that ID exists in the organization.'
      operationId: getTemplate
      tags:
      - Templates
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
        description: Template ID
      responses:
        '200':
          description: Template details
          content:
            application/json:
              schema:
                type: object
                properties:
                  template:
                    allOf:
                    - type: object
                      properties:
                        id:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                        name:
                          type: string
                        content:
                          type:
                          - string
                          - 'null'
                        fields:
                          $ref: '#/components/schemas/StoredFields'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  /template/find:
    get:
      summary: List templates
      description: List non-archived templates, newest first. There are no filter or pagination parameters.
      operationId: listTemplates
      tags:
      - Templates
      responses:
        '200':
          description: List of templates
          content:
            application/json:
              schema:
                type: object
                properties:
                  templates:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        created_at:
                          type: string
                          format: date-time
                        updated_at:
                          type: string
                          format: date-time
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
  /template/update:
    post:
      summary: Update a template
      description: Update a non-archived template. `name` and `content` are required on every call. Unless `content` is empty, at least one variable must resolve to a signer-completed signature field.
      operationId: updateTemplate
      tags:
      - Templates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTemplateRequest'
      responses:
        '200':
          description: Template updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  template:
                    $ref: '#/components/schemas/Template'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /template/archive:
    post:
      summary: Archive a template
      description: Archive a template (soft delete). Archived templates are excluded from `/template/find` and cannot be updated or used for new contracts.
      operationId: archiveTemplate
      tags:
      - Templates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              properties:
                id:
                  type: string
                  description: Template ID to archive
      responses:
        '200':
          description: Template archived
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /template/upload:
    post:
      summary: Create a template from a .docx file
      description: Create a template from a Word document. The template is named after the file and has no field definitions.
      operationId: uploadTemplate
      tags:
      - Templates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FileUploadRequest'
      responses:
        '200':
          description: Template created
          content:
            application/json:
              schema:
                type: object
                properties:
                  template:
                    $ref: '#/components/schemas/Template'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    CreateTemplateRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          minLength: 3
        content:
          type: string
          description: Markdown with {{variables}}
    Template:
      type: object
      properties:
        id:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        org_id:
          type: string
        name:
          type: string
        content:
          type:
          - string
          - 'null'
          description: Markdown with {{variables}}
        fields:
          $ref: '#/components/schemas/StoredFields'
        archived:
          type: boolean
        test_mode:
          type: boolean
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Error message
        details:
          type: array
          description: Present on request validation errors
          items:
            type: object
            properties:
              field:
                type: string
                description: Dot path of the invalid field
              message:
                type: string
    FileUploadRequest:
      type: object
      required:
      - filename
      - fileData
      properties:
        filename:
          type: string
          description: File name ending in .docx
        fileData:
          type: string
          description: File bytes, base64-encoded
    StoredFields:
      type:
      - object
      - 'null'
      description: Field data as stored on a contract or template
      properties:
        fields:
          type: array
          items:
            $ref: '#/components/schemas/FieldDefinition'
        signers:
          type: array
          description: Per-signer field assignments, matched to signers by signing_order
          items:
            type: object
            properties:
              signing_order:
                type: integer
              signerFields:
                type: array
                items:
                  type: string
    UpdateTemplateRequest:
      type: object
      required:
      - id
      - name
      - content
      properties:
        id:
          type: string
        name:
          type: string
          minLength: 1
        content:
          type: string
          description: Full markdown content
        fields:
          type: array
          description: Replaces stored field definitions; omit to keep them
          items:
            type: object
            required:
            - name
            - type
            properties:
              name:
                type: string
              type:
                type: string
              completedBy:
                type: string
                description: Defaults to signer
                enum:
                - signer
                - creator
              label:
                type: string
    FieldDefinition:
      type: object
      required:
      - name
      - type
      - completedBy
      properties:
        name:
          type: string
          description: Variable name without braces
        type:
          type: string
          description: signature, initials, signer_name, timestamp, text, email, phone or date
        completedBy:
          type: string
          enum:
          - signer
          - creator
        label:
          type: string
          description: Prompt shown for a text field
  responses:
    ServerError:
      description: Internal server error (also returned for a request body that is not valid JSON)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request, or the action is not allowed in the resource's current state
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: 'Missing, invalid, expired or deleted API key. Body: `{ "error": "Unauthorized" }`'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found in this organization
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key from the dashboard (Account → MCP & API Keys). Keys start with `ask_`. A key's `read`/`read_write` permission applies only to the MCP server; REST endpoints do not check it.