Ask to invite Reviewers

POST/v1/organization/{orgId}/awards/workspace/programs/{programId}/reviewers

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

Asks a person to add up to 50 people as Reviewers on the program's review pass. Inviting creates their accounts where needed and emails each one an invitation, so an API call never invites directly: it answers 202 with status: needs_approval and a link, and nothing is sent until a person approves it in Sessionboard Awards. It then runs as that person. Do not call again for the same people. Requires write:awards; the token's user needs the Awards update permission and must manage the program. Refused for a key restricted to particular events. Also at POST /v1/awards/workspace/programs/{programId}/reviewers.

Request example

curl --request POST \
  --url 'https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs/{programId}/reviewers' \
  --header 'x-access-token: <api-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "reviewers": [
    {
      "email": "jane@example.com",
      "firstName": "<string>",
      "lastName": "<string>"
    }
  ],
  "source": {
    "client": "<string>",
    "version": "<string>",
    "run_id": "<string>",
    "prompt": "<string>"
  }
}'

const response = await fetch('https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs/{programId}/reviewers', {
  method: 'POST',
  headers: {
    "x-access-token": "<api-token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "reviewers": [
      {
        "email": "jane@example.com",
        "firstName": "<string>",
        "lastName": "<string>"
      }
    ],
    "source": {
      "client": "<string>",
      "version": "<string>",
      "run_id": "<string>",
      "prompt": "<string>"
    }
  }),
});

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

import requests

response = requests.request(
    "POST",
    "https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs/{programId}/reviewers",
    headers={
        "x-access-token": "<api-token>",
        "Content-Type": "application/json"
    },
    json={
        "reviewers": [
            {
                "email": "jane@example.com",
                "firstName": "<string>",
                "lastName": "<string>"
            }
        ],
        "source": {
            "client": "<string>",
            "version": "<string>",
            "run_id": "<string>",
            "prompt": "<string>"
        }
    },
)

print(response.json())

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs/{programId}/reviewers",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => '{
  "reviewers": [
    {
      "email": "jane@example.com",
      "firstName": "<string>",
      "lastName": "<string>"
    }
  ],
  "source": {
    "client": "<string>",
    "version": "<string>",
    "run_id": "<string>",
    "prompt": "<string>"
  }
}',
    CURLOPT_HTTPHEADER => [
        "x-access-token: <api-token>",
        "Content-Type: application/json",
    ],
]);

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

echo $response;

package main

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

func main() {
  req, _ := http.NewRequest("POST", "https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs/{programId}/reviewers", strings.NewReader(`{
  "reviewers": [
    {
      "email": "jane@example.com",
      "firstName": "<string>",
      "lastName": "<string>"
    }
  ],
  "source": {
    "client": "<string>",
    "version": "<string>",
    "run_id": "<string>",
    "prompt": "<string>"
  }
}`))
  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))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs/{programId}/reviewers"))
    .header("x-access-token", "<api-token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"reviewers\": [\n    {\n      \"email\": \"jane@example.com\",\n      \"firstName\": \"<string>\",\n      \"lastName\": \"<string>\"\n    }\n  ],\n  \"source\": {\n    \"client\": \"<string>\",\n    \"version\": \"<string>\",\n    \"run_id\": \"<string>\",\n    \"prompt\": \"<string>\"\n  }\n}"))
    .build();

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

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

Try it

Response headers

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.
programIdstring<uuid>pathrequired
The Awards program ID.

Request body

application/jsonrequired

reviewersobject[]required
Min items
1
Max items
50
Show child attributes
- emailstring<email>required
- firstNamestring
  Max length
  80
- lastNamestring
  Max length
  80
sourceAwardsWorkspaceSource
Optional on every write: which assistant is calling and what the person asked it. Recorded with the change in the organization's activity and on any approval request; never stored on the program.
Show child attributes
- clientstring
  The assistant's client name (for example Claude or ChatGPT).
- versionstring
- run_idstring
  Your own id for the conversation.
- promptstring
  What the person asked the assistant.
  Max length
  2000

Example

{
  "reviewers": [
    {
      "email": "jane@example.com",
      "firstName": "<string>",
      "lastName": "<string>"
    }
  ],
  "source": {
    "client": "<string>",
    "version": "<string>",
    "run_id": "<string>",
    "prompt": "<string>"
  }
}

Responses

202`application/json`

Waiting for a person: nothing was sent or published. payload.url opens the request in Sessionboard Awards, where a person approves or declines it. An approved request runs as that person; if it cannot run, the approval's status becomes failed with the reason in error.

successboolean
payloadAwardsWorkspaceApprovalRequest
Show child attributes
- statusstring
  Allowed values
  "needs_approval"
- approval_idstring<uuid>
- urlstring<uri>
  Where a person approves or declines the request in Sessionboard Awards (the workspace's approvals page, /awards/{orgId}/approvals?id={approval_id}).
- messagestring
  Waiting for your OK in Sessionboard: followed by url.
- notestring
  Example
  "Nothing was sent or published. A person approves or declines this in Sessionboard Awards; it then runs as them. Do not call again."
- approvalAwardsWorkspaceApproval
  A request from an assistant that waits for a person.
  Show child attributes
  - idstring<uuid>
  - statusstring
    Allowed values
    "pending", "approved", "declined", "failed"
  - actionstring
    Allowed values
    "open_awards_program", "invite_reviewers", "announce_winners"
  - surfacestring
    Allowed values
    "award_programs", "award_review", "award_winners"
  - titlestring
    Example
    "Open nominations for “Volunteer Awards 2027”"
  - summarystring
    The person's request to the assistant, when source.prompt was sent.
  - targetobject | null
    Show child attributes
    typestring
    Example
    "awards_program"
    idstring
  - event_idinteger | null
  - assistantobject
    Show child attributes
    vendorstring
    labelstring
    clientstring | null
    viastring | null
    Allowed values
    "api_token", "oauth", null
  - requested_byobject
    Show child attributes
    user_idinteger | null
    namestring | null
  - decided_byobject | null
    Show child attributes
    user_idinteger
    namestring | null
  - decided_atstring<date-time> | null
  - errorstring | null
    Why an approved request could not run.
  - remedyobject | null
    A one-step fix offered next to Retry, when there is one.
  - can_retryboolean
  - created_atstring<date-time>
  - productstring
    Allowed values
    "awards"
  - urlstring
    Where a person approves or declines it.

400`application/json`

VALIDATION_ERROR: the body or a path id does not match the schema. Unknown body fields are refused and named in the message; source is always accepted.

Error body for the Awards workspace operations.

errorstringrequired
Allowed values
"VALIDATION_ERROR", "SCOPE_REQUIRED", "ORG_WIDE_TOKEN_REQUIRED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED"
messagestringrequired
codestring
A more specific reason, when there is one (trial_ended, plan_ended).

401

Missing, invalid or expired token.

403`application/json`

SCOPE_REQUIRED: the token lacks write:awards. Legacy tokens with no scopes cannot write.
ORG_WIDE_TOKEN_REQUIRED: the key is restricted to particular events. The Awards workspace covers every awards program in the organization, so use a key without an event restriction.
FORBIDDEN with code: trial_ended or code: plan_ended: the organization's self-serve Awards plan is read-only (the trial ended, or the plan was canceled or is unpaid). Everything can still be read; choose a plan to make changes.
FORBIDDEN with no code: the token's user is not an active member of the organization, lacks the Awards permission the operation needs, does not manage the program, or (for the setup answers) is not an organization admin.

These operations do not return enterprise_only; the Enterprise-only items are listed by GET /v1/organization/{orgId}/awards/workspace/enterprise.

Error body for the Awards workspace operations.

errorstringrequired
Allowed values
"VALIDATION_ERROR", "SCOPE_REQUIRED", "ORG_WIDE_TOKEN_REQUIRED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED"
messagestringrequired
codestring
A more specific reason, when there is one (trial_ended, plan_ended).

404`application/json`

NOT_FOUND: orgId is not the token's organization, or the program is not in it.

Error body for the Awards workspace operations.

errorstringrequired
Allowed values
"VALIDATION_ERROR", "SCOPE_REQUIRED", "ORG_WIDE_TOKEN_REQUIRED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED"
messagestringrequired
codestring
A more specific reason, when there is one (trial_ended, plan_ended).

423`application/json`

A person has paused connected assistants for the organization, so writes from the API wait until they resume it in Sessionboard. code is AGENT_WRITES_PAUSED.

Error body for 423.

statusinteger
successboolean
messagestring
namestring
codestring
paused_atstring<date-time>
When assistants were paused.

429`application/json`

The token's request limit (100 requests per 15 minutes by default, per bucket). Wait Retry-After seconds. The body is the TooManyRequestsError shape — see Rate Limiting.
Writes only: QUOTA_EXCEEDED, the token's daily write quota (10,000 writes a day). It resets at midnight UTC.

responseTooManyRequestsError | AwardsWorkspaceError
name: TooManyRequestsError (TooManyRequestsError)
Body of a 429 from the API's own request limits (per token, and per organization and user). Wait Retry-After seconds.
- statusinteger
  Example
  429
- successboolean
  Example
  false
- messagestringrequired
  Example
  "Error while trying to reach the endpoint: Too many requests"
- namestringrequired
  Allowed values
  "TooManyRequestsError"
Option 2 (AwardsWorkspaceError)
Error body for the Awards workspace operations.
- errorstringrequired
  Allowed values
  "VALIDATION_ERROR", "SCOPE_REQUIRED", "ORG_WIDE_TOKEN_REQUIRED", "FORBIDDEN", "NOT_FOUND", "CONFLICT", "QUOTA_EXCEEDED"
- messagestringrequired
- codestring
  A more specific reason, when there is one (trial_ended, plan_ended).

Retry-Afterintegerheader
Seconds to wait before retrying.

Response examples

{
  "success": true,
  "payload": {
    "status": "needs_approval",
    "approval_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "url": "https://example.com",
    "message": "<string>",
    "note": "Nothing was sent or published. A person approves or declines this in Sessionboard Awards; it then runs as them. Do not call again.",
    "approval": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "status": "pending",
      "action": "open_awards_program",
      "surface": "award_programs",
      "title": "Open nominations for “Volunteer Awards 2027”",
      "summary": "<string>",
      "target": {
        "type": "awards_program",
        "id": "<string>"
      },
      "event_id": 123,
      "assistant": {
        "vendor": "<string>",
        "label": "<string>",
        "client": "<string>",
        "via": "api_token"
      },
      "requested_by": {
        "user_id": 123,
        "name": "<string>"
      },
      "decided_by": {
        "user_id": 123,
        "name": "<string>"
      },
      "decided_at": "2026-01-15T09:30:00Z",
      "error": "<string>",
      "remedy": {},
      "can_retry": true,
      "created_at": "2026-01-15T09:30:00Z",
      "product": "awards",
      "url": "<string>"
    }
  }
}

{
  "error": "VALIDATION_ERROR",
  "message": "Error on body parameter: data should NOT have additional properties: \"winners\""
}

{
  "error": "SCOPE_REQUIRED",
  "message": "This operation requires the 'write:awards' scope."
}

{
  "error": "ORG_WIDE_TOKEN_REQUIRED",
  "message": "The Awards workspace covers every awards program in the organization, so this API key (restricted to particular events) cannot use it. Use a key without an event restriction."
}

{
  "error": "FORBIDDEN",
  "message": "Your Awards trial has ended. Choose a plan to keep going; everything you made is still here.",
  "code": "trial_ended"
}

{
  "error": "FORBIDDEN",
  "message": "Your Awards plan has ended, so the workspace is read-only. Choose a plan to pick up where you left off.",
  "code": "plan_ended"
}

{
  "error": "FORBIDDEN",
  "message": "User is not a manager of this program"
}

{
  "error": "NOT_FOUND",
  "message": "Awards Program could not be found"
}

{
  "status": 423,
  "success": false,
  "message": "A person has paused connected assistants in Sessionboard. Ask them to resume it from their workspace before trying again.",
  "name": "AgentWritesPausedError",
  "code": "AGENT_WRITES_PAUSED",
  "paused_at": "2026-11-06T15:04:05.000Z"
}

{
  "status": 429,
  "success": false,
  "message": "Error while trying to reach the endpoint: Too many requests",
  "name": "TooManyRequestsError"
}

Ask to invite Reviewers

Request example

Try it

Authorizations

Path parameters

Request body

Responses

202application/json

400application/json

401

403application/json

404application/json

423application/json

429application/json

Response examples

202`application/json`

400`application/json`

403`application/json`

404`application/json`

423`application/json`

429`application/json`