The API is a JSON-based API, in which parameters are sent to the server via traditional URL-based encoding, and responses are sent back to the client in Json format.

Log-in to OkCupid via the login service, detailed below. That returns a standard HTTP-cookie (name is session), which should then be sent back to the server with each subsequent request in the session. We recommend using TLS/HTTPS to encrypt the whole session. But we support either HTTP or HTTPs.

To invoke the API, rather than the regular site, either provide the URL parameter okc_api=1 or the HTTP header parameter:

  X-OkCupid-Api-Version: 1

We leave this parameter out in the documentation below, assuming it in all cases.

Output types in our API are in JSON. This section presents our way of describing what form this JSON should take.

In our JSON, we use 5 primitive types:

• b — boolean
• i — integer (64-bit signed)
• q — unsigned 64 bit integer, often used for user IDs. Note that JavaScript and some client libraries case 64-bit unsigned integers to double, causing loss of precision. Thus, we shit unsigned 64-bit integers in quoted form (e.g. “44991023949129394123”) so that the client doesn't have a chance to perform that incorrect conversion.
• s — string (UTF-8)
• t — timestamp (UNIX-style time since Jan 1970)
• e — error/status code (see table below).

Compound structures are combinations of these primitive types. For instance, here is a dictionary that has one field, named userid, that is of type q:

{  userid:q }

Here is an array of 0 or more ints:

[ i* ]

And here is an array of 0 or more dictionaries, each containing the field userid:

[ { userid:q }* }

We of course can combine these to make more complicated structures, as seen below:

{ 
   ints   : [ i* ],
   events : [ { type:s,
                 from:s }* ],
   people : [ { screenname:s, 
                 gender:s,
                 is_online:b,
                 userid:q }* ]
}

That is to say, the top-level object is a JSON dictionary, with three fields, events, ints, and people. events and people are both arrays of dictionaries, whereas ints is an array of integers.

Error sequences 0 through 99 are various flavors of `OK'. 100-plus are various flavors of failure.

These should probably be presented in this same order to maintain consistency with the website

“Units” is either “Miles” or “Kilometers”, depending on the logged-in user's settings

A Looking for value of 72 decodes to : (2^3 + 2^6) : LOOKING_SORTTERMDATING + LOOKING_SEXPARTNERS

(Some text here about what the API Key ought to be, and also X-OkCupid header fields like software version, device ID, etc).

Most API methods below output the following parameters:

• status:e — the status of the last operation
• status_str:s — a string representation of the status (optional)
• num_quiver:i — the number of quivers left after the last operation (mail sends and quiver rejections might change this)
• num_unread:i – the number of unread mails after the the previous operation
• authcode:s — an authentication code that some POSTs ought to send back to the server. Such a code is set to expire and only valid for the current user, so it's used as XSS-prevention.

Here is a method-by-method listing of the OkCupid API.

Get the events most relevant to this user (as deemed by the server)

None

    {
        events : [ { username:s,
                     time:t,
                     type:s,
                     online:b,
                     image:s,
                     contents:s,
                     class:s }* ],
	image:s,
        numunread:i,
	numquiver:i,
	location:s,
	locid:i,
        image:s,
	announce : { url:s, height:i, width:i}
        viewer: {
            userid: q,
            username: s,
            gender: i,
            age: i,
            orientation: i,
            relationship_status: i,
            ethnicity: [ i* ],
            children: i,
            drinking: i,
            smoking: i,
            drugs: i,
            education_level: i,
            education_status: i,
            jobtype: i,
            money: i,
            cats: i,
            dogs: i,
            religion: i,
            religion_serious: i,
            country: s
  },
     }

• events — an array of pertinent events
  • username — the main user involved
  • time — when the event happened
  • type — the type of the event (all-caps enumerated)
  • online — if the user is online or not
  • image — image of the user
  • content — the content of the event to be displayed in the feed
  • class — ?
• announce — An announcement iFrame to make a free-form announcement. The server-side can specify a height and width so that the client can correctly size the iframe. Eventually the client might specify the size of its display to help the server out in this regard.

Instantevents is the service that handles the chat client, buddy lists, and any sort of event-based notifications. We might enable some of these later on. There are two modes: poll and send. Poll is discussed here, and send is discussed below.

Call this method as:

''http://www.okcupid.com/instantevents?''//args// 

either via HTTP POST or GET. Input arguments are detailed below, and passed via URL-encoding, chained together with & characters. Use instantevents in polling mode to figure out which server-side events ought to be shown on the client (such as incoming IMs), who the user's buddies are, or both in one call.

Treating these two cases separately, the call:

 http://www.okcupid.com/instantevents?server_seqid=0&server_gmt=0

Will poll the server for events relevant to this user. If there is no event ready to show, it can wait up to a minute before replying. Once the server replies, it will return a server_gmt and a server_seqid. The client should turn around and send these back to the server on the subsequent call.

Another use is to immediately return the user's buddy list:

 http://www.okcupid.com/instantevents?buddylist=1&load_thumbnails=1&default_thumbnails=1&show_offline=1

Which will not return any events, just a list of people.

These two calls can be combined by supplying the additional parameter do_event_poll=1,:

 http://www.okcupid.com/instantevents?buddylist=1&do_event_poll=1&server_seqid=0&server_gmt=0

Which will poll the server for events. When an event is ready, it will return with the relevant events, and with a fully populated buddy list.

• buddylist=1 — return a full buddy list
• load_thumbnails=1 — load thumbnails for all buddies returned
• show_offline=1 — show offline as well as online users.
• default_thumbnails=1 — specify default thumbnails for users who don't have them.
• do_event_poll=1 — don't return right away, poll for the next interesting event.
• server_seqid=seqid — 0 on the first request, or the sequence ID returned by the server if known.
• server_gmt=server_gmt — the GMT time last output by the server.
• do_post_read=1 — post a read event which means that the user will get credit for having read the IM. Without this, the user might get messages in his inbox saying that he missed an IM.

Json Format:

{ 
   events : [ { type:s,
                 from:s,
                 to:s,
                 contents:s,
                 server_gmt:t,
                 server_seqid:i }* ],
   people : [ { screenname:s, 
                 gender:s, 
                 orientation:s,
                 location:s, 
                 thumb:s,
                 match:i,
                 friend:i,
                 enemy:i,
                 is_ok:b,
                 open_connection:b,
                 userid:q }* ],
    num_unread:i,
    num_quivers:i,
    status:b, 
    status_str:s
}

• status is either OK or FAIL_NEED_LOGIN to denote needing a login.

• buddylist=1
• show_offline=b
• load_thumbnails=b

[
    {
        userid:q,
        screenname:s,
        is_online:b,
        im_ok:b,
        thumbnail
    }*
]

The same instant events service, with different parameters, can also be used to send messages to other users via IM. The simple request:

 http://www.okcupid.com/instantevents?send=1&recipient=chris&body=yoyoyo+boo&rid=44455

Will send an IM to the user chris with the text yoyoyo boo.

• send=1 — turn this mode to 1 to enable 'sending'
• recipient=user — specify the user that the IM is going to
• body=text — specify the text to send in the IM
• rid=random — specify a new random token with each IM sent

{
    status:e,
    status_str:s,
    server_gmt:t
}

Most important, specify the status of the operation. Can be one of:

Call /login to establish a session with OkCupid. For a user with username max and a password pluto, you can post the following HTTP request to login:

 http://www.okcupid.com/login?username=max&password=pluto

If it's the correct username and password, a session will be established on the server-side. The server will send back cookies:

 username=mnk77; expires=Thu, 26 Jan 2012 17:07:42 GMT; path=/; domain=.okcupid.com
 guestid=; expires=Wed, 02 May 2007 17:07:42 GMT; path=/; domain=.okcupid.com
 session=590435105645882864%1234512345; expires=Tue, 02 Feb 2010 17:07:42 GMT; path=/;domain=.okcupid.com

The client should then back the values for session and username with each subsequent request to continue acting in the session.

• username=username — the username to log-in as
• password=password — the password to use when logging in

{
   screenname:s,
   userid:q,
   status:e,
   status_str:s
}

Here are the relevant error codes:

• username=username
• staff_override=1
• ajax=1

{
   screenname:s,
   userid:q,
   status:e,
   status_str:s
}

This API method offers both folder-level views of all of the threads in a given mailbox folder, and also message-level views of all of the messages in a given thread. We describe the folder view here, and the thread view below.

There are two relevant folders: inbox, sent and smiles. To access the first, issue:

 http://www.okcupid.com/mailbox?folderid=1&low=1

The output gives the active threads in that mailbox

• folderid — 1 for inbox, 2 for sent-mail and 3 for smiles
• low – the low thread to display. by default the low is 1 and there are 30 threads per page.

    { numunread:i, 
      numthreads:i,
      max_message:i,
      status:e,
      status_str:s,
      messages : [ 
         { thread_id:q,
           subject:s,
           person:s,
           snippet:s,
           msg_class:s,
           is_new:b,
           timestamp:i,
           thumbnail_path:s }* ] }

This “snippet” field shows the first 50 characters or so of the message. Each entry of the messages array is a dictionary, containing the description of a message thread.

One you have a valid thread ID, you can request the corresponding messages that comprise the thread:

  http://www.okcupid.com/mailbox?readmsg=1&threadid=5555541338581775397
  

Assuming it's a valid thread, you'll get back all messages in the given thread.

• readmsg=1 — toggle message rather than folder view
• threadid=tid — specify the thread to read (as returned by /mailbox in folder view)

    { is_quiver_msg:b,
      messages : [ { age_gen:s,
                      timestamp:t,
                      body:s,
                      receiver_name:s,
                      sender_name:s,
                      senderid:q,
                      image:s,
                      from_user:b,
                      from_me:b,
                      msgid:q,
                      is_anchor:b }* ],
       thread_start:t,
       threadid:q,
       subject:s,
       num_msg:i,
       authcode:s,
       showmatch:b,
       screenname:s,
       buddy_name:s,
       status:e,
       status_str:s }

Send a message in an existing thread by specifying a thread ID, or send in a new thread if no thread ID is specified.

• sendmg=1 — trigger send-message mode
• authcode=code — provide an authcode that the server previously supplied for this user
• threadid=tid — either 0 or the thread ID to put a reply into
• r1=username — provide the screenname of the user to send to.
• subject=subj — if not a new thread, provide a subject.
• body=body the body of the new message.

{ 
   num_unread:i,
   status_str:s,
   status:e,
   num_quivers:i,
   msgid:q 
}

For all of these features, the output is of the form:

{
    status:e,
    status_str:s
}

Block the given thread ID's sender. As also, thread IDs are 64-bit unsigned IDs.

• blockuser=1
• threadid=id

Delete the given thread from the server

• deletethread=1
• threadid=id

Change a thread from unstarred to starred, or vice-versa.

• starmsg=b — provide 1 or 0
• threadid=id

• searchprefs.display=1

{
    gentation: i,
    age_min: i,
    age_max: i,
    only_single: i,
    only_photos: i,
    lookingfor: i
}

Return a random user that the current user hasn't voted on yet. Pass votes themselves through /vote_handler, reloading /getlucky for each

• cgi_prefs=1 — This tells the service to override stored preferences with CGI
• locid=id — Location, as retrieved from /locquery
• age_from=i — Youngest acceptable aged user to return
• age_to=i — Oldest acceptable aged user to return
• gentation=g — Combined gender/orientation code to return
• shown_uid=uid — User ID of the last person shown. Use this if you want the server to return match/profile data for the previous person as well as the current person

{
	userid : q,
	username : i,
	pics : [ {
		thumb : s,
		pic : s,
		pic2 : s,
		caption : s
	}* ],
	essays : [ { title : s, body : s}* ],
	gender : i,
	prev : {
		uid: q,
		username : s,
		age : i,
		thumb : s,
 
		gender : i,
		gender_letter : s,
		pronoun : s,
 
		orientation : i,
		orient_name : s,
 
		status : i,
		status_name : s,
 
		location : s,
	},
	adjectives : [ s* ],
	percentage : i,
	fpercentage : i,
	epercentage : i,
	is_male : b,
	has_persona : b,
	persona : s
}

Vote 1 to 5 stars on a user or object, or add a note for a user

• score – the score, an integer between 1 and 5

• type — provide vote
• target_userid=userid
• target_objectid=objectid — 0 for users, otherwise pass id of object (quiz)
• vote_type — provide personality for people or quiz for quizzes

• type — provide note
• target_userid=userid
• note=string — note contents

{
    status:e
}

 http://okcupid.com/profile/username1/compare/username2

• This service returns numbers as strings.

• target_user_only=b – Will return an array of traits for username1
• common_traits_only=b – Will return traits that username1 and username2 both share

Trait data:

range : [min,max]
axis_high : description
axis_low : description

Example (http://okcupid.com/profile/frostedwheat/compare/staffrobot?okc_api=1):

{
  "status" : 0,
  "staffrobot": [
    {
      "range": [
        "12",
        "34"
      ],
      "axis_high": "more adventurous",
      "axis_low": "less adventurous"
    },
    ...
  ],
  "frostedwheat": [
    {
      "range": [
        "58",
        "98"
      ],
      "axis_high": "more adventurous",
      "axis_low": "less adventurous"
    },
    ...
  ]
}

Example (http://okcupid.com/profile/frostedwheat/compare/staffrobot?okc_api=1&target_user_only=1):

{
  "status" : 0,
  "frostedwheat": [
    {
      "range": [
        "58",
        "98"
      ],
      "axis_high": "more adventurous",
      "axis_low": "less adventurous"
    },
    ...
  ]
}

This service manages a user's uploaded photos. It is also necessary to register a photo with this service's “Add Photo” function after submitting the photo data through /ajaxuploader.

• picture.profile = 1
• albumid = 0

    { pics : [{ url:s,
                picid:q,
                caption:s,
                ordinal:i,
                primary:b }*] }

• picture.view_album = 1
• albumid = aid

    { pics : [{ url:s,
                picid:q,
                caption:s,
                ordinal:i,
                primary:b }*] }

• picture.add_ajax = 1
• userid = q
• picid = q
• status = 0
• width = i
• height = i
• tn_upper_left_x = i
• tn_upper_left_y = i
• tn_lower_left_x = i
• tn_lower_left_y = i
• caption = s

    { picid:q, error:s, type:s, status:i }

• error - nonempty with description if there was an error
• type - the type of the image uploaded (e.g. jpg, gif).

will be null if there was an error.

• status - 1 on success, and 0 on failure

• picture.update_ajax = 1
• userid = q
• picid = q
• captions = s

    { picid:q, error:s, type:s, status:i }

• picture.move_to = 1
• userid = q
• picid = q
• position = i # Makes primary photo when set to 0¡

    { picid:q, error:s, type:s, status:i }

• picture.delete_ajax = 1
• userid = q
• picid = q

    { picid:q, error:s, type:s, status:i }

• file = data / / octet stream
• filename = s

• submit = s
• img_template = ””
• status = 0
• commit = “commit”
• userid = q
• type = 1

    {
        id:q,
        url:s,
        thumb_url:s,
        from:s,
        width:i,
        height:i,
        type:s,
        original_source_url:s,
        original_source_file:s
    }

• id - the picture ID of the uploaded photo
• url - the URL on okcupid to access it
• thumb_url - like above, but the thumbnail URL
• from - one of {“ERROR”, “DIRECT”, “URL”}
• width - width of the uploaded photo
• height - height of the uploaded photo
• type - jpg, gif, etc…
• original_source_url - parroted back if from == “URL”
• original_source_file - parroted back if from == “DIRECT”

Visit /profile/username

    {
        userid:q,
        username:s,
        thumbnail:s,
        thumbnail_100:s,
        thumbnail_60:s,
        adjectives:[ s* ],
        status:i,
        status_str:s,
        gender:i,
        gender_str:s,
        orientation:i,
        orientation_str:s
        age:i,
        location:s,
        distance:i,
        units:s,
        join_date:i,
        last_login:i,
        is_buddy:b,
        is_blocked:b,
        matchpercentage:i,
        friendpercentage:i,
        enemypercentage:i,
        curr_score:i,
 
        is_online:b,
        distance:i,
 
        skinny: {
            ethnicities: [ s* ],
            lookingfor: [ s* ],
            languages: [ s* ],
            last_online: i,
            join_date: i,
            smoker: s
            height: i,
            bodytype: s,
            drinker: s,
            drugs: s,
            religion: s,
            religionserious: s,
            sign: s,
            sign_status: s,
            education: s,
            education_status: s,
            job: s,
            income: s,
            children: s,
            dogs: s,
            cats: s,
            dogsandcats: s
        },
        essays : [
            { essay : [ {
                    essay_editors : [ s* ],
                    lang : s,
                    text : s
                }* ],
            title }* ],
        photos : [ { caption: s, image_url: s }* ]
    }

• u=s
• woo=1
• ajax=1

{ status : e }

• u=s
• ajax=1
• addbuddy=1
• sendmessage=b

{ status : e }

• u=s
• ajax=1
• removebuddy=1

{ status : e }

• Visit /questions/ask

{
    ideal_answers: [ {
        text: s
    }* ],
    qtext: s,
    answers : [ {
        CHECKED: i,
        text: s
    }* ],
    question_num: i,
    max_match: s,
    num_answered_str: s,
    qid: q,
    no_skip: i
}

• submit2=i
• qid=i

{
    ideal_answers: [ {
        text: s
    }* ],
    qtext: s,
    answers : [ {
        CHECKED: i,
        text: s
    }* ],
    question_num: i,
    max_match: s,
    num_answered_str: s,
    qid: q,
    no_skip: i
}

• submit=1
• qid=i
• ac=i
• answers=i
• matchanswers*=i
• importance=Importance Code
• is_public=1

{
    no_skip: i,
    errors: [ s* ],
    num_answered_str: s,
    answers: [ {
        CHECKED: i,
        text: s,
    }* ],
    qtext: s,
    qid: i,
    max_match: s,
    question_num: i,
    ideal_answers: [ {
        text: s
    }* ]
}

Visit /visitors

stalkers = [ {
    count : i,
    event_acct_level : i,
    event_gets_badge : b,
    event_SHOW_IM : b,
    event_time : i,
    event_userid : s,
    event_username : s,
    event_age : i,
    event_gender : s,
    event_user_location : s,
    event_user_orientation : s,
    event_user_status : s,
    event_user_thumbnail : s,
    match_percentage : i,
    friend_percentage : i,
    enemy_percentage : i,
    image : s
}* ]

• JSON=1
• doFlag=1
• name=s
• type=i
• reason=s
• comment=comment string
• owner_id=uid
• object_id=tid

Note: The “name” field should be the username of the offender

{ status : e }

Visit /quiver

quiver = [ {
    userid : s,
    username : s,
    age : i,
    gender : s,
    orientation : s,
    thumbnail_filepath : s,
    location : s,
    uber_description : s,
    note : s,
    reject : b
}* ]

• reject=userid

quiver = [ {
    userid : s,
    username : s,
    age : i,
    gender : s,
    orientation : s,
    thumbnail_filepath : s,
    location : s,
    uber_description : s,
    note : s,
    reject : b
}* ]

• func=query (use the exact string “query”)
• query=query string (such as “Seattle”)
• cbust=random

{
    status: e,
    query: s,
    locid: i,
    results: [ {
        locid: i,
        text: s
    }* ]
}

• full_img_path=1
• low=N
• use_filter_prefs=1
• discard_prefs=1
• loc_lookup=1
• locid=id
• filterN=type,param1[,param2]
• sortN=type,param

NOTE: The low parameter is how you control pagination. Basically a 1-indexed number indicating which item to start with. IMPORTANT: Only pass this in when N != 1

So for example, if you want single straight females with pictures, you'd pass:

• ?filter1=0,17&filter2=1,1&filter3=7,1

The parameter of a sort is the weight to be put on sorting on that dimension. You should just pass in “100” for a sort on a single dimension. Some examples are:

{
    username: s,
    foundany: i,
    maxmatch: i,
    lquery: s,
    numanswered: i,
    filters: {
        gentation: i,
        locid_str: s,
        gentation_str: s,
        locid: i,
        photos_only: s,
        radius: i,
        lquery: s,
        age_min: i,
        age_max: i,
        single_only: s,
        desc: s
    }
 
    amateur_results: [ {
        personality_orientation: i,
        r_ncontacts_in_28_no_im: s,
        s_looks_perc_adj_1: s,
        r_account_age: s,
        uber_description: s,
        match_perc: s,
        s_gender: s,
        note: s,
        message_votes: i,
        contacts_this_week: i,
        uncontacted_index: i,
        last_contact: i,
        personality_gender: i,
        s_avg_msg_vote_10_1: s,
        online_now: i,
        VIEWEE_PRO_STATUS: i,
        personality_code: s,
        age: i,
        last_login: i,
        location: s,
        friend_percentage: i,
        thumbnail_filepath: s,
        recent_contacts: i,
        personality: s,
        status: s,
        contacts_today: i,
        HAS_CR: i,
        age_delta: s,
        personality_score: i,
        s_profile_len: s,
        enemy_percentage: i,
        r_ncontacts_in_28: s,
        reply_perc: i,
        which_essay: i,
        match_percentage: i,
        uncontacted: i,
        reciprocol_percentage: i,
        message_points: i,
        r_reply_ratio_28_4_no_im: s,
        s_ncontacts_in_28_no_im: s,
        orientation_code: i,
        SHOW_IM: i,
        userid: s,
        first_contact_time: i,
        username: s,
        join_date: i,
        MEMBERS_ONLY: i,
        gender: s,
        recent_replies: i,
        contact_rating: i
    }* ],
 
    alist_results: [ {
        // Same structure as amateur results
    }* ]
}

• lat_long_loc=1
• lat=latitude
• long=longitude

{
    locid: i,
    location: s
}

• ajax: 1
• cf: iphone
• gender: i
• orientation: i
• status: i
• birthday: i
• birthmonth: i
• birthyear: i
• screenname: s
• password: s
• email: s
• email2: s
• locid: q
• captcha_input: q
• captcha_key: q
• corrections_page: ”/signup/paths/json/corrections.html”
• success_page: ”/signup/paths/json/success.html”