---
title: "Find or create a meeting"
method: POST
path: "/v2/meetings"
tags: ["Meetings"]
---

# Find or create a meeting

`POST /v2/meetings`

Finds an existing meeting or creates a new one if it doesn't yet exist. [Please see here](/rest-api/guides/syncing-meetings) for a full guide on syncing meetings to Attio.

This endpoint is in alpha and may be subject to breaking changes as we gather feedback.

Required scopes: `meeting:read-write`, `record_permission:read`.

## Request body

- object
  - `data` object, required
    - `title` string, required — The title of the meeting.
    - `description` string, required — The description of the meeting.
    - `start` union, required — When the meeting starts. Use a datetime and optional timezone for non-all day meetings, or a date for all day meetings.
      - object
        - `datetime` string, date-time, required — An ISO 8601 datetime indicating when a non-all day meeting starts.
        - `timezone` string, nullable — The IANA timezone the meeting starts in. If a datetime value is provided without an offset, this timezone will be used to convert the datetime to UTC using the timezone offset. If a datetime value is provided with an offset, this timezone will not be used to apply any additional offset to the datetime. Invalid timezones will be treated as UTC.
      - object
        - `date` string, required — An ISO 8601 date indicating when an all day meeting starts.
    - `end` union, required — When the meeting ends. Use a datetime and optional timezone for non-all day meetings, or a date for all day meetings.
      - object
        - `datetime` string, date-time, required — An ISO 8601 datetime indicating when a non-all day meeting ends. Note that this value is exclusive, meaning that the meeting ends before the specified time, not at it. For example, a one hour meeting starting at 14:00 would end at 15:00, not 15:59:59.
        - `timezone` string, nullable — The IANA timezone the meeting ends in. If a datetime value is provided without an offset, this timezone will be used to convert the datetime to UTC using the timezone offset. If a datetime value is provided with an offset, this timezone will not be used to apply any additional offset to the datetime. Invalid timezones will be treated as UTC.
      - object
        - `date` string, required — An ISO 8601 date indicating when an all day meeting ends. Note that dates are exclusive, meaning that the meeting ends before the specified time, not at it. For example, a one day meeting on June 3rd would end on June 4th, not June 3rd.
    - `is_all_day` boolean, required — Whether or not the meeting is an all day event. All day events may span multiple days. When true, start and end must use date format. When false, start and end must use datetime with timezone format.
    - `participants` object[], required
      - `email_address` string — The email address of the participant. New person records and companies will automatically be created based upon the email address values provided. If omitted, a name must be provided instead.
      - `is_organizer` union, required — Whether or not the participant is the organizer of the meeting.
        - boolean
        - 'true'
        - 'false'
      - `status` 'accepted' | 'tentative' | 'declined' | 'pending', required — The status of the individual meeting participant.
      - `name` string — The name of the participant. Required when no email_address is provided. Participants without an email do not create person or company records.
    - `linked_records` object[] — A list of records to link to the meeting. Each record is specified by its object (slug or UUID) and record ID (UUID). Attio will automatically link the meeting participants' companies to the meeting; this behavior is asynchronous.
      - `object` string, required — The slug or UUID of the object that the record being linked belongs to.
      - `record_id` string, uuid, required — The UUID of the record being linked.
    - `external_ref` union, required — A consistent external reference used to match and de-duplicate meetings. Can be either a plain string (for external system IDs) or an object with `ical_uid` and `provider`. If you are writing data into Attio which is based upon calendar events that you have synced from a Google or Microsoft calendar, you must use the iCal format to avoid creating duplicate meetings inside Attio.
      - string — A text ID that can be used to consistently reference and de-duplicate meetings. For example, this might be the primary key of a meeting in your system, or taken from an API response from a service you are connecting to Attio. You should ensure that this ID is unique across recurring meetings and does not change over time. If you do not have an ID immediately to hand, you may generate a UUID to use as the external reference.
      - object
        - `ical_uid` string, required — The ical uid of the meeting.
        - `provider` 'google' | 'microsoft', required — The email provider used to sync the meeting.
        - `original_start_time` string — The original start time of the meeting. Use a timestamp with a specified offset for all day and non-all day meetings. This property is required for recurring event exceptions and optional otherwise.
        - `is_recurring` boolean, required — Whether or not the meeting is recurring.

## Response `200`

Success

- object — Success
  - `data` Meeting, required
    - `id` object, required
      - `workspace_id` string, uuid, required — The ID of the workspace the meeting belongs to.
      - `meeting_id` string, uuid, required — The ID of the Attio meeting.
    - `title` string, required — The title of the meeting.
    - `description` string, required — The description of the meeting.
    - `is_all_day` boolean, required — Whether or not the meeting is an all day event. All day events may span multiple days.
    - `start` union, required
      - object
        - `datetime` string, required — If a non-all day event, a datetime representing when the meeting starts. Datetimes are formatted as UTC if no timezone is available. If a timezone is available, the datetime will offset using the specified timezone.
        - `timezone` string, nullable, required — The IANA timezone in which the meeting starts, if available.
      - object
        - `date` string, required — If an all day event, a date representing when the meeting starts.
    - `end` union, required
      - object
        - `datetime` string, required — A datetime representing when the meeting ends. All day meetings will return a date whereas non-all day meetings will return a datetime. Datetimes do not include timezone information; please refer to `timezone` for timezone information. Following iCalendar RFC 5545, the `end_at` property is exclusive, meaning that the meeting ends before the specified time, not at it. For example, a one day meeting on June 3rd would have an `end_at` of June 4th, not June 3rd; a one hour meeting starting at 14:00 would have an `end_at` of 15:00, not 14:00.
        - `timezone` string, nullable, required — The IANA timezone in which the meeting ends, if available.
      - object
        - `date` string, required — If an all day event, a date representing when the meeting ends.
    - `participants` object[], required
      - `status` 'accepted' | 'tentative' | 'declined' | 'pending', required — The status of the individual meeting participant.
      - `is_organizer` boolean, required — Whether or not the participant is the organizer of the meeting.
      - `email_address` string, nullable, required — The normalized email address of the meeting participant.
      - `name` string, nullable, required — The participant's name. This is only set when the name was explicitly provided when the participant was created. It is null for any participant identified by an email address — including workspace members and person records — whose display names are not resolved into this field.
    - `linked_records` object[], required — A list of records that are linked to the meeting. Participants with matching person records are automatically linked to the meeting but other records may also be linked explicitly.
      - `object_slug` string, required — The slug of the object the meeting linked record belongs to.
      - `object_id` string, uuid, required — The ID of the object the meeting linked record belongs to.
      - `record_id` string, uuid, required — The ID of the meeting linked record.
    - `created_at` string, required — Timestamp representing when the meeting was created.
    - `created_by_actor` object, required — The actor that created this meeting.
      - `id` string, nullable — An ID to identify the actor.
      - `type` 'api-token' | 'workspace-member' | 'system' | 'app', nullable — The type of actor. [Read more information on actor types here](/docs/actors).

## Other responses

- `400` — Bad Request

## Changes

- **2026-07-26** `0eb6da8a7a07` — 3 info
  - added the new optional request property `data/participants/items/name`
  - the request property `data/participants/items/email_address` became optional
  - added the required property `data/participants/items/name` to the response with the `200` status

[Change history](https://skmtc.dev/attio/apis/attio-api/changes/v2/meetings/post.md)

---

[API](https://skmtc.dev/attio/apis/attio-api.md) · [All operations](https://skmtc.dev/attio/apis/attio-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/attio/attio-api/revisions/0eb6da8a7a07/schema)