This documentation describes how to interact with TV 2 Play Partner API, also simply called Partner API. The Partner API is a RESTfull web service which acts as a common interface for partners to create and manage TV 2 Play subscriptions.
\nThe Partner API documentation is intended for software developers at partners that wishes to use the Partner API and therefore contains descriptions that requires basic knowledge of RESTful API. The documentation can also be useful for other individuals at the partner, that wants to learn about the logic and behavior of the Partner API and partner subscriptions.
\nhttp://partner-api-status.tv2.dk/
\nThe Partner API documentation contains example requests for all endpoints in multiple programming languages. Moreover, the Partner API is described by Swagger and RapiDoc API documentation which can be reached at:
https://play-partner.tv2api.dk/swagger/views/swagger-ui/index.html and
https://play-partner.tv2api.dk/swagger/views/rapidoc/index.html
Because some requests/responses will contain sensitive data, all data is transmitted via HTTPS on the default port (443). The Partner API is hosted on fault tolerant and redundant servers. Because of this, you must connect to the service via the DNS name and not the IP address directly, as the IP address might change.
\nThe API is build upon the concept of a subscriber, that is subscribed to subscriptions, and each subscription is assigned a product. In order to manage the concepts subscriber, subscription and product, they are each exposed as a resource object in JSON through the endpoints:
\n/subscribers <-- Create, fetch, update or remove subscribers\n/subscriptions <-- Update product and/or agreement ID at a subscriber's subscription \n/products <-- Fetch a list of available products organised by agreement ID\n\nThe subscriber resource contains one or many subscriptions. A subscription resource contains one product ID. The following shows the entire subscriber resource with its subscription:
\n\"subscriber\": {\n \"vasToken\": \"{{vasToken}}\",\n \"email\": \"{{email}}\",\n \"firstName\": \"{{firstName}}\",\n \"birthYear\": {{birthYear}},\n \"gender\": \"{{gender}}\",\n \"associateId\": {{associateId}},\n \"createPasswordLink\": \"{{createPasswordLink}}\",\n \"subscriptions\": [\n {\n \"status\": \"{{status}}\",\n \"start\": \"{{start}}\",\n \"renew\": \"{{renew}}\",\n \"freePeriod\": {{freePeriod}},\n \"productId\": {{productId}},\n \"productName\": \"{{productName}}\",\n \"agreementId\": \"{{agreementId}}\"\n }\n ]\n}\n\n\n\nNOTE: Requests and responses does not contain all of the JSON properties of the respected resource. The expected and necessary properties for the requests and the properties returned in the responses can be seen at the request descriptions.
\n
\n\nNOTE: The endpoint /subscribers can be used to fetch subscriber resources, incl. subscriptions, but can only update the subscriber resource, not the subscription. Use the endpoint /subscriptions to update a subscriber's subscription.
\n
A TV 2 user is a unified single account utillized by the end-user to access TV 2 Play and other systems supplied by TV 2. Logging in requeres an email and a password. Normally the password is set by the end-user at user creation, but if the user is created through the Partner API a create-password-link is sent to the email address. The end-user is free to change the email adress and the password whenever they see fit.
\nA subscriber is an abstraction of the TV 2 user. At subscriber creation, an email and a VAS token is supplied by the partner. At creation, the email is used as an identifier of the TV 2 user that should be linked to the subscriber. If no TV 2 user with the email exists, a new TV 2 user with the email will be created. The VAS token is henceforth used as the subscribers identifier; thus the partner has a subscriber identifier that is independent on the dynamic email of the TV 2 user. Learn more at the section Create subscriber.
A subscriber is created with an active subscription. It is the subscription, that grants the TV 2 user access to watch content at TV 2 Play. If the partner wishes to cancel the subscription, the partner must use the remove subscriber endpoint; learn more at the section Remove subscriber.
A partner can have multiple subscribers, but only one subscriber per TV 2 user and a subscriber has one active subscription, see Figure 1: The partner-subscriber-subscription relation. Thus, it is not possible for a partner to create multiple active subscriptions to one single user. Note that if the partner has cancelled the subscription, by remove subscriber, the subscription is no longer active and the partner is able to create a new active subscription by create subscriber.
\nMoreover, the partner subscription will exist in parallel with a TV 2 subscription, if any, and exist in parallel with any partner subscriptions from other partners, see Figure 2: Parallel existence of TV 2 subscription and partner subscriptions. Meaning, that subscriptions created by the end-user through Play and subscriptions created by partners cannot affect each other. It also means, that a Partner cannot use the Partner API to fetch/search, update or delete TV 2 subscriptions or subscriptions created by other partners. But, the end-user is able to get an overview of all subscriptions and who supplies them at the TV 2 user administration site called Mit TV 2.
\nAll subscriptions are assigned to an agreement ID and a product ID. Both are mandatory at creation and can not be removed. Agreement ID and product ID are updatable, however. Go to Update subscription to learn more about how to update the agreement ID and product ID.
At creation of a subscriber and when updating the agreement ID and/or product ID at the subscription, the agreement ID and product ID has to comply with the agreement-product relation. The agreement-product relation contains two rule sets:
Product availability rules - Each agreement has a list of available products. Get a list of available products by use of Fetch products.
\nProduct upgrade/downgrade rules - When changing a product and keeping the agreement ID unchanged, the resulting product update or downgrade has to comply with the upgrade/downgrade rules that are defined in cooperation with TV 2.
\nWhen the Partner API executes certain requests, the API will send emails to the end-users. The following is a list of actions and the resulting emails.
\nThis service can return two categories of errors; an error and a validation error. A validation error is returned if the input is invalid, e.g. parameters are missing or parameters contains illegal values. Validation errors are returned with HTTP status code 400 and a response body containing a list of validation errors formatted in JSON. A single validation error response can contain one to many validation errors as shown in the example below.
\nHTTP status code: 400\n{\n \"validationErrors\": [\n {\n \"message\": \"Specified value 'newmailtv2.dk' is not a valid email\"\n },\n {\n \"message\": \"vasToken cannot be null\"\n }\n ]\n}\n\nAll other types of errors, that are not validation errors, are returned as an error. An error is returned if, e.g. the VAS token in a create subscriber request is occupied or the product ID is unknown. Errors are returned with a HTTP status code and a response body containing an error code and an error message as shown in the following example.
\nHTTP status code: 400\n{\n \"errorCode\": 5007,\n \"errorMessage\": \"VAS token already in use. Another subscriber at the partner uses the VAS token.\"\n}\n\nThe chapter Error codes contains a list of errors inlc. HTTP status codes, error codes and error messages.
\nErrors are returned with a HTTP status code and a response body containing an error code and an error message. A client of this service can recognize a distinct error by the error code while the error message supplies a human readable error description. The purpose of the error messages is to inform the writer of the service client and therefore it is not recommended to pass the error massage to the end user.
\nTV 2 will charge the partner for subscriptions created by the Partner API accoring to the partner agreement. To avoid charges while testing, there are two options:
\nTest mode
The API will use stubs, programmed to return fixed values. Therefore no changes will be made and therefore change operations (create, update and delete) will not be persisted. Test mode is for checking that requests are readable for the Partner API and responses are readable by the partner.
Test partner key
In addition to a partner key, TV 2 may delever a test partner key. The test partner key gives access to a second account in the production environment at TV 2, called a test account. The test account has the same features as the normal account, but subscriptions are automatically closed after a short amount of days and the partner is not charged for these subscriptions.
\n\nWARNING: By using a test partner key, emails are sent as if using a normal partner key. Therefor it is highly recommended not to use emails of actual people; instead use bogus emails like \"test123456@mailinator.com\".
\n
\n\nNOTE: To test in test mode, you need a partner key.
\n
This chapter explanes the common way of dealing with specific error responses from the Partner API.
\nQ: I get {\"errorCode\":4007,\"errorMessage\":\"Not acceptable media type, please referer to the documentation for accepted media types\"} in my response body. What should I do?
A: The error is caused by a missing Accept HTTP header. Add the HTTP header Accept with the value application/json.
Q: Why can I not find my subscriber in the response from fetch subscribers?
A: The subscriber may be filtered out. Change the parameters limit, offset and/or status to include the subscriber in the get subscribers response.
Q: I get VAS Token Occupied when creating a subscriber. How can I reuse a VAS token that is occupied?
A: Use remove subscriber to remove/detach the occupying subscriber from your partner user. By doing so, the VAS token will become unoccupied and can be reused at create subscriber. Bevare that remove subscriber closes the subscription of the subscriber and that you will no longer be able to fetch or update the subscriber or the subscription.
This request creates a subscriber with a new subscription with a given product. The create subscriber request requires, as minimum, a VAS token, an email, a product ID and an agreement ID. Go to the parameter description to learn more about these parameters.
At creation, the subscriber is linked to a TV 2 user, which is identified by the email. Shortly after a subscriber has been created, an activation email will be send to the user's email adress notifying, that the user has been granted access to TV 2 Play by the partner.
The result of create subscriber and which activation email is send, is depending on whether a user with the given email already exists at TV 2. Figure 1: Simplified illustration of create subscriber behaviour shows the different outcomes based on the condition.
In short, if the TV 2 user does not exist, a new TV 2 user will be created and related to the partner as a new partner subscriber and be given a new partner subscription. If the TV 2 user already exists, the existing TV 2 user will be related to the partner as a new partner subscriber and be given a new partner subscription.
The activation emails from figure 1 is listed below.
\nIf agreed upon with TV 2, activation emails will not be send. In such case, an extra JSON-property named createPasswordLink will be present at the response body, but only if the request creates a new TV 2 user (alternative to activation email 1). If the request does not create a new TV 2 user, but instead adds a subscription to an existing TV 2 user, the createPasswordLink property will be absent. The link directs to the TV 2 user's create-password-page, where the end-user can set the password for the user's TV 2 account. The link will be deativated 7 days after subscriber creation.
\n\n\nWARNING: A subscriber occupies the VAS token and email at partner level making it impossible for the partner, whom created the subscriber, to create other subscribers with either the same VAS token or the same email. Use remove subscriber in order to reuse the VAS token and/or email.
\n
\n\nNOTE: The VAS token is a unique identifier at partner level, which means that there can only exist one subscriber with a given VAS token per partner. A VAS token can not be occupied by another partner or used to fetch or update subscriptions of other partners or subscriptions from TV 2.
\n
\n\nNOTE: The email is unique at TV 2, which means that there can only be one TV 2 user with a given email. If multiple subscribers from multiple partners are created with the same email, the subscribers shares the same TV 2 user, thus a TV 2 user may have multiple independent subscriptions; one per partner. Subscriptions work independently from other partners, which means that a partner is not able to fetch or interact with subscriptions from other partners. If a partner fetches a subscriber linked to a TV 2 user, that also has been granted subscriptions created by other partners, only the subscriptions created by the partner is returned.
\n
\n\nNOTE: Create subscriber may result in a Product Unavailable Error, if the agreement ID does not include the product ID. Visit the chapter Agreement-Product relation to learn more.
\n
\n\nNOTE: Create subscriber may result in an Unknown Agreement Error, if a non-existing agreement ID has been used.
\n
This request fetches a subscriber by VAS token.
\nThis request fetches a list of subscribers. The list is returned in pages with a size of no more than 100 subscribers. The page number and page size is declared by using the pagination parameters page and limit.
\n\n\nNOTE: If a subscriber has both an active and an expired subscription, both will be returned when fetching subscribers with ACTIVE subscriptions. Currently the status is limited to ACTIVE, which also is default.
\n
This request updates a subscriber. The updatable properties at the subscriber are: vasToken, email, firstName, birthYear, gender and associate ID. It is possible to update just one or a few of the properties by omitting the rest of the properties at the request body. Please browse the example requests to see how to update all properties, update only the vasToken or update only the email.
\nThis request removes/detaches a subscriber from the partner. By removing the subscriber, the subscription is closed and the subscriber's VAS token and email is made available for future creation. The request requires a VAS token and will remove the subscriber of that VAS token. When a subscriber is removed, it is no longer linked to the partner. The subscriber and its subscription can no longer be fetched or updated.
\nIn summery, use remove subscriber to:
\ndelete a subscriber,
\nclose a subscription and
\nfree up VAS token and email for use at create subscriber or update subscription.
\n\n\nNOTE: Although the subscription is closed when removing a subscriber, the TV 2 user persists and the end-user can continue to login into TV 2 Play and other TV 2 services. If the TV 2 user has non-expired subscriptions at other partners or directly at TV 2, the end-user continue to have access to watch content granted by those subscriptions.
\n
\n\nNOTE: The remove subscriber request does not effect other partners. If the subscriber's TV 2 user has subscribers at multiple partners, the other partners can continue to fetch and update the subscribers and subscriptions belonging to that partner.
\n
This request updates a subscription. The updatable properties at the subscription are: productId and agreementId. It is possible to update just one of the properties by omitting the other at the request body.
\nIf the product ID is updated exclusively, the new product ID is validated against the current agreement ID. If the agreement ID is updated exclusively, the new agreement ID is validated against the current product ID. If both the product ID and agreement ID is updated, the new product ID is validated against the new agreement ID.
\nPlease browse the example requests to see how to update all properties, update only the productId or update only the agreementId.
\n\n\nNOTE: Updating the product ID may result in a Product Unavailable error, if the agreement ID does not include the product ID, or a Product Change Violation error, if the product change violates the product change rules of the agreement ID. Product Change Violation errors can only occur, if the product is changed to another product within the same agreement ID, e.g. if the agreement ID is not updated.
\n
\n\nNOTE: Updating the agreement ID may result in a Product Unavailable error, if the agreement ID does not include the product ID.
\n
\n\nNOTE: Updating the agreement ID may result in an Unknown Agreement Error, if a non-existing agreement ID has been used.
\n
\n\nNOTE: Changing the product of a subscription by updating the product ID will not replace/close subscriptions given by TV 2 or other partners.
\n
This request fetches a single product. The product contains a product ID and the full product name.
\nThis request fetches products available for the partner. The response contains a map of agreement ID's and products. Each product contains a product ID and the full product name.
\n