Table of Contents

Application Programming Interface (API)

Benjamin Norton Updated by Benjamin Norton

Referrer Public API

Summary

The following public API’s/routes are available for use by referrers, without HTTP header authentication. 

API List

Purpose

HTTP Method(s)

Route

Response (Success/Fail)

Register a user from a referrer

POST, OPTIONS

/en/public/api/1.0.0/unauthorized/referrers/register

HTML/HTML

URL Construction

The root address is: 

https://api.pitchhub.com/en/public/api/1.0.0/unauthorized

API details

Register a user from a referrer

This API is being designed and is not available yet (Oct 2021)

Referrer site registers a user using a JWT Token, which has information about the user and authentication information.

If the user is already on the site then this action will connect the user's profile to this registration information. So this API can be called for both new users and existing users.

The POST method is used in order to avoid exposing the JWT

Request

Relative Route

/referrers/register

Route Parameters

None

Body Parameters

The following request body will be in JSON format

ID

Required

Description

jwt

Yes

JWT token containing information about the user and the referrer

JWT field parameters

CAR Field ID

Type

Required

Note

bre

string

--

Bureau of Real Estate ID

cell

string

--

User's cell phone number

city

string

--

User's city

company

string

--

User's company name

email

string

Yes

User's email address

exp

int

Yes

Authorization Expiration time for the JWT token; Unix Epoch time, UTC.

first_name

string

Yes

User's first name

last_name

string

Yes

User's last name

nrds

string

Yes

NAR Id

phone

string

--

User's phone number

state

string

--

User's state (U.S.)

street

string

--

Users street address

zip

string

--

User's zip code

promotion_code

string

--

Promotion Code string

referrer

string

Yes

Lower-case domain name of referring organizations

publish_groups

int array

Yes

Hard coded token values which map to groups of published content -- "Publish Group"

access_scope

string

--

Optional. Specifies the type of access to the Publish Groups. Default value is read-published.

content_exp

int

Authorization Expiration time for the content access; Unix Epoch time, UTC.

Example URL
https://api.pitchhub.com/en/public/api/1.0.0/unauthorized/referrers/register
Example Responses

The default response will be a HTTP redirection response, to the "/pages/login" routes on the front-end server which is associated to this API server.

Example: success -- HTTP status: 200

{
    "url": "https://www.pitchhub.com/pages/referrers-register?authorization_token=########&new_user=1&"
}
  • When HTTP status 200 is returned, the browser should be redirected to the URL indicated in the url response result. This URL will include some query parameters which are then used by the front-end software.

Example: incorrect route or HTTP method: -- HTTP status: 404

(no "URL" field)

{
    "error_code": "general.internal_server_exception",
    "error": "A system error occurred"
}

Example: invalid signature - HTTP Status: 401

{
    "error": "Provided JWT token is invalid: signature invalid",
    "error_code": "authorizations.invalid_jwt",
    "url": "https://app.pitchhub.com/pages/referrers-register?error=Provided+JWT+token+is+invalid%3A+signature+invalid"
}

Example: token expired ("exp" field) - HTTP Status: 401

{
    "error": "Provided JWT token is invalid: expired",
    "error_code": "authorizations.invalid_jwt",
    "url": "https://app.pitchhub.com/pages/referrers-register?error=Provided+JWT+token+is+invalid%3A+expired"
}

Example: missing a field inside the jwt -- HTTP Status: 400

{
    "error": "The field value is invalid: content_exp",
    "error_code": "general.field_value_invalid",
    "url": "https://app.pitchhub.com/pages/referrers-register?error=The+field+value+is+invalid%3A+content_exp"
}

Video Player Public API

Summary

The following public API’s/routes are available for use by other users and services, without authentication. 

API List

Purpose

HTTP Method(s)

Route

Response (Success/Fail)

Video Player IFRAME

GET, OPTIONS

/public/player/iframe/{id}

HTML/HTML

Video Player Embed JavaScript

GET, OPTIONS

/public/player/embed/{id}

JavaScript/HTML

Video Player Thumbnails

GET, OPTIONS

/public/player/thumbnails/{id}

JSON/JSON

Video Player Views

GET, OPTIONS

/public/player/basic-metrics{id}

JSON/JSON

URL Construction

The root address is: 

​https://player.pitchhub.com/en

An example, using the thumbnail API is, in generalized form: 

https://player.pitchhub.com/en/public/player/thumbnails/{id}

 

An example, using the thumbnail API with a specific ID: 

https://player.pitchhub.com/en/public/player/thumbnails/70c030c726183558ce09d52945083df3

API details

Video Player IFRAME

Video player designed to be used inside of an IFRAME, so there are no context controls.

Request

Relative Route

 /public/player/iframe/{id}

Route Parameters

ID

Required

Description

id

Yes

Video Menu token or Video token, also referred to as "id" in the PitchHub Video Export screen.

Example URL:
​https://player.pitchhub.com/en/public/player/70c030c726183558ce09d52945083df3

Example Response:

Valid (200)

Example:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        …
    </head>
    <body>

        <div id="menu"></div>

        <script src="https://player-dev.pitchhub.com/en/public/player/embed/8ee2afe9a240a968191d0ca0b37a4f02"></script>

    </body>

</html>

Not Found (404)

Example:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        …

    </head>
    <body>
        …
    </body>
</html>

Video Player Embedded

Video player designed to be imported in a <script> tag, as JavaScript code.

Request

Relative Route

/public/player/embed/{id}

Route Parameters

ID

Required

Description

id

Yes

Video Menu token or Video token, also referred to as "id" in the PitchHub Video Export screen.

Response

Example URL:

​https://player.pitchhub.com/en/public/player/embed/70c030c726183558ce09d52945083df3

Example Response:

Valid (200)

var defaultScriptElement = document.currentScript;

var constants = {

Asset_Type_Javascript: 'js',

Asset_type_CSS: 'css',

…

Not Found (404)

Example:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <meta http-equiv="X-UA-Compatible" content="IE=edge">
        …
    </head> 

    <body>
        …
    </body> 
</html>

Video Player Thumbnails

Return a JSON object with an array of available thumbnails.

The number of thumbnails in the array will vary depending upon the full size dimensions.  The pixel width and height of each thumbnail is listed, along with the full URL to the thumbnail. 

In the future:

  • Thumbnails can originate from other services (AWS S3/CloudFront, Mux.com, etc.)
  • Thumbnails might have signed URL’s that represent an extremely long amount of time until expiration. 
Request

Relative Route

/public/player/thumbnails/{id}

Route Parameters

ID

Required

Description

id

Yes

Video Menu token or Video token, also referred to as "id" in the PitchHub Video Export screen.

Response

Valid (200)

Example URL:

​https://player.pitchhub.com/en/public/player/thumbnails/70c030c726183558ce09d52945083df3

Example Response:

[
  {
    "width": 100,
    "height": 75,
    "url": "https://image.mux.com/E6Z6YXCnzLAN4Z1xtW2ULO6AQdrSj01bw/thumbnail.png?height=75&width=100&time=2.04271&fit_mode=preserve"
  },
  {
    "width": 200,
    "height": 150,
    "url": "https://image.mux.com/E6Z6YXCnzLAN4Z1xtW2ULO6AQdrSj01bw/thumbnail.png?height=150&width=200&time=2.04271&fit_mode=preserve"
  },
  {
    "width": 295,
    "height": 166,
    "url": "https://image.mux.com/E6Z6YXCnzLAN4Z1xtW2ULO6AQdrSj01bw/thumbnail.png?height=166&width=295&time=2.04271&fit_mode=preserve"
  },
  {
    "width": 640,
    "height": 360,
    "url": "https://image.mux.com/E6Z6YXCnzLAN4Z1xtW2ULO6AQdrSj01bw/thumbnail.png?height=360&width=640&time=2.04271&fit_mode=preserve"
  },
  {
    "width": 940,
    "height": 540,
    "url": "https://image.mux.com/E6Z6YXCnzLAN4Z1xtW2ULO6AQdrSj01bw/thumbnail.png?height=540&width=940&time=2.04271&fit_mode=preserve"
  },
  {
    "width": 1280,
    "height": 720,
    "url": "https://image.mux.com/E6Z6YXCnzLAN4Z1xtW2ULO6AQdrSj01bw/thumbnail.png?height=720&width=1280&time=2.04271&fit_mode=preserve"
  },
  {
    "width": 1920,
    "height": 1080,
    "url": "https://image.mux.com/E6Z6YXCnzLAN4Z1xtW2ULO6AQdrSj01bw/thumbnail.png?height=1080&width=1920&time=2.04271&fit_mode=preserve"
  }
]

Not Found (404)

Example:

{
    "error_code": "general.record_not_found",
    "error": "Record not found"
}

 Video Player Basic Metrics

Return a JSON object with the basic metrics for a video. The metrics are created only for views which take place outside of the PitchHub web app (e.g. HTML "iframe", or "Video Hosted Page")

Request

Relative Route

/public/player/basic-metrics/{id}

Route Parameters

ID

Required

Description

id

Yes

Video Menu token or Video token, also referred to as "id" in the PitchHub Video Export screen.

(note as of June 10, 2021: currently only "Video" entries are supported, not "Video Menus")

Response

Valid (200)

Example URL:

​https://player.pitchhub.com/en/public/player/basic-metrics/70c030c726183558ce09d52945083df3

Example Response:

{
    "play_count": 2
}

Not Found (404)

Example:

{
    "error_code": "general.record_not_found",
    "error": "Record not found"
}

 

How did we do?

Creating Cover Image Thumbnails from Videos

Embedding a YouTube Playlist into your Website

Contact