OpenAssistantAPI
→

User API

Preferences

Scheduling, reminders, and supervision preferences

GET/identifiers/{identifierId}/preferences

Get all preferences for an identifier

Path parameters

identifierId reqstring

Responses

200Preferences
ok reqenumtrue
preferences reqobject
id reqstring
account reqstring
userIdentifier reqstring
preferences reqobject
schedulingobject
syncboolean
availabilityobject
syncboolean
workingHoursobject
MOobject[]
startstring
endstring
TUobject[]
startstring
endstring
WEobject[]
startstring
endstring
THobject[]
startstring
endstring
FRobject[]
startstring
endstring
SAobject[]
startstring
endstring
SUobject[]
startstring
endstring
workingHolidaysstring[]
customHolidaysstring[]
holidayCountriesstring[]
holidayCountrystring
defaultsobject
syncboolean
virtualobject
durationnumber
defaultMeetingLinkstring
conferenceSolutionstring
conferenceIntegrationstring
inPersonobject
durationnumber
defaultLocationstring
calendarsobject
syncboolean
readstring[]
writestring
buffersobject
syncboolean
bufferTypeenumnonemeetingtimeBlock
bufferLengthnumber
bufferBlockLengthnumber
dailyMeetingLimitnumber
customEventTitlesobject
internalobject
useCustomTitlesboolean
solostring
oneAttendeestring
twoAttendeesstring
manyAttendeesstring
externalobject
useCustomTitlesboolean
oneAttendeestring
twoAttendeesstring
manyAttendeesstring
remindersobject
levelenumall-eventsagnt-eventsnone
smartRemindersboolean
recipientobject
asOrganizerenumonly-mewith-attendeesnone
asAttendeeenumonly-menone
calendarsobject
readstring[]
emailobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
slackobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
teamsobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
desktopobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
checkInAfternumber
followupsobject
enabledboolean
countnumber
intervalnumber
travelobject
seatPreferencestring
cabinClassstring
mealPreferencestring
airlinePreferencesstring[]
supervisionobject
modestring
threadInclusionenumsupervisedsemi-supervisedunsupervised
visibilitystring
notifyOnenumalwayson_flagnever
reviewTimeoutnumber
scopestring
matrixobject
matrixUpdatedAtstring | null
createdAt reqstring
updatedAt reqstring
404Not found
status reqinteger
error_codestring
error reqstring

Request

curl 'https://app.openassistant.us/api/identifiers/<identifierId>/preferences' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "preferences": {
    "id": "string",
    "account": "string",
    "userIdentifier": "string",
    "preferences": {
      "scheduling": {
        "sync": true,
        "availability": {
          "sync": null,
          "workingHours": null,
          "workingHolidays": null,
          "customHolidays": null
        },
        "defaults": {
          "sync": null,
          "virtual": null,
          "inPerson": null
        },
        "calendars": {
          "sync": null,
          "read": null,
          "write": null
        }
      },
      "reminders": {},
      "followups": {},
      "travel": {}
    },
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  }
}
GET/identifiers/{identifierId}/preferences/{skillName}

Get preferences for a specific skill

Path parameters

identifierId reqstring
skillName reqstring

Responses

200Skill preferences
ok reqenumtrue
skillPreferences reqobject
skill reqstring
preferences reqobject

Request

curl 'https://app.openassistant.us/api/identifiers/<identifierId>/preferences/<skillName>' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "skillPreferences": {
    "skill": "string",
    "preferences": {}
  }
}
PUT/identifiers/{identifierId}/preferences/{skillName}

Set preferences for a specific skill

Path parameters

identifierId reqstring
skillName reqstring

Request body

preferences reqobject

Responses

200Updated skill preferences
ok reqenumtrue
skillPreferences reqobject
skill reqstring
preferences reqobject

Request

curl 'https://app.openassistant.us/api/identifiers/<identifierId>/preferences/<skillName>' \
  -X PUT \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "preferences": {}
}'

Response

{
  "ok": true,
  "skillPreferences": {
    "skill": "string",
    "preferences": {}
  }
}
GET/users/{userId}/preferences/scheduling

Get scheduling preferences for user's primary identifier

Path parameters

userId reqstring

Responses

200Scheduling preferences
ok reqenumtrue
schedulingPreferences reqobject
syncboolean
availabilityobject
syncboolean
workingHoursobject
MOobject[]
startstring
endstring
TUobject[]
startstring
endstring
WEobject[]
startstring
endstring
THobject[]
startstring
endstring
FRobject[]
startstring
endstring
SAobject[]
startstring
endstring
SUobject[]
startstring
endstring
workingHolidaysstring[]
customHolidaysstring[]
holidayCountriesstring[]
holidayCountrystring
defaultsobject
syncboolean
virtualobject
durationnumber
defaultMeetingLinkstring
conferenceSolutionstring
conferenceIntegrationstring
inPersonobject
durationnumber
defaultLocationstring
calendarsobject
syncboolean
readstring[]
writestring
buffersobject
syncboolean
bufferTypeenumnonemeetingtimeBlock
bufferLengthnumber
bufferBlockLengthnumber
dailyMeetingLimitnumber
customEventTitlesobject
internalobject
useCustomTitlesboolean
solostring
oneAttendeestring
twoAttendeesstring
manyAttendeesstring
externalobject
useCustomTitlesboolean
oneAttendeestring
twoAttendeesstring
manyAttendeesstring

Request

curl 'https://app.openassistant.us/api/users/<userId>/preferences/scheduling' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "schedulingPreferences": {
    "sync": true,
    "availability": {
      "sync": true,
      "workingHours": {
        "MO": [
          null
        ],
        "TU": [
          null
        ],
        "WE": [
          null
        ],
        "TH": [
          null
        ]
      },
      "workingHolidays": [
        "2025-01-15T10:30:00Z"
      ],
      "customHolidays": [
        "2025-01-15T10:30:00Z"
      ]
    },
    "defaults": {
      "sync": true,
      "virtual": {
        "duration": 0,
        "defaultMeetingLink": "string",
        "conferenceSolution": "string",
        "conferenceIntegration": "string"
      },
      "inPerson": {
        "duration": 0,
        "defaultLocation": "string"
      }
    },
    "calendars": {
      "sync": true,
      "read": [
        "string"
      ],
      "write": "string"
    }
  }
}
PUT/users/{userId}/preferences/scheduling

Update scheduling preferences for user's primary identifier

Path parameters

userId reqstring

Request body

schedulingPreferences reqobject
syncboolean
availabilityobject
syncboolean
workingHoursobject
MOobject[]
startstring
endstring
TUobject[]
startstring
endstring
WEobject[]
startstring
endstring
THobject[]
startstring
endstring
FRobject[]
startstring
endstring
SAobject[]
startstring
endstring
SUobject[]
startstring
endstring
workingHolidaysstring[]
customHolidaysstring[]
holidayCountriesstring[]
holidayCountrystring
defaultsobject
syncboolean
virtualobject
durationnumber
defaultMeetingLinkstring
conferenceSolutionstring
conferenceIntegrationstring
inPersonobject
durationnumber
defaultLocationstring
calendarsobject
syncboolean
readstring[]
writestring
buffersobject
syncboolean
bufferTypeenumnonemeetingtimeBlock
bufferLengthnumber
bufferBlockLengthnumber
dailyMeetingLimitnumber
customEventTitlesobject
internalobject
useCustomTitlesboolean
solostring
oneAttendeestring
twoAttendeesstring
manyAttendeesstring
externalobject
useCustomTitlesboolean
oneAttendeestring
twoAttendeesstring
manyAttendeesstring

Responses

200Updated scheduling preferences
ok reqenumtrue
schedulingPreferences reqobject
syncboolean
availabilityobject
syncboolean
workingHoursobject
MOobject[]
startstring
endstring
TUobject[]
startstring
endstring
WEobject[]
startstring
endstring
THobject[]
startstring
endstring
FRobject[]
startstring
endstring
SAobject[]
startstring
endstring
SUobject[]
startstring
endstring
workingHolidaysstring[]
customHolidaysstring[]
holidayCountriesstring[]
holidayCountrystring
defaultsobject
syncboolean
virtualobject
durationnumber
defaultMeetingLinkstring
conferenceSolutionstring
conferenceIntegrationstring
inPersonobject
durationnumber
defaultLocationstring
calendarsobject
syncboolean
readstring[]
writestring
buffersobject
syncboolean
bufferTypeenumnonemeetingtimeBlock
bufferLengthnumber
bufferBlockLengthnumber
dailyMeetingLimitnumber
customEventTitlesobject
internalobject
useCustomTitlesboolean
solostring
oneAttendeestring
twoAttendeesstring
manyAttendeesstring
externalobject
useCustomTitlesboolean
oneAttendeestring
twoAttendeesstring
manyAttendeesstring

Request

curl 'https://app.openassistant.us/api/users/<userId>/preferences/scheduling' \
  -X PUT \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "schedulingPreferences": {
    "sync": true,
    "availability": {
      "sync": true,
      "workingHours": {
        "MO": [
          null
        ],
        "TU": [
          null
        ],
        "WE": [
          null
        ],
        "TH": [
          null
        ]
      },
      "workingHolidays": [
        "2025-01-15T10:30:00Z"
      ],
      "customHolidays": [
        "2025-01-15T10:30:00Z"
      ]
    },
    "defaults": {
      "sync": true,
      "virtual": {
        "duration": 0,
        "defaultMeetingLink": "string",
        "conferenceSolution": "string",
        "conferenceIntegration": "string"
      },
      "inPerson": {
        "duration": 0,
        "defaultLocation": "string"
      }
    },
    "calendars": {
      "sync": true,
      "read": [
        "string"
      ],
      "write": "string"
    }
  }
}'

Response

{
  "ok": true,
  "schedulingPreferences": {
    "sync": true,
    "availability": {
      "sync": true,
      "workingHours": {
        "MO": [
          null
        ],
        "TU": [
          null
        ],
        "WE": [
          null
        ],
        "TH": [
          null
        ]
      },
      "workingHolidays": [
        "2025-01-15T10:30:00Z"
      ],
      "customHolidays": [
        "2025-01-15T10:30:00Z"
      ]
    },
    "defaults": {
      "sync": true,
      "virtual": {
        "duration": 0,
        "defaultMeetingLink": "string",
        "conferenceSolution": "string",
        "conferenceIntegration": "string"
      },
      "inPerson": {
        "duration": 0,
        "defaultLocation": "string"
      }
    },
    "calendars": {
      "sync": true,
      "read": [
        "string"
      ],
      "write": "string"
    }
  }
}
GET/users/{userId}/preferences/reminders

Get reminder preferences for the user (cross-identifier)

Path parameters

userId reqstring

Responses

200Reminder preferences
ok reqenumtrue
reminderPreferences reqobject
levelenumall-eventsagnt-eventsnone
smartRemindersboolean
recipientobject
asOrganizerenumonly-mewith-attendeesnone
asAttendeeenumonly-menone
calendarsobject
readstring[]
emailobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
slackobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
teamsobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
desktopobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
checkInAfternumber

Request

curl 'https://app.openassistant.us/api/users/<userId>/preferences/reminders' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "reminderPreferences": {}
}
PATCH/users/{userId}/preferences/reminders

Update reminder preferences for the user (cross-identifier)

Path parameters

userId reqstring

Request body

preferences reqobject
levelenumall-eventsagnt-eventsnone
smartRemindersboolean
recipientobject
asOrganizerenumonly-mewith-attendeesnone
asAttendeeenumonly-menone
calendarsobject
readstring[]
emailobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
slackobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
teamsobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
desktopobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
checkInAfternumber

Responses

200Updated reminder preferences
ok reqenumtrue
reminderPreferences reqobject
levelenumall-eventsagnt-eventsnone
smartRemindersboolean
recipientobject
asOrganizerenumonly-mewith-attendeesnone
asAttendeeenumonly-menone
calendarsobject
readstring[]
emailobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
slackobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
teamsobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
desktopobject
enabledboolean
virtualDurationnumber
inPersonDurationnumber
checkInAfternumber

Request

curl 'https://app.openassistant.us/api/users/<userId>/preferences/reminders' \
  -X PATCH \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "preferences": {
    "level": "all-events",
    "smartReminders": true,
    "recipient": {
      "asOrganizer": "only-me",
      "asAttendee": "only-me"
    },
    "calendars": {
      "read": [
        "string"
      ]
    }
  }
}'

Response

{
  "ok": true,
  "reminderPreferences": {}
}
GET/users/{userId}/preferences/supervision/matrix

Get supervision matrix for user's primary identifier

Path parameters

userId reqstring

Responses

200Supervision matrix
ok reqenumtrue
supervisionMatrix reqobject
matrix reqobject
email_as_userany...
email_as_assistantany...
messagingany...
voice_callany...
calendarany...
filesany...
driveany...
contactsany...
third_party_skillsany...
websiteany...
lockedstring[]
exceptionsany[]
matrixUpdatedAtstring | null
parentLockedCellsstring[]

Request

curl 'https://app.openassistant.us/api/users/<userId>/preferences/supervision/matrix' \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "supervisionMatrix": {
    "matrix": {
      "email_as_user": null,
      "email_as_assistant": null,
      "messaging": null,
      "voice_call": null
    }
  }
}
PATCH/users/{userId}/preferences/supervision/matrix

Deep-merge an update into the supervision matrix

Path parameters

userId reqstring

Request body

matrix reqobject
email_as_userobject
modeenumautotime-boxedmanualnull
timeBoxedWindowMinnumber | null
timeBoxedExpiryenumexecutecancelnull
undoDelaySecnumber | null
email_as_assistantobject
modeenumautotime-boxedmanualnull
timeBoxedWindowMinnumber | null
timeBoxedExpiryenumexecutecancelnull
undoDelaySecnumber | null
messagingobject
modeenumautotime-boxedmanualnull
timeBoxedWindowMinnumber | null
timeBoxedExpiryenumexecutecancelnull
undoDelaySecnumber | null
voice_callobject
modeenumautotime-boxedmanualnull
timeBoxedWindowMinnumber | null
timeBoxedExpiryenumexecutecancelnull
undoDelaySecnumber | null
calendarobject
modeenumautotime-boxedmanualnull
timeBoxedWindowMinnumber | null
timeBoxedExpiryenumexecutecancelnull
undoDelaySecnumber | null
filesobject
modeenumautotime-boxedmanualnull
timeBoxedWindowMinnumber | null
timeBoxedExpiryenumexecutecancelnull
undoDelaySecnumber | null
driveobject
modeenumautotime-boxedmanualnull
timeBoxedWindowMinnumber | null
timeBoxedExpiryenumexecutecancelnull
undoDelaySecnumber | null
contactsobject
modeenumautotime-boxedmanualnull
timeBoxedWindowMinnumber | null
timeBoxedExpiryenumexecutecancelnull
undoDelaySecnumber | null
third_party_skillsobject
modeenumautotime-boxedmanualnull
timeBoxedWindowMinnumber | null
timeBoxedExpiryenumexecutecancelnull
undoDelaySecnumber | null
websiteobject
modeenumautotime-boxedmanualnull
timeBoxedWindowMinnumber | null
timeBoxedExpiryenumexecutecancelnull
undoDelaySecnumber | null
lockedstring[]
exceptionsobject[]
idstring
labelstring | null
match reqany...
mode reqenumautotime-boxedmanualdenied
timeBoxedWindowMininteger | null
timeBoxedExpiryenumexecutecancelnull
undoDelaySecinteger | null
appliesTostring[]
createdAtstring
createdBystring | null

Responses

200Updated supervision matrix
ok reqenumtrue
supervisionMatrix reqobject
matrix reqobject
email_as_userany...
email_as_assistantany...
messagingany...
voice_callany...
calendarany...
filesany...
driveany...
contactsany...
third_party_skillsany...
websiteany...
lockedstring[]
exceptionsany[]
matrixUpdatedAtstring | null
parentLockedCellsstring[]
400Invalid body (e.g. matrix.locked at user scope)
status reqinteger
error_codestring
error reqstring
403Loosening a parent-locked cell
status reqinteger
error_codestring
error reqstring

Request

curl 'https://app.openassistant.us/api/users/<userId>/preferences/supervision/matrix' \
  -X PATCH \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "matrix": {
    "email_as_user": {
      "mode": "auto",
      "timeBoxedWindowMin": 0,
      "timeBoxedExpiry": "execute",
      "undoDelaySec": 0
    },
    "email_as_assistant": {
      "mode": "auto",
      "timeBoxedWindowMin": 0,
      "timeBoxedExpiry": "execute",
      "undoDelaySec": 0
    },
    "messaging": {
      "mode": "auto",
      "timeBoxedWindowMin": 0,
      "timeBoxedExpiry": "execute",
      "undoDelaySec": 0
    },
    "voice_call": {
      "mode": "auto",
      "timeBoxedWindowMin": 0,
      "timeBoxedExpiry": "execute",
      "undoDelaySec": 0
    }
  }
}'

Response

{
  "ok": true,
  "supervisionMatrix": {
    "matrix": {
      "email_as_user": null,
      "email_as_assistant": null,
      "messaging": null,
      "voice_call": null
    }
  }
}
PUT/users/{userId}/preferences/supervision/matrix/reset

Reset supervision matrix to null (restore defaults)

Path parameters

userId reqstring

Responses

200Reset supervision matrix
ok reqenumtrue
supervisionMatrix reqobject
matrix reqobject
email_as_userany...
email_as_assistantany...
messagingany...
voice_callany...
calendarany...
filesany...
driveany...
contactsany...
third_party_skillsany...
websiteany...
lockedstring[]
exceptionsany[]
matrixUpdatedAtstring | null
parentLockedCellsstring[]

Request

curl 'https://app.openassistant.us/api/users/<userId>/preferences/supervision/matrix/reset' \
  -X PUT \
  -H "Authorization: Bearer ak_live_..."

Response

{
  "ok": true,
  "supervisionMatrix": {
    "matrix": {
      "email_as_user": null,
      "email_as_assistant": null,
      "messaging": null,
      "voice_call": null
    }
  }
}
POST/users/{userId}/preferences/supervision/exceptions

Append a recipient exception to the supervision matrix

Path parameters

userId reqstring

Request body

labelstring | null
match reqobject
kind reqenumtagprioritycompanycontactIdemaildomaininternal
value reqstring
mode reqenumautotime-boxedmanualdenied
timeBoxedWindowMininteger | null
timeBoxedExpiryenumexecutecancelnull
undoDelaySecinteger | null
appliesTostring[]

Responses

201Created exception
ok reqenumtrue
recipientException reqobject
idstring
labelstring | null
match reqobject
kind reqenumtagprioritycompanycontactIdemaildomaininternal
value reqstring
mode reqenumautotime-boxedmanualdenied
timeBoxedWindowMininteger | null
timeBoxedExpiryenumexecutecancelnull
undoDelaySecinteger | null
appliesTostring[]
createdAtstring
createdBystring | null
400Invalid match selector or value
status reqinteger
error_codestring
error reqstring
403Loosening a parent-locked resource
status reqinteger
error_codestring
error reqstring

Request

curl 'https://app.openassistant.us/api/users/<userId>/preferences/supervision/exceptions' \
  -X POST \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
  "match": {
    "kind": "tag",
    "value": "string"
  },
  "mode": "auto"
}'

Response

{
  "ok": true,
  "recipientException": {
    "match": {
      "kind": "tag",
      "value": "string"
    },
    "mode": "auto"
  }
}
DELETE/users/{userId}/preferences/supervision/exceptions/{exceptionId}

Remove a recipient exception by id

Path parameters

userId reqstring
exceptionId reqstring

Responses

204Deleted
404Exception not found
status reqinteger
error_codestring
error reqstring

Request

curl 'https://app.openassistant.us/api/users/<userId>/preferences/supervision/exceptions/<exceptionId>' \
  -X DELETE \
  -H "Authorization: Bearer ak_live_..."