> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowsign.app/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Flowsign is one word with a lowercase s. > The REST API base URL is https://my.flowsign.app and every endpoint lives under /api/v1. > When answering API questions, cite the HTTP method and endpoint path. > API access needs the Enterprise plan and an API key with the API access permission. # Create a package > Creates a DRAFT package, or a SCHEDULED one when `scheduledAt` is set. Requires canSendPackages. ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/packages openapi: 3.0.3 info: title: Flowsign API version: 1.0.0 description: >- Public v1 API for Flowsign. Every endpoint is authenticated with a Bearer API key (prefix `fsk_`). Errors use `{ error, details? }`; success responses wrap payload data as `{ data }`. An organisation is divided into workspaces. A key is issued for one workspace and acts there on every request (see `GET /api/v1/workspaces`); `X-Workspace-Id` is optional and may only name that workspace. Packages, templates, contacts and members are scoped to the key's workspace. servers: - url: https://my.flowsign.app description: Production security: - ApiKey: [] paths: /api/v1/packages: post: tags: - Packages summary: Create a package description: >- Creates a DRAFT package, or a SCHEDULED one when `scheduledAt` is set. Requires canSendPackages. operationId: postPackages parameters: - schema: type: string description: >- The workspace the key was issued for, as returned by `GET /api/v1/workspaces`. Optional: omitting it acts in the key's workspace, and any other id is rejected with 401. required: false name: x-workspace-id in: header requestBody: required: true content: application/json: schema: type: object properties: title: type: string minLength: 1 description: The package's title, shown to recipients. example: Employment agreement for Jane Ahu description: type: string description: >- A description of the package. Defaults to "Package with N documents" when omitted. example: Jane's signed agreement ahead of her 12 October start. signingMode: $ref: '#/components/schemas/SigningMode' accessCode: type: string minLength: 4 maxLength: 64 description: >- A password every signing recipient must enter before signing, 4 to 64 characters. Stored only as a hash. example: harbour-4821 externalId: type: string minLength: 1 maxLength: 255 description: >- Your own identifier for the package, unique within the organisation. Find the package by it with `GET /api/v1/packages/by-external-id/:externalId`. A second package with the same value is a 409. example: crm-deal-48213 emailSubject: type: string description: >- The subject line of the invitation email. Omit for the default subject. example: Please sign your employment agreement emailMessage: type: string description: A message from the sender included in the invitation email. example: >- Kia ora Jane, please review and sign before your start date. Tom reminderIntervalDays: type: integer minimum: 1 description: >- Days between automatic reminders to each recipient who hasn't finished, counted from their invitation. Null or absent sends none. example: 3 scheduledAt: type: string format: date-time description: >- An ISO 8601 time to send the package automatically. Creates it as SCHEDULED rather than DRAFT, and needs at least one document. example: '2026-10-01T20:00:00.000Z' expirationDays: type: integer minimum: 1 description: >- Days the package stays open for signing, counted from when it is sent. Null or absent means it never expires. example: 30 expiryWarningDays: type: integer minimum: 1 description: >- Days before expiry at which recipients who haven't finished are warned. MUST be fewer than `expirationDays`. example: 5 tags: type: array items: type: string description: >- A tag name. Tags the organisation does not have yet are created. example: HR description: Tag names to attach to the package. example: - HR - Onboarding metadata: type: object additionalProperties: type: string maxLength: 500 description: >- A custom field value of up to 500 characters. An empty string clears the value. example: CC-4410 description: >- Custom field values keyed by custom field `key`. Every key must be a live custom field that applies to this package. An empty string clears a value. Unknown keys are rejected with 422, and so are missing required values when `scheduledAt` is set. example: cost_centre: CC-4410 region: Auckland recipients: type: array items: $ref: '#/components/schemas/RecipientInput' minItems: 1 maxItems: 100 description: >- The people the package goes to, in signing order. At least one and at most 100. documents: type: array items: type: object properties: fileName: type: string minLength: 1 description: >- The PDF's file name. The document's title is the name without its extension, and the name also forms the storage path. example: Employment agreement.pdf pageCount: type: integer minimum: 1 description: The number of pages in the PDF, at least 1. example: 4 nonce: type: string minLength: 1 description: >- A caller-chosen string echoed back on the matching document in the response, so each upload URL can be matched to its file. example: doc-1 required: - fileName - pageCount - nonce default: [] description: >- The PDFs to attach. Each comes back with an upload URL for its bytes. May be empty for a draft that takes its documents from the library through `POST /api/v1/packages/:packageId/library-documents`; a scheduled package needs at least one. required: - title - recipients responses: '201': description: Success content: application/json: schema: type: object properties: data: type: object properties: id: type: string description: The package's id. example: cmg4v8q2k0001s7xh3b9d2f6a recipients: type: array items: type: object properties: id: type: string description: >- The recipient's id, which library documents map their roles onto. example: cmg4v8q2k0002s7xh6k4m1p9c name: type: string description: The recipient's name. example: Jane Ahu email: type: string description: The recipient's email address. example: jane.ahu@example.co.nz required: - id - name - email description: The recipients in the order given. documents: type: array items: $ref: '#/components/schemas/UploadedDocument' description: >- One entry per document in the request, in the same order, with its upload URL. Sending is a separate PATCH call, refused while any document's file has not arrived. required: - id - recipients - documents required: - data '400': description: The body is not valid JSON, or a host is not a member who may host content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: Caller's plan does not include this feature (publicApi / webhooks) content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: API key present but caller lacks the required permission content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Another package in the organisation already has this `externalId` content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Request failed schema validation; details keyed by field content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limit exceeded; see `Retry-After` content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: SigningMode: type: string enum: - PARALLEL - SEQUENTIAL - WORKFLOW description: >- PARALLEL (the default) invites everyone at once; SEQUENTIAL invites one recipient at a time in the order given. WORKFLOW is refused here, since a workflow is drawn in the app or comes from a template. example: SEQUENTIAL RecipientInput: type: object properties: name: type: string minLength: 1 description: The recipient's name. example: Jane Ahu email: type: string format: email description: >- The recipient's email address. Required unless `delivery` is IN_PERSON. example: jane.ahu@example.co.nz actionType: $ref: '#/components/schemas/ActionType' delivery: $ref: '#/components/schemas/RecipientDelivery' hostRole: $ref: '#/components/schemas/RecipientHostRole' hostUserIds: type: array items: type: string minLength: 1 maxItems: 5 description: The members who may host, when `hostRole` is SPECIFIC_USER. Up to 5. example: - 8f1c2a4e-6b3d-4c9a-9e7f-2d5b1a3c4e6f hostGroupIds: type: array items: type: string minLength: 1 maxItems: 3 description: >- The member groups whose members may host, when `hostRole` is MEMBER_GROUP. Up to 3. example: - cmg1hd3x10002v8p9f6r8bt4n delay: type: integer minimum: 0 description: >- Minutes to wait after this recipient's turn begins before their invitation is sent. Only accepted when `signingMode` is SEQUENTIAL. example: 60 required: - name description: >- A person the package goes to. `actionType` defaults to SIGNER and `delivery` to EMAIL; an IN_PERSON recipient is hosted by the sender unless `hostRole` says otherwise. UploadedDocument: type: object properties: id: type: string description: The new document's id. example: cmg4v8q2k0003s7xhq1w8n5r7 nonce: type: string description: The `nonce` given for this document in the request. example: doc-1 filePath: type: string description: >- Where the file is stored once uploaded, under the workspace's prefix. Informational: upload through `uploadUrl`. example: >- cmf9x1a2b0000abcd1e2f3g4h/cmf9x1a2b0001abcd5i6j7k8l/packages/cmg4v8q2k0001s7xh3b9d2f6a/cmg4v8q2k0003s7xhq1w8n5r7-Employment agreement.pdf uploadUrl: type: string format: uri description: >- A single-use signed URL. PUT the file's bytes to it within two hours to attach the file. example: >- https://xyzcompany.supabase.co/storage/v1/object/upload/sign/pdf/cmf9x1a2b0000abcd1e2f3g4h/cmf9x1a2b0001abcd5i6j7k8l/packages/cmg4v8q2k0001s7xh3b9d2f6a/cmg4v8q2k0003s7xhq1w8n5r7-Employment%20agreement.pdf?token=eyJhbGciOiJIUzI1NiJ9.example required: - id - nonce - filePath - uploadUrl description: A document created by an upload request, with the URL its bytes go to. Error: type: object properties: error: type: string description: What went wrong, in plain words. example: 'Missing permission: canSendPackages' details: type: object additionalProperties: type: array items: type: string description: >- Validation problems keyed by field path. Present only on 422 responses. example: recipients.0.email: - Invalid email required: - error ActionType: type: string enum: - SIGNER - VIEWER - CC description: >- What the recipient does with the package. SIGNER completes fields and signs; VIEWER can open and read the package while it is out but has no fields; CC only receives the finished copy by email and never gets a signing session. example: SIGNER RecipientDelivery: type: string enum: - EMAIL - IN_PERSON description: >- How the recipient receives the package. EMAIL sends them an invitation; IN_PERSON sends no email, and a host opens the session and hands the device over. example: EMAIL RecipientHostRole: type: string enum: - SENDER - SPECIFIC_USER - MEMBER_GROUP description: >- Who may host an IN_PERSON recipient's session. SENDER is whoever sent the package; SPECIFIC_USER is one of `hostUserIds`; MEMBER_GROUP is any member of `hostGroupIds`. example: SENDER securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: fsk_* ````