API Introduction
Guide to navigating the V4MOS.AI API reference
This section contains every public endpoint of the V4MOS.AI API, organized by platform. Each endpoint page is generated from the OpenAPI specification and includes parameters, response schemas, code samples and a playground to try the call.
Base URL
https://data.v4mos.aiAll requests must be made over HTTPS, with JSON (UTF-8) requests and responses.
Platforms
📊 Advertising & Media
- Google Ads - Accounts, campaigns, ad groups, keywords, conversions and segmentations
- Facebook Ads - Accounts, campaigns, ad sets, ads, creatives and breakdowns
- Google Analytics - GA4 sessions, events, transactions, customers and products
🛒 E-commerce
- Tray - Customers, orders and products
- Shopify - Customers, orders, order items and products
- VTEX - Orders and order items
- E-commerce Summary - Aggregated order summary for VTEX, Shopify and Tray
🎯 CRM
- HubSpot - Contacts, deals, companies, pipelines and products
- Kommo - Leads, contacts, pipelines and users
- CRM V4 - Leads, opportunities, companies, contacts and pipelines
📈 Analytics
- Profitability - Profitability indicators, metric evolution and cohorts
- Products - Sales, margin, stock and entry cohort per product
- Acquisition - Funnel, channels, campaigns and paid media
Common API Patterns
Authentication
Every request requires the credentials in the headers and organizationId as a query parameter. See Authentication to generate your credentials.
x-client-id: your_client_id
x-client-secret: your_client_secretCommon Query Parameters
| Parameter | Type | Description | Default |
|---|---|---|---|
organizationId | string | Organization ID | required |
page | integer | Page number | 1 |
limit | integer | Records per page (1 to 5000) | 500 |
orderBy | string | Field to sort by | varies by endpoint |
orderDirection | string | Sort direction (ASC/DESC) | varies by endpoint |
Date filters and other parameters vary by endpoint; see each endpoint page. Pagination and rate limit details are in Limits and Best Practices.
Pagination
List endpoints are paginated with page and limit; the response carries the records in data and the pagination state in meta:
{
"data": [...],
"meta": {
"page": 1,
"limit": 500,
"hasNextPage": true,
"hasPreviousPage": false
}
}pagestarts at1;limitranges from1to5000(default500). Out-of-range values are adjusted automatically.- To walk through every record, increment
pagewhilemeta.hasNextPageistrue. - Aggregated endpoints (such as E-commerce Summary) return a single result, without pagination. Check the response schema on each endpoint page.
Full examples in Limits and Best Practices.
Common errors
| Status | When it happens | How to fix it |
|---|---|---|
400 | Missing organizationId or invalid parameter (validation error) | Send organizationId on every request and check parameter names, types and formats |
401 | Missing x-client-id/x-client-secret headers or invalid credentials | Check the headers or generate new credentials in Authentication |
429 | Rate limit of 100 requests per minute per credential exceeded | Wait for the Retry-After header and retry with exponential backoff |
500 | Internal server error | Retry with backoff; if it persists, contact support |
Error responses are JSON, with the problem description in message.
Next Steps
- Generate your credentials in Authentication
- Pick a platform from the sidebar
- Try the endpoints in each page's playground
- Learn how data is refreshed in Data Synchronization and Updates