# Book a meeting

Puts a meeting on the caller's own calendar (Google or Microsoft, whichever they connected) and links it to a record. Takes title, startsAt, an optional endsAt (the member's default duration when absent), attendees, meetLink for a video link, and definitionKey + rowId to pin it to a record. attendeesFromRecord adds the record's own addresses and the contacts filed against it; attendeesFromAssignees adds the people its person columns name (opener, closer, owner) — so nobody retypes what the record already knows. To tie a task: taskId links an existing task of this record (refused if it already has a live meeting), or createTask {title, description, dueAt, assigneeAccountId, entityKind} raises one beside the meeting — blanks default to the meeting's title, its start as the due time, the caller as the assignee, and the record's own entity word; the answer carries taskId. Never send both. This is a write: it pauses for the person's approval, which is where they accept or decline the invite before it goes out.

Access class: `workspace`.

## Endpoint

`POST /v1/calendar/events`

## Request body

Content type: `application/json`.

```json
{
  "body": {
    "attendees": [
      "string"
    ],
    "attendeesFromAssignees": true,
    "attendeesFromRecord": true,
    "createTask": {
      "assigneeAccountId": "",
      "description": "string",
      "dueAt": "string",
      "entityKind": "string",
      "title": "string"
    },
    "definitionKey": "string",
    "description": "string",
    "endsAt": "string",
    "meetLink": true,
    "rowId": "",
    "startsAt": "string",
    "taskId": 1,
    "title": "string"
  },
  "params": {},
  "query": {}
}
```

## Responses

### 201

the action's answer

Content type: `application/json`.

```json
{
  "data": {
    "attendees": [
      "string"
    ],
    "calendarId": "",
    "cancelledAt": "string",
    "createdAt": "string",
    "definitionId": "",
    "definitionKey": "string",
    "endsAt": "string",
    "id": "",
    "meetingUrl": "string",
    "memberUserId": 1,
    "provider": "string",
    "providerEventId": "",
    "rowId": "",
    "startsAt": "string",
    "status": "string",
    "taskId": 1,
    "title": "string",
    "updatedAt": "string"
  }
}
```

### default

a refusal: `{"error": "<what a person needs to read>"}`. 401 no credential, 402 the plan does not include this, 403 the seat does not, 404 the thing does not exist or is not yours to see.

Content type: `application/json`.

```json
{
  "error": "string"
}
```