> ## 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.

# API Overview

> Complete guide to the Penbox API endpoints and capabilities

The Penbox API provides programmatic access to Penbox's form management, case management, and document processing capabilities. This comprehensive guide covers all API capabilities, response formats, and best practices.

<Card title="New to the API?" icon="rocket" href="/api-reference/introduction">
  Start with the Quick Start guide to make your first API call
</Card>

## API Categories

### Cases

Manage multi-step workflows with contacts and structured data.

**Key Endpoints:**

* `GET /cases` - List cases with filtering
* `POST /cases` - Create a new case
* `GET /cases/{id}` - Get case details with steps
* `POST /cases/{id}/data` - Update case data fields
* `POST /cases/{id}` - Archive or unarchive a case
* `GET /cases/count` - Count cases

**Common Use Cases:**

* Create structured workflows for customer onboarding, support tickets, etc.
* Track case progress through multiple steps
* Manage contacts associated with cases
* Update case data programmatically

### Forms

Manage forms and responses.

**Key Endpoints:**

* `GET /forms` - List forms with filtering and pagination
* `POST /forms` - Create a new form
* `GET /forms/{id}` - Get form details including responses
* `PATCH /forms/{id}` - Update form status or properties
* `GET /forms/count` - Count forms with optional grouping
* `GET /responses/{id}` - Get response details

**Common Use Cases:**

* Send forms to customers or partners
* Track form completion status
* Archive or process completed forms
* Retrieve form responses with attachments

### Form Templates

Access and configure form templates and their customizations.

**Key Endpoints:**

* `GET /form_templates` - List available form templates
* `GET /form_templates/{slug}/options` - Get template configuration options
* `GET /form_templates/{slug}/steps` - Get template structure and fields

**Common Use Cases:**

* Discover available form templates
* Understand form structure before creating forms
* Access template-specific settings

### Attachments

Upload, download, and manage file attachments.

**Key Endpoints:**

* `POST /attachments` - Upload files (JSON or multipart)
* `GET /attachments/{id}` - Download single attachment
* `GET /attachments?ids=...` - Download multiple attachments as PDF

**Common Use Cases:**

* Upload documents for processing
* Download form response attachments
* Merge multiple documents into a single PDF

### Document Intelligence

Extract structured data from documents using AI.

**Key Endpoints:**

* `POST /document-intelligence` - Create extraction job
* `GET /document-intelligence/{id}` - Get extraction results

**Common Use Cases:**

* Extract invoice data (number, date, amount)
* Parse ID documents
* Process contracts and forms automatically

### Signatures

Access digital signatures created through form responses.

**Key Endpoints:**

* `GET /signatures/{id}` - Get signature metadata or download file

**Common Use Cases:**

* Download signed documents
* Track signature status
* Verify signature completion

### Workspaces

List available workspaces accessible with your token.

**Key Endpoints:**

* `GET /workspaces` - List accessible workspaces

## Rate Limiting

* **100 requests per minute** per access token
* **1,000 requests per hour** per client

If you exceed the rate limit, you'll receive a `429 Too Many Requests` response. Implement exponential backoff in your integration.

## Response Format

All responses use JSON format with consistent structure:

### Single Resource Response

```json theme={null}
{
  "id": "uuid",
  "created_at": "2024-01-15T10:30:00Z",
  "status": "completed",
  "archived": false,
  ...
}
```

### Paginated Collection Response

```json theme={null}
{
  "meta": {
    "total_count": 150,
    "total_pages": 8,
    "page_size": 20,
    "current_page": 1
  },
  "data": [
    { "id": "uuid-1", ... },
    { "id": "uuid-2", ... }
  ]
}
```

### Error Response

```json theme={null}
{
  "error": "Error message",
  "statusCode": 400,
  "message": "Detailed error description"
}
```

## Pagination and Filtering

The API provides powerful pagination, sorting, and filtering capabilities on all list endpoints.

<CardGroup cols={2}>
  <Card title="Pagination & Sorting" icon="arrows-up-down" href="/api-reference/pagination-and-sorting">
    Control result size and order with `page[number]`, `page[size]`, and `sort` parameters
  </Card>

  <Card title="Advanced Filters" icon="filter" href="/api-reference/advanced-filters">
    Filter results with operators like `$eq`, `$ne`, `$gt`, `$like`, and `$extends`
  </Card>
</CardGroup>

## Common Headers

### Request Headers

* `Authorization: Bearer {token}` - Required for authentication
* `Content-Type: application/json` - For JSON request bodies
* `Accept: application/json` - Default response format (optional)

### Response Headers

* `Content-Type: application/json` - JSON responses
* `Content-Type: application/octet-stream` - Binary file downloads

## HTTP Status Codes

| Code  | Description                             |
| ----- | --------------------------------------- |
| `200` | Success                                 |
| `201` | Created                                 |
| `202` | Accepted (async processing)             |
| `400` | Bad Request - Invalid input             |
| `401` | Unauthorized - Invalid or missing token |
| `403` | Forbidden - No access to resource       |
| `404` | Not Found - Resource doesn't exist      |
| `413` | Payload Too Large                       |
| `429` | Too Many Requests - Rate limit exceeded |
| `500` | Internal Server Error                   |

## Webhooks

When creating forms, you can specify webhook URLs to receive real-time notifications about events:

```json theme={null}
{
  "webhooks": {
    "https://your-server.com/webhook": [
      "responses:completed",
      "forms:updated"
    ]
  }
}
```

Available webhook events:

* `forms:created`, `forms:updated`, `forms:deleted`
* `forms:archived`, `forms:unarchived`
* `responses:created`, `responses:updated`, `responses:deleted`
* `responses:completed`

## Best Practices

### 1. Use Filtering Wisely

Apply filters to reduce data transfer and improve response times.

### 2. Implement Error Handling

Always handle potential error responses and implement retry logic with exponential backoff.

### 3. Store IDs, Not Full Objects

Store resource IDs and fetch fresh data when needed to avoid stale data.

### 4. Use Webhooks for Real-Time Updates

Instead of polling, use webhooks to receive notifications when forms are completed.

### 5. Batch Operations

When possible, use batch endpoints like `POST /cases/{id}/data` to update multiple fields at once.

### 6. Respect Rate Limits

Implement proper rate limiting in your application to avoid `429` errors.

## Support

For questions or issues with the API:

* Check the detailed endpoint documentation
* Review the [Advanced Filters](/api-reference/advanced-filters) guide
* Contact support at [support@penbox.io](mailto:support@penbox.io)

## Version History

**Current Version:** v1

The API follows semantic versioning principles. Breaking changes will be introduced in new major versions.