InPlayer API (2.0.0)

Download OpenAPI specification:Download

INTRODUCTION

Our Paywall platform enables you up to create a detailed subscription business, allowing you to build a consumer base and drive significant revenues. Our paywall supports recurring payments and billing, consumer acquisition, subscriber lifecycle management and gives you consumer retention CRM tools.

Once you have an InPlayer Merchant Account you can use our dashboard at https://dashboard.inplayer.com to publish, manage and sell premium content. However, you can always integrate with our APIs for full custom integration.

INPLAYER API

The InPlayer API has REST architecture. It has mostly resource-oriented URLs, and uses standard HTTP response codes to indicate API errors or success requests. Every InPlayer Core Resource has its own URL and each operation (GET, POST, PUT, and DELETE) has a specific meaning

All API requests should be made with Content-Type:application/x-www-form-urlencoded header.

JSON is returned by all API responses, no matter if they are success or errors.

DOCS TERMINOLOGY

In the section bellow you can find explanation about the terms that are used for the Core Resources in the InPlayer Platform. Be sure to read it before you start with custom integration.

Items/Assets and Item Types

Term Explanation
items Items or sometimes referred as Assets are the digital assets that Merchants can protect and sell. Asset is an Item with applied pricing and access options.
item_type Is the type of the digital content that can be created in the InPlayer Platform. The only difference between the Item Types is the premium content type. Currently, only available options for Item Types are html_asset where you can store HTML code or any IFRAME code, and ooyala_asset where you can store digital asset content hosted in Ooyala.
content Content of one Item is the premium content that you can store and protect. Once the Consumer has access to the Item, he can view the content.
metadata Metadata is unlimited key-value store for describing Items.

Access Types

Term Explanation
access_type Types of access that can be used in the system.
period The time frame of the asset access that the consumer get after purchasing.

Access Fees

Term Explanation
access_fee Applied access_type and price to Item.

Items Packages

Term Explanation
package Collection of multiple Items. Packages are group of Items. You can set up Package Access Fee that will be additional pricing option for the Items that belong to a Package. Once the Consumer buys Package Access Fee he will have access to every Item that belongs to the Package.

API ENVIRONMENTS

To make the API as explorable as possible, we have 2 different environments for live or testing purposes. There is no switch for changing between modes, just use the different URLs of our API servers.

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. When a request is valid but does not complete successfully (e.g., 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 missing a required parameter.
401 Unauthorized No valid access token provided.
402 Request Failed The parameters were valid but the request failed.
404 Not Found The requested resource doesn't exist.
409 Conflict The request conflicts with another request.
429 Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of 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

Creates 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_asset" "wowza_asset" "wistia_asset" "livestream_asset"

The name of the item type

content
string

The item's content

title
required
string

The title of the item

access_control_type_id
integer <int64>
metadata
Array of object
external_asset_id
string

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

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

Deletes an item

Authorizations:
path Parameters
id
required
integer

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

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

Updates an item

Authorizations:
path Parameters
id
required
integer

Item id

Request Body schema: application/x-www-form-urlencoded
item_type
required
string

The name of the item type

content
string

The item's content

title
required
string

The title of the item

access_control_type_id
integer <int64>
metadata
Array of object
external_asset_id
string

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

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

Patch item

Authorizations:
path Parameters
id
required
integer

Item id

Request Body schema: application/x-www-form-urlencoded
item_type
string

The name of the item type

content
string

The item's content

title
string

The title of the item

access_control_type_id
integer <int64>
metadata
Array of object
external_asset_id
string

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

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

Get access fees

Returns a collection of fees for a specific asset

path Parameters
id
required
integer

Item 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

Response samples

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

Post access fee

Creates access fee for a specific asset

Authorizations:
path Parameters
id
required
integer

Item 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

Access type id

setup_fee_amount
integer

3

setup_fee_description
string

3.00$ setup fee

trial_period_quantity
integer

2

trial_period_period
string

hour

trial_period_description
string

2 hour access

amount
required
number

5

currency
required
string

USD

description
required
string

5.00$ for 1 hour access

starts_at
string

2019-11-12T11:45:26.371Z (RFC3339)

expires_at
string

2019-11-12T11:45:26.371Z (RFC3339)

Responses

201

Fee created

400

Invalid fee amount

401

Unauthorized

404

Resource not found

422

Unprocessable entity

post /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 -X POST https://services.inplayer.com/v2/items/{id}/access-fees \
    -H "Authorization:Bearer <token>" \
    -d 'access_type_id=1' \
    -d 'amount=2' \
    -d 'currency=EUR' \
    -d 'description=Simple Access Fee' \
    -d 'starts_at=2019-11-12T11:45:26.371Z' \
    -d 'expires_at=2019-11-12T11:45:26.371Z' \
    -d 'trial_period_description=Bla' \
    -d 'trial_period_quantity=1' \
    -d 'trial_period_period=week' \
    -d 'setup_fee_amount=3' \
    -d 'setup_fee_description=3.00$ setup fee' \
    -d 'country_set_id=2'

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 44,
  • "merchant_id": 21,
  • "amount": 5,
  • "currency": "USD",
  • "description": "5.00$ for 1 hour access",
  • "item":
    {
    },
  • "access_type":
    {
    },
  • "trial_period":
    {
    },
  • "setup_fee":
    {
    },
  • "geo_restriction":
    {
    },
  • "expires_at": 1531482438
}

Get access fee

Fetches an access fee by the given ID

path Parameters
id
required
integer

Item id

fee_id
required
integer

Fee id

Responses

200

Fee details

404

Access fee not found

get /v2/items/{id}/access-fees/{fee_id}
Staging Server
https://staging-v2.inplayer.com/v2/items/{id}/access-fees/{fee_id}
Production Server
https://services.inplayer.com/v2/items/{id}/access-fees/{fee_id}

Request samples

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

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 44,
  • "merchant_id": 21,
  • "amount": 5,
  • "currency": "USD",
  • "description": "5.00$ for 1 hour access",
  • "item":
    {
    },
  • "access_type":
    {
    },
  • "trial_period":
    {
    },
  • "setup_fee":
    {
    },
  • "geo_restriction":
    {
    },
  • "expires_at": 1531482438
}

Delete access fee

Deletes an access fee by the given ID

Authorizations:
path Parameters
id
required
integer

Item id

fee_id
required
integer

Fee id

Responses

204

No content

401

Unauthorized

404

Resource not found

412

Unable to process request

delete /v2/items/{id}/access-fees/{fee_id}
Staging Server
https://staging-v2.inplayer.com/v2/items/{id}/access-fees/{fee_id}
Production Server
https://services.inplayer.com/v2/items/{id}/access-fees/{fee_id}

Request samples

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

Response samples

application/json
Copy
Expand all Collapse all
{
  • "code": 401,
  • "message": "Invalid auth token"
}

Put access fee

Update access fee for a specific asset

Authorizations:
path Parameters
id
required
integer

Item id

fee_id
required
integer

Fee 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

Access type id

setup_fee_amount
integer

3

setup_fee_description
string

3.00$ setup fee

trial_period_quantity
integer

2

trial_period_period
string

hour

trial_period_description
string

2 hour access

amount
required
number

5

currency
required
string

USD

description
required
string

5.00$ for 1 hour access

starts_at
string

2019-11-12T11:45:26.371Z (RFC3339)

expires_at
string

2019-11-12T11:45:26.371Z (RFC3339)

Responses

201

Fee created

400

Invalid fee amount

401

Unauthorized

404

Resource not found

422

Unprocessable entity

put /v2/items/{id}/access-fees/{fee_id}
Staging Server
https://staging-v2.inplayer.com/v2/items/{id}/access-fees/{fee_id}
Production Server
https://services.inplayer.com/v2/items/{id}/access-fees/{fee_id}

Request samples

Copy
curl -X PUT https://services.inplayer.com/v2/items/{id}/access-fees{fee_id} \
    -H "Authorization:Bearer <token>" \
    -d 'access_type_id=1' \
    -d 'amount=2' \
    -d 'currency=EUR' \
    -d 'description=Simple Access Fee' \
    -d 'starts_at=2019-11-12T11:45:26.371Z' \
    -d 'expires_at=2019-11-12T11:45:26.371Z' \
    -d 'trial_period_description=Bla' \
    -d 'trial_period_quantity=1' \
    -d 'trial_period_period=week' \
    -d 'setup_fee_amount=3' \
    -d 'setup_fee_description=3.00$ setup fee' \
    -d 'country_set_id=2'

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 44,
  • "merchant_id": 21,
  • "amount": 5,
  • "currency": "USD",
  • "description": "5.00$ for 1 hour access",
  • "item":
    {
    },
  • "access_type":
    {
    },
  • "trial_period":
    {
    },
  • "setup_fee":
    {
    },
  • "geo_restriction":
    {
    },
  • "expires_at": 1531482438
}

Patch access fee

Creates or Updates access fees for a specific asset

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

MK

restriction_type
string

blacklist|whitelist

access_fees
Array of object

Responses

201

Fee created

400

Invalid fee amount

401

Unauthorized

404

Resource not found

422

Unprocessable entity

patch /v2/items/{id}/access-fees/bulk
Staging Server
https://staging-v2.inplayer.com/v2/items/{id}/access-fees/bulk
Production Server
https://services.inplayer.com/v2/items/{id}/access-fees/bulk

Request samples

Copy
curl -X PATCH https://services.inplayer.com/v2/items/{id}/access-fees/bulk \
    -H "Authorization:Bearer <token>" \
    -d 'access_fees[0][id]=0' \
    -d 'access_fees[0][access_type_id]=1' \
    -d 'access_fees[0][amount]=2' \
    -d 'access_fees[0][currency]=EUR' \
    -d 'access_fees[0][description]=Simple Access Fee' \
    -d 'access_fees[0][starts_at]=2019-11-12T11:45:26.371Z' \
    -d 'access_fees[0][expires_at]=2019-11-12T11:45:26.371Z' \
    -d 'access_fees[0][trial_period_description]=Bla' \
    -d 'access_fees[0][trial_period_quantity]=1' \
    -d 'access_fees[0][trial_period_period]=week' \
    -d 'access_fees[0][setup_fee_amount]=3' \
    -d 'access_fees[0][setup_fee_description]=3.00$ setup fee' \
    -d 'access_fees[0][restriction_type]=blacklist' \
    -d 'access_fees[0][country_iso]=MK'

Response samples

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

Get item details

path Parameters
id
required
integer

Item id

merchant_uuid
required
string <uuid>

Merchant's uuid

Responses

200

Item details

404

Item not found

get /v2/items/{merchant_uuid}/{id}
Staging Server
https://staging-v2.inplayer.com/v2/items/{merchant_uuid}/{id}
Production Server
https://services.inplayer.com/v2/items/{merchant_uuid}/{id}

Request samples

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

Response samples

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

V1

All operations related to items/assets

Get access fees

Returns a collection of fees for a specific asset

path Parameters
id
required
integer

Item id

Responses

200

Fees collection

422

Unprocessable entity

get /items/{id}/access-fees
Staging Server
https://staging-v2.inplayer.com/items/{id}/access-fees
Production Server
https://services.inplayer.com/items/{id}/access-fees

Request samples

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

Response samples

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

Get item access

This endpoint checks and retrieves a customer's entitlement to an asset

Authorizations:
path Parameters
id
required
integer

Item id

Responses

200

Item access

401

Unauthorized

402

Payment required

403

Invalid privileges

404

Item not found

422

Unprocessable entity

get /items/{id}/access
Staging Server
https://staging-v2.inplayer.com/items/{id}/access
Production Server
https://services.inplayer.com/items/{id}/access

Request samples

Copy
   curl https://services.inplayer.com/items/{id}/access \
        -H "Authorization:Bearer <token>"

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 44,
  • "account_id": 21,
  • "customer_id": 33,
  • "customer_uuid": "11a7ed90-65d3-4ee2-9d91-4e1409678576",
  • "ip_address": "0.0.0.0",
  • "country_code": "UK",
  • "created_at": 1531482438,
  • "expires_at": 1531482438,
  • "item":
    {
    }
}

Revoke item access

This endpoint revokes a customer's entitlement to an asset. Only merchants are authorized to make this call.

Authorizations:
path Parameters
id
required
integer

Item id

query Parameters
consumer_id
required
integer

Customer's id

Responses

204

Item access deleted

400

Cannot delete resource

401

Unauthorized

403

Invalid privileges

delete /items/{id}/access
Staging Server
https://staging-v2.inplayer.com/items/{id}/access
Production Server
https://services.inplayer.com/items/{id}/access

Request samples

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

Response samples

application/json
Copy
Expand all Collapse all
{
  • "code": 400,
  • "message": "Failed to remove item access"
}

Get item details

path Parameters
id
required
integer

Item id

merchant_uuid
required
string <uuid>

Merchant's uuid

Responses

200