Skip to main content

​
Introduction

The OptiFlow API provides programmatic access to your business management system. Built on Laravel 12 with a RESTful architecture, the API enables you to manage invoices, quotations, products, contacts, inventory, and workspaces.

​
Base URL

The OptiFlow API uses tenant-based URLs with subdomain routing: 
https://{tenant}.yourdomain.com/api/v1
Where {tenant} is your organization’s unique subdomain identifier.
All API requests must include the tenant subdomain. The system uses Laravel’s stancl/tenancy package to initialize the correct tenant context based on the subdomain.

​
Authentication

OptiFlow uses Laravel Sanctum for API authentication. All API requests must include a valid API token in the request headers. See the Authentication page for detailed information.

​
Request Format

All API requests should:
  • Use HTTPS
  • Include the Accept: application/json header
  • Include the Authorization: Bearer {token} header
  • Send request data as JSON with Content-Type: application/json

​
Example Request

curl -X GET https://acme.yourdomain.com/api/v1/invoices \
  -H "Accept: application/json" \
  -H "Authorization: Bearer your-api-token" \
  -H "Content-Type: application/json"

​
Response Format

All API responses are returned in JSON format. Successful responses include the requested data, while error responses include error details.

​
Success Response

{
  "data": {
    "id": 1,
    "document_number": "INV-0001",
    "total_amount": "1500.00",
    "status": "pending_payment"
  }
}

​
Error Response

{
  "message": "The given data was invalid.",
  "errors": {
    "contact_id": [
      "The contact id field is required."
    ]
  }
}

​
HTTP Status Codes

The API uses standard HTTP status codes:
Status CodeDescription
200OK - Request succeeded
201Created - Resource successfully created
204No Content - Request succeeded with no response body
400Bad Request - Invalid request data
401Unauthorized - Missing or invalid authentication
403Forbidden - Insufficient permissions
404Not Found - Resource does not exist
422Unprocessable Entity - Validation error
429Too Many Requests - Rate limit exceeded
500Internal Server Error - Server error

​
Pagination

List endpoints support pagination using query parameters:
​
page
integer
default:"1"
Page number to retrieve
​
per_page
integer
default:"15"
Number of items per page (max 100)

​
Paginated Response

{
  "data": [
    // ... items
  ],
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 72
  },
  "links": {
    "first": "https://acme.yourdomain.com/api/v1/invoices?page=1",
    "last": "https://acme.yourdomain.com/api/v1/invoices?page=5",
    "next": "https://acme.yourdomain.com/api/v1/invoices?page=2",
    "prev": null
  }
}

​
Filtering and Sorting

Many list endpoints support filtering and sorting:
​
filter[field]
string
Filter results by field value
​
sort
string
Sort by field (prefix with - for descending)

​
Example

GET /api/v1/invoices?filter[status]=pending_payment&sort=-issue_date

​
Rate Limiting

The API implements rate limiting to ensure fair usage:
  • Authenticated requests: 60 requests per minute per user
  • Unauthenticated requests: 10 requests per minute per IP
When rate limited, the API returns a 429 Too Many Requests response with headers: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 42

​
Multi-Tenancy Considerations

All API operations are scoped to the tenant specified in the subdomain. Resources cannot be accessed across tenants, even with valid authentication.

​
Workspace Context

Many resources (products, invoices, contacts) are further scoped to specific workspaces within a tenant. When working with these resources:
  • Users can only access resources in workspaces they belong to
  • Some operations require specifying a workspace_id
  • Stock levels and inventory are managed per workspace
See the Workspaces documentation for details on managing workspace context.

​
Webhooks

OptiFlow supports webhooks for real-time notifications (coming soon). You’ll be able to subscribe to events like:
  • Invoice created/updated/paid
  • Quotation converted to invoice
  • Product stock low
  • Payment received

​
SDK and Libraries

PHP SDK

Official PHP SDK for Laravel applications

JavaScript SDK

JavaScript/Node.js SDK with TypeScript support

​
API Versioning

The current API version is v1. Version information is included in the URL path: 
https://{tenant}.yourdomain.com/api/v1/...
Future API versions will be released with a deprecation period. We’ll provide advance notice before deprecating any version.

​
Support

For API support:

​
Next Steps

Authentication

Learn how to authenticate API requests

Invoices

Manage invoices via the API

Products

Create and update products

Contacts

Manage customer and supplier contacts

Build docs developers (and LLMs) love

Get started for freeTalk to us