> ## Documentation Index
> Fetch the complete documentation index at: https://docs.penbox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Form

> Update a form's status or properties.

Update a form's status or properties.

## Updatable Fields

| Field          | Type    | Description                                       |
| -------------- | ------- | ------------------------------------------------- |
| `archived`     | boolean | Archive or unarchive the form                     |
| `draft`        | boolean | Set draft status (true = draft, false = activate) |
| `processed`    | boolean | Mark as processed or unprocessed                  |
| `active_until` | string  | Update expiration date (ISO 8601)                 |

## Common Use Cases

### Archive a Form

Archive completed or cancelled forms to keep your list organized:

```javascript theme={null}
await fetch(`https://connect.penbox.io/v1/forms/${formId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ archived: true })
});
```

### Mark as Processed

Track which forms you've reviewed in your system:

```javascript theme={null}
await fetch(`https://connect.penbox.io/v1/forms/${formId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ processed: true })
});
```

### Activate a Draft

Activate a draft form to send it to the contact:

```javascript theme={null}
await fetch(`https://connect.penbox.io/v1/forms/${formId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ draft: false })
});
```

## Response Codes

| Code  | Description                             |
| ----- | --------------------------------------- |
| `200` | Success - Form updated successfully     |
| `400` | Bad Request - Invalid parameters        |
| `401` | Unauthorized - Invalid access token     |
| `403` | Forbidden - No access to this resource  |
| `404` | Not Found - Form doesn't exist          |
| `422` | Unprocessable - Validation failed       |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Server Error - Internal error           |

<Note>
  You can only update certain fields. To modify form data or user information, you'll need to create a new form.
</Note>


## OpenAPI

````yaml PATCH /forms/{id}
openapi: 3.0.0
info:
  title: Penbox API
  version: '1.0'
  description: >-
    The Penbox API provides programmatic access to Penbox's form management,
    case management, and document processing capabilities. Authenticate using
    Bearer tokens created at https://app.penbox.io/workspace/settings/api
servers:
  - url: https://connect.penbox.io/v1
    description: Production
  - url: https://connect.aiboov.com/v1
    description: Staging
security:
  - BearerAuth: []
paths:
  /forms/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: Form UUID
        schema:
          type: string
          format: uuid
    patch:
      summary: Update Form
      description: Update a form's status or properties.
      operationId: update-form
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              minProperties: 1
              properties:
                archived:
                  type: boolean
                  description: Archive or unarchive the form
                draft:
                  type: boolean
                  description: Set draft status
                processed:
                  type: boolean
                  description: Mark as processed or unprocessed
                active_until:
                  type: string
                  format: date-time
                  description: Update expiration date (ISO 8601)
              description: At least one field must be provided
      responses:
        '200':
          description: Form updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Form'
components:
  schemas:
    Form:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Form UUID
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        status:
          type: string
          enum:
            - draft
            - pending
            - completed
            - declined
            - processed
          description: Current form status
        archived:
          type: boolean
          description: Whether the form is archived
        archived_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when archived
        processed_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when marked as processed
        active_from:
          type: string
          format: date-time
          nullable: true
          description: When the form becomes active
        active_until:
          type: string
          format: date-time
          nullable: true
          description: When the form expires
        links:
          type: object
          properties:
            fill:
              type: string
              format: uri
              description: Public form link for the contact
            app:
              type: string
              format: uri
              description: Internal app link to view the form
          description: URLs for accessing the form
        user:
          type: object
          properties:
            anonymous:
              type: boolean
            email:
              type: string
            phone:
              type: string
            given_name:
              type: string
            family_name:
              type: string
            company_name:
              type: string
            internal_ref:
              type: string
          description: Contact information
        owner:
          type: object
          nullable: true
          properties:
            id:
              type: string
              format: uuid
            email:
              type: string
          description: Form owner information
        flow:
          type: object
          properties:
            slug:
              type: string
              description: Form template slug identifier
          description: Form template information
        data:
          type: object
          description: Pre-filled form data
        external_args:
          type: object
          nullable: true
          description: Custom metadata
        options:
          type: object
          nullable: true
          description: Form-specific options
        responses:
          type: array
          items:
            $ref: '#/components/schemas/ResponseFlat'
          description: Array of form responses
        notifications:
          type: array
          items:
            $ref: '#/components/schemas/Notification'
          description: Array of notifications sent for this form
        webhooks:
          type: object
          nullable: true
          description: Webhook URLs with event subscriptions
          additionalProperties:
            type: array
            items:
              type: string
    ResponseFlat:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Response UUID
        completed_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the response was completed
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
        data:
          type: object
          description: Form field values
        user:
          type: object
          properties:
            anonymous:
              type: boolean
            ip:
              type: string
            email:
              type: string
            phone:
              type: string
            locale:
              type: string
            given_name:
              type: string
            family_name:
              type: string
            user-agent:
              type: string
            accept-language:
              type: string
          description: User information
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/AttachmentFlat'
          description: Uploaded files
        signatures:
          type: object
          description: Signature data
        files:
          type: object
          description: Organized files by category
    Notification:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique notification identifier
        status:
          type: string
          enum:
            - pending
            - sent
            - failed
            - skipped
          description: Current status of the notification
        method:
          type: string
          enum:
            - sms
            - email
          description: Delivery method
        at:
          type: string
          format: date-time
          description: Timestamp when the notification was sent
        to:
          type: string
          nullable: true
          description: Recipient address (email or phone number)
        from:
          type: string
          nullable: true
          description: Sender address
        cc:
          type: string
          nullable: true
          description: Carbon copy recipient
        bcc:
          type: string
          nullable: true
          description: Blind carbon copy recipient
        system:
          type: boolean
          description: Whether this is a system notification
        locale:
          type: string
          description: Language/locale code (e.g., 'fr', 'en')
        template:
          type: string
          nullable: true
          description: Template name used for the notification
        variables:
          type: object
          nullable: true
          description: Template variables used in the message
        active:
          type: boolean
          description: Whether the notification is active
        error:
          type: string
          nullable: true
          description: Error message if notification failed
        message_id:
          type: string
          nullable: true
          description: External message identifier from delivery provider
        attachments:
          type: object
          nullable: true
          description: Attached files
        deleted_at:
          type: string
          format: date-time
          nullable: true
          description: Timestamp when the notification was deleted
      required:
        - id
        - status
        - method
        - at
    AttachmentFlat:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Attachment UUID
        name:
          type: string
          description: Original filename
        type:
          type: string
          description: MIME type
        scope:
          type: string
          nullable: true
          description: Attachment scope
        data:
          type: string
          nullable: true
          description: Base64-encoded file content
        metadata:
          type: object
          properties:
            size:
              type: integer
              description: File size in bytes
            width:
              type: integer
              nullable: true
            height:
              type: integer
              nullable: true
        uri:
          type: string
          format: uri
          description: Direct download URL
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: token
      description: >-
        API token (starts with pnbx_). Create at
        https://app.penbox.io/workspace/settings/api. Include as: Authorization:
        Bearer {token}

````