# Create or Update Invite

> **BETA**

#### Description
Create a new Smart Invite for a recipient.

#### URL format
```
{data_center_url}/v1/smart_invites
```

#### Example Request
```http
POST /v1/smart_invites HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {API_KEY}
Content-Type: application/json; charset=utf-8

{
  "method": "request",
  "recipient": {
    "email": "cronofy@example.com"
  },
  "smart_invite_id": "your-unique-identifier-for-invite",
  "callback_url": "https://yourapp.example.com/cronofy/smart_invite/notifications",
  "event": {
    "summary": "Board meeting",
    "description": "Discuss plans for the next quarter.",
    "start": "2026-04-29T09:30:00Z",
    "end": "2026-04-29T10:00:00Z",
    "tzid": "Europe/London",
    "location": {
      "description": "Board room"
    }
  },
  "organizer": {
    "name": "Smart invite application",
    "email": "organizer@myapplication.com"
  }
}
```

#### Example Response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "recipient": {
    "email": "cronofy@example.com",
    "status": "pending"
  },
  "smart_invite_id": "your-unique-identifier-for-invite",
  "callback_url": "https://yourapp.example.com/cronofy/smart_invite/notifications",
  "event": {
    "summary": "Board meeting",
    "description": "Discuss plans for the next quarter.",
    "start": {
      "time": "2026-04-29T09:30:00Z",
      "tzid": "Europe/London"
    },
    "end": {
      "time": "2026-04-29T10:00:00Z",
      "tzid": "Europe/London"
    },
    "location": {
      "description": "Board room"
    }
  },
  "attachments": {
    "icalendar": "BEGIN:VCALENDAR\nVERSION:2.0..."
  }
}
```

#### Request parameters
##### `data_center_url` *(required)*

The URL for the data center you want to communicate with. Possible choices are:

- `api-au.cronofy.com` - Australia
- `api-ca.cronofy.com` - Canada
- `api-de.cronofy.com` - Germany
- `api-sg.cronofy.com` - Singapore
- `api-uk.cronofy.com` - United Kingdom
- `api.cronofy.com` - United States

Find out more about [Cronofy's data centers](/developers/data-centers/index.md).
##### `API_KEY` *(required)*

This is the `client_secret` for your Application in the [Cronofy Developer Dashboard](https://app.cronofy.com/jump/developer). You can find this on the Settings tab. If you don't have an Application registered with Cronofy yet, you can easily create one by clicking on the "Create New Application" button on the left hand side of the dashboard.

##### `recipient`

This contains the email address of the attendee.

##### `smart_invite_id` *(required)*

Your unique identifier for the Smart Invite. Normally this will relate to an appointment, interview, or any other type of meeting in your application. You can use the same `smart_invite_id` for different attendees when you want multiple people to attend the same event.

##### `callback_url` *(optional)*

The URL for Cronofy to `POST` updates to whenever the attendee status changes.

The response contains the contents of your original post along with an iCalendar attachment you would add to the email to the recipient.

> **WARNING:** `https://yourapp.example.com/cronofy/smart_invite/notifications` is provided for testing and illustrative purposes only. It is not a functional endpoint and must not be used in production.
For production use, you must supply your own valid, publicly accessible callback URL.

##### `event` *(required)*

An object with the details of the event you wish to wish to invite the recipient to. Details of what parameters this object can hold can be found in the [create or update event](/developers/api/events/upsert-event/index.md) documentation.

Please note the following event properties are not supported with Smart Invites:

- `event.attendees` - this is set by the Smart Invite to include your recipient(s) automatically

- `event.conferencing` - Support for conferencing generation is not yet available for Smart Invite events

##### `recipient.email` *(required)*

The email address you are going to send the Smart Invite to.

##### `method` *(optional)*

The method to use when creating the invite, this defaults to `request`

- `request` request a response from invited emails.

- `cancel` cancel the invitation.

##### `organizer.name` *(optional)*

The display name for the organizer of the Smart Invite. This is the value which will appear as the name of the organizer in the end user's calendar. If omitted the name of the application will be used in its place.

##### `organizer.email` *(optional)*

The email for the organizer of the Smart Invite. This is the value which will
be used as the email of the organizer in the end user's calendar. If omitted the
default address for the Cronofy data centre will be used.

[Email forwarding](/developers/smart-invites/organizer-email/index.md) **must** be set up for the full
capability of Smart Invites to function.

#### Response parameters
##### `recipient.email`

The email address of the recipient for the Smart Invite.

##### `recipient.status`

The current status of the recipient. Can be one of:

- `pending` have not received any response from the recipient

- `accepted` the recipient has accepted the invitation

- `tentative` the recipient has tentatively accepted the invitation

- `declined` the recipient has declined the invitation

##### `smart_invite_id`

The identifier for the event within your application.

##### `callback_url`

The URL within your application that Cronofy will send notifications to about user interactions with the Smart Invite.

##### `event`

The details of the event.

##### `attachments`

Attachments to add to the multipart email being sent to the recipient.

##### `attachments.icalendar`

The iCalendar representation of the event to be sent to the user.

Please see our best practices on [sending Smart Invite ICS files](/developers/smart-invites/sending/index.md).



---
[Read in HTML](/developers/api/smart-invites/create-smart-invite/)