DDEX Gateway

The Enterprise DDEX Gateway supports two equal integration paths. REST-first clients reference a SpaceMedia release and never need to generate XML. Standards-native clients submit their existing ERN message, keep the original payload intact, and use the same validation, delivery, acknowledgement, and webhook resources.

The gateway is part of the Enterprise Delivery API add-on. API clients receive no DDEX access until ddex:read, ddex:write, or ddex:manage is explicitly granted.

Current availability

DDEX public routes are currently available in staging for onboarding and conformance. Do not send production DDEX traffic until SpaceMedia confirms that the production routes and the specific live connection are active. A production 404 during this phase means the public DDEX route is not available in that environment; it is not a signal to retry or change credentials.

Staging add-on activation and API testing are free. An organization administrator can activate the Enterprise Delivery API add-on, create scoped credentials under Settings > DDEX Gateway, exchange them at POST /api/v1/token, inspect the standards matrix, create locked connection profiles, run validations, and test webhook receivers.

Every customer connection requires SpaceMedia connection activation review and passing conformance evidence before sandbox transport is enabled. This protects partner endpoints and is separate from release review. Customers can prepare and validate the complete integration before transport approval.

Staging simulation and real approval boundaries

Staging provides an isolated DDEX simulator while the official licensed schema assets and external approvals are pending. It lets clients exercise the complete API lifecycle without contacting a DSP, SFTP server, or partner Web Service endpoint.

When licensed schema assets are absent, the validation report contains the informational finding DDEX_SCHEMA_VALIDATION_SIMULATED. The gateway never reports this as XSD validation. Connection health checks return simulated: true and external_probe_performed: false when the staging simulator handled the check.

Simulated conformance can approve a sandbox connection for local testing after SpaceMedia review. It can never approve or activate a live connection. Live activation remains blocked until the official schema package, recorded licence and retention approvals, and bilateral partner conformance evidence are present.

Choose an integration path

Send exactly one source field. Native XML is preserved without rewriting sender, recipient, identifiers, deals, or valid partner extensions.

SpaceMedia review boundary

The connection's commercial_route determines the review rule.

Both routes still receive secure parsing, DDEX, catalog, contract, transport, and state validation. A direct partner route is not a way to bypass security or partner contract rules.

Version policy

Call GET /api/v1/ddex/standards during onboarding and store the returned matrix.

New integrations must not request ERN 3 live feeds. The gateway does not silently downgrade messages or treat ERN 4.2 as compatible with ERN 4.3.

Supported first-release profiles are Audio and Simple Audio Single. Connections pin an exact ERN version, profile, AVS revision, and either Web Service 1.8 or Cloud Storage 1.8.1 choreography. Generated operations default to AVS 011.

ERN 4.3.2 uses the exact http://ddex.net/xml/ern/432 namespace. Generated messages set ReleaseProfileVersionId to Audio or SimpleAudioSingle, use AVS 011, and do not add a non-standard MessageSchemaVersionId attribute. The gateway never treats the ERN 4.3.1 namespace as a 4.3.2 alias.

DPIDs are shown in their human-readable hyphenated form in settings. DDEX XML uses the canonical form without hyphens. For example, SpaceMedia's displayed PA-DPIDA-2025040501-N identifier is emitted as PADPIDA2025040501N inside DDEX messages.

Create a connection

Before connection creation:

1. Register and attest a sender DPID.
2. Select an integration owner from the same organization.
3. Agree the partner DPID, actions, asset rules, acknowledgements, and environment.
4. Create a sandbox connection.
5. Submit it through POST /api/v1/ddex/connections/{reference}/activation-request.
6. Complete SpaceMedia sandbox conformance testing before requesting live enablement.

Create the sandbox connection with a new idempotency key:

{
  "name": "Partner sandbox",
  "partner_name": "Partner DSP",
  "sender_identity_reference": "1a12f4f0-07a1-4294-a556-21b0f59e8c42",
  "integration_owner_reference": "10f94dbe-2677-49d1-91e3-3464b40edb23",
  "commercial_route": "direct_partner",
  "direction": "outbound",
  "environment": "sandbox",
  "remote_dpid": "PA-DPIDA-2026072902-N",
  "ern_version": "4.3.2",
  "release_profile": "Audio",
  "avs_version": "011",
  "choreography": "web_service_1_8",
  "hosting_mode": "spacemedia_managed",
  "auth_type": "bearer",
  "agreement_reference": "PARTNER-SANDBOX-2026",
  "capabilities": ["insert", "update", "global_takedown"]
}

For spacemedia_delivery_deal, omit sender_identity_reference; SpaceMedia supplies the platform sender identity. For direct_partner, the sender identity is required and must belong to the same organization.

Create an explicit deal profile before a REST-first delivery that needs commercial rights:

{
  "name": "Worldwide streaming",
  "commercial_model": "SubscriptionModel",
  "use_types": ["OnDemandStream"],
  "territories": ["GB", "US", "DE"],
  "valid_from": "2026-08-21T00:00:00Z",
  "valid_until": null,
  "terms": {
    "rights_claimed": true
  }
}

Creating a connection never enables transport. It starts as a locked draft. An activation request submits it for SpaceMedia connection review and sandbox conformance testing. Transport becomes available only after the applicable connection and production-readiness checks pass. This operational review applies to all connections and is separate from SpaceMedia release review. A partner certificate is not required.

For live activation, submit a live connection for the same organization, partner DPID, ERN, release profile, AVS, and choreography as a passing sandbox connection. Live connections remain disabled until licensing, retention, bilateral agreement, connection health, compatible transport, and production-access requirements are confirmed. Staging cannot contact live DDEX endpoints.

Sender-hosted Web Service feeds are available for outbound conformance. Partner-managed outbound SFTP for Cloud Storage 1.8.1 is available with pinned host keys and streamed, size-checked, atomic publication. Web Service recipient polling and SpaceMedia-managed SFTP are enabled per connection when available and after bilateral conformance. Their unavailability does not prevent a separate connection from using another supported transport. A connection health check reports the applicable requirements explicitly.

Rotate connection credentials through POST /api/v1/ddex/connections/{reference}/rotate-secret, then run POST /api/v1/ddex/connections/{reference}/health-check. Stored credentials are encrypted and never returned.

Connection capability and contract profiles are immutable versions. To replace one, create a complete connection profile with supersedes_reference set to the prior connection reference. The prior profile becomes superseded, in-flight evidence keeps its original profile, and the replacement starts in testing.

Validate without transmission

curl --request POST \
  --url https://staging.spacemedia.uk/api/v1/ddex/validations \
  --header "Authorization: Bearer $SPACEMEDIA_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: validation-20260729-001" \
  --data '{
    "connection_reference": "3bc1f628-60af-4db2-b984-321c1525df20",
    "release_reference": "b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8",
    "deal_profile_reference": "bb9b8f3b-55b1-498f-a484-05155b8950ef",
    "action": "insert"
  }'

The API returns 202 with a canonical status_url, correlation key, current state, and findings. Validation itself can finish in the first request, but clients must still handle the operation as asynchronous. On staging, inspect findings for DDEX_SCHEMA_VALIDATION_SIMULATED before treating a successful result as official XSD conformance.

Every finding includes a stable code, family, severity, stage, retryability, JSON Pointer or XPath, explanation, remediation, optional partner rule, and correlation key.

A successful asynchronous operation returns a public operation reference, current state, findings, canonical status URL, and correlation key:

{
  "data": {
    "reference": "45be9e79-f39e-4cf9-bfc8-bf9f10481da6",
    "status": "ready",
    "review_status": "not_required",
    "transport_status": "not_started",
    "partner_status": "not_started",
    "findings": []
  },
  "status_url": "/api/v1/ddex/messages/45be9e79-f39e-4cf9-bfc8-bf9f10481da6",
  "correlation_key": "ddex_01J2M4Y8Q7K3"
}

Validation includes secure XML parsing, exact namespace/schema/profile/AVS pins, DPIDs, GTIN check digits, ISRC format, P-line and C-line ownership, dates, territories, verified-master MIME/size/hash, deal validity, partner-required fields, allowed actions, transport credentials, choreography/auth compatibility, duplicate messages, update ordering, and acknowledged identifier locks. Download the complete report from GET /api/v1/ddex/messages/{reference}/validation-report.

Common stable finding codes:

Deliver a release

TypeScript:

const result = await fetch("https://staging.spacemedia.uk/api/v1/ddex/deliveries", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SPACEMEDIA_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "delivery-20260729-001"
  },
  body: JSON.stringify({
    connection_reference: "3bc1f628-60af-4db2-b984-321c1525df20",
    release_reference: "b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8",
    deal_profile_reference: "bb9b8f3b-55b1-498f-a484-05155b8950ef",
    action: "insert"
  })
});

if (result.status !== 202) throw new Error(`DDEX delivery failed: ${result.status}`);
const operation = await result.json();

PHP:

$response = $client->request('POST', '/api/v1/ddex/deliveries', [
    'headers' => [
        'Authorization' => 'Bearer '.$token,
        'Idempotency-Key' => 'delivery-20260729-001',
    ],
    'json' => [
        'connection_reference' => '3bc1f628-60af-4db2-b984-321c1525df20',
        'release_reference' => 'b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8',
        'deal_profile_reference' => 'bb9b8f3b-55b1-498f-a484-05155b8950ef',
        'action' => 'insert',
    ],
]);

Clients choose insert, update, territorial_takedown, global_takedown, or purge. Do not classify a change as metadata-only or resource-only. Updates are complete statements of current and future deal truth. Unchanged binaries may be omitted when the connection permits it.

REST-first insert, update, and territorial_takedown operations require deal_profile_reference. The gateway does not guess commercial rights. A generated global_takedown intentionally omits the deal list, while purge creates a PurgeReleaseMessage for corrupt catalog state.

On staging, an approved sandbox connection uses the isolated transport simulator. Poll the message until it reaches acknowledged, then inspect delivery_simulated. A value of true confirms only that the local contract, queue, packaging, status, acknowledgement, and webhook lifecycle completed without external delivery.

A territorial takedown also requires an explicit subset of the selected deal profile and an ISO 8601 effective time with timezone:

{
  "connection_reference": "3bc1f628-60af-4db2-b984-321c1525df20",
  "release_reference": "b7a15d95-58f6-4f67-b5d1-89f4f5bfb4d8",
  "deal_profile_reference": "bb9b8f3b-55b1-498f-a484-05155b8950ef",
  "action": "territorial_takedown",
  "metadata_overlay": {
    "takedown": {
      "territories": ["DE"],
      "effective_at": "2026-08-01T00:00:00+02:00"
    }
  }
}

Native relay and import

Use native_xml instead of release_reference:

{
  "connection_reference": "3bc1f628-60af-4db2-b984-321c1525df20",
  "action": "insert",
  "native_xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><ern:NewReleaseMessage>...</ern:NewReleaseMessage>"
}

POST /api/v1/ddex/uploads preserves and validates a native message. POST /api/v1/ddex/imports stages a create-only inbound import under the connection's same-organization integration owner. Imports are atomic and create drafts only. UPC, ISRC, source-message, or catalog collisions block the complete import rather than creating partial catalog records.

Fields that cannot safely round-trip through the normalized catalog remain attached to the original message and appear in unmapped_fields.

Follow the returned import status_url, or call GET /api/v1/ddex/imports/{reference}, to inspect the canonical import result.

State model

Normal control progression:

accepted → validating → ready → queued → packaging → available or transferring → transferred → claimed → acknowledged

Exceptional states are blocked, rejected, failed, cancelled, and expired.

Review, transport, partner, and webhook states are separate. Recipient DELETE confirms claim only. It is not proof of processing or storefront availability. The API exposes live only after an explicit partner processing status reports it.

Retry and cancellation

• Reusing an idempotency key with the same request safely replays the outcome.
• Reusing it with a different request returns a conflict.
• Validation errors and partner rejections are not retried automatically.
• Temporary timeouts, resets, throttling, and server failures use bounded retry with backoff.
• Retry only messages that the API reports as recoverable.
• Cancel only work that has not been claimed.

Web Service and Cloud Storage

Web Service 1.8 uses the sender-hosted feed and recipient claim semantics. Resource downloads use GET /api/v1/ddex/messages/{reference}/resources/{resourceReference} with stable authenticated URLs, SHA-256 checksums, ETag, and byte-range requests through the standard Range header. Processing status remains separate from claim.

Read the Atom feed through GET /api/v1/ddex/connections/{reference}/feed. A feed contains at most the current available message for a release. A superseded payload URL returns 404.

Cloud Storage 1.8.1 supports release-by-release and negotiated batches. A message cannot enter multiple open batches. Batch completion and its manifest checksum are published after all message artifacts.

Conformance checklist

• Sandbox DPIDs and credentials are exchanged out of band.
• Exact ERN, profile, AVS, and choreography match the connection.
• Single, album, update, takedown, purge, invalid message, retry, claim, and acknowledgement fixtures pass.
• Release-by-release and batch flows are tested separately.
• Direct partner tests confirm no SpaceMedia review or credit mutation.
• SpaceMedia delivery deal tests confirm transmission cannot start before review approval.
• Duplicate, stale, out-of-order, and identifier-changing updates are rejected.
• Webhook signatures, duplicates, retries, ordering, and secret rotation are verified.
• Operational owners agree acknowledgement deadlines and escalation contacts.

Related pages