API Reference

API Documentation

Complete REST API reference with authentication, endpoints, and code examples

20 min read

Authentication Required

All API requests require authentication. Include your API key in the request header as shown below. You can generate API keys from your Account Settings.

Authentication

Authenticate API requests by including your API key in the Authorization header. All requests must be made over HTTPS.

Authentication Header

Bash

1# Include the API key in every request
2curl -X GET https://api.umbraerp.com/v1/invoices \
3  -H "Authorization: Bearer YOUR_API_KEY" \
4  -H "Content-Type: application/json" \
5  -H "Accept: application/json"

If authentication fails, the API returns a 401 Unauthorized response:

401 Unauthorized Response

JSON

1{
2  "error": {
3    "code": "UNAUTHORIZED",
4    "message": "Invalid or expired API key",
5    "status": 401
6  }
7}

Base URL

All API endpoints are relative to the following base URL:

Base URL

Bash

https://api.umbraerp.com/v1

Endpoints Overview

The API is organized around REST principles. Below is a summary of the main resource endpoints:

Method	Endpoint	Description
`GET`	/invoices	List all invoices
`POST`	/invoices	Create a new invoice
`GET`	/customers	List all customers
`POST`	/customers	Create a new customer
`GET`	/products	List all products
`POST`	/products	Create a new product
`GET`	/employees	List all employees
`GET`	/reports/profit-loss	Generate profit & loss report
`GET`	/webhooks	List webhook subscriptions

List Invoices

Retrieve a paginated list of all invoices in your account. Supports filtering, sorting, and pagination through query parameters.

GET /invoices

Bash

1curl -X GET "https://api.umbraerp.com/v1/invoices?page=1&limit=20&status=unpaid&sort=due_date:asc" \
2  -H "Authorization: Bearer YOUR_API_KEY"

Successful response:

200 OK Response

JSON

1{
2  "data": [
3    {
4      "id": "inv_abc123",
5      "number": "INV-01001",
6      "customer": {
7        "id": "cust_xyz789",
8        "name": "Acme Corp"
9      },
10      "total": 1500.00,
11      "currency": "USD",
12      "status": "unpaid",
13      "due_date": "2026-04-15",
14      "created_at": "2026-03-01T10:30:00Z"
15    }
16  ],
17  "pagination": {
18    "page": 1,
19    "limit": 20,
20    "total": 1,
21    "total_pages": 1
22  }
23}

Create an Invoice

Create a new invoice by sending a POST request with the required fields in the request body:

POST /invoices

Bash

1curl -X POST https://api.umbraerp.com/v1/invoices \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "customer_id": "cust_xyz789",
6    "items": [
7      {
8        "description": "Web Development Services",
9        "quantity": 40,
10        "unit_price": 75.00
11      },
12      {
13        "description": "Hosting (Monthly)",
14        "quantity": 1,
15        "unit_price": 49.99
16      }
17    ],
18    "due_date": "2026-04-15",
19    "currency": "USD",
20    "notes": "Payment due within 30 days"
21  }'

Successful creation returns the invoice with a 201 status:

201 Created Response

JSON

1{
2  "data": {
3    "id": "inv_def456",
4    "number": "INV-01002",
5    "customer_id": "cust_xyz789",
6    "items": [
7      {
8        "description": "Web Development Services",
9        "quantity": 40,
10        "unit_price": 75.00,
11        "total": 3000.00
12      },
13      {
14        "description": "Hosting (Monthly)",
15        "quantity": 1,
16        "unit_price": 49.99,
17        "total": 49.99
18      }
19    ],
20    "subtotal": 3049.99,
21    "tax": 0,
22    "total": 3049.99,
23    "currency": "USD",
24    "status": "draft",
25    "due_date": "2026-04-15",
26    "created_at": "2026-03-04T12:00:00Z"
27  }
28}

Error Handling

The API uses standard HTTP status codes to indicate success or failure. Error responses include a structured JSON body with details:

Error Response Format

JSON

1{
2  "error": {
3    "code": "VALIDATION_ERROR",
4    "message": "The request body contains invalid fields",
5    "status": 422,
6    "details": [
7      {
8        "field": "customer_id",
9        "message": "Customer ID is required"
10      }
11    ]
12  }
13}

Common Status Codes

Code	Meaning
200	Request succeeded
201	Resource created successfully
400	Bad request (malformed syntax)
401	Unauthorized (invalid API key)
403	Forbidden (insufficient permissions)
404	Resource not found
422	Validation error
429	Rate limit exceeded
500	Internal server error

Rate Limiting

API requests are rate limited based on your plan tier. Rate limit information is included in the response headers:

Rate Limit Headers

Bash

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1705312800
Retry-After: 60

Handling Rate Limits

Implement exponential backoff in your client code to gracefully handle rate limit responses. Check the Retry-After header to determine how long to wait before retrying the request.

SDK Examples

Use the official SDK for a simpler integration experience:

TypeScript SDK Example

TypeScript

1import { UmbraClient } from '@umbra-erp/sdk';
2 
3const client = new UmbraClient({
4  apiKey: process.env.UMBRA_API_KEY,
5});
6 
7// List invoices
8const invoices = await client.invoices.list({
9  page: 1,
10  limit: 20,
11  status: 'unpaid',
12});
13 
14// Create an invoice
15const newInvoice = await client.invoices.create({
16  customer_id: 'cust_xyz789',
17  items: [
18    { description: 'Consulting', quantity: 10, unit_price: 150 },
19  ],
20  due_date: '2026-04-15',
21});
22 
23// List customers
24const customers = await client.customers.list({ limit: 50 });
25 
26// Create a product
27const product = await client.products.create({
28  name: 'Widget Pro',
29  sku: 'WDG-PRO-001',
30  price: 29.99,
31  stock: 500,
32});
33 
34console.log('Unpaid invoices:', invoices.data.length);
35console.log('New invoice:', newInvoice.data.number);

Python SDK Example

Python

1from umbra_erp import UmbraClient
2 
3client = UmbraClient(api_key="YOUR_API_KEY")
4 
5# List invoices
6invoices = client.invoices.list(page=1, limit=20, status="unpaid")
7 
8# Create an invoice
9new_invoice = client.invoices.create(
10    customer_id="cust_xyz789",
11    items=[
12        {"description": "Consulting", "quantity": 10, "unit_price": 150},
13    ],
14    due_date="2026-04-15",
15)
16 
17# List customers
18customers = client.customers.list(limit=50)
19 
20# Create a product
21product = client.products.create(
22    name="Widget Pro",
23    sku="WDG-PRO-001",
24    price=29.99,
25    stock=500,
26)
27 
28print(f"Unpaid invoices: {invoices.pagination.total}")
29print(f"New invoice: {new_invoice.data.number}")