Quickstart

Get started with TConnect APIs for telco subscriber music streaming

Outcome

Test the end-to-end flow for integrating a music offer into a telco environment.

Step you will complete

Auth → Register subscriber → Verify user profile → Search the catalogue → Stream track → Log playback

Timed required

~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-by-step implementation

1

Step 1: Register a user (TConnect)

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

Bash

 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.

2

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

Bash

 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.

3

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

Bash

 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:

Bash

 {
  "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.

4

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

Bash

 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:

Bash

 [
  {
    "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.

4.5

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

Bash

 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
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

Bash

 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.

5

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

Bash

 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:

Markdown

 /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.

6

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

Bash

 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

Bash

 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.

8

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}

Bash

 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 logging events:

Plain text

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 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

Quick Reference — Headers

Every request requires at minimum:

Plain text

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 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.

Sections

Quickstart

Outcome

Step you will complete

Timed required

~10-15 minutes

Prerequisites

Step-by-step implementation

1

Step 1: Register a user (TConnect)

2

Step 2: Validate the user

3

Step 3: Authenticate (Get Bearer Token)

4

Step 4: Check subscription status

4.5

Step 4.5: Get user profile

5

Step 5: Search the catalogue

6

Step 6: Get stream URL

6a. Request Stream Token

6b. Get stream location

8

Log playback events

Troubleshooting

Quick Reference — Headers

Notes

On this page