Skip to main content
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.

New to the API?

Start with the Quick Start guide to make your first API call

​
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
  • 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

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

​
Paginated Collection Response

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

​
Error Response

{
  "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.

Pagination & Sorting

Control result size and order with page[number], page[size], and sort parameters

Advanced Filters

Filter results with operators like $eq, $ne, $gt, $like, and $extends

​
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

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

​
Webhooks

When creating forms, you can specify webhook URLs to receive real-time notifications about events: 
{
  "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:

​
Version History

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