# Create Smart Invite ### Description Create or update a Smart Invite for one or more recipients. All recipients are invited to a single event, and each one's response is tracked against their entry in the `recipients` collection. Calling the endpoint again with the same `smart_invite_id` updates the invite. The response includes an ICS attachment to send to the recipients. ### 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", "recipients": [ { "email": "cronofy@example.com", "status": "accepted" }, { "email": "cronofy@example.org" } ], "smart_invite_id": "your-unique-id-for-invite", "callback_url": "https://example.com/cronofy/smart_invite/notifications", "event": { "summary": "Board meeting", "description": "Discuss plans for the next quarter.", "start": "2026-10-24T09:30:00Z", "end": "2026-10-24T10: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 { "recipients": [ { "email": "cronofy@example.com", "status": "accepted" }, { "email": "cronofy@example.org", "status": "pending" } ], "smart_invite_id": "your-unique-id-for-invite", "callback_url": "https://example.com/cronofy/smart_invite/notifications", "event": { "summary": "Board meeting", "description": "Discuss plans for the next quarter.", "start": { "time": "2026-10-24T09:30:00Z", "tzid": "Europe/London" }, "end": { "time": "2026-10-24T10: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](https://docs.cronofy.com/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. ##### `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](https://docs.cronofy.com/api-reference/calendar-control/smart-invites/cancel-invite/index.md). - `remove` [remove a recipient](https://docs.cronofy.com/api-reference/calendar-control/smart-invites/remove-recipient/index.md) from the invitation. ##### `recipients` *(required)* An array of the people you are inviting to the event. ##### `recipients.email` *(required)* The email address you are going to send the Smart Invite to. ##### `recipients.status` *(optional)* The initial status for the recipient as a [`String`](https://docs.cronofy.com/api-reference/fundamentals/data-types/index.md), can be one of: - `accepted` - `declined` - `pending` (default) - `tentative` ##### `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. ##### `callback_url` *(optional)* The URL for Cronofy to `POST` updates to whenever an attendee's status changes. See [Invite Callback](https://docs.cronofy.com/api-reference/calendar-control/smart-invites/invite-callback/index.md). ##### `event` *(required)* An object with the details of the event you wish to invite the recipients to. Details of what parameters this object can hold can be found in the [create or update event](https://docs.cronofy.com/api-reference/calendar-control/calendar-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 recipients automatically - `event.conferencing` - Support for conferencing generation is not yet available for Smart Invite events ##### `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 center will be used. [Email forwarding](https://docs.cronofy.com/developers/smart-invites/organizer-email/index.md) **must** be set up for the full capability of Smart Invites to function. ### Response parameters ##### `recipients.email` The email address of the recipient. ##### `recipients.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 recipients. ##### `attachments.icalendar` The iCalendar representation of the event to be sent to the recipients. Please see our best practices on [sending Smart Invite ICS files](https://docs.cronofy.com/developers/smart-invites/sending/index.md). --- [Read in HTML](https://docs.cronofy.com/api-reference/calendar-control/smart-invites/create-smart-invite/)