Add a sign-up form (no setup)

POST/v1/organization/{orgId}/marketing/audience/forms/ensure

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

The sign-up form for an event page, a library or a recording: the one already there, or a new one with good defaults. With eventId and addToPage: true, the form is also placed on the event page draft (made from the Brand kit when the event has no page yet); payload.page has preview_url and revision. Nothing is published. Calling it again returns the same form. Requires write:marketing. Also at POST /v1/marketing/audience/forms/ensure.

Request example

cURL

curl --request POST \
  --url 'https://public-api.sessionboard.com/v1/organization/{orgId}/marketing/audience/forms/ensure' \
  --header 'x-access-token: <api-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "eventId": 123,
  "placement": "event_page",
  "targetKind": "media_item",
  "targetId": "<string>",
  "name": "<string>",
  "heading": "<string>",
  "body": "<string>",
  "buttonText": "<string>",
  "fields": {
    "name": true,
    "company": true
  },
  "listKey": "<string>",
  "doubleOptIn": true,
  "consentText": "<string>",
  "successMessage": "<string>",
  "addToPage": true
}'

JavaScript

const response = await fetch('https://public-api.sessionboard.com/v1/organization/{orgId}/marketing/audience/forms/ensure', {
  method: 'POST',
  headers: {
    "x-access-token": "<api-token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "eventId": 123,
    "placement": "event_page",
    "targetKind": "media_item",
    "targetId": "<string>",
    "name": "<string>",
    "heading": "<string>",
    "body": "<string>",
    "buttonText": "<string>",
    "fields": {
      "name": true,
      "company": true
    },
    "listKey": "<string>",
    "doubleOptIn": true,
    "consentText": "<string>",
    "successMessage": "<string>",
    "addToPage": 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/audience/forms/ensure",
    headers={
        "x-access-token": "<api-token>",
        "Content-Type": "application/json"
    },
    json={
        "eventId": 123,
        "placement": "event_page",
        "targetKind": "media_item",
        "targetId": "<string>",
        "name": "<string>",
        "heading": "<string>",
        "body": "<string>",
        "buttonText": "<string>",
        "fields": {
            "name": True,
            "company": True
        },
        "listKey": "<string>",
        "doubleOptIn": True,
        "consentText": "<string>",
        "successMessage": "<string>",
        "addToPage": True
    },
)

print(response.json())

PHP

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://public-api.sessionboard.com/v1/organization/{orgId}/marketing/audience/forms/ensure",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => '{
  "eventId": 123,
  "placement": "event_page",
  "targetKind": "media_item",
  "targetId": "<string>",
  "name": "<string>",
  "heading": "<string>",
  "body": "<string>",
  "buttonText": "<string>",
  "fields": {
    "name": true,
    "company": true
  },
  "listKey": "<string>",
  "doubleOptIn": true,
  "consentText": "<string>",
  "successMessage": "<string>",
  "addToPage": 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/audience/forms/ensure", strings.NewReader(`{
  "eventId": 123,
  "placement": "event_page",
  "targetKind": "media_item",
  "targetId": "<string>",
  "name": "<string>",
  "heading": "<string>",
  "body": "<string>",
  "buttonText": "<string>",
  "fields": {
    "name": true,
    "company": true
  },
  "listKey": "<string>",
  "doubleOptIn": true,
  "consentText": "<string>",
  "successMessage": "<string>",
  "addToPage": 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/audience/forms/ensure"))
    .header("x-access-token", "<api-token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"eventId\": 123,\n  \"placement\": \"event_page\",\n  \"targetKind\": \"media_item\",\n  \"targetId\": \"<string>\",\n  \"name\": \"<string>\",\n  \"heading\": \"<string>\",\n  \"body\": \"<string>\",\n  \"buttonText\": \"<string>\",\n  \"fields\": {\n    \"name\": true,\n    \"company\": true\n  },\n  \"listKey\": \"<string>\",\n  \"doubleOptIn\": true,\n  \"consentText\": \"<string>\",\n  \"successMessage\": \"<string>\",\n  \"addToPage\": 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*

Body application/json

{ "eventId": 123, "placement": "event_page", "targetKind": "media_item", "targetId": "<string>", "name": "<string>", "heading": "<string>", "body": "<string>", "buttonText": "<string>", "fields": { "name": true, "company": true }, "listKey": "<string>", "doubleOptIn": true, "consentText": "<string>", "successMessage": "<string>", "addToPage": 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.

Request body

application/json

Every field is optional; defaults come from the event, the organization or the recording.

• eventIdinteger | null
• placementstring

  Allowed values

  "event_page", "gallery", "clip", "recording_gate"

• targetKindstring | null

  Allowed values

  "media_item", "content_item", "gallery", "gallery_item", null

• targetIdstring | null
• namestring

  A label your team sees.

• headingstring
• bodystring
• buttonTextstring
• fieldsobject
  Show child attributes

  • nameboolean
  • companyboolean
• listKeystring
• doubleOptInboolean
• consentTextstring

  What visitors agree to; {org} is replaced with your organization's name.

• successMessagestring
• addToPageboolean

  Also put the form on the event page draft (needs eventId). Never publishes.

Example

{
  "eventId": 123,
  "placement": "event_page",
  "targetKind": "media_item",
  "targetId": "<string>",
  "name": "<string>",
  "heading": "<string>",
  "body": "<string>",
  "buttonText": "<string>",
  "fields": {
    "name": true,
    "company": true
  },
  "listKey": "<string>",
  "doubleOptIn": true,
  "consentText": "<string>",
  "successMessage": "<string>",
  "addToPage": true
}

Responses

200

payload.form, payload.created, and with addToPage payload.page and payload.message

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 event or recording is not in your organization.