> ## Documentation Index > Fetch the complete documentation index at: https://staging.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. # Edit a draft package > Changes a DRAFT package's details; any other status is a 409. Every field is optional, and a field left out keeps its current value. `recipients` replaces the whole list: keep a recipient by carrying their `id`. `metadata` is merged over the current custom field values; unknown keys are rejected with 422. `mergeValues` is checked against each merge field's type and options, and a bad value is a 422. Requires canSendPackages, and the same draft access the app requires. ## OpenAPI ````yaml /api-reference/openapi.json put /api/v1/packages/{packageId} 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/{packageId}: put: tags: - Packages summary: Edit a draft package description: >- Changes a DRAFT package's details; any other status is a 409. Every field is optional, and a field left out keeps its current value. `recipients` replaces the whole list: keep a recipient by carrying their `id`. `metadata` is merged over the current custom field values; unknown keys are rejected with 422. `mergeValues` is checked against each merge field's type and options, and a bad value is a 422. Requires canSendPackages, and the same draft access the app requires. operationId: putPackagesByPackageId parameters: - schema: type: string required: true name: packageId in: path - 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. An empty string clears it. example: Jane's signed agreement ahead of her 12 October start. signingMode: allOf: - $ref: '#/components/schemas/SigningMode' - description: >- How recipients are walked through signing. PARALLEL invites every recipient at once; SEQUENTIAL invites one at a time in `order`; WORKFLOW follows the template's workflow, asking recipients its questions as they open the package. emailSubject: type: string description: >- The subject line of the invitation email. An empty string restores the default. 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 recipients: type: array items: $ref: '#/components/schemas/RecipientUpdate' minItems: 1 maxItems: 100 description: >- Replaces the recipients, in signing order. Carry a recipient's `id` to keep them and the fields assigned to them; a recipient left out is removed along with their fields' assignment. accessCode: type: string nullable: true minLength: 4 maxLength: 64 description: >- A password every signing recipient must enter before signing, 4 to 64 characters. Null removes it; leaving it out keeps the current one. example: harbour-4821 reminderIntervalDays: type: integer nullable: true 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 expirationDays: type: integer nullable: true 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 nullable: true 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 minLength: 1 description: >- Replaces the package's tags. Tags the organisation does not have yet are created. 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. example: cost_centre: CC-4410 region: Auckland mergeValues: type: object additionalProperties: type: string description: >- Values for the package's merge fields, keyed by merge field key. Each is checked against the field's type and list options. example: start_date: '2026-10-12' responses: '200': description: Success content: application/json: schema: type: object properties: data: type: object properties: id: type: string description: The package's id. example: cmg4v8q2k0001s7xh3b9d2f6a warnings: type: array items: type: string description: >- Parts of the package's workflow that no longer apply after the change and were dropped, such as a card naming a removed recipient. Empty when nothing was dropped. example: [] required: - id - warnings required: - data '400': description: >- The body is not valid JSON, a host is not a member who may host, or the recipient count is over the plan's limit 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' '404': description: No package with that id that the caller can edit content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- The package is not a DRAFT, or another member is editing it in the app right now 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 RecipientUpdate: 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 applies when `signingMode` is SEQUENTIAL. example: 60 id: type: string minLength: 1 description: >- The id of a recipient the package already has, to keep them (and the fields assigned to them) while changing their details. Leave it out for a new recipient; details a kept recipient leaves out keep their current value. example: cmg4v8q2k0002s7xh6k4m1p9c required: - name description: A person the package goes to, as sent when editing a draft. 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_* ````