Viewcast direct measurement purchase

The direct measurement purchase endpoint lets you buy a measurement for a display without first creating a draft asset. It is the search-driven path: you found a display_id through the public display inventory (or a Displays inventory search), and you want to own the measurement for that display right away. Instead of the three-step lifecycle (create a draft asset, purchase a draft measurement, purchase a final measurement), one synchronous call mints a completed, final-measured asset owned by your organization.

POST /v2/viewcast/measurements/purchase/direct

The endpoint is on the v2 base https://api2.mworks.com. For the endpoint-by-endpoint reference, see the Viewcast API reference. For how the normal draft-to-final lifecycle works, see Displays On Demand measurements.

This page covers the direct purchase type only. The same /v2/viewcast/measurements/purchase/{type} route also serves the draft and final types for assets you already created; those are documented on the Displays On Demand pages.

When to use it

Use the direct purchase when:

you hold a display_id from inventory search or the public display inventory and want to acquire the measurement for it, and
you do not need the intermediate draft result; you want the final, measured asset in one step.

The result is a final_measured asset, owned by your organization, with both display_id and source_display_id set to the display_id you submitted. The purchase also starts a 12-month subscription window from the purchase date (see below).

Request

The request body is strict and minimal: exactly two fields. Unknown keys return 400, and the error names the rejected field. The five fields the direct path previously accepted (classification, anchor, related_parties, display, user_reference) are retired: sending any of them returns 400 naming the field.

Field	Type	Required	Meaning
`display_id`	String	Yes	The display identifier to purchase, as issued by the Motionworks display catalog. Must exist in the catalog: an unknown `display_id` returns 404 before any charge (no reservation is made, no credit moves). Locked onto the minted asset: both `display_id` and `source_display_id` are set to this value.
`measurement_request_id`	UUID	Yes	Caller-minted idempotency key (see below). Any RFC 4122 UUID.

The asset definition comes from the catalog, not from you. The classification, anchor, and display descriptor are read from the Motionworks display catalog for the display_id you submit, at purchase time. You do not send them and you cannot override them; the catalog is the single source of the display's definition.

Classification is immutable: the classification stamped onto the minted asset is the catalog value at purchase time, and it is final for the life of the asset. There is no PATCH path to correct it later (the minted asset rejects refine requests entirely, see below). If the catalog entry changes after your purchase, your minted asset keeps the definition it was minted with.

An unknown display_id returns 404 pre-charge: existence is validated against the catalog before anything is minted or charged. Submit the exact identifier you found through search; a mistyped identifier fails fast at no cost rather than minting an asset against the wrong display.

curl -X POST https://api2.mworks.com/v2/viewcast/measurements/purchase/direct \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "display_id": "dsp_4471MYFACE",
    "measurement_request_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response

The purchase is synchronous: a successful call returns 200 OK with the freshly minted asset in the standard measurement result envelope.

{
  "data": {
    "asset_id": "vcaJDVDYWSSMHAXVEFYW1DVD2PPFD",
    "kind": "direct",
    "status": "completed"
  },
  "meta": {
    "request_id": "req_...",
    "credits_used": 300,
    "product": "viewcast"
  }
}

The data.kind is direct and data.status is completed: there is nothing to poll. The minted asset is in the final_measured state immediately.

What the purchase mints

The call creates a final_measured asset that is:

Owned by your organization.
Private (not published to the shared inventory surface).
Locked: the asset is in a terminal state. PATCH refine requests and DELETE archive requests both return 409. There is no way to modify or archive a direct-purchased asset through the API.
Identified: display_id and source_display_id are both set to the submitted value, so the asset joins to the broader Displays inventory surface by that identifier.
Catalog-sourced: the classification, anchor, and display descriptor on the minted asset are the values the Motionworks display catalog held for that display_id at purchase time. None of them are caller-supplied.

Pricing

The direct purchase costs 300 credits total: 1 cr base endpoint cost plus the 299 cr purchase charge (viewcast_viewshed_purchase_direct). If your wallet cannot fund the charge, the call returns 402 before any write: nothing is minted and no credit moves.

Idempotency and replay

measurement_request_id (any RFC 4122 UUID, minted client-side) is the idempotency key:

Same measurement_request_id + same body: returns the original 200 response at 0 credits, with the header X-MW-Idempotent-Replay: 1. No second asset is minted and no second charge occurs.
Same id + different body: returns 409 idempotency_mismatch. The mismatch is rejected before any charge, so no credit moves.

Mint a fresh UUID for each genuinely new purchase.

Per-organization licensing

Direct-purchase licensing is scoped to your organization and to the subscription window. There is no global exclusivity on a display_id:

Within your organization, at most one active direct license per display_id per 12-month subscription window.
A same-organization re-attempt for a display_id your org already licensed, while the window is open, returns 409 (CONFLICT) with an already-licensed message before any charge. You already own the read; there is nothing new to buy.
After the 12-month window lapses, your organization may purchase the same display_id again to open a new window (the window does not auto-renew; repurchase is the renewal path).
Other organizations may license the same display_id independently. Two orgs can each hold an active direct license for the same display at the same time; one org's license never blocks another's.

The 12-month subscription window

The purchase stamps a 12-month subscription window starting on the purchase date. The subscription governs licensed access to the display's profile through Viewcast Profiles: while the window is open, GET /v2/viewcast/profiles/{display_id} serves your organization as an owned read. At expiry the profile route fails closed until repurchase.

For the full subscription and renewal mechanics, see Purchase flow and credits.

How this relates to Viewcast Profiles

The Viewcast Profiles read endpoint (GET /v2/viewcast/profiles/{display_id}) is the consumption side: it serves the profile of a display your organization already owns a measurement for. The direct purchase is the acquisition side: it is how you acquire that ownership. An unowned caller reading the profile route receives 403 FEATURE_NOT_LICENSED pointing at this purchase surface; after a successful direct purchase, the same read serves your organization.