Overview

What this analysis answersCopy Anchor Link

The Acquisition API shows how much the organization invests to win new customers and what that investment returns. It combines media spend (Meta Ads and Google Ads), the customers attributed to each channel and campaign, and the revenue they generate, and returns ready-made metrics such as CAC, LTV, ROI and payback. Every response uses the same period, and the summary cards include a comparison with the previous period.

Questions you can answer:

• How much did we invest in the period, and how many new customers did it bring?
• What is our CAC, and how many months does it take to pay back the investment?
• Which channel and which campaign have the best cost and the best return?
• How do customers move through the funnel stages?
• How is paid media performing (impressions, clicks, leads, cost per lead), and which audience and regions does it reach?

Which endpoint to useCopy Anchor Link

Notes per endpointCopy Anchor Link

• /summary and /channels: each metric comes as { value, changePct }, with the percentage change against the previous period. The Orgânico (organic) channel is not part of /channels, because it has no spend. The channel list is not sorted.
• /funnel: returns only the funnel stages the organization configured on the V4MOS.AI platform. Each stage count is event volume (impressions, clicks, leads, orders) summed across the connected tools. It is not a number of distinct people. EXPOSURE and ATTENTION measure media (scale: "media") and the remaining stages measure customer-side events (scale: "customer"). The step from one group to the other is a change of unit, not a conversion rate. With no configured stages, the response is stages: [].
• /new-customers-over-time includes the Orgânico channel. /unit-economics-over-time has paid channels only. In both series, days with no data are omitted: fill them with zero in your chart (new customers) or leave them blank (ratios).
• /campaigns: a channel → campaign → ad set → ad tree, always with two groups: acquisition (campaigns marked as acquisition) and other (everything else). Media metrics exist at every level. Business metrics (customers, CAC, LTV, ROI, payback, leads) exist only at channel and campaign level, because customer attribution stops at the campaign.
• /paid-media: Meta Ads and Google Ads only. Leads add up the CRM leads attributed to a paid channel by UTM and the platform leads (Meta and Google) that the organization's funnel counts on its Interest stage. The daily series has one point per day, with no gaps, and the cards are its sum.
• /paid-media/audience: Meta Ads only. Leads here are Meta's lead event and do not match /paid-media, which also adds CRM and Google leads.

Available endpointsCopy Anchor Link

• getGet Acquisition Summary Cards/v1/acquisition/summaryThe organization's consolidated acquisition numbers for the period: investment, new customers, CAC, LTV, ROI and payback.
• getGet Acquisition Cards by Channel/v1/acquisition/channelsOne card per paid channel, such as Meta Ads and Google Ads, with investment, new customers, CAC, LTV, LTV/CAC, ROI and payback.
• getGet Gain-Flow Funnel/v1/acquisition/funnelVolume of each stage of the funnel the organization configured, from exposure to retention, with the proportion between stages.
• getGet New Customers Over Time/v1/acquisition/new-customers-over-timeDaily series of new customers, with one tab per channel, the Orgânico (organic) channel included.
• getGet Unit Economics Over Time/v1/acquisition/unit-economics-over-timeDaily series of CAC, LTV and cost per sale (CPV), with one tab per paid channel.
• getGet Campaigns Table/v1/acquisition/campaignsHierarchical channel → campaign → ad set → ad table, with media and business metrics, split into two groups.
• getGet Paid Media Overview/v1/acquisition/paid-mediaPaid media overview (Meta Ads and Google Ads): investment, impressions, reach, clicks, leads and cost per lead, with a daily series.
• getGet Paid Media Audience/v1/acquisition/paid-media/audienceMeta Ads audience and regions: investment, leads and cost per lead by gender and age range, and reach and cost by region.

MetricsCopy Anchor Link

Ratios are rounded to 2 decimal places. Investment is not rounded.

Important rulesCopy Anchor Link

null means "not defined", never zeroCopy Anchor Link

When a ratio cannot be calculated (for example, CAC with no new customer, or CPC with no click), the field is null. A 0 is always a real, measured value.

Fields that can be null: cac, ltv, avgLtv, acquisitionAvgLtv, ltvCacRatio, acquisitionLtvCacRatio, roi, acquisitionRoi, paybackMonths, cpv, cpm, ctr, cpc, cpl, leads, reach and costPerThousandReach. changePct is null when the comparison is not possible (previous value zero or missing), and on paybackMonths it is always null. For paybackMonths, 0 and null are opposite results: 0 means the investment paid back within the acquisition month itself; null means no group of customers reached payback, or their cost is unknown.

Funnel exception: on /funnel, pctOfFirst and pctOfPrevious are 0 (not null) when the reference stage has a zero count.

CAC only counts campaigns marked as acquisitionCopy Anchor Link

On the V4MOS.AI platform, each organization marks which campaigns are acquisition campaigns (winning new customers). The other campaigns are brand, monetization or unclassified. The CAC in this API uses only the campaigns marked as acquisition, on both sides of the division: cac = acquisitionInvestment ÷ acquisitionNewCustomers.

That is why responses carry two sets of numbers:

The hasAcquisitionClassification field (on /summary and /channels) tells whether the organization has marked any campaign as acquisition, at any date. When it is false, cac, ltvCacRatio, paybackMonths and the acquisition* metrics are null, and the acquisition group of /campaigns is empty. This is not missing data for the period: the acquisition campaigns still need to be marked on the platform. The broad totals keep their real values.

Contribution marginCopy Anchor Link

The contribution margin the organization configured on the platform (100% when not configured) is applied to roi, acquisitionRoi, paybackMonths and acquisitionAvgLtv (and therefore to acquisitionLtvCacRatio). ltv and avgLtv are gross, with no margin. Responses from /summary, /channels, /unit-economics-over-time and /campaigns report the margin status in marginConfigured (whether it was configured), marginCompleteness (complete, partial or none) and marginItemStatus (status of each cost: payment gateway, tax, freight and cost of goods).

Period and comparisonCopy Anchor Link

• The comparison window is always the period of the same length right before the selected one. Example: a 12-day selection is compared with the 12 days immediately before it.
• Time series are always daily, whatever the length of the period. A 365-day period returns about 365 points per channel; group them into weeks or months on your side if needed.
• "Today" is the UTC calendar day. When the period includes today, that last day is still partial, because the day's data keeps arriving.

Data availability flagsCopy Anchor Link

Campaigns table: row limitCopy Anchor Link

/campaigns returns at most 5,000 rows across both groups and every level, with no pagination. When the limit is reached, the deepest levels are removed first (ads, then ad sets). Channels and campaigns are never removed. The truncation object reports what happened: truncated, returnedRows, totalRows and droppedLevels. Use it to show "showing N of M rows".

Use campaignId to identify a campaign. Each row's id is unique in the response and works as a key, but for channels and for rows without a platform id it is generated by the API and must not be parsed.

Common parametersCopy Anchor Link

Date rules:

• Send startDate and endDate together. Sending only one returns 400.
• Send the date only (2026-03-11). A date with a time (2026-03-11T00:00:00Z) or a date that does not exist (2026-02-30) returns 400.
• startDate must be on or before endDate, neither date can be in the future (UTC), and the range can cover at most 366 days (365 days between the two dates).
• With no dates and no period, the API uses the last 30 days (30d).

ExampleCopy Anchor Link

curl -X GET "https://data.v4mos.ai/v1/acquisition/summary?organizationId=organization_123&startDate=2026-03-01&endDate=2026-03-31" \
  -H "x-client-id: your_client_id" \
  -H "x-client-secret: your_client_secret"

AuthenticationCopy Anchor Link

Every endpoint uses the base URL https://data.v4mos.ai and requires the x-client-id and x-client-secret headers. See Authentication.