Get an awards program

GET/v1/organization/{orgId}/awards/workspace/programs/{programId}

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

One program in full: its counts and review pass, the nomination form's questions, the scorecard, the winner types, every submitted nomination with its average score (scale questions only), reviewer progress, the winner announcement and its delivery progress (or null), and what the plan allows (plan: one review pass and free submissions on self-serve). Reads only. Requires read:awards; the token's user needs the Awards read permission and must manage the program. Refused for a key restricted to particular events. Also at GET /v1/awards/workspace/programs/{programId}.

Request example

curl --request GET \
  --url 'https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs/{programId}' \
  --header 'x-access-token: <api-token>'

const response = await fetch('https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs/{programId}', {
  method: 'GET',
  headers: {
    "x-access-token": "<api-token>"
  },
});

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

import requests

response = requests.request(
    "GET",
    "https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs/{programId}",
    headers={
        "x-access-token": "<api-token>"
    },
)

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}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "x-access-token: <api-token>",
    ],
]);

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

echo $response;

package main

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

func main() {
  req, _ := http.NewRequest("GET", "https://public-api.sessionboard.com/v1/organization/{orgId}/awards/workspace/programs/{programId}", nil)
  req.Header.Add("x-access-token", "<api-token>")

  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}"))
    .header("x-access-token", "<api-token>")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .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.

Responses

200`application/json`

successboolean
payloadAwardsWorkspaceProgramDetail
Show child attributes
- programAwardsWorkspaceProgram
  Show child attributes
  - idstring<uuid>
  - namestring
  - nomenclaturestring
    Allowed values
    "awards", "grants", "scholarships"
  - descriptionstring | null
  - nomination_modestring
    nominate_others: people nominate someone else. self_only: people submit for themselves. Defaults to the audience's mode.
    Allowed values
    "nominate_others", "self_only"
  - statusstring
    Worked out from the dates: open while it is on the Awards Site and its nomination window is running, reviewing after nominations close, closed when it has nominations and every date has passed.
    Allowed values
    "draft", "open", "reviewing", "closed", "archived"
  - decidedboolean
    At least one winner has been picked.
  - roundAwardsWorkspaceRound | any | null
    Show child attributes
    idstring<uuid>
    namestring
    submission_start_datestring<date-time> | null
    submission_end_datestring<date-time> | null
    The nomination deadline.
    review_start_datestring<date-time> | null
    review_end_datestring<date-time> | null
  - roundsinteger
    How many Rounds the program has (one on self-serve).
  - categoriesAwardsWorkspaceCategory[]
    Show child attributes
    idstring<uuid>
    namestring
  - categories_revisionstring
    Send this as baseRevision when replacing the categories.
  - public_urlstring | null
    The program's sign-in page on the Awards Site, once it has been opened. Empty when the Site has no address yet.
  - countsAwardsWorkspaceProgramCounts
    Show child attributes
    submittedinteger
    Submitted nominations.
    draftsinteger
    Nominations started and not submitted.
    reviewersinteger
    scorecardsinteger
    Finished scorecards.
    reviewedinteger
    Submitted nominations with at least one finished scorecard.
    winnersinteger
  - created_atstring<date-time>
- formobject[]
  The nomination form's questions, in order.
  Show child attributes
  - idstring<uuid>
  - namestring
  - typestring
    Example
    "textarea"
  - requiredboolean
- scorecardobject[]
  The scorecard's questions, in order.
  Show child attributes
  - idstring<uuid>
  - labelstring
  - typestring
    Example
    "scale_1_5"
  - requiredboolean
- winner_typesobject[]
  Show child attributes
  - idstring<uuid>
  - namestring
- submissionsAwardsWorkspaceSubmission[]
  Show child attributes
  - idstring<uuid>
  - friendly_idstring | null
  - nomineestring
    The nominee's name, else their organization, else the friendly id.
  - organizationstring | null
    The nominee's organization.
  - categorystring | null
  - statusstring | null
    Allowed values
    "draft", "pending_payment", "submitted", "under_review", "accepted", "rejected", null
  - submitted_atstring<date-time>
  - average_scorenumber | null
    Average of the scale questions across Reviewers, to one decimal.
  - reviewsinteger
    Reviewers who saved any answer.
  - winnerobject | null
    Show child attributes
    winner_type_idstring<uuid>
    namestring
    Example
    "Winner"
- reviewAwardsWorkspaceReviewProgress
  Show child attributes
  - reviewersobject[]
    Show child attributes
    user_idinteger
    namestring
    emailstring<email>
    assignedinteger
    Nominations assigned, not counting abstentions.
    doneinteger
    Finished scorecards.
  - assignedinteger
  - doneinteger
  - not_startedinteger
    Reviewers with assignments and no finished scorecard.
- announcementAwardsWorkspaceAnnouncement | any | null
  Show child attributes
  - idstring<uuid>
  - statusstring
    Allowed values
    "queued", "sending", "sent", "partial"
  - job_idstring<uuid> | null
  - announced_atstring<date-time> | null
  - completed_atstring<date-time> | null
  - recipientsinteger
  - winnersinteger
    Recipients who won (any winner type).
  - progressobject
    Show child attributes
    sentinteger
    failedinteger
    skippedinteger
    pendinginteger
- planobject
  Show child attributes
  - tierstring
    self_serve for an organization on a self-serve Awards plan; enterprise for every other organization.
    Allowed values
    "self_serve", "enterprise"
  - max_review_roundsinteger | null
    1 on self-serve; null when not limited.
  - feesstring
    enterprise: submission fees need Enterprise Awards.
    Allowed values
    "enterprise", "available"
  - ssostring
    Allowed values
    "enterprise", "available"

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 read:awards. A write scope does not grant reads; a legacy token with no scopes may read.
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: the token's user is not an active member of the organization, lacks the Awards read permission, or does not manage the program.

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).

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": {
    "program": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "nomenclature": "awards",
      "description": "<string>",
      "nomination_mode": "nominate_others",
      "status": "draft",
      "decided": true,
      "round": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "submission_start_date": "2026-01-15T09:30:00Z",
        "submission_end_date": "2026-01-15T09:30:00Z",
        "review_start_date": "2026-01-15T09:30:00Z",
        "review_end_date": "2026-01-15T09:30:00Z"
      },
      "rounds": 123,
      "categories": [
        {
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "<string>"
        }
      ],
      "categories_revision": "<string>",
      "public_url": "<string>",
      "counts": {
        "submitted": 123,
        "drafts": 123,
        "reviewers": 123,
        "scorecards": 123,
        "reviewed": 123,
        "winners": 123
      },
      "created_at": "2026-01-15T09:30:00Z"
    },
    "form": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "type": "textarea",
        "required": true
      }
    ],
    "scorecard": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "label": "<string>",
        "type": "scale_1_5",
        "required": true
      }
    ],
    "winner_types": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>"
      }
    ],
    "submissions": [
      {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "friendly_id": "<string>",
        "nominee": "<string>",
        "organization": "<string>",
        "category": "<string>",
        "status": "draft",
        "submitted_at": "2026-01-15T09:30:00Z",
        "average_score": 123.45,
        "reviews": 123,
        "winner": {
          "winner_type_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "name": "Winner"
        }
      }
    ],
    "review": {
      "reviewers": [
        {
          "user_id": 123,
          "name": "<string>",
          "email": "jane@example.com",
          "assigned": 123,
          "done": 123
        }
      ],
      "assigned": 123,
      "done": 123,
      "not_started": 123
    },
    "announcement": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "status": "queued",
      "job_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "announced_at": "2026-01-15T09:30:00Z",
      "completed_at": "2026-01-15T09:30:00Z",
      "recipients": 123,
      "winners": 123,
      "progress": {
        "sent": 123,
        "failed": 123,
        "skipped": 123,
        "pending": 123
      }
    },
    "plan": {
      "tier": "self_serve",
      "max_review_rounds": 123,
      "fees": "enterprise",
      "sso": "enterprise"
    }
  }
}

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

{
  "error": "SCOPE_REQUIRED",
  "message": "Token missing required scope: read:awards"
}

{
  "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": "NOT_FOUND",
  "message": "Awards Program could not be found"
}

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

Get an awards program

Request example

Try it

Authorizations

Path parameters

Responses

200application/json

400application/json

401

403application/json

404application/json

429application/json

Response examples

200`application/json`

400`application/json`

403`application/json`

404`application/json`

429`application/json`