Using the Object API

With the Object API you can create and manage Open Graph objects using a simple HTTP-based API. The Object API is supported for both mobile and web apps.

The Object API is one of two ways that objects can be created. Objects can also be created by adding special markup to web pages that you host. These self-hosted objects must be hosted on your web server and all objects are public. Creating self-hosted objects is covered in our Using Objects documentation. In contrast, the Object API lets you create objects through a single HTTP call without the requirement for a web server to host them. The Object API can also create objects that have custom or non-public privacy settings.

The Object API also includes an API for you to upload images to Facebook to use in objects and stories.

Objects must be in English. Learn how to localize objects created via the object API in our documentation on localizing open graph stories.

App-owned and user-owned objects

With the Object API you can create two kinds of objects:

  1. An app-owned object. These objects are used across your entire app. They are public, just like self-hosted objects. Anyone who uses your app can see them and they can be attached to any story your app creates.

  2. A user-owned object. A user-owned object is owned by a user. The privacy setting on a user-owned object can be changed so it's only visible to a subset of a person's audience. Stories created with a user-owned object are specific to the person attached to it.

Creating app-owned objects

In order to create an app-owned object you make a call to a URL that includes the type of object you want to create along with a JSON-encoded version of the object attached. For example, if you want to create an app-owned that is a common book object you can make this call:

curl \
  -X POST \
  "https://graph.facebook.com/app/objects/books.book"  \
  -F "access_token=$APP_TOKEN" \
  -F "object={
    \"title\":\"The Hunt for Red October\",
    \"image\":\"http://ecx.images-amazon.com/images/I/314leP6WviL._SL500_AA300_.jpg\",
    \"url\":\"https://link.you.want.displayed/example/hunt-for-red-october-link\",
    \"description\":\"Classic cold war technothriller\",
    \"data\": {
      \"isbn\":\"425240339\"
    }
  }"

There are several things to note with this call:

The path:

  • The path is /app/objects/{object_type}.
  • /app is shorthand for your app. It's roughly equivalent to /me, but for apps instead of people.
  • object/{object_type} provides Facebook context on what type of object you want to create. In our example, we create a books.book object type. If you use a custom object type the format will be something like app_namespace:object_type instead of books.book.

The access token: In order to create an app-owned object, you must use an app access token. App-owned objects are public and can be used with multiple people and multiple stories.

The object: The object is a JSON-encoded version of an object. The types used here are the types used in the books.book type. You can also include any of the properties of standard objects. Note that the type is not included in the call. This is because it's implied from the path that you used when you made the call.

The image: The image associated with this object. It will likely be used with stories told with it. Follow the guidelines for image sizes when referencing an image. (See og:image for guidelines.)

The URL: The object URL is what a story on Facebook links to when it shows up in News Feed. Note that any URL you reference must be below the URL that's set in your app dashboard. This isn't required for hosted objects. You can also use this URL to set up deep linking to your native app, in which case you must use the canonical_url of an App Link Host in this parameter.

Return value

When you create an object with the API, the id of the new object is returned:

{"id":"505124632884107"}

With that ID, you can publish a story to Facebook.

Reading an object

You can read an API object just like any other object or action in the graph, with its ID:

curl https://graph.facebook.com/505124632884107

Deleting an object

Deleting an object is done by ID:

curl –X DELETE https://graph.facebook.com/505124632884107?access_token={app-access-token}

Creating user-owned objects

Creating a user-owned object is very similar to creating an app-owned object. Here's an example call for the deliciousapp app that creates a custom object that has the object type meal:

curl 
  -X POST 
  "https://graph.facebook.com/me/objects/deliciousapp:meal" 
  -F "access_token={user-or-app-access-token}",
  -F "privacy={'value':'SELF'}",
  -F "object={\"title\":\"Chicken Enchiladas\",
       \"image\":\"http://upload.wikimedia.org/wikipedia/commons/thumb/2/23/Enchiladas_suizas.jpg/800px-Enchiladas_suizas.jpg\",
       \"url\":\"https://your.app.url.net/objects/meals/Chicken-Enchiladas\",
       \"description\":\"My homemade enchiladas\",
       \"data\":{
         \"calories\":1200
       }
     }"

The path:

  • The path is /me/objects/{custom_object_type}.
  • /me is shorthand for the person using your app.
  • object/{custom_object_type} provides Facebook context on what type of object you want to create. In our example, we create a deliciousapp:meal object type. If you use a common object type, the path to the object would be books.book instead of deliciousapp:meal.

The access token: To create a user-owned object you must use either a user token or an app access token.

The privacy parameter: This call includes a privacy parameter. In this example, the value is SELF, which means that the post is visible only to the person making the call. Your app can set this value to another setting if it informs the person using the app of the privacy setting when the object is created. Your privacy setting can not be more public than what the person has chosen for your app. For example, if a person has chosen 'Friends' you can't set the privacy of an object to 'Public.' If you don't include a privacy parameter, the default privacy setting that the person has chosen for the app will be used for the privacy of the object.

The object: The object is a JSON-encoded version of an object. This is a custom object type and includes a data section for non-default object properties, as mentioned in the section on properties. Note that the type is not included in the call. This is because it's implied from the path that you used when you made the call.

The image: The image associated with this object. This image will be used when a story appears on timeline or News Feed. Follow the guidelines for image sizes when referencing an image. (See og:image for guidelines.) The Object API also makes it possible to upload an image and then reference it in the object when it's created.

The URL: The Object URL is what a story on Facebook links to when it shows up in News Feed. Note that any URL you reference must be below the URL that's set in your app's website URL that's set in your App Dashboard. This isn't required for hosted objects. You can also use this URL to set up deep linking to your native app.

A successful call returns the ID of the object:

{"id":"509707412404500"}

Reading an object

Read the object with its ID:

curl https://graph.facebook.com/509707412404500?access_token={user-access-token}

Deleting an object

Delete the object by its ID

curl –X DELETE https://graph.facebook.com/509707412404500?access_token={user-access-token}

Publishing a story

Publishing a story on Facebook with objects created via the object API is very similar to publishing stories with self-hosted objects. There are only two differences: First, you must specify the object by ID instead of using a URL, and second, the object must be visible to the person posting the story. Here's an example of creating a story with the books.reads action. For the book argument, it uses the ID of an object you created with the Object API:

curl
  -X POST
  "https://graph.facebook.com/me/books.reads"
  -F "book=505124632884107"
  -F "access_token=$TOKEN"

Properties

Object properties are added to the top-level of the JSON object that you pass into your call to create an object.

Any property that's not a standard object property should be included as a data: {...} element on the JSON object you pass in when creating an object. Here's an example of a custom mountain type that includes an elevation custom property:

{
  title: 'Mt. Rainier', 
  type: 'myapp:mountain',
  image: 'http://en.wikipedia.org/wiki/File:Mount_Rainier_5917s.JPG', 
  url: 'https://url.to.your.app/example/mountains/Mt-Rainier',
  description: 'Classic cold war technothriller',
  data: {
    elevation: 14411
  }
}

This format is the same as what an object looks like when it's read back from the database via the Graph API.

Images with the Object API

Facebook offers a staging service that allows you to upload images in order to reference them in both objects and actions. This service allows you to upload an image via an HTTP endpoint and the service returns an opaque token you can use as an image URL when referencing images in objects and actions.

Using the staging service with the Object API is optional and is provided only for convenience. If you want to use an image hosted on your own server, just use a URL to your image wherever an image argument is required.

The staging service is only available for use with user-owned objects and actions. It can't be used with app-owned objects.

Staging images

If you want to stage an image for a user-owned object, use this URL:

https://graph.facebook.com/me/staging_resources

As an example, if you wanted to stage an image to use in a user-owned object, a call with curl would look like this:

curl -X POST \
  https://graph.facebook.com/me/staging_resources \
  -F "file=@images/prawn-curry-1.jpg" \
  -F "access_token=$USER_ACCESS_TOKEN"

The file argument is how you attach the file to the HTTP call.

Note: Curl does not always add an image type for PNG images, so you may have to add the image type manually if your images are pngs:

-F file='@foo.png;type=image/png'

Return value

A call to the service will return an opaque uri value that you can use in later calls:

{"uri":"fbstaging://graph.facebook.com/staging_resources/MDAxMDE1MTU3NjIyNzExNzYwNA=="}

Although this is a URI, it's for internal use only and is only a way to pass around an identifier. Referencing it as if it were an image will not return any useful data.

Creating an object

Once you have the handle, you can easily create an object with the Object API and reference the image that you just uploaded. This is an example of creating a user-owned object:

curl -X POST
  "https://graph.facebook.com/me/objects/cookingapp:meal"
  -F "access_token=$USER_ACCESS_TOKEN"
  -F object=
    '{"title": "Prawn Curry",
      "image": {
        "url": "fbstaging://graph.facebook.com/staging_resources/MDAxMDE1MTU3NjIyNzExNzYwNA==",
        "user_generated": true
      }
    }'

That call returns an object ID you can use to post an action, as referenced above. Stories created with this object use the image you uploaded to the staging service.

Creating an action

You can also attach images to actions as well as objects. We'll use an example of uploading two user-generated photos with an action.

First, upload two photos:

curl -X POST
  https://graph.facebook.com/me/staging_resources
  -F file=@images/us-at-the-door.jpg
  -F access_token={user-access-token}

curl -X POST \
  https://graph.facebook.com/me/staging_resources
  -F file=@images/band-on-stage.jpg
  -F access_token={user-access-token}

These calls return two URIs:

{"uri":"fbstaging://graph.facebook.com/staging_resources/MDAxMDE1MTU3NjIyNzExNzYwNA=="}
{"uri":"fbstaging://graph.facebook.com/staging_resources/MDAxMDE1MTU3NjIyNzExNzYwNZ=="}

You can then reference the images in an action. In this example, we create a custom action called concertapp:see:

curl -X POST
  https://graph.facebook.com/me/concertapp:see
  -F image[0][url]=fbstaging://graph.facebook.com/staging_resources/MDAxMDE1MTU3NjIyNzExNzYwNA==
  -F image[0][user_generated]=true
  -F image[1][url]=fbstaging://graph.facebook.com/staging_resources/MDAxMDE1MTU3NjIyNzExNzYwNZ==
  -F image[1][user_generated]=true
  -F concert=https://www.concertapp.com/shows/pearljam/20130403
  -F access_token={user-access-token}

Multiple images in objects

It's possible to specify more than one image with an object, much like you can with an og:image with self-hosted objects. This is useful because different types of stories require different resolution images, depending on the device the viewer is using.

In a previous example, we specified a single image:

{
  title: 'Mt. Rainier', 
  type: 'myapp:mountain',
  image: 'http://en.wikipedia.org/wiki/File:Mount_Rainier_5917s.JPG', 
  ...
}

But you can also include more than one image with the following syntax:

{
  title: 'Mt. Rainier', 
  type: 'myapp:mountain',
  image:[
    {url: 'http://en.wikipedia.org/wiki/File:Mount_Rainier_5917s.JPG'},
    {url:'http://en.wikipedia.org/wiki/File:Mount_Rainier_Even_Larger.JPG'}
  ],
  ...
}

Listing objects

It's possible to iterate over the user-owned and app-owned objects that your app has created. The syntax that you use depends on if you want to iterate over user-owned or app-owned objects:

https://graph.facebook.com/app/objects/$OBJECT_TYPE?access_token=$APP_ACCESS_TOKEN

https://graph.facebook.com/me/objects/$OBJECT_TYPE?access_token=$APP_OR_USER_ACCESS_TOKEN

A JSON dictionary is returned that includes a data array for the data and a paging element to give you the ability to page through objects. To learn more about using paging, please see the paging section of the Graph API documentation.

This is an example of app-owned data. User-owned data will be similar.

{
  "data": [
    {
      "id": "534973293215437",
      "url": "https://url.to.your.site/hunt-for-red-october-link",
      "type": "books.book",
      "title": "The Hunt for Red October",
      "image": [
        {
          "url": "http://ecx.images-amazon.com/images/I/314leP6WviL._SL500_AA300_.jpg"
        }
       ],
      "data": {
        "isbn": "425240339"
      },
      "updated_time": "2013-04-12T21:06:15+0000",
      "created_time": "2013-04-12T21:06:15+0000",
      "application": {
        "id": "190052254412546",
        "name": "Your App Name",
        "url": "http://url.to.your.site/app-url/"
      },
      "is_scraped": false
    },
  ],
  "paging": {
    "next": "https://graph.facebook.com/1900522544109786/objects?type=books.book&amp;access_token=<token>&amp;limit=25&amp;offset=25&amp;__after_id=521388851272635"
  }
}

Viewing objects with the object browser

Facebook offers an object browser that lets you browse objects that you've created:

From this object browser you can also click on links and edit existing objects. You can also select on the upper-right-hand side of the browser from your apps to see app-owned objects or people to see user-owned objects. You can also create new objects from a drop down in the upper-right-hand side.