Member Quicksearch API

Overview

Quicksearch is a single read-only endpoint. You send your site GUID plus the filters you want, and it returns a list of member profiles: display name, age, location, headline, profile summary, interests, rating and a photo URL.

It is the same endpoint that powers the member showcase on HubPeople hosted pages, so the members you see through the API are the members your visitors see.

Typical uses:

• Show real local members on a custom landing page to build trust before registration
• Populate a "members near you" block on your own site or app
• Build location pages for the towns and cities you market in
• Check what your member pool looks like in a given country, region or city

Returning integrators: see the Changelog for what has changed since you last implemented.

Endpoint

A single GET request returns JSON.

GET https://api.hub-cdn.com/api/hs/quicksearch

All filters are supplied as URL query string parameters. All values must be URL encoded.

Authentication

There is no API key, token or secret. The request is identified by the guid parameter, which is your site GUID. HubPeople hosted pages call this endpoint directly from the visitor's browser, so it is reachable from client side JavaScript as well as from your own server.

Because there is no secret involved, treat your site GUID as public information, and treat the response as personal data (see Data Protection below).

Finding your site GUID

This is the same site GUID used by the Registration URL API, so if you have already integrated registration you are holding it. There are two places to find it, and it is a one off: your site GUID does not change over the life of the brand.

From the Founders Account tab

This works for every brand and takes under a minute. You only need to do it once.

1. Sign in to the portal at portal.hubpeople.ai.
2. In the left hand menu, click My Brands.
3. Click the brand you want the GUID for. This opens that brand's detail page, with a row of tabs across it.
4. Open the Founders Account tab.
5. Click the button on that panel. It reads Login if you already have a Founders Account, or Create if you do not. Either one is fine for this purpose.
6. A new browser tab opens. Look at its address bar.

The exact address varies. It differs depending on your brand, on whether the button said Login or Create, and it grows as the page moves you into the sign up flow. So do not count slashes or take the end of the address. Use this rule instead, which holds in every case:

Your site GUID is the first GUID shaped value in the address.

A GUID is 36 characters, hexadecimal, in five hyphen separated groups of 8, 4, 4, 4 and 12:

00000000-0000-0000-0000-000000000000

It always sits just after /s/register/ or /s/login/. Here are two real shapes, both carrying the same GUID:

https://members.yourbrand.com/s/login/00000000-0000-0000-0000-000000000000

https://members.yourbrand.com/s/register/00000000-0000-0000-0000-000000000000/t/1f4c9e2a.../membertype
                                         |________________________________|  |__________|  |________|
                                               your site GUID                   ignore       ignore

Nothing else in that address is your GUID:

• The value after /t/ is 32 characters with no hyphens. It is a one time value for that sign up session, not part of your integration, so ignore it and do not copy or share it.
• The final segment is whichever step the flow has reached, such as membertype. More segments may appear as you go. None of them is the GUID.

If you are extracting it in code, match on the shape:

[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}

7. Copy that GUID.
8. Close the tab. You do not need to sign in, and if the button said Create you do not need to fill anything in. Opening the page does not create an account.

It does not change, so save it somewhere alongside your other integration settings rather than repeating these steps.

To check you have the right value, just use it. An unrecognised site GUID is rejected outright with 400 Bad Request, so a 200 response with members in it tells you the GUID is valid for your site. You do not need to recognise the individual members.

From a registration or login link you already have

It is the same value, so if you have already integrated registration you are holding it:

https://auth-affinity.com/s/register/00000000-0000-0000-0000-000000000000

If neither route works for you, your account manager can give you the GUID.

Either way, the quickest confirmation is to make one call with it: an unrecognised GUID returns 400 Bad Request, a valid one returns 200 with a list of members.

Query Parameters

Location, age and member type filters are all optional. Sending none of them returns a general sample for your site.

Parameter names are not case sensitive, so ageMin and AgeMin behave identically. The spellings above are the ones the platform generates, so they are the safest to copy.

Showing your own members

Send myBrandMembersOnly=TRUE on every request. Partners should only show their own members, meaning the people who joined through your brand. Those are the members your visitors can actually go on to meet, so showing them keeps what a visitor sees on your pages consistent with what they find after they register.

This is a requirement, not a preference, and it also happens to be in your favour. Members who did not join through your brand can be shown on other partners' sites as well, so the same profile text can end up published in several places at once. Search engines treat that as duplicate content: they may filter it out of results or credit it to whichever site they saw it on first, which weakens the very pages you are trying to rank. Your own members are the ones that are genuinely yours, and they are the ones a visitor can go on to meet.

Leaving the parameter out is not the same as setting it to TRUE, so send it explicitly on every call rather than relying on the default.

Platform

You can leave this out. The service works out which member platform to search from your site GUID, so the parameter is not needed and omitting it returns the same members.

You will see it in URLs generated inside the platform, where the value is affinite for Affinity brands and excite for Excite brands. Sending it does no harm, and neither does leaving it off. If you are copying an existing URL, just leave whatever is already there.

Member types

Supply membertypes as a comma separated list. Omit the parameter to leave member type unfiltered.

Example

membertypes=female,male

Which types actually return profiles depends on your brand's member pool, so a type that exists on the platform may still come back empty for a narrow location.

Couple profiles describe two people, so they carry both ages in the MemberAges field of the response. See Response below.

Location

Supply any combination of country, region and city. Each one narrows the search further, so country on its own gives you a national sample and adding city pinpoints a town.

Example

country=USA
region=Texas
city=Dallas

Values are matched against the platform's own location data, so they must be spelled the way the platform holds them. Matching is not case sensitive, so Australia and australia behave the same.

An unrecognised value is not an error. If you send a country, region or city the platform does not hold, you will not get an error or an empty list. You will get members that simply are not filtered the way you intended. A typo therefore fails silently and looks like working code, so take your values from the Location reference below and check that a new filter returns the members you expect before you build a page on it.

Age range

Both ends of the range accept 18 to 90. Every member on the platform is 18 or over, so 18 is the effective floor.

ageMin=25
ageMax=45

Result count and photo size

Ask for no more than 20 profiles. Twenty is comfortably enough for a members block or a location page, it keeps the response small and quick, and it keeps the number of member profiles sitting on your pages proportionate to what you actually display.

The service itself will not return more than 50 however many you request, so 50 is a hard ceiling rather than a target. Requesting a large block and trimming it in your own code means pulling member data you never show, which is exactly what the guidance under Data Protection asks you to avoid.

imageSize is requested in pixels. HubPeople's own components use imageSize=80.

Location reference

The platform holds members in 10 countries, divided into 300 regions and around 50,000 towns and cities. Countries and regions are listed in full below, which is everything you need to build country and region pickers. The full city list is large, so it lives in a separate reference.

Countries

Send the country name exactly as written above. Note that the United States is USA and the United Kingdom is UK, not their longer names.

Regions

Every valid region value, grouped by country.

USA (55)
Alabama, Alaska, Arizona, Arkansas, Armed Forces Pacific, California, Colorado, Connecticut, Delaware, District of Columbia, Federated States of Micronesia, Florida, Georgia, Hawaii, Idaho, Illinois, Indiana, Iowa, Kansas, Kentucky, Louisiana, Maine, Maryland, Massachusetts, Michigan, Minnesota, Mississippi, Missouri, Montana, Nebraska, Nevada, New Hampshire, New Jersey, New Mexico, New York, North Carolina, North Dakota, Ohio, Oklahoma, Oregon, Palau, Pennsylvania, Puerto Rico,, Rhode Island, South Carolina, South Dakota, Tennessee, Texas, Utah, Vermont, Virginia, Washington, West Virginia, Wisconsin, Wyoming

UK (107)
England: Avon, England: Bedfordshire, England: Berkshire, England: Bolton, Greater Manchester, England: Buckinghamshire, England: Bury, Greater Manchester, England: Cambridgeshire, England: Cheshire, England: City of Manchester, Greater Manchester, England: City of Salford, Greater Manchester, England: Cornwall, England: Cumbria, England: Derbyshire, England: Devon, England: Dorset, England: Durham, England: East Sussex, England: Essex, England: Gloucestershire, England: Greater London, England: Hampshire, England: Hereford and Worcester, England: Hertfordshire, England: Isle of Wight, England: Kent, England: Lancashire, England: Leicestershire, England: Lincolnshire, England: Merseyside, England: Norfolk, England: North Humberside, England: North Yorkshire, England: Northamptonshire, England: Northumberland, England: Nottinghamshire, England: Oldham, Greater Manchester, England: Oxfordshire, England: Rochdale, Greater Manchester, England: Shropshire, England: Somerset, England: South Yorkshire, England: Staffordshire, England: Stockport, Greater Manchester, England: Suffolk, England: Surrey, England: Tameside, Greater Manchester, England: Trafford, Greater Manchester, England: Tyne and Wear, England: Warwickshire, England: West Midlands, England: West Sussex, England: West Yorkshire, England: Wigan, Greater Manchester, England: Wiltshire, N.ireland: Antrim, N.ireland: Armagh, N.ireland: Belfast, N.ireland: Down, N.ireland: Fermanagh, N.ireland: Londonderry, N.ireland: Tyrone, Scotland: Aberdeenshire, Scotland: Angus, Scotland: Argyll, Scotland: Ayrshire, Scotland: Dumfries and Galloway, Scotland: Dunbartonshire, Scotland: East Lothian, Scotland: Edinburgh, Scotland: Fife, Scotland: Glasgow, Scotland: Invernessshire, Scotland: Isle of Lewis, Scotland: Isle of Shetland, Scotland: Lanarkshire, Scotland: Midlothian, Scotland: Morayshire, Scotland: Orkney Islands, Scotland: Perthshire, Scotland: Renfrewshire, Scotland: Stirlingshire, Scotland: The Scottish Borders, Scotland: West Lothian, Wales: Blaenau Gwent, Wales: Bridgend, Mid Glamorgan, Wales: Caerphilly, Gwent, Wales: Caerphilly, Mid Glamorgan, Wales: Cardiff, South Glamorgan, Wales: Carmarthenshire, Dyfed, Wales: Ceredigion, Dyfed, Wales: Conwy, Clwyd, Wales: Conwy, Gwynedd, Wales: Denbighshire, Clwyd, Wales: Flintshire, Clwyd, Wales: Gwynedd, Gwynedd, Wales: Isle of Anglesey, Gwynedd, Wales: Merthyr Tydfil, Mid Glamorgan, Wales: Monmouthshire, Gwent, Wales: Neath Port Talbot, West Glamorgan, Wales: Newport, Gwent, Wales: Pembrokeshire, Dyfed, Wales: Powys, Wales: Rhondda Cynon Taff, Mid Glamorgan, Wales: Swansea, West Glamorgan, Wales: Torfaen, Gwent, Wales: Vale of Glamorgan, South Glamorgan, Wales: Wrexham, Clwyd

Spain (16)
Andalucia, Aragon, Asturias, Cantabria, Castilla y Leon, Castilla-La Mancha, Catalonia, Comunidad Valenciana, Extremadura, Galicia, Islas Baleares, La Rioja, Madrid, Murcia, Navarra, Pais Vasco

Australia (8)
Australian Capital Territory, New South Wales, Northern Territory, Queensland, South Australia, Tasmania, Victoria, Western Australia

Brazil (27)
Acre, Alagoas, Amapa, Amazonas, Bahia, Ceara, Distrito Federal, Espirito Santo, Goias, Maranhao, Mato Grosso, Mato Grosso do Sul, Minas Gerais, Para, Paraiba, Parana, Pernambuco, Piaui, Rio Grande do Norte, Rio Grande do Sul, Rio de Janeiro, Rondonia, Roraima, Santa Catarina, Sao Paulo, Sergipe, Tocantins

Canada (13)
Alberta, British Columbia, Manitoba, New Brunswick, Newfoundland and Labrador, Northwest Territories, Nova Scotia, Nunavut, Ontario, Prince Edward Island, Quebec, Saskatchewan, Yukon Territory

Ireland (26)
Carlow, Cavan, Clare, Cork, Donegal, Dublin, Galway, Kerry, Kildare, Kilkenny, Laois, Leitrim, Limerick, Longford, Louth, Mayo, Meath, Monaghan, Offaly, Roscommon, Sligo, Tipperary, Waterford, Westmeath, Wexford, Wicklow

Argentina (24)
Buenos Aires, Catamarca, Chaco, Chubut, Cordoba, Corrientes, Distrito Federal, Entre Rios, Formosa, Jujuy, La Pampa, La Rioja, Mendoza, Misiones, Neuquen, Rio Negro, Salta, San Juan, San Luis, Santa Cruz, Santa Fe, Santiago del Estero, Tierra del Fuego, Tucuman

South Africa (10)
Eastern Cape, Free State, Gauteng, KwaZulu-Natal, Limpopo, Mpumalanga, North-West, North-Western Province, Northern Cape, Western Cape

New Zealand (14)
Auckland, Bay of Plenty, Canterbury, Gisborne, Hawke`s Bay, Manawatu-Wanganui, Marlborough, Nelson, Otago, Southland, Taranaki, Waikato, Wellington, West Coast

Two things to watch in the UK list. UK regions carry a nation prefix, as in England: Cornwall, so the colon and the space are part of the value. Some region values also contain a comma of their own, as in England: Bolton, Greater Manchester. Send the value whole and URL encode it. Do not split region values on commas, and do not confuse this with membertypes, which is genuinely a comma separated list.

Cities

There are around 50,000 cities and towns, far too many to list on a page. They are published as JSON instead, under Machine readable downloads below, either one country at a time or all of them in one file.

Those files are the reference list. If a city you expect is not in them, it is not a value this endpoint will match.

Machine readable downloads

For building against rather than reading, the same data is published as JSON. Download it once and keep your own copy; do not fetch it on every request.

Take the smallest file that answers your question. Most integrations only need the first one.

view opens the file in a new tab, so you keep your place on this page. download saves it straight to your machine.

These files are meant to be downloaded and parsed, not read in a browser tab. They are laid out with one line per region, which keeps them compact, but the full file is still 50,000 cities. If you open it in a browser and switch on the JSON viewer's Pretty-print option, it will expand to roughly 68,000 lines and can hang the tab. To look at the data by eye, open a per country file, or the countries and regions file, rather than the full one.

Per country files

Shape

generated is the date the data was last refreshed. locations.json nests city under region under country:

{
 "generated": "2026-08-18",
 "countries": {
  "Australia": {
   "Victoria": ["Melbourne", "Geelong", "Ballarat"]
  }
 }
}

A per country file drops one level and names the country instead:

{
 "generated": "2026-08-18",
 "country": "Australia",
 "regions": {
  "Victoria": ["Melbourne", "Geelong", "Ballarat"]
 }
}

In countries-regions.json each country maps to a plain array of region names, with no cities at all.

These files are the reference list for this endpoint, last refreshed on 18 August 2026. Countries and regions rarely change, and this page is updated when they do, so refreshing your copy once or twice a year is plenty. The generated date tells you which version you are holding.

Complete Example

Your own members, aged 25 to 45, female and male, in Dallas, Texas:

https://api.hub-cdn.com/api/hs/quicksearch
?country=USA
&region=Texas
&city=Dallas
&ageMin=25
&ageMax=45
&myBrandMembersOnly=TRUE
&membertypes=female,male
&results=30
&guid=00000000-0000-0000-0000-000000000000
&imageSize=80

With curl, from broad to narrow

Start broad, confirm you get members, then add one filter at a time. Substitute your own site GUID for the zeros. Each of these is a complete, runnable command.

1. Your members, no filters. Start here. If this returns members, your GUID is right and everything after this is refinement.

curl "https://api.hub-cdn.com/api/hs/quicksearch?guid=00000000-0000-0000-0000-000000000000&myBrandMembersOnly=TRUE&results=20&imageSize=80"

2. Narrow to a country.

curl "https://api.hub-cdn.com/api/hs/quicksearch?guid=00000000-0000-0000-0000-000000000000&myBrandMembersOnly=TRUE&country=UK&results=20&imageSize=80"

3. Add member type and an age range.

curl "https://api.hub-cdn.com/api/hs/quicksearch?guid=00000000-0000-0000-0000-000000000000&myBrandMembersOnly=TRUE&country=UK&membertypes=female&ageMin=25&ageMax=45&results=20&imageSize=80"

4. Add a region. Note the encoding: this region name contains a colon and a space, which become %3A and %20.

curl "https://api.hub-cdn.com/api/hs/quicksearch?guid=00000000-0000-0000-0000-000000000000&myBrandMembersOnly=TRUE&country=UK&region=England%3A%20Greater%20London&membertypes=female&ageMin=25&ageMax=45&results=20&imageSize=80"

5. Narrow to a city. This is as tight as it gets.

curl "https://api.hub-cdn.com/api/hs/quicksearch?guid=00000000-0000-0000-0000-000000000000&myBrandMembersOnly=TRUE&country=UK&region=England%3A%20Greater%20London&city=London&membertypes=female&ageMin=25&ageMax=45&results=20&imageSize=80"

Watch the record count fall as you add filters. On a large brand every step may still return your full results count; on a smaller one it drops away quickly, which is the honest signal that a filter is too tight for your member base. Remember that an unrecognised location does not error, so if the count does not change when you add a location, check the spelling against the Location reference.

With JavaScript

Replace the GUID with your own and this will run as it stands.

const params = new URLSearchParams({
  guid: '00000000-0000-0000-0000-000000000000',
  country: 'USA',
  region: 'Texas',
  ageMin: 25,
  ageMax: 45,
  membertypes: 'female,male',
  myBrandMembersOnly: 'TRUE',
  results: 20,
  imageSize: 80,
});

const response = await fetch(
  'https://api.hub-cdn.com/api/hs/quicksearch?' + params,
);
const members = await response.json();

members.forEach((member) => {
  console.log(member.MemberName, member.MemberAge, member.City);
});

Because URLSearchParams encodes the values for you, this also handles the region names that contain a comma or a colon.

If your pages are hosted on the HubPeople CMS, note that custom JavaScript is not enabled on every brand. See Keeping profiles current for what to do if it is not enabled on yours.

Response

The response is a JSON array of member profiles. Each profile contains these fields:

Example response, shortened to one profile with placeholder values:

[
  {
    "MemberName": "ExampleMember",
    "MemberImage": "https://affinity-media.hub-cdn.com/profile/ExampleMember.jpg?size=80",
    "MemberAge": 34,
    "MemberAges": "34",
    "City": "Dallas",
    "Region": "Texas",
    "Country": "USA",
    "Headline": "New here and looking to meet people locally",
    "Description": "I moved to Dallas last year and I am still finding my way around.",
    "Interests": "A Relationship,Friendship",
    "Rating": 4.4,
    "IdVerified": false
  }
]

Build against the fields in the table above, and treat every field as optional in your own code: a member who has not filled in a headline or interests will come back with those fields empty.

Member photos

MemberImage is a ready to use absolute URL on the platform's media host, with the size you asked for applied as a size parameter:

https://affinity-media.hub-cdn.com/profile/ExampleMember.jpg?size=80

Affinity photos are served from affinity-media.hub-cdn.com and Excite photos from excite-media.hub-cdn.com.

Two things worth knowing:

• You can change the size value on a returned URL to fetch a larger version, which is useful when the same profile appears both as a small thumbnail and as a larger card.
• The member media hosts support the size parameter only. They do not do format conversion or quality settings, so you cannot request WebP versions of member photos the way you can with brand images on b.hub-cdn.com.

Request the size you will actually display. Asking for a large size and scaling it down in CSS wastes your visitors' bandwidth.

Keeping profiles current

Member profiles are not static. People edit them, and people leave. If a member's profile is removed from the platform, your pages should stop showing that member shortly afterwards.

How you do that depends on whether you call the endpoint when a page is viewed, or publish its results into pages ahead of time. Both are fine, and they need different things from you.

Calling the endpoint live

This is the simpler option and the one we would suggest. Responses are returned with Cache-Control: public, max-age=60, so an identical request made again within the minute is answered from cache rather than reaching the service. Honour that header and ordinary HTTP caching does the work for you: a busy page does not generate one call per visitor.

Do not defeat it by appending changing values to the query string to force a fresh response. That bypasses the cache, multiplies your traffic and gains you nothing, since the underlying data does not change minute to minute.

There is no published rate limit, and normal use is unlikely to approach one. If you are calling the endpoint often enough to wonder, that is usually a sign the cache header is being bypassed rather than a sign you need a higher limit.

Publishing results into pages

So if you write results into pages instead of calling the endpoint on each view, refresh them at least once a day. A daily scheduled job is the minimum. More often is better, and calling live is better still.

A profile written into a static page stays there until something rewrites it, so a page you publish and forget will still be showing those members in a year.

This is the partner's responsibility. If you choose to use this endpoint, keeping the members you display in step with the platform is down to you.

If your pages are on the HubPeople CMS

Custom JavaScript is not enabled on every brand on our CMS. If it is not enabled on yours, you cannot make a live call from the page itself, so you will be publishing member data into the page instead.

That does not exempt you from the one day rule. If you cannot call live, you must refresh the published page at least daily by whatever means you do have. If you cannot commit to that, do not put member profiles on the page.

Coming soon We are building proper support for this: member snippet placeholders and JavaScript widgets that let you request members for a page and have the platform handle fetching them and keeping the page current, so you will not have to manage freshness yourself. This guide will be updated when that ships.

If your pages are not on the HubPeople CMS

You will need to handle this yourself. Either call the endpoint live when the page is viewed, or refresh on a schedule frequent enough that a removed member does not linger.

Site rating

A companion endpoint returns headline numbers for your site rather than individual profiles, which is handy for a stat band or a rating badge:

GET https://api.hub-cdn.com/api/hs/siterating

It takes guid, membertypes, results and imageSize, and returns:

HubPeople's own rating block requests 5 results from this endpoint. results controls how many photos come back in MemberImages, not a number of profiles.

That matters most when you place it next to a location. Putting the figure on a page about Essex implies it describes Essex, and the number can easily exceed the population of the place you have named, which destroys the credibility of the page it was meant to support. The same applies to any claim of the form "N members near you".

Safe uses are ones where the number is honestly platform wide: overall scale, a rating badge, or a row of member photos. If you want a count that genuinely reflects a place, do not use this endpoint. Use quicksearch with the location filters you actually mean, and count what comes back, remembering that results caps at 50 so it will not give you a true total either.

If in doubt, do not publish the raw number. Check with your account manager what it represents for your brand.

A third endpoint, api/hs/search, exists on the same service. It is not covered by this document; use quicksearch for the member sampling described here.

Example use cases

Three worked examples showing how to shape the query for a real page. All of them keep myBrandMembersOnly=TRUE, and all were run against a live brand before being written down.

A city landing page: women in London

The straightforward case. You are building a page targeting one city, so filter to it directly and add an age range that suits the page.

curl "https://api.hub-cdn.com/api/hs/quicksearch?guid=00000000-0000-0000-0000-000000000000&myBrandMembersOnly=TRUE&country=UK&city=London&membertypes=female&ageMin=25&ageMax=40&results=20&imageSize=80"

On the brand we tested this returned 9 members, every one of them in London. Note the count: a tight city plus gender plus a 15 year age band is a narrow ask, so you get what genuinely exists rather than a padded 20. Design the page to look right with 9 tiles, or loosen a filter.

A small town with no members: widen without leaving the area

The case that catches people out. You want women in Acampo, California, a small town:

curl "https://api.hub-cdn.com/api/hs/quicksearch?guid=00000000-0000-0000-0000-000000000000&myBrandMembersOnly=TRUE&country=USA&region=California&city=Acampo&membertypes=female&results=20&imageSize=80"

That returns an empty list. There is nothing wrong with the request; there are simply no matching members in that town. Do not respond by dropping myBrandMembersOnly or by widening to the whole country, which would put members thousands of miles away on a page about Acampo.

Drop the city and keep the region. You stay in California and get a usable block:

curl "https://api.hub-cdn.com/api/hs/quicksearch?guid=00000000-0000-0000-0000-000000000000&myBrandMembersOnly=TRUE&country=USA&region=California&membertypes=female&results=20&imageSize=80"

That returned a full set for us, drawn from Los Angeles, San Francisco, San Jose and elsewhere in the state. The page can then honestly say "women in California" rather than claiming Acampo.

This city, then region, then country ladder is the pattern to implement: request the narrowest thing you want, and if the list is empty or too short, step out one level and change the wording on the page to match what you actually got.

An age targeted page: older members across a country

When the page is about an age group rather than a place, drop the city and region entirely and let the age range do the work.

curl "https://api.hub-cdn.com/api/hs/quicksearch?guid=00000000-0000-0000-0000-000000000000&myBrandMembersOnly=TRUE&country=UK&membertypes=female,male&ageMin=50&ageMax=70&results=20&imageSize=80"

This returned a full 20 for us, every member inside the 50 to 70 band. Because the location filter is only a country, the pool is large and you reliably fill the block.

Choosing filters: the trade off

Every filter you add makes the result more relevant and the list shorter. The order to relax them when you come up short:

1. Widen the age range first. It usually costs you the least relevance.
2. Then drop city and keep region.
3. Then drop region and keep country.
4. Only then reconsider membertypes.

Never relax myBrandMembersOnly=TRUE. It is not a filter to trade away.

Reliability

The service occasionally returns a 502 Bad Gateway. It is uncommon and transient: the same request succeeds on a retry a second or two later. We have seen it during ordinary testing, so assume you will meet it in production.

Build in a retry. Treat a 502, and any other 5xx, as retryable: wait a second or two and try once or twice more before giving up. Do not retry a 400, which means the request itself is wrong, most often an unrecognised site GUID.

Whatever happens, fail quietly on the page. If the call does not succeed, render the page without the member block rather than showing an error or an empty frame to a visitor.

Practical guidance

• Take location values from the Location reference. An unrecognised country, region or city fails silently rather than erroring.
• Check your filters return members before you build around them. results is a maximum, not a quantity you are guaranteed: a narrow combination of city, age range and member type returns however many members match, which can be far fewer than you asked for, or none at all. Handle a short or empty array gracefully rather than rendering an empty grid.
• Do not treat the filters as a guarantee about any individual profile. The filters sample the member pool; they are not a verification step. If the profiles are going in front of the public, look at what came back before you publish it.
• Prefer calling the endpoint live and honour the 60 second cache header. If you publish results into pages instead, refresh them at least once a day, never less often. See Keeping profiles current, which is the part of this document most likely to cause you trouble if it is skipped.
• Ask for no more than 20 profiles. Request what you will display rather than a large block you then trim.
• Always send myBrandMembersOnly=TRUE. Show your own members, not somebody else's. A visitor who registers should find the people your pages promised them.
• Ask for the photo size you will display and give every image an alt attribute so the block is accessible.

Data Protection

This endpoint returns real people: names, ages, locations, profile text and photographs. That is personal data, and in most cases the profile and preference fields count as special category data under GDPR and similar laws.

• Show it, do not accumulate it. Display what you need and avoid building your own copy of the member base.
• If you do store responses, keep the retention period short, secure the store, and have a route to remove a profile on request.
• Serve it only over HTTPS, and do not put member data into logs, analytics events or third party tools.
• Remember that a profile you copied into a static page is no longer under platform control. If a member closes their account, your page keeps showing them until you refresh it.

This is guidance, not legal advice; partners are responsible for their own compliance.

Changelog