Ask for an email to watch a recording

POST/v1/organization/{orgId}/marketing/video/items/{mediaId}/gate

US Region: https://public-api.sessionboard.com · EU Region: https://public-api-eu.sessionboard.com

Visitors enter an email before the recording plays, or at atS seconds after watching that far. It uses the recording's sign-up form (made on the first call, with words from the recording). Any valid email unlocks it; only people who tick the box join your list. off: true removes the gate. Calling it again with the same time changes nothing. Returns form_id, at_s and share_path (the page to share). Requires write:marketing; refused for a key restricted to particular events. Also at POST /v1/marketing/video/items/{mediaId}/gate.

Request example

cURL

curl --request POST \
  --url 'https://public-api.sessionboard.com/v1/organization/{orgId}/marketing/video/items/{mediaId}/gate' \
  --header 'x-access-token: <api-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "atS": 0,
  "off": true
}'

JavaScript

const response = await fetch('https://public-api.sessionboard.com/v1/organization/{orgId}/marketing/video/items/{mediaId}/gate', {
  method: 'POST',
  headers: {
    "x-access-token": "<api-token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "atS": 0,
    "off": true
  }),
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.request(
    "POST",
    "https://public-api.sessionboard.com/v1/organization/{orgId}/marketing/video/items/{mediaId}/gate",
    headers={
        "x-access-token": "<api-token>",
        "Content-Type": "application/json"
    },
    json={
        "atS": 0,
        "off": True
    },
)

print(response.json())

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://public-api.sessionboard.com/v1/organization/{orgId}/marketing/video/items/{mediaId}/gate",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => '{
  "atS": 0,
  "off": true
}',
    CURLOPT_HTTPHEADER => [
        "x-access-token: <api-token>",
        "Content-Type: application/json",
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

Go

package main

import (
  "fmt"
  "io"
  "net/http"
  "strings"
)

func main() {
  req, _ := http.NewRequest("POST", "https://public-api.sessionboard.com/v1/organization/{orgId}/marketing/video/items/{mediaId}/gate", strings.NewReader(`{
  "atS": 0,
  "off": true
}`))
  req.Header.Add("x-access-token", "<api-token>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := io.ReadAll(res.Body)

  fmt.Println(string(body))
}

Java

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://public-api.sessionboard.com/v1/organization/{orgId}/marketing/video/items/{mediaId}/gate"))
    .header("x-access-token", "<api-token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"atS\": 0,\n  \"off\": true\n}"))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

Try it

RegionUS Region — https://public-api.sessionboard.comEU Region — https://public-api-eu.sessionboard.com

Authorization

Send asAPI token (x-access-token)OAuth access token (Bearer)

Token

Your token stays in this page. It is sent only to the region above and is never saved; it is gone when you leave or reload the page.

Path parameters

orgId*

mediaId*

Body application/json

{ "atS": 0, "off": true }

POST

Send request

Authorizations

• x-access-tokenstringheader

  Organization API token. Generate from Organization Settings → API Tokens.

• AuthorizationBearer <token>headeror

  OAuth 2.1 access token. Obtained via the OAuth PKCE flow at /oauth/token.

Send one of these. See Authentication.

Path parameters

• orgIdstringpathrequired

  Your organization ID. Any other organization returns 404.

• mediaIdstring<uuid>pathrequired

  The recording (Media item)

Request body

application/json

• atSinteger

  Ask at this second; leave out to ask before it plays

  Minimum

  0

  Maximum

  86400

• offboolean

  Remove the gate

Example

{
  "atS": 0,
  "off": true
}

Responses

200

payload.gated, payload.form_id, payload.at_s, payload.share_path

400

The time is after the end of the recording.

403

• SCOPE_REQUIRED — the token lacks read:marketing (reads) or write:marketing (writes).
• ORG_WIDE_TOKEN_REQUIRED — the token is restricted to particular events; this operation reads the whole organization.
• FORBIDDEN — the organization's plan does not include Marketing, or the token's user cannot change goals (writes need an organization admin or the organization settings permission).

404

The recording is not in your organization.