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 https://ws.deezer.com/subscriber.

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

"https://ws.deezer.com/subscriber/?action=set&partner_id={PARTNER_IDENTIFIER}&subscriber_id=123

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:/ws.deezer.com/subscriber/?action=set&partner_id=99&subscriber_id=john@doe.com&token=&offer_code
=0&end_date=2022-01-01 20:00:00

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@doe.com

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 20:00:00

Optional Datetime
Y-m-d H:i:s
End date of the Deezer offer

start_date 2020-01-01 20:00:00

Optional Datetime
Y-m-d H:i:s
Start date of the Deezer offer

customer_id john@partner.com

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:/ws.deezer.com/subscriber/?action=set&partner_id=99&subscriber_id=john@doe.com&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@doe.com

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:/ws.deezer.com/subscriber/?action=set&partner_id=99&subscriber_id=john@doe.com&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@doe.com
subsc be _ d jo @doe.co

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:/ws.deezer.com/subscriber/?action=set&partner_id=99&subscriber_id=john@doe.com&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@doe.com

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:/ws.deezer.com/subscriber/?action=set&partner_id=99&subscriber_id=john@doe.com&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@doe.com

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:/ws.deezer.com/subscriber/?action=set&partner_id=99&subscriber_id=john@doe.com&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@doe.com

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:/ws.deezer.com/subscriber/?action=set&partner_id=99&subscriber_id=john@doe.com&token=&end_date=2
022-01-01 20:00:00

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@doe.com

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 20:00:00

Optional Datetime
Y-m-d H:i:s
End date of the Deezer offer

POST Deprovisioning a user (setting offer_code to 0)

https:/ws.deezer.com/subscriber/?action=set&partner_id=99&subscriber_id=john@doe.com&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@doe.com

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:/ws.deezer.com/subscriber/?action=deactivate&partner_id=99&subscriber_id=john@doe.com&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@doe.com

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:/ws.deezer.com/subscriber/?action=swap&partner_id=99&subscriber_id=john@doe.com&token=&new_sub
scriber_id=jane@doe.com

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@doe.com

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@doe.com

Required String
New subscriber of the customer, during a swap

Deezer account creation

POST Creating an account with a mail address

https:/ws.deezer.com/user/{{email}}?action=set&partner_id=99&token=&name=john&email=john@doe.com&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@doe.com

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:/ws.deezer.com/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:/ws.deezer.com/subscriber/?action=set&partner_id=99&subscriber_id=john@doe.com&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@doe.com

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:/ws.deezer.com/subscriber/?action=set&partner_id=99&subscriber_id=john@doe.com&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@doe.com

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 : https://partner-ws.deezerdev.com, 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 : https://bo-
 Yes, we have a dedicated back office for our parners that we can set up : https://bo
partners.deezer.com/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@deezer.com !

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@deezer.com

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": "http://activationlink.com",
"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