Create measurement source

POST /api/v2/buyer/advertisers/{advertiserId}/measurement-sources Registers a measurement data source (e.g. an MMM model or brand-lift study) for an advertiser. The source defines which outcome type it produces, how often, and the lag before data lands — the engine uses these to weigh incoming records and check freshness.

Request

curl -X POST https://api.apostra.com/api/v2/buyer/advertisers/12345/measurement-sources \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sourceKey": "acme_incr_rev",
    "name": "Acme Incrementality",
    "outcomeType": "incremental_revenue",
    "granularity": "geo_week",
    "cadence": "weekly",
    "provider": "acme-mmm",
    "lagWeeks": 1,
    "signalWeight": 1,
    "status": "active"
  }'

Parameters

Field	Type	Required	Notes
`advertiserId`	string	Yes	Path parameter — the owning advertiser
`sourceKey`	string	Yes	Stable key tying records to this source
`name`	string	Yes	Human-readable label
`outcomeType`	string	Yes	Primary outcome the source reports
`granularity`	string	Yes	Reporting grain (e.g. `geo_week`)
`cadence`	enum	Yes	`continuous`, `daily`, `weekly`, `biweekly`, `monthly`, `quarterly`
`provider`	string	Yes	Partner name (e.g. `acme-mmm`)
`outcomeTypes`	string[]	No	Additional outcome types the source reports
`lagWeeks`	integer	No	Expected reporting lag in weeks (default 1)
`ingestionMethod`	string	No	How records arrive (e.g. `api`, `sync`)
`attributionConfig`	object	No	Free-form provider attribution settings
`signalWeight`	number	No	Weight in belief updates, 0–1 (default 1)
`status`	enum	No	`pending`, `active`, `paused` (default `pending`)
`notes`	string	No	Free-text notes
`vendor`	object	No	The measurement vendor as AdCP identifies it: `domain` (the domain hosting the vendor’s `brand.json`, e.g. `placer.ai`) and optional `brandId`
`vendorMetrics`	object[]	No	Vendor metrics this source reports, up to 50. Each is `{ metricId, outcomeType }`: the vendor’s AdCP metric id and the outcome type this source’s records carry for it. Requires `vendor`

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "advertiserId": "12345",
  "sourceKey": "acme_incr_rev",
  "name": "Acme Incrementality",
  "outcomeType": "incremental_revenue",
  "outcomeTypes": [],
  "granularity": "geo_week",
  "cadence": "weekly",
  "provider": "acme-mmm",
  "lagWeeks": 1,
  "signalWeight": 1,
  "status": "active",
  "vendor": null,
  "vendorMetrics": [],
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-01-15T10:30:00Z"
}

Name the vendor and its metrics

provider is a free-text label. When the source is a measurement vendor that sellers and goals can refer to, also send vendor and vendorMetrics. Sellers identify a vendor metric by the vendor’s domain and the metric id, so this is what lets a goal later be counted by this source. Each metric maps to one of the source’s outcome types; records you upload under that outcome type count as that vendor metric.

{
  "sourceKey": "placer_store_visits",
  "name": "Placer store visits",
  "outcomeType": "foot_traffic",
  "granularity": "store_week",
  "cadence": "weekly",
  "provider": "placer",
  "vendor": { "domain": "placer.ai" },
  "vendorMetrics": [{ "metricId": "store_visits", "outcomeType": "foot_traffic" }]
}

The returned id is the sourceId you pass to Get and Update.

Errors

400 VALIDATION_ERROR — missing a required field, invalid cadence/status, or signalWeight outside 0–1.
400 VALIDATION_ERROR — vendorMetrics sent without vendor, a metricId listed twice, or a metric mapped to an outcome type that is neither outcomeType nor in outcomeTypes.
404 NOT_FOUND — advertiserId does not exist or is not visible to the authenticated account.

See Errors for the full error contract.

Measurement tasks

All measurement operations

Measurement overview

Pipeline, belief state, and concepts

List measurement sources

See registered sources

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Create measurement source

Request

Parameters

Response

Name the vendor and its metrics

Errors

Measurement tasks

Measurement overview

List measurement sources

​Request

​Parameters

​Response

​Name the vendor and its metrics

​Errors

​Related

Measurement tasks

Measurement overview

List measurement sources

Request

Parameters

Response

Name the vendor and its metrics

Errors

Related