Skip to content

hoichoitech/PartnerAPI

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

4 Commits
README.md
README.md
 
 
SUMMARY.md
SUMMARY.md
 
 

Repository files navigation

Partner API Specification v1.0.0

API Specification

History

Version # Date Author Reviewed By Affected Sections & Summary of Change
v1 Nitesh and Sujith Sujith, Abhishek and Arul Added partner subscription APIs

Overview 4

Audience 4

Getting Started 4

Environment Details 4

API Conventions 5

REST URI 5

Authentication 5

HTTP Operations 5

Common Request Parameters 6

Response Format 6

Common Responses 6

Subscription Service 7

Create Subscription 7

Request: 7

Response: 8

Examples: 9

Update Subscription 11

Request: 11

Response: 12

Examples: 12

Delete Subscription API 15

Request: 15

Response: 15

Examples: 16

Get Subscription API 18

Request 18

Response 18

Examples: 19

Appendix 21

Device Identifier 21

Subscription Status 21

Overview

Viewlift Platform supports creating seamless digital experiences for your brand to reach every device and manage it all with one centralized platform. Viewlift Partners can access some of the APIs for user onboarding, deboarding, managing subscriptions, profile and entitlements exclusively via Partner Integration APIs.

Audience

This document is intended for software developers, architects and technologists planning or creating applications using the Viewlift Platform.

Getting Started

Before getting started you need the following.

Partner APIs are only accessible from a list of Allowed IP addresses. You need to send the IP address range (CIDR) to Viewlift Support in order to successfully communicate with the platform APIs.

The Viewlift Support team will provide you with a partner API key once the IP address has been added to the allowed list.

If you need certificate based authentication please reach out to support for the documentation on steps to be followed.

Environment Details

Apart from the production environment we provide a staging environment for testing and certification purposes.

Environment Domain
Prod prod-api-partner.viewlift.com
Staging staging-api-partner.viewlift.com

API Conventions

Viewlift Partner API provides Restful resource oriented application programming interface that developers can use to work with different platform services. Developers can use the preferred programming language to access the APIs using HTTP requests.

REST URI

https://{baseURI}/{version}/{service}/{resource}}

{baseURI} - The base URI will be different for each environment. Please look at section Environment Details

{service} - The name of the Viewlift Platform service. A set of resources are logically grouped under a specific service. Resources from the subscription service are exposed at this point.

{version} - The version of the API. We ensure that any changes to a specific version made are backward compatible. When there are non backward compatible changes to the APIs we will need you to move to higher versions to use those.

The versions should be specified in the format v1, v2, v3 etc.

Example:

https://prod-api-partner.viewlift.com/v1/subscription

https://prod-api-partner.viewlift.com/v1/subscription/plans

Authentication

  1. We recommend our partners to provide us with a set of ip addresses in order to allow the given IPs access to our APIs.
  2. In case of any queries or any suggestions, please contact techsupport@viewlift.

HTTP Operations

The different operations on resources are mapped to corresponding HTTP operations. Each operation has specific functions and characteristics as explained below.

GET - All safe, idempotent cacheable requests to retrieve the data from the platform.

POST - Non-Idempotent request which will result in the creation of a new resource or updating an existing resource

PUT - Idempotent request which will result in the updating an existing resource

DELETE - Idempotent request to delete or inactivate an existing resource.

Common Request Parameters

Param Type Description Required
Accept Header application/json Y
x-api-key Header Success - New Resource created. Y
Content-Type Header application/json Y
site Query Viewlift provided identifier Y
partner Query Name of the partner Y

Response Format

All responses will be JSON. The content type should be specified as application/json

Common Responses

Response Status Codes:

Code Description
200 Success
201 Success - New Resource created.
400 Failure - Invalid request
401 Unauthorized
403 X-api-key is incorrect. Forbidden
412 Precondition check failed.
500 Failure - Internal Server Error

Subscription Service

Create Subscription

URL: /subscription/{resource}

Http method: POST

Request:

Headers:

Provided in the common request Headers

Query Parameters:

Provided in the common request params.

Body:

Parameter Datatype Description Required
phoneNumber String phone number of the user YES if One Time Password Login is enabled in Viewlift Platform.
email String Email of the user Yes if phoneNumber is not provided
planCode String Plan code of the plan applied to the user YES
startDate String Specify the Start date of the user subscription in UTC NO, default will be current date
endDate String Specify End date of the user subscription in UTC NO, default will be plan duration added to current date
device String Device using which user subscribed for our subscription on partner platform. This should be one of the values in Device Identifier NO, default will be web_browser
externalUserId String Unique identifier used in the partner system to identify a user/account. YES
password String The password for the user registration along with email. Only if the email/password login is the primary option.

Response:

Success:

Parameter Datatype Description
phoneNumber String phone number of the user
email String Email of the user
planCode String Plan code of the plan applied to the user
id String Unique identifier of a user at viewlift server
requestId String Unique Identifier assigned to a partner’s request
startDate String Start date of the user subscription
endDate String End date of the user subscription
status String Subscription status of the user. The status will be one of the Subscription Status

Error:

Parameter Datatype Description
error String Description of the error

Examples:

Request:

curl --location --request POST 'https://staging-api-partner.viewlift.com/subscription/subscribe?site=xyz&#x26;partner=ABC' </p>

--header 'x-api-key: JdfefBdsREfdsgkSBbok02k6RLRzI23wauoSfC3FP7u' </p>

--header 'Content-Type: application/json' </p>

--data-raw '{

"phoneNumber": "+91XXXXXXXXXX",

"device": "android_phone",

"planCode": "configuredPlanCode",

"endDate": "2020-10-04T11:22:23.958Z",

"startDate": "2020-09-04T11:23:42.958Z",

"externalUserId": "123456722"

}'

Response Body (Success): Status Code 201

{

"phoneNumber": "+91XXXXXXXXXX",

"planCode": "configuredPlanCode",

“id”: “1234-XXXXXXXXXX- 45678”,

“requestId”: “4531-XXXXXXXXXXX-342422”,

“startDate”: “2020-09-04T11:23:42.958Z”,

“endDate”: “2020-10-04T11:22:23.958Z”,

"status": "COMPLETED"

}

Response Body (Success): Status Code 200

{

"phoneNumber": "+91XXXXXXXXXX",

"planCode": "configuredPlanCode",

"id": "1234-XXXXXXXXXX- 45678",

"requestId": "4531-XXXXXXXXXXX-342422",

"startDate": "2020-09-04T11:23:42.958Z",

"endDate": "2020-10-04T11:23:42.958Z",

"status": "COMPLETED"

}

Response Body (Failure): Status Code 400

{
"error”: “Invalid Request. Please try again.”

}

Response Body (Failure): Status Code 412

{
"error”: “Precondition check failed. Mandatory parameters are missing. Please try again.”

}

Response Body (Failure): Status Code 500

{
"error”: “Something went wrong. Please contact viewlift technical support (techsupport@viewlift.com) for resolution.”

}

Update Subscription

URL: /subscription/{resource}

Http method: PUT

Request:

Headers:

Provided in the common request Headers

Query Parameters:

Provided in the common request params.

Body:

Parameter Datatype Description Required
phoneNumber String phone number of the user YES if One Time Password Login is enabled in Viewlift Platform.
email String Email of the user

Yes if phoneNumber is not provided

If phoneNumber and email are provided, phoneNumber will be used to identify the user.
planCode String Plan code of the plan applied to the user YES
startDate String Specify the Start date of the user subscription in UTC NO, default will be set to current date
endDate String Specify End date of the user subscription in UTC NO, default will be plan duration added to current date
id String Unique identifier of a user at viewlift server YES, if phoneNumber is not provided.
externalUserId String Unique identifier used in the partner system to identify a user/account. YES

Response:

Success:

Parameter Datatype Description
phoneNumber String phone number of the user
email String Email of the user
planCode String Plan code of the plan applied to the user
id String Unique identifier of a user at viewlift server
requestId String Unique Identifier assigned to a partner’s request
startDate String Start date of the user subscription
endDate String End date of the user subscription
status String Subscription status of the user. The status will be one of the Subscription Status

Error:

Parameter Datatype Description
error String Description of the error

Examples:

Request:

curl --location --request PUT 'https://staging-api-partner.viewlift.com/subscription/subscribe?site=xyz&#x26;partner=ABC' </p>

--header 'x-api-key: JdfefBdsREfdsgkSBbok02k6RLRzI23wauoSfC3FP7u' </p>

--header 'Content-Type: application/json' </p>

--data-raw '{

"phoneNumber": "+91XXXXXXXXXX",

"planCode": "configuredPlanCode",

"endDate": "2020-10-04T11:22:23.456Z",

"startDate": "2020-09-04T11:23:42.456Z",

"externalUserId": "123456722"

}'

Response Body (Success): Status Code 201

{

"phoneNumber": "+91XXXXXXXXXX",

"planCode": "configuredPlanCode",

“id”: “1234-XXXXXXXXXX- 45678”,

“requestId”: “4531-XXXXXXXXXXX-342422”,

“startDate”: “2020-09-04T11:23:42.958Z”,

“endDate”: “2020-10-04T11:23:42.958Z”,

"status": "COMPLETED"

}

Response Body (Success): Status Code 200

{

"phoneNumber": "+91XXXXXXXXXX",

"planCode": "configuredPlanCode",

"id": "1234-XXXXXXXXXX- 45678",

"requestId": "4531-XXXXXXXXXXX-342422",

"startDate": "2020-09-04T11:23:42.958Z",

"endDate": "2020-10-04T11:23:42.958Z",

"status": "COMPLETED"

}

Response Body (Failure): Status Code 400

{
"error”: “Invalid Request. Please try again.”

}

Response Body (Failure): Status Code 412

{
"error”: “Precondition check failed. Mandatory parameters are missing. Please try again.”

}

Response Body (Failure): Status Code 500

{
"error”: “Something went wrong. Please contact viewlift technical support (techsupport@viewlift.com) for resolution.”

}

Delete Subscription API

URL: /subscription

Http method: DELETE

Request:

Headers:

Provided in the common request headers.

Query Parameters:

Please provide the following parameters in addition to what is specified in the common request params.

Parameter Datatype Description Whether mandatory
id String Unique identifier of the user in viewlift platform YES if externalUserId is not provided.
phoneNumber String Phone number of the user YES, if id is not provided
externalUserId String The user id or account id used by the partner to identify the user account. Yes if id is not provided.

Body: No request body

Response:

Success:

Parameter Datatype Description
id String Unique identifier of a user at viewlift server
externalUserId String The user id or account id used by the partner to identify the user account.
status String Current status of the subscription

Error:

Parameter Datatype Description
error String Description of the error

Examples:

Request

curl --location --request DELETE 'https://staging-api-partner.viewlift.com/subscription/subscribe?site=xyz&#x26;id=d5d276fc-f82b-4e21-b1e9-bdddef5e8e7e&#x26;partner=ABC </p>

--header 'x-api-key: JdfefBdsREfdsgkSBbok02k6RLRzI23wauoSfC3FP7u' </p>

--header 'Content-Type: application/json'

Response Body (Success): Status Code 200

{

"subscriptionId": "1234-XXXXXXXXXX- 45678",

"subscriptionStatus": "CANCELLED"

}

Response Body (Failure): Status Code 400

{
"error”: “Invalid Request. Please try again.”

}

Response Body (Failure): Status Code 412

{
"error”: “Precondition check failed. Mandatory parameters are missing. Please try again.”

}

Response Body (Failure): Status Code 500

{
"error”: “Something went wrong. Please contact viewlift technical support (techsupport@viewlift.com) for resolution.”

}

Get Subscription API

URL: /subscription

Http method: GET

Request

Headers:

Provided in the common request headers.

Query Parameters:

Provided in the common request params.

Parameter Datatype Description Whether mandatory
id String Unique identifier of a user at viewlift server YES if externalUserId is not provided
phoneNumber String Phone number of the user Yes if id is not provided
externalUserId String The user id or account id used by the partner to identify the user account. Yes if id is not provided.

Response

Success:

Parameter Datatype Description
id String Unique identifier of a user at viewlift server
phoneNumber String Phone number of the user at viewlift server
planCode String Plan code of the plan subscribed by user in viewlift server
startDate String Start date of the user subscription
endDate String End date of the user subscription
email String Email of the user in viewlift server
status String Subscription status of the user at viewlift server


Error:

Parameter Datatype Description
error String Description of the error

Examples:

Request:

curl --location --request GET 'https://staging-api-partner.viewlift.com/subscription/user?site=xyz&#x26;id=e280c222-768b-4daf-9c23-9741365462c0&#x26;partner=ABC' </p>

--header 'x-api-key: JdfefBdsREfdsgkSBbok02k6RLRzI23wauoSfC3FP7u' </p>

--header 'Content-Type: application/json'

Response Body (Success): Status Code 200

{

“id”: “1234-XXXXXXXXXX- 45678”,

"phoneNumber": "+91XXXXXXXXXX",

“planCode”: “configuredPlanCode”,

"email”: “test1@xyz.com”,

“startDate”: “2020-10-26T14:12:10.476Z”,

“endDate”: “2020-11-26T14:12:10.476Z”,

"status": "CANCELLED"

}

Response Body (Failure): Status Code 400

{
"error”: “Invalid Request. Please try again.”

}

Response Body (Failure): Status Code 412

{
"error”: “Precondition check failed. Mandatory parameters are missing. Please try again.”

}

Response Body (Failure): Status Code 500

{
"error”: “Something went wrong. Please try again later.”

}

Appendix

Device Identifier

ios_phone
web_browser
android_phone
jio_stb
android_tablet
fire_tv
ios_ipad
ios_apple_tv
roku_box

Subscription Status

COMPLETED
SUSPENDED
CANCELLED
DEFERRED_CANCELLATION

About

Docs for hoichoi partner API

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published