Create a task

POST/v1/tasks

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

Creates a task and tells the assignee. Without event_id the task belongs to the whole organization.

Assignee: assignee_email or assignee_id; they must be a member of the organization, or a user on the task's event. The task's creator is the API key's user.
Dates: due_date (YYYY-MM-DD) and an optional due_time (HH:mm, 24-hour) in the event's time zone. For an organization task it is the assignee's time zone, else America/New_York. Without a time the task is due at 23:59 that day and has_due_time is false.
Records: the records the task is about, each { type, id }; the first is the primary. Every record must be in your organization, and in the task's event when the task has one.
Reminder: with a due date and no reminder, the assignee is reminded at 09:00 on the due date (9am). Send none to skip it.

Unknown fields are a 400. source is api. Needs write:tasks.

Request example

curl --request POST \
  --url 'https://public-api.sessionboard.com/v1/tasks' \
  --header 'x-access-token: <api-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "event_id": 7001,
  "title": "Chase Dr. Okafor'\''s disclosure",
  "records": [
    {
      "type": "contact",
      "id": "9b2e4c1a-0d3f-4a5b-8c7d-6e5f4a3b2c1d"
    }
  ],
  "assignee_email": "dana@example.org",
  "due_date": "2026-11-20",
  "reminder": "9am",
  "priority": "high"
}'

const response = await fetch('https://public-api.sessionboard.com/v1/tasks', {
  method: 'POST',
  headers: {
    "x-access-token": "<api-token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "event_id": 7001,
    "title": "Chase Dr. Okafor's disclosure",
    "records": [
      {
        "type": "contact",
        "id": "9b2e4c1a-0d3f-4a5b-8c7d-6e5f4a3b2c1d"
      }
    ],
    "assignee_email": "dana@example.org",
    "due_date": "2026-11-20",
    "reminder": "9am",
    "priority": "high"
  }),
});

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

import requests

response = requests.request(
    "POST",
    "https://public-api.sessionboard.com/v1/tasks",
    headers={
        "x-access-token": "<api-token>",
        "Content-Type": "application/json"
    },
    json={
        "event_id": 7001,
        "title": "Chase Dr. Okafor's disclosure",
        "records": [
            {
                "type": "contact",
                "id": "9b2e4c1a-0d3f-4a5b-8c7d-6e5f4a3b2c1d"
            }
        ],
        "assignee_email": "dana@example.org",
        "due_date": "2026-11-20",
        "reminder": "9am",
        "priority": "high"
    },
)

print(response.json())

<?php

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://public-api.sessionboard.com/v1/tasks",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => '{
  "event_id": 7001,
  "title": "Chase Dr. Okafor\'s disclosure",
  "records": [
    {
      "type": "contact",
      "id": "9b2e4c1a-0d3f-4a5b-8c7d-6e5f4a3b2c1d"
    }
  ],
  "assignee_email": "dana@example.org",
  "due_date": "2026-11-20",
  "reminder": "9am",
  "priority": "high"
}',
    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/tasks", strings.NewReader(`{
  "event_id": 7001,
  "title": "Chase Dr. Okafor's disclosure",
  "records": [
    {
      "type": "contact",
      "id": "9b2e4c1a-0d3f-4a5b-8c7d-6e5f4a3b2c1d"
    }
  ],
  "assignee_email": "dana@example.org",
  "due_date": "2026-11-20",
  "reminder": "9am",
  "priority": "high"
}`))
  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/tasks"))
    .header("x-access-token", "<api-token>")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\n  \"event_id\": 7001,\n  \"title\": \"Chase Dr. Okafor's disclosure\",\n  \"records\": [\n    {\n      \"type\": \"contact\",\n      \"id\": \"9b2e4c1a-0d3f-4a5b-8c7d-6e5f4a3b2c1d\"\n    }\n  ],\n  \"assignee_email\": \"dana@example.org\",\n  \"due_date\": \"2026-11-20\",\n  \"reminder\": \"9am\",\n  \"priority\": \"high\"\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.

Request body

application/jsonrequired

event_idinteger
The event the task belongs to. Omit for an organization task.
titlestringrequired
descriptionstring
recordsTaskRecordRef[]
Show child attributes
- typestringrequired
  Allowed values
  "contact", "session", "sponsor", "exhibitor", "group"
- idstringrequired
assignee_idinteger
assignee_emailstring<email>
Instead of assignee_id.
due_datestring<date>
Example
"2026-11-20"
due_timestring
24-hour HH:mm in the event's time zone. Omit for the end of the day.
Pattern
^([01][0-9]|2[0-3]):[0-5][0-9]$
Example
"14:00"
reminderstring
Default: 9am when the task has a due date, otherwise none.

due at the due time, 9am at 09:00 on the due date, 1h an hour before, 1d / 1w at 09:00 one day or one week before.
Allowed values
"none", "due", "9am", "1h", "1d", "1w"
prioritystring
Allowed values
"low", "normal", "high", "urgent"
Default
"normal"

Remind Dana to chase a disclosure by Friday

{
  "event_id": 7001,
  "title": "Chase Dr. Okafor's disclosure",
  "records": [
    {
      "type": "contact",
      "id": "9b2e4c1a-0d3f-4a5b-8c7d-6e5f4a3b2c1d"
    }
  ],
  "assignee_email": "dana@example.org",
  "due_date": "2026-11-20",
  "reminder": "9am",
  "priority": "high"
}

Responses

201`application/json`

Created

dataTask
A to-do for your team, about one or more records, in an event or across the organization.
Show child attributes
- idstring<uuid>
- org_idstring
- event_idinteger | null
- eventobject | null
  Show child attributes
  - idinteger
  - namestring
  - timezonestring
- kindstring
  Allowed values
  "task", "milestone"
- titlestring
- descriptionstring | null
- statusstring
  Allowed values
  "open", "in_progress", "completed", "cancelled"
- prioritystring
  Allowed values
  "low", "normal", "high", "urgent"
- assigneeTaskPerson | any | null
  Show child attributes
  - idinteger
  - first_namestring | null
  - last_namestring | null
  - emailstring
  - photo_urlstring | null
- creatorTaskPerson | any | null
  Show child attributes
  - idinteger
  - first_namestring | null
  - last_namestring | null
  - emailstring
  - photo_urlstring | null
- completed_byTaskPerson | any | null
  Show child attributes
  - idinteger
  - first_namestring | null
  - last_namestring | null
  - emailstring
  - photo_urlstring | null
- recordsTaskRecord[]
  Show child attributes
  - typestring
    A submission is a session.
    Allowed values
    "contact", "session", "sponsor", "exhibitor", "group"
  - idstring
  - labelstring | null
    The contact's name, the session's title, or the sponsor's, exhibitor's or group's name. null when restricted.
  - restrictedboolean
    The key's user cannot read this record, so its label is withheld.
- due_atstring<date-time> | null
- has_due_timeboolean
  false when only a date was set (due at 23:59 that day in the time zone).
- due_datestring<date> | null
  The due date in timezone.
- due_timestring | null
  The due time (HH:mm) in timezone; null when has_due_time is false.
- timezonestring
  The IANA time zone of due_date and due_time — the event's, or for an organization task the assignee's (else America/New_York).
- record_typestring | null
  The primary record's type (the same as records[0].type).
- record_idstring | null
  The primary record's id.
- parent_idstring | null
- start_atstring<date-time> | null
- reminderstring
  Allowed values
  "none", "due", "9am", "1h", "1d", "1w"
- reminder_atstring<date-time> | null
  When the reminder goes to the assignee.
- milestoneobject | null
  Show child attributes
  - idstring
  - titlestring
  - due_atstring<date-time> | null
- sourcestring | null
  Where the task came from, such as api, custom, note or milestone.
- source_note_idstring | null
  The note this task follows up, when it was created from one.
- completion_notestring | null
- completed_atstring<date-time> | null
- follower_idsinteger[]
- is_overdueboolean
- can_editboolean
  The key's user can update, complete or reopen it.
- can_deleteboolean
- created_atstring<date-time>
- updated_atstring<date-time>

400`application/json`

A missing title, a bad date or time, an unknown reminder or field, an assignee who cannot be assigned, a record outside your organization or the event (VALIDATION_ERROR), or a key that belongs to no user (USER_REQUIRED).

errorstring
VALIDATION_ERROR, USER_REQUIRED, FORBIDDEN, NOT_FOUND, TASKS_PLATFORM_ONLY, SCOPE_REQUIRED, ORG_WIDE_TOKEN_REQUIRED or INTERNAL_ERROR.
messagestring

401

Unauthorized

403`application/json`

TASKS_PLATFORM_ONLY: the organization uses a self-serve Sessionboard product; Tasks are part of Sessionboard Platform.
SCOPE_REQUIRED: the key lacks read:tasks (reads) or write:tasks (writes). Legacy keys with no scopes can read but not write.
ORG_WIDE_TOKEN_REQUIRED: the key is restricted to particular events; Tasks need a key without an event restriction.
FORBIDDEN: the key's user can read this task but not change it (only the assignee, the creator, a follower or an admin can; only the creator or an admin can delete), or cannot use Tasks (reviewers and portal users).

errorstring
VALIDATION_ERROR, USER_REQUIRED, FORBIDDEN, NOT_FOUND, TASKS_PLATFORM_ONLY, SCOPE_REQUIRED, ORG_WIDE_TOKEN_REQUIRED or INTERNAL_ERROR.
messagestring

Response examples

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "org_id": "<string>",
    "event_id": 123,
    "event": {
      "id": 123,
      "name": "<string>",
      "timezone": "<string>"
    },
    "kind": "task",
    "title": "<string>",
    "description": "<string>",
    "status": "open",
    "priority": "low",
    "assignee": {
      "id": 123,
      "first_name": "<string>",
      "last_name": "<string>",
      "email": "<string>",
      "photo_url": "<string>"
    },
    "creator": {
      "id": 123,
      "first_name": "<string>",
      "last_name": "<string>",
      "email": "<string>",
      "photo_url": "<string>"
    },
    "completed_by": {
      "id": 123,
      "first_name": "<string>",
      "last_name": "<string>",
      "email": "<string>",
      "photo_url": "<string>"
    },
    "records": [
      {
        "type": "contact",
        "id": "<string>",
        "label": "<string>",
        "restricted": true
      }
    ],
    "due_at": "2026-01-15T09:30:00Z",
    "has_due_time": true,
    "due_date": "2026-01-15",
    "due_time": "<string>",
    "timezone": "<string>",
    "record_type": "<string>",
    "record_id": "<string>",
    "parent_id": "<string>",
    "start_at": "2026-01-15T09:30:00Z",
    "reminder": "none",
    "reminder_at": "2026-01-15T09:30:00Z",
    "milestone": {
      "id": "<string>",
      "title": "<string>",
      "due_at": "2026-01-15T09:30:00Z"
    },
    "source": "<string>",
    "source_note_id": "<string>",
    "completion_note": "<string>",
    "completed_at": "2026-01-15T09:30:00Z",
    "follower_ids": [
      123
    ],
    "is_overdue": true,
    "can_edit": true,
    "can_delete": true,
    "created_at": "2026-01-15T09:30:00Z",
    "updated_at": "2026-01-15T09:30:00Z"
  }
}

{
  "error": "<string>",
  "message": "<string>"
}

{
  "error": "TASKS_PLATFORM_ONLY",
  "message": "Tasks are part of Sessionboard Platform."
}

{
  "error": "SCOPE_REQUIRED",
  "message": "Token missing required scope: write:tasks"
}