Back to Technical Docs
SSO Digital Solutions — Developer Reference

API Integration
Documentation

Technical implementation reference for all SSO Digital Solutions APIs. Covers authentication, endpoint schemas, request/response formats, and integration patterns for each tool in the SSO ecosystem.

⚠ API keys are issued exclusively to licensed SSO Digital Solutions clients upon execution of a signed sales order and custom service contract. Placeholder keys shown in this document (prefixed SSO_KEY_XXXX) are for structural reference only and will not authenticate. Contact enterprise@ssoentertainment.sbs to begin the contracting process.

All SSO Digital Solutions API endpoints require bearer token authentication. Your API key is issued after execution of a signed sales order contract and is scoped to the specific tools included in your service plan.

Request Header

http
Authorization: Bearer SSO_KEY_XXXXXXXXXXXXXXXXXXXX
Content-Type: application/json
X-SSO-Client-ID: your_client_id_here
X-SSO-Version: 2026-01

Key Structure

  • Prefix: SSO_KEY_ — all production keys begin with this prefix
  • Scope: Each key is scoped to your contracted tool set. A key issued for ARDnDeX will not authenticate against the Atmos Engine endpoint unless that tool is in your contract.
  • Rotation: Keys expire on a 90-day cycle. Renewal notices are sent 14 days prior to expiry to the contract email on file.
  • Rate Limits: Default 1,000 requests/hour per key. Enterprise plans support burst limits up to 10,000 req/hr. Exceeding limits returns HTTP 429.

Obtaining Your Key

API keys are not self-service. To receive a key you must: (1) have a current signed sales order with SSO Digital Solutions, (2) have a negotiated custom quote covering the relevant tools, and (3) be provisioned by an SSO engineer. Contact enterprise@ssoentertainment.sbs to initiate the contracting process.

Error Responses

json
// 401 Unauthorized — key missing or malformed
{ "error": "unauthorized", "message": "Valid API key required. Keys are issued to licensed SSO clients only." }

// 403 Forbidden — key valid but lacks scope for this endpoint
{ "error": "forbidden", "message": "Your API key does not include scope for this endpoint. Review your contract." }

// 429 Too Many Requests
{ "error": "rate_limit_exceeded", "retry_after": 60 }

ARDnDeX (Automated Recursive Distribution and Network Data Exchange) is SSO's proprietary probabilistic validation and metadata inference engine. It uses Monte Carlo, Markov Chain, and Bayesian frameworks to perform predictive error analysis, ISRC/UPC conflict detection, and self-learning DDEX compliance verification.

The ARDnDeX API exposes three primary surfaces: Validate, Infer, and Audit.

Base URL

http
https://api.ssoentertainment.sbs/ardndex/v2

POST /validate — Probabilistic Metadata Validation

Submits a release metadata payload to the ARDnDeX stochastic validation pipeline. The engine runs Bayesian inference against global rights databases (BMI, ASCAP, IFPI) to verify consistency, detect ISRC conflicts, and flag DDEX schema violations before delivery.

bash
curl -X POST https://api.ssoentertainment.sbs/ardndex/v2/validate \
  -H "Authorization: Bearer SSO_KEY_XXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "upc": "123456789012",
    "release_name": "Album Title",
    "artist": "Artist Name",
    "isrc_list": ["US-ABC-26-00001", "US-ABC-26-00002"],
    "distributor": "SSO Gateway",
    "territories": ["US", "GB", "DE"],
    "track_count": 10,
    "ddex_format": "ERN_4_1",
    "audio_lufs": -14.2,
    "validation_depth": "full"
  }'

Response — /validate

json
{
  "validation_id": "val_a1b2c3d4e5f6",
  "status": "passed_with_warnings",
  "confidence_score": 0.94,
  "probabilistic_errors": [],
  "warnings": [
    {
      "code": "LUFS_BOUNDARY",
      "field": "audio_lufs",
      "message": "Audio at -14.2 LUFS is within Apple Music tolerance but may trigger loudness normalization on Spotify. Recommended: -14.0 LUFS.",
      "severity": "low"
    }
  ],
  "isrc_conflict_scan": {
    "scanned": 2,
    "conflicts_detected": 0,
    "status": "clean"
  },
  "ddex_compliance": {
    "schema": "ERN_4_1",
    "valid": true,
    "missing_fields": []
  },
  "bayesian_risk_score": 0.06,
  "recommended_action": "PROCEED_TO_DELIVERY"
}

POST /infer — Missing Metadata Inference

When submitting older catalog transfers, the ARDnDeX Predictive Clean Cataloging system can infer missing fields (historical ISRC dates, territory codes, rights organization registrations) using recursive distribution models trained on the SSO global catalog dataset.

bash
curl -X POST https://api.ssoentertainment.sbs/ardndex/v2/infer \
  -H "Authorization: Bearer SSO_KEY_XXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "upc": "123456789012",
    "release_name": "Album Title",
    "artist": "Artist Name",
    "known_isrc": "US-ABC-26-00001",
    "infer_fields": ["release_date_estimate", "territory_expansion", "pro_registration"],
    "inference_model": "markov_v3"
  }'

Response — /infer

json
{
  "inference_id": "inf_x9y8z7w6v5u4",
  "inferred_fields": {
    "release_date_estimate": {
      "value": "2023-03-15",
      "confidence": 0.88,
      "method": "markov_chain_v3",
      "source": "IFPI_registry_cross_reference"
    },
    "territory_expansion": {
      "recommended_additions": ["CA", "AU", "NZ", "FR"],
      "confidence": 0.91
    },
    "pro_registration": {
      "detected_pro": "BMI",
      "registered": true,
      "ipi_number_pattern": "00XXXXXXXXX"
    }
  },
  "model_version": "ardndex_markov_v3",
  "processing_time_ms": 312
}

GET /audit/{upc} — Catalog Audit Report

Pulls a full stochastic audit trail for a release by UPC. Returns all validation events, conflict scan history, rights routing status, and delivery integrity scores across DSPs. This is the primary tool for post-delivery reconciliation.

bash
curl https://api.ssoentertainment.sbs/ardndex/v2/audit/123456789012 \
  -H "Authorization: Bearer SSO_KEY_XXXXXXXXXXXXXXXXXXXX"

ARDnDeX Conflict Resolution — ISRC Live Transfer

If a "Live" ISRC is detected as still active at a previous distributor during the validation scan, ARDnDeX will flag a CONFLICT_LIVE_ISRC error and block delivery. You must issue a takedown request at the prior distributor after new assets are delivered to stores but before the final switch-over date. Use the /resolve-conflict endpoint to mark resolution after confirmation.

bash
curl -X POST https://api.ssoentertainment.sbs/ardndex/v2/resolve-conflict \
  -H "Authorization: Bearer SSO_KEY_XXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "validation_id": "val_a1b2c3d4e5f6",
    "conflict_code": "CONFLICT_LIVE_ISRC",
    "resolution_type": "TAKEDOWN_CONFIRMED",
    "takedown_confirmation_id": "TD-2026-XXXXX",
    "resolved_by": "engineer@yourlabel.com"
  }'

SSO Node is the infrastructure-layer ingestion engine. It accepts CSV and DDEX XML file uploads, parses them natively or via the ARDnDeX AI pipeline, and writes normalized release records to the distribution database. The Node API is primarily used by SSO engineers; label clients interact through the Onboarding Portal. Direct API access is available on Enterprise plans only.

Base URL

http
https://api.ssoentertainment.sbs/node/v1

POST /ingest — File Upload & Ingestion

Upload a catalog CSV, Delivery Log CSV, or DDEX ERN/MEAD XML file for ingestion. File type is auto-detected by filename and header structure. The Node processes the file asynchronously and returns an ingestion job ID for polling.

bash
curl -X POST https://api.ssoentertainment.sbs/node/v1/ingest \
  -H "Authorization: Bearer SSO_KEY_XXXXXXXXXXXXXXXXXXXX" \
  -F "file=@/path/to/catalog_export.csv" \
  -F "label_id=LABEL_XXXXX" \
  -F "ingestion_type=auto_detect" \
  -F "notify_on_complete=true"

Response — /ingest

json
{
  "job_id": "job_n1o2d3e4_ingest",
  "status": "queued",
  "file_type_detected": "sso_catalog_csv",
  "estimated_processing_ms": 4500,
  "poll_url": "https://api.ssoentertainment.sbs/node/v1/jobs/job_n1o2d3e4_ingest"
}

GET /jobs/{job_id} — Poll Ingestion Status

bash
curl https://api.ssoentertainment.sbs/node/v1/jobs/job_n1o2d3e4_ingest \
  -H "Authorization: Bearer SSO_KEY_XXXXXXXXXXXXXXXXXXXX"
json
{
  "job_id": "job_n1o2d3e4_ingest",
  "status": "parsed",
  "releases_created": 12,
  "releases_updated": 3,
  "releases_skipped": 1,
  "parse_errors": [],
  "audit_log_entry": "ING_20260402_XXXXXXXX",
  "completed_at": "2026-04-02T22:31:14.000Z"
}

GET /releases — List Releases

bash
curl "https://api.ssoentertainment.sbs/node/v1/releases?limit=50&sort=-updated_date" \
  -H "Authorization: Bearer SSO_KEY_XXXXXXXXXXXXXXXXXXXX"

GET /releases/{upc} — Release Detail

bash
curl https://api.ssoentertainment.sbs/node/v1/releases/123456789012 \
  -H "Authorization: Bearer SSO_KEY_XXXXXXXXXXXXXXXXXXXX"
json
{
  "upc": "123456789012",
  "release_name": "Album Title",
  "artist": "Artist Name",
  "distributor": "SSO Gateway",
  "status": "delivered",
  "track_count": 10,
  "isrc_list": ["US-ABC-26-00001"],
  "territories": ["US","GB","DE"],
  "platform_status": {
    "spotify": "delivered",
    "apple_music": "delivered",
    "amazon_music": "delivered",
    "youtube_music": "delivered",
    "tiktok": "pending",
    "deezer": "delivered",
    "tidal": "delivered"
  },
  "delivery_timestamps": {
    "spotify": "2026-03-15T14:22:00Z",
    "apple_music": "2026-03-15T15:01:00Z"
  },
  "events": [
    { "timestamp": "2026-04-01T12:00:00Z", "event_type": "CSV_CATALOG_INGESTED", "detail": "12 tracks ingested from SSO_catalog_Q1.csv" }
  ]
}

The Gateway Sync API pushes normalized release records from SSO Node to the SSO Gateway distribution layer, which handles downstream delivery to 150–300+ DSPs globally. Only releases with a valid UPC are eligible for sync. The sync engine deduplicates by UPC, updating existing Gateway records only when status, title, or artist data has changed.

Base URL

http
https://api.ssoentertainment.sbs/gateway/v1

POST /sync — Trigger Full Catalog Sync

bash
curl -X POST https://api.ssoentertainment.sbs/gateway/v1/sync \
  -H "Authorization: Bearer SSO_KEY_XXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "full_catalog",
    "label_id": "LABEL_XXXXX",
    "dry_run": false
  }'

Response — /sync

json
{
  "sync_id": "sync_g1a2t3e4w5",
  "status": "completed",
  "created": 5,
  "updated": 12,
  "skipped": 43,
  "failed": 0,
  "duration_ms": 2841,
  "gateway_endpoint": "https://gateway.ssoentertainment.sbs"
}

Status Mapping (Node → Gateway)

text
Node Status    →    Gateway Status
─────────────────────────────────
active         →    live
delivered      →    delivered
pending        →    pending
ingesting      →    pending
failed         →    pending
(other)        →    pending

Release Type Inference

text
track_count = 0 or 1    →    "single"
track_count 2–6         →    "ep"
track_count ≥ 7         →    "album"

POST /sync/single — Sync Single UPC

bash
curl -X POST https://api.ssoentertainment.sbs/gateway/v1/sync/single \
  -H "Authorization: Bearer SSO_KEY_XXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{ "upc": "123456789012" }'

The Atmos Authoring Engine API accepts stereo or multitrack audio sources and returns a Dolby Atmos ADM BWF master file ready for delivery to Apple Music (Spatial Audio badge), TIDAL (Dolby Atmos), and Amazon Music HD. The engine uses intelligent spatial mapping and object placement — files cannot be "upmixed" from processed stereo; original multitrack stems are required for best results.

Base URL

http
https://api.ssoentertainment.sbs/atmos/v1

POST /jobs — Submit Authoring Job

bash
curl -X POST https://api.ssoentertainment.sbs/atmos/v1/jobs \
  -H "Authorization: Bearer SSO_KEY_XXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "isrc": "US-ABC-26-00001",
    "source_type": "multitrack_stems",
    "source_file_urls": [
      "https://cdn.yourlabel.com/stems/track01_vocals.wav",
      "https://cdn.yourlabel.com/stems/track01_drums.wav",
      "https://cdn.yourlabel.com/stems/track01_bass.wav",
      "https://cdn.yourlabel.com/stems/track01_mix.wav"
    ],
    "target_format": "ADM_BWF",
    "target_lufs": -18,
    "spatial_profile": "auto",
    "output_sample_rate": 48000,
    "output_bit_depth": 24,
    "validate_adm": true
  }'

Response — /jobs

json
{
  "job_id": "atm_j1o2b3_xxxx",
  "status": "processing",
  "estimated_completion_seconds": 240,
  "poll_url": "https://api.ssoentertainment.sbs/atmos/v1/jobs/atm_j1o2b3_xxxx"
}

GET /jobs/{job_id} — Poll + Download

json
{
  "job_id": "atm_j1o2b3_xxxx",
  "status": "completed",
  "output": {
    "adm_bwf_url": "https://cdn.ssoentertainment.sbs/output/atm_j1o2b3_xxxx.wav",
    "adm_bwf_checksum_sha256": "a1b2c3d4...",
    "lufs_integrated": -18.1,
    "true_peak_dbfs": -1.0,
    "adm_validation_passed": true,
    "object_count": 7,
    "bed_channels": "7.1.2"
  }
}

Audio Requirements

  • Source files must be WAV, minimum 24-bit / 48kHz (96kHz or 192kHz preferred for Hi-Res Lossless badge eligibility)
  • Apple Digital Masters badge requires files mastered by an Apple-certified mastering engineer — provide engineer name and email during submission
  • For Apple Music Hi-Res Lossless: provide at least 24-bit / 48kHz sources; 96kHz or 192kHz automatically triggers the Hi-Res badge
  • ADM BWF files are validated against SSO ADM Validator schema before delivery

The Lyrics Tooling API covers both the AI Lyrics Transcription Engine (speech-to-text TTML draft generation) and the Apple Music Sing Lyrics Tool (word-level timing, translation, romanization, and export). The API accepts audio file URLs and returns TTML documents compliant with Apple Music Sing delivery specifications.

Base URL

http
https://api.ssoentertainment.sbs/lyrics/v1

POST /transcribe — AI Transcription to TTML Draft

bash
curl -X POST https://api.ssoentertainment.sbs/lyrics/v1/transcribe \
  -H "Authorization: Bearer SSO_KEY_XXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "isrc": "US-ABC-26-00001",
    "audio_url": "https://cdn.yourlabel.com/audio/track01_master.wav",
    "language": "en-US",
    "output_format": "ttml_apple_sing_draft",
    "word_level_timing": true,
    "include_romanization": false,
    "translation_language": null
  }'

Response — /transcribe

json
{
  "job_id": "lyr_t1r2a3_xxxx",
  "status": "processing",
  "estimated_seconds": 45,
  "poll_url": "https://api.ssoentertainment.sbs/lyrics/v1/jobs/lyr_t1r2a3_xxxx"
}

POST /ttml/compile — Compile Validated TTML for Delivery

Accepts an edited TTML draft (from the GUI tool or direct API editing) and runs Apple Music Sing compliance validation before generating the final delivery-ready TTML file. Supports line-level translations and per-word romanization tracks.

bash
curl -X POST https://api.ssoentertainment.sbs/lyrics/v1/ttml/compile \
  -H "Authorization: Bearer SSO_KEY_XXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "isrc": "US-ABC-26-00001",
    "ttml_source_url": "https://cdn.yourlabel.com/lyrics/draft_US-ABC-26-00001.ttml",
    "validation_profile": "apple_music_sing_v2",
    "include_translation": true,
    "translation_language": "es",
    "include_romanization": false,
    "background_vocal_config": {
      "enabled": true,
      "lines": [4, 8, 12]
    }
  }'

TTML Delivery Format Notes

  • Output is TTML 1.0 with Apple Music Sing extensions for word-level begin and end attributes
  • Translations attach as <div xml:lang="es"> parallel blocks
  • ISRC-based bulk export available: POST /ttml/bulk-export with array of ISRCs
  • Beat-by-beat (word-level) sync is required for Apple Music Sing — line-level-only TTML will be rejected by Apple

The DDEX Authoring Engine generates fully compliant DDEX ERN 4.1 and MEAD XML packages from structured release data. It accepts normalized JSON release payloads and returns valid XML files ready for DSP submission or delivery log ingestion through SSO Node.

Base URL

http
https://api.ssoentertainment.sbs/ddex/v1

POST /ern/generate — Generate ERN Package

bash
curl -X POST https://api.ssoentertainment.sbs/ddex/v1/ern/generate \
  -H "Authorization: Bearer SSO_KEY_XXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_version": "ERN_4_1",
    "message_sender": {
      "party_id": "DPID:SSO_XXXXXX",
      "name": "SSO Digital Solutions"
    },
    "message_recipient": {
      "party_id": "DPID:SPOTIFY_XX",
      "name": "Spotify AB"
    },
    "release": {
      "upc": "123456789012",
      "release_name": "Album Title",
      "artist": "Artist Name",
      "isrc_list": ["US-ABC-26-00001", "US-ABC-26-00002"],
      "territories": ["US", "GB", "DE", "Worldwide"],
      "release_date": "2026-05-01",
      "label": "Your Label Name",
      "track_count": 10,
      "genre": "Electronic",
      "parental_advisory": false
    },
    "deal_terms": {
      "usage_type": "PermanentDownload",
      "price_tier": "Front",
      "deal_start_date": "2026-05-01"
    }
  }'

Response — /ern/generate

json
{
  "job_id": "ddex_e1r2n3_xxxx",
  "status": "completed",
  "output": {
    "ern_xml_url": "https://cdn.ssoentertainment.sbs/ddex/ern_123456789012_v41.xml",
    "schema_validated": true,
    "business_rules_passed": true,
    "file_size_bytes": 8421,
    "schema_version": "ERN_4_1"
  }
}

POST /mead/generate — Generate MEAD Package

Same payload structure as ERN generation. Set "schema_version": "MEAD_1_0". MEAD packages are used for music encoding and distribution metadata and include extended fields for Dolby Atmos and immersive audio delivery.

The DDEX Validation Engine command-line API validates ERN, MEAD, and related XML files against DDEX schemas and business rules before distributor submission. It returns structured pass/fail reports with line-level error detail.

Base URL

http
https://api.ssoentertainment.sbs/ddex-validate/v1

POST /validate — Validate XML File

bash
curl -X POST https://api.ssoentertainment.sbs/ddex-validate/v1/validate \
  -H "Authorization: Bearer SSO_KEY_XXXXXXXXXXXXXXXXXXXX" \
  -F "file=@/path/to/ern_release.xml" \
  -F "schema=ERN_4_1" \
  -F "business_rules=true"

Response — /validate

json
{
  "validation_id": "val_ddex_x1y2z3",
  "file": "ern_release.xml",
  "schema": "ERN_4_1",
  "schema_valid": true,
  "business_rules_passed": false,
  "errors": [
    {
      "rule": "BR_ERN_004",
      "severity": "error",
      "message": "ReleaseDate must not be in the past for NewReleaseMessage",
      "xpath": "/NewReleaseMessage/ReleaseList/Release/ReleaseDate",
      "line": 142
    }
  ],
  "warnings": [],
  "submission_eligible": false
}

The Encoding & Localization Engine API handles UTF-8/UTF-16 encoding normalization (with or without BOM), language code assignment, script normalization, and region-aware metadata formatting for global releases. It is the final processing step before DDEX package assembly.

Base URL

http
https://api.ssoentertainment.sbs/encoding/v1

POST /normalize — Normalize Metadata Encoding

bash
curl -X POST https://api.ssoentertainment.sbs/encoding/v1/normalize \
  -H "Authorization: Bearer SSO_KEY_XXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "release_name": "アルバムタイトル",
    "artist": "アーティスト名",
    "language_code": "ja",
    "script": "Jpan",
    "target_encoding": "UTF-8",
    "bom": false,
    "romanize": true,
    "region_format": "JP"
  }'

Response — /normalize

json
{
  "normalized_release_name": "アルバムタイトル",
  "normalized_artist": "アーティスト名",
  "romanized_release_name": "Arubamu Taitoru",
  "romanized_artist": "Aatisuto Mei",
  "encoding": "UTF-8",
  "bom_present": false,
  "language_code": "ja",
  "script_detected": "Jpan",
  "ddex_language_tag": "ja-Jpan-JP",
  "region_format_applied": "JP"
}

SSO Digital Solutions APIs support outbound webhooks for asynchronous job completion and system events. Configure webhook endpoints in your SSO Node client dashboard (Enterprise plan). All webhook payloads are signed with HMAC-SHA256 using your webhook secret.

Signature Verification

javascript
const crypto = require('crypto');

function verifyWebhook(payload, signatureHeader, webhookSecret) {
  const expectedSig = crypto
    .createHmac('sha256', webhookSecret)
    .update(payload)
    .digest('hex');
  const receivedSig = signatureHeader.replace('sha256=', '');
  return crypto.timingSafeEqual(
    Buffer.from(expectedSig, 'hex'),
    Buffer.from(receivedSig, 'hex')
  );
}

Webhook Event Types

json
// ARDnDeX validation complete
{ "event": "ardndex.validation.complete", "validation_id": "val_a1b2c3", "status": "passed", "timestamp": "..." }

// Node ingestion complete
{ "event": "node.ingestion.complete", "job_id": "job_n1o2d3e4", "releases_created": 12, "timestamp": "..." }

// Gateway sync complete
{ "event": "gateway.sync.complete", "sync_id": "sync_g1a2t3", "created": 5, "updated": 12, "timestamp": "..." }

// Atmos job complete
{ "event": "atmos.job.complete", "job_id": "atm_j1o2b3", "adm_bwf_url": "https://...", "timestamp": "..." }

// TTML compile complete
{ "event": "lyrics.ttml.complete", "job_id": "lyr_t1r2a3", "ttml_url": "https://...", "timestamp": "..." }

Retry Policy

  • Webhooks are retried up to 5 times on non-2xx responses with exponential backoff (10s, 30s, 2m, 10m, 30m)
  • After 5 failures the event is marked dead and logged to your audit feed
  • Webhook endpoints must respond within 10 seconds or the delivery is marked as a timeout
API Keys — Contract Required

Ready to integrate?

API access is issued exclusively to licensed SSO Digital Solutions clients. All keys are provisioned after execution of a signed sales order and custom service contract. Contact our enterprise team to begin.