InPlayer API (2.0.0)

Download OpenAPI specification:Download

INTRODUCTION

InPlayer equips you to run a detailed subscription business model, to build and grow your consumer base, and drive significant revenues. Our paywall supports recurring payments and billing cycles, consumer acquisition, subscriber lifecycle management, and provides you with consumer retention CRM tools.

Once you create an InPlayer Merchant Account, you are entitled to using our InPlayer dashboard for publishing, managing, and selling your premium content. Moreover, you can always integrate with our APIs for a full custom integration.

INPLAYER API

The InPlayer API follows the REST architectural style and uses standard HTTP response codes to indicate success requests (2xx) or API errors (4xx, 5xx). Each of the InPlayer Core Resources (Accounts & Authentication, Asset & Access, Payments & Subscriptions, Vouchers & Promotions, Branding, Restrictions & Rules, Reporting, Analytics, and Features) has their own URL and each of the operations involved (POST, PUT, PATCH, GET, and DELETE) carries a specific meaning like creating, updating, fetching, deleting data, and much more.

All API requests should contain Content-Type:application/x-www-form-urlencoded header. The responses are always returned in JSON object(s), both for the successful requests and the failed attempts (errors).

DOCS TERMINOLOGY

The following section defines the domain language used across our platform. Proceed reading to introduce yourself to the terms employed for each of our Core Resources before you start working on your custom integration.

Items/Assets and Item Types

Term Explanation
items The digital Assets that Merchants can protect and sell. Asset is an Item with applied pricing and access options.
item_type The type of the digital content that can be created in the InPlayer platform. According to the type of the premium content, we distinguish between a few item types. Currently, we support HTML/Text (where you can store HTML code or any IFRAME code), video, file, and RSS type of asset.
content The content of the Item is the premium content that you can store and protect. Once the Customer has access to the Item, they can view the content.
metadata An unlimited key-value store containing additional info of the Item concerned.

Access Types

Term Explanation
access_type The supported types of granting access in the system (pay-per-view and subscription).
period The period of the access entitlement that consumers get after purchasing the asset.

Access Fees

Term Explanation
access_fee The applied access_type and price to an Item.

Items Packages

Term Explanation
package The Packages are a collection of multiple Items (a group of Items). You can set up a Package Access Fee as an additional pricing option for Items that are part of a given Package. Once the Customer buys the Package Access Fee, they will have access to every Item that belongs to that Package.

API ENVIRONMENTS

To make the API as explorable as possible, we have two different environments for production related and testing purposes. There is no switch for changing between modes, so just refer to the URL you need.

ERRORS

InPlayer uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g. a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with InPlayer's servers.

Not all errors map cleanly onto HTTP response codes, however. For instance, when a request is valid but does not complete successfully (e.g. if asset access is not found), we return a 402 error code.

List of status codes

Status code Explanation
200 OK Everything worked as expected.
201 Created The resource has been created.
202 Accepted The request has been accepted for processing, but the processing has not been completed.
204 No Content The server has fulfilled the request but does not need to return an entity-body.
400 Bad Request The request was unacceptable, often due to omission of a required parameter.
401 Unauthorized No valid access token has been provided.
402 Request Failed The parameters were valid but the request failed.
404 Not Found The requested resource does not exist.
409 Conflict The request conflicts with another request.
429 Too Many Requests Too many requests have been sent to the API in a short amount of time. We recommend using exponential backoff for your requests.
500, 502, 503, 504 Server Errors Something went wrong on InPlayer's end.

Authentication

bearerAuth

You can create a JSON Web Token (JWT) via the authenticate endpoint. Usage format: Bearer <JWT>

Security scheme type: HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

V2

All operations related to items/assets

Create item

Enables the merchant to create an item.

Authorizations:
Request Body schema: application/x-www-form-urlencoded
item_type
required
string
Enum: "package" "html_asset" "ooyala_asset" "brightcove_asset" "cloudfront_asset" "dacast_asset" "sportradar_asset" "panopto_asset" "qbrick_asset" "kaltura_asset" "jw" "wowza_asset" "wistia_asset" "livestream_asset" "streamamg_asset" "template_id"

One of the asset types (HTML/Text, Video, File or RSS )

content
string

The item's content

title
required
string

The title of the item

access_control_type_id
integer <int64>

Shows the access control type ID carrying one of the enlisted values:

  • 1 - Paid ("name")
  • 2 - Code ("id")
  • 3 - Auth ("auth")
metadata
Array of objects

Object containing additional information about the item

external_asset_id
string

The external asset identifier set by the hosting platform or OVP provider

template_id
int

Template id for asset

Responses

201

Created asset

401

Unauthorized

403

Invalid privileges

422

Cannot create resource

post /v2/items

Staging Server

https://staging-v2.inplayer.com/v2/items

Production Server

https://services.inplayer.com/v2/items

Request samples

Copy
curl https://services.inplayer.com/v2/items \
    -H 'Authorization:Bearer <token>' \
    -d item_type=inplayer_asset \
    -d title="Foo bar" \
    -d metadata[foo]=bar
    -d external_asset_id=eaeEa521edAx

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": 33,
  • "merchant_id": 21,
  • "merchant_uuid": "e5ac2013-8d10-42ba-abb5-291c5201cea8",
  • "active": true,
  • "title": "Foo bar",
  • "access_control_type":
    {
    },
  • "item_type":
    {
    },
  • "age_restriction":
    {
    },
  • "metahash":
    {
    },
  • "created_at": 1531482438,
  • "updated_at": 1531482438,
  • "template_id": 1
}

Delete item

Enables the merchant to delete a given item.

Authorizations:
path Parameters
id
required
integer

Unique item ID

Responses

201

Item deleted

400

Cannot delete resource

401

Unauthorized

403

Invalid privileges

delete /v2/items/{id}

Staging Server

https://staging-v2.inplayer.com/v2/items/{id}

Production Server

https://services.inplayer.com/v2/items/{id}

Request samples

Copy
curl -X DELETE https://services.inplayer.com/v2/items/{id} \
    -H 'Authorization:Bearer <token>'

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "code": 400,
  • "message": "Item not found"
}

Update item

Updates a given asset.

Authorizations:
path Parameters
id
required
integer

Unique item ID

Request Body schema: application/x-www-form-urlencoded
item_type
required
string
Enum: "package" "html_asset" "ooyala_asset" "brightcove_asset" "cloudfront_asset" "dacast_asset" "sportradar_asset" "panopto_asset" "qbrick_asset" "kaltura_asset" "jw" "wowza_asset" "wistia_asset" "livestream_asset" "streamamg_asset" "template_id"

One of the asset types (HTML/Text, Video, File or RSS )

content
string

The item's content

title
required
string

The title of the item

access_control_type_id
integer <int64>

Shows the access control type ID carrying one of the enlisted values:

  • 1 - Paid ("name")
  • 2 - Code ("id")
  • 3 - Auth ("auth")
metadata
Array of objects

Object containing additional information about the item

external_asset_id
string

The external asset identifier set by the hosting platform or OVP provider

template_id
integer

The template id of the item

Responses

201

Updated asset

401

Unauthorized

403

Invalid privileges

422

Cannot create resource

put /v2/items/{id}

Staging Server

https://staging-v2.inplayer.com/v2/items/{id}

Production Server

https://services.inplayer.com/v2/items/{id}

Request samples

Copy
curl -X PUT https://services.inplayer.com/v2/items/{id} \
    -H "Authorization:Bearer <token>" \
    -d title="Foo bar" \
    -d metadata[foo]=bar
    -d external_asset_id=eaeEa521edAx

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": 33,
  • "merchant_id": 21,
  • "merchant_uuid": "e5ac2013-8d10-42ba-abb5-291c5201cea8",
  • "active": true,
  • "title": "Foo bar",
  • "access_control_type":
    {
    },
  • "item_type":
    {
    },
  • "age_restriction":
    {
    },
  • "metahash":
    {
    },
  • "created_at": 1531482438,
  • "updated_at": 1531482438,
  • "template_id": 1
}

Patch item

Authorizations:
path Parameters
id
required
integer

Unique item ID

Request Body schema: application/x-www-form-urlencoded
item_type
string
Enum: "package" "html_asset" "ooyala_asset" "brightcove_asset" "cloudfront_asset" "dacast_asset" "sportradar_asset" "panopto_asset" "qbrick_asset" "kaltura_asset" "jw" "wowza_asset" "wistia_asset" "livestream_asset" "streamamg_asset"

One of the asset types (HTML/Text, Video, File or RSS )

content
string

The item's content

title
string

The title of the item

access_control_type_id
integer <int64>

Shows the access control type ID carrying one of the enlisted values:

  • 1 = Paid ("name")
  • 2 = Code ("id")
  • 3 = Auth ("auth")
metadata
Array of objects

Object containing additional information about the item

external_asset_id
string

The external asset identifier set by the hosting platform or OVP provider

Responses

201

Patched asset

401

Unauthorized

403

Invalid privileges

422

Cannot create resource

patch /v2/items/{id}

Staging Server

https://staging-v2.inplayer.com/v2/items/{id}

Production Server

https://services.inplayer.com/v2/items/{id}

Request samples

Copy
curl -X PATCH https://services.inplayer.com/v2/items/{id} \
    -H "Authorization:Bearer <token>" \
    -d title="Foo bar" \
    -d metadata[foo]=bar
    -d external_asset_id=eaeEa521edAx

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "id": 33,
  • "merchant_id": 21,
  • "merchant_uuid": "e5ac2013-8d10-42ba-abb5-291c5201cea8",
  • "active": true,
  • "title": "Foo bar",
  • "access_control_type":
    {
    },
  • "item_type":
    {
    },
  • "age_restriction":
    {
    },
  • "metahash":
    {
    },
  • "created_at": 1531482438,
  • "updated_at": 1531482438,
  • "template_id": 1
}

Get access fees

Lists the various fees for a specific asset.

Authorizations:
path Parameters
id
required
integer

Unique item ID

query Parameters
expand[voucher]
integer

Voucher ID

Responses

200

Fees collection

422

Unprocessable entity

get /v2/items/{id}/access-fees

Staging Server

https://staging-v2.inplayer.com/v2/items/{id}/access-fees

Production Server

https://services.inplayer.com/v2/items/{id}/access-fees

Request samples

Copy
curl https://services.inplayer.com/v2/items/{id}/access-fees?expand[voucher]=14

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Post access fee

Creates access fee for a specific asset

Authorizations:
path Parameters
id
required
integer

Unique item ID

query Parameters
expand[voucher]
integer

Voucher ID

Request Body schema: application/x-www-form-urlencoded
One of
  • Country ISO
  • Country Set
country_iso
string

MK

restriction_type
string

blacklist|whitelist

access_type_id
required
integer

a number denoting that the access type of interest is granted via the pay-per-view, subscription, or season alternative