Atlas API - Getting Started

The Atlas API is a restricted platform which may only be accessed by whitelisted Apps. You need to configure your app. You need to apply separately for each app. Atlas API documents are accessible by developers of Atlas API enabled Apps.

This document is intended to get you started with the setup to start using Atlas APIs.


1. Set up a Facebook App

2. Generate Access Token

3. Best Practices

Next Steps

Set up a Facebook App

To being using the Atlas API, you'll need to create a Facebook app:

Clients to configure your Facebook App

To get started, you need to do the following:

  1. Log in to Facebook using the account you'll use to create the app. This must be a real Facebook account.
  2. Go to the App Dashboard and create a new app.
  3. Make sure that Settings -> Contact Email is populated with the 'User Email ID'.
  4. Take the app out of development mode. In the Status & Review section, enable the "Do you want to make this app available to the public" check box.
  5. Note the 'App ID' provided. Pass on the 'App ID' and a 'User Email ID' to your Facebook contact.
Create a New App

Generate Access Token

  1. The 'User Email Id' will be used by FB as the user that the app will operate as in the specific company you want to access.
  2. Your FB contact will notify you on completion of Step 1.
  3. After you have been notified, you can try generating access tokens using the instructions here:

Access tokens are required to access data or make changes to objects via the Atlas API. When API access has been granted to your app, your app is authorized to act on behalf of certain users. You can get the access token of the app's users by making an HTTP GET request.

An example of the request and response:

Request:

https://graph.facebook.com/<API_VERSION>/<APP ID>?access_token=<APP ID>|<CLIENT SECRET>&fields=manageable_users{name,access_token} 

Response:

{
   "manageable_users": {
      "data": [
         {
            "id": "123456789",
            "name": "User Name"
            "access_token": "<ACCESS TOKEN>"
         }
      ],
      "paging": {
         "cursors": {
            "before": "MTQwOTk3NDU5OTI5MjkyOQ==",
            "after": "MTQwOTk3NDU5OTI5MjkyOQ=="
         }
      }
   },
   "id": "<APP ID>"
}

Error:

If App is invalid - hasn't get Atlas permission

{
 "error": {
   "message": "(#100) Tried accessing nonexisting field (manageable_users) on node type (Application)", 
   "type": "OAuthException",
   "code": 100,
    }
}

If no manageable user, response is empty (doesn't contain manageable_users field):

{
  "id": "<app_id>"
}

Then, you can try out your access token by submitting any api request. An example is shown below.

Request:

https://graph.facebook.com/<API_VERSION>/me/companies?access_token=<ACCESS TOKEN> 

Response:

{
   "data": [
      {
         "created_date": "2013-11-04T20:15:11+0000",
         "id": "<COMPANY_ID>",
         "last_modified_date": "2013-11-04T20:15:11+0000",
         "name": "My company",
         "version": "1",
      }
   ]
}

You can use debug_token API to check if token is valid or when is expiration date. Check this doc for details. Note that, you need a valid access token to perform any API request.

GET /debug_token?
  input_token={input-token}&amp;
  access_token={access-token}

Alternatively, use Access Token Tool to debug.

Best Practices

Keep these best practices in mind as you work with the Atlas API.

Paging the response data

For paging the response data in the Graph API, see How-To: Paging with the Graph API and FQL.

Use Batch Requests for improved throughput

Batch requests allow you to make multiple requests to the Graph API using a single http call. For more information on Graph API Batch Requests please review the following:

You can also query for multiple objects by ID using the following trick:

  • https://graph.facebook.com/<API_VERSION>/?ids=[id1,id2]

If you need to query for a specific field,

  • https://graph.facebook.com/<API_VERSION>/?ids=[id1,id2]&fields=field1,field2

Allow people to fix their mistakes by surfacing errors

People make mistakes and try to create ads that are not accepted, error codes will surface the reason an API call failed. It is recommended to surface some form of the error to the user to allow them to fix their ads.

Next steps

Now that you have gotten set up, check out

API GuideReference