Tuned Global
Docs / Telco Quick Start

Telco Quick Start

Get started with TConnect APIs for telco subscriber music streaming

Music for Telcos — API Quick Start Guide

Overview

This guide walks through the end-to-end flow for integrating Tuned Global's TConnect APIs into a telco environment. By the end, you'll have registered a subscriber, verified their profile, searched the catalogue, streamed a track, and logged a play event.

Estimated time: 10–15 minutes

Prerequisites

  • A StoreId issued by Tuned Global for your telco environment
  • OAuth2 client credentials (client ID and secret) from Tuned Global
  • A test MSISDN (phone number) or external user ID
  • cURL or Postman installed

Step 1: Register a User (TConnect)

Register a new subscriber using their MSISDN or external user ID via the TConnect endpoint.

Endpoint: POST https://api-services-connect.tunedglobal.com/api/v1/tconnect/users

curl -X POST "https://api-services-connect.tunedglobal.com/api/v1/tconnect/users" \
  -H "Content-Type: application/json" \
  -H "StoreId: YOUR_STORE_ID" \
  -d '{
    "ExternalUserId": "+601234567890",
    "FirstName": "Jane",
    "LastName": "Doe",
    "Email": "jane.doe@example.com",
    "Gender": "Female",
    "BirthYear": 1990,
    "Country": "MY"
  }'

Note: The ExternalUserId is typically the subscriber's MSISDN. This creates the user in TConnect and returns their Tuned Global user ID.

Step 2: Validate the User

Confirm the user exists and is correctly linked to your store before proceeding.

Endpoint: POST https://api-services-connect.tunedglobal.com/api/v1/tconnect/users/validate

curl -X POST "https://api-services-connect.tunedglobal.com/api/v1/tconnect/users/validate" \
  -H "Content-Type: application/json" \
  -H "StoreId: YOUR_STORE_ID" \
  -d '{
    "Msisdn": "+601234567890",
    "StoreId": "YOUR_STORE_ID",
    "ExternalUserId": "+601234567890"
  }'

A successful response returns the user's internal ID, confirming registration.

Step 3: Authenticate (Get Bearer Token)

Obtain a JWT token to authorise subsequent API calls.

Endpoint: POST https://api-authentication-connect.tunedglobal.com/oauth2/token

curl -X POST "https://api-authentication-connect.tunedglobal.com/oauth2/token" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password&username=YOUR_TEST_USERNAME&password=YOUR_TEST_PASSWORD"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 86400
}

Save the access_token — you'll use it as a Bearer token in all authenticated requests below.

Step 4: Check Subscription Status

Verify the subscriber has an active package/subscription before allowing playback.

Endpoint: GET https://api-services-connect.tunedglobal.com/api/v1/tconnect/sub-status

curl -X GET "https://api-services-connect.tunedglobal.com/api/v1/tconnect/sub-status?msisdn=%2B601234567890&storeId=YOUR_STORE_ID" \
  -H "StoreId: YOUR_STORE_ID"

Response:

[
  {
    "Id": 12345,
    "StartDate": "2026-01-01T00:00:00",
    "EndDate": "2026-12-31T23:59:59",
    "PackageName": "Premium Music",
    "PlanName": "Monthly",
    "UserId": 67890,
    "PhoneNumber": "+601234567890"
  }
]

This confirms the user's subscription is active and which package they're on.

Step 4.5: Get User Profile

Retrieve the registered user's profile to confirm their account details, active subscriptions, and device entitlements.

Endpoint: GET https://api-services-connect.tunedglobal.com/api/v3/users/{user_id}/profile

curl -X GET "https://api-services-connect.tunedglobal.com/api/v3/users/67890/profile" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Replace 67890 with the UserId returned in Step 4 (sub-status response).

Response includes: user profile data, active subscriptions, and registered devices.

You can also retrieve the subscriber's total listening minutes — useful for engagement reporting and telco dashboards:

Endpoint: GET https://api-services-connect.tunedglobal.com/api/v1/tconnect/listening-minutes

curl -X GET "https://api-services-connect.tunedglobal.com/api/v1/tconnect/listening-minutes?msisdn=%2B601234567890&storeId=YOUR_STORE_ID" \
  -H "StoreId: YOUR_STORE_ID"

Response: a numeric value representing total listening minutes for the subscriber.

Step 5: Search the Catalogue

Search for tracks, artists, or albums across the catalogue.

Endpoint: GET https://api-metadata-connect.tunedglobal.com/api/v2.4/search/songs

curl -X GET "https://api-metadata-connect.tunedglobal.com/api/v2.4/search/songs?q=Bohemian%20Rhapsody&offset=0&count=5" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Country: MY"

Other search endpoints available:

/api/v2.4/search/albums       Search albums
/api/v2.4/search/artists      Search artists
/api/v2.4/search/playlists    Search playlists
/api/v2.4/search              Search across all types
/api/v2.4/search/songs/advanced   Advanced search (BPM, duration, year, key, tags)

Note the Track ID from the response — you'll need it for streaming.

Step 6: Get Stream URL

First, request a security token for the stream, then obtain the signed CDN streaming URL.

6a. Request Stream Token

Endpoint: POST https://api-services-connect.tunedglobal.com/api/v3/plays/{deviceId}/{trackId}/token

curl -X POST "https://api-services-connect.tunedglobal.com/api/v3/plays/1001/987654/token" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Save the token value from the response.

6b. Get Stream Location

Endpoint: POST https://api-services-connect.tunedglobal.com/api/v3/plays/{deviceId}/{trackId}/stream

curl -X POST "https://api-services-connect.tunedglobal.com/api/v3/plays/1001/987654/stream?streamType=Music&streamProvider=Tuned" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '"STREAM_TOKEN_FROM_STEP_6A"'

The response is a signed streaming URL with a TTL (time-to-live) expiration. Use this URL in your audio player for playback.

Step 7: Log Playback Events

Log play events for royalty reporting, analytics, and compliance. You should log at minimum: Start, 30-second mark, and End of File.

Endpoint: POST https://api-services-connect.tunedglobal.com/api/v3/plays/{deviceId}

curl -X POST "https://api-services-connect.tunedglobal.com/api/v3/plays/1001" \
  -H "StoreId: YOUR_STORE_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "TrackId": 987654,
    "LogPlayType": "Start",
    "Seconds": 0,
    "Source": "Search",
    "SourceId": "0",
    "Guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "Country": "MY",
    "PlayerType": "MobilePhone"
  }'

Recommended log events:

LogPlayType       When                                          Seconds
---------------   -------------------------------------------   ----------------
Start             Playback begins                               0
30SecondMark      30 seconds elapsed (mandatory for royalties)  30
Skip              User skips track                              Current position
EndOfFile         Track finishes                                Total duration

Troubleshooting

Error                    Cause                                Solution
-----------------------  -----------------------------------  ------------------------------------------
403 on stream            Token expired or no subscription     Re-authenticate (Step 3), verify sub (Step 4)
401 Unauthorized         Missing or invalid Bearer token      Check Authorization header: Bearer <token>
Empty search results     Country filter or catalogue issue    Verify Country header matches store territory
User validation fails    MSISDN not registered                Complete Step 1 (registration) first
Missing play logs        Invalid device ID or bad payload     Verify deviceId matches a registered device

Quick Reference — Headers

Every request requires at minimum:

Header          Value                               Required By
--------------- ----------------------------------- ----------------------------
StoreId         Your Tuned Global store identifier  All endpoints
Authorization   Bearer <access_token>               Authenticated endpoints (5-7)
Content-Type    application/json                    POST/PUT requests
Country         ISO country code (e.g. MY, AU)      Metadata/search endpoints

Notes

Replace YOUR_STORE_ID, YOUR_ACCESS_TOKEN, YOUR_TEST_USERNAME, YOUR_TEST_PASSWORD, and the example IDs (1001, 987654) with your actual test credentials provided by Tuned Global.

On this page