Priority Helpline Filtering

4 min

Topics Currently Available

Suicidal thoughts

The helplines endpoint supports two distinct retrieval modes: Standard (comprehensive) and Priority (curated). These modes control the selection and ranking logic of the results, but always return the same data structure, ensuring simple integration.

The choice of mode is controlled by the optional boolean query parameter priority_only.

Mode	Parameter Flag	Selection Logic	Best For
Standard	(default - no flag needed)	Returns all verified helplines matching the country and topic, ranked by our algorithm.	Broad discovery, filtering, and navigable user interfaces.
Priority	priority_only=true	Returns a curated short list of the country's most critical helplines for the topic.	"Show one number" UIs and quick, universal referral.

Technical Integration

To access the curated Priority Mode list, simply add thepriority_only=true flag to your request:

https://api.throughlinecare.com/v1/helplines
  ?country_code=US
  &topic=Suicidal%20thoughts
  &priority_only=true

Existing integrations will continue to default to Standard Mode (unfiltered) and require no code changes to function.

If you are using the Entry API tierEntry API tier, the priority_only flag will be set automatically even if you don’t include it in your request.

Criteria for Priority Helplines

The services returned when priority_only=true represent the country's foremost resource(s) for the topic. These services are specifically selected to be the default, universally recommended option for all individuals seeking support with that topic:

Universal Reach & Paired Services: The service(s) must be capable of supporting all individuals who make contact, regardless of age or demographic.

Crucial Rule: If the query returns a list containing two services (e.g., one for adults, one for youth, or services for two official languages), API consumers must display both services or refrain from displaying any. Displaying only one of a pair would risk recommending a specialized service to an unsuitable demographic.

Filtering Exception: If you can reliably detect demographic data (such as age or preferred language) prior to calling the API, you may use that data in combination with specialty filters (e.g., specialty=children) to potentially return only the single most appropriate service from the curated list.

Primary Mission: The service's main purpose must be to support individuals with the topic, and it must be recognized within the country as the foremost resource for this issue.

Nationwide Scope: Available and accessible throughout the entire country.

Extensive Hours: Operates with extensive hours to ensure broad availability and high service reliability.