{"openapi":"3.0.1","info":{"title":"Candid News","description":"Access the only API on the market delivering real-time, actionable news on nonprofits, philanthropy, and the social sector that is curated by Candid from over 65,000 sources.","license":{"name":"Candid API License Agreement"},"version":"1.0"},"tags":[{"name":"Research & News"}],"servers":[{"url":"https://api.candid.org/news","description":"Production Server"}],"paths":{"/v1/search":{"get":{"tags":["News Search"],"security":[{"apiKeyHeader":[]}],"operationId":"news_v1_search","summary":"/news/v1/search","description":"Access the only API on the market delivering real-time, actionable news on nonprofits, philanthropy, and the social sector, curated by Candid from over 65,000 sources.","parameters":[{"name":"search_terms","in":"query","description":"Term(s) to search in Candid’s news sources.","required":false,"schema":{"type":"string","example":"Tree planting","maxLength":255}},{"name":"start_date","in":"query","description":"The oldest article publication date to search from in the format yyyy-MM-dd. Default is one month before today's date, and the earliest possible value is 2018-09-24. The start_date and end_date can be at most one year apart.","required":false,"schema":{"type":"string","format":"date","example":"2021-09-01","maxLength":10}},{"name":"end_date","in":"query","description":"The most recent article publication date to search to in the format yyyy-MM-dd. Default is today's date. The start_date and end_date can be at most one year apart.","required":false,"schema":{"type":"string","format":"date","example":"2021-10-01","maxLength":10}},{"name":"added_start_date","in":"query","description":"A filter, along with added_end_date, based on the date an article was added to the Candid News database, in the format yyyy-MM-ddTHH:mm:ss.fffffffZ. Default is one month before today's date. The added_start_date and added_end_date fields can be at most one year apart. The earliest added_start_date to search from is 2018-09-24","required":false,"schema":{"type":"string","format":"date-time","example":"2021-09-01T17:32:18.1169712Z"}},{"name":"added_end_date","in":"query","description":"A filter, along with added_start_date, based on the date an article was added to the Candid News database in the format yyyy-MM-ddTHH:mm:ss.fffffffZ. Default is today's date. The added_start_date and added_end_date fields can be at most one year apart.","required":false,"schema":{"type":"string","format":"date-time","example":"2021-10-02T17:32:18.1169712Z"}},{"name":"eins","in":"query","description":"A list of up to 25 organization EINs each of which formatted with or without a dash. Multiple values should be joined using OR.","required":false,"schema":{"type":"array","items":{"type":"string","default":null,"example":["13-1837418","58-1721923",742150288],"maxLength":32},"maxItems":25}},{"name":"organizations","in":"query","description":"A list of up to 25 organization names. Multiple values should be joined using OR.","required":false,"schema":{"type":"array","items":{"type":"string","default":null,"example":["Glaad","Friends of Hawaiian Islands National Wildlife Refuge","Running Rebels Community Organization Inc"],"maxLength":255},"maxItems":25}},{"name":"locations","in":"query","description":"A list of up to 25 geoName IDs for locations. Multiple values should be joined using OR. Contact Candid for a JSON file of all Candid-supported GeoName IDs.","required":false,"schema":{"type":"array","items":{"type":"integer","default":null,"example":[5791132,7007157,7007919],"minimum":0,"maximum":999999999999999},"maxItems":25}},{"name":"subjects","in":"query","description":"A list of up to 25 Candid Philanthropy Classification System (PCS) Subject Facet codes (eg. ST000000, SR040000, SA010200, etc). Top-level PCS codes will include searches for all related child codes. Multiple values should be joined using OR.","required":false,"schema":{"type":"array","items":{"type":"string","default":null,"example":["ST000000","SR040000","SA010200"],"maxLength":32},"maxItems":25}},{"name":"populations","in":"query","description":"A list of up to 25 Candid Philanthropy Classification System (PCS) Population Facet codes (eg. PC000000, PG010000, PE050000, etc). Top-level PCS codes will include searches for all related child codes. Multiple values should be joined using OR.","required":false,"schema":{"type":"array","items":{"type":"string","default":null,"example":["PC000000","PG010000","PE050000"],"maxLength":32},"maxItems":25}},{"name":"people","in":"query","description":"A list of up to 25 names of people by which to filter news articles. Multiple values should be joined using OR.","required":false,"schema":{"type":"array","items":{"type":"string","default":null,"example":["Bradford K. Smith","Mizmun Kusairi"],"maxLength":255},"maxItems":25}},{"name":"sources_include","in":"query","description":"A list of up to 25 names of news source to include. Accepts up to 25, multiple values should be joined using OR.","required":false,"schema":{"type":"array","items":{"type":"string","default":null,"example":["www.philanthropynewsdigest.org/","www.nytimes.com/"],"maxLength":255},"maxItems":25}},{"name":"sources_exclude","in":"query","description":"A list of up to 25 names of news sources to exclude. Accepts up to 25, multiple values should be joined using OR.","required":false,"schema":{"type":"array","items":{"type":"string","default":null,"example":["philanthropy.com/","www.niemanlab.org/"],"maxLength":255},"maxItems":25}},{"name":"staff_change_mentioned","in":"query","description":"Indicates whether to return articles containing mentions of staff changes. If true, only articles that mention staff changes will be returned. If false, only articles that do not mention staff changes will be returned. If null, articles will be returned regardless of staff changes mentioned.","required":false,"schema":{"type":"boolean","example":""}},{"name":"rfp_mentioned","in":"query","description":"Indicates whether to return articles containing mentions of rfp. If true, only articles containing mentions of RFPs will be returned. If false, only articles not containing mentions of RFPs will be returned. If null, articles will be returned regardless of RFPs mentioned.","required":false,"schema":{"type":"boolean","example":""}},{"name":"grant_mentioned","in":"query","description":"Indicates whether to return articles containing mentions of grants. If true, only articles containing mentions of grants will be returned. If false, only articles not containing mentions of grants will be returned. If null, articles will be returned regardless of grants mentioned.","required":false,"schema":{"type":"boolean","example":""}},{"name":"filter_operator","in":"query","description":"Determines the union type for searches for the following parameters Subjects, Populations, Locations, People, and Organizations. Default is AND. Note that inter-array parameter values are not affected by the filter operator.","required":false,"schema":{"type":"string","default":"","enum":["AND","OR"],"example":""}},{"name":"advisory_content","in":"query","description":"Advisory content is flagged for organizations or people in the social sector that may or may not require due diligence. True = Only return articles flagged as advisory content. False = Do not return articles flagged as advisory content. Null = Return articles regardless of advisory content.","required":false,"schema":{"type":"boolean","example":""}},{"name":"sort_order","in":"query","description":"The direction to sort the results by publication date, either \"asc\" (ascending) or \"desc\" (descending). Default is desc.","required":false,"schema":{"type":"string","enum":["desc","asc"],"example":""}},{"name":"page","in":"query","description":"Select the page number for search results. If page is not specified, it defaults to 1. The maximum page value is the total number of results divided by 25.","required":false,"schema":{"type":"integer","example":1,"minimum":1,"maximum":400}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"code":{"type":"integer","description":"HTTP response status code.","example":200},"status":{"type":"string","description":"Description of the HTTP response status code.","example":"OK"},"elapsed_time":{"type":"string","description":"Elapsed time of API call in miliseconds.","example":1},"time":{"type":"string","description":"Time of API call.","example":"2021-01-01T01:01:01.000Z"},"article_count":{"type":"integer","description":"Number of news articles returned by the search.","example":1621,"maximum":10000},"page_count":{"type":"integer","description":"Number of pages returned by the search.","example":67,"maximum":400},"parameters":{"type":"object","properties":{"search_terms":{"type":"string","description":"Filter passed through for search_terms parameter","example":"Tree planting","maxLength":255},"start_date":{"type":"string","description":"Filter passed through for start_date parameter","format":"date","default":null,"example":"2020-01-01","maxLength":10},"end_date":{"type":"string","description":"Filter passed through for end_date parameter","format":"date","default":null,"example":"2020-12-31","maxLength":10},"added_start_date":{"type":"string","description":"Filter passed through for added_start_date parameter","format":"date","default":null,"example":"2021-08-01T17:32:18.1169712Z"},"added_end_date":{"type":"string","description":"Filter passed through for added_end_date parameter","format":"date","default":null,"example":"2021-08-02T17:32:18.1169712Z"},"eins":{"type":"array","description":"Filter passed through for eins parameter","items":{"type":"string","default":null,"example":["13-1837418","58-1721923",742150288],"maxLength":32},"maxItems":25},"organizations":{"type":"array","description":"Filter passed through for organizations parameter","items":{"type":"string","default":null,"example":["Glaad","Friends of Hawaiian Islands National Wildlife Refuge","Running Rebels Community Organization Inc"],"maxLength":255},"maxItems":25},"locations":{"type":"array","description":"Filter passed through for locations parameter","items":{"type":"integer","default":null,"example":[5791132,7007157,7007919],"minimum":0,"maximum":999999999999999},"maxItems":25},"subjects":{"type":"array","description":"Filter passed through for subjects parameter","items":{"type":"string","default":null,"example":["SE000000","SR030000","SR020200"],"maxLength":32},"maxItems":25},"populations":{"type":"array","description":"Filter passed through for populations parameter","items":{"type":"string","default":null,"example":["PA000000","PC000000","PC010200"],"maxLength":32},"maxItems":25},"filter_operator":{"type":"string","description":"Filter passed through for filter_operator parameter","default":"AND","enum":["AND","OR"],"example":"AND"},"people":{"type":"array","description":"Filter passed through for people parameter","items":{"type":"string","default":null,"example":["Bradford K. Smith","Mizmun Kusairi"],"maxLength":255},"maxItems":25},"sources_include":{"type":"array","description":"Filter passed through for sources_include parameter","items":{"type":"string","default":null,"example":["www.prweb.com/","www.philanthropynewsdigest.org/"],"maxLength":255},"maxItems":25},"sources_exclude":{"type":"array","description":"Filter passed through for sources_exclude parameter","items":{"type":"string","default":null,"example":["news.yahoo.com/","philanthropy.com/"],"maxLength":255},"maxItems":25},"staff_change_mentioned":{"type":"boolean","description":"Filter passed through for staff_change_mentioned parameter","default":null,"example":true},"rfp_mentioned":{"type":"boolean","description":"Filter passed through for rfp_mentioned parameter","default":null,"example":true},"grant_mentioned":{"type":"boolean","description":"Filter passed through for grant_mentioned parameter","default":null,"example":true},"advisory_content":{"type":"boolean","description":"Filter passed through for advisory_content parameter","default":null,"example":true},"sort_order":{"type":"string","description":"Filter passed through for sort_order parameter","enum":["desc","asc"],"default":"desc","example":"desc"},"page":{"type":"integer","description":"Filter passed through for page parameter","default":1,"example":1,"minimum":1,"maximum":400}}}}},"data":{"type":"array","items":{"type":"object","properties":{"data_id":{"type":"integer","description":"Candid data ID of the news article.","example":5419718},"title":{"type":"string","description":"Title of the news article.","example":"Candid Announces Three New Appointments to Board of Trustees"},"content":{"type":"string","description":"Short preview content of the news article.","example":"Candid announced the appointment this month of..."},"publication_date":{"type":"string","description":"Date article was published.","example":"2020-03-31T00:14:11.647Z"},"added_date":{"type":"string","description":"Date article was added to the Candid News database.","example":"2021-08-01T17:32:18.1169712"},"author":{"type":"string","description":"Author of the news article when available.","example":"Candid"},"link":{"type":"string","description":"Link to the news article.","example":"https://www.prweb.com/releases/candid_announces_three_new_appointments_to_board_of_trustees/prweb17831736.htm"},"image":{"type":"string","description":"Article image.","example":"https://ww1.prweb.com/prfiles/2021/03/29/17831736/gI_145751_NewsImage_vcsPRAsset_3781265_145751_e773fde5-b617-4001-8b99-ae767b935333_0.png"},"sources":{"type":"array","items":{"type":"string","description":"List of news article sources.","example":["www.prweb.com/"]}},"site_name":{"type":"string","description":"Site name where the news article published.","example":"PRWeb"},"base_url":{"type":"string","description":"Base URL of the news article source website.","example":"https://www.prweb.com"},"icon_url":{"type":"string","description":"URL of the news article source website icon.","example":"https://www.prnewswire.com/content/dam/prnewswire/icons/2019-Q4-PRN-Icon-32-32.png"},"philanthropy_classification_system":{"type":"array","items":{"type":"object","properties":{"subjects":{"type":"array","items":{"type":"object","properties":{"taxonomy_code":{"type":"string","description":"Philanthropy Classification Code (PCS) subject facet codes related to the article.","example":"SP030000"},"taxonomy_code_description":{"type":"string","description":"Philanthropy Classification Code (PCS) subject facet descriptions related to the article.","example":"Universal Design"}}}},"populations":{"type":"array","items":{"type":"object","properties":{"taxonomy_code":{"type":"string","description":"Philanthropy Classification Code (PCS) population facet codes related to the article.","example":"PE000000"},"taxonomy_code_description":{"type":"string","description":"Philanthropy Classification Code (PCS) population facet descriptions related to the article.","example":"Ethnic and Racial Groups"}}}}}}},"people_mentioned":{"type":"array","items":{"type":"string","description":"List of people mentioned in the article.","example":["Donna Murray-Brown","Ken","Kenneth Jones","Kami","Brad Smith","Gretchen Whitmer","T. Sylvester John"]}},"most_relevant_organizations":{"type":"array","description":"The most relevant organizations to the article, sorted by most salient to least salient.","items":{"properties":{"name":{"type":"string","description":"Name of the organization.","example":"Michigan Nonprofit Association"},"org_type":{"type":"string","description":"Organization type, either recipient or funder.","example":"recipient"},"profile_link":{"type":"string","description":"URL of organization's profile on Guidestar.org or Foundationcenter.org","example":"https://www.guidestar.org/profile/38-2959692"},"profile_link_type":{"type":"string","description":"The profile type of the profile link.","example":"guidestar","enum":["foundation_directory","guidestar"]},"ein":{"type":"string","description":"EIN of the organization.","example":"38-2959692"},"org_salience_score":{"type":"number","description":"The likelihood that the given organization is the most important organization in the context of the article. Values closer to 1 indicate that the organization is very important.","example":0.9595482}}}},"organizations_mentioned":{"type":"array","items":{"type":"string","description":"List of organizations mentioned in the article.","example":["AfricaWorks","The Annie E. Casey Foundation","Cobell Board of Trustees","Candid","Center for Disaster Philanthropy","Center for Urban Families, Inc.","Detroit Public Television","Devex","Ford Motor Company Fund","China Foundation Center","Guidestar","Macarthur Foundation","Michigan Nonprofit Association","Mission Investors Exchange, Inc.","National Council on Aging","National Council of Nonprofits","National Prevention Science Coalition to Improve Lives, Inc.","Northern Michigan University","Oxfam","Public Justice Center","Southern Education Foundation, Inc.","Steve Fund","Thurgood Marshall Academy","The World Bank","Worldreader"]}},"eins":{"type":"array","items":{"type":"string","description":"EINs of organizations mentioned in the article.","example":["13-1837418","56-2618866"]}},"locations_mentioned":{"type":"array","items":{"properties":{"geoid":{"type":"string","description":"GeoID of a location mentioned in the article.","example":4990729},"location_name":{"type":"string","description":"Location name mentioned in the article.","example":"Detroit, MI"}}}},"staff_change_mentioned":{"type":"boolean","description":"True if the article contains a mentions of staff changes.","example":false},"rfp_mentioned":{"type":"boolean","description":"True if the article contains a mentions of RFPs.","example":false},"grant_mentioned":{"type":"boolean","description":"True if the article contains a mentions of  grants.","example":true},"advisory_content":{"type":"boolean","description":"True if the article has been flagged for advisory content.","example":true},"scores":{"type":"object","properties":{"article_score":{"type":"number","description":"The total score for the article which drives article ranking. This can be any number greater than or equal to 0.","example":0.8396587},"grant_mentioned_confidence":{"type":"number","description":"The likelihood that at least one grant transaction is mentioned in the article.","example":0.6595482},"rfp_mentioned_confidence":{"type":"number","description":"The likelihood that at least one RFP announcement is mentioned in the article.","example":0.4394065},"advisory_content_confidence":{"type":"number","description":"The likelihood that the article includes advisory content about organizations or people in the social sector that may or may not require due diligence.","example":0.9355742},"staff_change_mentioned_confidence":{"type":"number","description":"The likelihood that at least one staff change is mentioned in the article. Staff changes include, but are not limited to, retirements, new hires, promotions, board member appointments, and terminations.","example":0.5034921}}}}}}}}}}},"400":{"$ref":"#/components/responses/400APIError"},"401":{"$ref":"#/components/responses/401APIError"},"403":{"$ref":"#/components/responses/403APIError"},"404":{"$ref":"#/components/responses/404APIError"},"406":{"$ref":"#/components/responses/406APIError"},"429":{"$ref":"#/components/responses/429APIError"},"500":{"$ref":"#/components/responses/500APIError"}}}}},"components":{"securitySchemes":{"apiKeyHeader":{"type":"apiKey","name":"Subscription-Key","in":"header"}},"responses":{"400APIError":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications."},"code":{"type":"string","description":"HTTP response status code.","example":400},"errors":{"type":"string","example":"X is not a valid parameter."}}}}}},"401APIError":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"HTTP response status code.","example":401},"message":{"type":"string","description":"Diagnostic message for response status","example":"Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."}}}}}},"403APIError":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"HTTP response status code.","example":403},"message":{"type":"string","description":"Diagnostic message for response status","example":"Forbidden, we found insufficient permissions to grant access to the resources. Please check the detailed message of the response."}}}}}},"404APIError":{"description":"No Results Found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"HTTP response status code.","example":404},"message":{"type":"string","description":"Diagnostic message for response status","example":"Oops! We didn't find anything on that query, try again with a different query!"}}}}}},"406APIError":{"description":"Not Acceptable","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"HTTP response status code.","example":406},"message":{"type":"string","description":"Diagnostic message for response status","example":"The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request."}}}}}},"415APIError":{"description":"Unsupported Media Type","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"HTTP response status code.","example":415},"message":{"type":"string","description":"Diagnostic message for response status","example":"The request entity has a media type which the server or resource does not support."}}}}}},"429APIError":{"description":"Too Many Requests","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"HTTP response status code.","example":429},"message":{"type":"string","description":"Diagnostic message for response status","example":"Rate limit is exceeded. Try again later."}}}}}},"500APIError":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"HTTP response status code.","example":500},"message":{"type":"string","description":"Diagnostic message for response status","example":"We had a problem with our server. Try again later."}}}}}}}},"x-readme":{"explorer-enabled":true,"proxy-enabled":true}}