API Access for Developers

BreezeDoc provides a REST API for developers to integrate document workflows into applications. This guide covers API access, authentication methods, endpoints, rate limits, and getting started with the BreezeDoc API.

Prerequisites

  • Plan: Pro or Agency plan required (API not available on Free plan)
  • Account: Active BreezeDoc account with API access enabled
  • Technical Knowledge: Basic understanding of REST APIs and HTTP requests
  • Tools: API client (Postman, curl, or programming language HTTP library)

What is the BreezeDoc API?

The BreezeDoc API is a RESTful API that allows you to:

  • Create Documents: Programmatically create documents from templates or PDFs
  • Send Documents: Send documents to recipients for signing
  • Track Status: Monitor document progress and completion
  • Manage Templates: Create and retrieve templates
  • Manage Recipients: Add recipients and track their status
  • Team Operations: Manage team documents and templates (Agency plan)
  • User Management: Retrieve user information and settings

Authentication Methods

BreezeDoc API supports two authentication methods:

Personal Access Tokens (Recommended for Individual Use)

Simple authentication using a long-lived token:

  • Use Case: Personal scripts, internal tools, testing
  • Security: Single token with full account access
  • Setup: Generate in BreezeDoc settings
  • Format: Bearer token in Authorization header

OAuth 2.0 (Recommended for Applications)

Standard OAuth flow for third-party applications:

  • Use Case: Public applications, multi-user integrations
  • Security: User-specific permissions, token refresh
  • Setup: Register OAuth application in BreezeDoc
  • Format: Standard OAuth 2.0 authorization code flow

Getting Started with the API

Step 1: Enable API Access

  1. Upgrade to Pro or Agency plan if needed.
  2. API access is automatically enabled on Pro and Agency plans.
  3. Go to Settings ➜ Integrations ➜ API.

Step 2: Choose Authentication Method

For quick testing or personal use:

  1. Go to Settings ➜ Integrations ➜ API.
  2. Click Generate Personal Access Token.
  3. Copy the token (shown only once).
  4. Store securely (treat like a password).

For building applications:

  1. Go to Settings ➜ Integrations ➜ OAuth Apps.
  2. Click Create OAuth Application.
  3. Enter application details (name, redirect URL).
  4. Receive Client ID and Client Secret.
  5. Implement OAuth 2.0 flow in your application.

Step 3: Make Your First API Request

Example: Get Current User Information

curl -X GET https://api.breezedoc.com/v1/me \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Response:

{
  "id": "user_123",
  "email": "user@example.com",
  "name": "John Doe",
  "plan": "pro",
  "documentsUsed": 5,
  "documentsLimit": 20
}

Available API Endpoints

User Endpoints

  • GET /api/me  - Get current user information
  • POST /api/users  - Create new user (admin only)

Document Endpoints

  • GET /api/documents  - List all documents
  • POST /api/documents  - Create new document
  • GET /api/documents/{id}  - Get document details
  • GET /api/documents/{id}/recipients  - List document recipients
  • POST /api/documents/{id}/send  - Send document to recipients

Template Endpoints

  • GET /api/templates  - List all templates
  • GET /api/templates/{id}  - Get template details
  • POST /api/templates/{id}/create-document  - Create document from template

Recipient Endpoints

  • GET /api/recipients  - List all recipients across documents

Team Endpoints (Agency Plan)

  • GET /api/teams/{id}/documents  - List team documents
  • GET /api/teams/{id}/templates  - List team templates

Rate Limits

API requests are rate-limited to ensure system stability:

  • Rate Limit: 60 requests per minute per account
  • Headers: Rate limit info included in response headers:
    • X-RateLimit-Limit : Maximum requests per minute (60)
    • X-RateLimit-Remaining : Requests remaining in current window
    • X-RateLimit-Reset : Timestamp when limit resets
  • Exceeded Limit: Returns HTTP 429 (Too Many Requests)

Rate Limit Best Practices

  • Monitor rate limit headers in responses
  • Implement exponential backoff on 429 errors
  • Cache responses when possible
  • Batch operations instead of individual requests
  • Use webhooks for event-driven workflows (future feature)

Common API Workflows

Workflow 1: Create and Send Document from Template

  1. List templates: GET /api/templates
  2. Create document: POST /api/templates/{id}/create-document
  3. Add recipients: Include in document creation payload
  4. Send document: POST /api/documents/{id}/send

Workflow 2: Check Document Status

  1. List documents: GET /api/documents
  2. Get document details: GET /api/documents/{id}
  3. Check recipients: GET /api/documents/{id}/recipients
  4. Parse status: Check each recipient's completion status

Workflow 3: Bulk Document Creation

  1. Get template: GET /api/templates/{id}
  2. Loop through recipients: Create one document per recipient
  3. Send all documents: Use send endpoint for each document

Error Handling

API errors return standard HTTP status codes:

  • 200 OK: Request successful
  • 201 Created: Resource created successfully
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Invalid or missing authentication
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource does not exist
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server-side error

Error Response Format

{
  "error": "invalid_request",
  "message": "Missing required field: recipient_email",
  "code": 400
}

API Best Practices

  • Security: Never expose API tokens in client-side code or public repositories
  • HTTPS Only: All API requests must use HTTPS
  • Error Handling: Implement retry logic with exponential backoff
  • Logging: Log all API requests and responses for debugging
  • Versioning: Use versioned endpoints (currently /v1/)
  • Testing: Test in development environment before production
  • Monitoring: Monitor rate limits and API health

Troubleshooting

Issue: 401 Unauthorized error

Fix: Verify your access token is correct and not expired. Ensure you're including the Authorization header: Authorization: Bearer YOUR_TOKEN . Check that API access is enabled on your Pro or Agency plan.

Issue: 429 Rate limit exceeded

Fix: Wait until the rate limit window resets (check X-RateLimit-Reset header). Implement exponential backoff. Reduce request frequency or batch operations.

Issue: Cannot access API - Feature not available

Fix: API access requires Pro or Agency plan. Upgrade from Free plan to enable API access. Verify upgrade is active in Settings ➜ Billing.

Issue: CORS errors in browser

Fix: API should be called from server-side code, not directly from browsers. Use a backend proxy to make API calls. Never expose API tokens in client-side JavaScript.

FAQ

Q: Is the BreezeDoc API free to use?

A: API access requires a Pro ($19/month) or Agency ($49/month) plan. It is not available on the Free plan.

Q: What is the API rate limit?

A: 60 requests per minute per account. Rate limit headers are included in all API responses.

Q: Can I use the API on the Free plan?

A: No, API access is only available on Pro and Agency plans. Upgrade to enable API access.

Q: Is there API documentation?

A: Yes, complete API documentation is available at api.breezedoc.com/docs with interactive examples and SDKs.


Need more help? Contact our support team – we are here to help!

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Related Articles