> ## 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. # Save a package document's fields > Applies `ops` to the fields of one document on a DRAFT package, in order and all or nothing. Requires canSendPackages. ## OpenAPI ````yaml /api-reference/openapi.json put /api/v1/packages/{packageId}/fields 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}/fields: put: tags: - Packages summary: Save a package document's fields description: >- Applies `ops` to the fields of one document on a DRAFT package, in order and all or nothing. Requires canSendPackages. operationId: putPackagesByPackageIdFields 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: documentId: type: string minLength: 1 description: >- The document whose fields to change. It must be attached to the package or template in the path; any other document is a 404. example: cmg1p4k2a0007v9x0d8n3f5t2 ops: type: array items: oneOf: - type: object properties: type: type: string enum: - add description: >- Write the field with this `id`, creating it when it does not exist. Behaves the same as `update`. example: add field: type: object properties: id: type: string minLength: 1 description: >- The field's id. Choose it yourself for a new field (any non-empty string, a cuid or uuid is conventional) and reuse it to update or remove that field later. An id already used by a field on another document is a 404. example: cmg1p4k2a000bv9x0f2r6s8u4 pageNumber: type: integer minimum: 0 exclusiveMinimum: true description: The page the field sits on, counting from 1. example: 1 fieldType: $ref: '#/components/schemas/WritableFieldType' position: type: object properties: x: type: number minimum: 0 maximum: 1 description: >- Distance from the page's left edge to the field's left edge, as a fraction of the page width (0 is the left edge, 1 the right). example: 0.12 'y': type: number minimum: 0 maximum: 1 description: >- Distance from the page's top edge to the field's top edge, as a fraction of the page height (0 is the top, 1 the bottom). example: 0.78 required: - x - 'y' description: >- The field's top-left corner, as fractions of the page's width and height. Fractions keep the placement valid whatever the page's pixel size. example: x: 0.12 'y': 0.78 size: type: object properties: width: type: number minimum: 0 exclusiveMinimum: true maximum: 1 description: >- The field's width as a fraction of the page width. example: 0.28 height: type: number minimum: 0 exclusiveMinimum: true maximum: 1 description: >- The field's height as a fraction of the page height. example: 0.05 required: - width - height description: >- The field's extent, as fractions of the page's width and height. Both must be above 0, and the field must end on the page: `position.x + size.width` and `position.y + size.height` are at most 1. example: width: 0.28 height: 0.05 isRequired: type: boolean description: >- Whether the recipient must complete the field before finishing. Defaults to true when left out. example: true placeholder: type: string nullable: true description: >- Text shown inside the empty field to say what goes there, in place of the default for its type (such as "Click to sign"). For a `label` field it is the text itself. Null or absent clears it. example: Sign here dropdownOptions: type: array items: type: string description: One choice, shown as written. example: Full time description: >- The choices a `dropdown` field offers, in display order. Ignored for other types and treated as empty when left out. example: - Full time - Part time - Casual radioGroup: type: string nullable: true description: >- For a `radio` field, the name shared by every option in the same group; the recipient picks one option per group. Null or absent for other types. example: employment-type recipientId: type: string nullable: true minLength: 1 description: >- The package recipient who completes this field, one of the ids `POST /api/v1/packages` returned. Null or absent leaves the field unassigned, so nobody is asked to fill it. A recipient of another package is a 400. example: cmg1p4k2a0005v9x0r1c9t3m7 required: - id - pageNumber - fieldType - position - size description: The field's full placement. required: - type - field - type: object properties: type: type: string enum: - update description: >- Write the field with this `id`, creating it when it does not exist. Every value is replaced, so send the whole placement, not a patch. example: update field: type: object properties: id: type: string minLength: 1 description: >- The field's id. Choose it yourself for a new field (any non-empty string, a cuid or uuid is conventional) and reuse it to update or remove that field later. An id already used by a field on another document is a 404. example: cmg1p4k2a000bv9x0f2r6s8u4 pageNumber: type: integer minimum: 0 exclusiveMinimum: true description: The page the field sits on, counting from 1. example: 1 fieldType: $ref: '#/components/schemas/WritableFieldType' position: type: object properties: x: type: number minimum: 0 maximum: 1 description: >- Distance from the page's left edge to the field's left edge, as a fraction of the page width (0 is the left edge, 1 the right). example: 0.12 'y': type: number minimum: 0 maximum: 1 description: >- Distance from the page's top edge to the field's top edge, as a fraction of the page height (0 is the top, 1 the bottom). example: 0.78 required: - x - 'y' description: >- The field's top-left corner, as fractions of the page's width and height. Fractions keep the placement valid whatever the page's pixel size. example: x: 0.12 'y': 0.78 size: type: object properties: width: type: number minimum: 0 exclusiveMinimum: true maximum: 1 description: >- The field's width as a fraction of the page width. example: 0.28 height: type: number minimum: 0 exclusiveMinimum: true maximum: 1 description: >- The field's height as a fraction of the page height. example: 0.05 required: - width - height description: >- The field's extent, as fractions of the page's width and height. Both must be above 0, and the field must end on the page: `position.x + size.width` and `position.y + size.height` are at most 1. example: width: 0.28 height: 0.05 isRequired: type: boolean description: >- Whether the recipient must complete the field before finishing. Defaults to true when left out. example: true placeholder: type: string nullable: true description: >- Text shown inside the empty field to say what goes there, in place of the default for its type (such as "Click to sign"). For a `label` field it is the text itself. Null or absent clears it. example: Sign here dropdownOptions: type: array items: type: string description: One choice, shown as written. example: Full time description: >- The choices a `dropdown` field offers, in display order. Ignored for other types and treated as empty when left out. example: - Full time - Part time - Casual radioGroup: type: string nullable: true description: >- For a `radio` field, the name shared by every option in the same group; the recipient picks one option per group. Null or absent for other types. example: employment-type recipientId: type: string nullable: true minLength: 1 description: >- The package recipient who completes this field, one of the ids `POST /api/v1/packages` returned. Null or absent leaves the field unassigned, so nobody is asked to fill it. A recipient of another package is a 400. example: cmg1p4k2a0005v9x0r1c9t3m7 required: - id - pageNumber - fieldType - position - size description: The field's full placement. required: - type - field - type: object properties: type: type: string enum: - remove description: >- Delete the field with this `id`. Removing an id that does not exist is not an error. example: remove field: type: object properties: id: type: string minLength: 1 description: The id of the field to delete. example: cmg1p4k2a000bv9x0f2r6s8u4 required: - id description: Which field to delete. required: - type - field description: >- The changes to apply, in order, as one transaction: if any operation fails, none is kept. An empty list is accepted and changes nothing. required: - documentId - ops responses: '200': description: Success content: application/json: schema: type: object properties: data: type: object properties: packageId: type: string description: The package whose document was changed. example: cmg1p4k2a0003v9x0hq7d2e1s required: - packageId required: - data '400': description: >- The body is not valid JSON, the package is not a DRAFT, or a `recipientId` belongs to another package 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 is visible to the caller, the document is not attached to it, or a field `id` belongs to another document content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: >- Another member is editing the package in the app right now; try again once they are done 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: WritableFieldType: type: string enum: - text - signature - date - initial - comment - name - email - company - title - number - checkbox - radio - dropdown - label description: >- What the field collects. The same values as `FieldType`, less `formula`, `payment` and `attachment`, which cannot be placed through the API yet. example: signature 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 securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: fsk_* ````