Meeting Requests

Meeting requests represent scheduling requests that SkipUp coordinates on your behalf. You create a request with an organizer and participants, and SkipUp handles the back-and-forth of finding a time and booking the meeting.

The meeting request object

Field	Type	Description
id	string	Unique identifier for the meeting request.
organizer_email	string	Email address of the meeting organizer.
participant_emails	string[]	Email addresses of all participants.
status	string	Current status: active, paused, booked, or cancelled.
title	string | null	Title of the meeting.
purpose	string | null	Description of the meeting’s purpose.
description	string | null	Free-text instructions for the AI (e.g. CRM notes, tone guidance).
include_introduction	boolean | null	Whether the AI will compose an introduction for the outreach.
duration_minutes	integer | null	Requested meeting duration in minutes.
timeframe	object | null	Preferred scheduling window. Contains start and end ISO 8601 timestamps.
created_at	string	ISO 8601 timestamp of when the request was created.
updated_at	string	ISO 8601 timestamp of the last update.
booked_at	string | null	ISO 8601 timestamp of when the meeting was booked. Present only for booked requests.
cancelled_at	string | null	ISO 8601 timestamp of when the request was cancelled. Present only for cancelled requests.
paused_at	string | null	ISO 8601 timestamp of when the request was paused. Present only for paused requests. Cleared to null when the request is resumed.

Statuses

Status	Description
active	SkipUp is actively coordinating schedules with participants.
paused	Scheduling is temporarily paused. Messages are recorded but not acted on.
booked	A meeting time has been confirmed and calendar invites sent.
cancelled	The request was cancelled before a meeting was booked.

List meeting requests

GET /api/v1/meeting_requests

Returns a paginated list of meeting requests in your workspace, sorted by creation date (newest first).

Scope required: meeting_requests.read

Query parameters

Parameter	Type	Description
participant_email	string	Filter by participant email address.
organizer_email	string	Filter by organizer email address.
status	string	Filter by status: active, paused, booked, or cancelled.
created_after	string	ISO 8601 timestamp. Only return requests created on or after this time.
created_before	string	ISO 8601 timestamp. Only return requests created on or before this time.
limit	integer	Number of results per page. Default 25, max 100.
cursor	string	Cursor for fetching the next page. Use next_cursor from a previous response.

Request

curl "https://api.skipup.ai/api/v1/meeting_requests?status=active&limit=10" \
  -H "Authorization: Bearer $SKIPUP_API_KEY"

Response

{
  "data": [
    {
      "id": "mr_01HQ...",
      "organizer_email": "[email protected]",
      "participant_emails": ["[email protected]", "[email protected]"],
      "status": "active",
      "title": "Project kickoff",
      "purpose": "Discuss Q2 roadmap",
      "duration_minutes": 30,
      "timeframe": {
        "start": "2025-02-01T00:00:00Z",
        "end": "2025-02-14T23:59:59Z"
      },
      "created_at": "2025-01-20T14:30:00Z",
      "updated_at": "2025-01-20T14:30:00Z"
    }
  ],
  "meta": {
    "limit": 10,
    "has_more": true,
    "next_cursor": "mr_01HP..."
  }
}

Tip

To paginate through all results, keep passing the next_cursor value from each response as the cursor parameter until has_more is false.

Get a meeting request

GET /api/v1/meeting_requests/:id

Retrieves a single meeting request by ID.

Scope required: meeting_requests.read

Request

curl https://api.skipup.ai/api/v1/meeting_requests/mr_01HQ... \
  -H "Authorization: Bearer $SKIPUP_API_KEY"

Response

{
  "data": {
    "id": "mr_01HQ...",
    "organizer_email": "[email protected]",
    "participant_emails": ["[email protected]"],
    "status": "booked",
    "title": "1:1 sync",
    "duration_minutes": 30,
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-16T09:00:00Z",
    "booked_at": "2025-01-16T09:00:00Z"
  }
}

Create a meeting request

POST /api/v1/meeting_requests

Creates a new meeting scheduling request. SkipUp processes the request asynchronously — the response returns immediately with status 202 Accepted while scheduling begins in the background.

Scope required: meeting_requests.write

Request body

Parameter	Type	Required	Description
organizer_email	string	Yes	Email address of the meeting organizer.
participant_emails	string[]	Conditional	Email addresses of participants to schedule with. At least one required. Cannot be combined with participants.
participants	object[]	Conditional	Rich participant objects. At least one required. Cannot be combined with participant_emails.
participants[].email	string	Yes	Participant email address.
participants[].name	string	No	Participant full name. Backfills the name on the person record if not already set.
participants[].timezone	string	No	IANA timezone (e.g. America/Los_Angeles). Stored as a preference for automatic pickup by the AI.
organizer_name	string	No	Organizer’s full name. Backfills the name if not already set.
organizer_timezone	string	No	IANA timezone for the organizer (e.g. America/New_York). Stored as a preference for automatic pickup by the AI.
include_introduction	boolean	No	When true, the AI composes a warm introduction explaining who is requesting the meeting and why. Defaults to false.
context	object	No	Additional context for the meeting.
context.title	string	No	Title for the meeting.
context.purpose	string	No	Description of why the meeting is needed.
context.description	string	No	Free-text instructions for the AI. Use this for CRM notes, tone guidance, or personalization hints.
context.duration_minutes	integer	No	Desired meeting duration in minutes.
context.timeframe	object	No	Preferred scheduling window.
context.timeframe.start	string	No	ISO 8601 start of the scheduling window.
context.timeframe.end	string	No	ISO 8601 end of the scheduling window.

Request

curl -X POST https://api.skipup.ai/api/v1/meeting_requests \
  -H "Authorization: Bearer $SKIPUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizer_email": "[email protected]",
    "organizer_name": "Alice Chen",
    "organizer_timezone": "America/New_York",
    "participants": [
      {"email": "[email protected]", "name": "Bob Lee", "timezone": "America/Chicago"},
      {"email": "[email protected]"}
    ],
    "include_introduction": true,
    "context": {
      "title": "Project kickoff",
      "purpose": "Discuss Q2 roadmap and assign workstreams",
      "description": "Meeting with the RevOps team. Keep tone friendly and concise.",
      "duration_minutes": 45,
      "timeframe": {
        "start": "2025-02-01T00:00:00Z",
        "end": "2025-02-14T23:59:59Z"
      }
    }
  }'

You can also use flat participant_emails instead of participants:

curl -X POST https://api.skipup.ai/api/v1/meeting_requests \
  -H "Authorization: Bearer $SKIPUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "organizer_email": "[email protected]",
    "participant_emails": ["[email protected]", "[email protected]"],
    "context": {
      "title": "Project kickoff",
      "purpose": "Discuss Q2 roadmap and assign workstreams",
      "duration_minutes": 45
    }
  }'

Response 202 Accepted

{
  "data": {
    "id": "mr_01HQ...",
    "organizer_email": "[email protected]",
    "participant_emails": ["[email protected]", "[email protected]"],
    "status": "active",
    "title": "Project kickoff",
    "purpose": "Discuss Q2 roadmap and assign workstreams",
    "description": "Meeting with the RevOps team. Keep tone friendly and concise.",
    "include_introduction": true,
    "duration_minutes": 45,
    "timeframe": {
      "start": "2025-02-01T00:00:00Z",
      "end": "2025-02-14T23:59:59Z"
    },
    "created_at": "2025-01-20T14:30:00Z",
    "updated_at": "2025-01-20T14:30:00Z"
  }
}

Idempotency

The create endpoint supports idempotency keys. Pass an Idempotency-Key header with a unique value (such as a UUID) to safely retry requests without creating duplicate meeting requests. Cached responses are stored for 24 hours.

curl -X POST https://api.skipup.ai/api/v1/meeting_requests \
  -H "Authorization: Bearer $SKIPUP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "organizer_email": "[email protected]",
    "participant_emails": ["[email protected]"]
  }'

Note

If you retry a request with the same Idempotency-Key within 24 hours, you receive the original response without creating a new meeting request.

Cancel a meeting request

POST /api/v1/meeting_requests/:id/cancel

Cancels a meeting request. Only requests with status active or paused can be cancelled.

Scope required: meeting_requests.write

Request body

Parameter	Type	Required	Default	Description
notify	boolean	No	false	Whether to send cancellation notifications to participants.

Request

curl -X POST https://api.skipup.ai/api/v1/meeting_requests/mr_01HQ.../cancel \
  -H "Authorization: Bearer $SKIPUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"notify": true}'

Response

{
  "data": {
    "id": "mr_01HQ...",
    "organizer_email": "[email protected]",
    "participant_emails": ["[email protected]"],
    "status": "cancelled",
    "created_at": "2025-01-20T14:30:00Z",
    "updated_at": "2025-01-21T10:00:00Z",
    "cancelled_at": "2025-01-21T10:00:00Z"
  }
}

Errors

Status	Type	Description
422	invalid_request	The request is not in active or paused status and cannot be cancelled.

Pause a meeting request

POST /api/v1/meeting_requests/:id/pause

Pauses an active meeting request. While paused, SkipUp stops processing messages and sending follow-ups on this conversation. Incoming messages are still recorded but not acted on. Only requests with status active can be paused.

Scope required: meeting_requests.write

Request body

No request body is required.

Request

curl -X POST https://api.skipup.ai/api/v1/meeting_requests/mr_01HQ.../pause \
  -H "Authorization: Bearer $SKIPUP_API_KEY"

Response

{
  "data": {
    "id": "mr_01HQ...",
    "organizer_email": "[email protected]",
    "participant_emails": ["[email protected]"],
    "status": "paused",
    "title": "Project kickoff",
    "purpose": "Discuss Q2 roadmap",
    "duration_minutes": 30,
    "timeframe": {
      "start": "2025-02-01T00:00:00Z",
      "end": "2025-02-14T23:59:59Z"
    },
    "created_at": "2025-01-20T14:30:00Z",
    "updated_at": "2025-01-22T09:00:00Z",
    "paused_at": "2025-01-22T09:00:00Z",
    "booked_at": null,
    "cancelled_at": null
  }
}

Errors

Status	Type	Description
422	invalid_request	The request is not in active status. Returns a message indicating the current status (e.g. “Cannot pause a request that is already paused”).

Note

Pausing a request is a silent operation. Participants are not notified when a conversation is paused.

Resume a meeting request

POST /api/v1/meeting_requests/:id/resume

Resumes a paused meeting request. SkipUp returns the request to active status and picks up scheduling where it left off, including reviewing any messages that arrived while the request was paused. Only requests with status paused can be resumed.

Scope required: meeting_requests.write

Request body

No request body is required.

Request

curl -X POST https://api.skipup.ai/api/v1/meeting_requests/mr_01HQ.../resume \
  -H "Authorization: Bearer $SKIPUP_API_KEY"

Response

{
  "data": {
    "id": "mr_01HQ...",
    "organizer_email": "[email protected]",
    "participant_emails": ["[email protected]"],
    "status": "active",
    "title": "Project kickoff",
    "paused_at": null,
    "created_at": "2025-01-20T14:30:00Z",
    "updated_at": "2025-01-23T11:00:00Z"
  }
}

Errors

Status	Type	Description
422	invalid_request	The request is not in paused status (e.g. “Cannot resume a request that is not paused”).

Tip

If a participant sends a message with scheduling intent while the request is paused, SkipUp may automatically resume the request to avoid missing a booking opportunity. You can check for this via the meeting_request.resumed webhook event.

Change organizer

POST /api/v1/meeting_requests/:id/change_organizer

Changes the organizer of an active meeting request.

Scope required: meeting_requests.write

Request body

Parameter	Type	Required	Description
new_organizer_email	string	Yes	Email address of the new organizer.

Request

curl -X POST https://api.skipup.ai/api/v1/meeting_requests/mr_01HQ.../change_organizer \
  -H "Authorization: Bearer $SKIPUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"new_organizer_email": "[email protected]"}'

Response

{
  "data": {
    "id": "mr_01HQ...",
    "organizer_email": "[email protected]",
    "participant_emails": ["[email protected]"],
    "status": "active",
    "created_at": "2025-01-20T14:30:00Z",
    "updated_at": "2025-01-21T11:00:00Z"
  }
}

Errors

Status	Type	Description
422	invalid_request	The request is not in active status.
422	validation_error	The new organizer email is invalid or cannot be assigned.

Update context

POST /api/v1/meeting_requests/:id/context

Updates the scheduling context of an active meeting request. You can update any combination of context fields. Only the fields you provide are updated.

Scope required: meeting_requests.write

Request body

Parameter	Type	Required	Description
title	string	No	Updated meeting title.
purpose	string	No	Updated meeting purpose.
description	string	No	Updated free-text instructions for the AI.
duration_minutes	integer	No	Updated meeting duration in minutes.
timeframe	object	No	Updated scheduling window.
timeframe.start	string	No	ISO 8601 start of the scheduling window.
timeframe.end	string	No	ISO 8601 end of the scheduling window.

Request

curl -X POST https://api.skipup.ai/api/v1/meeting_requests/mr_01HQ.../context \
  -H "Authorization: Bearer $SKIPUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated kickoff meeting",
    "description": "Carol is joining from the London office — suggest afternoon slots.",
    "duration_minutes": 60,
    "timeframe": {
      "start": "2025-02-10T00:00:00Z",
      "end": "2025-02-21T23:59:59Z"
    }
  }'

Response

{
  "data": {
    "id": "mr_01HQ...",
    "organizer_email": "[email protected]",
    "participant_emails": ["[email protected]", "[email protected]"],
    "status": "active",
    "title": "Updated kickoff meeting",
    "purpose": "Discuss Q2 roadmap and assign workstreams",
    "description": "Carol is joining from the London office — suggest afternoon slots.",
    "duration_minutes": 60,
    "timeframe": {
      "start": "2025-02-10T00:00:00Z",
      "end": "2025-02-21T23:59:59Z"
    },
    "created_at": "2025-01-20T14:30:00Z",
    "updated_at": "2025-01-22T08:00:00Z"
  }
}

Errors

Status	Type	Description
422	invalid_request	The request is not in active status.