Organizational Search

Overview

This endpoint will allow you to search for Organizations known to the BBB. Organizations may include businesses or charities.

Endpoint

This endpoint will allow consumers to search for Organizations known to the BBB. Organizations may include businesses or charities. It supports pagination of results using the "TotalResults" in the output, which displays the total number of matches by the search critieria. PageNumber and PageSize query parameters allow you to page through total results and get smaller sets at a time.

Endpoint	HTTP Method	Authorization	Format of return output
https://api.bbb.org/api/orgs/search	GET	Required	JSON or XML, determined by header specification; JSON is default

Header Values

Accept (optional) - specify json (default) or xml as follows:
- accept: application/json
- accept: application/xml
Authorization
- Requires valid Bearer token

Query Parameters

Query parameter	Data Type	Description
PageSize	integer	Number of results that will be included.
PageNumber	integer	Page number to return. Starts at 1. Defaults to 1
BusinessId	string	Internal id of an organization. This is only unique across BBBs/Bureaus. The BusinessId plus the BBBID will make a unique record.
BBBId	string	Internal identifier of a regional BBB
BBBRating	string	Letter grade rating of organization Valid values: A, A+, A-, B, B+, B-, C, C+, C-, D, D+, D-, F, NA, NR
IsBBBAccredited	boolean	Is organization accredited?

IsReportable	boolean	Is organization reported on the public web site?
OrganizationName	string	One of the names that the organization is known by.
PrimaryOrganizationName	string	The primary name that the organization is known by.
PrimaryCategory	string	The primary category that the organization falls under.
ContactFirstName	string	First name of a known organization contact
ContactLastName	string	Last name of a known organization contact
ContactMiddleName	string	Middle name of a known organization contact
ContactTitle	string	Title of a known organization contact
ContactPrefix	string	Prefix of a known organization contact
Address	string	Street address of one of the organization's locations
City	string	City of one of the organization's locations
StateProvince	string	State/Province of one of the organization's locations
PostalCode	string	Postal code of one of the organization's locations
Phone	string	Phone number of the organization
BusinessURL	string	URL of the organization
ReportURL	string	URL to the organization's BBB Business Review
OrganizationType	string	Type of organization ("Business" or "Charity")
CollectionId	integer	Unique identifier of existing collection. Used to filter results to a set of pre-defined organizations.
OrganizationLastChanged	date/time	Date/time value that indicates when any field on an organization was last changed. Including this value will return all organizations that changed on or after the specified date/time.
RatingLastChanged	date/time	Date/time value that indicates when the rating grade for an organization was last changed. Including this value will return all organizations that changed their rating on or after the specified date/time.
AccreditationStatusLastChanged	date/time	Date/time value that indicates when the accreditation status for an organization was last changed. Including this value will return all organizations that changed their accreditation status on or after the specified date/time.

Example Queries/Responses

Data is returned in two sections:

TotalResults = Total number of results matching search criteria. This may not be the same as the actual results returned, since pagination is used to navigate large sets of results.
PageNumber = Current page number being shown. Starts at 1. Defaults to 1.
SearchResults = The list of Organizations matching the search criteria.

Organization result is defined here:

Organization fields to return	Data Type	Description
BusinessId	string	Internal id of an organization. This is only unique across BBBs/Bureaus. The BusinessId plus the BBBID will make a unique record.
OrganizationType	string	Type of organization.
BBBId	string	Internal identifier of a regional BBB
BBBRating (Populated for Partners only)	string	Letter grade rating of organization Valid values: A, A+, A-, B, B+, B-, C, C+, C-, D, D+, D-, F,NA, NR
IsBBBAccredited (Populated for Partners only)	boolean	Is organization accredited?
+ RatingIcons	array of RatingIcon Structure (string Url, string DeviceType)	Letter grade rating and accreditation status icon of organization for "web", "mobile" and "tablet" formats. Ex. "RatingIcons": [ { "Url": "http://bbb.org/ratingicons/lg-A.png", "DeviceType": "web" }, { "Url": "http://bbb.org/ratingicons/sm-A.png", "DeviceType": "mobile" }, { "Url": "http://bbb.org/ratingicons/md-A.png", "DeviceType": "tablet" } ] }
StarRatingScore	numeric	Number between >= 0.00 and <= 5.00
IsReportable	boolean	Is organization reported on the public web site?
PrimaryOrganizationName	string	Name designated as primary
AltOrganizationNames	list of strings	List of alternate organization names.
PrimaryCategory	string	Category designated as primary
ContactFirstName	string	First name of primary contact
ContactLastName	string	Last name of primary contact
ContactMiddleName	string	Middle name of primary contact
ContactTitle	string	Title of primary contact
ContactPrefix	string	Prefix of primary contact
ContactEmailAddress	string	Email address of contact
DateBusinessStarted	date/time	Date business started
Address	string	Street address
City	string	City
StateProvince	string	State or province
PostalCode	string	Postal/Zip code
Phones	list of strings	All phone numbers associated with an organization
BusinessURLs	list of strings	All URLs associated with an organization
ReportURL	string	URL to the organization's BBB Business Review. Suppressed if the Organization's "IsReportable" flag is false.
OrganizationLastChanged	date/time	Date/time value indicating when any field on an organization was last changed.
RatingLastChanged	date/time	Date/time value indicating when the rating grade for an organization was last changed.
AccreditationStatusLastChanged	date/time	Date/time value indicating when accreditation status for an organization was last changed.

Usage and Examples

HTTP Request	Result
/api/orgs/search?PageSize=50&OrganizationName=Taco+Bell	Returns all organizations with "Taco" and "Bell" in any of the known organization names
/api/orgs/search?PageSize=50&OrganizationName=Chipotle&City=Richmond&State=VA	Returns all organizations named "Chipotle" in Richmond, VA.
/api/orgs/search?PageSize=50&PrimaryCategory=Restaurants&City=Richmond&State=VA&BBBRating=A-	Returns all organizations in the category, "Restaurants", in Richmond, VA with a rating of A-
/api/orgs/search?PrimaryCategory=Restaurants&City=Richmond&State=VA&PageSize=10&PageNumber=2	Returns second set of 10 results that match the criteria - Restaurants in Richmond, VA. (i.e. results 11-20)
/api/orgs/search?PageSize=50&CollectionId=45	Returns first set of 50 results of organizations that are in CollectionId=45

Sections: