Deezer Partner API
alt text
What's the purpose of the Deezer Partner API ?
This API is particularly convenient for a Partnership where the Partner wants to have a complete ownership regarding the
subscription process and the billing of their customers.
This means that the Partner will be able to manage the whole life cycle of Deezer subscriptions for your customers from
A to Z and only with the help of this API.
Definitions
Find below all the concepts we use at Deezer to describe how our API works. In relation with that concepts, you will find
the technical name of the parameter that will be used further in the API, just for your information.
DEEZER B2B OFFER
A Deezer offer that is a result of a commercial agreement between the Partner and Deezer. This offer is distributed
through the Partner's channels.
Parameter name used in the API:
Plain Text
offer_code
PROVISION
A provision happens when Deezer is notified that a Partner's client is eligible to a Deezer B2B offer and subscribed on the
Partner's side.
a t e s s de.
ACTIVATION
When a user has been provisioned, he cannot benefit from his Deezer B2B offer yet, he needs to activate his offer by
associating his new subscription to a Deezer account (existing or new).
This activation can be done by the user or the the Partner with different features that will be presented separately to this
documentation.
ACTIVATION LINK
An activation link is a unique link that can be generated by the Partner through an API call.
This link can be distributed by the Partner to the client through different channels (that have to be secured such as SMS
or personal account)
PARTNER
To access the API, the Partner needs to have an identifier. This identifier is created by Deezer and then communicated to
the Partner.
Parameter name used in the API:
Plain Text
partner_id
SUBSCRIBER
A subscriber is a Partner customer who subscribed to a Deezer B2B offer.
Parameter name used in the API:
Plain Text
subscriber_id
USER
A user defines a Deezer account.
Parameter name used in the API:
Plain Text
user_id
Prerequisites
The only information you need to begin is the credentials that Deezer will provide to you.
These credentials will allow you to build the requests used in our Partner API.
What will be shared with you is:
a unique identifier related to you. We use it to recognize you and whitelist your request
a secret key, related to the unique identifier. That secret key will be used to create an access token that will secure
the requests you will send to our Partner API
Let's get started!
A quick guide to implement our API and what you need to do.
Create a new subscriber
The endpoint you have to call is [Link]
Please note that all requests have to be launched in HTTPS.
Let's create a subscriber with the identifier 123456789.
You will see that it is very simple as you have now your credentials for creating the token and you only have to execute
that command:
Plain Text
curl --location --request POST
"[Link]
With PARTNER_IDENTIFIER the unique identifier we shared with you, and PARTNER_REQUEST_TOKEN built this way:
Sort all the parameters in alphabetical order. In our case, we have these ones: action, partner_id, subscriber.
Concatenate all these sorted parameters with their value to have some kind of passphrase. The result in our
example will be: action=setpartner_id={PARTNER_IDENTIFIER}subscriber_id=123456789
Add your secret key at the end of this passphrase. For example, if your secret key is “azertyuiopmlkjhgfdsq”, your
final passphrase will be “action=setpartner_id=
{PARTNER_IDENTIFIER}subscriber_id=123456789azertyuiopmlkjhgfdsq”
Encrypt your whole obtained passphrase in md5, and you have your token!
It is the simpler action that you can do with our Partner API!
For further more specific use cases, please read the sections below.
Use cases
A Partner's customer just subscribed to an offer
POST Provisioning a subscriber with an end date
https:/[Link]/subscriber/?action=set&partner_id=99&subscriber_id=john@[Link]&token=&offer_code
=0&end_date=2022-01-01 [Link]
PARAMS
action set
Required String
set / get / swap / deactivate
Creates a new subscriber account or updates an existing one, with at least
subscriber_id, operator_id and checksum parameters.
partner_id 99
Required Integer
The Partner's unique identifier created by Deezer.
subscriber_id john@[Link]
Required String
The Partner's customer identifier who subscribed to a Deezer offer
token Required String
The token that you obtain in the "Let's get started!" section
offer_code 0
Optional Integer
0 / ...
The Deezer offer the Partner's customer is elegible to
end_date 2022-01-01 [Link]
Optional Datetime
Y-m-d H:i:s
End date of the Deezer offer
start_date 2020-01-01 [Link]
Optional Datetime
Y-m-d H:i:s
Start date of the Deezer offer
customer_id john@[Link]
Optional String
Customer alias that can be used for association journey
output json
output json
Optional String
json / php / xml
Output format XML, Json or PHP serialized
linked 1
Optional Integer
0 / 1
Indicates that you want to link that subscribtion to the User ID from Deezer
defined below.
user_id 1234567
Optional Integer
User ID retrieved from Deezer service
extra_info Deezer add-on
Optional String
Extra information on the subscriber
instant_login_url 1
Optional Integer
0 / 1
Retrieve a link allowing the user to directly authenticate. user_id must be filled
to get that value.
new_subscriber_id 7654321
Required String
New subscriber of the customer, during a swap
phone_number_creation 1
Optional Integer
0 / 1
If the option is available, automatically create a phone number and a user
associated to this subscriber
user_name john
Optional String
Add a username to the user linked to this subscriber
quicklink 0
Optional Integer
If the option is available, provide an activation lin, allowing to activate the
subscription. An offer_code has to be set to be used.
POST Provisioning a subscriber with no end date
https:/[Link]/subscriber/?action=set&partner_id=99&subscriber_id=john@[Link]&token=&offer_code
0
=0
PARAMS
action set
Required String
set / get / swap / deactivate
Creates a new subscriber account or updates an existing one, with at least
subscriber_id, operator_id and checksum parameters.
partner_id 99
Required Integer
The Partner's unique identifier created by Deezer.
subscriber_id john@[Link]
Required String
The Partner's customer identifier who subscribed to a Deezer offer
token Required String
The token that you obtain in the "Let's get started!" section
offer_code 0
Optional Integer
0 / ...
The Deezer offer the Partner's customer is elegible to
POST Provisioning a subscriber and generating an activation link
https:/[Link]/subscriber/?action=set&partner_id=99&subscriber_id=john@[Link]&token=&offer_code
=0&quicklink=1
PARAMS
action set
Required String
set / get / swap / deactivate
Creates a new subscriber account or updates an existing one, with at least
subscriber_id, operator_id and checksum parameters.
partner_id 99
Required Integer
The Partner's unique identifier created by Deezer.
subscriber id john@[Link]
subsc be _ d jo @[Link]
Required String
The Partner's customer identifier who subscribed to a Deezer offer
token Required String
The token that you obtain in the "Let's get started!" section
offer_code 0
Optional Integer
0 / ...
The Deezer offer the Partner's customer is elegible to
quicklink 1
Optional Integer
If the option is available, provide an activation lin, allowing to activate the
subscription. An offer_code has to be set to be used.
POST Provisioning a subscriber and linking him to a Deezer user
https:/[Link]/subscriber/?action=set&partner_id=99&subscriber_id=john@[Link]&token=&offer_code
=0&user_id=1234567&linked=1
PARAMS
action set
Required String
set / get / swap / deactivate
Creates a new subscriber account or updates an existing one, with at least
subscriber_id, operator_id and checksum parameters.
partner_id 99
Required Integer
The Partner's unique identifier created by Deezer.
subscriber_id john@[Link]
Required String
The Partner's customer identifier who subscribed to a Deezer offer
token Required String
The token that you obtain in the "Let's get started!" section
offer_code 0
Optional Integer
0 / ...
The Deezer offer the Partner's customer is elegible to
user_id 1234567
_
Optional Integer
User ID retrieved from Deezer service
linked 1
Optional Integer
0 / 1
Indicates that you want to link that subscribtion to the User ID from Deezer
defined below.
POST Provisioning a subscriber with a bundle offer (offer with different phases)
https:/[Link]/subscriber/?action=set&partner_id=99&subscriber_id=john@[Link]&token=&bundle_cod
e=0
PARAMS
action set
Required String
set / get / swap / deactivate
Creates a new subscriber account or updates an existing one, with at least
subscriber_id, operator_id and checksum parameters.
partner_id 99
Required Integer
The Partner's unique identifier created by Deezer.
subscriber_id john@[Link]
Required String
The Partner's customer identifier who subscribed to a Deezer offer
token Required String
The token that you obtain in the "Let's get started!" section
bundle_code 0
Optional Integer
0 / ...
The Deezer bundle the Partner's customer is elegible to
A subscriber changed his offer
POST Updating an offer
https:/[Link]/subscriber/?action=set&partner_id=99&subscriber_id=john@[Link]&token=&offer_code
=0
PARAMS
action set
Required String
set / get / swap / deactivate
Creates a new subscriber account or updates an existing one, with at least
subscriber_id, operator_id and checksum parameters.
partner_id 99
Required Integer
The Partner's unique identifier created by Deezer.
subscriber_id john@[Link]
Required String
The Partner's customer identifier who subscribed to a Deezer offer
token Required String
The token that you obtain in the "Let's get started!" section
offer_code 0
Optional Integer
0 / ...
The Deezer offer the Partner's customer is elegible to
POST Updating an end date
https:/[Link]/subscriber/?action=set&partner_id=99&subscriber_id=john@[Link]&token=&end_date=2
022-01-01 [Link]
PARAMS
action set
Required String
set / get / swap / deactivate
Creates a new subscriber account or updates an existing one, with at least
subscriber_id, operator_id and checksum parameters.
partner_id 99
Required Integer
The Partner's unique identifier created by Deezer.
subscriber_id john@[Link]
Required String
The Partner's customer identifier who subscribed to a Deezer offer
token Required String
The token that you obtain in the "Let's get started!" section
end_date 2022-01-01 [Link]
Optional Datetime
Y-m-d H:i:s
End date of the Deezer offer
POST Deprovisioning a user (setting offer_code to 0)
https:/[Link]/subscriber/?action=set&partner_id=99&subscriber_id=john@[Link]&token=&offer_code
=0
PARAMS
action set
Required String
set / get / swap / deactivate
Creates a new subscriber account or updates an existing one, with at least
subscriber_id, operator_id and checksum parameters.
partner_id 99
Required Integer
The Partner's unique identifier created by Deezer.
subscriber_id john@[Link]
Required String
The Partner's customer identifier who subscribed to a Deezer offer
token Required String
The token that you obtain in the "Let's get started!" section
offer_code 0
Optional Integer
0 / ...
The Deezer offer the Partner's customer is elegible to
A subscriber is no longer the Partner's client
POST Deactivating a subscriber
https:/[Link]/subscriber/?action=deactivate&partner_id=99&subscriber_id=john@[Link]&token=
PARAMS
action deactivate
Required String
set / get / swap / deactivate
Creates a new subscriber account or updates an existing one, with at least
subscriber_id, operator_id and checksum parameters.
partner_id 99
Required Integer
The Partner's unique identifier created by Deezer.
subscriber_id john@[Link]
Required String
The Partner's customer identifier who subscribed to a Deezer offer
token Required String
The token that you obtain in the "Let's get started!" section
The subscriber identifier of the user changed (new phone
number or technical migration)
POST Swaping subscribers (only possible with a new subscriber)
https:/[Link]/subscriber/?action=swap&partner_id=99&subscriber_id=john@[Link]&token=&new_sub
scriber_id=jane@[Link]
PARAMS
action swap
Required String
set / get / swap / deactivate
Creates a new subscriber account or updates an existing one, with at least
subscriber_id, operator_id and checksum parameters.
partner_id 99
Required Integer
The Partner's unique identifier created by Deezer.
subscriber_id john@[Link]
Required String
The Partner's customer identifier who subscribed to a Deezer offer
token Required String
The token that you obtain in the "Let's get started!" section
new_subscriber_id jane@[Link]
Required String
New subscriber of the customer, during a swap
Deezer account creation
POST Creating an account with a mail address
https:/[Link]/user/{{email}}?action=set&partner_id=99&token=&name=john&email=john@[Link]&gend
er=M&birthday=1989-06-27
PARAMS
action set
Required String
set / get / swap / deactivate
Creates a new subscriber account or updates an existing one, with at least
subscriber_id, operator_id and checksum parameters.
partner_id 99
Required Integer
The Partner's unique identifier created by Deezer.
token Required String
The token that you obtain in the "Let's get started!" section
name john
Required String
Name of the new user
email john@[Link]
Required String
Email of the new user
gender M
Optional String
M/F
Gender of the new user (Male or Female)
birthday 1989-06-27
Optional String
Birthday date of the new user
POST Creating an account with a phone number (MSISDN)
https:/[Link]/subscriber/?action=set&partner_id=99&token=&offer_code=&subscriber_id=phone number
Phone number account creation is only possible with a special configuration Deezer makes for the Partner where the
MSISDN login method is enabled.
PARAMS
action set
Required String
set / get / swap / deactivate
Creates a new subscriber account or updates an existing one, with at least
subscriber_id, operator_id and checksum parameters.
partner_id 99
Required Integer
The Partner's unique identifier created by Deezer.
token Required String
The token that you obtain in the "Let's get started!" section
offer_code Required Integer
0 / ...
The Deezer offer the Partner's customer is elegible to.
Should be different than 0 for the phone number account creation
subscriber_id phone number
Required String
The Partner's customer identifier who subscribed to a Deezer offer
Sending SMS on provision
POST Sending a SMS when the subscriber identifier is not a phone number (using
parameter customer_id)
https:/[Link]/subscriber/?action=set&partner_id=99&subscriber_id=john@[Link]&token=&offer_code
=0&customer_id=0102030405
PARAMS
action set
Required String
set / get / swap / deactivate
Creates a new subscriber account or updates an existing one, with at least
subscriber_id, operator_id and checksum parameters.
partner_id 99
Required Integer
The Partner's unique identifier created by Deezer.
subscriber_id john@[Link]
Required String
The Partner's customer identifier who subscribed to a Deezer offer.
token Required String
The token that you obtain in the "Let's get started!" section
offer_code 0
Optional Integer
0 / ...
The Deezer offer the Partner's customer is elegible to
customer_id 0102030405
Optional String
Customer alias that can be used for association journey.
Must be a MSISDN to send an SMS
POST Sending an SMS when the subscriber identifier is a phone number
https:/[Link]/subscriber/?action=set&partner_id=99&subscriber_id=john@[Link]&token=&offer_code
=0
PARAMS
action set
Required String
set / get / swap / deactivate
Creates a new subscriber account or updates an existing one, with at least
subscriber_id, operator_id and checksum parameters.
partner_id 99
Required Integer
The Partner's unique identifier created by Deezer.
subscriber_id john@[Link]
Required String
The Partner's customer identifier who subscribed to a Deezer offer.
Must be a MSISDN to send an SMS
token Required String
The token that you obtain in the "Let's get started!" section
offer_code 0
Optional Integer
0 / ...
The Deezer offer the Partner's customer is elegible to
FAQ
Is there a test environment to test the API ?
Yes, you can test our API on our Partner environment : [Link] after whitelisting your
servers IP. You will still need a secret key, partner_id and offer_code to try it.
When should I use the POST request method in this API ?
Every time you would like to create or update the subscriber's data
Is there a specific backoffice for the Partners where we can check the status of our
customers ?
Yes, we have a dedicated back-office for our parners that we can set up : [Link]
Yes, we have a dedicated back office for our parners that we can set up : [Link]
[Link]/partner/{partner_name}. With this, the partner's customer service will be able to check the status
of the subscription and also help some customers to sort out their subscription.
I tried to call the API and I had an error as a result, what do I do ?
Check the error message and try to correct your call accordingly. If the error message is not explicit enough, check if
all the parameters are all correctly spelled and used, the the URL of the API is correct as well. If the issue persists,
contact your point of contact at Deezer or write a mail to support-partners@[Link] !
Is there a way to get some reports ?
Yes you can have reports on a periodic basis, the report can be retrieved on a FTP repository. If you want to have
reports we will set this up for you and give you all the information to access the FTP repository.
What is the advantage of using the "deactivate" method when a customer is no longer your
customer ?
Some Partners decide to just change the offer of a client to offer_code 0 instead of deactivating a user. This can
create issues when doing some reports, that's why we strongly advise that, when a client is no longer with you, you
deactivate him: the subscriber will be erased from our tables and the Deezer account will just turn into a Freemium
account.
Who can I contact if the API does not work properly or if I find a bug ?
support-partners@[Link]
Result codes
Results code will be obtains after each API call to communicate the success or failure of the Partner's API call. If there is
an error, an error message will let you know what you have to change to make your call successful. Each result code will
be sent in a regular json format.
Examples :
SUCCESS
Subscription API call with all the correct parameters.
Plain Text
{
"error": {
},
"results": {
"offer_code": "991",
"bundle_phase_code": "N/A",
"bundle_code": "N/A",
"bundle_creation_date": "N/A",
"quicklink": "[Link]
"result_code": 1,
"result label": "Success"
ERROR
Subscritpion API call with an unexisting offer code.
Plain Text
{
"error": {
"result_code": -40,
"result_label": "Undefined Offer Code"
}
}
You will find below all the result codes you might encounter in your integration journey
Result Code Result Label Detail Behavior
1 Success API call was successful
0 Undefined Error An undefined error retry the API call until
occurred - no action successful
was performed
-1 Undefined Telco Id Your partner_ID is wrong correct the API call with
the right partner_id
-2 Invalid Telco Config There is a problem with contact Deezer Support
the configuration
-3 Internal error -retry There is an internal retry the API call until
server error - no action successful
was performed
-10 Undefined Operator your partner_ID is wrong correct the API call with
the right partner_id
-11 Not allowed IP The IP of the server contact Deezer Support
your are using is not in
Deezer's whitelist
-12 Invalid Token The token does not check the token
correspond to the API calculation
call parameters
