Getting Started

The Official Events API allows your app to create and update Events on behalf of Pages, requiring no action from page owners.

For example, let's say you are a ticketing provider for a disaster relief organization who is planning a fundraising concert that will feature multiple performing artists. You can use the Official Events API to create an event on the organization's Facebook page and associate the venue and artists pages with the event by assigning roles for each of them.

Having one “official” event reduces the risk of participants accidentally creating duplicate events that might end up causing attendee confusion.

If you enable a third-party to create, publish, or manage events for a page, you must obtain a page access token for the page and request the pages_manage_engagement, pages_manage_posts, pages_read_engagement, and pages_read_user_content permissions from the third-party.

Categories & Roles

Every official event has a category and usually one page that has been assigned a primary performer role. You must include a category when you create an event. Role assignments, however, are optional. You can the see the list of Roles and Categories in the Official Events API Reference Documentation (Note: Your application must be white listed for you to view the Reference Documentation)

App Access Token

All API requests require your app access token.

Creating

To create an official event, send a POST request to the official_events edge and include the following parameters:

ParameterDescription

access_token

Your app's app access token.

category

The event's category.

name

The event's name.

description

The event's description.

place_id

The FBID of the target Page where the official event is to be created. This page must have a Place set up. If it does not, you can use the Unowned Places API to create one.

timezone

The event's timezone. Refer to the Official Events Graph API Reference for an enum of possible timezones.

cover

The URL to a cover photo for the event, as well as an X- and Y-offset to set the crop starting point. The dimensions should be 1.91:1 aspect ratio at a recommended 1200x628px resolution.

This will create the event and return the event id.

Example Request and Response

  Http Method: POST
  URL: /v2.8/official_events
  Request Body:
  {
     "name": "Get Started with Ticketing",
     "description": "This is the best place to buy your first ticket",
     "access_token": "{access_token}",
     "place_id": "{place_id}",
     "cover": {
        "source":  "{hosted_image_url}",
        "offset_x": 0,
        "offset_y": 0
        },
     "category": "FAMILY_EVENT",
     "timezone": "US/Pacific",
     "start_time": "2012-03-24 17 (tel:2012032417) 17:45:12",
     "roles":{"{page_id}":"{EVENT_ROLE}"}
  }
  
  Response Body:
  {
     "id": "{id_of_the_new_event}"
  }
  

Reading

To read an official event, send a GET request to /{official_event_id}.

Example Request and Response

  Http Method: GET
  URL: /v2.8/{official_event_id}?access_token={access_token}
  
  Response Body:
  {
     "description": "This is the best place to buy your first ticket",
     "name": "Get Started with Ticketing",
     "place": {
        "name": "Facebook HQ",
        "location": {
            "city": "Menlo Park",
            "country": "United States",
            "latitude": 37.483909424364,
            "longitude": -122.1489697771,
            "state": "CA",
            "street": "1 Hacker Way",
            "zip": "94025"
         },
        "id": "{place_id}"
      },
     "start_time": "2012-03-24T17:45:12-0700",
     "id": "{event_id}"
  }
  

Updating

To update an official event, send a POST request to /{official_event_id}.

Example Request and Response

  Http Method: POST
  URL: /v2.8/{official_event_id}
  Request Body:
  {
     "name": "This is an updated name of the event",
     "access_token": "{access_token}"
  }
  
  Response Body:
  {
     "success": boolean
  }
  

Deleting

To delete an official event, send a DELETE request to /{official_event_id}.

Example Request and Response

  Http Method: DELETE
  URL: /v2.8/{official_event_id}
  Request Body:
  {
     "access_token":"{access_token}"
  }
  
  Response Body:
  {
      "success": boolean
  }
  

Merging

You can merge an official event with another by sending a POST request to /{official_event_id}/merge_into and including the target event's official event id.

Example Request and Response

  Http Method: POST
  URL: /v2.8/{official_event_id}/merge_into
  Request Body:
  {
     "access_token": "{access_token}",
     "destination_id": "{target_event_id}"
  }
  
  Response Body:
  {
     "success": boolean
  }
  

Pixel Implementation Guide

Who is this for?

Transactional partners implementing their FB integrated checkout flow must implement the Facebook Pixel. Read more about Facebook Pixel.

Implementation

Follow these steps and make sure Pixel is setup in your Ads Manager. Start adding the code snippet to your pages. At a minimum, the pixel should be enabled by traffic driven from Facebook.

Ticketing Specific Pixel Events

  1. Landing on the ticket purchase page
    (fbq('track', 'ViewContent', {content_ids: ['partner_event_id']}))
            
  2. Entering checkout flow
    (fbq('track', 'InitiateCheckout', {content_ids: ['partner_event_id']}))
            
  3. Purchase
    (fbq('track', 'Purchase', {value:15.30, currency: 'USD', num_items: 1, {content_ids: ['partner_event_id']}})
            
Pixel EventAttributesEvents
ViewContent

content_ids

An Array of ID's that uniquely identifies events. For example event's database ID.

(Required)
InitiateCheckout

content_ids

An Array of ID's that uniquely identifies events. For example event's database ID.

(Required)
Purchase

value

Total Value of the transaction

(Required)

currency

3 Letter ISO Code

(Required)

num_items

Total number of event tickets purchased

(Required)

content_ids

An Array of ID's that uniquely identifies events. For example event's database ID.

(Required)

Error Handling

Error ConstantError CodeDescription

EVENT_INVALID_ROLE

1004

Invalid role for this event category

EVENT_INVALID_TIME

1000

Invalid time for an event

EVENT_NO_IMAGE_PAGE

10003

Cannot find a page associated with the app for uploading cover photo

PERMISSION_CREATE_EVENT

296

Managing events requires the extended permission create_event

PERMISSION_EVENT

290

Creating and modifying events requires the extended permission create_event

PARAM

100

Invalid parameter

PARAM

104

Missing access token

PARAM

190

Invalid OAuth access token

PARAM

803

Request with invalid Event Id

Testing using Sample code

Want to test the waters before you begin development work ? Use this link below to test the API functionalities in your local Postman instance

You can download the Postman collection using this link: Official Events API Collection In addition to the collection download this environment file and import to your postman instance that will help running these sample code