Create or Update Invite ^BETA

Description #

Create a new Smart Invite for a recipient.

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",
  "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": "2024-07-28T09:30:00Z",
    "end": "2024-07-28T10: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

{
  "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": "2024-07-28T09:30:00Z",
      "tzid": "Europe/London"
    },
    "end": {
      "time": "2024-07-28T10: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.

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.

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