---
title: "Update a meeting"
method: PATCH
path: "/api/v1/meetings/{meetingId}"
tags: ["Meetings"]
---

# Update a meeting

`PATCH /api/v1/meetings/{meetingId}`

## Request

- Base URL: `https://api.recruitwithatlas.com`
- URL: `https://api.recruitwithatlas.com/api/v1/meetings/{meetingId}`
- Auth: HTTP bearer

Updates a general meeting’s details and notes, through the same service the Atlas app uses. Every field is optional, but at least one is required; omitted fields are left unchanged. `attendees` replaces the whole attendee list, `null` clears `location`, `description` or `peopleNotes`, and `projectId: null` unlinks the project. `status` only accepts `canceled`, which marks the meeting canceled in Atlas and withdraws the candidate invite but leaves the organizer’s calendar event and the AI notetaker in place.

When this edit moves `endAt` into the past, the meeting is marked `completed`. If the meeting has a calendar event, it is updated too; if that fails, nothing is saved and a `400` is returned.

Who can update it follows the agency’s “Who can edit a meeting note?” setting: by default the meeting’s creator or an agency admin, and the agency can extend this to the creator’s teammates or to everyone. Candidate interviews cannot be updated here. Returns the meeting in the same shape as `GET /api/v1/meetings/{meetingId}`.

## Path parameters

- `meetingId` string, uuid, required: ID of the meeting to retrieve

## Request body

- object
  - `name` string: Meeting title
  - `description` string, nullable: Meeting description, also used as the calendar event body. `null` clears it.
  - `startAt` string, date-time: Start time, ISO 8601 with `Z` or an explicit offset
  - `endAt` string, date-time: End time, ISO 8601 with `Z` or an explicit offset. Must not be before the start time. Moving it into the past marks the meeting `completed`.
  - `timeZone` string: IANA time zone the meeting is held in, used for the calendar event
  - `communicationMethod` 'video_call' | 'phone_call' | 'in_person': How the meeting is held
  - `location` string, nullable: Meeting location. `null` clears it.
  - `attendees` object[]: Replaces the people and users in the meeting (1-50).
    - `id` string, uuid: Atlas person ID (or user ID when `isUser` is true) of this attendee. Without it every person holding `email` is linked, Gmail aliases included. Must belong to your agency.
    - `email` string, email, required: Attendee email address
    - `isUser` boolean, required: `true` when the attendee is a user of your agency, `false` for a person (candidate or contact).
    - `optional` boolean: Invite the attendee as optional on the calendar event. Only used when `skipCalendarEvent` is false.
  - `projectId` string, uuid, nullable: Project the meeting relates to. Must belong to your agency. `null` unlinks it.
  - `isPrivate` boolean: Mark the meeting private
  - `hideAttendees` boolean: Hide the attendee list on the calendar event
  - `inviteAINotetaker` boolean: Invite or remove the AI notetaker. Only applies to a meeting with a calendar event.
  - `peopleNotes` string, nullable: Plain-text notes about the meeting (the manual note). `null` clears it.
  - `candidateEvent` object: A separate calendar invite for the candidate, with its own title and body. Enabling it needs a meeting with a calendar event, and `inviteeEmail` unless the meeting already has a candidate invite.
    - `enabled` boolean, required: Send the separate invite. Requires `skipCalendarEvent: false`.
    - `eventTitle` string, nullable: Title of the invite. Defaults to the meeting `name`.
    - `description` string, nullable: Body of the invite
    - `inviteeEmail` string, email: Address the invite is sent to. Required when `enabled` is true. A person in your agency with this email is linked to the meeting.
    - `inviteeName` string, nullable: Name of the invitee
  - `status` 'canceled': Only `canceled` is accepted, to cancel the meeting. This marks it canceled in Atlas and withdraws the separate candidate invite, if there is one, the same as cancelling it in the Atlas app. It does not cancel the organizer’s calendar event or remove the AI notetaker.

## Response `200`

Meeting updated

- object
  - `status` 'ok', required
  - `data` object, required
    - `id` string, uuid, required
    - `name` string, nullable, required
    - `description` string, nullable, required
    - `location` string, nullable, required
    - `meetingUrl` string, nullable, required
    - `method` 'video_call' | 'phone_call' | 'in_person' | 'null', nullable, required: Communication method. Null when the meeting has no linked interview record.
    - `status` 'draft' | 'created' | 'scheduled' | 'coming' | 'waiting_to_join' | 'live' | 'completed' | 'transcribed' | 'failed' | 'canceled' | 'no_answer' | 'scheduling', required: Meeting status (meeting.status)
    - `direction` 'inbound' | 'outbound' | 'null', nullable, required: Call direction (`inbound`/`outbound`). Only populated for VoIP-sourced phone calls (e.g. RingOver, RingCentral); null for video meetings and manually logged calls.
    - `startAt` string, nullable, required: UTC ISO 8601 start time
    - `endAt` string, nullable, required: UTC ISO 8601 end time
    - `createdAt` string, nullable, required
    - `updatedAt` string, nullable, required: Effective last-updated timestamp: the later of the meeting row and its linked interview record — the same value the list endpoint reports.
    - `organizer` object, nullable, required: Meeting organizer — resolved the same way as the list shape: an Atlas user when the organizer email matches one of the meeting users, otherwise an `external` attendee with `id` null. Null when no organizer was recorded. The organizer may or may not also appear in `participants` — do not assume dedup.
      - `id` string, uuid, nullable, required: Atlas user ID when `type=user`; null when `type=external` (organizer not present in Atlas).
      - `name` string, required
      - `email` string, nullable, required
      - `type` 'user' | 'external', required
      - `relationship` 'user' | 'external', required: Same as `type`: `user` for an Atlas user, `external` for an organizer not present in Atlas.
    - `participants` object[], required: Flat list of users and people invited to the meeting. Filter by `type` to separate them.
      - `id` string, uuid, required: Atlas user or person ID
      - `name` string, required
      - `email` string, nullable, required
      - `type` 'user' | 'person', required
      - `relationship` 'user' | 'candidate' | 'company_contact' | 'person', required: How the participant relates to the interview: `user` (an Atlas user), `candidate` (the interview candidate), `company_contact` (a person who is an active contact of a company), or `person` (any other person).
    - `project` object, nullable, required: Project linked to the meeting. Null when no project is associated.
      - `id` string, uuid, required
      - `role` string, required: Job role (project.jobRole)
      - `companyName` string, nullable, required: Name of the project's company, null when none is set
    - `company` object, nullable, required: Company linked to the meeting. Resolved from the linked project's company when present, otherwise from the direct company link. Null when neither is set.
      - `id` string, uuid, required
      - `name` string, required
    - `customAttributes` object[], required
      - `attributeId` string, uuid, required: Custom attribute definition ID
      - `attributeName` string, nullable, required: Attribute name
      - `attributeType` 'options' | 'text_block' | 'text_line' | 'number_input' | 'integer' | 'date' | 'null', nullable, required: Attribute type — drives the shape of each entry in `values`.
      - `values` union[], required: All values recorded for this attribute. For single-value attributes the array has one entry; for multi-select `options` attributes it may have several.
        - union: A single value entry. Shape depends on `attributeType`: - `text_line` / `text_block` → string - `integer` / `number_input` → number - `date` → ISO `YYYY-MM-DD` string - `options` → `{ optionId, optionValue }` object
          - string
          - number
          - object
            - `optionId` string, uuid, required: Selected option ID
            - `optionValue` string, nullable, required: Display value of the option

## Other responses

- `400`: The meeting’s calendar event could not be updated, so nothing was saved
- `401`: Unauthorized - missing or invalid API key
- `403`: The agency’s “Who can edit a meeting note?” setting does not let the user that owns the API key edit this meeting
- `404`: Meeting not found or belongs to a different agency, or `projectId` is not in your agency
- `415`: The request body is not sent as `application/json`
- `422`: The body failed validation, `endAt` is before the start time, an attendee `id` is not in your agency, `candidateEvent` cannot be sent for this meeting, the ID belongs to an interview, or the meeting has no editable details
- `429`: Too many requests - the caller has exceeded the per-agency rate limit for the tier this endpoint counts against (default per minute: 1200 read / 400 write / 60 upload). Inspect the `RateLimit-*` headers — returned on every response, not only on 429s — and back off until the window resets. See the "Rate limits" section of the introduction for details.

## Changes

- **2026-11-16** `7239e8f4db5c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/recruitwithatlas/apis/atlas-api/changes/api/v1/meetings/:meetingId/patch.md)

---

[API](https://skmtc.dev/recruitwithatlas/apis/atlas-api.md) - [All operations](https://skmtc.dev/recruitwithatlas/apis/atlas-api/llms.txt) - [OpenAPI document](https://skmtc.dev/recruitwithatlas/apis/atlas-api/revisions/dec3d55a17be?raw)
