API Reference
API Introduction
Learn how to authenticate and use the Faurya public API.
API Introduction
Use the Faurya public API to read analytics data, inspect visitors, and send server-side conversion or revenue events.
Base URL
All endpoints use this base URL:
https://api.faurya.com
Authentication
All API requests require Bearer Token authentication.
Add your API key in the Authorization header:
Authorization: Bearer YOUR_FAURYA_API_KEYContent type
Send JSON request bodies with:
Content-Type: application/jsonAvailable endpoints
- Visitor:
GET /api/v1/visitors/{faurya_visitor_id} - Create a goal:
POST /api/v1/goals - Delete goals:
DELETE /api/v1/goals - Create a payment:
POST /api/v1/payments - Delete payments:
DELETE /api/v1/payments - Billing customers:
PUT/GET /api/v1/billing/customers/{external_id} - Billing plans:
PUT/GET /api/v1/billing/plans/{external_id} - Billing invoices:
PUT/GET /api/v1/billing/invoices/{external_id} - Billing invoice status:
PUT /api/v1/billing/invoices/{external_id}/status - Billing transactions:
PUT/GET /api/v1/billing/transactions/{external_id} - Subscription events:
PUT /api/v1/billing/subscription-events/{external_id} - Subscriptions:
GET /api/v1/billing/subscriptions/{external_id} - Bulk import:
POST /api/v1/billing/imports - Analytics overview:
GET /api/v1/analytics/overview - Analytics metadata:
GET /api/v1/analytics/metadata - Realtime analytics:
GET /api/v1/analytics/realtime - Realtime map:
GET /api/v1/analytics/realtime/map - Devices:
GET /api/v1/analytics/devices - Pages:
GET /api/v1/analytics/pages - Campaigns:
GET /api/v1/analytics/campaigns - Referrers:
GET /api/v1/analytics/referrers - Countries:
GET /api/v1/analytics/countries - Regions:
GET /api/v1/analytics/regions - Cities:
GET /api/v1/analytics/cities - Browsers:
GET /api/v1/analytics/browsers - Operating systems:
GET /api/v1/analytics/operating-systems - Hostnames:
GET /api/v1/analytics/hostnames
GET /api/v1/analytics/timeseries and GET /api/v1/analytics/goals currently return 501 Not Implemented.
The billing endpoints have their own response envelope, error catalogue and rate limit, described in the Billing API overview. The notes below describe the other endpoints.
Common response behavior
200 OK: Request accepted and recorded.400 Bad Request: Invalid payload (missing required fields, invalid field format, or bot visitor).401 Unauthorized: Missing or invalid Bearer Token.404 Not Found: Resource context missing (for example, creating a goal for a visitor with no prior pageviews).429 Too Many Requests: Account event limit reached.501 Not Implemented: Endpoint exists but is not implemented yet.500 Internal Server Error: Unexpected server issue.
Field naming and validation notes
- Payments require a unique
transaction_id. - Goal and payment
metadatamust be a JSON object with a maximum of 10 primitive values. - If available, always send
faurya_visitor_idto improve attribution quality.
Best practices
- Send events server-side after the action is confirmed (successful checkout, confirmed signup, etc.).
- Retry safely on transient errors, but avoid duplicate sends for the same event.
- Log response status and payload in your backend for debugging.
Next steps
- Start with Create a goal to track non-payment conversions.
- Use Create a payment to attribute revenue from any payment provider.
- Use the Billing API when you need subscriptions, invoices, refunds and MRR rather than single payments.