Invite Status

Description #

Once a Smart Invite has been created you may need to retrieve the current state of it, usually in response to a notification from Cronofy.

Example Request #

GET /v1/smart_invites?smart_invite_id=your-unique-id-for-invite&include_ics=true HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {API_KEY}

Example Response #

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "recipients": [
    {
      "email": "cronofy@example.com",
      "status": "tentative",
      "comment": "example comment",
      "proposal": {
        "start": {
          "time": "2026-10-25T23:00:00+02:00",
          "tzid": "Europe/Paris"
        },
        "end": {
          "time": "2026-10-25T23:00:00+02:00",
          "tzid": "Europe/Paris"
        }
      }
    },
    {
      "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-27T09:30:00Z",
      "tzid": "Europe/London"
    },
    "end": {
      "time": "2026-10-27T10:00:00Z",
      "tzid": "Europe/London"
    },
    "location": {
      "description": "Board room"
    }
  },
  "attachments": {
    "icalendar": "BEGIN:VCALENDAR\nVERSION:2.0..."
  }
}

Single recipient Smart Invites #

Smart Invites created with the superseded single recipient version are identified by both the smart_invite_id and the recipient_email. The response has a single recipient and a replies collection in place of recipients.

GET /v1/smart_invites?recipient_email=cronofy@example.com&smart_invite_id=your-unique-identifier-for-invite&include_ics=true HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {API_KEY}

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "recipient": {
    "email": "cronofy@example.com",
    "status": "declined",
    "comment": "example comment",
    "proposal": {
      "start": {
        "time": "2026-10-25T23:00:00+02:00",
        "tzid": "Europe/Paris"
      },
      "end": {
        "time": "2026-10-25T23:00:00+02:00",
        "tzid": "Europe/Paris"
      }
    }
  },
  "replies": [
    {
      "email": "person1@example.com",
      "status": "accepted"
    },
    {
      "email": "person2@example.com",
      "status": "declined",
      "comment": "example comment",
      "proposal": {
        "start": {
          "time": "2026-10-25T23:00:00+02:00",
          "tzid": "Europe/Paris"
        },
        "end": {
          "time": "2026-10-25T23:00:00+02:00",
          "tzid": "Europe/Paris"
        }
      }
    }
  ],
  "smart_invite_id": "your-unique-identifier-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-27T09:30:00Z",
      "tzid": "Europe/London"
    },
    "end": {
      "time": "2026-10-27T10:00:00Z",
      "tzid": "Europe/London"
    },
    "location": {
      "description": "Board room"
    }
  },
  "attachments": {
    "icalendar": "BEGIN:VCALENDAR\nVERSION:2.0..."
  }
}

Request parameters #

API_KEY Required  #

The client_secret of the client creating the event.

smart_invite_id Required  #

The identifier for the Smart Invite within your application.

recipient_email Optional  #

The email address of the recipient. Required for Smart Invites created with the superseded single recipient version, where it identifies the Smart Invite along with the smart_invite_id. Omit it for Smart Invites with a recipients collection.

include_ics Optional  #

A Boolean indicating whether you would like the current ICS attachment to be returned in the response. Defaults to false.

Response parameters #

recipients  #

An array of the recipients of the Smart Invite, each with the same attributes as recipient below.

recipient  #

Only returned for single recipient Smart Invites.

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

recipient.comment  #

Any comments provided along with the reply.

recipient.proposal  #

Details of the counter proposal received as a reply.

recipient.proposal.start  #

The proposed start for the event, an object with two attributes, time and tzid:

{
  "time": "2026-10-24T23:00:00+02:00",
  "tzid": "Europe/Paris"
}

The time attribute is the Time or Date at which the event starts. This will be provided with an offset matching that of the corresponding tzid.

The tzid attribute specifies a String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

• Etc/UTC
• Europe/Paris
• America/Chicago

recipient.proposal.end  #

The proposed end for the event, an object with two attributes, time and tzid:

{
  "time": "2026-10-24T23:00:00+02:00",
  "tzid": "Europe/Paris"
}

The time attribute is the Time or Date by which the event ends. This will be provided with an offset matching that of the corresponding tzid.

The tzid attribute specifies a String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

• Etc/UTC
• Europe/Paris
• America/Chicago

replies  #

Only returned for single recipient Smart Invites.

An array of all the replies received for the invitation.

These include all replies, not just from the email address of the invited user. This is useful in cases of invitation forwarding, email address aliases or sending to distribution lists.

reply.email  #

The email address of the reply for the Smart Invite.

reply.status  #

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

• pending have not received any response from the reply
• accepted the reply has accepted the invitation
• tentative the reply has tentatively accepted the invitation
• declined the reply has declined the invitation

reply.comment  #

Any comments provided along with the reply.

reply.proposal  #

Details of the counter proposal received as a reply.

reply.proposal.start  #

The proposed start for the event, an object with two attributes, time and tzid:

{
  "time": "2026-10-24T23:00:00+02:00",
  "tzid": "Europe/Paris"
}

The time attribute is the Time or Date at which the event starts. This will be provided with an offset matching that of the corresponding tzid.

The tzid attribute specifies a String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

• Etc/UTC
• Europe/Paris
• America/Chicago

reply.proposal.end  #

The proposed end for the event, an object with two attributes, time and tzid:

{
  "time": "2026-10-24T23:00:00+02:00",
  "tzid": "Europe/Paris"
}

The time attribute is the Time or Date by which the event ends. This will be provided with an offset matching that of the corresponding tzid.

The tzid attribute specifies a String representing a known time zone identifier from the IANA Time Zone Database.

Common examples are:

• Etc/UTC
• Europe/Paris
• America/Chicago

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  #

Only returned when the include_ics request parameter is true.

The iCalendar representation of the event to be sent to the user. Usually you would send the ICS returned from the initial call to create the Smart Invite, however it is included here for scenarios where you wish to re-send the invite, or to distribute status updates in the case of Smart Invites with multiple recipients, as other recipients only see a recipient’s updated status once they’re sent a new ICS file.

Please see our best practices on sending Smart Invite ICS files.