User API

Introduction
Basics
Authorisation
Obtaining data with API
Error handling and content uploading
Final remarks

UserAPI is an application programming interface (API), which enables anyone to create social networks and other projects based on Vkontakte data storage.

Anyone can create a social network in any part of the world, using our technical resources, database and a shared authorisation system for more than 40 million users.

The fastest way to master UserAPI is to begin creating and testing your own project right now, using the Sample Social Network as a starting point. The very first UserAPI-based project (a social network client for iPhone) has been designed solely by analysing the requests of the Sample Social Network, without any formal documentation.

Please notice that before you start working, you need to register your project and obtain the identification number (id) for your site. The complete UserAPI documentation follows.

API relies on the HTTP protocol to carry requests from client to server and answers from server to client, always returned as a UTF-8-encoded JSON data array. Gzip compression is supported.

Client →	← Server
HTTP request	Data (JSON)
Sample API Request	Sample API Response
http://userapi.com/data?act=get_school_num&s=1	{"num": 225005}
http://userapi.com/data?act=schools&parent=1516340	{"n": 4, "d": [[374587, "Conservatorio Egidio Romualdo Duni", 100], [2151441, "GLK", 0], [2089411, "Liceo Classico E. Duni", 0], [2151440, "Rossa vita", 0]]}

Successful completion of a request and transfer of any data to the Client requires some valid Client authentification data. This is normally achieved by passing the so-called Session ID ('sid') as one of the HTTP request arguments.

Sample API Request	Sample API Response
http://userapi.com/data?act=photos&from=0&to=2&id=1&sid=c9858c2feaa17203fa87e6b8c2371380	[["1_115456905", "http://cs93.userapi.com/u00001/25797999/m_f9af6bf6.jpg", "http://cs93.userapi.com/u00001/25797999/x_be594ecc.jpg"], ["1_90710441", "http://cs37.userapi.com/u00001/5433484/m_5ac5c794.jpg", "http://cs37.userapi.com/u00001/5433484/x_2e4eddbb.jpg"]]

That's why any UserAPI application (Client) has to obtain a valid sid from the Server before any other actions can be performed.

User authorisation is achieved by HTTP requests to http://login.userapi.com/auth.
User authorisation is understood here as the generation of a valid Session ID ('sid') by the Server.
Session ID ('sid') depends on User ID, IP Address, and the Site (UserAPI project) used for authorisation
A 'sid' can be generated by submitting explicitly User's e-mail and password (login=force), or automatically based on User's cookies (login=auto).

Authorisation by submitting email and password (Login)

After successful login the Client obtains a new Session ID ('sid'), which can be used for subsequent API requests. A 'remixpassword' cookie is set in domain login.userapi.com, which may be used later for automatical session prolongation.

Client →

← Server

Parameters
login	'force'
site	ID of your site
email	user's email
pass	user's password

Setting 'remixpassword' cookie for domain login.userapi.com.
'remixpassword' is used for automatic user authentification.
Redirect to
{site URL}/index.html#;sid={session ID}

Sample API Request

Sample API Response

http://login.userapi.com/auth?login=force&site=2&email=test@test.com&pass=7777777

Set-Cookie: remixpassword=0f183e4767ea1c738c0cabe1011356d4a7a00c1812899a447691fa80; domain=login.userapi.com
Location: http://durov.ru/index.html#;sid=c9858c2feaa17203fa87e6b8c2371380

Authorisation by means of 'remixpassword' cookie

The 'remixpassword' cookie set up as a result of successful login can be used for automatic session ID ('sid') prolongation.

Client →

← Server

Parameters
login	'auto'
site	site id
remixpassword	cookie for login.userapi.com, sent in HTTP request header

Redirect to
{site URL}/index.html#;sid={session ID}
Redirect to {site URL}/index.html;sid=-1
if 'remixpassword' is invalid

Sample API Request

Sample API Response

http://login.userapi.com/auth?login=auto&site=2

Location: http://durov.ru/index.html#;sid=c9858c2feaa17203fa87e6b8c2371380

First-use one-time authorisation by registration identifier

After registration the User receives an e-mail with an account activation link.
This link contains a certain 'confirmation id', which can be used for User's account activation and authorisation exactly once.

Client →

← Server

Parameters
login	'confirm'
site	Site id
cid	Confirmation id

Redirect to
{site URL}/index.html#;sid={session ID}

Sample API Request

Sample API Response

http://login.userapi.com/auth?login=confirm&site=2&cid=546ca8664640fef3d8b0a0a2978c3fbd

Location: http://durov.ru/index.html#;sid=c9858c2feaa17203fa87e6b8c2371380

Session ID removal (Logout)

Client →

← Server

Parameters
login	'logout'
site	Site ID
sid	Session ID

Removal of session given by sid on Server
Removal of 'remixpassword' cookie on Client
Redirect to
{site URL}/index.html

Sample API Request

Sample API Response

http://login.userapi.com/auth?login=logout&site=2&sid=c9858c2feaa17203fa87e6b8c2371380

Set-Cookie: remixpassword=; domain=login.userapi.com
Location: http://durov.ru/index.html

All data are obtained through HTTP requests to http://userapi.com/data.
Almost all data requests require a 'sid' parameter.
The answer to a data request usually is an array of similar records (e.g. an array of friend descriptions, or an array of photo descriptions etc.).
Any request may have an optional 'back' parameter, containing the name of callback function to be used as a wrapper for the resulting JSON array.

Sample API Request→	← Response
http://userapi.com/data?act=friends&from=10&to=12&id=1&sid=9986006b784ebbc4c472db7319a51e93&back=processFriends	processFriends([[42, "Sergey Markin", "http://cs113.userapi.com/u00042/b_94ae6676.jpg", 0], [45, "Sergey Vinogradov", "http://cs16.userapi.com/u00045/b_f9c7d9e.jpg", 0]]);
Require the part of friend list for user 1, from the 10th to the 12th friend (exclusive), with the resulting array passed to a certain processFriends() function.	Function processFriends() is to be invoked with the array of friends 10 and 11 of user 1 as an argument.

Client →

← Server

Parameters
act	'friends'
id	user ID
from	no. of first entry required (zero-based)
to	no. of last entry required (plus one)
sid	session ID
back*	callback function

General structure of resulting array
[0]	first (required) entry data
[1]	second entry data
...	...
[n]	n+1-st entry data

Structure of each entry of resulting array
[0]	user id
[1]	user name
[2]	url of user photo (100px-wide)
[3]	online flag (0 or 1)

Sample API Request

Sample API Response

http://userapi.com/data?act=friends&from=16&to=18&id=1&sid=9986006b784ebbc4c472db7319a51e93

[[79, "David Spekter", "http://cs13.userapi.com/u00079/b_693df63.jpg", 0],[133, "Nikolay Harchev", "http://cs230.userapi.com/u00133/b_90db7675.jpg", 0]]

Other values for act:

Value of 'act'	Result
friends	List of all friends of a user
friends_mutual	List of mutual friends with a user
friends_online	List of online friends of a user
friends_new	List of new friend requests to the current user

Client →

← Server

Parameters
act	'photos'
id	user id
from	first entry no.
to	last entry no.
sid	session id
back*	callback function

General structure of resulting array
[0]	first entry data
[1]	second entry data
...	...
[n]	n+1-st entry data

Structure of each entry of array
[0]	string '{owner id}_{photo id}' used to identify photos elsewhere
[1]	thumbnail url (130px)
[2]	image url (604px)

Sample API Request

Sample API Response

http://userapi.com/data?act=photos&from=0&to=2&id=1&sid=c6c1d30d34459e592ca0455f69b2c8a3

[["1_115456905", "http://cs93.userapi.com/u00001/25797999/m_f9af6bf6.jpg", "http://cs93.userapi.com/u00001/25797999/x_be594ecc.jpg"], ["1_90710441", "http://cs37.userapi.com/u00001/5433484/m_5ac5c794.jpg", "http://cs37.userapi.com/u00001/5433484/x_2e4eddbb.jpg"]]

Other values for act:

Value of 'act'	Result
photos	List of all photos uploaded by a user
photos_with	List of all photos with a user
photos_new	List of new (unapproved) photos, on which current user has been tagged

Client →

← Server

Parameters
act	'wall'
id	user id
from	first entry
to	last entry
sid	session ID
ts*	timestamp of current version of this wall on the Client (if present)
back*	callback function

General structure of resulting array
n	total messages on wall
d	array with requested messages
h	current wall version (timestamp, ts), or array with all updates of this wall since last query (characterized by 'ts' request parameter)

Structure of each message array ("d") entry
[0]	message id
[1]	creation time (unixtime)
[2]	array with message content
[3]	array with sender description
[4]	array with recipient description

Structure of message content array (["d"][n][2])
[0]	message text
[1]*	message type 0 = plain text 1 = photo 2 = graffiti 3 = video 4 = audio
[2]*	title
[3]*	thumbnail url
[4]*	image/media url
[5]*	owner id
[6]*	image/media object id
[7]*	image/media object size

Structure of arrays with user descriptions (["d"][n][3], ["d"][n][4])
[0]	user id
[1]*	user name
[2]*	photo url (100px-wide)
[3]*	thumbnail image filename (50px)
[4]*	gender 1 = female 2 = male
[5]*	online status of a user (0 or 1)

Structure of each entry of updates history array (["h"])
[0]	timestamp after this update is applied
[1]	action type "add" = message added "del" = message deleted "restore" = message restored (undeleted) "read" = message read (for private messages only)
[2]	array with message content, same structure as ["d"][n][2]

Sample API Request

Sample API Response

http://userapi.com/data?act=wall&from=0&to=2&id=1&ts=670000055&sid=c6c1d30d34459e592ca0455f69b2c8a3

{"n": 22459, "d": [[48776839, 1224745160, ["<a href='http://195.218.181.1/assets/videos/bc71198266671054.vk.flv'><img src='http://195.218.181.1/assets/thumbnails/bc71198266671054.160.vk.jpg'/></a>", 3, "George Carlin - Religion is bullshit", "http://195.218.181.1/assets/thumbnails/bc71198266671054.160.vk.jpg", "http://195.218.181.1/assets/videos/bc71198266671054.vk.flv", "16494692", "70493039"], [1, "Pavel Durov", "http://cs137.userapi.com/u00001/b_6261d317.jpg", "c_015fd76c", 2, 1], [1]], [48771962, 1224715800, ["Thank you for all you do!"], [9958040, "Alena Kravtsova", "http://cs293.userapi.com/u9958040/b_1de41aae.jpg", "c_bb652722", 1, 0], [1]]], "h": [[670000057, "add", [48777477, 1224746560, ["test"], [1, "Pavel Durov", "http://cs137.userapi.com/u00001/b_6261d317.jpg", "c_015fd76c", 2, 1], [1]]], [670000059, "del", [48777477]], [670000061, "undel", [48777477, 1224746560, ["test"], [1, "Pavel Durov", "http://cs137.userapi.com/u00001/b_6261d317.jpg", "c_015fd76c", 2, 1], [1]]]}

Client →

← Server

Параметры
act	'photos_comments'
parent	-1 = comments to all photos uploaded by user -2 = comments to all photos with user {owner id}_{photo id} = comments to specified photo
id	user id
from	first entry
to	last entry
sid	session ID
ts*	timestamp of current version of these comments on Clients (if present)
back*	callback function

General structure of resulting array
parent	value of request 'parent' parameter
n	total comments
d	array with requested comments
h	updates history (cf. wall)
author*	array with author (uploader) user description
tags*	array with tags data
*	"author" and "tags" are returned only for requests to comments of one photo, and only if from=1

Structure of each entry of comments list array ("d")
[0]	comment id
[1]	creation time (unixtime)
[2]	array with comment content (cf. wall)
[3]	array with sender description (cf. wall)
[4]	array with recipient description (cf. wall)
[5]	0, reserved
[6]	0, reserved
[7]	array with photo description

Structure of photo description array (["d"][n][7])
[0]	photo id
[1]*	thumbnail URL (75px wide)

Structure of array with uploader (author) description (["author"])
[0]	uploader id
[1]	uploader name

Structure of tags array (["tags"])
tid	tag id
placer_id	id of user who put this tag
id	id of tagged user
name	name of tagged user
x1	x-coordinate of upper left corner, %
y1	y-coordinate of upper left corner, %
x2	x-coordinate of lower right corner, %
y2	y-coordinate of lower right corner, %

Sample API Request

Sample API Response

http://userapi.com/data?act=photos_comments&from=0&to=2&parent=1_79435064&id=1&sid=c6c1d30d34459e592ca0455f69b2c8a3

{"parent": "1_79435064", "h": 983000002, "d": [["85935454", "1219069674", ["yes, thaaat's me - near the very top ;)"], [12, "Yuly Dzhumasultanov", "http://cs201.userapi.com/u00012/b_5a7b82f4.jpg", "c_7e80ab05", 2, 0], [1], 0, 0, [79435064]], [81711268, 1208200679, ["Beautiful..."], [3226038, "Masha Petrova", "http://cs309.userapi.com/u3226038/b_02f896e7.jpg", "c_a8170db8", 1, 0], [1], 0, 0, [79435064]]], "n": 2, "tags": [{"tid": 3611353, "placer_id": 1, "id": "12", "name": "Yuly Dzhumasultanov", "x1": 38.99, "y1": 23.67, "x2": 62, "y2": 52.88}], "author": [1, "Pavel Durov"]}

Client →

← Server

Parameters
act	'activity'
id	user id
from	first entry
to	last entry
sid	session id
ts*	timestamp of current version on Client (if any)
back*	callback function

General structure of response array
n	total status updates
d	array with requested status updates
h	updates history (cf. wall)

Structure of each entry of status updates list ("d")
[0]	'{user id}_{status id}' (string)
[1]	id of user who updated their status
[2]	0, reserved (rather user's gender?)
[3]	name of user
[4]	update time (unixtime)
[5]	status text

Sample API Request

Sample API Response

http://userapi.com/data?act=activity&from=1&to=2&id=6704204&sid=622ccd76a5b4b67fbc753abd53e41ad2

{"n": 42, "d": [["6704204_140129285", 6704204, 1, "Sidney Bristow", 1224735103, "Kamakazi, nazi, nazi, copy papi I'm a baller baller, you're not at all Oops, oopsy daisy, oh I'm crazed..."], ["6704204_139859457", 6704204, 1, "Sidney Bristow", 1224529016, "to the beach yo."]], "h": 299000002}

Client →

← Server

Parameters
act	'fave'
from	first entry
to	last entry
sid	session ID
back*	callback function

General structure of resulting array
n	total bookmarked users
d	array with bookmarked users descriptions (cf. friends)

Sample API Request

Sample API Response

http://userapi.com/data?act=fave&from=6&to=8&id=1&sid=622ccd76a5b4b67fbc753abd53e41ad2

{"n": 154, "d": [["32951", "Viktoria Turgunova", "http://cs407.userapi.com/u32951/b_8109fa23.jpg", 0], ["740975", "Anna Kameneva", "http://cs17.userapi.com/u740975/b_7eef1de.jpg", 0]]}

Other values for act:

Value of 'act'	Result
fave	List of all users bookmarked by current user
fave_online	List of online bookmarked users
faved	List of users who bookmarked current user

Getting friends' status updates news

Client →

← Server

Parameters
act	'updates_activity'
from	first entry
to	last entry
back*	callback function

General structure of resulting array
n	total records
d	array with friends' status updates data (cf. statuses)

Sample API Request

Sample API Response

http://userapi.com/data?act=updates_activity&from=0&to=2&id=0&sid=622ccd76a5b4b67fbc753abd53e41ad2

{"n": 484, "d": [["31225_140195756", 31225, 1224757408, "Lyolya Fomina", 1224757173, "chocolates, chocolates...))))))))."], ["201541_140123249", 201541, 1224757307, "Sveta Pusechkina", 1224756891, "These intriguing and enthralling stares....this barrier, obstacle.....this voice.....this girl....why everything is so complicated?"]]}

Getting new friends of friends

Client →

← Server

Parameters
act	'updates_friends'
from	first entry
to	last entry
back*	callback function

General structure of resulting array
n	total users
d	array with requested users (cf. friends)

Sample API Request

Sample API Response

http://userapi.com/data?act=updates_friends&from=0&to=2&id=0&sid=622ccd76a5b4b67fbc753abd53e41ad2

{"n": 1034, "d": [["3643009", "Nadezhda Troitskaya", "http://cs206.userapi.com/u3643009/b_0fbda514.jpg", 0], ["20175184", "Alexey Seryapin", "http://cs272.userapi.com/u20175184/b_6626ecfb.jpg", 0]]}

Getting new friends' photos

Client →

← Server

Parameters
act	'updates_photos'
from	first entry
to	last entry
back*	callback function

General structure of resulting array
n	total photos
d	array with photo descriptions (cf. photos)

Sample API Request

Sample API Response

http://userapi.com/data?act=updates_photos&from=0&to=2&id=0&sid=622ccd76a5b4b67fbc753abd53e41ad2

{"n": 956, "d": [["7275620_117953590", "http://cs440.userapi.com/u7275620/19135819/m_cb29d6c4.jpg", "http://cs440.userapi.com/u7275620/19135819/x_54a5f2b5.jpg"], ["7275620_117953589", "http://cs440.userapi.com/u7275620/19135819/m_56784e9e.jpg", "http://cs440.userapi.com/u7275620/19135819/x_3f973a90.jpg"]]}

Other values for act:

Value of 'act'	Result
updates_photos	List of photos uploaded by current user's friends recently (at most 3 days ago)
updates_tagged_photos	List of photos with recently tagged user's friends

Client →

← Server

Parameters
act	'message'
id	id of user with whom current user is corresponding
from	first entry
to	last entry
sid	session ID
ts*	timestamp of Client's version of private message (if any)
back*	callback function

General structure of resulting array
n	total private messages to/from given user
d	array with requested messages
h	change history (cf. wall) NB. All private message lists of current user share the same timestamp, so this change history might include changes not related to given corresponding user

Structure of each message list ("d") entry
[0]	message id
[1]	creation time (unixtime)
[2]	message content (cf. wall)
[3]	sender data (cf. wall)
[4]	recipient data (cf. wall)
[5]	message read flag (0 or 1)

Sample API Request

Sample API Response

http://userapi.com/data?act=message&from=0&to=2&id=10&sid=622ccd76a5b4b67fbc753abd53e41ad2

{"n": 151, "d": [[121444273, 1224759330, ["Well is he a genius?"], [1, "Pavel Durov", "http://cs137.userapi.com/u00001/b_6261d317.jpg", "c_015fd76c", 2, 1], [10], 0], [106065105, 1224583486, ["An old acquaintance of mine thinks about changing his job, and asks whether we need developers. Do we?"], [10, "Alexandr Kuznetsov", "http://cs146.userapi.com/u00010/b_34230f2c.jpg", "c_8109903f", 2, 0], [1], 1]], "h": 433000024}

Other values of act:

Value of 'act'	Result
message	Correspondence between given user and current user
inbox	All incoming messages of current user
outbox	All outgoing messages of current user

Important: act=inbox and act=outbox share the same 'ts' (timestamp) parameter with act=message.

Getting information about cities in a country

Client →

← Server

Parameters
act	'cities'
parent	country id
from	no. of first entry
to	no. of last entry
q*	substring to be contained in city name
back*	callback function

General structure of resulting array
n	total amount of matching cities
d	array with descriptions of requested cities

Structure of each city array ("d") entry
[0]	array with city description
[1]	array with description of lower-level subdivision entity
[2]	array with description of higher-level subdivision entity
[3]	array with country description

Structure of city description array
[0]	city id
[1]	city name
[2]	city type 1 = city 2 = village 21 = "county" (lower subdivision entity) 22 = "region" or state (higher subdivision entity)
[3]	1 for "large" cities, 0 else
[4]	which word of city name begins with search string (1 or 2)

Array describing a subdivision entity
[0]	subdivision id
[1]	subdivision name
[2]	subdivision type

Array describing a country
[0]	country id (1-254)

Sample API Request

Sample API Response

http://userapi.com/data?act=cities&from=0&to=2&parent=9&id=1&q=bosto

{"n": 63, "d": [[[1515864, "Boston", 1, 0, 1], [5035939, "Suffolk County", 22], [5135820, "Massachusetts", 21], [9]], [[4978585, "Boston", 1, 0, 1], [4979613, "Highland County", 22], [5066570, "Ohio", 21], [9]]]}

Getting information about schools (educational institutes) in a city

Client →

← Server

Parameters
act	'schools'
parent	city id
back*	callback function

General structure of resulting array
n	total schools
d	array with school descriptions

Structure of each entry of school descriptions array ("d")
[0]	school id
[1]	school name
[2]	school type 1-20: different kinds of schools (primary and secondary) 100: higher education institute (university) 110: subdivision of a university (e.g. faculty, college, chair)

Sample API request

Sample API Response

http://userapi.com/data?act=schools&parent=1933819

{"n": 1, "d": [[2101401, "st. Antonio # 34.5", 0]]}

Searching users by school and graduation year

Client →

← Server

Parameters
act	'quick_search'
q	given name or surname
from	first entry
to	last entry
year	graduation year (1920-2066, 0=any)
back*	callback function

General structure of resulting array
n	total users found
d	array with required users (cf. friends)
belongs	is the current user a member of this school (-1 or 1)

Sample API Request

Sample API Response

http://userapi.com/data?act=search_results&from=0&to=2&parent=2289&sid=0a200f062ebba1b9ca32e24ba9685638

{"belongs": -1, "n": 2937, "d": [[43433, "Sergey Leonov", "http://cs100.userapi.com/u43433/b_8b09b08a.jpg", 0], [45307, "Maria Soshnikova", "http://cs228.userapi.com/u45307/b_2415eec0.jpg", 0]]}

Searching users by name

Client →

← Server

Parameters
act	'quick_search'
q	given name or surname for search
from	no. of first entry
to	no. of last entry
back*	callback function

General structure of resulting array
n	total users found
d	array with requested users (cf. friends)

Sample API Request

Sample API Response

http://userapi.com/data?act=quick_search&from=0&to=2&q=durov&sid=622ccd76a5b4b67fbc753abd53e41ad2

{"n": 1189, "d": [[1, "Pavel Durov", "http://cs137.userapi.com/u00001/b_6261d317.jpg", 1], [6, "Nikolay Durov", "http://cs1024.userapi.com/u00006/b_37a43719.jpg", 1]]}

Client →

← Server

Parameters
act	'profile'
id	user id
back*	callback function

General structure of resulting array

id

user id

fn

user's given name(s)

ln

user's surname

mn

user's previous surname (e.g. maiden name)

actv

current status (cf. status)

ht


coi	country id
con	ISO country code
cii	city id
cin	city name

sx

user's gender

bp

photo URL (200px wide)

bd

birthday day (1-31 or 0)

bm

birthday month (1-12 or 0)

by

birthday year (1900-2100 or 0)

fs

marital/relationship status

1 = single
2 = in a relationship
3 = engaged
4 = married
5 = it's complicated
6 = looking for a relationship

pv

political views

1 = communist
2 = socialist
3 = moderate
4 = liberal
5 = conservative
6 = monarchist
7 = ultraconservative
8 = apathetic

fr

friends array (cf. friends)

fro

online friends array (cf. friends)

frm

mutual friends array (cf. friends)

ph

uploaded photos array (cf. photos)

phw

array of photos with user (cf. photos)

pr

array with privacy settings and hashes
pa	profile view flag (1=allowed, 0=hidden)
wa	wall view flag (1 or 0)
ms	message send flag (1 or 0)

wa

wall messages array (cf. wall)

us

viewer (i.e. current user) id

on

online flag (0 or 1)

isf

1 if is a friend

isi

1 if has invited current user to friends

f

1 if has been bookmarked by current user

edu

array of all user's schools

Hash values for photos upload*
pr	url	URL to upload profile photo to
	hash	hash for uploading profile photo
	rhash	"reverse" hash for uploading profile photo
ph	url	URL to upload user's album photos to
	aid	user's album id
	hash	hash for uploading album photos
	rhash	"reverse" hash for uploading album photos
*present if profile is being viewed by its owner

Structure of each element of user's schools list
[0]	school id
[1]	parent university id (if this is a subdivision of a university)
[2]	school type (cf. school types)
[3]	school name
[4]	graduation year

UserAPI allows miscellaneous types of data to be fetched by one common request. These types of data include: 'fave', 'fave_online', 'faved', 'updates_activities', 'updates_friends', 'updates_photos', 'updates_tagged_photos', 'photos', 'photos_with', 'wall', 'friends', 'friends_online', 'friends_mutual', 'profile'.

In order to do this the required actions from this list should be used as parameter names to http://userapi.com/data, with values set to no. of first and last entry to be fetched from the corresponding list, separated by a hyphen ('-').

Client →

← Server

Parameters
fave	{from}-{to}
fave_online	{from}-{to}
faved	{from}-{to}
updates_activities	{from}-{to}
updates_friends	{from}-{to}
updates_photos	{from}-{to}
updates_tagged_photos	{from}-{to}
photos	{from}-{to}
photos_with	{from}-{to}
wall	{from}-{to}
friends	{from}-{to}
friends_online	{from}-{to}
friends_mutual	{from}-{to}
profile	{from}-{to}

General structure of resulting array
fave	Same as the result of a fave query
fave_online	Same as fave_online
faved	Same as faved
updates_activities	Same as updates_activities
updates_friends	Same as updates_friends
updates_photos	Same as updates_photos
updates_tagged_photos	Same as updates_tagged_photos
photos	Same as photos
photos_with	Same as photos_with
wall	Same as wall
friends	Same as friends
friends_online	Same as friends_online
friends_mutual	Same as friends_mutual
profile	Same as profile

Sample API Request

Sample API Response

http://userapi.com/data?friends=0-2&photos=0-2&wall=0-2&id=1&sid=0a200f062ebba1b9ca32e24ba9685638

{"wall": {"n": 22452, "d": [[48469764, 1224323455, ["Pavel,the site is really super!!!!"], [273611, "Svetlana Fedorova", "http://cs166.userapi.com/u273611/b_7ba3263a.jpg", "c_85f62239", 1, 0], [1]], [48350915, 1224155096, ["Cool site ;) Thanks :)"], [6875276, "Irina Kalyuzhina", "http://cs1432.userapi.com/u6875276/b_0c8cdb78.jpg", "c_388c71b4", 1, 0], [1]]]}, "photos": {"n": 34, "d": [["1_115456905", "http://cs93.userapi.com/u00001/25797999/m_f9af6bf6.jpg", "http://cs93.userapi.com/u00001/25797999/x_be594ecc.jpg"], ["1_90710441", "http://cs37.userapi.com/u00001/5433484/m_5ac5c794.jpg", "http://cs37.userapi.com/u00001/5433484/x_2e4eddbb.jpg"]]}, "friends": {"n": 349, "d": [[3, "Vyacheslav ", "http://cs47.userapi.com/u00003/b_4fd0a4bc.jpg", 0], [7, "Alexey Kobylyansky", "http://cs26.userapi.com/u00007/b_5b634f4.jpg", 0]]}}

By means of act=history the UserAPI enables the Client to obtain recent updates history for one or several objects, which may be used to display changes almost immediately after they happen, without having to refresh all data. Besides that, act=history enables the Client to obtain values of several counters (such as the new friend applications counter), which can be also displayed and taken into account immediately. Furthermore, the same act=history request may be also used to tell the Server that various data will soon be needed, so as to enable the Server to prepare these data beforehand.

Obtaining new messages, new friends and new photos counters

Client →

← Сервер

Parameters
act	'history'

General structure of resulting array
nm	Amount of new (i.e. unread) private messages
nf	Amount of new (unprocessed) friend invitations (if any)
nph	Amount of new tags (if any)

Sample API Request

Sample API Response

http://userapi.com/data?act=history&sid=0b95f864b67a0b16d9d0fc20748b8e2d

{"nm": 0, "nf": 271929, "nph": 2}

Obtaining own and friends' profile updates history

Client →

← Server

Parameters
act	'history'
wall*	current wall version timestamp (ts)
activity*	current activity version (ts)
message*	current message list version (ts)
updates_photos*	current updates_photos version (ts)
updates_tagged_photos*	current updates_tagged_photos version (ts)
updates_friends*	current updates_friends version (ts)
updates_activity*	current updates_activity version (ts)
photos_comments*	current photos_comments version (ts)
parent*	photo id (for photos_comments)
back*	callback function

General structure of resulting array

wall

h	wall updates history

activity

h	activity updates history

message

h	message update history

updates_photos

h	updates_photos update history

updates_tagged_photos

h	updates_tagged_photos update history

updates_friends

h	updates_friends update history

updates_activity

h	updates_activity update history

photos_comments

Subarray structure
h	photos_comments update history
parent	parent (photo_id) for photos_comments

Sample API Request

Sample API Response

http://userapi.com/data?act=history&wall=992000002&id=1&sid=0b95f864b67a0b16d9d0fc20748b8e2d

{"wall": {"h": [[992000003, "add", [48872711, 1224866627, ["test"], [1, "Pavel Durov", "http://cs137.userapi.com/u00001/b_6261d317.jpg", "c_015fd76c", 2, 1], [1]]]]}, "nf": 271930, "nm": 0}

Pre-loading data

Client →

← Server

Parameters
act	'history'
inbox*	amount of 'inbox' entries to be loaded
outbox*	amount of 'outbox' entries to be loaded
friends_new*	amount of 'friends_new' entries to be loaded
fave*	amount of 'fave', 'fave_online' and 'faved' entries to be loaded
profile*	-1
us*	-1
read*	{id of 1st read private message}_{id of 2nd read message}_...

General structure of resulting array
inbox	Same as for inbox
outbox	Same as outbox
friends_new	Same structure as friends
fave	Same as fave
fave_online	Same as fave_online
faved	Same as faved
profile	Same as profile
us	id of current user

Sample API Request

Sample API Response

http://userapi.com/data?act=history&friends_new=2&us=-1&sid=55b15011458c72fa559b7431be8fec47

{"friends_new": {"n": 272396, "d": [[19224971, "Roman Boguslavsky", "http://cs266.userapi.com/u19224971/b_9fe20cc1.jpg"], [11116614, "Dmitry Shabala", "http://cs1209.userapi.com/u11116614/b_1b620100.jpg"]]}, "nf": 272396, "nm": 0, "us": 1}

Modification requests to the UserAPI database are performed by means of HTTP requests to userapi.com/data. The whole procedure is exactly the same as for data retrieval described above.
The error code is usually returned in "ok" field of resulting array. Negative values correspond to various error conditions, positive values mean success.

When a certain action (such as posting new messages) is performed too often, UserAPI can return the following array instead of expected result:

{"ok": -2}

This code means that a CAPTCHA has to be shown to the user. Following steps are required for this:

1. Generate captcha_sid - any random integer or real number of at least 8 decimal digits
2. Generate and show an image via: <img src='http://userapi.com/data?act=captcha&csid={captcha_sid}' />
3. Once the user enters the code, the original (unsuccessful) request has to be repeated with additional parameters:
..&fcsid={captcha_sid}&fccode={user-entered code}

Sample API Request	Sample API Response
http://userapi.com/data?act=add_wall&id=1&ts=647000005&message=tst&fcsid=0.615638748369059&fccode=9mn3h&sid=55b15011458c72fa559b7431be8fec47	{"ok": 1, "h": [[647000007, "add", [48897703, 1224891706, ["tst"], [1, "Pavel Durov", "http://cs137.userapi.com/u00001/b_6261d317.jpg", "c_015fd76c", 2, 1], [1]]]]}

When the session given by session id expires or any other authorisation failure occurs, UserAPI will return the following array instead of expected result:

{"ok": -1}

Such an answer means that automatic session prolongation is required before retrying any requests.

If automatic session prolongation fails, the User should be redirected to the Login page.

When login data are submitted the following error conditions may arise:

Error code	Explanation
Redirect to {site url}#index.html;sid=-1	Incorrect email or password
Redirect to {site url}#index.html;sid=-2	Incorrect CAPTCHA code while submitting email and password
Redirect to {site url}#index.html;sid=-3	Incorrect email or password, next login attempt must be submitted with a CAPTCHA code.
Redirect to {site url}#index.html;sid=-4	Incorrect email or password, CAPTCHA is not required

Registration of a new user on your site is achieved by submitting the following request:

Client →

← Server

Parameters
act	'register'
fn	user's given name(s)
ln	user's surname
email	user's email
pass	user's password
sex	user's gender
site	id of your Site
school	id of school chosen by user
year	graduation year
csid	captcha_sid for captcha
ccode	captcha code entered by user
back*	callback function

Error codes
1	Successful registration
-1	Incorrect captcha code
-2	Empty given name
-3	Empty surname
-4	Empty email
-5	Password too short
-6	User already registered
-7	User has been banned

Sample API Request

Sample API Response

http://userapi.com/data?act=register&s=397539&year=2013&fn=Iwan&ln=Smirnow&email=iwan-sm100@mail.ru&pass=777777777&sex=2&site=2&ccode=k86gz&csid=0.24627315661712001

1

After a successful registration the user will receive an e-mail with the account activation link.

User's profile data is changed by means of following requests:

Client →

← Server

Parameters
act	'edit_page'
fs	marital/relationship status
ln	surname
pv	political views
bd	birthday day
bm	birthday month
by	birthday year
cii	city id
mo	mobile phone number
nf	enable email notifications about new friend requests (1 or 0)
nm	enable email notifications about new messages and comments (1 or 0)
back*	callback function

Error codes
ok	1	success

Sample API Request

Sample API Response

http://userapi.com/data?act=edit_page&sx=2&fs=1&pv=3&bd=10&bm=10&by=1984&mo=7777777&cii=2&sid=95468d56b3a2dedd8fa9b6e03fc6c2d0

{"ok": 1}

Client →

← Server

'add_friend' parameters
act	'add_friend'
id	user id
'del_friend' parameters
act	'del_friend'
id	user id

Error codes
ok	0	user with specified id and current user are no longer friends
ok	1	friend request has been sent to specified user from current user
ok	2	specified user and current user are friends now
ok	3	incoming friend request from specified user has been accepted right now
ok	4	incoming friend request from specified user has been rejected

Sample API Request

Sample API Response

http://userapi.com/data?act=add_friend&id=18369759&sid=95468d56b3a2dedd8fa9b6e03fc6c2d0

{"ok": 3}

Client →

← Server

'add_fave' parameters
act	'add_fave'
id	user id
'del_fave' parameters
act	'del_fave'
id	user id

Result
ok	0	user removed from bookmarks
ok	1	user bookmarked
id	user id

Sample API Request

Sample API Response

http://userapi.com/data?act=del_fave&id=543870&sid=95468d56b3a2dedd8fa9b6e03fc6c2d0

{"ok": 0, "id": 543870}

Client →

← Server

'add_school' parameters
act	'add_school'
school	school id
year	graduation year
'delete_school' parameters
act	'delete_school'
school	school id
year	graduation year

Result structure
ok	1	success
ok	0	failure

Sample API Request

Sample API Response

http://userapi.com/data?act=add_school&school=3378&year=2004&sid=db9e1d4282d77ffffea070797ba0cea7

{"ok": 1}

Client →

← Server

'put_tag' parameters
act	'put_tag'
id	tagged user id
name	tagged user name
parent	{photo owner id}_{photo id}
'delete_tag' parameters
act	'delete_tag'
tid	tag id
parent	{photo owner id}_{photo id}
'confirm_tag' parameters
act	'confirm_tag'
tid	tag id
parent	{photo owner id}_{photo id}

General structure of resulting array
Array with all new tags on photograph

Structure of each entry of new tags array
tid	tag id
placer_id	id of user who placed this tag
id	tagged user id
name	tagged user name
x1	x coordinate of upper left corner, %
y1	y coordinate of upper left corner, %
x2	x coordinate of lower right corner, %
y2	y coordinate of lower right corner, %

Sample API Request

Sample API Response

http://userapi.com/data?act=put_tag&id=1&x1=31&y1=5.932203389830509&x2=81&y2=34.18079096045198&parent=1_3637189&name=Pavel Durov&sid=db9e1d4282d77ffffea070797ba0cea7

[{"tid": "3824227", "placer_id": "1", "id": "0", "name": "yabloko", "x1": 67, "y1": 23.45, "x2": 95, "y2": 38.7}, {"tid": "5022359", "placer_id": "1", "id": "1", "name": "Pavel Durov", "x1": 31, "y1": 5.93, "x2": 81, "y2": 34.18}]

Client →

← Server

'add_wall' parameters
act	'add_wall'
id	user id
ts	current wall version (timestamp)
message	message text
'add_message' parameters
act	'add_message'
id	user id
ts	current messages version (timestamp)
message	message text
'add_photos_comments' parameters
act	'add_photos_comments'
id	user id
ts	current photos_comments timestamp (ts)
message	message text
parent	{photo owner id}_{photo id}

Result structure
ok	1	success
	0	failure
	-1	authorisation error
	-2	flood control, captcha required
	-3	operation prohibited by privacy settings
h		updates history of object in question

Sample API Request

Sample API Response

http://userapi.com/data?act=add_message&id=5&ts=64000010&message=test&sid=db9e1d4282d77ffffea070797ba0cea7

{"ok": 1, "h": [[64000011, "add", [121503169, 1224926063, ["test"], [1, "Pavel Durov", "http://cs137.userapi.com/u00001/b_6261d317.jpg", "c_015fd76c", 2, 1], [5, "Ilya Perekopsky", "http://cs194.userapi.com/u00005/b_0e9c3bd8.jpg", "c_fcf3c114", 2, 1], 0]]]})

Client →

← Server

'del_wall' parameters
act	'del_wall'
id	user id
ts	current wall timestamp (ts)
wid	{user id}_{message id}
'del_message' parameters
act	'del_message' 'del_inbox' 'del_outbox'
id	user id
ts	current messages timestamp (ts)
wid	{user id}_{message id}
'del_photos_comments' parameters
act	'del_photos_comments'
id	user id
ts	current photos_comments timestamp (ts)
wid	{user id}_{comment id}
parent	{photo owner id}_{photo id}

Result structure
ok	1	success
ok	0	failure
h		updates history of object in question

Sample API Request

Sample API Response

http://userapi.com/data?act=del_message&id=197&wid=197_106183129&ts=64000095&sid=6fd0082c0589039a245d6adea72fe8eb

{"ok": 1, "h": [[64000097, "del", [106183129, 1224896986, "", [197], [1]]]]}

Client →

← Server

'restore_wall' parameters
act	'restore_wall'
id	user id
ts	current wall timestamp (ts)
wid	{user id}_{message id}
'restore_message' parameters
act	'restore_message' 'restore_inbox' 'restore_outbox'
id	user id
ts	current messages timestamp (ts)
wid	{user id}_{message id}
'restore_photos_comments' parameters
act	'restore_photos_comments'
ts	current photos_comments timestamp (ts)
wid	{user id}_{comment id}
parent	{photo owner id}_{photo id}

Result structure
ok	1	success
ok	0	failure
h		updates history of object in question

Sample API Request

Sample API Response

http://userapi.com/data?act=restore_photos_comments&id=1&wid=1_82500403&ts=361000047&parent=1_79435059&sid=6fd0082c0589039a245d6adea72fe8eb

{"ok": 1, "h": [[361000049, "undel", [82500403, 1210328210, ["are you totally crazy to upload theze fukked photos????fuck you must be an emryo of unborn bullshit!!!"], [1079177, "Danya Voodoo", "http://cs1578.userapi.com/u1079177/b_44294230.jpg", "c_aa97508d", 2, 1], [1], 0, 0, [79435059, "http://cs85.userapi.com/u00001/3440093/m_bde156aa.jpg"]]]]}

Uploading new photos requires knowledge of hashes obtained while loading user's profile.

Uploading photos

Important: the POST HTTP request with photo image file is submitted not to http://userapi.com/data, but to the following URL:

{value of ["pr"]["url"]}+upload.php

For example, if the value of ["pr"]["url"], obtained in a profile request, equals 'http://cs190.userapi.com/', then the URL for posting photos will be:

http://cs190.userapi.com/upload.php

Client →

← Server

Parameters for uploading main (profile) photo
act	'lprofile'
id	user id
hash	["pr"]["hash"] from profile
rhash	["pr"]["rhash"] from profile
file	image file (JPEG)
sid	Session ID
back	URL to redirect user's browser to after upload
Parameters for uploading album photos
act	'lphotos'
id	user id
oid	user id
hash	["ph"]["hash"] from profile
rhash	["ph"]["rhash"] from profile
aid	["ph"]["aid"] form profile
file1	image file 1
file2	image file 2 (may be absent)
file3	image file 3
file4	image file 4
file5	image file 5
file6	image file 6
sid	Session ID
back	redirect URL

Response structure
Regardless of the success of upload, user's browser is finally redirected to "back" URL, possibly through some intermediate URLs

Sample API Request

Sample API Response

http://cs190.userapi.com/upload.php?act=lprofile&id=1&hash=e41ae396adbb129786285e0cf35cc75e&rhash=49c248a12ccf77a3587cc994da9df191&sid=6fd0082c0589039a245d6adea72fe8eb&back=http://durov.ru/#1&file=...

Location: http://durov.ru/#1

Removing photos

Client →

← Server

Removal of main (profile) photo
act	'delete_page_photo'
Removal of an album photo
act	'delete_photo'
photo	'{owner id}_{photo id}'

Result structure
ok	1	success
ok	0	failure

Sample API Request

Sample API Response

http://userapi.com/data?act=delete_photo&photo=1_118073657&sid=6fd0082c0589039a245d6adea72fe8eb

{"ok": 1}

Client →

← Server

Updating current user's status
act	'set_activity'
ts	known 'activity' timestamp (ts)
text	new status text
Clearing all current user's statuses
act	'clear_activity'
ts	current 'activity' timestamp (ts)
Removal of current user's status
act	'del_activity'
ts	activity (ts)

Result structure
ok	1	success
ok	0	failure
h		updates history of 'activity' object

Sample API Request

Sample API Response

http://userapi.com/data?act=del_activity&id=1&wid=1_140403095&ts=754000053&sid=6fd0082c0589039a245d6adea72fe8eb

{"ok": 1, "h": [[754000055, "del", ["1_140403095"]]]}

All registered project leaders will be informed about new UserAPI capabilities by e-mail.