{
  "swagger": "2.0",
  "info": {
    "title": "Siggy eSignatures",
    "description": "Send documents for legally-binding electronic signature with Siggy (siggy.com.au). Create an API key in Siggy under Security > API keys (Business plan or above), then connect with the value: Bearer sk_live_yourkey",
    "version": "1.0.0",
    "contact": {
      "name": "Siggy support",
      "email": "info@axiomdata.com.au",
      "url": "https://siggy.com.au"
    }
  },
  "host": "siggy.com.au",
  "basePath": "/api/be/v1",
  "schemes": ["https"],
  "consumes": ["application/json"],
  "produces": ["application/json"],
  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Authorization",
      "description": "Enter: Bearer sk_live_yourkey (include the word Bearer and a space)"
    }
  },
  "security": [{ "api_key": [] }],
  "paths": {
    "/templates": {
      "get": {
        "operationId": "ListTemplates",
        "summary": "List templates",
        "x-ms-summary": "List templates",
        "description": "Templates available to send from, with the signer roles each one needs filled.",
        "responses": {
          "200": {
            "description": "Templates",
            "schema": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "string", "x-ms-summary": "Template ID" },
                      "name": { "type": "string", "x-ms-summary": "Name" },
                      "routing_mode": { "type": "string", "x-ms-summary": "Routing mode" },
                      "created_at": { "type": "string", "x-ms-summary": "Created at" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/templates/{template_id}/send": {
      "post": {
        "operationId": "SendFromTemplate",
        "summary": "Send envelope from template",
        "x-ms-summary": "Send envelope from template",
        "description": "Instantiate a saved template with real people and send it for signature — no field coordinates needed.",
        "parameters": [
          {
            "name": "template_id",
            "in": "path",
            "required": true,
            "type": "string",
            "x-ms-summary": "Template ID",
            "x-ms-url-encoding": "single"
          },
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "required": ["recipients"],
              "properties": {
                "title": {
                  "type": "string",
                  "x-ms-summary": "Envelope title",
                  "description": "Optional title shown to signers (defaults to the template name)"
                },
                "recipients": {
                  "type": "array",
                  "x-ms-summary": "Recipients",
                  "items": {
                    "type": "object",
                    "required": ["name", "email"],
                    "properties": {
                      "name": { "type": "string", "x-ms-summary": "Name" },
                      "email": { "type": "string", "x-ms-summary": "Email" },
                      "access_code": {
                        "type": "string",
                        "x-ms-summary": "Access code",
                        "description": "Optional code the signer must enter before signing (Professional plan and above)"
                      }
                    }
                  }
                }
              }
            }
          }
        ],
        "responses": {
          "201": { "description": "Sent", "schema": { "$ref": "#/definitions/EnvelopeResult" } },
          "402": { "description": "Quota spent or plan lacks a required feature" }
        }
      }
    },
    "/envelopes": {
      "post": {
        "operationId": "CreateEnvelope",
        "summary": "Send a document for signature",
        "x-ms-summary": "Send a document for signature",
        "description": "Create and send an envelope in one call. Provide the PDF as base64 file content (use the File Content output of SharePoint/OneDrive actions with the base64() expression if needed).",
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "required": ["title", "recipients"],
              "properties": {
                "document_base64": {
                  "type": "string",
                  "x-ms-summary": "PDF content (base64)",
                  "description": "The PDF file, base64-encoded"
                },
                "filename": { "type": "string", "x-ms-summary": "File name" },
                "document_id": {
                  "type": "string",
                  "x-ms-summary": "Document ID",
                  "description": "Alternative to PDF content: the ID of a previously uploaded document"
                },
                "title": { "type": "string", "x-ms-summary": "Envelope title" },
                "routing_mode": {
                  "type": "string",
                  "x-ms-summary": "Routing mode",
                  "description": "sequential or parallel",
                  "default": "sequential",
                  "enum": ["sequential", "parallel"]
                },
                "recipients": {
                  "type": "array",
                  "x-ms-summary": "Recipients",
                  "items": {
                    "type": "object",
                    "required": ["name", "email"],
                    "properties": {
                      "name": { "type": "string", "x-ms-summary": "Name" },
                      "email": { "type": "string", "x-ms-summary": "Email" },
                      "routing_order": {
                        "type": "integer",
                        "x-ms-summary": "Routing order",
                        "default": 1
                      },
                      "access_code": { "type": "string", "x-ms-summary": "Access code" }
                    }
                  }
                },
                "fields": {
                  "type": "array",
                  "x-ms-summary": "Signature fields",
                  "description": "Where each signer signs. Coordinates are fractions of the page (0-1), top-left origin.",
                  "items": {
                    "type": "object",
                    "required": ["recipient_index", "type", "page", "x", "y", "w", "h"],
                    "properties": {
                      "recipient_index": { "type": "integer", "x-ms-summary": "Recipient index" },
                      "type": {
                        "type": "string",
                        "x-ms-summary": "Field type",
                        "enum": ["signature", "initials", "date", "name", "text", "checkbox"]
                      },
                      "page": { "type": "integer", "x-ms-summary": "Page" },
                      "x": { "type": "number", "x-ms-summary": "X (0-1)" },
                      "y": { "type": "number", "x-ms-summary": "Y (0-1)" },
                      "w": { "type": "number", "x-ms-summary": "Width (0-1)" },
                      "h": { "type": "number", "x-ms-summary": "Height (0-1)" }
                    }
                  }
                }
              }
            }
          }
        ],
        "responses": {
          "201": { "description": "Sent", "schema": { "$ref": "#/definitions/EnvelopeResult" } },
          "400": { "description": "Invalid request" },
          "402": { "description": "Monthly envelope quota spent" },
          "413": { "description": "File too large (max 25 MB)" }
        }
      },
      "get": {
        "operationId": "ListEnvelopes",
        "summary": "List envelopes",
        "x-ms-summary": "List envelopes",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "type": "string",
            "required": false,
            "x-ms-summary": "Status filter",
            "enum": ["sent", "completed", "declined", "voided"]
          },
          {
            "name": "limit",
            "in": "query",
            "type": "integer",
            "required": false,
            "default": 25,
            "x-ms-summary": "Page size"
          },
          {
            "name": "offset",
            "in": "query",
            "type": "integer",
            "required": false,
            "default": 0,
            "x-ms-summary": "Offset"
          }
        ],
        "responses": {
          "200": {
            "description": "Envelopes",
            "schema": {
              "type": "object",
              "properties": {
                "data": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "string", "x-ms-summary": "Envelope ID" },
                      "title": { "type": "string", "x-ms-summary": "Title" },
                      "status": { "type": "string", "x-ms-summary": "Status" },
                      "created_at": { "type": "string", "x-ms-summary": "Created at" }
                    }
                  }
                },
                "has_more": { "type": "boolean", "x-ms-summary": "Has more" }
              }
            }
          }
        }
      }
    },
    "/envelopes/{envelope_id}": {
      "get": {
        "operationId": "GetEnvelope",
        "summary": "Get envelope status",
        "x-ms-summary": "Get envelope status",
        "parameters": [
          {
            "name": "envelope_id",
            "in": "path",
            "required": true,
            "type": "string",
            "x-ms-summary": "Envelope ID",
            "x-ms-url-encoding": "single"
          }
        ],
        "responses": {
          "200": {
            "description": "Envelope",
            "schema": {
              "type": "object",
              "properties": {
                "id": { "type": "string", "x-ms-summary": "Envelope ID" },
                "title": { "type": "string", "x-ms-summary": "Title" },
                "status": { "type": "string", "x-ms-summary": "Status" },
                "recipients": {
                  "type": "array",
                  "x-ms-summary": "Recipients",
                  "items": {
                    "type": "object",
                    "properties": {
                      "name": { "type": "string", "x-ms-summary": "Name" },
                      "email": { "type": "string", "x-ms-summary": "Email" },
                      "status": { "type": "string", "x-ms-summary": "Status" }
                    }
                  }
                }
              }
            }
          },
          "404": { "description": "Not found" }
        }
      }
    },
    "/envelopes/{envelope_id}/document": {
      "get": {
        "operationId": "GetSealedDocument",
        "summary": "Download the sealed PDF",
        "x-ms-summary": "Download the sealed PDF",
        "description": "The tamper-evident signed PDF. Available once the envelope is completed.",
        "produces": ["application/pdf"],
        "parameters": [
          {
            "name": "envelope_id",
            "in": "path",
            "required": true,
            "type": "string",
            "x-ms-summary": "Envelope ID",
            "x-ms-url-encoding": "single"
          }
        ],
        "responses": {
          "200": {
            "description": "PDF file",
            "schema": { "type": "string", "format": "binary", "x-ms-summary": "File content" }
          },
          "409": { "description": "Envelope is not completed yet" }
        }
      }
    },
    "/envelopes/{envelope_id}/certificate": {
      "get": {
        "operationId": "GetCertificate",
        "summary": "Download the completion certificate",
        "x-ms-summary": "Download the completion certificate",
        "description": "Audit-trail certificate PDF: consent, signatures, timestamps.",
        "produces": ["application/pdf"],
        "parameters": [
          {
            "name": "envelope_id",
            "in": "path",
            "required": true,
            "type": "string",
            "x-ms-summary": "Envelope ID",
            "x-ms-url-encoding": "single"
          }
        ],
        "responses": {
          "200": {
            "description": "PDF file",
            "schema": { "type": "string", "format": "binary", "x-ms-summary": "File content" }
          },
          "409": { "description": "Certificate is not ready yet" }
        }
      }
    },
    "/envelopes/{envelope_id}/void": {
      "post": {
        "operationId": "VoidEnvelope",
        "summary": "Void an envelope",
        "x-ms-summary": "Void an envelope",
        "parameters": [
          {
            "name": "envelope_id",
            "in": "path",
            "required": true,
            "type": "string",
            "x-ms-summary": "Envelope ID",
            "x-ms-url-encoding": "single"
          },
          {
            "name": "body",
            "in": "body",
            "required": false,
            "schema": {
              "type": "object",
              "properties": {
                "reason": { "type": "string", "x-ms-summary": "Reason" }
              }
            }
          }
        ],
        "responses": {
          "200": { "description": "Voided" },
          "409": { "description": "Envelope cannot be voided in its current state" }
        }
      }
    },
    "/envelopes/{envelope_id}/remind": {
      "post": {
        "operationId": "RemindEnvelope",
        "summary": "Send a reminder",
        "x-ms-summary": "Send a reminder",
        "description": "Re-emails the signing link to whoever the envelope is currently waiting on.",
        "parameters": [
          {
            "name": "envelope_id",
            "in": "path",
            "required": true,
            "type": "string",
            "x-ms-summary": "Envelope ID",
            "x-ms-url-encoding": "single"
          }
        ],
        "responses": { "200": { "description": "Reminded" } }
      }
    },
    "/webhooks": {
      "get": {
        "operationId": "ListWebhooks",
        "summary": "List webhook endpoints",
        "x-ms-summary": "List webhook endpoints",
        "responses": { "200": { "description": "Webhook endpoints" } }
      },
      "post": {
        "operationId": "CreateWebhook",
        "summary": "Register a webhook endpoint",
        "x-ms-summary": "Register a webhook endpoint",
        "description": "Siggy POSTs a signed JSON event to this HTTPS URL on envelope.sent, recipient.signed, envelope.completed and envelope.declined. Paste a Power Automate 'When an HTTP request is received' URL here to trigger flows.",
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "type": "object",
              "required": ["url"],
              "properties": {
                "url": { "type": "string", "x-ms-summary": "HTTPS URL" },
                "description": { "type": "string", "x-ms-summary": "Description" }
              }
            }
          }
        ],
        "responses": { "201": { "description": "Created (response includes the signing secret)" } }
      }
    },
    "/webhooks/{endpoint_id}": {
      "delete": {
        "operationId": "DeleteWebhook",
        "summary": "Delete a webhook endpoint",
        "x-ms-summary": "Delete a webhook endpoint",
        "parameters": [
          {
            "name": "endpoint_id",
            "in": "path",
            "required": true,
            "type": "string",
            "x-ms-summary": "Endpoint ID",
            "x-ms-url-encoding": "single"
          }
        ],
        "responses": { "204": { "description": "Deleted" } }
      }
    }
  },
  "definitions": {
    "EnvelopeResult": {
      "type": "object",
      "properties": {
        "id": { "type": "string", "x-ms-summary": "Envelope ID" },
        "status": { "type": "string", "x-ms-summary": "Status" },
        "recipients": {
          "type": "array",
          "x-ms-summary": "Recipients",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string", "x-ms-summary": "Name" },
              "email": { "type": "string", "x-ms-summary": "Email" },
              "sign_url": { "type": "string", "x-ms-summary": "Signing link" }
            }
          }
        }
      }
    }
  }
}