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
  • Invoice Management: Create, send, and track invoices programmatically

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

BreezeDoc API Settings page showing OAuth Clients and Personal Access Tokens sections

  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://breezedoc.com/api/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

Invoice Endpoints

  • GET /api/invoices    - List all invoices (supports status filter: draft, sent, paid)
  • POST /api/invoices    - Create new invoice with line items
  • GET /api/invoices/{id}    - Get invoice details
  • PUT /api/invoices/{id}    - Update invoice (draft or sent only)
  • DELETE /api/invoices/{id}    - Delete invoice (draft only)
  • POST /api/invoices/{id}/send    - Send invoice to customer

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

Workflow 4: Create and Send Invoice via API

  1. Create invoice: POST /api/invoices     with customer_email, currency, description, payment_due, and items array
  2. Add line items: Include items with description, details (optional), quantity, and unit_price
  3. Attach payment methods: Include payment_platform_ids array with your connected Stripe/PayPal IDs
  4. Auto-send: Set send: true     to create and send in one request

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