{
  "openapi": "3.1.0",
  "info": {
    "title": "VoidSign API",
    "description": "Public API for creating signature requests, tracking status, and downloading signed documents.",
    "version": "1.0.0"
  },
  "paths": {
    "/api/v1/requests": {
      "post": {
        "tags": [
          "VoidSign Public API v1"
        ],
        "summary": "Create a signature request",
        "description": "Upload a PDF document with positioned fields and send signature invitations to the specified signers. Each signer receives an email with a link to sign the document.",
        "operationId": "create_request_api_v1_requests_post",
        "parameters": [
          {
            "name": "X-VoidSign-Key",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Voidsign-Key"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateRequestBody"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateRequestResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad request (anchor tag not found in PDF, duplicate anchor tag in PDF)."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "403": {
            "description": "API key does not have permission for this operation."
          },
          "422": {
            "description": "Validation error (invalid base64, invalid PDF, duplicate signer refs, unknown signer_ref in field, PDF too large, page number out of bounds, date fields in multi-signer requests, conflicting signer info, telephone not yet supported)."
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "RateLimit-Policy": {
                "description": "Rate limit policy (e.g., `60;w=60`).",
                "schema": {
                  "type": "string",
                  "example": "60;w=60"
                }
              },
              "RateLimit-Limit": {
                "description": "Maximum requests per window.",
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests remaining in current window.",
                "schema": {
                  "type": "integer",
                  "example": 0
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until at least one token is available.",
                "schema": {
                  "type": "integer",
                  "example": 1
                }
              },
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "example": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error (company not found)."
          }
        }
      }
    },
    "/api/v1/requests/{request_id}": {
      "get": {
        "tags": [
          "VoidSign Public API v1"
        ],
        "summary": "Get signature request status",
        "description": "Retrieve the current status of a signature request, including per-signer details and timestamps.",
        "operationId": "get_request_api_v1_requests__request_id__get",
        "parameters": [
          {
            "name": "request_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Unique identifier of the signature request.",
              "title": "Request Id"
            },
            "description": "Unique identifier of the signature request."
          },
          {
            "name": "X-VoidSign-Key",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Voidsign-Key"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetRequestResponse"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "403": {
            "description": "Signature request belongs to a different company."
          },
          "404": {
            "description": "Signature request not found."
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "RateLimit-Policy": {
                "description": "Rate limit policy (e.g., `60;w=60`).",
                "schema": {
                  "type": "string",
                  "example": "60;w=60"
                }
              },
              "RateLimit-Limit": {
                "description": "Maximum requests per window.",
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests remaining in current window.",
                "schema": {
                  "type": "integer",
                  "example": 0
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until at least one token is available.",
                "schema": {
                  "type": "integer",
                  "example": 1
                }
              },
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "example": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/requests/{request_id}/downloads/signed": {
      "get": {
        "tags": [
          "VoidSign Public API v1"
        ],
        "summary": "Download the signed PDF",
        "description": "Download the final signed PDF document. The request must be fully signed (all signers have completed).",
        "operationId": "download_signed_pdf_api_v1_requests__request_id__downloads_signed_get",
        "parameters": [
          {
            "name": "request_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Unique identifier of the signature request.",
              "title": "Request Id"
            },
            "description": "Unique identifier of the signature request."
          },
          {
            "name": "X-VoidSign-Key",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Voidsign-Key"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "400": {
            "description": "Signature request is not fully signed yet."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "403": {
            "description": "Signature request belongs to a different company."
          },
          "404": {
            "description": "Signature request or signed file not found."
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "RateLimit-Policy": {
                "description": "Rate limit policy (e.g., `60;w=60`).",
                "schema": {
                  "type": "string",
                  "example": "60;w=60"
                }
              },
              "RateLimit-Limit": {
                "description": "Maximum requests per window.",
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests remaining in current window.",
                "schema": {
                  "type": "integer",
                  "example": 0
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until at least one token is available.",
                "schema": {
                  "type": "integer",
                  "example": 1
                }
              },
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "example": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/requests/{request_id}/downloads/audit-trail/{format}": {
      "get": {
        "tags": [
          "VoidSign Public API v1"
        ],
        "summary": "Download the audit trail",
        "description": "Download the audit trail for a fully signed request. Available in JSON or PDF format.",
        "operationId": "download_audit_trail_api_v1_requests__request_id__downloads_audit_trail__format__get",
        "parameters": [
          {
            "name": "request_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Unique identifier of the signature request.",
              "title": "Request Id"
            },
            "description": "Unique identifier of the signature request."
          },
          {
            "name": "format",
            "in": "path",
            "required": true,
            "schema": {
              "enum": [
                "json",
                "pdf"
              ],
              "type": "string",
              "description": "Output format: `json` or `pdf`.",
              "title": "Format"
            },
            "description": "Output format: `json` or `pdf`."
          },
          {
            "name": "X-VoidSign-Key",
            "in": "header",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "X-Voidsign-Key"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {}
              }
            }
          },
          "400": {
            "description": "Signature request is not fully signed yet."
          },
          "401": {
            "description": "Missing or invalid API key."
          },
          "403": {
            "description": "Signature request belongs to a different company."
          },
          "404": {
            "description": "Signature request not found."
          },
          "429": {
            "description": "Rate limit exceeded.",
            "headers": {
              "RateLimit-Policy": {
                "description": "Rate limit policy (e.g., `60;w=60`).",
                "schema": {
                  "type": "string",
                  "example": "60;w=60"
                }
              },
              "RateLimit-Limit": {
                "description": "Maximum requests per window.",
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              },
              "RateLimit-Remaining": {
                "description": "Requests remaining in current window.",
                "schema": {
                  "type": "integer",
                  "example": 0
                }
              },
              "RateLimit-Reset": {
                "description": "Seconds until at least one token is available.",
                "schema": {
                  "type": "integer",
                  "example": 1
                }
              },
              "Retry-After": {
                "description": "Seconds to wait before retrying.",
                "schema": {
                  "type": "integer",
                  "example": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RateLimitErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ApiDocument": {
        "properties": {
          "base64": {
            "type": "string",
            "title": "Base64",
            "description": "Base64-encoded PDF content. Maximum decoded size: 3 MB.",
            "examples": [
              "JVBERi0xLjQg..."
            ]
          },
          "fields": {
            "items": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/ApiSfieldSignature"
                },
                {
                  "$ref": "#/components/schemas/ApiSfieldSignatureACPGD"
                },
                {
                  "$ref": "#/components/schemas/ApiSfieldText"
                },
                {
                  "$ref": "#/components/schemas/ApiSfieldParaph"
                },
                {
                  "$ref": "#/components/schemas/ApiSfieldDate"
                }
              ]
            },
            "type": "array",
            "title": "Fields",
            "description": "List of fields (signature, paraph, text, date) to place on the document."
          }
        },
        "type": "object",
        "required": [
          "base64",
          "fields"
        ],
        "title": "ApiDocument"
      },
      "ApiSfieldDate": {
        "properties": {
          "type": {
            "type": "string",
            "const": "date",
            "title": "Type",
            "description": "Field type. Must be `date`."
          },
          "box_coordinate_system": {
            "type": "string",
            "const": "CS-CP-AD",
            "title": "Box Coordinate System",
            "description": "Coordinate system. Must be `CS-CP-AD` (center point + auto-derived dimensions)."
          },
          "box_center_x_ratio": {
            "type": "number",
            "maximum": 1.0,
            "minimum": 0.0,
            "title": "Box Center X Ratio",
            "description": "X position of the center point as a ratio (0.0-1.0) of page width."
          },
          "box_center_y_ratio": {
            "type": "number",
            "maximum": 1.0,
            "minimum": 0.0,
            "title": "Box Center Y Ratio",
            "description": "Y position of the center point as a ratio (0.0-1.0) of page height."
          },
          "page_number": {
            "type": "integer",
            "minimum": 0.0,
            "title": "Page Number",
            "description": "Zero-based page number where the field is placed."
          },
          "font_size": {
            "type": "number",
            "maximum": 100.0,
            "exclusiveMinimum": 0.0,
            "title": "Font Size",
            "description": "Font size in points."
          }
        },
        "type": "object",
        "required": [
          "type",
          "box_coordinate_system",
          "box_center_x_ratio",
          "box_center_y_ratio",
          "page_number",
          "font_size"
        ],
        "title": "ApiSfieldDate",
        "description": "Automatic date field positioned using the CS-CP-AD coordinate system (center point + auto-derived dimensions).",
        "examples": [
          {
            "box_center_x_ratio": 0.5,
            "box_center_y_ratio": 0.92,
            "box_coordinate_system": "CS-CP-AD",
            "font_size": 10.0,
            "page_number": 0,
            "type": "date"
          }
        ]
      },
      "ApiSfieldParaph": {
        "properties": {
          "type": {
            "type": "string",
            "const": "paraph",
            "title": "Type",
            "description": "Field type. Must be `paraph`."
          },
          "box_coordinate_system": {
            "type": "string",
            "const": "CS-CP-AD",
            "title": "Box Coordinate System",
            "description": "Coordinate system. Must be `CS-CP-AD` (center point + auto-derived dimensions)."
          },
          "box_center_x_ratio": {
            "type": "number",
            "maximum": 1.0,
            "minimum": 0.0,
            "title": "Box Center X Ratio",
            "description": "X position of the center point as a ratio (0.0-1.0) of page width."
          },
          "box_center_y_ratio": {
            "type": "number",
            "maximum": 1.0,
            "minimum": 0.0,
            "title": "Box Center Y Ratio",
            "description": "Y position of the center point as a ratio (0.0-1.0) of page height."
          },
          "page_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "string",
                "const": "all"
              }
            ],
            "title": "Page Number",
            "description": "Zero-based page number, or `\"all\"` to place on every page."
          },
          "signer_ref": {
            "type": "integer",
            "minimum": 1.0,
            "title": "Signer Ref",
            "description": "Reference number of the signer who must initial this field. Must match a signer `ref` in the request."
          },
          "font_size": {
            "type": "number",
            "maximum": 100.0,
            "exclusiveMinimum": 0.0,
            "title": "Font Size",
            "description": "Font size in points."
          }
        },
        "type": "object",
        "required": [
          "type",
          "box_coordinate_system",
          "box_center_x_ratio",
          "box_center_y_ratio",
          "page_number",
          "signer_ref",
          "font_size"
        ],
        "title": "ApiSfieldParaph",
        "description": "Paraph (initials) field positioned using the CS-CP-AD coordinate system (center point + auto-derived dimensions).",
        "examples": [
          {
            "box_center_x_ratio": 0.9,
            "box_center_y_ratio": 0.95,
            "box_coordinate_system": "CS-CP-AD",
            "font_size": 10.0,
            "page_number": "all",
            "signer_ref": 1,
            "type": "paraph"
          }
        ]
      },
      "ApiSfieldSignature": {
        "properties": {
          "type": {
            "type": "string",
            "const": "signature",
            "title": "Type",
            "description": "Field type. Must be `signature`."
          },
          "box_coordinate_system": {
            "type": "string",
            "const": "CS-ULP-GD",
            "title": "Box Coordinate System",
            "description": "Coordinate system. Must be `CS-ULP-GD` (upper-left point + given dimensions)."
          },
          "box_x_ratio": {
            "type": "number",
            "maximum": 1.0,
            "minimum": 0.0,
            "title": "Box X Ratio",
            "description": "X position of the upper-left corner as a ratio (0.0-1.0) of page width."
          },
          "box_y_ratio": {
            "type": "number",
            "maximum": 1.0,
            "minimum": 0.0,
            "title": "Box Y Ratio",
            "description": "Y position of the upper-left corner as a ratio (0.0-1.0) of page height."
          },
          "box_width_ratio": {
            "type": "number",
            "maximum": 1.0,
            "minimum": 0.0,
            "title": "Box Width Ratio",
            "description": "Width of the signature box as a ratio (0.0-1.0) of page width."
          },
          "box_height_ratio": {
            "type": "number",
            "maximum": 1.0,
            "minimum": 0.0,
            "title": "Box Height Ratio",
            "description": "Height of the signature box as a ratio (0.0-1.0) of page height."
          },
          "page_number": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "string",
                "const": "all"
              }
            ],
            "title": "Page Number",
            "description": "Zero-based page number, or `\"all\"` to place on every page."
          },
          "signer_ref": {
            "type": "integer",
            "minimum": 1.0,
            "title": "Signer Ref",
            "description": "Reference number of the signer who must sign this field. Must match a signer `ref` in the request."
          }
        },
        "type": "object",
        "required": [
          "type",
          "box_coordinate_system",
          "box_x_ratio",
          "box_y_ratio",
          "box_width_ratio",
          "box_height_ratio",
          "page_number",
          "signer_ref"
        ],
        "title": "ApiSfieldSignature",
        "description": "Signature field positioned using the CS-ULP-GD coordinate system (upper-left point + given dimensions).",
        "examples": [
          {
            "box_coordinate_system": "CS-ULP-GD",
            "box_height_ratio": 0.1,
            "box_width_ratio": 0.3,
            "box_x_ratio": 0.15,
            "box_y_ratio": 0.7,
            "page_number": 0,
            "signer_ref": 1,
            "type": "signature"
          }
        ]
      },
      "ApiSfieldSignatureACPGD": {
        "properties": {
          "type": {
            "type": "string",
            "const": "signature",
            "title": "Type",
            "description": "Field type. Must be `signature`."
          },
          "box_coordinate_system": {
            "type": "string",
            "const": "CS-ACP-GD",
            "title": "Box Coordinate System",
            "description": "Coordinate system. Must be `CS-ACP-GD` (anchor center point + given dimensions)."
          },
          "box_center_anchor_tag": {
            "type": "string",
            "pattern": "^VS_ANCH_[A-Za-z0-9_]+$",
            "title": "Box Center Anchor Tag",
            "description": "Name of the hidden text anchor embedded in the PDF. Must start with `VS_ANCH_`."
          },
          "box_width_ratio": {
            "type": "number",
            "maximum": 1.0,
            "exclusiveMinimum": 0.0,
            "title": "Box Width Ratio",
            "description": "Width of the signature box as a ratio (0.0-1.0) of page width."
          },
          "box_height_ratio": {
            "type": "number",
            "maximum": 1.0,
            "exclusiveMinimum": 0.0,
            "title": "Box Height Ratio",
            "description": "Height of the signature box as a ratio (0.0-1.0) of page height."
          },
          "signer_ref": {
            "type": "integer",
            "minimum": 1.0,
            "title": "Signer Ref",
            "description": "Reference number of the signer who must sign this field. Must match a signer `ref` in the request."
          }
        },
        "type": "object",
        "required": [
          "type",
          "box_coordinate_system",
          "box_center_anchor_tag",
          "box_width_ratio",
          "box_height_ratio",
          "signer_ref"
        ],
        "title": "ApiSfieldSignatureACPGD",
        "examples": [
          {
            "box_center_anchor_tag": "VS_ANCH_ABCD",
            "box_coordinate_system": "CS-ACP-GD",
            "box_height_ratio": 0.1,
            "box_width_ratio": 0.3,
            "signer_ref": 1,
            "type": "signature"
          }
        ]
      },
      "ApiSfieldText": {
        "properties": {
          "type": {
            "type": "string",
            "const": "text",
            "title": "Type",
            "description": "Field type. Must be `text`."
          },
          "box_coordinate_system": {
            "type": "string",
            "const": "CS-CP-AD",
            "title": "Box Coordinate System",
            "description": "Coordinate system. Must be `CS-CP-AD` (center point + auto-derived dimensions)."
          },
          "box_center_x_ratio": {
            "type": "number",
            "maximum": 1.0,
            "minimum": 0.0,
            "title": "Box Center X Ratio",
            "description": "X position of the center point as a ratio (0.0-1.0) of page width."
          },
          "box_center_y_ratio": {
            "type": "number",
            "maximum": 1.0,
            "minimum": 0.0,
            "title": "Box Center Y Ratio",
            "description": "Y position of the center point as a ratio (0.0-1.0) of page height."
          },
          "page_number": {
            "type": "integer",
            "minimum": 0.0,
            "title": "Page Number",
            "description": "Zero-based page number where the field is placed."
          },
          "text": {
            "type": "string",
            "maxLength": 250,
            "title": "Text",
            "description": "Text content to display in the field."
          },
          "font_size": {
            "type": "number",
            "maximum": 100.0,
            "exclusiveMinimum": 0.0,
            "title": "Font Size",
            "description": "Font size in points."
          }
        },
        "type": "object",
        "required": [
          "type",
          "box_coordinate_system",
          "box_center_x_ratio",
          "box_center_y_ratio",
          "page_number",
          "text",
          "font_size"
        ],
        "title": "ApiSfieldText",
        "description": "Static text field positioned using the CS-CP-AD coordinate system (center point + auto-derived dimensions).",
        "examples": [
          {
            "box_center_x_ratio": 0.5,
            "box_center_y_ratio": 0.95,
            "box_coordinate_system": "CS-CP-AD",
            "font_size": 12.0,
            "page_number": 0,
            "text": "Contrat de prestation N°2024-001",
            "type": "text"
          }
        ]
      },
      "ApiSigner": {
        "properties": {
          "ref": {
            "type": "integer",
            "minimum": 1.0,
            "title": "Ref",
            "description": "Reference number for this signer within the request. Used by signature/paraph fields to indicate which signer they belong to.",
            "examples": [
              1
            ]
          },
          "email": {
            "type": "string",
            "format": "email",
            "title": "Email",
            "description": "Email address of the signer. An invitation will be sent to this address.",
            "examples": [
              "jean.dupont@example.com"
            ]
          },
          "first_name": {
            "type": "string",
            "title": "First Name",
            "description": "First name of the signer.",
            "examples": [
              "Jean"
            ]
          },
          "last_name": {
            "type": "string",
            "title": "Last Name",
            "description": "Last name of the signer.",
            "examples": [
              "Dupont"
            ]
          },
          "telephone": {
            "anyOf": [
              {
                "type": "string",
                "maxLength": 12,
                "pattern": "^\\+33[67]\\d{8}$"
              },
              {
                "type": "null"
              }
            ],
            "title": "Telephone",
            "description": "Personal mobile phone number in E.164 format. Only French mobile numbers are accepted (+336… or +337…, e.g. +33612345678). Reserved for future use; providing a value will return a 422 error.",
            "examples": [
              null
            ]
          },
          "reminder_days": {
            "anyOf": [
              {
                "items": {
                  "type": "integer"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Reminder Days",
            "description": "Days after creation to send reminder emails. Example: `[3, 7]` sends reminders on day 3 and day 7.",
            "examples": [
              [
                3,
                7
              ]
            ]
          }
        },
        "type": "object",
        "required": [
          "ref",
          "email",
          "first_name",
          "last_name"
        ],
        "title": "ApiSigner"
      },
      "CreateRequestBody": {
        "properties": {
          "documents": {
            "items": {
              "$ref": "#/components/schemas/ApiDocument"
            },
            "type": "array",
            "maxItems": 1,
            "minItems": 1,
            "title": "Documents",
            "description": "List of documents. Currently limited to exactly one document."
          },
          "signers": {
            "items": {
              "$ref": "#/components/schemas/ApiSigner"
            },
            "type": "array",
            "maxItems": 24,
            "minItems": 1,
            "title": "Signers",
            "description": "List of signers (1–24). Each signer receives an email invitation."
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description",
            "description": "Optional description for the signature request.",
            "examples": [
              "Service agreement Q1 2025"
            ]
          },
          "auth_method": {
            "type": "string",
            "const": "mail",
            "title": "Auth Method",
            "description": "Authentication method for signers. Currently only `\"mail\"` is supported (email-based verification).",
            "examples": [
              "mail"
            ]
          },
          "invitation_mode": {
            "type": "string",
            "const": "voidsign_mail",
            "title": "Invitation Mode",
            "description": "How participants receive their signing invitation. Currently only `\"voidsign_mail\"` is supported (VoidSign sends invitation emails).",
            "examples": [
              "voidsign_mail"
            ]
          },
          "locales": {
            "items": {
              "type": "string",
              "const": "fr-FR"
            },
            "type": "array",
            "minItems": 1,
            "title": "Locales",
            "description": "Languages available in the signing interface. Currently only `[\"fr-FR\"]` (French) is supported.",
            "examples": [
              [
                "fr-FR"
              ]
            ]
          },
          "locale_default": {
            "anyOf": [
              {
                "type": "string",
                "const": "fr-FR"
              },
              {
                "type": "null"
              }
            ],
            "title": "Locale Default",
            "description": "Default language for the signing interface. Required when `locales` contains more than one entry. Must be a value present in `locales`.",
            "examples": [
              null
            ]
          }
        },
        "type": "object",
        "required": [
          "documents",
          "signers",
          "auth_method",
          "invitation_mode",
          "locales"
        ],
        "title": "CreateRequestBody",
        "examples": [
          {
            "auth_method": "mail",
            "description": "Service agreement Q1 2025",
            "documents": [
              {
                "base64": "JVBERi0xLjQg...",
                "fields": [
                  {
                    "box_coordinate_system": "CS-ULP-GD",
                    "box_height_ratio": 0.1,
                    "box_width_ratio": 0.3,
                    "box_x_ratio": 0.15,
                    "box_y_ratio": 0.7,
                    "page_number": 0,
                    "signer_ref": 1,
                    "type": "signature"
                  }
                ]
              }
            ],
            "invitation_mode": "voidsign_mail",
            "locales": [
              "fr-FR"
            ],
            "signers": [
              {
                "email": "jean.dupont@example.com",
                "first_name": "Jean",
                "last_name": "Dupont",
                "ref": 1,
                "reminder_days": [
                  3,
                  7
                ]
              }
            ]
          }
        ]
      },
      "CreateRequestResponse": {
        "properties": {
          "request_id": {
            "type": "string",
            "title": "Request Id",
            "description": "Unique identifier for the created signature request.",
            "examples": [
              "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
            ]
          },
          "status": {
            "type": "string",
            "const": "created",
            "title": "Status",
            "description": "Status of the request. Always `created` on success.",
            "examples": [
              "created"
            ]
          },
          "signers": {
            "items": {
              "$ref": "#/components/schemas/SignerStatusResponse"
            },
            "type": "array",
            "title": "Signers",
            "description": "List of signers with their initial status."
          }
        },
        "type": "object",
        "required": [
          "request_id",
          "status",
          "signers"
        ],
        "title": "CreateRequestResponse"
      },
      "GetRequestResponse": {
        "properties": {
          "request_id": {
            "type": "string",
            "title": "Request Id",
            "description": "Unique identifier of the signature request.",
            "examples": [
              "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "created",
              "signed",
              "cancelled"
            ],
            "title": "Status",
            "description": "Overall request status.",
            "examples": [
              "created"
            ]
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description",
            "description": "Description provided when creating the request.",
            "examples": [
              "Service agreement Q1 2025"
            ]
          },
          "created_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "format": "date-time",
            "title": "Created At",
            "description": "ISO 8601 UTC timestamp when the request was created.",
            "examples": [
              "2025-01-15T10:00:00Z"
            ]
          },
          "signed_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "format": "date-time",
            "title": "Signed At",
            "description": "ISO 8601 UTC timestamp when all signers completed, or `null`.",
            "examples": [
              null
            ]
          },
          "signers": {
            "items": {
              "$ref": "#/components/schemas/GetRequestSignerResponse"
            },
            "type": "array",
            "title": "Signers",
            "description": "List of signers with their detailed status."
          }
        },
        "type": "object",
        "required": [
          "request_id",
          "status",
          "description",
          "created_at",
          "signed_at",
          "signers"
        ],
        "title": "GetRequestResponse"
      },
      "GetRequestSignerResponse": {
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "title": "Email",
            "description": "Email address of the signer.",
            "examples": [
              "jean.dupont@example.com"
            ]
          },
          "first_name": {
            "type": "string",
            "title": "First Name",
            "description": "First name of the signer.",
            "examples": [
              "Jean"
            ]
          },
          "last_name": {
            "type": "string",
            "title": "Last Name",
            "description": "Last name of the signer.",
            "examples": [
              "Dupont"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "waiting",
              "pending",
              "signed",
              "cancelled"
            ],
            "title": "Status",
            "description": "Signing status.",
            "examples": [
              "signed"
            ]
          },
          "signed_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "format": "date-time",
            "title": "Signed At",
            "description": "ISO 8601 UTC timestamp when the signer signed, or `null` if not yet signed.",
            "examples": [
              "2025-01-15T14:30:00Z"
            ]
          }
        },
        "type": "object",
        "required": [
          "email",
          "first_name",
          "last_name",
          "status",
          "signed_at"
        ],
        "title": "GetRequestSignerResponse"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTPValidationError"
      },
      "RateLimitErrorResponse": {
        "properties": {
          "error": {
            "$ref": "#/components/schemas/_RateLimitErrorBody"
          }
        },
        "type": "object",
        "required": [
          "error"
        ],
        "title": "RateLimitErrorResponse"
      },
      "SignerStatusResponse": {
        "properties": {
          "email": {
            "type": "string",
            "format": "email",
            "title": "Email",
            "description": "Email address of the signer.",
            "examples": [
              "jean.dupont@example.com"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "waiting",
              "pending",
              "signed",
              "cancelled"
            ],
            "title": "Status",
            "description": "Current signing status.",
            "examples": [
              "pending"
            ]
          }
        },
        "type": "object",
        "required": [
          "email",
          "status"
        ],
        "title": "SignerStatusResponse"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError"
      },
      "_RateLimitErrorBody": {
        "properties": {
          "code": {
            "type": "string",
            "const": "rate_limit_exceeded",
            "title": "Code",
            "description": "Error code."
          },
          "message": {
            "type": "string",
            "title": "Message",
            "description": "Human-readable error message."
          }
        },
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "title": "_RateLimitErrorBody"
      }
    },
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-VoidSign-Key",
        "description": "API key passed via the X-VoidSign-Key header. Manage your keys from the VoidSign dashboard under Settings > API."
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ]
}