Developer API

Build on EsperWorks

A REST API that lets you create invoices, sync clients, track payments, and receive real-time webhook events, from any platform or language.

Get your API key View endpoints

Quick start

1. Authenticate

All requests require a Bearer token. Generate one in Dashboard → Developer API.

curl https://api.tryesperworks.com/api/v1/partner/ping \
  -H "Authorization: Bearer ew_live_YOUR_KEY"

{
  "business": { "id": 1, "name": "Acme Ltd", "currency": "GHS" },
  "scopes": ["invoices:read", "invoices:write", "clients:read"]
}

2. Create an invoice

curl -X POST https://api.tryesperworks.com/api/v1/partner/invoices \
  -H "Authorization: Bearer ew_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 42,
    "currency": "GHS",
    "due_date": "2026-06-30",
    "items": [
      { "description": "Web design", "quantity": 1, "unit_price": 2500 }
    ]
  }'

3. Send it to the client

curl -X POST https://api.tryesperworks.com/api/v1/partner/invoices/123/send \
  -H "Authorization: Bearer ew_live_YOUR_KEY"

Errors & responses

200OKRequest succeeded

201CreatedResource created successfully

400Bad RequestValidation failed, check the errors field

401UnauthorizedMissing or invalid API key

403ForbiddenKey lacks the required scope

404Not FoundResource does not exist or belongs to another business

422UnprocessableRequest understood but business logic rejected it

429Rate LimitedExceeded 120 requests/minute, retry after the Retry-After header

500Server ErrorSomething went wrong on our end

Error responses always include a message string and optionally an errors object with field-level details.

Pagination

All list endpoints are paginated. Pass ?page= and ?per_page= (max 100). The response includes:

{
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 143,
    "last_page": 8
  }
}

Idempotency

Pass an Idempotency-Key: <uuid> header on any POST request to safely retry without creating duplicates. Keys expire after 24 hours.

curl -X POST https://api.tryesperworks.com/api/v1/partner/invoices \
  -H "Authorization: Bearer ew_live_YOUR_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Scopes

invoices:readRead invoices and payment status

invoices:writeCreate, update, send, and delete invoices

contracts:readRead contracts and proposals

contracts:writeCreate and update contracts

clients:readRead client records

clients:writeCreate, update, and delete clients

payments:readRead payment records

payments:writeProcess payments (initiate, simulate)

expenses:readRead expenses

expenses:writeCreate and update expenses

Webhooks

Set a webhook URL when creating an API key. EsperWorks will POST a signed JSON payload to your URL for each event.

invoice.createdA new invoice was created

invoice.sentInvoice was sent to the client

invoice.viewedInvoice was viewed by the client

invoice.paidInvoice was fully paid

payment.receivedA payment was recorded

contract.signedBoth parties have signed a contract

Verifying signatures

// Node.js example
const crypto = require('crypto');

const sig = req.headers['x-esperworks-signature'];
const expected = crypto
  .createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(req.rawBody)
  .digest('hex');

if (sig !== expected) return res.status(401).send('Invalid signature');

The raw request body must be used for signature verification, not a parsed JSON object.

Sandbox & test mode

Generate a test key (prefixed ew_test_...) from Dashboard → Developer API. Test keys behave identically to live keys but no real payments are processed and emails are suppressed.

Use POST /invoices/{id}/simulate-payment to trigger a payment webhook without going through a payment gateway; useful for testing your webhook handler end-to-end.

API Reference, 25 endpoints

Base URL: https://api.tryesperworks.com/api/v1/partnerAuth: Authorization: Bearer ew_live_...

GET/ping

—Verify key — returns business info and granted scopes

GET/business

—Get business profile (name, currency, country, plan)

GET/clients

clients:readList clients — supports ?search=, ?after=, ?per_page=

GET/clients/{id}

clients:readGet a single client by ID

POST/clients

clients:writeCreate a client

PATCH/clients/{id}

clients:writeUpdate a client

DELETE/clients/{id}

clients:writeDelete a client

GET/invoices

invoices:readList invoices — filter by ?status=, ?client_id=, ?after=, ?per_page=

GET/invoices/{id}

invoices:readGet invoice with line items and payment history

GET/invoices/{id}/payment-status

invoices:readGet payment status and outstanding amount

POST/invoices

invoices:writeCreate a draft invoice

POST/invoices/{id}/send

invoices:writeSend invoice to client by email

PATCH/invoices/{id}

invoices:writeUpdate draft invoice (notes, due_date, currency, items)

DELETE/invoices/{id}

invoices:writeDelete a draft invoice

POST/invoices/{id}/initiate-payment

invoices:writeGet payment URL for an invoice

POST/invoices/{id}/simulate-payment

invoices:writeTest mode only — simulate a payment and fire webhooks

POST/quick-charge

invoices:writeCreate invoice + payment URL in one call (auto-creates client if needed)

GET/contracts

contracts:readList contracts and proposals

GET/contracts/{id}

contracts:readGet a single contract

POST/contracts

contracts:writeCreate a contract programmatically — returns contract details, signing_url, and embed_url

GET/payments

payments:readList payments — filter by ?status=

GET/expenses

expenses:readList expenses — filter by ?category=, ?date_from=, ?date_to=

POST/expenses

expenses:writeCreate an expense

PATCH/expenses/{id}

expenses:writeUpdate an expense

DELETE/expenses/{id}

expenses:writeDelete an expense

Platform integrations

WordPress / WooCommerce

Auto-generate invoices from orders

Our free WordPress plugin connects your WooCommerce store to EsperWorks. Every completed order automatically creates a professional invoice and sends it to the customer.

Setup

1Download and install the plugin on your WordPress site

2Go to WooCommerce → Settings → EsperWorks

3Paste your EsperWorks API key (needs invoices:write + clients:write)

4Map your WooCommerce customer fields to EsperWorks client fields

5Save, new orders will now auto-create invoices

Download Plugin

Any platform

Shopify, custom apps, internal tools

Use the REST API directly from any platform that can make HTTP requests. Shopify scripts, Python scripts, internal dashboards, or mobile apps.

Pattern

1Create an API key with the scopes your integration needs

2On your platform, POST to /clients to create or find the customer

3POST to /invoices with the client_id and line items

4POST to /invoices/{id}/send to email it automatically

5Listen to webhook events to react to payments in real time

View endpoints

Ready to integrate?

Get your API key