Skip to content
Optiwork API Docs

Accept an invitation tentatively

POST
/events/{eventId}/invitations/tentative
curl --request POST \
  --url https://calendar.work.optidata.cloud/api/events/4167/invitations/tentative \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "calendar_id": 10 }'

Answers maybe. Use it when the invitee expects to attend but cannot commit; the status becomes TENTATIVE.

Same calendar_id and recurrence_id semantics as accepting, including replying on behalf of the owner of a calendar you manage.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters”
eventId
required
string

Id of the event, as returned in an event’s id.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Which invitation is being answered, and on whose behalf.

object
calendar_id
required

The caller’s calendar holding the invitation. When it is a calendar shared with the caller and their role is manager or admin, the reply is recorded for the calendar’s owner.

integer
recurrence_id

Start of the occurrence being answered. Omit to answer for the whole series.

string | null
datetime_start

Start of the occurrence, when the client already knows it.

string | null
datetime_end

End of the occurrence, when the client already knows it.

string | null
Examples
Exampletentative
{
  "calendar_id": 10
}

Responses

Section titled “ Responses ”

200

Section titled “200”

The event, with the caller’s participation status updated.

Media typeapplication/json
object
event
required

An event and its occurrences. The event itself carries the identifiers; everything about the schedule lives in instances.

object
id
string | null
uid

ICalendar UID. Unlike id, it survives the event being copied between calendars.

string | null
calendarId
required

Calendar the event lives in.

string
originalCalendarId
string | null
invId

Invitation id. Part of the concurrency triple you send back on an update.

string | null
ms

Modification sequence. Send it back unchanged on an update.

integer | null
rev

Revision. Send it back unchanged on an update.

integer | null
nextAlarm
One of:

The next reminder due for the event.

object
nextAlarmAt

When the reminder fires.

string | null
alarmInstStart

Start of the occurrence it belongs to.

string | null
invId
integer | null
instances
required
Array<object>

One occurrence of an event. A one-off event has exactly one; a recurring event has one per occurrence inside the window you asked for.

object
id
string | null
invId

Invitation id. Send it back when updating or rescheduling.

string | null
status
required

CONF confirmed, TENT tentative, CANC cancelled, NEED awaiting an answer.

string
Allowed values: CONF TENT CANC NEED
recurrenceId

Start of this occurrence, for a recurring event.

string | null
name

Title of the event.

string | null
location
string | null
start
required
string
end
required
string
isOrganizer
required

true when the caller owns the event.

boolean
isRecurring
required
boolean
isException
required

true when this occurrence was detached from its series.

boolean
isAllDay
required
boolean
videoConferenceUrl
string | null
description

Filled in on a single-event read; on a list, only when include_description was requested.

string | null
organizer
One of:

Who owns the event.

object
email
string | null
name
string | null
type
One of:

user is somebody with an Optiwork account in the tenant, group a user group, and guest an address outside it.

string
Allowed values: user guest group
avatarUrl
string | null
sentBy

Set when somebody sent the invitation for the organizer.

string | null
recurrenceRule
One of:

The repetition rule as stored. Mirrors the rule you send, in camelCase.

object
frequency
string
Allowed values: DAILY WEEKLY MONTHLY YEARLY
until
string | null
count
integer | null
interval
integer | null
byDay
Array<string> | null
byMonthDay
Array<integer> | null
byMonth
Array<integer> | null
bySetPos
Array<integer> | null
userParticipationStatus
One of:

How an attendee answered. NEEDS-ACTION means they have not answered yet.

string
Allowed values: NEEDS-ACTION ACCEPTED DECLINED TENTATIVE
originalTimezone

Time zone the event was created in, when it differs.

string | null
recurrenceBaseStart
string | null
recurrenceBaseEnd
string | null
attendees
required
Array<object>

Somebody invited to the event.

object
email
string | null
name
string | null
type
One of:

user is somebody with an Optiwork account in the tenant, group a user group, and guest an address outside it.

string
Allowed values: user guest group
avatarUrl
string | null
participationStatus
One of:

How an attendee answered. NEEDS-ACTION means they have not answered yet.

string
Allowed values: NEEDS-ACTION ACCEPTED DECLINED TENTATIVE
optiworkIdentifier
string | null
alarms
required
Array<object>

A reminder, expressed as an offset from the event. isNegative: true means the reminder fires before the moment named by related; the unit fields that do not apply are 0 or null.

object
description
string | null
related

Whether the offset is measured from the start or the end.

string | null
Allowed values: START END
isNegative
boolean
weeks
integer | null
days
integer | null
hours
integer | null
minutes
integer | null
seconds
integer | null
locale
string | null
participantsSummary

Who takes part in one occurrence, summarized for an event card. Present only on a list (GET /events) called with include_participants_summary=true; absent otherwise.

The participants are listed as the event details show them: the organizer first, when the occurrence has one, then the attendees in invitation order. The organizer is not looked up among the attendees, so an organizer who is also listed as an attendee counts twice. An exception occurrence is summarized from its own participants.

Even with the flag on, an occurrence can lack participantsSummary when its participants could not be read, for instance when the event was deleted while the list was being built. Read a missing participantsSummary as unknown, not as zero participants.

object
participantsCount
required

Number of participants of the occurrence: the organizer, when there is one, plus every attendee. 0 when it has none.

integer
participants
required

The first three participants, in the order above. Empty when the occurrence has none.

Array<object>
<= 3 items
object
name
required

The participant’s name or, when it has none, their email address. null when both are missing.

string | null
avatarUrl
required

The participant’s avatar, or null when there is none.

string | null
Example
{
  "event": {
    "id": "4167",
    "calendarId": "10",
    "instances": [
      {
        "status": "CONF",
        "organizer": {
          "type": "user"
        },
        "recurrenceRule": {
          "frequency": "DAILY"
        },
        "userParticipationStatus": "NEEDS-ACTION",
        "attendees": [
          {
            "type": "user",
            "participationStatus": "NEEDS-ACTION"
          }
        ],
        "alarms": [
          {
            "related": "START"
          }
        ],
        "participantsSummary": {
          "participantsCount": 5,
          "participants": [
            {
              "name": "Jane Doe"
            }
          ]
        }
      }
    ]
  }
}

401

Section titled “401”

Missing, malformed or expired authentication key.

Media typeapplication/json

Authentication failures use an error key rather than message.

object
error
required
string
Examples
Examplemissing

No bearer token sent

{
  "error": "JWT passport exception: Missing bearer token in request"
}

422

Section titled “422”

The request body or query string failed validation.

Media typeapplication/json
object
message
required

The first validation message.

string
errors
required

Validation messages keyed by field name.

object
key
additional properties
Array<string>
Examples
Exampleinvalid
{
  "message": "The event title field is required.",
  "errors": {
    "title": [
      "The event title field is required."
    ]
  }
}

429

Section titled “429”

Rate limit exceeded. Retry after the window resets.

Media typeapplication/json

Generic error envelope used by policy, binding and framework failures.

object
message
required

Human-readable description of the failure.

string
Examples
Examplethrottled
{
  "message": "Too Many Attempts."
}