Meetings and roles

Two things automations most often do for people: put a meeting on the calendar, and give someone a role. Both go through the same code as the Missived app, so the same rules apply: invites are emailed by Missived, outside guests are allowed only where the org allows them, and only owners and admins hand out roles.

Schedule a meeting

A meeting is organised by a person, so this needs a personal token (or a person's OAuth connection) with meetings:write. An app token gets 403: bots have no calendar.

curl -X POST https://api.missived.com/v1/orgs/$ORG_ID/meetings \
  -H "Authorization: Bearer $MISSIVED_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: weekly-sync-2026-10-20" \
  -d '{
    "title": "Weekly sync",
    "agenda": "Roadmap, then open questions",
    "start_time": "2026-10-20T15:00:00Z",
    "duration_minutes": 30,
    "time_zone": "America/New_York",
    "invitees": [
      { "user_id": "u_123" },
      { "email": "[email protected]", "name": "Vic", "role": "participant" }
    ]
  }'

The answer (201) is the meeting, with its id and join_url. Everyone invited gets an email with a calendar file, unless you send "send_invites": false.

• start_time is ISO 8601 with a time zone. It can't be more than five minutes in the past or more than two years ahead. duration_minutes is 5–1440.
• time_zone is an IANA zone such as Europe/London. It's how the invite shows the time.
• An invitee is a member (user_id, from GET /v1/orgs/{orgId}/members) or anyone by email. A member's email address becomes that member. Anyone else is an outside guest. If the org doesn't let you invite outsiders, the answer is 403 with external_not_allowed.
• role is participant (the default) or co_host. Only full members can be co-hosts.
• Send an Idempotency-Key so a retry doesn't make a second meeting. See Conventions.

Errors keep the meeting's own codes: invalid_time (start, length or zone), invalid_settings, too_many_invitees (200, of whom at most 100 from outside) and invalid_request. The message names the field.

Change, re-invite or cancel

Only the meeting's organiser can do these. Anyone else who can see the meeting gets 403. Anyone who can't see it gets 404.

Each one emails the people concerned unless you send "notify": false. A cancelled meeting answers 410 with meeting_cancelled to any further change.

These changes fire the meeting.scheduled, meeting.updated and meeting.cancelled events. A change made with "notify": false fires no event.

Give or take a custom role

# Give
curl -X PUT https://api.missived.com/v1/orgs/$ORG_ID/members/$USER_ID/roles/$ROLE_ID \
  -H "Authorization: Bearer $MISSIVED_TOKEN"

# Take away
curl -X DELETE https://api.missived.com/v1/orgs/$ORG_ID/members/$USER_ID/roles/$ROLE_ID \
  -H "Authorization: Bearer $MISSIVED_TOKEN"

Role ids come from GET /v1/orgs/{orgId}/roles. Both calls answer with the member and their custom roles. Giving a role they already have, or taking one they don't have, changes nothing and still answers 200.

• Custom roles only. Nothing here changes a member's Owner, Admin, Member or Guest role.
• Who may: the token needs roles:write, and its person must be an Owner or Admin of the org. This is the same rule as Org Settings → Members.
• Apps: only an Owner or Admin can grant an app roles:write. The app keeps the power only while the person who set it up is still an Owner or Admin. An app never gives or takes a role that has Manage integrations.
• Bots aren't members, so they can't be given roles (404).
• A linked-role rule (a role tied to a Twitch, Patreon or other connection) may give a role back on its next check if the person still qualifies.

Each change fires member.role_assigned or member.role_removed. The payload has member, role { id, name }, source (manual, or linked for a rule) and actor. The bot gateway sends these events under the members intent.