API Reference

The ezylegal API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL

All API endpoints are relative to:

https://api.ezy-forms.com.au/v1

Authentication

The ezylegal API uses API keys to authenticate requests. Include your API key in the Authorization header:

Authorization: Bearer ezc_live_your_api_key_here

See the Authentication Guide for more details.

Request Format

All POST and PUT requests must include a Content-Type: application/json header and send data as JSON:

curl -X POST https://api.ezy-forms.com.au/v1/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"form_type": "financial_statement"}'

Response Format

All responses return JSON with the following structure:

Successful Response

{
  "id": "sess_abc123xyz",
  "status": "pending",
  "created_at": "2024-01-15T10:30:00Z"
}

Error Response

{
  "error": {
    "code": "invalid_request",
    "message": "The form_type field is required",
    "details": {
      "field": "form_type"
    }
  }
}

HTTP Status Codes

| Code | Description | |------|-------------| | 200 | Success - Request completed successfully | | 201 | Created - Resource created successfully | | 400 | Bad Request - Invalid request parameters | | 401 | Unauthorized - Invalid or missing API key | | 403 | Forbidden - Valid key but insufficient permissions | | 404 | Not Found - Resource doesn't exist | | 409 | Conflict - Resource already exists or state conflict | | 422 | Unprocessable Entity - Validation error | | 429 | Too Many Requests - Rate limit exceeded | | 500 | Internal Server Error - Something went wrong |

Pagination

List endpoints return paginated results:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 150,
    "total_pages": 8
  }
}

Query Parameters

| Parameter | Default | Description | |-----------|---------|-------------| | page | 1 | Page number (1-indexed) | | per_page | 20 | Items per page (max 100) |

Rate Limiting

API requests are rate-limited to ensure fair usage:

Standard: 100 requests per minute
Burst: 200 requests in a 10-second window

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705320000

When rate limited, you'll receive a 429 response with a Retry-After header.

Idempotency

For POST requests, you can include an idempotency key to safely retry requests:

curl -X POST https://api.ezy-forms.com.au/v1/sessions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -d '{"form_type": "financial_statement"}'

If you send the same idempotency key within 24 hours, you'll receive the same response.

Available Endpoints

Sessions

| Method | Endpoint | Description | |--------|----------|-------------| | POST | /sessions | Create a new session | | GET | /sessions | List all sessions | | GET | /sessions/:id | Get session details | | DELETE | /sessions/:id | Cancel a session |

View Sessions API →

Data Retrieval

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /sessions/:id/data | Get completed form data | | GET | /sessions/:id/pdf | Download PDF document |

View Data Retrieval API →

Billing

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /billing/subscription | Get subscription status | | GET | /billing/usage | Get usage statistics |

View Billing API →

SDKs and Libraries

Official SDKs are coming soon. In the meantime, you can use our API directly with any HTTP client.

API Changelog

We announce breaking changes 30 days in advance. Non-breaking changes (new fields, new endpoints) are added without notice.

See the full changelog for all updates.