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 #

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/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 #

API_KEY Required  #

This is the client_secret for your Application in the Cronofy Developer Dashboard. 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.
• remove remove a recipient 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, 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.

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 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 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.