# Search for a cause
Now that you have obtained your JWT, you are able to access the rest of our API endpoints! For you to create a donation, you will first need to specify which cause the funds are going to be donated to. In order to do this, we'll be leveraging the /search/causes endpoint to find a cause that fits your criteria.
If you already know which cause you are donating to and have the causeId for it, you can skip this page and head to the next section to make a donation.
# Building your request
Search for a cause by passing your query as the value of the q parameter after the resource /search/causes. The query will be compared against the cause's name, description and tags (interests, skills, etc.). There are also additional filters that you can add to your search, such as geolocation or categories, which will be covered later.
Lastly, you will have to ensure that you authenticate the request with the JWT you've previously obtained, by passing the JWT as an Authorization header.
# Sample request:
To search for dogs, your q parameter would be 'dogs'.
# Sample response:
{
"data": [
{
"type": "causes",
"id": "840-275219467/49AVC4NGNK",
"attributes": {
"parent_id": "840-275219467",
"parent_name": "K9S FOR WARRIORS",
"name": "Petco Foundation K9 Center - San Antonio, Texas",
"description": "This 6,000 sq. ft. facility will hold 30 kennels and sit on 3 acres of land adjacent to the City of San Antonio Animal Care Services and serve as K9s For Warriors’ hub in the south...",
"city": "San Antonio",
"state": {
"name": "Texas",
"code": "US-TX"
},
"country": {
"name": "United States",
"code": "US"
},
"donation": {
"donors": 787
},
"logo": "https://logos.benevity.org/150x150/public/plogos/840-275219467|3478095f3d1ec7b1e11.jpg",
"categories": [
{
"category_name": "Animal-Related",
"category_code": "D",
"subcategory_name": "Animal-Related N.E.C.",
"subcategory_code": "D99"
}
],
"visibility": "match",
"status": {
"match": "eligible"
"program": "eligible",
"routing": "eligible",
"payment": "eligible"
},
"snippets": {
"tag": "service <em>dog</em>",
"body": "... in the southwestern United States. The Petco Foundation K9 Center’s focus will be on saving larger, hard-to-rescue <em>dogs</em> by pulling them from the City of San Antonio Animal Care Services shelter"
}
}
},
...
],
"meta": {
"search_information": {
"total_results": 8718,
"showing_results_for": "dogs",
"spell_check_suggestion": null
},
"search_parameters": {
"q": "dog",
"visibility": "donate",
"page": "1",
"page_size": "25"
},
"facets": [
{
"name": "country_facet",
"buckets": [
{
"val": "AR",
"label": "Argentina",
"count": 2
},
{
"val": "AU",
"label": "Australia",
"count": 65
},
...
]
},
{
"name": "state_facet",
"buckets": [
{
"val": "AR-B",
"label": "Buenos Aires",
"count": 2
},
{
"val": "AU-NSW",
"label": "New South Wales",
"count": 25
},
...
]
},
{
"name": "categories_facet",
"buckets": [
{
"val": "A",
"label": "Arts, Culture, and Humanities",
"count": 85
},
{
"val": "B",
"label": "Education",
"count": 180
},
...
]
},
{
"name": "subcategories_facet",
"buckets": [
{
"val": "A01",
"label": "Alliance/Advocacy Organizations",
"count": 2
},
{
"val": "A11",
"label": "Single Organization Support",
"count": 1
},
...
]
}
],
}
"links": {
"self": "/search/causes?q=dog&visibility=donate&page_size=25&page=1",
"first": "/search/causes?q=dog&visibility=donate&page_size=25&page=1",
"next": "/search/causes?q=dog&visibility=donate&page_size=25&page=2",
"last": "/search/causes?q=dog&visibility=donate&page_size=25&page=12"
}
}
# Response Details:
Once you find the cause you're looking for, you should make a note of the id, as you will need to have this piece of information in order to make a donation to the cause.
Many of the response attributes are self-descriptive, but some of them require a bit more clarity, like categories, snippets and visibility.
# Categories
Benevity follows a classification system called the National Taxonomy of Exempt Entities (NTEE) (opens new window), which describes the type of work that a cause may perform. It is important to note that although this classification system is based in the United States, Benevity assigns an NTEE code to every cause, even if they are not based in the US.
# Snippets
Snippets are fragments of text that reveal the contextual relevance between the search terms and the search results. Matching search terms are surrounded by emphasis tags <em></em>. Snippets can be any of the following:
title- Text matches in the cause's namecause- Text matches in the parent cause's name(s) or identifiersbody- Text matches in the cause's description or captiontag- Text matches in the cause's tagscontact- Text matches to content the cause has supplied for their Social Media or Websitelocation- Text matches to the cause or parent cause's City, Province/State, or Country
# Visibility
Visibility indicates if a cause meets your company's program guidelines. Benevity provides the ability to curate the wider cause database, allowing you to remove specific organizations or categories of causes from being eligible. These filters will be configured during your implementation onboarding by Benevity technical resources.
match- Your company may provide a match for this causedonate- Your company can donate to this causeprogram- This cause is a part of your company's program, but cannot be donated to- the
statusof the cause would show why you wouldn't be able to donate to it
- the
nominate- This cause isn't a part of your company's program, but can be nominated into itineligible- This cause is excluded from your company's programinactive- this cause is inactive in our system
# Status
Status a breakdown of how we determine a cause's visibility status, and whether or not they're eligible for your program. A cause must be eligible for all three criteria in order for your company to donate to them. Here's a breakdown of the status details:
match- Your own company's set of rules that determine what causes can be donation matchedprogram- Your own company's set of rules that determine what causes can be searched, or donated torouting- Your own company's program configuration determines what causes payments can be routed topayment- Causes outside of Canada/US are required to have an EFT payment type
# Searching with visibility
You can pass the query parameter visibility to the API to filter your results based on the desired eligibility level. Each visibility level builds off of the previous level, with each level providing further granularity for your queries. For example, setting the visibility to nominate will include search results with the nominate visibility, as well as the program and donate visibilities. The full details are below:
match- Returns results that your company may donation matchdonate- Default setting, returns results that your company can donate toprogram- Guaranteed to return results that are a part of your company's programnominate- Guaranteed to return results that can be nominated into your company's programineligible- Guaranteed to return results that are at least activeinactive- Returns all results, with no filter
# Sample request:
For example, suppose you are interested in causes that provide services for Dogs. You also want to make sure that your results are eligible in your company's program. Note that this will include results that have both the donate and program visibility.
# Searching with facets
You can narrow down your searches by utilizing the facets that are available. The facets provided can be used multiple times, and in conjunction with each other - the results will be combined together (an OR clause). All of the possible facets for a query will be returned in the response body, so you can utilize these values to provide even more granularity. Here are the possible facets types you can filter with:
category- Filtered based on the NTEE categories and subcategories the cause is associated withcountry- Filtered based on the ISO 3166 standard numeric codesstate- Filtered based on the ISO 3166-2 standard numeric codes
# Sample request:
Now let us add in this additional facet. We start with a search for Dogs, we want to make sure that the results are at least in your company's program, and we want to find causes related to education in Canada.
# Search by location
Another layer of search filtering provided is the ability to boost search results by location. Generally, results physically closer to the point provided will be ranked higher in the results. The search_location parameter is expressed in terms of latitude,longitude and should be a set of valid geographic coordinates.
# Sample request:
Putting all these together: suppose you wish to search for Dogs, with results in your company's program and related to education, and find results that are close to Calgary, AB. We will be using the latitude and longitude for Benevity's head office: 51.051651, -114.050880.
# Search with autocorrect
By passing an additional parameter of autocorrect with a value of true, the API will do it's best conversion of misspelled words to the correct spelling and return valid results, unless an exact match is present for the initial query term.
If the search query example was /search/causes?autocorrect=true&q=rekreasion (actual spelling would be recreation), the meta response data will have the following
search_informationshowing_results_for: The correct spelling from the search term providedspell_check_suggestion: The suggested corrected spelling from the search query provided
search_parametersautocorrect: if autocorrect was enabledq: the original query/search term used
# Sample response:
An example response from using /search/causes?autocorrect=true&q=rekreasion would be:
{
"data": [
{
"type": "causes",
"id": "840-844283689",
"attributes": {
"name": "HOOP BUS INC",
"city": "LOS ANGELES",
"state": {
"name": "California",
"code": "US-CA"
}...
}...
}
],
"meta": {
"search_information": {
"total_results": 100630,
"showing_results_for": "recreation",
"spell_check_suggestion": "recreation"
},
"search_parameters": {
"autocorrect": "true",
"include_children": "true",
"q": "rekreasion",
"visibility": "donate",
"page": "1",
"sort": "default",
"page_size": "25"
}...
}
}
# 🚀 ☀️ ⭐️ Congratulations! ⭐️ ☀️ 🚀
You have now found a cause worthy of your support, and you can begin engaging your users by enabling them to make a donation.