API Basics

API Basics

If you're a developer or you have one, HandyBook's REST API gives you full programmatic access to your data — for custom integrations, internal tools, reporting, or migration.

What the API can do

Every action you can do in the HandyBook UI is also available via API:

• Create / read / update / delete customers, jobs, quotes, invoices, payments, expenses
• Trigger drip campaigns
• Manage forms and submissions
• Read reports
• Listen for events (via webhooks)

Getting started

Get an API key

1. Settings → Developer → API Keys
2. Click Generate Key
3. Name it (e.g. "Internal dashboard")
4. Copy the key — it's shown only once
5. Set permissions (read-only, full access, scoped)

API keys can be revoked any time.

First request

curl https://api.handybook.app/v1/customers \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns a JSON list of your customers.

Documentation

Full docs at handybook.app/docs/api. Includes:

• All endpoints with parameters
• Sample requests in cURL, JavaScript, Python, Ruby
• Response schemas
• Error codes
• Pagination

Rate limits

• 100 requests / minute per API key (1,000 / minute for Business tier)
• 5,000 requests / hour
• Bulk endpoints (creating 100 customers at once, etc.) count as a single request

Hitting limits returns HTTP 429. Back off and retry.

Authentication

All requests must include:

Authorization: Bearer YOUR_API_KEY

Keys should be stored server-side, never in browser code. Front-end apps should call your own backend, which calls HandyBook.

Pagination

List endpoints return up to 100 items at a time. Use cursor pagination:

GET /v1/customers?limit=100&starting_after=cust_abc123

The response includes has_more and the cursor for the next page.

Webhooks

For real-time event notifications instead of polling:

1. Settings → Developer → Webhooks → + New Webhook
2. Enter your endpoint URL
3. Pick which events to subscribe to (or all)
4. Save — HandyBook sends a test event to verify

When events fire (e.g. invoice paid), HandyBook POSTs JSON to your URL. Verify the signature header to confirm authenticity.

See Webhooks article for details.

Common use cases

Custom dashboard

Pull /v1/jobs?status=in_progress into your own internal dashboard for techs in the field.

Migration / sync

Bulk move customer data between HandyBook and another system.

Custom reports

Pull raw data, do whatever analysis you want, output anywhere.

Embedded scheduling

Build a custom booking flow on your own website that creates HandyBook jobs via API.

Mobile app integration

If you have a custom mobile app, it can authenticate against HandyBook for service-pro tools.

SDKs

Official SDKs:

• JavaScript / TypeScript (@handybook/sdk)
• Python (handybook-python)

Community SDKs:

• Ruby
• PHP
• Go

Or use any HTTP library — it's just JSON over HTTPS.

Sandbox / test mode

For development and testing:

• Sandbox API at sandbox-api.handybook.app — separate test data, doesn't touch your real account
• Sandbox API keys generated separately
• Sandbox doesn't actually send emails or charge cards

Use sandbox for any code changes before pointing at production.

Versioning

The API is versioned via URL (/v1/). New breaking changes go in a new version. Old versions are supported for at least 12 months after deprecation.

FAQ

Do I need to pay for API access? API access is included on all tiers. Higher tiers get higher rate limits.

Can the API trigger drip campaigns? Yes — POST to /v1/campaigns/{id}/enroll with a customer ID.

Is there an OpenAPI spec? Yes — at handybook.app/docs/api/openapi.json. Use to generate clients.

What happens to the API if I disconnect Stripe? API still works for everything except payment-related actions (charging, refunding). Read access to historical payments still works.

Can my API key be scoped to read-only? Yes — when generating, pick the scope: read-only, write-only on certain resources, full access. Best practice: minimum necessary permissions per key.