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.

EndpointHTTP MethodAuthorizationFormat 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 parameterData TypeDescription

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 returnData TypeDescription

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 RequestResult

/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

Additional Notes