Invite Status BETA

Required plan: Starter

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?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}

Example Response #

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": "2024-11-13T23:00:00+02:00",
        "tzid": "Europe/Paris"
      },
      "end": {
        "time": "2024-11-13T23: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": "2024-11-13T23:00:00+02:00",
          "tzid": "Europe/Paris"
        },
        "end": {
          "time": "2024-11-13T23:00:00+02:00",
          "tzid": "Europe/Paris"
        }
      }
    }
  ],
  "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-11-15T09:30:00Z",
      "tzid": "Europe/London"
    },
    "end": {
      "time": "2024-11-15T10: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.

API_KEY required  #

The client_secret of the client creating the event.

smart_invite_id required  #

An identifier for the event within your application. Is used along with the recipient.email to uniquely identify the Smart Invite.

recipient_email required  #

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

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 #

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": "2024-11-12T23: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
recipient.proposal.end  #

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

{
  "time": "2024-11-12T23: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  #

An array of all the replies received for the invitation.

Note These will include all replies not just the email address of the invited user. This is useful in cases of invitation forwarding, email addresss 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": "2024-11-12T23: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
reply.proposal.end  #

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

{
  "time": "2024-11-12T23: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 multi-recipient invites.

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