Skip to content
EsperWorksEsperWorks

Integration Guide

Choose the integration model that fits your use case, follow the steps, and start building. Every example uses the Partner API under /api/v1.

Choose your path

Direct Integration

Automate your own business

You control one EsperWorks business and want to automate its workflows — sync clients from your CRM, auto-generate invoices, or embed payments in your app.

  1. 1Sign up at tryesperworks.com/signup and complete your business profile.
  2. 2Go to Dashboard → Developer API and create an API key.
  3. 3Select the scopes your integration needs (e.g. invoices:write + clients:write).
  4. 4Copy the key — it is shown only once. Store it as an environment variable.
  5. 5Make API requests with Authorization: Bearer ew_live_...
CRM syncAuto-invoicingEmbedded paymentsInternal dashboards
Quickstart →API keys →

OAuth App

Build for many businesses

You are building a platform or SaaS that many EsperWorks businesses will connect to. Each business authorizes your app once, and you receive a scoped API key per business.

  1. 1Register a developer account at /developer/register.
  2. 2Create an OAuth app in your developer dashboard.
  3. 3Redirect business owners to GET /oauth/authorize with your client_id, scopes, and redirect_uri.
  4. 4After approval, exchange the authorization code for an access token via POST /oauth/token.
  5. 5Use the access_token as a Bearer token. All requests are scoped to the authorizing business.
Accounting integrationsPayroll platformsMarketplacesAgency tools
OAuth flow →Register app →

Common patterns

CRM → Clients → Invoices

Poll or webhook from your CRM to detect new deals. Create a client via POST /clients, then create and send an invoice via POST /invoices and POST /invoices/{id}/send.

E-commerce → Quick Charge

When a customer checks out, call POST /quick-charge with amount, currency, and client details. EsperWorks auto-creates the client and invoice, returns a payment_url, and fires webhooks on payment.

Payment webhooks

Set a webhook_url on your API key. Listen for invoice.paid and payment.received to update your internal systems in real time.

Read-only reporting

Use GET /invoices, GET /payments, and GET /expenses with read-only scopes to build dashboards without risking data changes.

Test mode

Create a test-mode key (prefixed ew_test_) from the dashboard. Test keys skip real emails, do not call payment gateways, and let you use POST /invoices/{id}/simulate-payment to trigger webhooks without real money.

Test-mode data is not isolated. Invoices, payments, and clients created with a test key live in the same database as live data. Treat test data as real — do not rely on test mode for data separation.

Webhooks

Set a webhook_url and webhook_secret when creating an API key. EsperWorks will POST signed JSON payloads to your URL for these events:

invoice.createdA new invoice is created
invoice.sentAn invoice is emailed
invoice.viewedA client opens the payment page
invoice.paidAn invoice is fully paid
payment.receivedA payment is recorded
contract.signedBoth parties sign a contract

Verify signatures using the raw request body and your webhook_secret. EsperWorks retries failed deliveries up to 5 times with exponential backoff (10s → 30s → 90s → 4.5m → 13.5m). The idempotency_key in each payload is stable across retries — use it to deduplicate.

Rate limits

Each API key is limited to 120 requests per minute. Responses include X-RateLimit-Remaining and Retry-After headers. Implement exponential backoff on 429s.

Where to go next

Full API reference

All endpoints, scopes, and response shapes.

Webhooks

Payload format, signature verification, retries.

OAuth & Developer Apps

Multi-tenant app setup.

Errors & Rate Limits

HTTP status codes and error shapes.