Web AIM Server API Reference

The Web AIM API lets developers incorporate core AIM functionality into any web page, including the ability to sign on, send or receive IMs, and obtain a user's Buddy List. By using the Web AIM API to build their applications, developers can take advantage of AIM's power and large user base, while having the freedom to extend AIM's functionality in innovative new ways. The APIs support both the building of real-time, interactive widgets and one-time queries. Developers can use as much or as little of the platform as they like.

You will need a key to use the Web AIM APIs, which can be obtained from Web AIM Key Registration. If you are interested in using or modifying already-built widgets, visit AIM Whimsicals.

Authentication for APIs

There are five different types of authentication supported, however not all the APIs support all five. Most of the APIs require the source user to be specfied and authenticated, with each of the types require different parameters to be specified.

Anonymous - The source user isn't specified, and no extra parameters are required.
Web Auth Token - The source user is represented by an a= parameter (created by calling getToken), this auth token can only be used by web pages
Client Auth Token - The source user is represented by an a= parameter (created by calling clientLogin), and the calls must be signed and include a ts= and sig_sha256= parameter. URL signing requires the computers clock to be accurate or the use of hostTime returned by clientLogin, parameters must be in alphabetical order, and percent-encoding uses upper case hex characters.
aimsid - The source user is represented by an aimsid= parameter (created by calling startSession) after obtaining an auth token
Anonymous aimsid - The source user is represented by an aimsid= parameter (created by calling startSession with anonymous=true) and can only be used with certain APIs

Typical Web Authenticated Application Flow

A web application should not ask for the loginId and password directly. Instead, the application must show pages, usually in an IFRAME, generated by AOL to collect the authentication information. Usually an application will have a button that starts the authentication process, but it can also do parts of it on page load. What follows is the typical flow of an application that needs user authentication.

getToken - A token is required for many of the Web AIM APIs - the first call to getToken will almost always return an error and a redirectURL
Show the redirectURL to the user, usually using an IFRAME, and watch for the URL fragment to contain #AUTHDONE
getToken - The second call to getToken will return a success with a valid token
When using one of the APIs that supports the a= parameter, stop here, and use the token.a value
Some APIs require a session; use startSession to create a session and retrieve an aimsId
startSession - The first call to startSession MAY return a 450 error with redirectURL if the user is required to grant the page consent to access the user's data - Sessions are only needed when real time presence updates or interactive IMs are required
If consent was required, show the redirectURL to the user, usually in an IFRAME, and watch for the URL fragment to contain #CONSENTDONE
startSession - If required, call startSession again
Now any of the APIs that support the aimsId= parameter can be used
Sessions require periodic calls of the fetchEvents URL for outstanding items
endSession - Mark the user offline and clean up server state

Client Application Flow

It is possible to build a client using the APIs. In that case the developer will want to use clientLogin instead of getToken. Otherwise the flow will be the same as above.

Typical Anonymous Application Flow

When building an anonymous web AIM API application like WIMZI, that needs to establish an anonymous session, the following application flow should be used. An anonymous session can only interact with the user that created the key.

startSession - Call startSession with the annoymous= parameter and a WIMZI key
Use the returned widgetTitle returned from startSession in the UI
The creatorDisplayName will automatically be returned in the first BuddyList event as the only buddy
Sessions require periodic calls of the fetchEvents URL for outstanding items
Use the returned creatorDisplayName to address IMs
setState - the friendly= option can be used to set a friendly name for the anonymous visitor
endSession - Mark the anonymous user offline and clean up server state

TLS Support

TLS is supported by most APIs using the https protocol and requires the AOL Root Certificate in the certificate store. Currently the fetchEvents call does NOT support the https protocol.

The sections below contain a complete reference to the enumerations, types, and methods of Web AIM API.

Enumerations	Types	Methods
Format Presence State User Type Event Type Typing Status Expression Type Data IM Type Reject Reason IM Channel Client Error PdMode ICBM Errors AddBuddyResultCodeValue Preferences AvTrackResultCodeValue PDResultCode	Capability Location SmsSegment Presence Group Expression Personality MyInfoEvent PresenceEvent TypingEventData TypingEvent DataIMEventData DataIMEvent sentDataIMEventData sentDataIMEvent RawMsg IMEventData IMEvent sentIMEventData sentIMEvent ClientErrorEventData ClientErrorEvent OfflineIMEventData OfflineIMEvent BuddyListEventData BuddyListEvent SessionEndedEvent Event SendImSubCode QuietHours LocationAllow MediaContent MediaThumbnail MediaTitle BuddyFeedItem RankedUsersLocation EventStatus AddBuddyResultCode IMConversationLocation AvTrackImage AvTrackInfo AIMFightUser PDNameResult PDResults	Session Methods startSession fetchEvents deleteEvents endSession setSessionParam startOSCARSession Presence Methods getPresence getBuddyListPresence getPresenceIcon setState setStatus setProfile getProfile IM Methods sendIM sendDataIM rejectDataIM setTyping Expressions Methods getExpression getPersonalities getAsset setExpression uploadExpression Buddylist Editing Methods addBuddy removeBuddy moveBuddy setBuddyAttribute getBuddyAttribute addGroup removeGroup renameGroup moveGroup setGroupAttribute copyBuddyLists addTempBuddy removeTempBuddy Preference Methods setPreference getPreference setPermitDeny getPermitDeny Location Based Methods googleEarth.kml getRankedUsersLocations.kml getRankedUsersLocations getIMConversationsLocations.kml getIMConversationsLocations Buddyfeed Methods getUserFeed getBuddylistFeed pushFeed Miscellaneous Methods aimStartPage aimExpressionsPage getHostBuddyInfo getVanityInfo setAvTrack getAvTrack getAIMFight

Enumerations

These enumerations are constants used by Web AIM types and methods.

Enumeration: Format

The return format of the APIs

Values	Description
json	JSON Format
xml	Simple XML Format
php	Serialized PHP
amf0	Flash binary AMF0 format
amf3	Flash binary AMF3 format

Enumeration: Presence State

The presence state values of an AIM ID. An AIM ID can be in any one of these states.

Values	Description
online	Online State
invisible	Invisible - Only valid in myInfo objects
notFound	For email lookups the address was not found
idle	Idle State
away	Away State
mobile	Mobile State
offline	Offline State

Enumeration: User Type

The type of user

Values	Description
aim	AIM or AOL
icq	ICQ
sms	SMS phone number
interop	Gatewayed from another network
imserv	IMServ group target

Enumeration: Event Type

Web AIM supports multiple different event types. Each event type needs to be explicitly subscribed to (except for sessionEnded) when calling startSession. Since the different events occur asynchronously, calls to the fetchEvents method will return them.

Subscribing to the buddylist event is what makes the user appear online to everyone else, so not subscribing will cause the user to appear offline to everyone except those IMed. This way it is possible to build a widget that only appears online to those the user is having a conversation with.

Values	Description
myInfo	Information about oneself
presence	Presence changes about a buddy on the Buddy List
buddylist	Buddylist change, replace the current Buddy List with this one
typing	Typing indicator status change
im	Instant Message
dataIM	Data Instant Message
clientError	Client Error
sessionEnded	Session ended, do not call fetchEvents anymore
offlineIM	Offline Instant Message
sentIM	Keep track of IMs sent
sentDataIM	Keep track of data IMs sent

Enumeration: Typing Status

The current IM typing status generated by

Values	Description
none	Previously was in typing or typed status and has erased all their text
typing	Started typing, only send on transition not for every key press
typed	Previously typing and now has stopped typing - recommend only using after typing has stopped for at least 3 seconds

Enumeration: Expression Type

The type of expression data

Values	Description
miniIcon	Small icon - displayed on the Buddy List for users on some clients
buddyIcon	Large icon - displayed in IM window for most clients
bigBuddyIcon	Big buddy icon
arriveSound	Sound associated with the user signing on
departSound	Sound associated with the user signing off
imSound	Sound associated with the user receiving an IM
imChrome	Wallpaper
superBuddy	Super Buddy
immersiveChromeXML	Immersive Wallpaper
imChromeXML	Wallpaper XML
emoticon	Return the zipped emoticons

Enumeration: Data IM Type

The type of IM data, not all of these types must be used

Values	Description
invite	Start a custom session
accept	Accept a custom session
deny	Deny a custom session
data	Send data for a custom session
end	End a custom session

Enumeration: Reject Reason

For reject rendezvous

Values	Description
unsupported	Proposal capability not supported
denied	Not authorized or used declined
malformed	Proposal malformed
timedOut	Attempt to act on proposal timed out
notAvailable	Recipient away or busy
resources	Recipient had internal error
rateLimited	Recipient was rate limited
noData	Recipient had nothing to send
version	Incompatible version
security	Incompatible security setting

Enumeration: IM Channel

Internal channel used for IM

Values	Description
text	Regular text IM
data	Data or Rendezvous IM

Enumeration: Client Error

Reported by client

Values	Description
unsupported	Channel unsupported by client
malformed	Request unrecognizable
channel	Channel specific error

Enumeration: PdMode

The permit/deny mode

Values	Description
permitAll	Allow all aimIds
permitSome	Only aimId's tagged with allow
permitOnList	Only aimIds on Buddy List
denySome	Denied tagged aimIds
denyAll	Allow no one

Enumeration: ICBM Errors

Status values for mobile

Values	Description
0	No subcode supplied
1	IMs to recipient blocked
2	Remote restricted by parental controls
3	User needs to accept terms and conditions before sending to mobile
4	Client did not display SMS charging information before trying to send
5	Cannot send SMS message to destination country
6	User restricted to closed IM group
7	User cannot send without payment authorization
8	Cannot determine country for destination mobile device
9	IM cannot be initiated by a BOT
10	IM is not allowed by consumer BOT to recipient
11	IM is not allowed by consumer BOT due to usage limited
12	IM is not allowed by consumer BOT due to daily usage limited
13	IM is not allowed by consumer BOT due to monthly usage limited
14	User does not accept offline IMs
15	Exceed max storage limit of offline IMs
16	Multi file transfer request blocked by host

Enumeration: AddBuddyResultCodeValue

Result code value

Values	Description
0	Success
3	Already Exists
17	Over Buddy Limit
26	Timeout

Enumeration: Preferences

Various AIM preferences

Values	Description
displayLogin	[1] Display Buddy List at login
displayEBuddy	[1] Whether or not to display the EBuddy group
playEnter	[1] Whether or not to play a sound when a buddy enters
playExit	[1] Whether or not to play a sound when a buddy exits
viewIMTimestamps	[1] Whether or not to display the timestamp in IMs
viewSmilies	[1] Whether or not to display :) as a graphic
acceptIcons	[1] Accept buddy icons
knockNonAOLIMs	[1] Want knock-knocks for IMs from non-AOL users
knockNonListIMs	[1] Want knock-knocks for IMs from people not on your Buddy List
discloseIdle	[1] Let other users know if you are idle
acceptCustomBart	[0] Accept non-official icons, chromes
acceptNonListBart	[0] Accept icon, chromes, from non-buddies (official only)
acceptBgs	[1] Accept IM window backgrounds
acceptChromes	[1] Accept IM window chromes
acceptBLSounds	[1] Accept BL arrive/depart sounds
acceptIMsounds	[1] Accept IM sounds
noSeeRecentBuddies	[0] User does not see RECENT BUDDIES group
acceptSMSLegal	[0] User has accepted to SMS legal agreement
enterDoesCRLF	[0] Enter does not send IM
playIMSound	[1] Play sound on IM receipt
discloseTyping	[1] Send typing notifications
acceptSuperIcons	[1] Accept 'super- buddies'
acceptBLRichText	[1] Display rich-text screennames in Buddy List
reduceIMSound	[1] Attenuate IM sounds after first
confirmDirectIM	[1] Confirm with local user before starting Direct IM
oneTabbedIMWindow	[1] Show all IMs in one tabbed window
buddyInfoOnMouseover	[1] Popup information when mouse pauses above buddy
discloseBuddyMatches	[1] Let other users know if they have buddy matches
catchIMs	[0] For host use only - Clients use CATCH_IMS_FOR_CLIENT
showFriendlyName	[1] Show alias instead of screenname?
discloseRadio	[1] Buddies know when user listening to AOL radio
showCapabilities	[1] Show capabilities in the Buddy List
showBuddyListFilter	[1] Show Buddy List filter
showAwayIdle	[1] Show away and idle buddies
showMobile	[1] Show mobile buddies
sortBuddyList	[0] Keep Buddy List sorted a-z
catchIMsForClient	[0] IM catcher window enabled?
newMessageSmallNotification	[1] show small notification after new message arrives
noFrequentBuddies	[0] User does not see FREQUENT BUDDIES group
blogAwayMessages	[0] Send away messages to journals ?
blogAIMSigMessages	[0] Send AIM signature to journals ?
blogNoComments	[0] User allows comments ?
friendOfFriend	[0] Allow Friend of Friend queries
friendGetContactList	[0] Allow friend to get my Buddy List
compadInit	[0] ICQ Compad Init
sendBuddyFeed	[1] Send buddy feed - Young Teens(YT)/Kids Only(KO) default to OFF
blkSendIMWhileAway	[0] Block send IM while away
showBuddyFeed	[1] Show What is New indicator
noSaveVanityInfo	[0] Do not save vanity related info (IM sent, idle, etc)
acceptOffLineIM	[1] Accept Offline IMs
showGroups	[0] ICQ: Show buddies in groups ?
sortGroup	[1] ICQ: Sort groups ?
showOffLineBuddies	[1] ICQ: Show/Hide offline buddies
expandBuddies	[0] ICQ: Show multiline information on some buddies
thirdPartyFeeds	[0] BUDDY FEED: Does the owner have 3rd party feeds
notifyReceivedInvite	[1] Notify at login about received AIMPages Invitations
apfAutoAccept	[0] Auto accept AIMPages Invitations
apfAutoAcceptBuddy	[0] If APF_AUTO_ACCEPT & APF_AUTO_ACCEPT_BUDDY, Auto accept invites only from buddies
blockAwayMsgFeed	[0] Block feed storage for away messages
blockAIMProfileFeed	[0] Block feed storage for AIM Profiles
blockAIMPagesFeed	[0] Block feed storage for AIM Pages
blockJournalsFeed	[0] Block feed storage for AOL Journals
blockLocationFeed	[0] Block feed storage for Location data
blockStickiesFeed	[0] Block feed storage for Stickies
blockUncutFeed	[0] Block feed storage for Uncut video
blockLinksFeed	[0] Block feed storage for Interesting Links
blockAIMBulletinFeed	[0] Block feed storage for AIM Bulletins
saveStatusMsg	[1] Save status message
apfNotifyReceivedInviteByEmail	[0] Should email be sent when user invited
showOfflineGrp	[1] Show offline group
offlineGrpCollapsed	[0] Offline Group is collapsed
firstImSoundOnly	[0] Only play the sound on the first IM
imblastInviteNotify	[1] Allows Imserv invite notify message
blockpluginsFeed	[0] Block feed storage for plugin uploads
enableBeboAlerts	[1] Enable BEBO related alerts

Enumeration: AvTrackResultCodeValue

Result code value

Values	Description
0	Success
1	Internal Error
2	Not Found
3	Timeout

Enumeration: PDResultCode

Status code from PD operations

Values	Description
0	Success
1	Database Error
2	Not Found
12	Over the limit
16	Invalid Nickname

Types

Various data types that the methods return.

Type: Capability

A capability allows clients to broadcast what features they are interested in or support. They are represented with UUIDs. When sending or receiving a capability with these APIs, use the 32 character hex encoding of the UUID.

32 character UUID example: 550e8400e29b41d4a716446655440000

Type: Location

The Location Object contains field relating to a user's location.

Type	Field	Description
String	desc	Description
String	street	Street name
String	city	City name
String	country	Country name
String	state	State name
String	postcode	Postal code
String	accuracy	Measure of how accurate (in meters) location is
String	lat	Latitude
String	lon	Longitude
String	accu_string	Description of the accuracy level, ex Street\|City\|State, etc

Type: SmsSegment

The SMS Segment Object contains fields relating to segmenting IMs to send to SMS or IM Forwarding users

Type	Field	Description
Integer	single	Number of bytes that can be sent in a single segment message
Integer	initial	Number of bytes in the first segment of a multi-segment IM
Integer	trailing	Number of bytes in second or later segment of a multisegment IM

Type: Presence

The Presence Object contains fields relating to a users' online availability.

Type	Field	Description
String	aimId	Compressed AIM loginId - use this to identify windows; does not change
String	displayId	Display AIM loginId - use this to display an aimId to the end user
String	emailId	Email address of user - only set when doing an email search
String	friendly	Friendly alias - not always set; this is a local friendly name for the user
Presence State	state	State of the aimId
Integer	onlineTime	Seconds online
Integer	idleTime	Minutes idle
Integer	awayTime	Seconds away
Integer	statusTime	Seconds since status message was changed
String	awayMsg	Away message in xhtml form
String	profileMsg	Profile message in xhtml form
String	statusMsg	Status message in utf8 form
String	buddyIcon	Buddy icon URL
String	presenceIcon	Presence icon URL
Integer	memberSince	When user joined AIM
Array of Capability	capabilities	Capabilities of the user
Location	location	Information that the user has provided about their location
String	ipCountry	Country of the user if known. Based on IP address. Only valid in myInfo objects
Boolean	recent	For buddylist events, any buddies in the Recent Buddies group will have this set
Boolean	bot	For buddylist events, any buddies that are BOTs will have this set
Boolean	shared	For buddylist events, any buddies in the a shared buddies group will have this set
SmsSegment	smsSegment	Information about SMS/IMF users
User Type	userType	Type of user
Boolean	updatedBuddyInfo	Users Buddy Feed has been updated since you last viewed it

Type: Group

The Group Object is used to subdivide Buddy lists.

Type	Field	Description
String	name	Name of Group
Boolean	collapsed	List of buddies not expanded
Boolean	recent	This group contains Recent Buddies
Boolean	bot	This group contains system added BOTs
Boolean	shared	This is a shared group
Integer	smart	Reference ID for smart buddy group
String	imserv	If this is an IMserv group, this will be the name of the imserv
Array of Presence	buddies	Array of Users

Type: Expression

The Expression Object points to the personal Expression data described in the Expression Type enumeration - buddy icons, arrival and departure sounds, and wallpaper.

Type	Field	Description
Expression Type	type	Type of the expression
String	id	Id of the expression
String	url	URL to fetch the binary data for the expression

Type: Personality

The Personality Object points to the Personality name and contains the Expression data therein.

Type	Field	Description
String	name	Name of the personality
Array of Expression	expressions	Expression object contained in the personality

Type: MyInfoEvent

The MyInfoEvent, when subscribed to, returns the user's personal profile and online availability. Please refer to the Presence datatype section for specific details.

Type	Field	Description
String	type	Will be "myInfo"
Presence	eventData	Presence Event Data

Type: PresenceEvent

The PresenceEvent, when subscribed to, returns another user's personal profile and online availability. Please refer to the Presence datatype section for specific details.

As users on a logged-in AIM member's Buddy List change their Presence information (by logging in and out, changing their away message, etc.), Presence events are sent by the Web AIM API for pickup by the fetchEvents method.

Type	Field	Description
String	type	Will be "presence"
Presence	eventData	Presence Event Data

Type: TypingEventData

The Typing Event Data indicates whether a user is typing or not. Please refer to the Typing Status section for details.

Type	Field	Description
String	aimId	Source user
Typing Status	typingStatus	Status

Type: TypingEvent

The Typing Event is sent when a user's Typing Status changes.

Type	Field	Description
String	type	Will be "typing"
TypingEventData	eventData	Typing Event Data

Type: DataIMEventData

The Data IM Event Data contains the actual data message as well as the source of the message, its type, and a timestamp.

Type	Field	Description
Presence	source	Presence information about the source user
Capability	dataCapability	AIM Capability to which the message was sent
Data IM Type	dataType	Type of Message
String	dataIM	Base64 encoded data sent from the source user
Integer	timestamp	UTC timestamp of when the IM was sent
String	inviteMsg	For invite types, the message if present

Type: DataIMEvent

The IM Event will be retrieved by the fetchEvents method whenever a data IM is received by the user.

Type	Field	Description
String	type	Will be "dataIM"
DataIMEventData	eventData	Data for the Data IM Event

Type: sentDataIMEventData

The Sent Data IM Event Data contains the actual data message as well as the destination of the message, its type, and a timestamp.

Type	Field	Description
Presence	dest	Presence information about the destination user. Actual presence information may not be known
Capability	dataCapability	AIM Capability to which the message was sent
Data IM Type	dataType	Type of Message
String	dataIM	Base64 encoded data sent from the source user
Integer	timestamp	UTC timestamp of when the IM was sent
String	inviteMsg	For invite types, the message if present

Type: sentDataIMEvent

The Sent Data IM Event will be retrieved by the fetchEvents method whenever a data IM is sent by the user.

Type	Field	Description
String	type	Will be "sentDataIM"
sentDataIMEventData	eventData	Data for the Sent Data IM Event

Type: RawMsg

Includes base64 encoded raw IM data

Type	Field	Description
String	ipCountry	Country abbreviation, if known, based on IP lookup
String	clientCountry	Country abbreviation that the client asserts when starting a session
String	memberCountry	Country abbreviation for AOL member as set when user registered account
String	base64Msg	Base64 encoded raw IM data

Type: IMEventData

The IM Event Data contains the actual IM message as well as the source of the message, its autoresponse status, and a timestamp.

Type	Field	Description
Presence	source	Presence information about the source user
String	message	IM from the source user
Boolean	autoResponse	Is this an autoresponse IM?
Integer	timestamp	UTC timestamp of when the IM was sent
String	imserv	Name of IMServ if IM is from a IMServ group
RawMsg	rawMsg	base64 encoded raw data if rawMsg specified in startSession

Type: IMEvent

The IM Event will be retrieved by the fetchEvents method whenever an IM is received by the user.

Type	Field	Description
String	type	Will be "im"
IMEventData	eventData	IM Event Data

Type: sentIMEventData

The Sent IM Event Data contains the actual IM message as well as the destination of the message, its autoresponse status, and a timestamp.

Type	Field	Description
Presence	dest	Presence information about the source user. Actual online status may not be available
String	message	IM to the destination user
Boolean	autoResponse	Is this an autoresponse IM?
Integer	timestamp	UTC timestamp of when the IM was sent

Type: sentIMEvent

The IM Event will be retrieved by the fetchEvents method whenever an IM is sent by the user.

Type	Field	Description
String	type	Will be "sentIM"
sentIMEventData	eventData	Sent IM Event Data

Type: ClientErrorEventData

The Client Error Event Data contains the error data.

Type	Field	Description
Presence	source	Presence information about the source user
String	cookie	Base64 encoded conversation cookie
IM Channel	channel	Channel client reported error on
Client Error	code	Reason code
Reject Reason	rejectReason	For rendezvous rejects
String	errorInfo	Base64 encoded optional error information

Type: ClientErrorEvent

The Client Error Event will be retrieved by the fetchEvents method whenever a client error is received by the user.

Type	Field	Description
String	type	Will be "clientError"
ClientErrorEventData	eventData	Data for the Data IM Event

Type: OfflineIMEventData

The IM Event Data contains the actual IM message as well as the source of the message, its autoresponse status, and a timestamp.

Type	Field	Description
String	aimId	Source user
String	message	IM from the source user
Integer	timestamp	UTC timestamp of when the IM was sent

Type: OfflineIMEvent

The IM Event will be retrieved by the fetchEvents method whenever an IM is received by the user.

Type	Field	Description
String	type	will be "offlineIM"
OfflineIMEventData	eventData	Offline IM Event Data

Type: BuddyListEventData

The BuddyList Event Data contains the user's complete Buddy List, stored as an array of Buddy List groups.

Type	Field	Description
Array of Group	groups	groups inside the Buddy List

Type: BuddyListEvent

The Buddy List Event is sent to fetchEvents when a user first authenticates and gives permission for the API to access his Buddy List.

Type	Field	Description
String	type	Will be "buddylist"
BuddyListEventData	eventData	Presence Event Data

Type: SessionEndedEvent

This is the Session Ended Event from fetchEvents.

Type	Field	Description
String	type	Will be "sessionEnded"

Type: Event

Event Object is a base class to all the different Events above.

Type	Field	Description
Event Type	type	Type of event
String	eventData	Data for event - see all the *Event types above.
Integer	seqNum	Identifier for event. Can be used as eventNumber with deleteEvent.

Type: SendImSubCode

The subcode data returned with sendIM for mobile.

Type	Field	Description
ICBM Errors	subError	suberror code
String	subReason	reason of the failure

Type: QuietHours

Quiet hours

Type	Field	Description
String	start	Start time
String	end	End time

Type: LocationAllow

Location Allow

Type	Field	Description
String	aimId	Allowed AIM id
Array of QuietHours	quietHours	Quiet hours

Type: MediaContent

Media RSS content type

Type	Field	Description
Integer	height	Image height
Integer	width	Image width
String	url	Image location

Type: MediaThumbnail

Media RSS thumbnail type

Type	Field	Description
Integer	height	Image height
Integer	width	Image width
String	url	Image location

Type: MediaTitle

Media RSS title type

Type	Field	Description
String	contentValue	Image title

Type: BuddyFeedItem

This is the Buddy Feed Data.

Type	Field	Description
String	aimId	Compressed AIM id
String	title	Title
String	link	Link
String	domain	Domain link is on
String	description	Description
String	category	Category
String	pubDate	Date
Integer	timestamp	Epoch timestamp
String	author	Author
String	guid	guid
MediaContent	media-content	Media RSS content
MediaThumbnail	media-thumbnail	Media RSS thumbnail
MediaTitle	media-title	Media RSS title

Type: RankedUsersLocation

Ranked Users Locations Information

Type	Field	Description
String	name	Description of point
Integer	count	Number of users
Float	lat	latitude
Float	lon	longitude

Type: EventStatus

Event Status Information

Type	Field	Description
Integer	event	Event Number
Integer	code	Event Response Code

Type: AddBuddyResultCode

The result code returned for each buddy object.

Type	Field	Description
String	buddy	buddy name
AddBuddyResultCodeValue	resultCode	Status code of each buddy as a result of an action

Type: IMConversationLocation

IM Conversation Location Information

Type	Field	Description
String	name	Description of line
Integer	count	Number of users
Integer	age	How long ago
Float	lat1	latitude1
Float	lon1	longitude1
Float	lat2	latitude2
Float	lon2	longitude2

Type: AvTrackImage

Image Reference

Type	Field	Description
String	width	width
String	height	height
String	src	link of reference
Array of String	contentTags	content tag

Type: AvTrackInfo

All info about an track

Type	Field	Description
Integer	startDate	Unix EPOCH time when the track starts playing
Integer	Duration	Duration of the track
String	t	target name
AvTrackResultCodeValue	statusCode	result code
String	title	track name
String	uri	where to access the track directly
String	album	album name
String	albumLink	album link
String	artist	artist name
String	artistLink	artist link
Array of String	genres	genre
String	playlist	playlist name
String	playlistLink	playlist link
String	podcast	podcast name
String	podcastLink	podcast link
String	series	series name
String	seriesLink	series link
Array of AvTrackImage	images	image info

Type: AIMFightUser

User's AIM Fight information

Type	Field	Description
String	aimId	Compressed AIM id
Integer	score	The users score
Integer	rank	If the user is in the top 5% their numerical rank starting at 1, otherwise 0

Type: PDNameResult

The target name and status code data.

Type	Field	Description
String	aimid	aimid
PDResultCode	statusCode	status code returned for this aimid

Type: PDResults

The result code returned for each object.

Type	Field	Description
Integer	pdModeResult	Result of setting pdMode
Array of PDNameResult	allowResults	Status code of each target in pdAllow
Array of PDNameResult	blockResults	Status code of each target in pdBlock
Array of PDNameResult	IgnoreResults	Status code of each target in pdIgnore
Array of PDNameResult	allowRemoveResults	Status code of each target in pdAllowRemove
Array of PDNameResult	blockRemoveResults	Status code of each target in pdBlockRemove
Array of PDNameResult	IgnoreRemoveResults	Status code of each target in pdIgnoreRemove

Methods

This section contains methods supported by the Web AIM API. All of our methods that do not return raw data support both JavaScript Object Notation (JSON) and Simple XML output, so the developer can choose whichever is easier. JSON is a lightweight data-exchange format used by many popular web services. (To learn more about JSON, see JSON.org, as well as the resources linked to from JSON's Wikipedia page.)

Almost every method supports 3 standard parameters:

f (required) to select the format of the returned data
r (optional) to include a request Id that is returned with the results
c (optional) to specify a JSONP callback in the returned results

All of the output is wrapped in shared wrappers which contain the statusCode, statusText, an optional statusDetailCode and if provided in the request, the matching requestId. The HTTP Status Code will always be 200, unless a format parameter is missing, and instead results for the request are contained inside the statusCode field returned in the wrapper.

The JSON standard wrapper looks like this:

{ "response":{ "statusCode":200, "statusText":"Ok", "requestId":"123", "data":{ ... } } } < /pre>

The Simple XML standard wrapper looks like this:

<?xml version="1.0" encoding="UTF-8"?> <response> <statusCode>200</statusCode> <statusText>Ok</statusOk> <requestId>123</requestId> <data> ... </data> </response> < /pre>

Requests are sent to Web AIM through simple APIs. Each method is appended to the base URL and arguments are passed as parameters. Responses are sent back in Simple XML or JSON formats. If the command sent contained the optional callback parameter 'c', that parameter is prepended to the wrapped JSON literal resulting in a valid JavaScript function call; this is known as JSONP format.

For example, a developer might wish to use the Web AIM API's getToken method to determine whether a visitor has signed in, and if so, obtain an authentication token. The developer takes the base URL for the getToken method, https://api.screenname.aol.com/auth/getToken, and adds his developer key and desired output format, JSON, as parameters. They would like the API response to be parsed by a function, 'authenticate', so they add that as the callback parameter. The full API request looks like this:

https://api.screenname.aol.com/auth/getToken?f=json&k=MYKEY&c=authenticate

If the visitor hasn't signed in, the response from the Web AIM API might look like this:

authenticate({
  "response":{
    "statusCode":401,
    "statusText":"Authentication Required",
    "data":{
        "redirectURL":"http://api.screenname.aol.com/auth/login"
    }
  }
});
< /pre>
This is valid JavaScript. If placed in a script tag and dynamically inserted into the head of the document, it will execute, calling the function specified in the callback parameter - in the above example, 'authenticate'. This is one of JSON's chief advantages; properly padded, it allows developers to dynamically introduce data from other domains  without resorting to server-side code.
Since events from the Web AIM API can arrive asynchronously at the client, they are received by performing a long poll on special fetchEvent service.  
The fetchEvent service  waits until there are events ready to be received or a timeout has occured; when a timeout occurs, the caller simply begins a new fetchEvent.

Method: startSession

Start a Web AIM session. Since the AIM server needs to deliver asynchronous events, such as receiving IMs or buddy updates, a session is required for some of the APIs. However most of the APIs do not require a session, so there is no need to create one. After starting a session the AIM Session Id (aimsid) can be used instead of an AOL Authentication Token for most of the APIs. An AOL Authentication Token is required to start a session, which can be obtained with either getToken or clientLogin.

If end user interaction is required, a redirect URL is provide that needs to be shown to the end user in a DHTML control (such as an iframe). This redirection is to request the user's permission to access their Buddy List.

If an iframe is used, the calling code can detect when the end user has completed the interaction by looking for the #CONSENTDONE URL fragment, which the iframe will add to the parent document. The startSession call must be repeated at this point. If the end user does not give permission, the iframe will add the URL fragment #CONSENTCANCEL.

When using a token created with clientLogin the startSession call must be signed. An example of how to calculate sig_sha256 can be found at ClientLogin Example. URL signing requires the computers clock to be accurate or the use of hostTime returned by clientLogin, parameters must be in alphabetical order, and percent-encoding uses upper case characters.

URL: GET http://api.oscar.aol.com/aim/startSession
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	[Required] the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	a	[Required] Use an AOL Authentication Token for authentication, from the getToken call
Event Type	events	[Required] Comma separated list of events to subscribe to, fetchEvents will only return these events. The buddylist event triggers if the user will show up online to other folks or not.
Boolean	encodeData	Base 64 encode the data in imdata events
Capability	assertCaps	Comma separated list of capabilities to assert to other users and to receive from other users
Capability	interestCaps	Comma separated list of capabilities to ONLY receive from other users
Boolean	anonymous	Start an anonymous session
Boolean	invisible	Start an invisible session
Boolean	rawMsg	Setting this will result in receiving raw data from fetchEvent API. This data can be used by legacy clients
String	friendly	For anonymous sessions, this is an optional friendly name to display
String	language	The language and locale to use in "<lang>-<locale>" format. The lang is the 2 letter language code for I18N (default: en) and the locale is the 2 letter Locale code for I18N (default: us). If not passed in, the language will default to "en-us".
String	clientName	Client name - clientLogin parameter
Integer	clientVersion	Client version - clientLogin parameter
Integer	ts	Epoch timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
Boolean	mobile	Whether this is a mobile session.
Integer	sessionTimeout	Time in seconds before terminating idle web session.
Presence State	view	How we should appear to other users, offline and mobile are not valid in this case
Integer	buildNumber	Build Number
Integer	majorVersion	Major Version, i.e for 1.2.3, major version = 1
Integer	minorVersion	Minor Version, i.e for 1.2.3, minor version = 2
Integer	pointVersion	Point Version, i.e for 1.2.3, point version = 3
Integer	pollTimeout	Default value requested for fetchEvents, so client does not need to supply in each request
String	includePresenceFields	Comma separated list of fields to include in a presence object. This can be used to minimize data that the client does not use. You can also include "=" for any of the fields, so that the field will only be present if the value does not match the specified default value. Example: includePresenceFields=aimId,userType=icq,friendly
String	excludePresenceFields	Comma separated list of fields to exclude in a presence object. This can be used to minimize data that the client does not use. You can also include "=" for any of the fields, so that the field will only be present if the value does not match the specified default value. Example: excludePresenceFields=userType=icq,buddyIcon

Output Fields

Type	Field	Description
String	fetchBaseURL	Base URL to do fetches with, see fetchEvents method below
Array of Integer	ts	Epoch timestamp - clientLogin required parameter
String	aimsid	The aimsid to use in other calls
Presence	myInfo	Presence object about logged in user
String	creatorDisplayName	For anonymous sessions, this is the display name to use for the widget creator
String	widgetTitle	For anonymous sessions, this is the widget title to use
String	greetingMsg	For anonymous sessions, this is the greeting msg to use
String	offlineMsg	For anonymous sessions, this is the offline msg to use
String	cssURI	For anonymous sessions, this is the css uri path

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
408	Timeout of the backend servers
450	Consent required, use the redirectURL and append a k=KEY to it
460	Missing required parameter
462	Parameter error
607	Rate limit signing on, wait a few minutes before trying again

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call

Example: http://api.oscar.aol.com/aim/startSession?f=json&k=KEY&c=callback&a=AOLAUTHTOKEN

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "fetchBaseURL":"http://10.10.10.10/aim/fetchEvents?seq=10",
      "ts":[
      
      ],
      "aimsid":"opaquedata",
      "myInfo":{
        "aimId":"chattingchuck",
        "displayId":"ChattingChuck",
        "friendly":"Chuck my Buddy",
        "state":"away",
        "onlineTime":100,
        "awayTime":10,
        "statusTime":100,
        "awayMsg":"I'm busy right now chatting.",
        "profileMsg":"My name is Chuck, and I live on AIM.",
        "statusMsg":"Look at me!",
        "buddyIcon":"",
        "presenceIcon":"http://o.aolcdn.com/aim/img/away.gif",
        "capabilities":[
        "200A0000A28911D3A52D001083341CFA"
        ],
        "location":{
          "desc":"AOL Office",
          "street":"SULLY RD",
          "city":"STERLING",
          "country":"US",
          "state":"VA",
          "postcode":"20166",
          "accuracy":"100",
          "lat":"38.986750",
          "lon":"-77.430500",
          "accu_string":"Block1"
        },
        "ipCountry":"",
        "smsSegment":{
          "single":,
          "initial":,
          "trailing":
        },
        "userType":"aim",
        "updatedBuddyInfo":
      },
      "creatorDisplayName":"",
      "widgetTitle":"",
      "greetingMsg":"",
      "offlineMsg":"",
      "cssURI":""
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <fetchBaseURL>http://10.10.10.10/aim/fetchEvents?seq=10</fetchBaseURL>
    <ts>
    <0></0>
    </ts>
    <aimsid>opaquedata</aimsid>
    <myInfo>
      <aimId>chattingchuck</aimId>
      <displayId>ChattingChuck</displayId>
      <friendly>Chuck my Buddy</friendly>
      <state>away</state>
      <onlineTime>100</onlineTime>
      <awayTime>10</awayTime>
      <statusTime>100</statusTime>
      <awayMsg>I'm busy right now chatting.</awayMsg>
      <profileMsg>My name is Chuck, and I live on AIM.</profileMsg>
      <statusMsg>Look at me!</statusMsg>
      <buddyIcon></buddyIcon>
      <presenceIcon>http://o.aolcdn.com/aim/img/away.gif</presenceIcon>
      <capabilities>
      <capability>200A0000A28911D3A52D001083341CFA</capability>
      </capabilities>
      <location>
        <desc>AOL Office</desc>
        <street>SULLY RD</street>
        <city>STERLING</city>
        <country>US</country>
        <state>VA</state>
        <postcode>20166</postcode>
        <accuracy>100</accuracy>
        <lat>38.986750</lat>
        <lon>-77.430500</lon>
        <accu_string>Block1</accu_string>
      </location>
      <ipCountry></ipCountry>
      <smsSegment>
        <single></single>
        <initial></initial>
        <trailing></trailing>
      </smsSegment>
      <userType>aim</userType>
      <updatedBuddyInfo></updatedBuddyInfo>
    </myInfo>
    <creatorDisplayName></creatorDisplayName>
    <widgetTitle></widgetTitle>
    <greetingMsg></greetingMsg>
    <offlineMsg></offlineMsg>
    <cssURI></cssURI>
  </data>
</response>

Method: fetchEvents

Fetch outstanding events for an aimsid, waiting up to timeout milliseconds before returning. This URL is never formed on its own - instead, the URL is created by taking the fetchBaseURL returned by startSession or the last fetchEvents call, appending the required format parameter, and then optionally appending a requestId or callback parameters. Appending the aimsid is not necessary; the API automatically adds it to the fetchBaseURL as the first parameter. The client should wait at least timeToNextFetch milliseconds between calls and make sure to use the new fetchBaseURL returned for the next call. Using an old fetchBaseURL will cause previous events to be repeated. A session will be timed out if there isn't an active fetchEvents for more then 30 seconds.

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	aimsid	[Required] Use an AIM Session Id from the startSession call for authentication
Integer	timeout	[Default 1 hour] Timeout in milliseconds that the server will wait before returning. Minimum 500ms, maximum 1 hour. On timeout the server will still respond, there will be no events however. For a web application this must be set.
Boolean	peek	If true, then this fetch will not update the most recent seqNum returned

Output Fields

Type	Field	Description
Integer	timeToNextFetch	Milliseconds to wait before doing the next event fetch
String	fetchBaseURL	Base URL to do next fetch with
Array of Event	events	Events that occured between the last fetch and now, can be empty on timeout

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "timeToNextFetch":500,
      "fetchBaseURL":"http://10.10.10.10/aim/fetchEvents?seq=11",
      "events":[
      {
        "type":"sessionEnded",
        "eventData":"",
        "seqNum":
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <timeToNextFetch>500</timeToNextFetch>
    <fetchBaseURL>http://10.10.10.10/aim/fetchEvents?seq=11</fetchBaseURL>
    <events>
    <event>
      <type>sessionEnded</type>
      <eventData></eventData>
      <seqNum></seqNum>
    </event>
    </events>
  </data>
</response>

Method: deleteEvents

To delete multiple events

URL: GET http://api.oscar.aol.com/aim/deleteEvents
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	aimsid	[Required] Use an AIM Session Id from the startSession call for authentication
Integer	eventNumber	[Required] event numbers to delete. Multiple allowed.

Output Fields

Type	Field	Description
Array of EventStatus	results	Events response status

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Example: http://api.oscar.aol.com/aim/deleteEvents?f=json&aimsid=AIMSID&eventNumber=1&eventNumber=2

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "results":[
      {
        "event":7,
        "code":0
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <results>
    <eventStatus>
      <event>7</event>
      <code>0</code>
    </eventStatus>
    </results>
  </data>
</response>

Method: endSession

To be used when the user logs out or navigates away from the application, endSession ends an Web AIM session and set this session offline. A sessionEnded event will be generated after the last event is retrieved, so the client knows when to stop fetching events. If there isn't a active fetchEvents for more then 30 seconds, the backend will auto end the session.

URL: GET http://api.oscar.aol.com/aim/endSession
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	aimsid	[Required] Use an AIM Session Id from the startSession call for authentication
Boolean	invalidateToken	[Default 1] - Sending request to SAAB to logout

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Example: http://api.oscar.aol.com/aim/endSession?f=json&k=MYKEY&c=callback&aimsid=AIMSID

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: setSessionParam

To set session parameters

URL: GET http://api.oscar.aol.com/aim/setSessionParam
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	[Required] Use an AIM Session Id from the startSession call for authentication
Integer	sessionTimeout	Time in seconds before terminating idle web session.
Event Type	tempEvents	Comma separated list of events to temporarily subscribe to, fetchEvents will only return these events. This can be used if the client is entering some mode where it only wants to receive a subset of the events subscribed to in the startSession
Integer	pollTimeout	Default value requested for fetchEvents, so client does not need to supply in each request
String	includePresenceFields	Comma separated list of fields to include in a presence object. This can be used to minimize data that the client does not use. You can also include "=" for any of the fields, so that the field will only be present if the value does not match the specified default value. Example: includePresenceFields=aimId,userType=icq,friendly
String	excludePresenceFields	Comma separated list of fields to exclude in a presence object. This can be used to minimize data that the client does not use. You can also include "=" for any of the fields, so that the field will only be present if the value does not match the specified default value. Example: excludePresenceFields=userType=icq,buddyIcon

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Example: http://api.oscar.aol.com/aim/setSessionParam?f=json&aimsid=AIMSID

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: aimStartPage

This method will redirect the caller to the correct AIM Start Page for given language. If WIM is being used from a web page then calling this api directly is enough. If WIM is being used from a clientLogin session or from the OSCAR protocol then a wrapping Single Signon call must be used. See here for an example of using Single Signon.

URL: GET http://api.oscar.aol.com/aim/getStartPage
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	language	the required language and locale of the error/status messages. This is always in "<lang>-<locale>" format. The lang is the 2 letter language code for I18N (default: en) and the locale is the 2 letter Locale code for I18N (default: us). If not passed in, the language will be extracted from HTTP header (Accept-Language) and if that is not available will default to "en-us".
String	k	[Required] the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls

Common Status Codes

Status Code	Description
200	Success
460	Missing required parameter
462	Parameter error

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: aimExpressionsPage

This method will redirect the caller to the correct AIM Expressions page for given language. If WIM is being used from a web page then calling this api directly is enough. If WIM is being used from a clientLogin session or from the OSCAR protocol then a wrapping Single Signon call must be used. See here for an example of using Single Signon.

URL: GET http://api.oscar.aol.com/aim/getExpressionsPage
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	language	the required language and locale of the error/status messages. This is always in "<lang>-<locale>" format. The lang is the 2 letter language code for I18N (default: en) and the locale is the 2 letter Locale code for I18N (default: us). If not passed in, the language will be extracted from HTTP header (Accept-Language) and if that is not available will default to "en-us".
String	k	[Required] the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls

Common Status Codes

Status Code	Description
200	Success
460	Missing required parameter
462	Parameter error

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: getHostBuddyInfo

Get host buddy info. Only valid format supported is html.

URL: GET http://api.oscar.aol.com/aim/getHostBuddyInfo
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
String	f	[Required] Only f=html is supported
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	t	Target to query buddy info for
Boolean	headerOn	[Default 0] - Set to 1 if needed header data returned in response.
String	language	the language and locale in "<lang>-<locale>" format. The lang is the 2 letter language code for I18N (default: en) and the locale is the 2 letter Locale code for I18N (default: us).

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: startOSCARSession

Start a OSCAR AIM session. This API requires that the token came from a previous clientLogin call and that the URL is signed. For a complete example on using startOSCARSession see the OSCAR Protocol Signon Example. URL signing requires the computers clock to be accurate or the use of hostTime returned by clientLogin, parameters must be in alphabetical order, and percent-encoding uses upper case characters.

URL: GET http://api.oscar.aol.com/aim/startOSCARSession
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	[Required] the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	a	[Required] Use an AOL Authentication Token for authentication, from the getToken call
Boolean	useTLS	Request the connection to BOSS use TLS
Integer	buildNumber	Build Number
Integer	majorVersion	Major Version, i.e for 1.2.3, major version = 1
Integer	minorVersion	Minor Version, i.e for 1.2.3, minor version = 2
Integer	pointVersion	Point Version, i.e for 1.2.3, point version = 3
String	clientName	Client name - clientLogin parameter
Integer	clientVersion	Client version - clientLogin parameter
String	language	the required language and locale of the error/status messages. This is always in "<lang>-<locale>" format. The lang is the 2 letter language code for I18N (default: en) and the locale is the 2 letter Locale code for I18N (default: us). If not passed in, the language will be extracted from HTTP header (Accept-Language) and if that is not available will default to "en-us".
Integer	ts	[Required] Epoch timestamp - clientLogin required parameter
String	sig_sha256	[Required] Signature - clientLogin required parameter.

Output Fields

Type	Field	Description
String	host	Host to connect to
String	port	Port to connect to
Array of Integer	ts	[Required] Epoch timestamp - clientLogin required parameter
String	cookie	Binary cookie to present to BOSS
String	tlsCertName	If TLS is being used then this is the cert name to verify for the boss connection

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
408	Timeout of the backend servers
460	Missing required parameter
462	Parameter error
607	Rate limit signing on, wait a few minutes before trying again

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "host":"10.1.2.3",
      "port":"5190",
      "ts":[
      
      ],
      "cookie":"base64ed data",
      "tlsCertName":"bos.oscar.aol.com"
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <host>10.1.2.3</host>
    <port>5190</port>
    <ts>
    <0></0>
    </ts>
    <cookie>base64ed data</cookie>
    <tlsCertName>bos.oscar.aol.com</tlsCertName>
  </data>
</response>

Method: addBuddy

Add a buddy to the buddylist.

URL: GET http://api.oscar.aol.com/buddylist/addBuddy
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
String	buddy	[Required] buddy name. Multiple buddy= parameters are allowed.
String	group	[Required] group name to add buddy to

Output Fields

Type	Field	Description
Array of AddBuddyResultCode	results	Result for each buddy

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call

Example: http://api.oscar.aol.com/buddylist/addBuddy?f=json&c=callback&aimsid=AIMSID&buddy=buddy1&group=groupABC

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "results":[
      {
        "buddy":"foo",
        "resultCode":"0 for success, non-0 for failure"
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <results>
    <result>
      <buddy>foo</buddy>
      <resultCode>0 for success, non-0 for failure</resultCode>
    </result>
    </results>
  </data>
</response>

Method: removeBuddy

Remove a buddy from the buddylist.

URL: GET http://api.oscar.aol.com/buddylist/removeBuddy
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	buddy	[Required] buddy name
String	group	[Required] group name to remove buddy from

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Example: http://api.oscar.aol.com/buddylist/removeBuddy?f=json&c=callback&aimsid=AIMSID&buddy=buddy1&group=groupABC

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: moveBuddy

Move a buddy inside a group or to a new group

URL: GET http://api.oscar.aol.com/buddylist/moveBuddy
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	group	[Required] Group buddy is in
String	buddy	[Required] Buddy to move
String	beforeBuddy	Move the buddy before this buddy, if not specified move the buddy to the end of the group
String	newGroup	Move the buddy to the end of this new group

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: setBuddyAttribute

Set an attribute for a buddy

URL: GET http://api.oscar.aol.com/buddylist/setBuddyAttribute
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	buddy	buddy name. Should only enter either buddy= or t=
String	t	buddy name. Should only enter either buddy= or t=
String	friendly	Friendly name
String	smsNumber	SMS number for buddy
String	workNumber	Work number for buddy
String	otherNumber	Other number for buddy
String	phoneNumber	Home number for buddy
String	note	note, max 80 bytes

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Example: http://api.oscar.aol.com/buddylist/setBuddyAttribute?f=json&c=callback&aimsid=AIMSID&buddy=buddy1&friendly=

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: getBuddyAttribute

Get some buddy's attributes

URL: GET http://api.oscar.aol.com/buddylist/getBuddyAttribute
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	buddy	buddy name. Should only enter either buddy= or t=
String	t	buddy name. Should only enter either buddy= or t=

Output Fields

Type	Field	Description
String	friendly	Friendly name
String	smsNumber	SMS number for buddy
String	workNumber	Work number for buddy
String	otherNumber	Other number for buddy
String	homeNumber	Home number for buddy
String	note	note

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Example: http://api.oscar.aol.com/buddylist/getBuddyAttribute?f=json&c=callback&aimsid=AIMSID&buddy=buddy1

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "friendly":"",
      "smsNumber":"",
      "workNumber":"",
      "otherNumber":"",
      "homeNumber":"",
      "note":""
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <friendly></friendly>
    <smsNumber></smsNumber>
    <workNumber></workNumber>
    <otherNumber></otherNumber>
    <homeNumber></homeNumber>
    <note></note>
  </data>
</response>

Method: addGroup

Add an empty group to the buddylist.

URL: GET http://api.oscar.aol.com/buddylist/addGroup
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	[Required] Use an AIM Session Id from the startSession call for authentication
String	group	[Required] group name to add

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Example: http://api.oscar.aol.com/buddylist/addGroup?f=json&c=callback&aimsid=AIMSID&group=groupABC

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: removeGroup

Remove a group from the buddylist when possible, if the group doesn't exist the API still returns SUCCESS

URL: GET http://api.oscar.aol.com/buddylist/removeGroup
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	group	[Required] group name to remove

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Example: http://api.oscar.aol.com/buddylist/removeGroup?f=json&c=callback&aimsid=AIMSID&group=groupABC

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: renameGroup

Rename a group in the buddylist.

URL: GET http://api.oscar.aol.com/buddylist/renameGroup
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	oldGroup	[Required] Name of group to rename
String	newGroup	[Required] New name for group

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	If oldGroup doesn't exist or if newGroup already exists

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Example: http://api.oscar.aol.com/buddylist/renameGroup?f=json&c=callback&aimsid=AIMSID&oldGroup=groupABC&newGroup=groupDEF

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: moveGroup

Move a group

URL: GET http://api.oscar.aol.com/buddylist/moveGroup
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	group	[Required] Group to move. Recent Buddies and Offline groups can't be moved
String	beforeGroup	Move the group before this group, if missing or group does not exist moving to the end.

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: setGroupAttribute

Set an attribute for a group

URL: GET http://api.oscar.aol.com/buddylist/setGroupAttribute
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	group	[Required] group name
Boolean	collapsed	Is the group collapsed or not

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Example: http://api.oscar.aol.com/buddylist/setGroupAttribute?f=json&c=callback&aimsid=AIMSID&group=group&collapsed=

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: copyBuddyLists

Copy entire Buddy List and all host based settings from one account to another account. The existing Buddy List and all host based settings of the copy-to account will be completely replaced. This method is tricky in that two web auth tokens must be provided.

URL: GET http://api.oscar.aol.com/buddylist/copy
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	[Required] the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	a	Use an AOL Authentication Token for authentication, from the getToken call
String	ta	[Required] Target token, where the source users buddylist should be copied to

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call

Example: http://api.oscar.aol.com/buddylist/copy?f=json&k=MYKEY&c=callback&a=SRCTOKEN&ta=TGTTOKEN

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: addTempBuddy

Add a temporary buddy for presence updates

URL: GET http://api.oscar.aol.com/aim/addTempBuddy
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	aimsid	[Required] Use an AIM Session Id from the startSession call for authentication
String	t	[Required] buddy name, multiple t= parameters are allowed

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Example: http://api.oscar.aol.com/aim/addTempBuddy?f=json&c=callback&aimsid=AIMSID&t=msft@relegence.com

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: removeTempBuddy

Remove a temporary buddy for presence updates

URL: GET http://api.oscar.aol.com/aim/removeTempBuddy
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	aimsid	[Required] Use an AIM Session Id from the startSession call for authentication
String	t	[Required] Buddy name, multiple t= parameters are allowed

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Example: http://api.oscar.aol.com/aim/removeTempBuddy?f=json&c=callback&aimsid=AIMSID&t=msft@relegence.com

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: getPresence

Get the Presence information for one or more target users. Can also be used to retrieve the presence for the entire Buddy List. Can be used with an aimsid, with a token, or anonymously with no aimsid or token. In anonymous mode only users who allow anonymous presence will appear online. The Buddy List query does not work anonymously, for obvious reasons. To reduce the amount of data returned, it is possible to turn some of the fields off.

This method allows both Web AIM Keys and the previously support Presence Keys.

URL: GET http://api.oscar.aol.com/presence/get
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	[Required] either an AIM Web Key or AIM Presence Key from http://dev.aol.com/aim
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	t	Target aimIds, returns the results in the users section. Multiple t parameters are allowed
String	tw	Wimzi key target, returns the results in the users section. Multiple tw parameters are allowed
Boolean	bl	Not valid for anonymous queries, returns the Buddy List in the groups section
Boolean	emailLookup	[Default 0] - For targets, do an email look up and return presence on valid aimIds
Boolean	notFound	[Default 0] - For email lookups that fail, use a special not found icon instead of offline
Boolean	awayMsg	[Default 0] - Return away messages
Boolean	profileMsg	[Default 0] - Return profile messages
Boolean	presenceIcon	[Default 1] - Return presence icon
Boolean	location	[Default 1] - Return location information
Boolean	capabilities	[Default 0] - Return capability information
Boolean	memberSince	[Default 0] - Return member since information
Boolean	statusMsg	[Default 0] - Return status message information
Boolean	friendly	[Default 0] - Return friendly name

Output Fields

Type	Field	Description
Array of Group	groups	List of buddylist groups
Array of Presence	users	Target aimId, multiple t parameters are allowed

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Example: http://api.oscar.aol.com/presence/get?f=json&k=MYKEY&c=callback&aimsid=AIMSID&t=ChattingChuck& awayMsg=1&profileMsg=1

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "groups":[
      {
        "name":"Friends",
        "collapsed":,
        "recent":,
        "bot":,
        "shared":,
        "smart":,
        "imserv":"",
        "buddies":[
        {
          "aimId":"chattingchuck",
          "displayId":"ChattingChuck",
          "friendly":"Chuck my Buddy",
          "state":"away",
          "onlineTime":100,
          "awayTime":10,
          "statusTime":100,
          "awayMsg":"I'm busy right now chatting.",
          "profileMsg":"My name is Chuck, and I live on AIM.",
          "statusMsg":"Look at me!",
          "buddyIcon":"",
          "presenceIcon":"http://o.aolcdn.com/aim/img/away.gif",
          "capabilities":[
          "200A0000A28911D3A52D001083341CFA"
          ],
          "location":{
            "desc":"AOL Office",
            "street":"SULLY RD",
            "city":"STERLING",
            "country":"US",
            "state":"VA",
            "postcode":"20166",
            "accuracy":"100",
            "lat":"38.986750",
            "lon":"-77.430500",
            "accu_string":"Block1"
          },
          "ipCountry":"",
          "smsSegment":{
            "single":,
            "initial":,
            "trailing":
          },
          "userType":"aim",
          "updatedBuddyInfo":
        }
        ]
      }
      ],
      "users":[
      {
        "aimId":"chattingchuck",
        "displayId":"ChattingChuck",
        "friendly":"Chuck my Buddy",
        "state":"away",
        "onlineTime":100,
        "awayTime":10,
        "statusTime":100,
        "awayMsg":"I'm busy right now chatting.",
        "profileMsg":"My name is Chuck, and I live on AIM.",
        "statusMsg":"Look at me!",
        "buddyIcon":"",
        "presenceIcon":"http://o.aolcdn.com/aim/img/away.gif",
        "capabilities":[
        "200A0000A28911D3A52D001083341CFA"
        ],
        "location":{
          "desc":"AOL Office",
          "street":"SULLY RD",
          "city":"STERLING",
          "country":"US",
          "state":"VA",
          "postcode":"20166",
          "accuracy":"100",
          "lat":"38.986750",
          "lon":"-77.430500",
          "accu_string":"Block1"
        },
        "ipCountry":"",
        "smsSegment":{
          "single":,
          "initial":,
          "trailing":
        },
        "userType":"aim",
        "updatedBuddyInfo":
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <groups>
    <group>
      <name>Friends</name>
      <collapsed></collapsed>
      <recent></recent>
      <bot></bot>
      <shared></shared>
      <smart></smart>
      <imserv></imserv>
      <buddies>
      <buddy>
        <aimId>chattingchuck</aimId>
        <displayId>ChattingChuck</displayId>
        <friendly>Chuck my Buddy</friendly>
        <state>away</state>
        <onlineTime>100</onlineTime>
        <awayTime>10</awayTime>
        <statusTime>100</statusTime>
        <awayMsg>I'm busy right now chatting.</awayMsg>
        <profileMsg>My name is Chuck, and I live on AIM.</profileMsg>
        <statusMsg>Look at me!</statusMsg>
        <buddyIcon></buddyIcon>
        <presenceIcon>http://o.aolcdn.com/aim/img/away.gif</presenceIcon>
        <capabilities>
        <capability>200A0000A28911D3A52D001083341CFA</capability>
        </capabilities>
        <location>
          <desc>AOL Office</desc>
          <street>SULLY RD</street>
          <city>STERLING</city>
          <country>US</country>
          <state>VA</state>
          <postcode>20166</postcode>
          <accuracy>100</accuracy>
          <lat>38.986750</lat>
          <lon>-77.430500</lon>
          <accu_string>Block1</accu_string>
        </location>
        <ipCountry></ipCountry>
        <smsSegment>
          <single></single>
          <initial></initial>
          <trailing></trailing>
        </smsSegment>
        <userType>aim</userType>
        <updatedBuddyInfo></updatedBuddyInfo>
      </buddy>
      </buddies>
    </group>
    </groups>
    <users>
    <user>
      <aimId>chattingchuck</aimId>
      <displayId>ChattingChuck</displayId>
      <friendly>Chuck my Buddy</friendly>
      <state>away</state>
      <onlineTime>100</onlineTime>
      <awayTime>10</awayTime>
      <statusTime>100</statusTime>
      <awayMsg>I'm busy right now chatting.</awayMsg>
      <profileMsg>My name is Chuck, and I live on AIM.</profileMsg>
      <statusMsg>Look at me!</statusMsg>
      <buddyIcon></buddyIcon>
      <presenceIcon>http://o.aolcdn.com/aim/img/away.gif</presenceIcon>
      <capabilities>
      <capability>200A0000A28911D3A52D001083341CFA</capability>
      </capabilities>
      <location>
        <desc>AOL Office</desc>
        <street>SULLY RD</street>
        <city>STERLING</city>
        <country>US</country>
        <state>VA</state>
        <postcode>20166</postcode>
        <accuracy>100</accuracy>
        <lat>38.986750</lat>
        <lon>-77.430500</lon>
        <accu_string>Block1</accu_string>
      </location>
      <ipCountry></ipCountry>
      <smsSegment>
        <single></single>
        <initial></initial>
        <trailing></trailing>
      </smsSegment>
      <userType>aim</userType>
      <updatedBuddyInfo></updatedBuddyInfo>
    </user>
    </users>
  </data>
</response>

Method: getBuddyListPresence

There is no special getBuddyList method, instead the getPresence API can be used with a special bl=1 parameter.

URL: GET http://api.oscar.aol.com/presence/get
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	[Required] either an AIM Web Key or AIM Presence Key from http://dev.aol.com/aim
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	t	Target aimIds, returns the results in the users section. Multiple t parameters are allowed
Boolean	bl	returns the Buddy List in the groups section

Output Fields

Type	Field	Description
Array of Group	groups	List of buddylist groups
Array of Presence	users	Target aimId, multiple t parameters are allowed

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Example: http://api.oscar.aol.com/presence/get?f=json&k=MYKEY&c=callback&a=token&t=ChattingChuck&bl=1

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "groups":[
      {
        "name":"Friends",
        "collapsed":,
        "recent":,
        "bot":,
        "shared":,
        "smart":,
        "imserv":"",
        "buddies":[
        {
          "aimId":"chattingchuck",
          "displayId":"ChattingChuck",
          "friendly":"Chuck my Buddy",
          "state":"away",
          "onlineTime":100,
          "awayTime":10,
          "statusTime":100,
          "awayMsg":"I'm busy right now chatting.",
          "profileMsg":"My name is Chuck, and I live on AIM.",
          "statusMsg":"Look at me!",
          "buddyIcon":"",
          "presenceIcon":"http://o.aolcdn.com/aim/img/away.gif",
          "capabilities":[
          "200A0000A28911D3A52D001083341CFA"
          ],
          "location":{
            "desc":"AOL Office",
            "street":"SULLY RD",
            "city":"STERLING",
            "country":"US",
            "state":"VA",
            "postcode":"20166",
            "accuracy":"100",
            "lat":"38.986750",
            "lon":"-77.430500",
            "accu_string":"Block1"
          },
          "ipCountry":"",
          "smsSegment":{
            "single":,
            "initial":,
            "trailing":
          },
          "userType":"aim",
          "updatedBuddyInfo":
        }
        ]
      }
      ],
      "users":[
      {
        "aimId":"chattingchuck",
        "displayId":"ChattingChuck",
        "friendly":"Chuck my Buddy",
        "state":"away",
        "onlineTime":100,
        "awayTime":10,
        "statusTime":100,
        "awayMsg":"I'm busy right now chatting.",
        "profileMsg":"My name is Chuck, and I live on AIM.",
        "statusMsg":"Look at me!",
        "buddyIcon":"",
        "presenceIcon":"http://o.aolcdn.com/aim/img/away.gif",
        "capabilities":[
        "200A0000A28911D3A52D001083341CFA"
        ],
        "location":{
          "desc":"AOL Office",
          "street":"SULLY RD",
          "city":"STERLING",
          "country":"US",
          "state":"VA",
          "postcode":"20166",
          "accuracy":"100",
          "lat":"38.986750",
          "lon":"-77.430500",
          "accu_string":"Block1"
        },
        "ipCountry":"",
        "smsSegment":{
          "single":,
          "initial":,
          "trailing":
        },
        "userType":"aim",
        "updatedBuddyInfo":
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <groups>
    <group>
      <name>Friends</name>
      <collapsed></collapsed>
      <recent></recent>
      <bot></bot>
      <shared></shared>
      <smart></smart>
      <imserv></imserv>
      <buddies>
      <buddy>
        <aimId>chattingchuck</aimId>
        <displayId>ChattingChuck</displayId>
        <friendly>Chuck my Buddy</friendly>
        <state>away</state>
        <onlineTime>100</onlineTime>
        <awayTime>10</awayTime>
        <statusTime>100</statusTime>
        <awayMsg>I'm busy right now chatting.</awayMsg>
        <profileMsg>My name is Chuck, and I live on AIM.</profileMsg>
        <statusMsg>Look at me!</statusMsg>
        <buddyIcon></buddyIcon>
        <presenceIcon>http://o.aolcdn.com/aim/img/away.gif</presenceIcon>
        <capabilities>
        <capability>200A0000A28911D3A52D001083341CFA</capability>
        </capabilities>
        <location>
          <desc>AOL Office</desc>
          <street>SULLY RD</street>
          <city>STERLING</city>
          <country>US</country>
          <state>VA</state>
          <postcode>20166</postcode>
          <accuracy>100</accuracy>
          <lat>38.986750</lat>
          <lon>-77.430500</lon>
          <accu_string>Block1</accu_string>
        </location>
        <ipCountry></ipCountry>
        <smsSegment>
          <single></single>
          <initial></initial>
          <trailing></trailing>
        </smsSegment>
        <userType>aim</userType>
        <updatedBuddyInfo></updatedBuddyInfo>
      </buddy>
      </buddies>
    </group>
    </groups>
    <users>
    <user>
      <aimId>chattingchuck</aimId>
      <displayId>ChattingChuck</displayId>
      <friendly>Chuck my Buddy</friendly>
      <state>away</state>
      <onlineTime>100</onlineTime>
      <awayTime>10</awayTime>
      <statusTime>100</statusTime>
      <awayMsg>I'm busy right now chatting.</awayMsg>
      <profileMsg>My name is Chuck, and I live on AIM.</profileMsg>
      <statusMsg>Look at me!</statusMsg>
      <buddyIcon></buddyIcon>
      <presenceIcon>http://o.aolcdn.com/aim/img/away.gif</presenceIcon>
      <capabilities>
      <capability>200A0000A28911D3A52D001083341CFA</capability>
      </capabilities>
      <location>
        <desc>AOL Office</desc>
        <street>SULLY RD</street>
        <city>STERLING</city>
        <country>US</country>
        <state>VA</state>
        <postcode>20166</postcode>
        <accuracy>100</accuracy>
        <lat>38.986750</lat>
        <lon>-77.430500</lon>
        <accu_string>Block1</accu_string>
      </location>
      <ipCountry></ipCountry>
      <smsSegment>
        <single></single>
        <initial></initial>
        <trailing></trailing>
      </smsSegment>
      <userType>aim</userType>
      <updatedBuddyInfo></updatedBuddyInfo>
    </user>
    </users>
  </data>
</response>

Method: getPresenceIcon

This method call is a short cut to the anonymous presence icon for a user or email address, returning a HTTP 302 redirect to the correct standard presence icon.

URL: GET http://api.oscar.aol.com/presence/icon
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
String	r	Request id
String	k	[Required] the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	t	Target aimId, only one t or tw is allowed
String	tw	Wimzi key, only one t or tw is allowed
Boolean	emailLookup	For targets, do an email look up and return presence on valid aimIds
Boolean	notFound	For email lookups that fail, use a special not found icon instead of offline

Common Status Codes

Status Code	Description
200	Success
460	Missing required parameter
462	Parameter error

Example: <img src="http://api.oscar.aol.com/presence/icon?&k=MYKEY&t=ChattingChuck">

Method: setState

Sets the user's Presence information. The setState method call requires an aimsid from a previous startSession call.

URL: GET http://api.oscar.aol.com/presence/setState
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	aimsid	[Required] Use an AIM Session Id from the startSession call for authentication
Presence State	view	[Required] How we should appear to other users, offline and mobile are not valid in this case
String	away	If setting the state to away, this is the away message display to other users on mouse over
Boolean	encodeData	Base 64 encode the data in imdata events
Capability	assertCaps	Comma separated list of capabilities to assert to other users.
Capability	interestCaps	Comma separated list of capabilities to receive from other users. AssertCaps will also be received from other users.
String	friendly	For anonymous sessions, this is an optional friendly name to display
Boolean	invisible	Invisible

Output Fields

Type	Field	Description
Presence	myInfo	Information about the logged in user after applying the state change

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Example: http://api.oscar.aol.com/presence/setState?f=json&k=MYKEY&c=callback&aimsid=AIMSID&view=away&away=Gone

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "myInfo":{
        "aimId":"chattingchuck",
        "displayId":"ChattingChuck",
        "friendly":"Chuck my Buddy",
        "state":"away",
        "onlineTime":100,
        "awayTime":10,
        "statusTime":100,
        "awayMsg":"I'm busy right now chatting.",
        "profileMsg":"My name is Chuck, and I live on AIM.",
        "statusMsg":"Look at me!",
        "buddyIcon":"",
        "presenceIcon":"http://o.aolcdn.com/aim/img/away.gif",
        "capabilities":[
        "200A0000A28911D3A52D001083341CFA"
        ],
        "location":{
          "desc":"AOL Office",
          "street":"SULLY RD",
          "city":"STERLING",
          "country":"US",
          "state":"VA",
          "postcode":"20166",
          "accuracy":"100",
          "lat":"38.986750",
          "lon":"-77.430500",
          "accu_string":"Block1"
        },
        "ipCountry":"",
        "smsSegment":{
          "single":,
          "initial":,
          "trailing":
        },
        "userType":"aim",
        "updatedBuddyInfo":
      }
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <myInfo>
      <aimId>chattingchuck</aimId>
      <displayId>ChattingChuck</displayId>
      <friendly>Chuck my Buddy</friendly>
      <state>away</state>
      <onlineTime>100</onlineTime>
      <awayTime>10</awayTime>
      <statusTime>100</statusTime>
      <awayMsg>I'm busy right now chatting.</awayMsg>
      <profileMsg>My name is Chuck, and I live on AIM.</profileMsg>
      <statusMsg>Look at me!</statusMsg>
      <buddyIcon></buddyIcon>
      <presenceIcon>http://o.aolcdn.com/aim/img/away.gif</presenceIcon>
      <capabilities>
      <capability>200A0000A28911D3A52D001083341CFA</capability>
      </capabilities>
      <location>
        <desc>AOL Office</desc>
        <street>SULLY RD</street>
        <city>STERLING</city>
        <country>US</country>
        <state>VA</state>
        <postcode>20166</postcode>
        <accuracy>100</accuracy>
        <lat>38.986750</lat>
        <lon>-77.430500</lon>
        <accu_string>Block1</accu_string>
      </location>
      <ipCountry></ipCountry>
      <smsSegment>
        <single></single>
        <initial></initial>
        <trailing></trailing>
      </smsSegment>
      <userType>aim</userType>
      <updatedBuddyInfo></updatedBuddyInfo>
    </myInfo>
  </data>
</response>

Method: setStatus

Sets the user's status message.

URL: GET http://api.oscar.aol.com/presence/setStatus
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	statusMsg	[Required] status message display to other users
Boolean	beboFlag	This request is initiated by a Bebo client
String	mediaId	Identifier for photo/media associated with status. Can be multiple.

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Example: http://api.oscar.aol.com/presence/setStatus?f=json&c=callback&aimsid=AIMSID&statusMsg=mystatus

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: setProfile

Set the AIM buddy info for a user.

URL: GET http://api.oscar.aol.com/presence/setProfile
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	profile	[Required] The new AIM Profile, or blank to clear the current AIM Profile

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Example: http://api.oscar.aol.com/presence/setProfile?f=json&k=MYKEY&c=callback&aimsid=AIMSID&profile="Profile Message"

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: getProfile

Get the AIM Profile message for an aimId .

URL: GET http://api.oscar.aol.com/presence/getProfile
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.

Output Fields

Type	Field	Description
String	profileMsg	AIM Profile Message

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Example: http://api.oscar.aol.com/presence/getProfile?f=json&k=MYKEY&c=callback&s=ChattingChuck

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "profileMsg":"Profile Message"
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <profileMsg>Profile Message</profileMsg>
  </data>
</response>

Method: sendIM

Send an IM to an AIM user. Requires a valid aimsid from the startSession call or an AOL Authentication Token.

URL: GET http://api.oscar.aol.com/im/sendIM
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	a	Use an AOL Authentication Token for authentication, from the getToken call
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	t	[Required] Destination aimId
String	message	[Required] utf8 encoded message, limited to 1024 bytes
Boolean	autoResponse	Set the auto response flag be set, can not be set with offlineIM
Boolean	displaySMSSegmentData	[Default false] - Set true to display SMS segment data
Boolean	offlineIM	Deliver as an offline IM when possible if the user isn't online, autoResponse flag can no bet set

Output Fields

Type	Field	Description
SendImSubCode	subCode	subcode

Common Status Codes

Status Code	Description
200	Success
400	Session does not exist
401	Authorization required
430	Sending IMs too fast
450	Consent required, use the redirectURL and append a k=KEY to it
460	Missing required parameter
462	Parameter error
602	Target user is not available
603	Target user is blocked
606	Message is too large

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Example: http://api.oscar.aol.com/im/sendIM?f=json&k=MYKEY&c=callback&aimsid=AIMSID&msg=Hi&t=ChattingChuck

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "subCode":{
        "subError":"",
        "subReason":""
      }
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <subCode>
      <subError></subError>
      <subReason></subReason>
    </subCode>
  </data>
</response>

Method: sendDataIM

Send a Data IM to an AIM user. Requires a valid aimsid from the startSession call or an AOL Authentication Token.

URL: GET http://api.oscar.aol.com/im/sendDataIM
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	a	Use an AOL Authentication Token for authentication, from the getToken call
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	t	[Required] Destination aimId
Capability	cap	[Required] AIM Capability
Data IM Type	type	[Required] Type of Message
String	data	[Required] Data to send remote AIM user.
Boolean	dataIsBase64	If present, then the data parameter is base64 encoded
Boolean	autoResponse	Should the auto response flag be set
String	inviteMsg	For the invite message type, and optional invite message can be included
String	cookie	Base64 encoded cookie for this conversation
String	ip	IPv4 address recipient can connect to for peer-to-peer conversation
Integer	port	Port used in conjunction with ipAddr for connection
String	proposerIp	Internal IP address of client
Boolean	hostCheck	Host will check remote user to verify they have requested capability [Default 1]
Boolean	useRS	Use Relay server. ip will be from RS and not a peer [Default 0]
Integer	sequenceNum	Sequence number for proposal. Must increment by 1

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
430	Sending IMs too fast
450	Consent required, use the redirectURL and append a k=KEY to it
460	Missing required parameter
462	Parameter error
602	Target user is not available
605	Target user doesn't support the capability
606	Message is too large

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Example: http://api.oscar.aol.com/im/sendDataIM?f=json&k=MYKEY&c=callback&aimsid=AIMSID&data={data}&t=ChattingChuck& cookie=MTIzNDU2NzgK

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: rejectDataIM

Reject a Data IM from a user. Requires a valid aimsid from the startSession call or an AOL Authentication Token.

URL: GET http://api.oscar.aol.com/im/rejectDataIM
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	a	Use an AOL Authentication Token for authentication, from the getToken call
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	t	[Required] Destination aimId
String	cookie	[Required] base64 encoded converstation cookie
Reject Reason	reason	[Required] Reason for reject

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
430	Sending IMs too fast
450	Consent required, use the redirectURL and append a k=KEY to it
460	Missing required parameter
462	Parameter error
602	Target user is not available
605	Target user doesn't support the capability
606	Message is too large

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Example: http://api.oscar.aol.com/im/rejectDataIM?f=json&k=MYKEY&c=callback&aimsid=AIMSID&reason=denied&t=ChattingChuck&cookie=MTIzNDU2NzgK

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: setTyping

Set the current typing status. Only send a typing status on event change - there is no need to send a typing for every key press. Requires a valid aimsid from the startSession call.

URL: GET http://api.oscar.aol.com/im/setTyping
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	aimsid	[Required] Use an AIM Session Id from the startSession call for authentication
String	t	[Required] Destination aimId
Typing Status	typingStatus	[Required] The new typing status

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Example: http://api.oscar.aol.com/im/send?f=json&k=MYKEY&c=callback&aimsid=AIMSID&typingStatus=typing&t=ChattingChuck

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: getExpression

Returns the expression information - the personalized icons, sounds, and background images - for an AIM user. This routine supports two extra format parameters, both of which require the type= parameter to be set:

native - Return the binary data directly. For example with buddy icons can be used to embedded the image using a img tag. The type parameter is required.
redirect - Similiar to native, except use a redirect to fetch the binary data. This will eventually allow the browser to cache better. The type parameter is required.

URL: GET http://api.oscar.aol.com/expressions/get
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	t	[Required] Target aimId
Expression Type	type	The type of expression to return, if missing all expressions are returned. Required for the native and redirect format
String	defaultId	If the user doesn't have an expression, use this one instead
String	personality	personality name
String	text	emoticon text, i.e :-)
Boolean	noCustom	[Default 0] - if true a custom item isn't returned, instead the defaultId is returned if available

Output Fields

Type	Field	Description
Array of Expression	expressions	In JSON or Simple XML mode description of the expressions

Common Status Codes

Status Code	Description
200	Success
460	Missing required parameter
462	Parameter error

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "expressions":[
      {
        "type":"buddyIcon",
        "id":"050201020304",
        "url":"http://api.oscar.aol.com/get"
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <expressions>
    <expression>
      <type>buddyIcon</type>
      <id>050201020304</id>
      <url>http://api.oscar.aol.com/get</url>
    </expression>
    </expressions>
  </data>
</response>

Method: getPersonalities

Returns the personalities information - a container for the personalized icons, sounds, and background images - for an AIM user.

URL: GET http://api.oscar.aol.com/expressions/getPersonalities
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	t	[Required] Target aimId
Boolean	withExpressions	[Default 0] - if true all the expressions are returned for each personality

Output Fields

Type	Field	Description
Array of Personality	personalities	In JSON or Simple XML mode description of the personalities

Common Status Codes

Status Code	Description
200	Success
460	Missing required parameter
462	Parameter error

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "personalities":[
      {
        "name":"myPersonality",
        "expressions":[
        {
          "type":"buddyIcon",
          "id":"050201020304",
          "url":"http://api.oscar.aol.com/get"
        }
        ]
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <personalities>
    <personality>
      <name>myPersonality</name>
      <expressions>
      <expression>
        <type>buddyIcon</type>
        <id>050201020304</id>
        <url>http://api.oscar.aol.com/get</url>
      </expression>
      </expressions>
    </personality>
    </personalities>
  </data>
</response>

Method: getAsset

Get the binary asset, you really probably don't want to use this call since this is ID based and not user based

URL: GET http://api.oscar.aol.com/expressions/getAsset
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
String	c	JSONP callback
String	r	Request id
String	f	[Required] native
String	t	Target aimId
Expression Type	type	[Required] The type of expression to return
String	id	[Required] The bart id
String	text	emoticon text, i.e :-)
String	defaultId	If expression doesn't exist, use this one instead

Common Status Codes

Status Code	Description
200	Success
460	Missing required parameter
462	Parameter error

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: setExpression

Set the expression information - the personalized icons, sounds, and background images - for an AIM user.

URL: GET http://api.oscar.aol.com/expressions/set
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
Expression Type	type	[Required] The type of expression to set
String	id	[Required] The id of expression to set
String	typeAndId	[Required] The type and ID in the form of type:id. Multiple may be present. Ex: typeAndId=buddyIcon:0050201020304
String	personality	The name of the specific personality set

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error, such as bad type or id

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Example: http://api.oscar.aol.com/expressions/set?f=json&k=MYKEY&c=callback&aimsid=AIMSID&type=buddyIcon&id=00050201020304

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: uploadExpression

Upload a custom expression

URL: POST http://api.oscar.aol.com/expressions/upload

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
Expression Type	type	[Required] The type of expression being uploaded

Output Fields

Type	Field	Description
String	id	The id of the expression uploaded, can be used with setExpression after stripping the leading 4 hex digits.

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error, such as bad type or id

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "id":""
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <id></id>
  </data>
</response>

Method: googleEarth.kml

A Google Earth Network Link that contains all different items supported

URL: GET http://api.oscar.aol.com/location/googleEarth.kml

Common Status Codes

Status Code	Description
200	Success
460	Missing required parameter
462	Parameter error

Method: getRankedUsersLocations.kml

A Google Earth Network Link that displays the locations of AIM Fight ranked users.

URL: GET http://api.oscar.aol.com/location/getRankedUsers.kml

Common Status Codes

Status Code	Description
200	Success
460	Missing required parameter
462	Parameter error

Method: getRankedUsersLocations

Return the locations of AIM Fight ranked users. The format parameter f=kml is also supported for Google Earth output

URL: GET http://api.oscar.aol.com/location/getRankedUsers

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	[Required] the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
Integer	maxLocations	Max number of locations returned, locations are sorted by number of users
String	boundingBox	[bboxWest],[bboxSouth],[bboxEast],[bboxNorth] - Return only items inside the bounding box

Output Fields

Type	Field	Description
Array of RankedUsersLocation	locations	Ranked Users Locations

Common Status Codes

Status Code	Description
200	Success
460	Missing required parameter
462	Parameter error

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "locations":[
      {
        "name":"washington, dc",
        "count":100,
        "lat":38.910,
        "lon":-77.018
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <locations>
    <location>
      <name>washington, dc</name>
      <count>100</count>
      <lat>38.910</lat>
      <lon>-77.018</lon>
    </location>
    </locations>
  </data>
</response>

Method: getIMConversationsLocations.kml

A Google Earth Network Link that displays IM conversations initiated in the last minute. The conversations are aged out over time.

URL: GET http://api.oscar.aol.com/location/getIMConversations.kml

Common Status Codes

Status Code	Description
200	Success
460	Missing required parameter
462	Parameter error

Method: getIMConversationsLocations

Return the locations for recently intiated IM conversations. The conversations are aged out over time.

URL: GET http://api.oscar.aol.com/location/getIMConversations

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	[Required] the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
Integer	maxLocations	Max number of locations returned, locations are sorted by age and number of users
String	boundingBox	[bboxWest],[bboxSouth],[bboxEast],[bboxNorth] - Return only items where one of the two points are inside the bounding box

Output Fields

Type	Field	Description
Array of IMConversationLocation	locations	IM Conversation Locations

Common Status Codes

Status Code	Description
200	Success
460	Missing required parameter
462	Parameter error

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "locations":[
      {
        "name":"washington, dc - los angeles, ca",
        "count":10,
        "age":0,
        "lat1":38.910,
        "lon1":-77.018,
        "lat2":33.973,
        "lon2":-118.249
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <locations>
    <location>
      <name>washington, dc - los angeles, ca</name>
      <count>10</count>
      <age>0</age>
      <lat1>38.910</lat1>
      <lon1>-77.018</lon1>
      <lat2>33.973</lat2>
      <lon2>-118.249</lon2>
    </location>
    </locations>
  </data>
</response>

Method: setPreference

Set preferences

URL: GET http://api.oscar.aol.com/preference/set
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
Boolean	Preferences	[Required] The preference to set, the field name isn't Preferences, instead it is a value from the enumeration

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Example: http://api.oscar.aol.com/preference/set?f=json&k=KEY&c=callback&a=AOLAUTHTOKEN&displayLogin=1&showBuddyFeed=0

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: getPreference

Get preferences

URL: GET http://api.oscar.aol.com/preference/get
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
Boolean	Preferences	Optional selector of which preferences to return, otherwise all are returned

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Example: http://api.oscar.aol.com/preference/get?f=json&k=KEY&c=callback&a=AOLAUTHTOKEN

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

Method: getVanityInfo

Retrieve the vanity information for a user.

URL: GET http://api.oscar.aol.com/aim/getVanityInfo
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
Boolean	includeBuddyCount	Request for number of unique real buddies on the buddy list
Boolean	includeWatcherCount	Request for number of reverse buddies - buddies that are watching you

Output Fields

Type	Field	Description
Integer	imsSent	Number of IMs the user has sent during the collection interval
Integer	imsReceived	Number of IMs the user has received during the collection interval
Integer	awayMsgs	Number of away messages set during the collection interval
Integer	onlineTime	Minutes online
Integer	collectionInterval	Minutes since the first time data was collected
Integer	uniqueBuddyCount	Number of unique real buddies
Integer	watcherCount	Number of watchers

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "imsSent":10,
      "imsReceived":20,
      "awayMsgs":30,
      "onlineTime":30,
      "collectionInterval":300,
      "uniqueBuddyCount":,
      "watcherCount":
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <imsSent>10</imsSent>
    <imsReceived>20</imsReceived>
    <awayMsgs>30</awayMsgs>
    <onlineTime>30</onlineTime>
    <collectionInterval>300</collectionInterval>
    <uniqueBuddyCount></uniqueBuddyCount>
    <watcherCount></watcherCount>
  </data>
</response>

Method: setAvTrack

Set avTrack

URL: GET http://api.oscar.aol.com/aim/setAvTrack
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	title	track name
String	uri	where to access track directly
String	image	image reference of a track, multiple can be handled. An example to set image : image=width=64,height=64,src=http://image.allmusic.com//00/amg/cov200/drf500/f555/f55590zg6bm.jpg,contentTag=album cover,contentTag=artist logo. Note that in addition to any URL encoding needed to get special characters into a field(i.e contentTag) value, the resulting value of image must be URL encoded for sending.
Integer	startDate	Unix EPOCH time when the track starts playing
String	album	album name
String	albumLink	album link
String	artist	artist name
String	artistLink	artist link
String	genre	multiple entries are allowed
String	playlist	playlist name
String	playlistLink	playlist link
String	podcast	podcast name
String	podcastLink	podcast link
String	series	series name
String	seriesLink	series link

Output Fields

Type	Field	Description
String	id	The id of the avtrack uploaded in hex

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Example: http://api.oscar.aol.com/aim/setAvTrack?f=json&k=KEY&c=callback&a=mytoken&album=myalbum

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "id":""
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <id></id>
  </data>
</response>

Method: getAvTrack

Get avTrack.

URL: GET http://api.oscar.aol.com/aim/getAvTrack
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	[Required] the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	t	target name to get avtrack for. Multiple t= parameters are allowed.
Boolean	bl	Return avtrack for buddies on the buddy list.

Output Fields

Type	Field	Description
Array of AvTrackInfo	tracks	Track info if exists, can be empty on timeout

Common Status Codes

Status Code	Description
200	Success
460	Missing required parameter
462	Parameter error

Example: http://api.oscar.aol.com/aim/getAvTrack?f=json&k=MYKEY&c=callback

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "tracks":[
      {
        "startDate":,
        "Duration":,
        "t":"",
        "statusCode":"",
        "title":"",
        "uri":"",
        "album":"",
        "albumLink":"",
        "artist":"",
        "artistLink":"",
        "genres":[
        ""
        ],
        "playlist":"",
        "playlistLink":"",
        "podcast":"",
        "podcastLink":"",
        "series":"",
        "seriesLink":"",
        "images":[
        {
          "width":"",
          "height":"",
          "src":"",
          "contentTags":[
          ""
          ]
        }
        ]
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <tracks>
    <track>
      <startDate></startDate>
      <Duration></Duration>
      <t></t>
      <statusCode></statusCode>
      <title></title>
      <uri></uri>
      <album></album>
      <albumLink></albumLink>
      <artist></artist>
      <artistLink></artistLink>
      <genres>
      <genre></genre>
      </genres>
      <playlist></playlist>
      <playlistLink></playlistLink>
      <podcast></podcast>
      <podcastLink></podcastLink>
      <series></series>
      <seriesLink></seriesLink>
      <images>
      <image>
        <width></width>
        <height></height>
        <src></src>
        <contentTags>
        <contentTag></contentTag>
        </contentTags>
      </image>
      </images>
    </track>
    </tracks>
  </data>
</response>

Method: getAIMFight

Get the AIM Fight score and rank for multiple aimIds

URL: GET http://api.oscar.aol.com/aim/getAIMFight
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	[Required] either an AIM Web Key or AIM Presence Key from http://dev.aol.com/aim
String	t	Target aimIds, multiple t parameters are allowed

Output Fields

Type	Field	Description
Array of AIMFightUser	users	AIM Fight User information

Common Status Codes

Status Code	Description
200	Success
460	Missing required parameter
462	Parameter error

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "users":[
      {
        "aimId":"chattingchuck",
        "score":10000000,
        "rank":1
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <users>
    <user>
      <aimId>chattingchuck</aimId>
      <score>10000000</score>
      <rank>1</rank>
    </user>
    </users>
  </data>
</response>

Method: setPermitDeny

Change the permit/deny settings. The backend system enforces the permit/deny settings, this API is used to update those settings.

URL: GET https://api.oscar.aol.com/preference/setPermitDeny
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	pdAllow	Allow specified aimId
String	pdBlock	Block specified aimId
String	pdIgnore	Ignore IMs from specified aimId
String	pdAllowRemove	Remove specified aimId from allow list
String	pdBlockRemove	Remove specified aimId from block list
String	pdIgnoreRemove	Remove specified aimId from ignore list
PdMode	pdMode	Set the overall permit/deny mode

Output Fields

Type	Field	Description
PDResults	results	Results array for all items

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Example: https://api.oscar.aol.com/preference/setPermitDeny?k=MYKEY&f=xml&pdAllow=ChattingChuck&pdDeny=fred

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "results":{
        "pdModeResult":0-Success,
        "allowResults":[
        {
          "aimid":"foo",
          "statusCode":"0"
        }
        ],
        "blockResults":[
        {
          "aimid":"foo",
          "statusCode":"0"
        }
        ],
        "IgnoreResults":[
        {
          "aimid":"foo",
          "statusCode":"0"
        }
        ],
        "allowRemoveResults":[
        {
          "aimid":"foo",
          "statusCode":"0"
        }
        ],
        "blockRemoveResults":[
        {
          "aimid":"foo",
          "statusCode":"0"
        }
        ],
        "IgnoreRemoveResults":[
        {
          "aimid":"foo",
          "statusCode":"0"
        }
        ]
      }
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <results>
      <pdModeResult>0-Success</pdModeResult>
      <allowResults>
      <allowResult>
        <aimid>foo</aimid>
        <statusCode>0</statusCode>
      </allowResult>
      </allowResults>
      <blockResults>
      <blockResult>
        <aimid>foo</aimid>
        <statusCode>0</statusCode>
      </blockResult>
      </blockResults>
      <IgnoreResults>
      <IgnoreResult>
        <aimid>foo</aimid>
        <statusCode>0</statusCode>
      </IgnoreResult>
      </IgnoreResults>
      <allowRemoveResults>
      <allowRemoveResults>
        <aimid>foo</aimid>
        <statusCode>0</statusCode>
      </allowRemoveResults>
      </allowRemoveResults>
      <blockRemoveResults>
      <blockRemoveResults>
        <aimid>foo</aimid>
        <statusCode>0</statusCode>
      </blockRemoveResults>
      </blockRemoveResults>
      <IgnoreRemoveResults>
      <ignoreRemoveResult>
        <aimid>foo</aimid>
        <statusCode>0</statusCode>
      </ignoreRemoveResult>
      </IgnoreRemoveResults>
    </results>
  </data>
</response>

Method: getPermitDeny

Get the current permit/deny settings. The backend system enforces the permit/deny settings so this API really is only useful for building UIs that allow the user to change the settings.

URL: GET https://api.oscar.aol.com/preference/getPermitDeny
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	aimsid	Use an AIM Session Id from the startSession call for authentication - k is not required
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.

Output Fields

Type	Field	Description
PdMode	pdMode	Permit/Deny mode
Array of String	allows	aimIds allowed
Array of String	blocks	aimIds blocked
Array of String	ignores	aimIds ignored

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "pdMode":"permitOnList",
      "allows":[
      "ChattingChuck"
      ],
      "blocks":[
      "fred"
      ],
      "ignores":[
      "john"
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <pdMode>permitOnList</pdMode>
    <allows>
    <allow>ChattingChuck</allow>
    </allows>
    <blocks>
    <block>fred</block>
    </blocks>
    <ignores>
    <ignore>john</ignore>
    </ignores>
  </data>
</response>

Method: getUserFeed

Get the buddyfeed for a user. An extra format type of rss is supported.

Trusted, Token and Aimsid validation methods are currently not enforced.

URL: GET http://api.oscar.aol.com/buddyfeed/getUser
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	t	Target aimId
String	feedCategory	Filter feeds by this feed category. Can be multiple instances up to filters
Boolean	fullContent	Return the full html content for published items
Integer	maxItems	Max total number of items
Boolean	bfUI	if provided and set to 1, Profile, away and status msgs are NOT retrieved
Boolean	statusMsgs	This is used in conjunction with the bfUI parameter to include status msgs, but exclude profile and away msgs. eg: bfUI=1&statusMsgs=1 will pull cache items and status msgs
String	lastGuid	Retrieve only items newer than the item with this GUID
String	awayMsgs	Should away msgs be retrieved (Y or N). Default is Y. eg. awayMsgs=N
String	loc	the required language and locale of the error/status messages. This is always in "<lang>-<locale>" format. The lang is the 2 letter language code for I18N (default: en) and the locale is the 2 letter Locale code for I18N (default: us). If not passed in, the language will be extracted from HTTP header (Accept-Language) and if that is not available will default to "en-us".

Output Fields

Type	Field	Description
Array of BuddyFeedItem	items	Target aimId, multiple t parameters are allowed

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "items":[
      {
        "aimId":"chattingchuck",
        "title":"Blog update",
        "link":"http://journals.aol.com/chattingchuck/entry",
        "domain":"journals.aol.com",
        "description":"What I ate today",
        "category":"Journal",
        "pubDate":"Mon, 02 Apr 2007 14:02:12 GMT",
        "timestamp":1232986257,
        "author":"chattingchuck@aol.com",
        "guid":"Blah",
        "media-content":{
          "height":640,
          "width":480,
          "url":"http://images/test.jgp"
        },
        "media-thumbnail":{
          "height":60,
          "width":90,
          "url":"http://images/test-thumbnail.jgp"
        },
        "media-title":{
          "contentValue":"Self potrait"
        }
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <items>
    <item>
      <aimId>chattingchuck</aimId>
      <title>Blog update</title>
      <link>http://journals.aol.com/chattingchuck/entry</link>
      <domain>journals.aol.com</domain>
      <description>What I ate today</description>
      <category>Journal</category>
      <pubDate>Mon, 02 Apr 2007 14:02:12 GMT</pubDate>
      <timestamp>1232986257</timestamp>
      <author>chattingchuck@aol.com</author>
      <guid>Blah</guid>
      <media-content>
        <height>640</height>
        <width>480</width>
        <url>http://images/test.jgp</url>
      </media-content>
      <media-thumbnail>
        <height>60</height>
        <width>90</width>
        <url>http://images/test-thumbnail.jgp</url>
      </media-thumbnail>
      <media-title>
        <contentValue>Self potrait</contentValue>
      </media-title>
    </item>
    </items>
  </data>
</response>

Method: getBuddylistFeed

Get the buddyfeed for a user's entire buddylist. An extra format type of f=native for RSS is supported.

URL: GET http://api.oscar.aol.com/buddyfeed/getBuddylist
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type	Field	Description
Format	f	[Required] The format of the data returned
String	c	JSONP callback
String	r	Request id
String	k	[Required] the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls
String	s	Use trusted authentication, the source user
String	a	Use an AOL Authentication Token for authentication, from the getToken call
Integer	ts	The current timestamp - clientLogin required parameter
String	sig_sha256	Signature - clientLogin required parameter.
String	groupBy	(T or F) F = Sort results in revchron order (default), T = Sort results by buddy/subsort in revchron order
Integer	maxItems	Max total number of items
Integer	maxItemsPerMember	Max items per member
Integer	maxMembers	Max number of unique buddies to report on
String	feedCategory	Filter feeds by this feed category. Can be multiple instances up to filters
Boolean	bfUI	if true, Profile, away and status msgs are NOT retrieved
Boolean	statusMsgs	This is used in conjunction with the bfUI parameter to include status msgs, but exclude profile and away msgs. eg: bfUI=1&statusMsgs=1 will pull cache items and status msgs
String	awayMsgs	Should away msgs be retrieved (Y or N). Default is Y. eg. awayMsgs=N
Boolean	includeSelf	if true, the buddylist owners feeds are returned as well
String	loc	the required language and locale of the error/status messages. This is always in "<lang>-<locale>" format. The lang is the 2 letter language code for I18N (default: en) and the locale is the 2 letter Locale code for I18N (default: us). If not passed in, the language will be extracted from HTTP header (Accept-Language) and if that is not available will default to "en-us".

Output Fields

Type	Field	Description
Array of BuddyFeedItem	items	Items for all the users in the buddylist

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call
1014	Signature is bad, see the signature notes of startSession
1015	The ts parameter for clientLogin is too far in the past or future

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
      "items":[
      {
        "aimId":"chattingchuck",
        "title":"Blog update",
        "link":"http://journals.aol.com/chattingchuck/entry",
        "domain":"journals.aol.com",
        "description":"What I ate today",
        "category":"Journal",
        "pubDate":"Mon, 02 Apr 2007 14:02:12 GMT",
        "timestamp":1232986257,
        "author":"chattingchuck@aol.com",
        "guid":"Blah",
        "media-content":{
          "height":640,
          "width":480,
          "url":"http://images/test.jgp"
        },
        "media-thumbnail":{
          "height":60,
          "width":90,
          "url":"http://images/test-thumbnail.jgp"
        },
        "media-title":{
          "contentValue":"Self potrait"
        }
      }
      ]
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
    <items>
    <item>
      <aimId>chattingchuck</aimId>
      <title>Blog update</title>
      <link>http://journals.aol.com/chattingchuck/entry</link>
      <domain>journals.aol.com</domain>
      <description>What I ate today</description>
      <category>Journal</category>
      <pubDate>Mon, 02 Apr 2007 14:02:12 GMT</pubDate>
      <timestamp>1232986257</timestamp>
      <author>chattingchuck@aol.com</author>
      <guid>Blah</guid>
      <media-content>
        <height>640</height>
        <width>480</width>
        <url>http://images/test.jgp</url>
      </media-content>
      <media-thumbnail>
        <height>60</height>
        <width>90</width>
        <url>http://images/test-thumbnail.jgp</url>
      </media-thumbnail>
      <media-title>
        <contentValue>Self potrait</contentValue>
      </media-title>
    </item>
    </items>
  </data>
</response>

Method: pushFeed

Push a simple Buddy Feed Item

URL: GET http://api.oscar.aol.com/buddyfeed/pushFeed
POST with Content type of application/x-www-form-urlencoded also supported

Input Parameters

Type

Field

Description

Format

[Required] The format of the data returned

String

JSONP callback

String

Request id

String

the AIM Web Key from http://dev.aol.com/aim - use the same key for all calls

String

aimsid

Use an AIM Session Id from the startSession call for authentication - k is not required

String

Use an AOL Authentication Token for authentication, from the getToken call

String

feedTitle

[Required] Channel/Feed title

String

feedLink

[Required] URL to main feed page

String

feedDesc

[Required] Channel/Feed description

String

feedPublisher

Name of application publishing data

String

itemTitle

[Required] Title of item

String

itemLink

[Required] URL to item location

String

itemPubDate

Item published date in UNIX time in secs since EPOCH. If not provided, server will use system time

String

itemGuid

[Required] Unique per item ID

String

itemDesc

Item description

String

itemCategory

Item Category

String

media-thumbnail

Enclosed parameter list in the form of {field=value,field=value}. field/values are

Example : media-thumbnail={height=40,width=60,url=http://www.images.com/somethumbnail.jpg} Note: Multiple instances of media-thumbnail are permitted.

Field	Value	Example
height	40	height=40
width	60	width=60
url Required	http://www.images.com/somethumbnail.jpg	url=http://www.images.com/somethumbnail.jpg

Note that in addition to any URL encoding needed to get special characters into a field/member value, the resulting value must be URL encoded for sending. The actual value used for the value in the example above would need to be:

media-thumbnail=%7Bheight%3D40%2Cwidth%3D60%2Curl=http%3A//www.images.com/somethumbnail.jpg%7D

String

media-content

Enclosed parameter list in the form of {field=value,field=value} field/values are

Example : media-content={height=40,width=60,url=http://www.images.com/someimage.jpg}

Field	Value	Example
height	40	height=40
width	60	width=60
url Required	http://www.images.com/someimage.jpg	url=http://www.images.com/someimage.jpg

media-content=%7Bheight%3D40%2Cwidth%3D60%2Curl=http%3A//www.images.com/someimage.jpg%7D

String

media-title

Enclosed parameter list in the form of {field=value,field=value} field/values are

Example : media-title={type=plain,value=Family Picture}

Field	Value	Example
type	plain or html	type=plain
value	String	value=Photos

media-title=%7Btype%3Dplain%2Cvalue%3DFamily%20Picture%7D

Common Status Codes

Status Code	Description
200	Success
401	Authorization required
460	Missing required parameter
462	Parameter error

Common Status Detail Codes

Status Detail Code	Description
1004	Referer used to create token doesn't match referer of call

Sample JSON Output

{
  "response":{
    "statusCode":200,
    "statusText":"Ok",
    "requestId":"123",
    "data":{
    }
  }
}

Sample XML Output

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <statusCode>200</statusCode>
  <statusText>Ok</statusText>
  <requestId>123</requestId>
  <data>
  </data>
</response>

» Submitted by Developer Network on March 4, 2008 - 11:05pm.

Web AIM

Manage your keys

AIM Gallery

Open your Apps to millions of users at the AIM Gallery!

Stay Informed

What Do You Think?

Are you finding it easier to get the information you need on our new website? Is there something missing? Do you want to make a suggestion? Please send your feedback here.