Application API Search searches POST

October 15, 2026 at 9:35 AM

/searches [POST]

Performs a basic search and returns profiles under a number of filters - protected.

Note: Both POST and GET are accepted here. POST is recommended.

Parameters

/searches accepts two types of parameter:

  • search criteria
  • control parameters

Search criteria include all items returned by GET /searches/questions that a member has access to. Each criterion is specified as a map, and either:

  • value - string or numeric value to match
  • values - an array of string or numeric values to match (any of) - most search criteria should use this
  • from, to - a numeric range of values to match (anything within the range, e.g., age or height)
  • within, of - a geolocation criterion specifying a zipcode or lat/lon comma-separated pair (of) and a number of miles (within)

Examples:

  • {"age" : {"from" : 18, "to" : 30}, "location" : {"within" : 500, "of" : "40.730610,-73.935242"}}
  • {"age" : {"from" : 18, "to" : 30}, "zipcode" : {"within" : 500, "of" : "11212"}, "country" : {"value" : "US"}}
  • {"age" : {"from" : 18, "to" : 30}, "state" : {"value" : "New York"}, "country" : {"value" : "US"}}

Platinum vs Basic - The GET /searches/questions API returns search criteria information partitioned into basic, platinum, and (my) matches. This allows client applications to show Platinum criteria to all end users but client applications should not allow non-platinum (non-subscriber) members to select and submit Platinum criteria, only Basic criteria (and My Match criteria). If a search is performed by a non-subscriber, any Platinum-only criteria are silently ignored with one exception: within on a geolocation. If a non-subscriber provides a within distance value that is Platinum-only, a failure code will be returned.

  • any of the standard Search Control Parameters.
  • the default excludes list is blocks, declines, likes.
  • the default for sortby is distance; see additional sortby options in the note below.

Note: if you are searching for platinum_status true (optionally with auto_renew_status either true or false), you may want to sort on one of the following: platinum-asc, platinum-desc, platinum-score-asc, or platinum-score-desc. These refer to platinum expiration date order and whether the relevance score is considered or not (without the score, matches are sorted purely on the expiration date with no consideration of how good a match they are to the criteria passed in – beyond the minimum gender/preference and any criteria that cull/filter results rather than just match them).

Response Messages

403 Forbidden

The possible failcode entries are:

  • 31000 - the criterion value is ill-formed (not a hash map)
  • 31003 - a general criterion value does not contain either value or values
  • 31004 - a range criterion value does not contain to and from, or their values are not numeric, or the from value is higher than the to value
  • 31005 - an age range criterion value has to and/or from values outside the range 18..120
  • 31006 - a geolocation criterion does not contain within and of values, or the within value is not a numeric value from the set -1, 20, 30, 40, 50, 150, 500, 1000
  • 31007 - a geolocation criterion has a within value of 20, 30, 40, or 50 but the member is not platinum (only platinum members can specify those smaller distances)
  • 31008 - the criterion is only available to platinum members (the current member is not a subscriber)
  • 31009 - the criterion value(s) specified are not legal for this criterion (e.g., 50 for smoking, which only has 10, 20, 30, and 40 as legal values)
  • 31010 - the country criterion value is illegal (not a valid two-letter ISO code)
  • 31011 - the zipcode criterion value is illegal (for the member’s country)
  • 31012 - the age criterion is missing: it is required for all searches
  • 31013 - only one of zipcode, state, or location may be provided (they are both optional but they are mutually exclusive)
{ "fail" : "Invalid Argument", "failcode" : [ ... ] }

200 OK - success

The result includes:

  • totalmatches - the total number of matches in the entire search result set
  • page - the current page number within the result set
  • pagesize - the number of results on each page (reflecting pagesize passed as a parameter)
  • currentpagesize - the actual number of results on this page
  • users - an array of user status information, including additional relevance (0.0-1.0) and exactmatch (boolean) fields; if sortby "distance" was specified in the parameters (the default sortby value) then there will be an additional distance field in each user status information structure saying how many miles from the search location each member is
{
  "totalmatches" : 1430,
  "page" : 4,
  "pagesize" : 15,
  "currentpagesize" : 15,
  "users" : [
    { user status information },
    { user status information },
    ...
  ]
}