Intelligent CreativeNewsroomResourcesAbout UsHelp
Documentation

Key Concepts & Terminology

Organization and Workspace

An Organization is the top-level account entity — typically a brand or agency. An organization contains one or more Workspaces (logical containers for scorecards, criteria, and media scoped to a team/brand/product line).

Most API calls accept (but do not always require) a numeric workspaceId. Use GET /v1/workspaces to enumerate workspaces the API key can access.

Scorecard

A Scorecard is a named collection of scored media within a workspace, configured against a set of channels and guidelines. Each scorecard has a type:

  • IN_FLIGHT — for ongoing/active campaigns whose performance is being tracked.
  • PRE_FLIGHT — for pre-launch checks against a creative before it ships.

Scorecards are configured inside the Vidmob platform; the API exposes them as read-only references.

Channel

A Channel is an advertising platform (Meta, Google Ads, TikTok, etc.). Guidelines are channel-specific. One asset can be scored against multiple channels in a single submission. See Channel Identifiers.

Guideline (Criterion)

A Guideline (called a Criterion in the API) is a single evaluable rule. Each guideline targets a specific channel and creative type. When a media asset is scored, each applicable guideline returns PASS, FAIL, NOT_APPLICABLE, or a NO_DATA_* code.

The endpoint path uses criteria (/v1/scoring/criteria/metadata); field names and UI language use "guideline." They are the same thing.

Guideline Group (Criterion Group)

A Criterion Group is a named collection of guidelines within a workspace, used to organize/filter results. Groups are metadata — they do not change scoring, only its organization. A guideline can belong to multiple groups or none.

The criteriaGroups field is only returned by POST /v1/scoring/criteria/metadata. It is not returned by the scores endpoint.

Score vs. Adherence

The scores endpoint returns two metrics per channel:

  • score — Weighted aggregate across applicable guidelines, computed as SUM(passed_points) / SUM(total_points) where each guideline's weight determines its points contribution. Range: 0.0–1.0.
  • adherencePercent — Simple unweighted percentage of applicable guidelines that returned PASS. Range: 0.0–1.0.

For most integrations, adherencePercent is the more interpretable number. Use score when guideline weights are configured intentionally and you want a weighted rollup.

Media Identifiers

When you submit an asset via POST /v1/media, Vidmob assigns a uniqueId (UUID) that permanently identifies the asset.

Subsequent endpoints accept either:

  • The uniqueId, or
  • Your client-side id plus source and version query parameters (to disambiguate).

Use one approach or the other — not both.

The combination of client-side id + version must be unique within a source. Submitting the same (id, version) again returns the existing asset — Vidmob does not load the same media twice.

Aperture

Aperture is Vidmob's name for the Creative Tags engine. The endpoints live under /v1/media/aperture. The API key scope is aperture.

Guideline Weights vs. Consideration

Each guideline carries a numeric weight that drives the rolled-up channel score (see Score vs. Adherence). A separate consideration field (MANDATORY or OPTIONAL) exists for backward compatibility.

New integrations should rely on weight rather than filtering or branching on consideration. The consideration field is preserved for legacy integrations and is not the recommended way to express a guideline's importance.

A separate boolean bestPractice field flags whether a guideline is a best-practice rule. consideration and bestPractice are independent — do not conflate them.