Public API v1

Overview

The BlueClerk Public API v1 lets builders, contractors, and integrators build custom apps, sync data, and automate workflows. Authenticate via OAuth 2.0 with PKCE, access 12 REST endpoints for leads, tickets, jobs, properties, estimates, invoices, and contacts, and receive real-time webhook notifications when records change. Available on paid plans with per-tier rate limits.

NEW: Paid plan requirement - The Public API now requires an active paid subscription plan (STARTER or higher). Free trial users must upgrade to use OAuth authorization and API endpoints. Free tier tokens are rejected with 403 errors.

Authentication

OAuth 2.0 Authorization Code Flow with PKCE

The API uses OAuth 2.0 for secure authentication:

1. Register your client - Contact the BlueClerk partners team or use the CLI tool to get a client ID and secret
2. Redirect users to /oauth/authorize with your client ID, redirect URI, and PKCE code challenge
3. User authorizes your app and grants permissions
4. Exchange authorization code for access token at /oauth/token
5. Include token in Authorization header: Bearer YOUR_ACCESS_TOKEN

Plan Requirements

• Paid plan required - Users must have STARTER, PRO, or HIGH plan to authorize OAuth apps
• Free trial blocked - Free trial users see an error message prompting them to upgrade
• Consent screen - Shows plan requirement and features gated by subscription tier

PKCE Flow

PKCE (Proof Key for Code Exchange) adds security for public clients:

1. Generate code verifier - Random 43-128 character string
2. Create code challenge - Base64URL(SHA256(code_verifier))
3. Include in /oauth/authorize - Add code_challenge and code_challenge_method=S256
4. Include verifier in /oauth/token - Add code_verifier when exchanging code

Endpoints

Authorization

GET /oauth/authorize

Initiates OAuth flow - redirects user to consent screen.

Query Parameters:

• client_id (required) - Your OAuth client ID
• redirect_uri (required) - Must match registered redirect URI
• scope (required) - Space-separated list of requested scopes
• state (recommended) - CSRF protection token
• response_type (required) - Must be "code"
• code_challenge (required for PKCE) - Base64URL-encoded SHA256 hash
• code_challenge_method (required for PKCE) - Must be "S256"

POST /oauth/token

Exchanges authorization code for access token.

Body Parameters:

• grant_type (required) - Must be "authorization_code"
• code (required) - Authorization code from consent screen
• redirect_uri (required) - Must match authorization request
• client_id (required) - Your OAuth client ID
• client_secret (required) - Your OAuth client secret
• code_verifier (required for PKCE) - Original random string

Response:

{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "tickets.read jobs.read"
}

API Root

GET /api

Redirects to public API documentation.

Response: 302 redirect to https://github.com/blueclerk/api-docs

This endpoint is helpful for partners exploring the API - instead of hitting /api and getting a 404, they're automatically redirected to the documentation site.

Leads

GET /api/v1/leads

Fetch all leads for the authenticated company.

Headers:

• Authorization: Bearer YOUR_ACCESS_TOKEN

Response:

{
  "leads": [
    {
      "id": "lead_123",
      "name": "John Smith",
      "email": "john@example.com",
      "phone": "555-1234",
      "status": "new",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

Tickets

GET /api/v1/tickets

Fetch all tickets for the authenticated company.

POST /api/v1/tickets

Create a new ticket.

Body:

{
  "customerId": "cust_123",
  "propertyId": "prop_456",
  "description": "Leaky faucet in master bathroom",
  "priority": "high"
}

Jobs

GET /api/v1/jobs

Fetch all jobs for the authenticated company.

POST /api/v1/jobs

Create a new job.

Body:

{
  "ticketId": "ticket_123",
  "scheduledDate": "2024-01-20T14:00:00Z",
  "assignedTo": "user_456"
}

Properties

GET /api/v1/properties

Fetch all properties for the authenticated company.

POST /api/v1/properties

Create a new property.

Body:

{
  "address": "123 Main St",
  "city": "Austin",
  "state": "TX",
  "zip": "78701",
  "ownerId": "cust_123"
}

Estimates

GET /api/v1/estimates

Fetch all estimates for the authenticated company.

POST /api/v1/estimates

Create a new estimate.

Body:

{
  "customerId": "cust_123",
  "lineItems": [
    {
      "description": "Labor",
      "quantity": 2,
      "unitPrice": 75.00
    }
  ]
}

Invoices

GET /api/v1/invoices

Fetch all invoices for the authenticated company.

POST /api/v1/invoices

Create a new invoice.

Body:

{
  "customerId": "cust_123",
  "lineItems": [
    {
      "itemId": "item_456",
      "quantity": 1,
      "unitPrice": 150.00
    }
  ],
  "dueDate": "2024-02-01"
}

Contacts

GET /api/v1/contacts

Fetch all contacts for the authenticated company.

POST /api/v1/contacts

Create a new contact.

Body:

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "555-5678",
  "companyId": "company_123"
}

Webhooks

Subscribe to real-time events when records change.

Supported Events

• ticket.created
• ticket.updated
• job.created
• job.completed
• invoice.sent
• invoice.paid
• estimate.approved

Webhook Payload

{
  "event": "ticket.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "id": "ticket_123",
    "customerId": "cust_456",
    "description": "Leaky faucet"
  }
}

Configuring Webhooks

Contact the BlueClerk partners team to register webhook URLs for your OAuth client.

Rate Limits

Rate limits are enforced per company and tier:

• FREE: 0 requests/hour (blocked)
• STARTER: 100 requests/hour
• PRO: 500 requests/hour
• HIGH: 2,000 requests/hour

**