prepare_free_signature_document

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "fileName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "PDF filename, 1-255 characters, ending in .pdf (case-insensitive). Required for every source. Use a filename, not a path or URL."
    },
    "chatgptFile": {
      "description": "File source option 5: actual user-attached PDF supplied through ChatGPT's file-input integration. Use the host-provided file object with download_url and file_id. Omit all other file sources; do not copy a /mnt/data path into documentUrl or invent file metadata. Supply the separate fileName and normal contract fields. The server downloads and validates the PDF; expired URLs require a fresh host-provided file reference.",
      "type": "object",
      "properties": {
        "download_url": {
          "type": "string",
          "maxLength": 8192,
          "format": "uri",
          "description": "Host-provided temporary HTTPS download URL for the attached PDF. Use the exact URL; never substitute a local path."
        },
        "file_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 512,
          "description": "Host-provided OpenAI file identifier. Not a SELISE storage file ID or document ID; not used to fetch the file."
        },
        "mime_type": {
          "description": "Optional host-provided MIME type. Actual downloaded bytes determine whether the file is a valid PDF.",
          "type": "string",
          "maxLength": 255
        },
        "file_name": {
          "description": "Optional host-provided filename metadata. The separate top-level fileName remains required.",
          "type": "string",
          "maxLength": 1024
        }
      },
      "required": [
        "download_url",
        "file_id"
      ]
    },
    "documentBase64": {
      "description": "File source option 1: actual PDF bytes encoded as raw standard Base64. Whitespace is ignored; no data URL, placeholder, local path, or fabricated content. Omit all other file sources when using this option.",
      "type": "string",
      "minLength": 1
    },
    "documentUrl": {
      "description": "File source option 2: public HTTPS link that returns the actual PDF, optionally with a short-lived signed query string. No login page, browser cookies, custom authentication headers, local/private address, or data/file URL. Omit all other file sources. The server downloads and size-checks the file. For a ChatGPT attachment, use chatgptFile through the host file-input integration.",
      "type": "string",
      "maxLength": 8192,
      "format": "uri"
    },
    "storageFileId": {
      "description": "File source option 3: exact existing SELISE storage file ID accessible using this server's configured credentials. It is not a documentId, client-specific attachment ID, or uploadId. Use an original PDF intended for a NEW document; for an already prepared document use send_prepared_signature_document. Omit all other file sources. The PDF is validated and reused without uploading again.",
      "type": "string",
      "minLength": 1,
      "maxLength": 512,
      "pattern": "^[A-Za-z0-9_-]+$"
    },
    "uploadId": {
      "description": "File source option 4: exact signed reference returned by this server's POST /uploads endpoint. Valid for one hour, until its expiresAt; do not alter it or replace it with a storage ID. Omit the other sources. Use only to begin a new preparation; it does not make preparation/send calls idempotent. An accepted/pending document must not be prepared again.",
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "description": "Document title; required and nonempty after trimming."
    },
    "ownerEmail": {
      "description": "Document owner's valid email, without surrounding whitespace. Must match an email in signatories after lowercase normalization. Being the owner does not automatically make someone a signer; preserve their intended role.",
      "type": "string",
      "format": "email",
      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    },
    "signatories": {
      "minItems": 1,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "email": {
            "description": "Participant's valid email address, without surrounding whitespace. Normalized to lowercase; must be unique within signatories.",
            "type": "string",
            "format": "email",
            "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
          },
          "firstName": {
            "type": "string",
            "minLength": 1,
            "description": "Participant's first name; required and nonempty after trimming. Obtain it from the user or a trusted source."
          },
          "lastName": {
            "type": "string",
            "minLength": 1,
            "description": "Participant's last name; required and nonempty after trimming. Obtain it from the user or a trusted source."
          },
          "role": {
            "default": "signer",
            "description": "Role values and behavior: signer signs the contract; reviewer is a view-only participant who can see the contract but has no action to perform; approver reviews and approves the contract without signing. Map a requested viewer to reviewer, and a requested reviewer who must approve to approver. The literal value viewer is not accepted. If the intended action is unclear, ask before choosing a role. Defaults to signer when omitted; set reviewer or approver explicitly for participants who must not sign. In the combined tool, every signer needs a signature coordinate; the owner need not have role signer.",
            "type": "string",
            "enum": [
              "signer",
              "reviewer",
              "approver"
            ]
          },
          "signingOrder": {
            "description": "Optional positive integer signing sequence. Supply for every participant or omit for every participant. Do not infer sequence from array position; preserve the requested order.",
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "email",
          "firstName",
          "lastName"
        ],
        "description": "One document participant, with a unique email, real first and last names, and the intended role."
      },
      "description": "Complete participant list, including the owner; at least one entry. ownerEmail must match one of the signatories' emails. Signatory emails must be unique (case-insensitive). Provide a positive integer signingOrder for every signatory or omit it for all; role defaults to signer. Ask for missing participant details; do not invent people or change their intended roles to satisfy validation. Role values and behavior: signer signs the contract; reviewer is a view-only participant who can see the contract but has no action to perform; approver reviews and approves the contract without signing. Map a requested viewer to reviewer, and a requested reviewer who must approve to approver. The literal value viewer is not accepted. If the intended action is unclear, ask before choosing a role."
    },
    "language": {
      "default": "en-US",
      "description": "Document workflow language. Supported values: en, en-US, de, de-DE. Defaults to en-US; this does not translate the uploaded PDF.",
      "type": "string",
      "enum": [
        "en",
        "en-US",
        "de",
        "de-DE"
      ]
    },
    "receiveRolloutEmail": {
      "default": true,
      "description": "Whether the document owner should receive the rollout email when the document is sent. Defaults to true. Setting this during preparation does not send the document.",
      "type": "boolean"
    }
  },
  "required": [
    "fileName",
    "title",
    "ownerEmail",
    "signatories"
  ],
  "description": "Prepare one new PDF document without sending. Provide exactly ONE file source: documentBase64 (raw standard Base64), documentUrl (public HTTPS PDF download URL, including a temporary signed URL), storageFileId (an existing SELISE storage PDF accessible to this server), uploadId (the exact short-lived reference returned by this server's HTTP POST /uploads), or chatgptFile (the host-provided file object for a PDF attached in ChatGPT). In ChatGPT, use chatgptFile via the declared file-input integration for a user attachment; its download_url and file_id are supplied by the host. Do not combine sources, invent file content or IDs, or pass local paths to the server. A bare ChatGPT attachment ID is not a documentUrl or storageFileId. Other clients can continue using the four generic sources. For binary upload, POST multipart/form-data with one file part named file to /uploads on this server's HTTP deployment, then use the returned uploadId before expiresAt; uploading does not prepare or send a document. Raw application/pdf uploads with a fileName query parameter are also accepted. The uploadId is valid for one hour; keep it private. Source PDFs are validated consistently. documentUrl must return PDF bytes without additional authentication headers; the server does not use browser cookies, login pages, or private-network URLs. It follows at most three public HTTPS redirects. Storage files and upload references are reused without a second upload. Supply fileName ending in .pdf and the normal preparation fields for every method. A file reference is not a documentId and does not mean preparation has completed. ownerEmail must match one of the signatories' emails. Signatory emails must be unique (case-insensitive). Provide a positive integer signingOrder for every signatory or omit it for all; role defaults to signer. Ask for missing participant details; do not invent people or change their intended roles to satisfy validation. Role values and behavior: signer signs the contract; reviewer is a view-only participant who can see the contract but has no action to perform; approver reviews and approves the contract without signing. Map a requested viewer to reviewer, and a requested reviewer who must approve to approver. The literal value viewer is not accepted. If the intended action is unclear, ask before choosing a role.",
  "oneOf": [
    {
      "required": [
        "documentBase64"
      ]
    },
    {
      "required": [
        "documentUrl"
      ]
    },
    {
      "required": [
        "storageFileId"
      ]
    },
    {
      "required": [
        "uploadId"
      ]
    },
    {
      "required": [
        "chatgptFile"
      ]
    }
  ]
}