P.R.O. Agency - API
by P.R.O. Agency - Performing Rights Organization

P.R.O. Agency - API

A collection of REST based APIs to programmatically interact with the P.R.O. Agency platform.

https://api.pro-agency.net

https://api.pro-agency.net/v0.9
Headers

Use the header fields for authentication to the API and submitting or receiving any content.

pro-auth-token
string required

The pro-auth-token is the session token obtained from authenticating to ProDB API using your api key and is required on all calls after authentication.

Example:
B0A61931-E90D-4E49-B60A-741D4F91C3CE
Content-Type
string required

All responses for the service come back as JSON. This header is required on all calls after authentication.

Default:
application/json
API Methods

The API methods allow access to ProDB data.

  • Step 1: authentication of the accessing application
  • Step 2: Retrieve the labels that are assigned to your API key
  • Step 3: Upload the repertoire (META data / Track data)
Authentication Services

Use the authentication services to log in to the ProDB API with your application key, to validate your session token or to end your session.

Authenticate to ProDB / Login
POST /service/authenticate
Validate ProDB Authentication
GET /service/authenticate
Delete session / Logout
DELETE /service/authenticate
Authenticate to ProDB / Login
POST /service/authenticate

Pass in your API key to the autenticate call to get back a pro-auth-key to use in all subsequent calls. NOTE: The pro-auth-key is not required on this call. This call requires the API key to be posted to the system to get back a pro-auth-key.

Request headers

Content-Type
string required

All responses for the service come back as JSON. This header is required on all calls after authentication.

Default:
application/json

Request body

Send the API-Key in the request body.

string
Example:
4H0F3V80-C2DB-4711-8093360D6899CB98

Responses

200 OK

Authentication success

Body

pro-auth-token

string
Example:
B0A61931-E90D-4E49-B60A-741D4F91C3CE
400 Bad Request

Request Failed

401 Unauthorized

Authentication failed

Example Request
Example Response

POST request with API-Key in the request body

curl --data "4H0F3V80-C2DB-4711-8093360D6899CB98" \
     --header "Content-Type: application/json" \
     https://api.pro-agency.net/v0.9/service/authenticate/

Response with “pro-auth-token” in the body

"B0A61931-E90D-4E49-B60A-741D4F91C3CE"
Validate ProDB Authentication
GET /service/authenticate

Authentication

Auth Token
AuthUser

Use this call to validate if your ProDB session token is still valid

Request headers

pro-auth-token
string required

The pro-auth-token is the session token obtained from authenticating to ProDB API using your api key and is required on all calls after authentication.

Example:
B0A61931-E90D-4E49-B60A-741D4F91C3CE
Content-Type
string required

All responses for the service come back as JSON. This header is required on all calls after authentication.

Default:
application/json

Responses

200 OK

Valid Authentication

Body
string
Example:
Valid API Auth-Token
400 Bad Request

Request Failed

401 Unauthorized

Authentication failed

Example Request
Example Response

GET request with “pro-auth-token” in header

curl --header "Content-Type: application/json" \
     --header "pro-auth-token: B0A61931-E90D-4E49-B60A-741D4F91C3CE" \
     https://api.pro-agency.net/v0.9/service/authenticate/

Response if “pro-auth-token” is a valid auth token

"Valid API Auth-Token"
Delete session / Logout
DELETE /service/authenticate

Authentication

Auth Token
AuthUser

Remove this session key for usage.

Request headers

pro-auth-token
string required

The pro-auth-token is the session token obtained from authenticating to ProDB API using your api key and is required on all calls after authentication.

Example:
B0A61931-E90D-4E49-B60A-741D4F91C3CE
Content-Type
string required

All responses for the service come back as JSON. This header is required on all calls after authentication.

Default:
application/json

Responses

200 OK

Logout success

Body
string
Example:
Authorization Deleted
400 Bad Request

Request Failed

401 Unauthorized

Authentication failed

Example Request
Example Response

DELETE request with “pro-auth-token” in header

curl --header "Content-Type: application/json" \
     --header "pro-auth-token: B0A61931-E90D-4E49-B60A-741D4F91C3CE" \
     --request DELETE \
     https://api.pro-agency.net/v0.9/service/authenticate/

Response if “pro-auth-token” is a valid auth token and “pro-auth-token” has been deleted

Authorization Deleted
Label Services

Use the Label Services to retrieve all the data you need to link your assigned labels to the labels in our database.

List Labels
GET /service/label/list
List Labels
GET /service/label/list

Authentication

Auth Token
AuthUser

Get a list of all labels and label IDs that are assigned to your API key / your user account. You need the label IDs for uploading track / META data to ProDB.

Request headers

pro-auth-token
string required

The pro-auth-token is the session token obtained from authenticating to ProDB API using your api key and is required on all calls after authentication.

Example:
B0A61931-E90D-4E49-B60A-741D4F91C3CE
Content-Type
string required

All responses for the service come back as JSON. This header is required on all calls after authentication.

Default:
application/json

Responses

200 OK
Body
Object
LabelId
integer

Unique Label Id

LabelName
string

Label Name

CountryCode
string

Country Code ISO-3166-1 ALPHA-2

LabelCode
string

Label Code

400 Bad Request

Request Failed

401 Unauthorized

Authentication failed

Example Request
Example Response

GET request with “pro-auth-token” in header

curl --header "Content-Type: application/json" \
     --header "pro-auth-token: B0A61931-E90D-4E49-B60A-741D4F91C3CE" \
     https://api.pro-agency.net/v0.9/service/label/list

Response Label List if “pro-auth-token” is a valid auth token

[
    {"LabelId":345,"LabelName":"Red Label Name","CountryCode":"DE","LabelCode":"LC-4711"},
    {"LabelId":876,"LabelName":"Blue Label Name","CountryCode":"DE","LabelCode":"LC-4713"}
]
Track Data Services

List your META-data (releases and tracks) in the P.R.O. database.

List Releases
GET /service/release/list
List Release Tracks
GET /service/release/tracks/{UPC_EAN}
Upload Meta Data
POST /service/upload/release
List Releases
GET /service/release/list

Authentication

Auth Token
AuthUser

Get a list of all Releases that are assigned to your API key / your user account.

Request headers

pro-auth-token
string required

The pro-auth-token is the session token obtained from authenticating to ProDB API using your api key and is required on all calls after authentication.

Example:
B0A61931-E90D-4E49-B60A-741D4F91C3CE
Content-Type
string required

All responses for the service come back as JSON. This header is required on all calls after authentication.

Default:
application/json

Responses

200 OK
Body
Object
LabelName
string

Label Name

Example:
Red Label Name
UPC_EAN
string

Release UPC / EAN

Example:
4047179475025
CatalogueNumber
string

Catalogue Number

Example:
FG54D434
ReleaseTitle
string

Release Title

Example:
Release Name
ReleaseArtist
string

Release Artist

Example:
Artist Name
Tracks
number

Track Numbers

ReleaseDate
string

Release Date

Example:
2020-10-21
TypeContent
string

Type of Content

Example:
Audio
400 Bad Request

Request Failed

401 Unauthorized

Authentication failed

Example Request
Example Response

GET request with “pro-auth-token” in header

curl --header "Content-Type: application/json" \
     --header "pro-auth-token: B0A61931-E90D-4E49-B60A-741D4F91C3CE" \
     https://api.pro-agency.net/v0.9/service/release/list

Response Release List if “pro-auth-token” is a valid auth token

[
    {
        "UPC_EAN":"4047175627422",
        "ReleaseDate":"2013-09-06",
        "ReleaseTitle":"Black Star Release Title",
        "TypeContent":"Audio",
        "Tracks":10,
        "ReleaseArtist":"Max Mustermann",
        "LabelName":"Red Label Name",
        "CatalogueNumber":"FG54D434"
    },
    {
        "UPC_EAN":"7292031795199",
        "ReleaseDate":"2010-01-01",
        "ReleaseTitle":"Chartbreaker",
        "TypeContent":"Audio",
        "Tracks":10,
        "ReleaseArtist":"Renate Mustermann",
        "LabelName":"Blue Label Name",
        "CatalogueNumber":"BLN4712"
        
    }
]
show more
List Release Tracks
GET /service/release/tracks/{UPC_EAN}

Authentication

Auth Token
AuthUser

Get the Release tracks.

Path variables

UPC_EAN
string required

Request headers

pro-auth-token
string required

The pro-auth-token is the session token obtained from authenticating to ProDB API using your api key and is required on all calls after authentication.

Example:
B0A61931-E90D-4E49-B60A-741D4F91C3CE
Content-Type
string required

All responses for the service come back as JSON. This header is required on all calls after authentication.

Default:
application/json

Responses

200 OK
Body
Object
UPC_EAN
string

Release UPC / EAN

Example:
4047179579025
CatalogueNumber
string

Catalogue Number

Example:
GHvC077
ReleaseArtist
string

Release Artist

Example:
Artist Name
ReleaseTitle
string

Release Title

Example:
Release Name
LabelName
string

Label Name

Example:
Red Label Name
Tracks
integer

Tracks

Example:
12
ReleaseDate
string

Release Date

Example:
2020-10-21
TypeContent
string

Type of Content

Example:
Audio
Tracklist
Object

Release Tracks

TrackNumber
integer

Track Number

Example:
1
ISRC
string

ISRC Code

Example:
DEAK81100040
TrackArtist
string

Track Artist

Example:
Artist Name
TrackTitle
string

Track Title

Example:
Track Title
show more
400 Bad Request

Request Failed

401 Unauthorized

Authentication failed

Example Request
Example Response
curl --header "Content-Type: application/json" \
     --header "pro-auth-token: B0A61931-E90D-4E49-B60A-741D4F91C3CE" \
     https://api.pro-agency.net/v0.9/service/release/tracks/90034156996020
[
    {
        "UPC_EAN":"4047175627422",
        "ReleaseDate":"2013-09-06",
        "ReleaseTitle":"Black Star Release Title",
        "TypeContent":"Audio",
        "Tracks":3,
        "ReleaseArtist":"Max Mustermann",
        "LabelName":"Red Label Name",
        "CatalogueNumber":"FG54D434",
        [
            {
                "TrackNumber":1,
                "ISRC":"DE6428907521",
                "TrackArtist":"Max Mustermann",
                "TrackTitle":"Leave No One Behind!"
            },
            {
                "TrackNumber":2,
                "ISRC":"DE6428907522",
                "TrackArtist":"Max Mustermann",
                "TrackTitle":"Corona"
            },
            {
                "TrackNumber":3,
                "ISRC":"DE6428907523",
                "TrackArtist":"Max Mustermann",
                "TrackTitle":"I hate C*ps"
            }
        ]
    },
    {
        "UPC_EAN":"7292031795189",
        "ReleaseDate":"2010-01-01",
        "ReleaseTitle":"Chartbreaker",
        "TypeContent":"Audio",
        "Tracks":2,
        "ReleaseArtist":"Renate Mustermann",
        "LabelName":"Green Label Name",
        "CatalogueNumber":"GLN4715",
        [
            {
                "TrackNumber":1,
                "ISRC":"DE6428907513",
                "TrackArtist":"Renate Mustermann",
                "TrackTitle":"Legalize It"
            },
            {
                "TrackNumber":2,
                "ISRC":"DE64289075241",
                "TrackArtist":"Renate Mustermann",
                "TrackTitle":"Black Vampire"
            }
        ]
    }
]
show more
Upload Meta Data
POST /service/upload/release

Authentication

Auth Token
AuthUser

Upload Meta Date (releases / tracks) to ProDB.

Request headers

pro-auth-token
string required

The pro-auth-token is the session token obtained from authenticating to ProDB API using your api key and is required on all calls after authentication.

Example:
B0A61931-E90D-4E49-B60A-741D4F91C3CE
Content-Type
string required

All responses for the service come back as JSON. This header is required on all calls after authentication.

Default:
application/json

Request body

Send a single release that contains all release information and tracks with each request.

Meta Data Upload Structure

Responses

200 OK
400 Bad Request

Request failed

401 Unauthorized

Authentication failed

406 Not Acceptable

Track not bug-free, we can’t accept that line. See “Meta Data Upload Structure” for the specification of the valid upload format.

Body

List of error messages.

Example Request
curl --header "Content-Type: application/json" \ 
     --header "pro-auth-token: B0A61931-E90D-4E49-B60A-741D4F91C3CE" \
     --data   "@/path/to/your/trackdata.json" \
     https://api.pro-agency.net/v0.9/service/upload/release
Meta Data Upload Structure

Upload struture for Meta-Data.

Object
LabelId
integer required nullable

Marketing LabelId. Get LabelId with method “List Labels”. You can enter the LabelId and / or the LabelName. If you specify both, it is checked whether the LabelId matches the LabelName.

Example:
123
Labelname
string required nullable

Marketing label name You can enter the LabelId and / or the LabelName. If you specify both, it is checked whether the LabelId matches the LabelName.

Max length: 100
Example:
XXX Records
ReleaseArtist
string required

Name of the release artist (e.g. for Various Artists insert „Various Artists“ as release artist and the individual artist of the track in the TrackArtist line)

Max length: 100
Example:
Various Artists
ReleaseTitle
string required

Title of the album, single or EP

Max length: 150
Example:
XXX Album
NameDistributor
string nullable

Name of your main distributor

Max length: 100
Example:
XXX Distribution
CatalogueNumber
string nullable

Internal number of each release on the label release

Max length: 25
Example:
XXX001
Format
string required

Type of carrier

Max length: 30
Example:
CD,LP,MP3,DVD
TypeContent
string required

Type of content (audio or video)

Max length: 10
Example:
Audio
ReleaseDate
string YYYY-MM-DD required

Release date of the track

Min length: 10
Max length: 10
Example:
2014-04-18
StartDate
string YYYY-MM-DD nullable

Start date of rights ownership (usually January 1st of the release year)

Min length: 10
Max length: 10
Example:
2012-01-01
EndDate
string YYYY-MM-DD nullable

End date of rights ownership

Min length: 10
Max length: 10
Example:
2061-12-31
UPC_EAN
string required

EAN – European Article Numbering, UPC – Universal Product Code. Provide only one code per track.

Max length: 15
Example:
4047129768922
TerritoryRights
string required

Territory/territories of rights ownership. Use the ISO-3166-1 ALPHA 2 code for specific countries. Additionally, you can add WW (for worldwide) or EU (for geographical Europe). To limit or extend certain territories use minus (see example).

Example:
WW,-AU,-US
Tracks
Object required

Array of tracks

TrackNumber
number required nullable

Track position on the sound carrier

Example:
3
Track Artist
string required

Artist name of the individual track

Max length: 100
Example:
Max Mustermann
AdditionalTrackContributorsArtist
string nullable

Additonal artists to the TrackArtist (to add more than one artist separate by comma)

Max length: 100
Example:
Artist YXX
AdditionalTrackContributorsAccompanist
string nullable

Additonal artists to the TrackArtist (to add more than one artist separate by comma)

Max length: 100
Example:
Artist ZZZ
AdditionalTrackContributorsFeaturing
string nullable

Additonal artists to the TrackArtist (to add more than one artist separate by comma)

Max length: 100
Example:
Artist YXX
AdditionalTrackContributorsWith
string nullable

Additonal artists to the TrackArtist (to add more than one artist separate by comma)

Max length: 100
Example:
Artist YYY
TrackTitle
string required

Title of the track

Max length: 150
Example:
XXX Track
TrackDuration
string HH:MM:SS nullable

Track duration

Min length: 8
Max length: 8
Example:
00:04:49
TrackVersion
string nullable

Version of the track (remix, original, cover)

Max length: 150
Example:
Radio Edit
ISRC
string required

International Standard Recording Code

Min length: 12
Max length: 12
Example:
DEXXXXXXXXXX
Composer
string required nullable

Name of the composer (first and last name) / Might be empty if Author is specified

Max length: 200
Example:
Christian XXX, Christian YYYY
Author
string required nullable

Name of the author (first and last name) / Might be empty if Composer is specified

Max length: 100
Example:
Christian XXX, Christian YYYY
Publisher
string nullable

Name of Publishing Company

Max length: 200
Example:
XY Publishing
YearOfRecording
string YYYY nullable

The year in which the recording took place

Min length: 4
Max length: 4
Example:
2020
CountryCodeRecording
string required

Country in which the recording took place. Use the ISO-3166-1 ALPHA-2 format.

Min length: 2
Max length: 2
Example:
DE
NameFirstOwner
string required

Name of the original rights owner

Max length: 100
Example:
YYY Records
CountryCodeFirstOwner
string required

Country code of the original rights owner. Use the ISO-3166-1 ALPHA-2 format.

Min length: 2
Max length: 2
Example:
DE
GenreCode
string required

Decide on the Type of Genre of the Track. You can choose only POPULAR or CLASSICAL.

Max length: 9
Example:
CLASSICAL
PercentageRights
number decimal

The percentage of rights that you own of a certain recording

Example:
80.75
show more
Example Release

Upload Release Meta Data Structure

{
    "LabelId": "",
    "Labelname": "Muster Label",
    "ReleaseArtist": "Max Mustermann",
    "ReleaseTitle": "Max Mustermann Allstars Summerhits",
    "NameDistributor": "Name Vertrieb",
    "CatalogueNumber": "DF53423",
    "Format": "CD,LP,MP3",
    "TypeContent": "Video",
    "ReleaseDate": "2014-04-18",
    "StartDate": "2012-01-01",
    "EndDate": "2061-12-31",
    "UPC_EAN": "4047129768922",
    "TerritoryRights": "WW",
    "Tracks":[
        {
            "TrackNumber": 1,
            "TrackArtist": "Max Mustermann",
            "AdditionalTrackContributorsArtist": "",
            "AdditionalTrackContributorsAccompanist": "",
            "AdditionalTrackContributorsFeaturing": "",
            "AdditionalTrackContributorsWith": "",
            "TrackTitle": "Summerhit",
            "TrackDuration": "00:02:56",
            "TrackVersion": "",
            "ISRC": "DEH654336844",
            "Author": "Max Mustermann",
            "Composer": "Max Mustermann / Second Author",
            "Publisher": "",
            "GenreCode": "Popular",
            "YearOfRecording": "2012",
            "CountryCodeRecording": "DE",
            "NameFirstOwner": "Muster Label",
            "CountryCodeFirstOwner": "DE",
            "PercentageRights": 80.75
        },
        {
            "TrackNumber": 2,
            "TrackArtist": "Max Mustermann",
            "AdditionalTrackContributorsArtist": "",
            "AdditionalTrackContributorsAccompanist": "",
            "AdditionalTrackContributorsFeaturing": "",
            "AdditionalTrackContributorsWith": "",
            "TrackTitle": "Next Summerhit",
            "TrackDuration": "00:02:32",
            "TrackVersion": "",
            "ISRC": "DEH654336845",
            "Author": "Max Mustermann",
            "Composer": "Max Mustermann / Second Author",
            "Publisher": "",
            "GenreCode": "Popular",
            "YearOfRecording": "2012",
            "CountryCodeRecording": "DE",
            "NameFirstOwner": "Muster Label",
            "CountryCodeFirstOwner": "DE",
            "PercentageRights": 90
        },
        {
            "TrackNumber": 3,
            "TrackArtist": "Max Mustermann",
            "AdditionalTrackContributorsArtist": "",
            "AdditionalTrackContributorsAccompanist": "",
            "AdditionalTrackContributorsFeaturing": "",
            "AdditionalTrackContributorsWith": "",
            "TrackTitle": "Mega Summerhit",
            "TrackDuration": "00:02:27",
            "TrackVersion": "",
            "ISRC": "DEH654336845",
            "Author": "Max Mustermann",
            "Composer": "Max Mustermann / Second Author",
            "Publisher": "",
            "GenreCode": "Popular",
            "YearOfRecording": "2012",
            "CountryCodeRecording": "DE",
            "NameFirstOwner": "Muster Label",
            "CountryCodeFirstOwner": "DE",
            "PercentageRights": 100
        }
    ]
}
show more