Event

Specifies information about an event, including the location, event name, and which invitees plan to attend. The User and Page objects have an events connection.

To read an Event, you need one of the following:

• a generic access_token for public events (those whose privacy is set to OPEN)
• a user access_token for a user who can see the event for non-public events
• an app access_token (for non-public events, must be the app that created the event)
• a page access_token (for non-public events, must be the page that created the event)

To read the /events connection of a User, you need:

• the user_events permission for the current user
• the friends_events permission for a friend of the current user

Example

The Facebook Developer Garage Austin Event:

https://graph.facebook.com/331218348435

Creating Events

• To create an event on behalf of a User: instructions here
• To create an event on behalf of a Page: instructions here

Events Timezone Migration Note

Starting with the 'Events Timezone' migration, all event times are always ISO-8601 formatted strings; the 'date_format' query string modifier no longer has any effect. The following formats are now returned, depending on the type of event:

• Date-only (e.g., '2012-07-04'): events that have a date but no specific time yet.
• Precise-time (e.g., '2012-07-04T19:00:00-0700'): events that start at a particular point in time, in a specific offset from UTC. This is the way new Facebook events keep track of time, and allows users to view events in different timezones.
• Local-time (deprecated, e.g., '2012-07-04T19:00:00'): legacy events that do not have any timezone information. This format is deprecated, but continues to be returned due to legacy events that are still in the system.

Note: To create an Event for a page with the 'ticket_uri' field, you will need to have this migration turned on.

---

Fields

Name	Description	Permissions	Returns
id	The event ID	generic access_token, user_events or friends_events	string
owner	The profile that created the event	generic access_token, user_events or friends_events	object containing id and name fields
name	The event title	generic access_token, user_events or friends_events	string
description	The long-form description of the event	generic access_token, user_events or friends_events	string
start_time	The start time of the event, as you want it to be displayed on facebook	generic access_token, user_events or friends_events	string containing an ISO-8601 formatted date/time (see 'Events Timezone Migration Note' above for details on returned formats)
end_time	The end time of the event, if one has been set	generic access_token, user_events or friends_events	string containing an ISO-8601 formatted date/time (see 'Events Timezone Migration Note' above for details on returned formats)
location	The location for this event	generic access_token, user_events or friends_events	string
venue	The location of this event	generic access_token, user_events or friends_events	object containing one or more of the following fields: id, street, city, state, zip, country, latitude, and longitude fields
privacy	The visibility of this event	generic access_token, user_events or friends_events	string containing 'OPEN', 'SECRET', 'FRIENDS', or 'CLOSED' (deprecated)
updated_time	The last time the event was updated	generic access_token, user_events or friends_events	string containing ISO-8601 date-time
picture	The URL of the event's picture (only returned if you explicitly include picture in the fields param; example: ?fields=id,name,picture)	generic access_token, user_events or friends_events	string
ticket_uri	The URL to a location to buy tickets for this event (on Events for Pages only)	generic access_token, user_events or friends_events	string

---

Connections

Name	Description	Permissions	Returns
feed	This event's wall.	any valid access_token, user_events or friends_events	An array of Post objects.
noreply	All of the users who have been not yet responded to their invitation to this event.	any valid access_token, user_events or friends_events	array containing objects with id, name and rsvp_status fields.
invited	All of the users who have been invited to this event.	any valid access_token, user_events or friends_events	array containing objects with id, name and rsvp_status fields.
attending	All of the users who are attending this event.	any valid access_token, user_events or friends_events	array containing objects with id, name and rsvp_status fields.
maybe	All of the users who have been responded "Maybe" to their invitation to this event.	any valid access_token, user_events or friends_events	array containing objects with id, name and rsvp_status fields.
declined	All of the users who declined their invitation to this event.	any valid access_token, user_events or friends_events	array containing JSON objects with id, name and rsvp_status fields.
picture	The event's profile picture.	any valid access_token, user_events or friends_events	Returns a HTTP 302 with the URL of the event's picture (use ?type=small | normal | large to request a different photo).
videos	The videos uploaded to an event.	valid user access_token	array of Video objects.

---

feed

This connection corresponds to the Event's wall. You can create a link, post or status message by issuing an HTTP POST request to the EVENT_ID/feed connection.

links

Create

You can post a link on the event's wall by issuing an HTTP POST request to EVENT_ID/feed with the publish_stream permissions and the following parameters.

Parameter	Description	Type	Required
link	Link URL	string	yes
message	Link message	string	no

The other fields are taken from the metadata of the page URL given in the 'link' param.

If the create is successful, you get the following return.

Name	Description	Type
id	The new link ID	string

---

posts

Create

You can create a post on an Event's wall by issuing an HTTP POST request to EVENT_ID/feed with the publish_stream permissions and the following parameters.

Parameter	Description	Type	Required
message	Post message	string	either message or link
link	Post URL	string	either message or link
picture	Post thumbnail image (can only be used if link is specified)	string	no
name	Post name (can only be used if link is specified)	string	no
caption	Post caption (can only be used if link is specified)	string	no
description	Post description (can only be used if link is specified)	string	no
actions	Post actions	array of objects containing name and link	no

If the create is successful, you get the following return.

Name	Description	Type
id	The new post ID	string

---

statuses

create

You can post a status message on an Event's wall by issuing an HTTP POST request to EVENT_ID/feed with the publish_stream permissions and the following parameters.

Parameter	Description	Type	Required
message	Status Message content	string	yes

If the create is successful, you get the following return.

Name	Description	Type
id	The new status message ID	string

---

invited

Create

You can invite users to an event by issuing an HTTP POST to /EVENT_ID/invited/USER_ID. You can invite multiple users by issuing an HTTP POST to /EVENT_ID/invited?users=USER_ID1,USER_ID2,USER_ID3. Both of these require the create_event permission and return true if the invite is successful.

Read

You can read the list of invitees for an event by issuing an HTTP GET to /EVENT_ID/invited:

https://graph.facebook.com/331218348435/invited

You can check whether a specific user has been invited to an event by issuing an HTTP GET to /EVENT_ID/invited/USER_ID:

https://graph.facebook.com/331218348435/invited/2503747

You'll need the user_events or friend_events permissions to view the invite list for for non-public events.

These calls return an object with the name, id, and rsvp_status ('not_replied', 'unsure', 'attending', or 'declined') fields. When checking for a specific user, if the user is not invited to the event, the API will return an empty data array.

If a summary query parameter is passed with 1 as the value, a summary entry is included in the response:

Name	Description	Type
count	Total number of invitees (the sum of the other four fields)	integer
noreply_count	Total number of invitees that haven't yet replied	integer
attending_count	Total number of invitees that are attending	integer
declined_count	Total number of invitees that are not attending	integer
maybe_count	Total number of invitees that have not yet rsvp'ed	integer

For each other rsvp type (attending, not_replied, unsure, and declined), only the count field appears, and it is equal to the count of that rsvp type (eg maybe_count for /maybe/).

Delete

You can un-invite a user from an event by issuing an HTTP DELETE to /EVENT_ID/invited/USER_ID. Returns true if the request is successful. The user must be an admin (i.e. creator) of the event for this call to succeed. Requires create_event permission.

---

attending

Create

You can RSVP the user as 'attending' an Event by issuing an HTTP POST to EVENT_ID/attending. This requires the rsvp_event permission and returns true if the RSVP is successful, and false otherwise.

Read

You can see which users are 'attending' an event by issuing an HTTP GET to /EVENT_ID/attending This returns a list of all users who responded 'yes' to the event:

https://graph.facebook.com/331218348435/attending

You can check if a specific user responded 'yes' to an event by issuing an HTTP GET to /EVENT_ID/attending/USER_ID. These operations require the user_events or friends_events permissions for non-public events and return an array of objects with the name, id, and rsvp_status fields. When checking a single user, an empty data will be returned if the user did not respond 'yes' to the event.

---

maybe

Create

You can RSVP the user as a 'maybe' for an Event by issuing an HTTP POST to EVENT_ID/maybe. This requires the rsvp_event permission and returns true if the RSVP is successful, and false otherwise.

Read

You can see which users have replied 'maybe' to an event by issuing an HTTP GET to /EVENT_ID/maybe This returns a list of all users who responded 'maybe' to the event:

https://graph.facebook.com/331218348435/maybe

You can check if a specific user responded 'maybe' to an event by issuing an HTTP GET to /EVENT_ID/maybe/USER_ID. These operations require the user_events or friends_events permissions for non-public events and return an array of objects with the name, id, and rsvp_status fields. When checking a single user, an empty data will be returned if the user did not respond 'maybe' to the event.

---

declined

Create

You can RSVP the user as 'declined' for an Event by issuing an HTTP POST to EVENT_ID/declined. This requires the rsvp_event permission and returns true if the RSVP is successful, and false otherwise.

Read

You can see which users are declined an event (i.e. responded 'no') by issuing an HTTP GET to /EVENT_ID/declined This returns a list of all users who responded 'no' to the event:

https://graph.facebook.com/331218348435/declined

You can check if a specific user responded 'no' to an event by issuing an HTTP GET to /EVENT_ID/declined/USER_ID. These operations require the user_events or friends_events permissions for non-public events and return an array of objects with the name, id, and rsvp_status fields. When checking a single user, an empty data will be returned if the user did not respond 'no' to the event.

---

noreply

Read

You can see which users have not replied to an event by issuing an HTTP GET to /EVENT_ID/noreply This returns a list of all users who have not replied to the event:

https://graph.facebook.com/331218348435/noreply

You can check if a specific user has not replied to an event by issuing an HTTP GET to /EVENT_ID/noreply/USER_ID. These operations require the user_events or friends_events permissions for non-public events and return an array of objects with the name, id, and rsvp_status fields. When checking a single user, an empty data will be returned if the user did reply to the event.

---

photos

Read

You can read the photos published to an event by issuing an HTTP GET request to /EVENT_ID/photos with a user access_token.

The API returns an array of photo objects.

Create

You can post photos to an Event's Wall by issuing an HTTP POST request to EVENT_ID/photos with the publish_stream permission and the following parameters.

Parameter	Description	Type	Required
source	Photo content	multipart/form-data	yes
message	Photo description	string	no

If the create is successful, you get the following return.

Name	Description	Type
id	The new photo ID	string

---

videos

Read

You can read the videos published to an event by issuing an HTTP GET request to /EVENT_ID/videos with a user access_token.

The API returns an array of video objects.

Create

You can publish a video to an event by issuing an HTTP POST request to https://graph-video.facebook.com/EVENT_ID/videos with a user access_token and the following parameters:

Parameter	Description	Type	Required
source	Video content	multipart/form-data	yes
title	Video title	string	no
description	Video description	string	no

If the create is successful, you get the following return.

Name	Description	Type
id	The new video ID	string

---

picture

Read

Issuing an HTTP GET request to /EVENT_ID/picture returns an HTTP 302 redirect to URL of the event's profile picture.

Create/Update

You can add a profile picture to an event by issuing an HTTP POST request to /EVENT_ID/picture with the create_event permission for an admin of the event and the following parameter:

Parameter	Description	Type	Required
source	Picture content	multipart/form-data	yes

Returns true if the request is successful.

Delete

You can delete an event's profile picture by issuing an HTTP DELETE request to /EVENT_ID/picture with the create_event permission for an admin of the event.

Returns true if the request is successful.

---

ticket_uri

Note: ticket_uri is only available to events created by page admins on events that are created for pages.

Read

Issuing an HTTP GET request to /EVENT_ID?fields=ticket_uri returns a URI to a location where you can buy tickets.

Create/Update

You can add a ticket_uri to an event by issuing an HTTP POST request to /EVENT_ID with the create_event permission for a Page Admin and the following parameter:

Parameter	Description	Type	Required
ticket_uri	URI where people can buy tickets	string	yes

Returns true if the request is successful.