About.me API Reference

Introduction

You can use the about.me API to programmatically access the about.me site. With the API, you can:

• Search for user pages
• Get featured pages in the about.me system directories
• Get a specified number of random pages
• Get recommended pages for the specific user
• Get a user’s page information
• Create an about.me page
• Login and logout of an about.me page
• Edit a page
• Upload a new page background
• Add to or get a user’s list of favorites
• Send email
• Promote an about.me page on Facebook or Twitter
• Record a user’s current geographic location
• Connect with friends on Twitter or Facebook
• Compliment a user’s page
• Get notifications for a user
• Get a list of apps or social media services integrated with about.me

For a list of recent changes, refer to Change History.

The about.me Page

Whether you are creating, editing, or viewing a user page, it is helpful to understand the fields displayed on the page. Depending on the API call, you may provide page data in the query string or view page data in the return value. The following graphic shows some of the major fields:

You can also view detailed information about the fonts used, the position of the bio box, and the opacity of the bio box. For example, here are the fields that describe the fonts and colors in the bio box:

The about.me Directories

About.me organizes some pages into directories, which you can access via the API. These directories include:

• Featured: Pages that do a great job highlighting the user
• Inspirational: The most creative about.me pages
• Spotlight: The “best” about.me pages
• Team: The about.me team’s pages
• Founder: The about.me founders’ pages

You can access the above directories with the directory API call.

Note

The random API gives you a random selection of vetted pages. However, these are not actually organized into a directory.

The about.me API

Format of the API

The about.me API uses a REST interface. The general format is a URL specifying the type of object, the action, the specific object to act on, and a query string containing input parameters. The API uses HTTPS GET to view objects and an HTTPS POST to create and modify objects.

Note

Only authenticated API calls require an SSL connection. However, as authentication is optional for some calls, this document uses HTTPS throughout.

The exact format of an API call is:

https://api.about.me/api/<version>/<format>/<obj_type>/<action>/<object>?<query>

where:

• <version> is the API version. The current version is v2.

• <format> is the format for the response. At this time, JavaScript Object Notation (JSON) is the only supported format. Use “json” in lowercase in the API calls.

• <obj_type> defines the type of object to act on. Valid object types are:

  • user – A specific user

  • users – Multiple users (e.g. searching)

  • services – The social media services or apps integrated with about.me

    Note

    This document will refer to all integrated services and applications as “apps.”

• <action> is the required behavior. Examples of valid actions are:

  • edit
  • login
  • view

  Refer to Summary of API Calls for a complete list of actions.

• <object> is the specific object being acted on, often a username. However, this depends on the API call.

• <query> is the query string, which contains any additional parameters. Use standard URL encoding for any special characters.

Note

This document generally uses the <action> as the name of the API call. When an <action> is valid for more than one <obj_type>, this document uses <obj_type>/<action> to distinguish between the two API calls.

Usage Limits

About.me throttles the number of API calls to a few thousand per day per developer key. If you need more, please contact us at platform@about.me.

Summary of API Calls

The following table provides a summary of the API calls with the most common values. The Authentication Required column indicates whether you must call the login API for the user first.

Note

• Each of the API calls begins with the following:

  api/v2/json/

  For example, for the user/view API call, the entire call is:

  https://api.about.me/api/v2/json/user/view/<username>?<query>

• The query string is not included in this table. For full details, click on the link for the action.

URL	Description	Auth Req’d?	HTTPS/HTTP Method
API calls for a specific user
user/register/<identifier>	Request a new developer key	NO	POST
user/view/<username>	Get information about a particular user	NO	GET
user/inbound/<username>	Track a page view for a user	NO	GET
user/login/<username>	Get an access token for tasks requiring authentication	NO	POST
user/logout/<username>	Logout and invalidate previous access token	YES	POST
user/create/<username>	Create a new user page	NO	POST
user/edit/<username>	Edit a user’s page	YES	POST
user/upload/<username>	Upload a new image and set it as the user’s background	YES	POST
user/delete/<username>	Delete a user page	YES	POST
user/directory/<username>	Get a user’s directory of favorites	YES	GET
user/directory/<username>	Add a page to the user’s directory of favorites	YES	POST
user/peoplefeed/<username>	Get recommended pages for a particular user	YES	POST
user/promote/<username>	Promote an about.me page on Facebook or Twitter	YES	POST
user/connect/<username>	Connect with friends on Facebook or Twitter	YES	POST
user/compliment/<username>	Compliment a user’s about.me page	YES	POST
user/notifications/<username>	Get a user’s notifications	YES	POST
user/notifications/settings/view/<username>	Get a user’s notification settings	YES	GET
user/notifications/settings/change/<username>	Change a user’s notification settings	YES	POST
user/checkin/<username>	Register the user’s latitude and longitude (checkin) for location services	YES	POST
user/email/<username>	Send an email to the named person	YES	POST
user/validate/<username>	Validate a user’s authorization token	YES	GET
API calls for a group of users
users/view/directory/<type>	Get featured pages from an about.me directory	NO	GET
users/view/random	Get random pages	NO	GET
users/search	Search for one or more users based on a set of search criteria	NO	GET
API calls for integrated apps
services/add/<app_name>	Add an app or link to a user’s page	YES	POST
services/available	Get a list of apps integrated with about.me	NO	GET
services/edit/<app_name>	Complete the process of editing an app’s configuration	YES	POST

Authentication

Application Authentication

The API uses two types of keys to authenticate your application:

• Developer Key
• Registration Key

Your about.me developer key is available on your about.me page in the Account Settings. The developer key (designated by the keyword client_id) is required for all API calls. The developer key does not expire and is valid unless about.me revokes it. You can provide the developer key in the query string, in the body of a POST, or in the HTTPS Authorization header as:

Authorization:  Basic <developer_key>

Note

In API version 1, the client_id keyword was named the apikey. For backward compatibility, you can still use the apikey query string option to provide the developer key.

If about.me provides a registration key instead of a developer key, you use that key to request the developer key. About.me will tell you whether you have a developer key or a registration key.

If you receive a registration key, use the key with the register API to request a developer key. Registration is a one-time event. This is generally required for applications running on multiple devices, such as mobile applications.

User Authentication

API calls that require user authentication (such as editing pages) must have an access token. To obtain the access token, call the login API. The useful lifetime of the token is based on the application. If the login API returns a value in expires_in, then the access token has a limited lifetime. If no expiration is provided, the access token is long lasting.

The about.me API uses the OAuth 2.0 authorization protocol. API version 2 supports only the “Resource Owner Password Credentials.” This flow uses the login API (using POST) to issue username/password credentials to the API server (called the Authorization Server) in exchange for an access token.

You must use HTTPS for all calls requiring authentication. If an authenticated call uses the GET method, then your application can pass the access token in the query string. For POST methods, pass the access token in the body of the message or in an HTTPS Authorization header, as follows:

Authorization:  OAuth <Access Token>

Status Codes

The API always returns a status code, regardless of outcome. If an error occurs, the return value also includes an error message. The codes include the following values:

• 200 OK: Success.
• 205 Rest Content: The content of a system directory, such as the featured directory, has changed. This is returned by the users/view/directory API.
• 304 Not Modified: There was no new data to return.
• 400 Bad Request: The request was invalid.
• 401 Unauthorized: The developer key or user credentials are invalid or disabled.
• 403 Forbidden: The request is understood, but it has been refused.
• 404 Not Found: The URL requested is invalid or the resource requested does not exist.
• 406 Not Acceptable: The format of the request is invalid. This is returned by the search API.
• 500 Internal Server Error: Something is broken.
• 501 Not Implemented: The requested feature is not implemented or supported.
• 502 Bad Gateway: About.me is down or being upgraded.
• 503 Service Unavailable: The about.me servers are up, but overloaded with requests. Please try again later.

Sample Code

About.me provides an iPhone library that you can use as a model for iOS development. Note that this library is offered “as is,” without any documentation. You can download the library from https://github.com/about-me/ios_about.me_sdk.

Using the about.me API

This section provides an overview of common tasks with the API. When practical, each API call shows the minimum required values. For a complete description of all options and return values, click on the links to the API calls.

Refer to the following sections to get started:

• Authenticating
• Creating and Editing Pages
• Viewing Pages
• Browsing and Searching for Pages
• Tracking Page Views
• Making Connections
• Adding and Viewing Favorites
• Compliments and Notifications

Authenticating

As discussed earlier, there are two levels of authentication:

• Client level
• User level

All API calls require client-level authentication. About.me will provide you a developer key for client-level authentication. In some cases, this will be a one-time key. About.me will let you know if you need to register to acquire a permanent developer key. If so, use an HTTPS POST for the register API call as follows:

https://api.about.me/api/v2/json/user/register/<identifier>

where the <identifier> describes the type of client, such as ipad.

The return value will include “apikey”: <developer_key>, which you use in all future API calls with the client_id query string option.

Many user-level actions require an access token to edit or view specific information in a user’s about.me page. For these, the API calls require an access token. You can obtain the token using an HTTPS POST for the login API call, as follows:

https://api.about.me/api/v2/json/user/login/<username>

The login API requires the following query string options, which would be in the body of the HTTPS POST:

grant_type=password&password=<password>&client_id=<developer_key>

The return value will include “access_token”: <token>, which you can use in subsequent API calls requiring user-level authentication.

You can use the validate API call to check whether the access_token is still valid, with an HTTPS GET:

https://api.about.me/api/v2/json/user/validate/<username>?
client_id=<developer_key>
&token=<access_token>

If the token is still valid, the return value includes status”: 200. If it is not valid, the status code is 401.

To logout or invalidate the token, use an HTTPS POST to the logout API:

https://api.about.me/api/v2/json/user/logout/<username>

The logout API requires the following query string options, which would be in the body of the HTTPS POST:

client_id=<developer_key>&token=<access_token>

If successful, the return value is status”: 200.

Creating and Editing Pages

This section discusses the API calls to create and edit pages. These API calls have many query string options and can return detailed information about a user’s page, so be sure to check the full description for each API call.

The first step to creating a new about.me page begins with the create API call. To create and publish a page, use an HTTPS POST as follows:

https://api.about.me/api/v2/json/user/create/<username>

The following are the minimum required query string options, to be included in the body of the HTTPS POST:

client_id=<developer_key>&email=<email_address>&password=<password>&first_name=<fname>

The return value is “status”: 200 if successful. If the requested username is not available, the status is 304.

If you plan to further edit the about.me page, include login=true in the query string. The return value will include “access_token”: <token>.

Once the page is created, you can use the edit API call to change user information such as the name, email address, biography (bio), and background. For example, to change the first and last name, use an HTTPS POST:

https://api.about.me/api/v2/json/user/edit/<username>

The following query string options would be in the body of the HTTPS POST:

client_id=<developer_key>
&token=<access_token>
&first_name=<new_value>&last_name=<new_value>
&show_profile=true

The show_profile option causes the return value to include details about the user’s page.

Two other options to edit a user’s page include:

• Upload a background image: https://api.about.me/api/v2/json/user/upload/<username>
• Delete a page: https://api.about.me/api/v2/json/user/delete/<username>

Both require an HTTPS POST, with the client_id and token included.

Viewing Pages

To display a page for a given about.me username, you can use the user/view API call. If you do not have the username for the page to be displayed, refer to Browsing and Searching for Pages to get started.

Use an HTTPS GET for the view API call:

https://api.about.me/api/v2/json/user/view/<username>?client_id=<developer_key>

The return value includes the fields on the user’s page, such as the URL, the username, first and last names, background, and bio text. To get the complete page information, including fonts, colors, and apps, include the extended=true option. Refer to the create API call for a complete description of the page information.

Note

By default the view API does not return a page without an individual background image. This applies to both pages using about.me-provided backgrounds and pages without background images. You can override this by including the on_match=true option.

Browsing and Searching for Pages

You have several options for browsing about.me pages. You can search according to specific criteria, browse the pages in the about.me system directories, or browse a random selection of pages. You can also view the recommended pages for a specific user. In general, the results return the same information as the view API, but for one or more pages. In other words, you do not need to call the view API to display any of the returned pages.

Use the search API to search by first name, last name, email address, or geographic location. Searching by geographic location requires that the user be logged in and using a mobile app. With the exception of the first and last name, you cannot combine search criteria in a single call. To search by first and last name, use an HTTPS GET, with at least these query string options:

https://api.about.me/api/v2/json/users/search?
client_id=<developer_key>&first_name=<first>&last_name=<last>

The return value includes the “total_count”, “total_available”, and “result”. The latter is an array of the username, display name, and bio fields. To retrieve more page information, use the extended=true option.

Note

All about.me APIs that return about.me pages support the on_match and extended options. The former includes pages without individual backgrounds, while the latter returns all page information, including fonts and apps.

To display pages in the about.me system directories, use the users/view/directory API. This API requires an HTTPS GET. The following shows the minimum query string options:

https://api.about.me/api/v2/json/users/view/directory/<type>?
client_id=<developer_key>

where the <type> is the directory to display. The about.me Directories section describes the directory types.

The return value includes the “count”, “directory_type”, and “profiles”. The latter is an array of returned pages.

To display a random selection of pages, use the users/view/random API. This API requires an HTTPS GET. The following shows the minimum query string options:

https://api.about.me/api/v2/json/users/view/random?client_id=<developer_key>

The return value includes the “total_count”, “total_available”, and “result”. The latter is an array of returned pages. By default, the random API returns 5 pages. You can adjust the number with the profile_number query string option.

To display recommended pages for a specific user, use the peoplefeed API. This API requires an HTTPS POST:

https://api.about.me/api/v2/json/user/peoplefeed/<username>

The following query string options would be in the body of the HTTPS POST:

client_id=<developer_key>
&token=<access_token>

The return value includes the “total_count”, “total_available”, and “result”. The latter is an array of returned pages, including icons and text indicating why the page was recommended.

Tracking Page Views

The about.me API does not automatically track page views for the user/view API call. You can add query string options for this purpose, as shown in the following example:

https://api.about.me/api/v2/json/user/view/<username>?
client_id=<developer_key>&unique_id=<string>&agent=<requester>&refer=<url>

• <username> identifies the page being viewed.
• unique_id is an identifier for the page view.
• agent identifies the user agent making the request, such as a browser version or mobile platform.
• refer is the referring page, such as https://api.about.me/search.

Alternatively, you can call the inbound API to increment the page view count. Do not use both the query string options and the inbound API call.

API calls that return multiple pages automatically increment the statistics. This includes the following API calls:

• user/directory
• peoplefeed
• search
• users/view/directory
• users/view/random

Although these calls automatically increment the statistics, you can improve the quality of information with the following query string options:

• unique_id is an identifier for the set of returned pages.
• agent identifies the user agent making the request, such as the browser version.
• refer is the referring page, such as https://api.about.me/search.

Making Connections

About.me offers several ways for users to connect with others:

• Checkin geographically, so that the search API can locate users within the same area
• Connect by getting a list of the user’s Facebook or Twitter connections
• Promote the about.me page on Facebook or Twitter

For a geographic checkin, use an HTTPS POST for the checkin API as follows:

https://api.about.me/api/v2/json/user/checkin/<username>

The following query string options would be in the body of the HTTPS POST:

client_id=<developer_key>&token=<access_token>
&long=<longitude>&lat=<latitude>

The return value is “status”: 200 if successful. Refer to the search API to search for nearby about.me users.

To get the user’s Facebook or Twitter connections, use an HTTPS GET for the connect API with the minimum query string options as follows:

https://api.about.me/api/v2/json/user/connect/<username>?
client_id=<developer_key>&token=<access_token>&forum=<app_name>

where the <app_name> is either “facebook” or “twitter”.

The return value includes two sets of data:

• “known_friends” are those connections with about.me pages, including their Facebook or Twitter IDs and their about.me pages.
• “unknown_friends” are those connections without about.me pages, showing only their Facebook or Twitter IDs.

To promote the about.me page on Facebook or Twitter, use an HTTPS POST for the promote API as follows:

https://api.about.me/api/v2/json/user/promote/<username>

The following query string options would be in the body of the HTTPS POST:

client_id=<developer_key>&token=<access_token>&forum=<app_name>

where <app_name> is either “facebook” or “twitter”. The return value is “status”: 200 if successful.

Note

The promote API does not require a previous call to the connect API.

Adding and Viewing Favorites

In addition to the system directories described in The about.me Directories, about.me has individual favorites directories. The user/directory API provides the following:

• An HTTPS POST adds about.me pages to the user’s favorites list.
• An HTTPS GET returns the about.me pages in the user’s favorites list.

To add one or more pages, use an HTTPS POST for the user/directory API call as follows:

https://api.about.me/api/v2/json/user/directory/<username>

The following query string options would be in the body of the HTTPS POST:

client_id=<developer_key>&token=<access_token>&to_add=<fav1, fav2, ... favN>

Note that the <username> is the user whose favorites list is being updated. The to_add option contains a comma-separated list of favorite usernames.

The return value includes the usernames, whether each username was added, and the total favorites added.

To retrieve a user’s favorites list, use an HTTPS GET for the user/directory API call:

https://api.about.me/api/v2/json/user/directory/<username>?
client_id=<developer_key>&token=<access_token>

The return value includes the total number of pages returned, the total available, and an array of pages.

The following API calls also include is_fav in the return value if a returned page is a favorite of the current user:

• https://api.about.me/api/v2/json/user/connect/<username>
• https://api.about.me/api/v2/json/user/view/<username>
• https://api.about.me/api/v2/json/users/view/directory/<type>
• https://api.about.me/api/v2/json/users/view/random
• https://api.about.me/api/v2/json/users/search

Note that the token is required to identify the current user.

Compliments and Notifications

In addition to keeping a Favorites directory, a user can directly compliment another user on his or her page. These compliments include “love your page”, “great background”, “well written”, and “let’s collaborate.” To compliment a page, use an HTTPS POST for the compliment API call as follows:

https://api.about.me/api/v2/json/user/compliment/<username>

The following query string options would be in the body of the HTTPS POST:

client_id=<developer_key>&token=<access_token>&action=<compliment_type>

The <compliment_type> is one of the following: “love”, “greatpic”, “wellwritten”, or “collaborate”.

The return value is “status”: 200 if successful.

When a user gets a compliment, about.me generates a notification to that user. Notifications extend beyond compliments to include a user adding the page to the Favorites directory, tweets and Facebook Likes about the page, and system-generated notifications. To get a user’s notifications, use an HTTP POST for the notifications API call as follows:

https://api.about.me/api/v2/json/user/notifications/<username>

The following query string options would be in the body of the HTTPS POST:

client_id=<developer_key>&token=<access_token>&action=<compliment_type>

The return value includes the “total_count”, “total_new”, and “result”. The latter is an array of notifications, including the reason for the notification and, if applicable, the person responsible for it.

The user can receive different types of notifications on the dashboard, via email, or both. You can view and change the user’s notifications with the following API calls:

• https://api.about.me/api/v2/json/user/notifications/settings/view/<username>
• https://api.about.me/api/v2/json/user/notifications/settings/change/<username>

API Details

This section lists the API calls alphabetically by their <obj_type>, followed by the <action>. The <obj_type> includes:

• services
• user
• users

Services Calls

This section includes API calls for the following actions:

• add
• available
• edit

Add

Purpose: Add an app or link to a user’s page.

Note

The about.me SDK requires this call to complete the Add App process. Refer to the SDK Developer’s Guide for more information on adding an app.

URL:

https://api.about.me/api/v2/json/services/add/<app_name>

<app_name> is the platform name of the app to add to the user’s page. The platform name is a unique alphanumeric identifier in the app’s metadata. If adding a link, omit the <app_name>.

Method: POST

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me. See Note below.
token		Yes	Access token issued by the login API. See Note below.
display_name		No	A display name for this user’s instance of the app. If omitted, about.me uses the value in the app’s metadata.
app_user_id		No	A unique user ID for the user. If omitted, about.me cannot guarantee accurate usage statistics for the app on the user’s about.me dashboard.
service_url		Yes	The full URL to display the user’s information in the app.
site_url		No	The full URL to display the user’s information on the app’s website.
config_url		No	The full URL for the user to edit the app’s configuration settings.
remove_url		No	The full URL for about.me to call if the user deletes the app.
is_link	false	No	If set to true, the API adds a link instead of the app’s icon.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Note

You can replace client_id and token with api_args if you are using the about.me SDK. The about.me SDK appends api_args to the app’s configuration URL.

Return:

• “status”: Status code for the call; 200 if successful.
• “error_message”: Reason call failed if status is not 200.

See Also:

services/edit

Example:

https://api.about.me/api/v2/json/services/add/myexampleapp

POST data:

api_args=01234567890a11012b0ee1d2c3b456fab78901aa,9876543.2101235678.9¬
1d2e34567890ce98bf7aed65f010c432a100c23e45678
&service_url=http%3A%2F%2Fexample.com%2Fmyexampleapp%2Freg
&site_url=http%3A%2F%2Fexample.com%2Fusername
&config_url=http%3A%2F%2Fexample.com%2Fmyexampleapp%2Fconfig
&remove_url=http%3A%2F%2Fexample.com%2Fmyexampleapp%2Fremove
&display_name=My%20Example%20App&app_user_id=id1234

Returns:

{"status": 200}

Available

Purpose: Get a list of apps integrated with about.me.

Note

To find the apps a particular user has, use the user/view API.

URL:

https://api.about.me/api/v2/json/services/available

Method: GET

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Return:

• “status”: Status code for the call; 200 if successful.
• “websites”: An array of the available apps on about.me, including the following fields:
  • “platform”: The name of the app (for example, facebook, twitter).
  • “icon42_url”: The URL to the 42x42 icon.
  • “icon84_url”: The URL to the 84x84 icon.
• “error_message”: Reason call failed if status is not 200.

Example:

https://api.about.me/api/v2/json/services/available/?
client_id=01234567890a12012b8ee3d4c0b567fab89987aa

Returns:

{
  "status": 200,
  "websites": [
  {
    "platform": "facebook",
    "icon84_url": "http://about.me/.../facebook-84x84.png",
    "icon42_url": "http://about.me/.../facebook-42x42.png"
  },
  {
    "platform": "twitter",
    "icon84_url": "http://about.me/.../twitter-84x84.png",
    "icon42_url": "http://about.me/.../twitter-42x42.png"
  }
  ]
}

Note

For brevity, the above example only shows a partial list of the returned apps.

Edit

Purpose: Edits an app’s configuration on a user’s page.

Note

The about.me SDK requires this call to complete the Edit App process. Refer to the SDK Developer’s Guide for more information on editing an app’s configuration.

URL:

https://api.about.me/api/v2/json/services/edit/<app_name>

<app_name> is the platform name of the app to edit on the user’s page. The platform name is a unique alphanumeric identifier in the app’s metadata.

Method: POST

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me. See Note below.
token		Yes	Access token issued by the login API. See Note below.
display_name		No	A display name for this user’s instance of the app. If omitted, about.me uses the value in the app’s metadata.
service_url		No	The full URL to display the user’s information in the app.
site_url		No	The full URL to display the user’s information on the app’s website.
config_url		No	The full URL for the user to edit the app’s configuration settings.
remove_url		No	The full URL for about.me to call if the user deletes the app.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Note

You can replace client_id and token with api_args if you are using the about.me SDK. The about.me SDK appends api_args to the app’s configuration URL.

Return:

• “status”: Status code for the call; 200 if successful.
• “error_message”: Reason call failed if status is not 200.

See Also:

add

Example:

https://api.about.me/api/v2/json/services/edit/myexampleapp

POST data:

api_args=01234567890a11012b0ee1d2c3b456fab78901aa,9876543.2101235678.9¬
1d2e34567890ce98bf7aed65f010c432a100c23e45678
&service_url=http%3A%2F%2Fexample.com%2Fmyexampleapp%2Freg
&site_url=http%3A%2F%2Fexample.com%2Fusername
&config_url=http%3A%2F%2Fexample.com%2Fmyexampleapp%2Fconfig
&remove_url=http%3A%2F%2Fexample.com%2Fmyexampleapp%2Fremove
&display_name=My%20Example%20App

Returns:

{"status": 200}

User Calls

This section includes API calls for the following actions:

• checkin
• compliment
• connect
• create
• delete
• directory
• edit
• email
• inbound
• login
• logout
• notifications
• notifications/settings
• peoplefeed
• promote
• register
• upload
• validate
• view

Checkin

Purpose: Record the mobile user’s current geographical location. This call stores the user’s location so that the user page is available for a search by location.

URL:

https://api.about.me/api/v2/json/user/checkin/<username>

<username> is the username for the user checking in.

Method: POST

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
token		Yes	Access token issued by the login API.
lat		Yes	The user’s latitude.
long		Yes	The user’s longitude.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Return:

• “status”: Status code for the call; 200 if successful.
• “error_message”: Reason call failed if status is not 200.

See Also:

search by location

Example:

https://api.about.me/api/v2/json/user/checkin/testaccount

POST data:

token=123.4567890987.65.4e321012345678f9123c66a4567890ae12fe3450d6789
&client_id=01234567890a12012b8ee3d4c0b567fab89987aa
&lat=37.4789171794&long=-122.22071170807

Returns:

{"status": 200}

Compliment

Purpose: Generate a compliment for an about.me page. The compliments include:

• Love your page
• Great background
• Well written
• Let’s collaborate

The user generating the compliment must be authenticated (logged in).

Note

A user cannot compliment his or herself. The API will return status code 403.

URL:

https://api.about.me/api/v2/json/user/checkin/<username>

<username> is the user to be complimented.

Method: POST

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
token		Yes	Access token issued by the login API.
action		Yes	The type of compliment: love, greatpic, wellwritten, collaborate.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Return:

• “status”: Status code for the call; 200 if successful.
• “error_message”: Reason call failed if status is not 200.

See Also:

user/directory, notifications

Example:

https://api.about.me/api/v2/json/user/compliment/testaccount

POST data:

token=123.4567890987.65.4e321012345678f9123c66a4567890ae12fe3450d6789
&client_id=01234567890a12012b8ee3d4c0b567fab89987aa
&action=greatpic

Returns:

{"status": 200}

Connect

Purpose: Get a list of the authenticated user’s Facebook or Twitter connections. The API returns two lists:

• Connections that have about.me pages
• Connections that do not have about.me pages

URL:

https://api.about.me/api/v2/json/user/connect/<username>

<username> is the username whose connections are requested.

Method: GET

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
token		Yes	Access token issued by the login API.
forum		Yes	The app to query for connections (facebook, twitter).
is_fav_of	true	No	By default, the return value indicates whether a returned page is in the user’s favorites list.
count	20	No	For pagination, indicates the maximum number of records to return.
offset	0	No	For pagination, indicates the starting record to return.
strip_html	true	No	Strips or includes HTML from the returned bio.
extended	false	No	If true, API returns all details about the user’s page, such a font details and position of the bio box. See Note below.
on_match	false	No	If false, API does not return information for pages without individual backgrounds. If true, returns information regardless of background image.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Note

The extended option does not override the on_match setting; it only provides additional information if the API returns a page.

Return:

• “status”: Status code for the call; 200 if successful.

• “result”: List of connections in the following categories:

  • “known_friends”: Connections with about.me pages as follows:

    • “total_count”: Number of pages returned.

    • “total_available”: Total number of connections.

    • “profiles”: Array of about.me pages, including the Facebook or Twitter IDs.

      Refer to the create API for details.

  • “unknown_friends”: Connections without about.me pages as follows:

    • “total_count”: Number of connections returned.
    • “total_available”: Total number of connections.
    • “profiles”: Facebook or Twitter IDs.

• “error_message”: Reason call failed if status is not 200.

See Also:

Promote

Example:

https://api.about.me/api/v2/json/user/connect/testaccount?
client_id=01234567890a12012b8ee3d4c0b567fab89987aa
&token=123.4567890987.65.4e321012345678f9123c66a4567890ae12fe3450d6789
&forum=facebook

Returns:

{
  "status": 200,
  "result": {
    "known_friends":
    {
      "total_count": 1,
      "total_available": 3,
      "profiles": [{
        "profile": "http://about.me/testing",
        "user_name": "testing",
        "first_name": "Testing",
        "last_name": " Smith",
        "display_name": "Testing Smith",
        "header": "instantiating ideas...",
        "bio": "adventure seeker",
        "background": "http://...//background/testing_1288732523_81.jpg",
        "mobile_background": "",
        "email_public": true,
        "email_searchable": true,
        "avatar": "",
        "img_base_url": "http://.../thumbnail",
        "thumbnail_291x187": "http://.../thumbnail/291x187/testing.jpg",
        "thumbnail1": "http://.../thumbnail/803x408/testing.jpg",
        "thumbnail2": "http://.../thumbnail/260x176/testing.jpg",
        "thumbnail3": "http://.../thumbnail/198x134/testing.jpg",
        "thumbnail4": "http://.../thumbnail/161x109/testing.jpg",
        "facebook_uid": "12345",
        "is_fav": true
      }]
    },
    "unknown_friends": {
      "total_count": 2,
      "total_available": 3,
      "profiles": ["88888", "99999"]
    }
  }
}

Create

Purpose: Create an about.me page.

URL:

https://api.about.me/api/v2/json/user/create/<username>``

<username> is the requested username. Maximum length is 32 characters.

Note

If the requested username is not available, the create API returns status code 304.

Method: POST

Query String Options:

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
email		Yes	Email address to associate with this account. Must be a valid email address and from a valid domain. See Note below.
password		Yes	The password to set on the account.
first_name		Yes	First name of the user, up to 32 characters.
last_name		No	Last name of the user, up to 32 characters.
headline		No	The headline to be set, up to 100 characters.
bio		No	The biography to be set, up to 2500 characters. See Note below.
tags		No	Comma-delimited list of tags for the account.
email_searchable	true	No	Indicates whether the user can be searched by email.
email_me	true	No	Indicates whether the user accepts email from other users.
login	false	No	If true, API returns an access token.
strip_html	true	No	Strips or includes HTML from the returned bio.
extended	false	No	If true, API returns all details about the user’s page, such a font details and position of the bio box. See Note below.
on_match	false	No	If false, API does not return information for pages without individual backgrounds. If true, returns information regardless of background image.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Note

If the email option’s value is already used by another about.me account, the API returns a 304 error.

The bio option may include the following HTML tags: ‘rev’, ‘prompt’, ‘color’, ‘colspan’, ‘accesskey’, ‘usemap’, ‘cols’, ‘accept’, ‘datetime’, ‘char’, ‘accept-charset’, ‘shape’, ‘href’, ‘hreflang’, ‘selected’, ‘frame’, ‘type’, ‘alt’, ‘nowrap’, ‘border’, ‘id’, ‘axis’, ‘compact’, ‘rows’, ‘checked’, ‘for’, ‘start’, ‘hspace’, ‘charset’, ‘ismap’, ‘label’, ‘target’, ‘bgcolor’, ‘readonly’, ‘rel’, ‘valign’, ‘scope’, ‘size’, ‘cellspacing’, ‘cite’, ‘media’, ‘multiple’, ‘src’, ‘rules’, ‘nohref’, ‘action’, ‘rowspan’, ‘abbr’, ‘span’, ‘method’, ‘height’, ‘class’, ‘enctype’, ‘lang’, ‘disabled’, ‘name’, ‘charoff’, ‘clear’, ‘summary’, ‘value’, ‘longdesc’, ‘headers’, ‘vspace’, ‘noshade’, ‘coords’, ‘width’, ‘maxlength’, ‘cellpadding’, ‘title’, ‘align’, ‘dir’, ‘tabindex’, ‘style’, ‘a’

The bio option may include the following HTML styles: ‘text-decoration: underline’, ‘text-decoration: line-through’

The extended option does not override the on_match setting; it only provides additional information if the API returns a page.

Return:

• “status”: Status code for the call; 200 if successful.

• “access_token”: Access token if login=true is provided.

• “error_message”: Reason call failed if status is not 200.

• “user”: The following basic page fields:

  • “profile”: About.me page URL.

  • “user_name”: About.me username.

  • “first_name”: First name of the user.

  • “last_name”: Last name of the user.

  • “display_name”: First and last name values concatenated.

  • “header”: User’s headline text.

  • “bio”: User’s biographical information.

  • “background”: The URL to the background.

  • “mobile_background”: The URL to the background for use by a mobile application. The image is 80% of the original image’s resolution.

  • “email_address”: The email address of the user. This field is only returned for when the page is for an authenticated user (for example, create or login) or when the user already has the page owner’s email address (search by email).

  • “email_searchable”: Indicates that the user’s email address may be searched for.

  • “email_public”: Indicates that the user accepts email from other users.

  • “tags”: A list of the user’s search tags (if extended=true).

  • “avatar”: A small image that displays next to the user’s biography.

  • “img_base_url”: Path to thumbnails.

  • “thumbnail_291x187”: A 291x187 thumbnail of the full page, created by about.me when the user uploads a background or edits a page.

  • “thumbnail1”: An 803x408 thumbnail of the full page.

  • “thumbnail2”: A 260x176 thumbnail of the full page.

  • “thumbnail3”: A 198x134 thumbnail of the full page.

  • “thumbnail4”: A 161x109 thumbnail of the full page.

    Note

    For API versions 2 and above, if a thumbnail is not found, then a default image is supplied.

If you specify extended=true, the “user” section also contains “display_details”, “websites”, and “available_backgrounds” sections, each with their own set of fields:

• “display_details”: Contains details concerning how to display the page:

  • “profile_color”: Background color for the bio box. The visibility of the profile_color depends on the profile_opacity setting.
  • “name_color”: Color of the user’s name.
  • “heading_color”: Color of the headline.
  • “bio_color”: Color of the bio text.
  • “links_color”: Color of the user’s links to websites that are not integrated with about.me. This does not affect hyperlinks within the biographical text.
  • “font_name”: Font for the user’s name.
  • “font_heading”: Font for the headline text.
  • “font_bio”: Font for the biographical text.
  • “font_findme”: Font for the user’s links to websites.
  • “font_name_size”: Font size for the name.
  • “font_heading_size”: Font size for the headline.
  • “font_bio_size”: Font size for the biographical text.
  • “font_findme_size”: Font size for user’s links to websites.
  • “text_top”: Top position of the bio box.
  • “text_left”: Left position of the bio box, relative to the center of the page.
  • “profile_opacity”: Opacity of the bio box over the background.
  • “profile_width”: Width of the bio box, which is based on the length of the user’s name and headline. The about.me page sets the box’s height based on the content.
  • “background_repeat”: Indicates whether the background image is centered, scaled, or tiled.
  • “background_color”: Color of the background if an image does not fill the screen.
  • “background_width”: Width of the background.
  • “background_height”: Height of the background.

  For an illustration of these settings, refer to The about.me Page.

• “websites”: Contains the apps and website links on the user’s about.me page:

  • “display_name”: Name of the app.
  • name of the app: The name and URL of the app.
  • “service_url”: The URL of the app. This will be phased out in the future.
  • “modal_url”: The URL to display the user’s information in the app.
  • “site_url”: The URL to display the user’s page on the app’s website, such as twitter.com/tester.
  • “platform”: The name of the app (for example, facebook, twitter, link). Only available with version 2 (v2).
  • “icon_url”: The URL to the 32x32 icon if the platform is a link.
  • “icon42_url”: The URL to the 42x42 icon.
  • “icon84_url”: The URL to the 84x84 icon.

• “available_backgrounds”: Contains the mobile, saved, and gallery backgrounds:

  • “mobile”: Array of mobile backgrounds including the image’s display name, artist, artist’s URL, image name, image URL, and thumbnail.
  • “saved”: Array of uploaded backgrounds including the image’s display name, artist, artist’s URL, image name, image URL, and thumbnail. For uploaded images, only the last two have values. Note that the saved images array is empty when a page is created.
  • “gallery”: Array of about.me gallery images, including the image’s display name, artist, artist’s URL, image name, image URL, and thumbnail.

See Also:

user/edit, upload

Example:

https://api.about.me/v2/json/user/create/johnjames1234

POST data:

client_id=01234567890a12012b8ee3d4c0b567fab89987aa&password=test123
&email=johnjames1234%40example.com&first_name=test&login=true&extended=true

Returns:

{
  "status": 200,
  "access_token": "123.4567890987.65.4e321012345678f9123c66a4567890ae12fe34",
  "user": {
    "profile": "http://about.me/johnjames1234",
    "user_name": "johnjames1234",
    "first_name": "test",
    "last_name": null,
    "display_name": "test ",
    "header": "",
    "bio": "",
    "background": "",
    "mobile_background": "",
    "email_address": "johnjames1234@example.com",
    "email_searchable": true,
    "email_public": true,
    "tags": [],
    "avatar": "",
    "img_base_url": "http://about.me/.../thumbnail",
    "thumbnail_291x187":
    "http://about.me/.../thumbnailnotavailable-260x176.png",
    "thumbnail1": "http://about.me/.../thumbnailnotavailable-260x176.png",
    "thumbnail2": "http://about.me/.../thumbnailnotavailable-260x176.png",
    "thumbnail3": "http://about.me/.../thumbnailnotavailable-260x176.png",
    "thumbnail4": "http://about.me/.../thumbnailnotavailable-260x176.png",
    "display_details": {
      "profile_color": "000000",
      "name_color": "FFF",
      "heading_color": "FFF",
      "bio_color": "FFF",
      "links_color": "2B82AD",
      "font_name": "proxima-nova-1,proxima-nova-2",
      "font_heading": "proxima-nova-1,proxima-nova-2",
      "font_bio": "proxima-nova-1,proxima-nova-2",
      "font_findme": "proxima-nova-1,proxima-nova-2",
      "font_name_size": 80,
      "font_heading_size": 22,
      "font_bio_size": 14,
      "font_findme_size": 14,
      "text_top": 100,
      "text_left": -590,
      "profile_opacity": 0,
      "profile_width": 450,
      "background_repeat": "center",
      "background_color": "000",
      "background_width": 1680,
      "background_height": 1050
    },
    "websites": {
    },
    "available_backgrounds":
    {
      "mobile": [{
        "name": "sky",
        "artist": "",
        "image_name": "",
        "image_url": "http://.../mobile/1024/sky.png",
        "artist_url": "",
        "thumb_url": "http://.../mobile/570/sky.png"
      }],
      "saved": [],
      "gallery": [{
        "name": "Bear-Hair",
        "artist": "Eva Hjelte",
        "image_name": "bear-ears.jpg",
        "image_url": "",
        "artist_url": "http://www.aolartists.com/profiles/eva-hjelte",
        "thumb_url": "http://about.me/.../bear-ears_thumb.jpg"
      }]
    }
  }
}

Note

For brevity, the above example only shows a partial list of the available backgrounds.

Delete

Purpose: Delete the authenticated user’s page. About.me deletes the page and username immediately.

URL:

https://api.about.me/api/v2/json/user/delete/<username>

<username> is the username for the about.me page to delete.

Method: POST

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
token		Yes	Access token issued by the login API.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Return:

• “status”: Status code for the call; 200 if successful.
• “error_message”: Reason call failed if status is not 200.

Example:

https://api.about.me/api/v2/json/user/delete/testaccount

POST data:

client_id=01234567890a12012b8ee3d4c0b567fab89987aa
&token=123.4567890987.65.4e321012345678f9123c66a4567890ae12fe3450d6789

Returns:

{"status": 200}

Directory

Purpose: Access the authenticated user’s directory of favorites, either getting the directory contents or updating the directory.

URL:

https://api.about.me/api/v2/json/user/directory/<username>

<username> is the username whose directory is to be accessed.

Method: GET (to view)/POST (to update)

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
token		Yes	Access token issued by the login API.
unique_id		No	A free-form string to uniquely identify the set of returned pages. See Note below.
agent		No	The user agent making the request, such as the browser version or mobile platform.
refer		No	The referring page, such as https://api.about.me/search.
to_add		Yes for POST	Comma-delimited list of one or more usernames to add to the directory.
count		No	For pagination, indicates the maximum number of records to return.
offset	0	No	For pagination, indicates the starting record to return.
strip_html	true	No	Strips or includes HTML from the returned bio.
extended	false	No	If true, API returns all details about the user’s page, such a font details and position of the bio box. See Note below.
on_match	false	No	If false, API does not return information for pages without individual backgrounds. If true, returns information regardless of background image.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Note

The unique_id, agent, and refer options provide more detailed statistics for page views. These options are ignored when the API call is an HTTPS POST to update the user’s directory.

The extended option does not override the on_match setting; it only provides additional information if the API returns a page.

Return:

For GET operations (to_add omitted):

• “status”: Status code for the call; 200 if successful.
• “total_count”: Number of records returned.
• “total_available”: Number of records in user’s favorites directory.
• “result”: Array of pages found. Refer to the create API for details.
• “error_message”: Reason call failed if status is not 200.

For POST operations (to_add provided):

• “status”: Status code for the call; 200 if successful.

• “total_count”: Number of records added.

• “result”: Array for each about.me page to be added:

  • “username”: About.me page to add to directory.
  • “status”: True or false indicating if page added.
  • “message”: If status = false, reason the add failed.

• error_message”: Reason call failed if status is not 200.

Example (for GET):

https://api.about.me/api/v2/json/user/directory/testaccount?
client_id=01234567890a12012b8ee3d4c0b567fab89987aa
&token=123.4567890987.65.4e321012345678f9123c66a4567890ae12fe3450d6789

Returns:

{
  "status": 200,
  "total_count": 2,
  "total_available": 2,
  "result":
  [{
    "status": 200,
    "user_name": "favorite02",
    "first_name": "Favorite",
    "last_name": "02",
    "bio": "",
    "avatar": "",
    "thumbnail": "http://about.me/.../260x176/favorite02.jpg",
    "thumb1": "http://about.me/.../803x408/favorite02.jpg",
    "thumb2": "http://about.me/.../260x176/favorite02.jpg",
    "thumb3": "http://about.me/.../198x134/favorite02.jpg",
    "thumb4": "http://about.me/.../161x109/favorite02.jpg",
    "background": "http://about.me/.../miguel_gonzalez_passing_by.jpg",
    "mobile_background": ""
  },
  {
    "status": 200,
    "user_name": "favo03",
    "first_name": "Fav",
    "last_name": "03",
    "bio": "",
    "avatar": "",
    "thumbnail": "http://about.me/.../260x176/fav03.jpg",
    "thumb1": "http://about.me/.../803x408/fav03.jpg",
    "thumb2": "http://about.me/.../260x176/fav03.jpg",
    "thumb3": "http://about.me/.../198x134/fav03.jpg"
    "thumb4": "http://about.me/.../161x109/fav03.jpg",
    "background": "http://about.me/.../birth_of_the_giant_turtle.jpg",
    "mobile_background": ""
  }]
}

Edit

Purpose: Modify the user’s page information. This can affect data displayed on the page or user settings, such as whether the page is searchable by email address.

URL:

https://api.about.me/api/v2/json/user/edit/<username>

<username> is the username of the page to edit.

Method: POST

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
token		Yes	Access token issued by the login API.
email_address		No	Replacement email address. Must be a valid email address and from a valid domain.
first_name		No	Replacement first name, up to 32 characters.
last_name		No	Replacement last name, up to 32 characters.
headline		No	Replacement headline text, up to 100 characters.
bio		No	Replacement bio text, up to 2500 characters. See Note below.
background		No	Replacement background from gallery, mobile backgrounds, or previously uploaded images. See Note below.
tags		No	Comma-delimited list of replacement tags.
email_searchable		No	Changes whether the user can be searched by email.
email_me		No	Changes whether the user accepts email from other users.
strip_html	true	No	Strips or includes HTML from the returned bio.
extended	false	No	If true, API returns all details about the user’s page, such a font details and position of the bio box. See Note below.
on_match	false	No	If false, API does not return information for pages without individual backgrounds. If true, returns information regardless of background image.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Note

The bio option may include the following HTML tags: ‘rev’, ‘prompt’, ‘color’, ‘colspan’, ‘accesskey’, ‘usemap’, ‘cols’, ‘accept’, ‘datetime’, ‘char’, ‘accept-charset’, ‘shape’, ‘href’, ‘hreflang’, ‘selected’, ‘frame’, ‘type’, ‘alt’, ‘nowrap’, ‘border’, ‘id’, ‘axis’, ‘compact’, ‘rows’, ‘checked’, ‘for’, ‘start’, ‘hspace’, ‘charset’, ‘ismap’, ‘label’, ‘target’, ‘bgcolor’, ‘readonly’, ‘rel’, ‘valign’, ‘scope’, ‘size’, ‘cellspacing’, ‘cite’, ‘media’, ‘multiple’, ‘src’, ‘rules’, ‘nohref’, ‘action’, ‘rowspan’, ‘abbr’, ‘span’, ‘method’, ‘height’, ‘class’, ‘enctype’, ‘lang’, ‘disabled’, ‘name’, ‘charoff’, ‘clear’, ‘summary’, ‘value’, ‘longdesc’, ‘headers’, ‘vspace’, ‘noshade’, ‘coords’, ‘width’, ‘maxlength’, ‘cellpadding’, ‘title’, ‘align’, ‘dir’, ‘tabindex’, ‘style’, ‘a’

The bio option may include the following HTML styles: ‘text-decoration: underline’, ‘text-decoration: line-through’

For the background option, to set a mobile or uploaded background, provide the image_url value returned by the create or user/view API. To set a gallery background, provide the image_name value (optional).

The extended option does not override the on_match setting; it only provides additional information if the API returns a page.

Return:

• “status”: Status code for the call; 200 if successful.
• “user”: The user page. Refer to the create API for details.
• “error_message”: Reason call failed if status is not 200.

See Also:

upload

Example:

https://api.about.me/api/v2/json/user/edit/testaccount

POST data:

client_id=01234567890a12012b8ee3d4c0b567fab89987aa
&token=123.4567890987.65.4e321012345678f9123c66a4567890ae12fe3450d6789
&headline=my+headline&first_name=test22&last_name=tester
&email_me=on

Returns:

{
  "status": 200,
  "user": {
    "profile": "http://about.me/testaccount",
    "user_name": "testaccount",
    "first_name": "test22",
    "last_name": "tester",
    "display_name": "test22 tester",
    "header": "my headline",
    "bio": "test this is one!!!!",
    "tags": ["foosball", "hiking"],
    "avatar": "http://about.me/.../testaccount_1325746595_83.jpg"
    "background": "http://about.me/.../testaccount_1326415784_79.jpg",
    "mobile_background": "",
    "email_address": "testaccount@example.com",
    "email_searchable": true,
    "email_public": false,
    "img_base_url": "http://about.me/.../thumbnail",
    "thumbnail_291x187": "http://about.me/.../291x187/testaccount.jpg",
    "thumbnail1": "http://about.me/.../803x408/testaccount.jpg",
    "thumbnail2": "http://about.me/.../260x176/testaccount.jpg",
    "thumbnail3": "http://about.me/.../198x134/testaccount.jpg",
    "thumbnail4": "http://about.me/.../161x109/testaccount.jpg"
  }
}

Email

Purpose: Send an email to a user who has enabled “email me” in the account settings. The sending user must be authenticated (logged in). If the user does not accept emails, the API returns status code 400 and does not send the message.

Note

About.me does not show the recipient’s email address to the sender.

URL:

https://api.about.me/api/v2/json/user/email/<username>

<username> is the user to receive the email.

Method: POST

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
token		Yes	Access token issued by the login API.
reply_to		No	Provide a different email address from the sending user’s registered email address.
message		Yes	The message to be sent.
subject		Yes	Subject of the email message.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Return:

• “status”: Status code for the call; 200 if successful.
• “error_message”: Reason call failed if status is not 200.

Example:

https://api.about.me/api/v2/json/user/email/testaccount

POST data:

client_id=01234567890a12012b8ee3d4c0b567fab89987aa
&token=123.4567890987.65.4e321012345678f9123c66a4567890ae12fe3450d6789
&message=how%20are%20things%20going&subject=Hi%20There

Returns:

{"status": 200}

Inbound

Purpose: Track page views for the given user. This updates the metrics in the user’s dashboard.

Note

Do not use the inbound API call if you provide the following query string options with the user/view API call: unique_id, agent, and refer.

URL:

https://api.about.me/api/v2/json/user/inbound/<username>

<username> is the user whose page is being viewed.

Method: GET

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
unique_id		Yes	A free-form string to uniquely identify this page view.
agent		Yes	The user agent making the request, such as the browser version or mobile platform.
refer		No	The referring page, such as http://api.about.me/search.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Return:

• “status”: Status code for the call; 200 if successful.

See Also:

user/view

Example:

https://api.about.me/api/v2/json/user/inbound/testaccount?
client_id=01234567890a12012b8ee3d4c0b567fab89987aa
&unique_id=XYZ1330108986.45&agent=IOS5

Returns:

{"status": 200}

Login

Purpose: Get an access token to use in API calls requiring user authentication. The access token may become invalid for one of the following reasons:

• The token has expired.
• The user changed their password.
• The user logged out.

URL:

https://api.about.me/api/v2/json/user/login/<username>

<username> is the username to login with. This can also be the email address.

Method: POST

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
grant_type		Yes	Must be set to ‘password’.
scope	general	No	Scope of the access token requested: mobile or general.
password		Yes	The password for the user.
show_profile	false	No	If true, returns the user’s page information on successful login.
strip_html	true	No	Strips or includes HTML from the returned bio.
extended	false	No	If true, API returns all details about the user’s page, such a font details and position of the bio box.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Return:

• “status”: Status code for the call; 200 if successful.
• “access_token”: Token to use in API calls requiring user authentication.
• “expires_in”: Number of seconds until the token expires. If not provided, the token does not expire.
• “user_info”: The user page if show_profile is set. Refer to the create API for details.
• “error_message”: Reason call failed if status is not 200.

See Also:

logout, validate

Example:

https://api.about.me/api/v2/json/user/login/testaccount

POST data:

client_id=abcDqEFGrH0IzJKylmnBGoP2qr2ST7WvxySGX0SaBC4
&grant_type=password&password=ttt1234&show_profile=true

Returns:

{
  "access_token": "123.4567890987.65.4e321012345678f9123c66a4567890ae12fe34",
  "status": 200,
  "expires_in": 1800,
  "user_info": {
    "profile": "http://about.me/testaccount",
    "user_name": "testaccount",
    "first_name": "test22",
    "last_name": "tester",
    "display_name": "test22 tester",
    "header": "Another test of headline",
    "bio": "test this is one!!!!",
    "tags": ["foosball", "hiking"],
    "background": "http://about.me/.../testaccount_1326415784_79.jpg",
    "mobile_background": "",
    "email_address": "testaccount@example.com",
    "email_searchable": true,
    "email_public": true,
    "avatar": "http://about.me/.../testaccount_1325746595_83.jpg"
    "img_base_url": "http://about.me/.../thumbnail",
    "thumbnail_291x187": "http://about.me/.../291x187/testaccount.jpg",
    "thumbnail1": "http://about.me/.../803x408/testaccount.jpg",
    "thumbnail2": "http://about.me/.../260x176/testaccount.jpg",
    "thumbnail3": "http://about.me/.../198x134/testaccount.jpg",
    "thumbnail4": "http://about.me/.../161x109/testaccount.jpg"
  }
}

Logout

Purpose: Invalidate an access token.

URL:

https://api.about.me/api/v2/json/user/logout/<username>

<username> is the username to logout. This can also be the email address.

Method: POST

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
token		Yes	Access token issued by the login API.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Return:

• “status”: Status code for the call; 200 if successful.
• “error_message”: Reason call failed if status is not 200.

See Also:

login

Example:

https://api.about.me/api/v2/json/user/logout/testaccount

POST data:

client_id=abcDqEFGrH0IzJKylmnBGoP2qr2ST7WvxySGX0SaBC4
&token=123.4567890987.65.4e321012345678f9123c66a4567890ae12fe3450d6789

Returns:

{"status": 200}

Notifications

Purpose: Get notifications about activity regarding the user’s page.

URL:

https://api.about.me/api/v2/json/user/notifications/<username>

<username> is the user whose notifications are being retrieved.

Method: POST

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
token		Yes	Access token issued by the login API.
mark_as_read	false	No	If true, marks returned notifications as read.
count	10	No	For pagination, indicates the maximum number of records to return.
offset	0	No	For pagination, indicates the starting record to return.
count_only	false	No	If true, returns the number of unread notifications, but no actual notifications.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Return:

• “status”: Status code for the call; 200 if successful.

• “total_count”: Number of returned notifications.

• “total_new”: Number of unread notifications.

• “result”: Array of notifications, including the following fields:

  • “action”: Type of notification, such as a compliment or being added to someone’s Favorites directory.
  • “text”: Reason for the notification, in plain text.
  • “html_text”: Reason for the notification, in HTML.
  • “icon”: Icon representing the action.
  • “icon2x”: Icon representing the action, for retina displays.
  • “source”: The source of the notification, which is “aboutme”.
  • “timestamp”: When the notification was generated.
  • “emailed”: Indicates whether the notification was also sent via email.
  • “unread”: Indicates whether the notification has been read.
  • “id”: Unique ID for the notification.
  • “actor”: Username of the person generating the notification.
  • “actor_display_name”: Name of the person generating the notification.
  • “thumbnail2”: Thumbnail for the person generating the notification.

  Note

  For system-generated notifications, the actor, actor_display_name, and thumbnail2 are omitted.

• “error_message”: Reason call failed if status is not 200.

See Also:

notifications/settings, user/directory, compliment

Example:

https://api.about.me/api/v2/json/user/notifications/testaccount

POST data:

token=123.4567890987.65.4e321012345678f9123c66a4567890ae12fe3450d6789
&client_id=01234567890a12012b8ee3d4c0b567fab89987aa

Returns:

{
  "status": 200,
  "total_count": 2,
  "total_new": 0,
  "result": [{
    "action": "featured",
    "text": "Your page has been added to the featured directory!",
    "html_text": "Your page has been added to the <a href=\\"/directory\\">featured directory</a>!",
    "icon": "http://about.me/.../blueme_ip.png"
    "icon2x": "http://about.me/.../blueme_ip2x.png",
    "source": "aboutme",
    "timestamp": "Tue Jul 24 2012 21:51:22 +0000",
    "emailed": false,
    "unread": true,
    "id": "500f18daae1a8868b1b9c359"
  },
  {
    "action": "wellwritten",
    "text": "test22 tester thinks your bio is well-written.",
    "html_text": "<a href=\\"/tester\\">test22 tester</a> thinks your bio is well-written.",
    "icon": "http://about.me/.../bio_ip.png",
    "icon2x": "http://about.me/.../bio_ip2x.png",
    "source": "aboutme",
    "timestamp": "Tue Jul 24 2012 18:11:53 +0000",
    "emailed": false,
    "unread": true,
    "id": "500ee569ae1a885e43e99a54",
    "actor": "tester",
    "actor_display_name": "test22 tester",
    "thumbnail2": "http://about.me/.../tester.jpg"
  }]
}

Notifications/Settings

Purpose: View or change a user’s notification settings. A user can receive different types of notifications by email and on the website.

URL:

https://api.about.me/api/v2/json/user/notifications/settings/view/<username>

https://api.about.me/api/v2/json/user/notifications/settings/change/<username>

<username> is the user whose notification settings are being retrieved or updated.

Method: GET (to view)/POST (to change)

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
token		Yes	Access token issued by the login API.
fave_site		No	Change whether the dashboard shows notifications about being added as a favorite. See Note below.
compliment_site		No	Change whether the dashboard shows compliment notifications.
shared_site		No	Change whether the dashboard shows notifications about page sharing.
reward_site		No	Change whether the dashboard shows system notifications about page completeness.
featured_site		No	Change whether the dashboard shows notifications about the featured directory.
homepage_site		No	Change whether the dashboard shows notifications about being featured on the homepage.
fave_email		No	Change whether the user gets email notifications about being added as a favorite.
compliment_email		No	Change whether the user gets email notifications about compliments.
shared_email		No	Change whether the user gets email notifications about page sharing.
reward_email		No	Change whether the user gets email notifications about page completeness.
featured_email		No	Change whether the user gets email notifications about the featured directory.
homepage_email		No	Change whether the user gets email notifications about being featured on the homepage.
digest_email		No	Change whether the user gets a weekly email digest of notifications.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Note

The options to change notifications take true or false values. These options are only valid for notifications/settings/change.

Return:

For GET operations (notifications/settings/view):

• “status”: Status code for the call; 200 if successful.
• “settings”: An array of the following fields:
  • “fave_site”: Whether the dashboard shows notifications about being added as a favorite.
  • “compliment_site”: Whether the dashboard shows compliment notifications.
  • “shared_site”: Whether the dashboard shows notifications about page sharing.
  • “reward_site”: Whether the dashboard shows system notifications about page completeness.
  • “featured_site”: Whether the dashboard shows notifications about the featured directory.
  • “homepage_site”: Whether the dashboard shows notifications about being featured on the homepage.
  • “fave_email”: Whether the user receives email notifications about being added as a favorite.
  • “compliment_email”: Whether the user receives email notifications about compliments.
  • “shared_email”: Whether the user receives email notifications about page sharing.
  • “reward_email”: Whether the user receives email notifications about page completeness.
  • “featured_email”: Whether the user receives email notifications about the featured directory.
  • “homepage_email”: Whether the user receives email notifications about being featured on the home page.
  • “digest_email”: Whether the user receives a weekly email digest of notifications.
• “error_message”: Reason call failed if status is not 200.

For POST operations (notifications/settings/change):

• “status”: Status code for the call; 200 if successful.
• “error_message”: Reason call failed if status is not 200.

See Also:

notifications

Example (for GET):

https://api.about.me/api/v2/json/user/notifications/settings/view/testaccount?
token=123.4567890987.65.4e321012345678f9123c66a4567890ae12fe3450d6789
&client_id=01234567890a12012b8ee3d4c0b567fab89987aa

Returns:

{
  "status": 200,
  "settings": {
    "fave_site": false,
    "compliment_site": true,
    "shared_site": true,
    "reward_site": true,
    "featured_site": true,
    "homepage_site": true,
    "fave_email": false,
    "compliment_email": false,
    "shared_email": false,
    "reward_email": email,
    "featured_email": false,
    "homepage_email": false,
    "digest_email": false
  }
}

Peoplefeed

Purpose: Get 10 recommended pages for a specific user. The API uses a scoring mechanism to determine which pages should be most interesting to a user, including information such as connections on other social media and geographic location, if provided.

The API returns the same 10 pages for that user until midnight EST, then returns a new set of pages. After the API returns a set of pages, those pages are marked as viewed and are not recommended for this user for 30 days.

URL:

https://api.about.me/api/v2/json/user/peoplefeed/<username>

<username> is the username for whom the pages are recommended.

Method: POST

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
token		Yes	Access token issued by the login API.
unique_id		No	A free-form string to uniquely identify the set of returned pages. See Note below.
agent		No	The user agent making the request, such as the browser version or mobile platform.
refer		No	The referring page, such as https://api.about.me/search.
lat		No	Latitude to use for recommendations by location. See Note below.
long		No	Longitude to use for recommendations by location.
distance		No	Distance in miles from the provided lat and long values.
strip_html	true	No	Strips or includes HTML from the returned bio.
extended	false	No	If true, API returns all details about the user’s page, such a font details and position of the bio box. See Note below.
on_match	false	No	If false, API does not return information for pages without individual backgrounds. If true, returns information regardless of background image.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Note

The unique_id, agent, and refer options provide more detailed statistics for page views.

The lat, long, and distance options enable the peoplefeed API to look for users near you.

The extended option does not override the on_match setting; it only provides additional information if the API returns a page.

The peoplefeed API returns a subset of the basic fields. Use extended = true to see both the full set of basic fields and the extended fields.

Return:

• “status”: Status code for the call; 200 if successful.

• “total_count”: Number of returned pages.

• “result”: Array of returned pages, including the following additional fields:

  • “icons”: Array of icons representing the source of the connection, such as Facebook.
  • “icons2x”: Array of high-resolution icons representing the source of the connection, such as Facebook.
  • “reasons”: Array of reasons, in English, representing the source of the connection, such as Facebook friend.
  • “score”: Total score of the page, indicating likelihood of interest to the user.

  For more details on the fields, refer to the create API for details.

• “total_available”: Number of available pages.

• “error_message”: Reason call failed if status is not 200.

See Also:

directory, random

Example:

https://api.about.me/api/v2/json/user/peoplefeed/testaccount

POST data:

client_id=abcDqEFGrH0IzJKylmnBGoP2qr2ST7WvxySGX0SaBC4
&token=123.4567890987.65.4e321012345678f9123c66a4567890ae12fe3450d6789

Returns:

{
  "status": 200,
  "total_count": 10,
  "result": [{
    "bio": "I'm a start-up junkie.",
    "display_name": "Tony Conrad",
    "icons": [
      "http://about.me/.../linkedin/people_feed.png",
      "http://about.me/.../facebook/people_feed.png",
      "http://about.me/.../twitter/people_feed.png"
    ],
    "icons2x": [
      "http://about.me/.../linkedin/people_feed2x.png",
      "http://about.me/.../facebook/people_feed2x.png",
      "http://about.me/.../twitter/people_feed2x.png"
    ],
    "profile": "http://about.me/tonyconrad",
    "reasons": [
      "linkedin friend",
      "facebook friend",
      "twitter friend"
    ],
    "score": 400,
    "user_name": "tonyconrad"
  }],
  "total_available": 10
}

Note

For brevity, the above example only shows a single page. The return value includes 10 pages.

Promote

Purpose: Promote an about.me page on Facebook or Twitter. The API sends a standard message.

URL:

https://api.about.me/api/v2/json/user/promote/<username>

<username> is the username of the page to promote.

Method: POST

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
token		Yes	Access token issued by the login API.
forum		Yes	The app on which to promote the user’s page (facebook, twitter).
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Return:

• “status”: Status code for the call; 200 if successful.
• “error_message”: Reason call failed if status is not 200.

https://api.about.me/api/v2/json/user/promote/testaccount

POST data:

client_id=01234567890a12012b8ee3d4c0b567fab89987aa
&token=123.4567890987.65.4e321012345678f9123c66a4567890ae12fe3450d6789
&forum=twitter

Returns:

{"status": 200}

Register

Purpose: Register for a new developer key. This is typically necessary if about.me issued your app a key for registration only.

URL:

https://api.about.me/api/v2/json/user/register/<identifier>

<identifier> is the identifier to be associated with the new developer key, for example ipad. The API accepts any freeform value, but about.me requires it describe the type of application.

Method: POST

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Registration key, issued to you by about.me.
src_url		No	URL to be associated with the client_id.
src		No	Source or application to be associated with the client_id.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Return:

• “status”: Status code for the call; 200 if successful.
• “apikey”: The key to be used for the new developer key.
• “error_message”: Reason call failed if status is not 200.

Example:

https://api.about.me/api/v2/json/user/register/ipad

POST data:

client_id=abcDqEFGrH0IzJKylmnBGoP2qr2ST7WvxySGX0SaBC4

Returns:

{"status": 200, "apikey": "abcDqEFxG0HzIjjyklmNOoP2qr2XY7ZaAqBCX0DEFG"}

Upload

Purpose: Upload and set a user’s background image.

URL:

https://api.about.me/api/v2/json/user/upload/<username>

<username> is the username whose image is to be uploaded and set.

Method: POST

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
token		Yes	Access token issued by the login API.
user_background		Yes	A .jpg, .gif, or .png image, up to 5 MB. Upload the image using multipart form data. See Note below.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Note

If the user_background image is too large, the API returns a 401 status code.

Return:

• “status”: Status code for the call; 200 if successful.
• “error_message”: Reason call failed if status is not 200.

See Also:

user/edit

Example:

Using pycurl as a client:

import pycurl
c = pycurl.Curl()
c.setopt(c.POST, 1)
c.setopt(c.URL, "https://api.about.me/api/v2/json/user/upload/test")
c.setopt(c.HTTPPOST, [('user_background', (c.FORM_FILE, "./gal1.jpg")),
    ('client_id', '01234567890a12012b8ee3d4c0b567fab89987aa'),
    ('token', '123.4567890987.65.4e321012345678f9123c66a4567890ae12fe34')])
c.perform()

Returns:

{"status": 200}

Validate

Purpose: Check the validity of a user’s access token. For example, the access token can time out or become invalid if the user changes the email address. This call returns 401 or 200, depending on the status of the token.

URL:

https://api.about.me/api/v2/json/user/validate/<username>

<username> is the username whose token is to be validated.

Method: GET

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
token		Yes	Access token issued by the login API.
strip_html	true	No	Strips or includes HTML from the returned bio.
extended	false	No	If true, API returns all details about the user’s page, such a font details and position of the bio box. See Note below.
on_match	false	No	If false, API does not return information for pages without individual backgrounds. If true, returns information regardless of background image.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Note

The extended option does not override the on_match setting; it only provides additional information if the API returns a page.

Return:

• “status”: Status code for the call; 200 if successful.
• “user_info”: The user page if the token is still valid. Refer to the create API for details.
• “error_message”: Reason call failed if status is not 200.

See Also:

login

Example:

https://api.about.me/api/v2/json/user/validate/testaccount?
client_id=01234567890a12012b8ee3d4c0b567fab89987aa
&token=123.4567890987.65.4e321012345678f9123c66a4567890ae12fe3450d6789

Returns:

{
  "status": 200,
  "user_info": {
    "profile": "http://about.me/testaccount",
    "user_name": "testaccount",
    "first_name": "test22",
    "last_name": "tester",
    "display_name": "test22 tester",
    "header": "my headline",
    "bio": "test this is one!!!!",
    "tags": ["foosball", "hiking"],
    "background": "http://about.me/.../testaccount_1326415784_79.jpg",
    "mobile_background": "",
    "email_address": "testaccount@example.com",
    "email_searchable": true,
    "email_public": false,
    "avatar": "http://about.me/.../testaccount_1325746595_83.jpg",
    "img_base_url": "http://about.me/.../thumbnail",
    "thumbnail_291x187": "http://about.me/.../291x187/testaccount.jpg",
    "thumbnail1": "http://about.me/.../803x408/testaccount.jpg",
    "thumbnail2": "http://about.me/.../260x176/testaccount.jpg",
    "thumbnail3": "http://about.me/.../198x134/testaccount.jpg",
    "thumbnail4": "http://about.me/.../161x109/testaccount.jpg"
  }
}

View

Purpose: Get page information about a particular user.

URL:

https://api.about.me/api/v2/json/user/view/<username>

<username> is the username for the page to retrieve.

Method: GET

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
token		No	Access token issued by the login API.
unique_id		No	A free-form string to uniquely identify the set of returned pages.
agent		No	The user agent making the request, such as the browser version or mobile platform.
refer		No	The referring page, such as https://api.about.me/search.
is_fav_of	true	No	By default, the return value indicates whether a returned page is in the user’s favorites list. See Note below.
strip_html	true	No	Strips or includes HTML from the returned bio.
extended	false	No	If true, API returns all details about the user’s page, such a font details and position of the bio box. See Note below.
on_match	false	No	If false, API does not return information for pages without individual backgrounds. If true, returns information regardless of background image.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Note

The is_fav_of option checks the user’s favorites, where the user is defined by the token, not the <username>. If the token is omitted, is_fav_of is ignored.

The extended option does not override the on_match setting; it only provides additional information if the API returns a page.

Return:

• “status”: Status code for the call; 200 if successful.
• The user page. Refer to the create API for details.
• “error_message”: Reason call failed if status is not 200.

See Also:

inbound, search

Example:

https://api.about.me/api/v2/json/user/view/testaccount?
client-id=01234567890a12012b8ee3d4c0b567fab89987aa
&token=123.4567890987.65.4e321012345678f9123c66a4567890ae12fe3450d6789

Returns:

{
  "status": 200,
  "profile": "http://about.me/testaccount",
  "user_name": "test account",
  "first_name": "test22",
  "last_name": "tester",
  "display_name": "test22 tester",
  "header": "my headline",
  "bio": "test this is one!!!!",
  "background": "http://about.me/.../testaccount_1326415784_79.jpg",
  "mobile_background": "",
  "email_searchable": true,
  "email_public": false,
  "avatar": "http://about.me/.../testaccount_1325746595_83.jpg",
  "img_base_url": "http://about.me/.../thumbnail",
  "thumbnail_291x187": "http://about.me/.../291x187/testaccount.jpg",
  "thumbnail1": "http://about.me/.../803x408/testaccount.jpg",
  "thumbnail2": "http://about.me/.../260x176/testaccount.jpg",
  "thumbnail3": "http://about.me/.../198x134/testaccount.jpg",
  "thumbnail4": "http://about.me/.../161x109/testaccount.jpg",
  "is_fav": false
}

Users Calls

This section includes API calls for the following actions:

• directory
• random
• search

Directory

Purpose: Get the about.me pages in the specified directory.

URL:

https://api.about.me/api/v2/json/users/view/directory/<type>

<type> is one of the following directory types:

• all – Spotlight, featured, and inspirational pages
• spotlight – Spotlight pages
• featured – Featured pages
• inspirational – Inspirational pages
• team – About.me team pages
• founder – Founder pages

For more information, refer to The about.me Directories.

Method: GET

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
token		No	Access token issued by the login API.
unique_id		No	A free-form string to uniquely identify the set of returned pages. See Note below.
agent		No	The user agent making the request, such as the browser version or mobile platform.
refer		No	The referring page, such as https://api.about.me/search.
is_fav_of	true	No	By default, the return value indicates whether a returned page is in the user’s favorites list. See Note below.
lu		No	Timestamp of the last known update, returned by a previous call to the users/view/directory API. Include this option and update_check to check whether a directory has changed. See Note below.
update_check	false	No	If set to true, checks whether a directory has changed. See Note below.
strip_html	true	No	Strips or includes HTML from the returned bio.
extended	false	No	If true, API returns all details about the user’s page, such a font details and position of the bio box. See Note below.
on_match	false	No	If false, API does not return information for pages without individual backgrounds. If true, returns information regardless of background image.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Note

The unique_id, agent, and refer options provide more detailed statistics for page views.

The is_fav_of option is ignored if the token is omitted.

For lu, if you are checking multiple directories by setting <type> to all, use <directory>_lu for each directory, such as inspirational_lu.

For update_check, if the directory has changed, the API returns status code 205 and the names of the changed directories. If the lu or <directory>_lu option is omitted, the API automatically returns 205.

The extended option does not override the on_match setting; it only provides additional information if the API returns a page.

Return:

• “status”: Status code for the call; 200 if successful.

• “directories”: Returned pages including:

  • “count”: Number of pages returned.

  • “directory_type”: Directory of pages returned.

  • “profiles”: Array of returned pages, including the following additional fields:

    • “is_fav” to indicate whether a featured page is a favorite of the current user.
    • “default_thumbnail” is a 400x270 thumbnail. This field is deprecated.

    For more details on the page fields, refer to the create API for details.

  • “last_update”: Timestamp indicating when the directory was last changed.

• “error_message”: Reason call failed if status is not 200.

See Also:

users/view/random

Example:

https://api.about.me/api/v2/json/users/view/directory/spotlight?
client_id=abcDqEFGrH0IzJKylmnBGoP2qr2ST7WvxySGX0SaBC4&ts=1307430942
&token=123.4567890987.65.4e321012345678f9123c66a4567890ae12fe3450d6789

Returns:

{
  "status": 200,
  "directories": [{
    "count": 2,
    "directory_type": "spotlight",
    "profiles": [{
      "profile": "http://about.me/testaccount",
      "user_name": "test",
      "first_name": "Test",
      "last_name": " Account",
      "display_name": "Test Account",
      "header": "",
      "bio": "Hi, my name is Suzy and I'm just getting started!",
      "background": "http://about.me/.../suzy_1307258235_28.jpg",
      "mobile_background": "",
      "email_searchable": true,
      "email_public": false,
      "avatar": "",
      "img_base_url": "http://about.me/.../thumbnail",
      "thumbnail_291x187":
      "http://about.me/.../thumbnailnotavailable-260x176.png",
      "thumbnail1": "http://about.me/.../thumbnailnotavailable-260x176.png",
      "thumbnail2": "http://about.me/.../thumbnailnotavailable-260x176.png",
      "thumbnail3": "http://about.me/.../thumbnailnotavailable-260x176.png",
      "thumbnail4": "http://about.me/.../thumbnailnotavailable-260x176.png",
      "default_thumbnail": "http://about.me/.../400x270/suzy.jpg",
      "is_fav": false
    },
    {
      "profile": "http://about.me/theeoin",
      "user_name": "theeoin",
      "first_name": "Simon",
      "last_name": " Prickett",
      "display_name": "The E\u00f3in",
      "header": "",
      "bio": "Pragmatic technology expert, traveler, hockey fan",
      "background": "http://about.me/.../mike_klay_closing_in.jpg",
      "mobile_background": "",
      "email_searchable": true,
      "email_public": true,
      "avatar": "http://about.me/.../simonprickett_1284602215_29.jpg",
      "img_base_url": "http://about.me/.../thumbnail",
      "thumbnail_291x187":
      "http://about.me/.../thumbnailnotavailable-260x176.png",
      "thumbnail1": "http://about.me/.../thumbnailnotavailable-260x176.png",
      "thumbnail2": "http://about.me/.../thumbnailnotavailable-260x176.png",
      "thumbnail3": "http://about.me/.../thumbnailnotavailable-260x176.png",
      "thumbnail4": "http://about.me/.../thumbnailnotavailable-260x176.png",
      "default_thumbnail": "http://about.me/.../400x270/theeoin.jpg",
      "is_fav": true
    }],
    "last_update": 1327387907
  }]
}

Random

Purpose: Get a specified number of random pages.

URL:

https://api.about.me/api/v2/json/users/view/random

Method: GET

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
token		No	Access token issued by the login API.
unique_id		No	A free-form string to uniquely identify the set of returned pages. See Note below.
agent		No	The user agent making the request, such as the browser version or mobile platform.
refer		No	The referring page, such as https://api.about.me/search.
is_fav_of	true	No	By default, the return value indicates whether a returned page is in the user’s favorites list. See Note below.
profile_number	5	No	Number of pages to return.
strip_html	true	No	Strips or includes HTML from the returned bio.
extended	false	No	If true, API returns all details about the user’s page, such a font details and position of the bio box. See Note below.
on_match	false	No	If false, API does not return information for pages without individual backgrounds. If true, returns information regardless of background image.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Note

The unique_id, agent, and refer options provide more detailed statistics for page views.

The is_fav_of option is ignored if the token is omitted.

The extended option does not override the on_match setting; it only provides additional information if the API returns a page.

Return:

• “status”: Status code for the call; 200 if successful.
• “total_count”: Number of returned pages.
• “result”: Array of returned pages, including “is_fav” to indicate whether a featured page is a favorite of the current user. For more details on the fields, refer to the create API for details.
• “total_available”: Number of available pages.
• “error_message”: Reason call failed if status is not 200.

See Also:

users/view/directory

Example:

https://api.about.me/api/v2/json/users/view/random/?
client_id=abcDqEFGrH0IzJKylmnBGoP2qr2ST7WvxySGX0SaBC4
&token=123.4567890987.65.4e321012345678f9123c66a4567890ae12fe3450d6789
&profile_number=1

Returns:

{
  "status": 200,
  "total_count": 1,
  "result":
  [{
    "profile": "http://about.me/melissadipasquale",
    "user_name": "melissadipasquale",
    "first_name": "MELISSA",
    "last_name": " DI PASQUALE",
    "display_name": "MELISSA  DI PASQUALE",
    "header": "Photographer",
    "bio": "Melissa graduated from Humber College during the spring ...",
    "background": "http://about.me/.../melissadipasquale_1290058842_91.jpg",
    "mobile_background": "",
    "email_searchable": true,
    "email_public": true,
    "avatar": "",
    "tags": [],
    "img_base_url": "http://about.me/.../thumbnail",
    "thumbnail_291x187": "http://about.me/.../291x187/melissadipasquale.jpg",
    "thumbnail1": "http://about.me/.../803x408/melissadipasquale.jpg",
    "thumbnail2": "http://about.me/.../260x176/melissadipasquale.jpg",
    "thumbnail3": "http://about.me/.../198x134/melissadipasquale.jpg",
    "thumbnail4": "http://about.me/.../161x109/melissadipasquale.jpg",
    "is_fav": true
  }],
  "total_available": 1
}

Search

Purpose: Search for one or more users matching the requested parameters:

• first name
• last name
• email address
• username
• tags
• location

URL:

https://api.about.me/api/v2/json/users/search

Method: GET

Query String Options:

Option	Default	Req’d?	Description
client_id		Yes	Your developer key, issued to you by about.me.
token		No	Access token issued by the login API.
unique_id		No	A free-form string to uniquely identify the set of returned pages. See Note below.
agent		No	The user agent making the request, such as the browser version or mobile platform.
refer		No	The referring page, such as https://api.about.me/search.
is_fav_of	true	No	By default, the return value indicates whether a returned page is in the user’s favorites list. See Note below.
search_key		No	Search by user’s display name.
bio_length	50	No	The maximum characters to return.
lat		No	Latitude for the search by location. See Note below.
long		No	Longitude for the search by location.
distance		No	Distance in miles from the provided lat and long values.
first_name		No	Search by user’s first name. See Note below.
last_name		No	Search by user’s last name.
email		No	Search by user’s email address. To search for multiple addresses, use a comma as the delimiter.
username		No	Search by user’s about.me username.
tags		No	Search by tags the user has defined for his or her page. To search for multiple tags, use a comma as the delimiter. See Note below.
count	20	No	For pagination, indicates the maximum number of records to return.
offset	0	No	For pagination, indicates the starting record to return.
show_not_found	false	No	If true, then a search by email shows both the records matching the specified email addresses and the email addresses that were not found.
strip_html	true	No	Strips or includes HTML from the returned bio.
extended	false	No	If true, API returns all details about the user’s page, such a font details and position of the bio box. See Note below.
on_match	false	No	If false, API does not return information for pages without individual backgrounds. If true, returns information regardless of background image.
requestid		No	Identifier that you provide, to be returned in the JSON object.
callback		No	JavaScript function to wrap the return value.

Note

The unique_id, agent, and refer options provide more detailed statistics for page views.

The is_fav_of option is ignored if the token is omitted.

The lat, long, and distance options are all required for search by location. Search by location looks for users who have checked in on the mobile app within the last 3 hours.

The first_name and last_name options, when combined, use the OR operator. The API returns records matching either the first or last name.

For the tags option, the API uses the AND operator for multiple tags.

The extended option does not override the on_match setting; it only provides additional information if the API returns a page.

The search API returns a subset of the basic fields. Use extended = true to see both the full set of basic fields and the extended fields.

Return:

• “status”: Status code for the call; 200 if successful.

• “total_count”: Number of returned pages.

• “total_available”: Number of pages meeting search criteria.

• “caller_location”: For a search by location, includes the authenticated user’s latitude, longitude, city, state, and country.

• “result”: Array of returned pages, including the following fields:

  • “user_name”
  • “display_name”
  • “bio”
  • “is_fav”
  • “latitude”, “longitude”, “city”, “state”, and “country” if searching by location.

  Note that the result set does not display a complete set of fields for the page. To get all fields, use extended=true. For more details on the page fields, refer to the create API for details.

  If show_not_found is true, then the results are broken up into two sets, identified as “found” and “not_found”. See the second example for more information.

• “error_message”: Reason call failed if status is not 200.

See Also:

checkin

Example:

https://api.about.me/api/v2/json/users/search/?
client_id=01234567890a12012b8ee3d4c0b567fab89987aa
&on_match=true&count=5
&token=123.4567890987.65.4e321012345678f9123c66a4567890ae12fe3450d6789
&search_key=David&requestid=request123

Returns:

{
  "status": 200,
  "total_count": 5,
  "requestid": "request123",
  "result":
  [{
    "user_name": "dtest1",
    "display_name": "David Tester",
    "bio": "Test",
    "is_fav": false
  },
  {
    "user_name": "testing21",
    "display_name": "David Testing",
    "bio": "",
    "is_fav": false
  },
  {
    "user_name": "drtest1",
    "display_name": "David Fred",
    "bio": "",
    "is_fav": false
  },
  {
    "user_name": "a313_a",
    "display_name": "David a313_b",
    "bio": "",
    "is_fav": false
  },
  {
    "user_name": "a313_c",
    "display_name": "David Test",
    "bio": "Test: http://en.wikipedia.org/wiki/The_Elephant_Man_(film)
            is one of my favorite films This is another test:
            http://en.wikipedia.org/wiki/The_Elephant_Man_(film)",
    "is_fav": true
  }],
  "total_available": 13
}

The following example shows searching by email with show_not_found set to true:

https://api.about.me/api/v2/json/users/search/?
client_id=01234567890a12012b8ee3d4c0b567fab89987aa
&token=123.4567890987.65.4e321012345678f9123c66a4567890ae12fe3450d6789
&email=me%40me.me%2Ctest%40example.com
&show_not_found=true&requestid=request123

Returns:

{
  "status": 200,
  "result": {
    "found":
    {
      "total_count": 1,
      "total_available": 1,
      "profiles":
      [{
        "user_name": "tester",
        "display_name": "test22 tester",
        "bio": "test this is one!!!!",
        "email_address": "test@example.com",
        "is_fav": false
      }]
    },
    "not_found": {
      "unknown": ["me@me.me"],
      "total_available": 1,
      "total_count": 1
    }
  },
  "requestid": "request123"
}

Change History

• 10/1/2012: Changed the default setting for the is_fav_of query string option to true. This applies to the connect, user/view, users/view/directory, users/view/random, and search API calls.

  Added src_url and src query string options to the register API call. These are for applications that require a URL.

• 9/5/2012: Added modal_url and site_url to the returned about.me page data. This is part of the websites information. Refer to the create API call for more details.

  Added the site_url query string option to the services/add and services/edit API calls.

  Added the unique_id, agent, and refer query string options to the user/view API call. These options support page tracking directly in user/view, instead of calling the inbound API.

• 8/14/2012: Added compliment, notifications, and notifications/settings API calls. You can also refer to the Compliments and Notifications section.

  Added the ability to improve statistics for page views with the unique_id, agent, and refer query options. These options are valid for the following API calls:

  • user/directory
  • peoplefeed
  • search
  • users/view/directory
  • users/view/random

  You can also refer to the Tracking Page Views section.

  Reformatted the query options for improved readability.

• 7/17/2012: Added peoplefeed API call, which returns a set of pages recommended for the specific user.

  Added the Sample Code section.

• 6/19/2012: Added is_link query string option to the services/add API call to support adding links to the about.me page.

  Both services/add and services/edit can use the client_id and token or api_args. The latter is provided by the about.me SDK and includes the client_id and token values.

• 6/12/2012: For consistency with the Account Settings page, the client_id is described as “Your developer key, issued by about.me.” The Authentication section also reflects this terminology change.

  Added a Usage Limits section.

• 5/29/2012: Added strip_html query string option to all API calls that return the bio text. When false, this option prevents the API from removing HTML from the returned bio text. The default is true.

  Added tags and username query string options to the search API call.