Collections - Partners Only

Creation

Overview

BBB Partners will need to be able to identify collections of Organizations they care about and be able to manage those collections and receive Organization info and updates on them as needed.

Endpoints

Steps to create and add to a collection

To create a collection of organizations, you must know the unique id of the organization. Work with Council to collect a list of organization ids that match your list of businesses/organizations.

Here are sample API calls to create a collection and map to organization ids:

StepURLHTTP MethodJSON ExampleExpected Result

Create a new collection with a name and description

https://api.bbb.org/api/collections

POST

{
	"Name": "My First Collection",
	"Description": "This is my first collection"
}

200 OK

Collection created successfully.

Response should include Collection Id - use this Collection Id for subsequent calls to manage the collection

Assign organization id's to the newly created collection

https://api.bbb.org/api/collections/(Collection Id)/mappings

POST

{
	"OrganizationIds":[
		123,
		456,
		9988
		]
}

200 OK

Organization Id's added to collection successfully (assuming organization id's are valid).

View contents of collection

https://api.bbb.org/api/collections/(Collection Id)

GET

None

Returns current state of collection including mappings to organization id's.

Remove organization id from the collection

https://api.bbb.org/api/collections/(Collection Id)/mappings/delete

POST

{
	"OrganizationIds":[
		123
		]
}

200 OK

Removes organization id from collection

Next Steps

Once you've created a collection of organizations, there are three ways to view/monitor organization changes:

  1. View the current state of the organizations using a real-time search.
  2. View the current state of the organizations by scheduling file creation and delivery to specified API endpoint.
  3. Receive real-time, push updates when a rating or accreditation status changes for an organization.

This endpoint will allow consumers to create Collections, which are groupings of either Organizations (by OrganizationId), Categories (NAICS) or a combination of both types.

Request Structure

Organization Type Structure
  • OrgId
  • OrgName
Category Type Structure
  • CategoryId
  • CategoryTypeId
Fields and Descriptions

Inbound Message for POST

The inbound message will either be JSON or XML and will represent the collection with all relevant fields.

Collection fields

FieldRequired?DescriptionType (JSON)Max LengthValid Values

Name

Yes

Name of collection

String

256

 

Description

No

Description of collection

String

1024

 

Collection Mapping Fields

FieldRequired?DescriptionType (JSON)Max LengthValid Values

CollectionId

Yes

Type of entity that will be affected by this message.

Number

   

OrganizationIds

No

List of Organization Ids.

Array of numbers

   

Categories

No

List of categories that represent NAICS

codes

Array of Category types

   

OrganizationsByCategory

No

List of categories that represent NAICS codes

Array of Category types

   

Outbound Message for GET

FieldDescription

CollectionId

Type of entity that will be affected by this message.

Name

Name of collection

Description

Description of collection

Organizations

Array of Organization types

Categories

Array of Category types

Outbound Message for Error Messages ("ErrorMessages" array)

FieldDescription 

Message

Description of error

 

Organizations

Array of Organization types

List of organizations that were not mapped to the collection for reason stated in "Message"

Categories

Array of Category types

List of categories that were not mapped to the collection for reason stated in "Message"

Examples

Create by Category(s)

{
	"OrganizationIds": [
		123,
		456,
		9988
		],
	"Categories": [
		{
			"CategoryId": "3133",
			"CategoryTypeId": 5502
		},
		{
			"CategoryId": "721",
			"CategoryTypeId": 5502
		},
		{
			"CategoryId": "00101-000",
			"CategoryTypeId": 5501
		}
	]
}

Create by List of ID's

{
	"OrganizationIds": [
		123,
		456,
		9988
	],
	"Categories": [
		{
			"CategoryId": "3133",
			"CategoryTypeId": 5502
		},
		{
			"CategoryId": "721",
			"CategoryTypeId": 5502
		},
		{
			"CategoryId": "00101-000",
			"CategoryTypeId": 5501
		}
	]
}

Responses

Errors/Status

Outbound Message for Error Messages ("ErrorMessages" array)

FieldDescription 

Message

Description of error

 

Organizations

Array of Organization types

List of organizations that were not mapped to the collection for reason stated in "Message"

Categories

Array of Category types

List of categories that were not mapped to the collection for reason stated in "Message"

Additional Notes

Management

Endpoints

These endpoints will allow partners to manage their Collections, which are groupings of either Organizations (by OrganizationId), Categories (NAICS) or a combination of both types.

EndpointHTTP MethodAuthorizationFormat of inputDescription of OperationPossible return status codes

https://api.bbb.org/api/collections

POST

Required

JSON or

XML

Creates a new collection

201 Created - if successful

400 Bad Request - Invalid input type;

could not be processed

https://api.bbb.org/api/collections/{CollectionId}

GET

Required

No JSON/XML input

View an existing collection

200 Successful - if successful

https://api.bbb.org/api/collections/{CollectionId}

DELETE

Required

No JSON/XML input

Deletes entire collection and associated mappings

200 Successful - if successfully deleted

https://api.bbb.org/api/collections/{CollectionId}/

mappings

POST

Required

JSON or

XML

Creates collection mappings

201 Created - if successful

400 Bad Request - Invalid input type;

could not be processed

https://api.bbb.org/api/collections/{CollectionId}/

mappings

DELETE

Required

JSON or

XML

Deletes mappings specified in the input

200 Successful - if successfully deleted

Header Values

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

Inbound Message for POST

The inbound message will either be JSON or XML and will represent the collection with all relevant fields.

Request Structure

Organization Type Structure

OrgId

OrgName

Category Type Structure

CategoryId

CategoryTypeId

Fields and Descriptions

Collection Fields

FieldRequired?DescriptionType (JSON)Max LengthValid Values

Name

Yes

Name of collection

String

256

 

Description

No

Description of collection

String

1024

 

Collection Mapping Fields

FieldRequired?DescriptionType (JSON)Max LengthValid Values

CollectionId

Yes

Type of entity that will be affected by this message.

Number

   

OrganizationIds

No

List of Organization Ids.

Array of numbers

   

Categories

No

List of categories that represent either YPPA/TOB or NAICS

codes

Array of Category types

   

OrganizationsByCategory

No

List of categories that represent either YPPA/TOB or NAICS

codes

Array of Category types    
Outbound Message for GET
FieldDescription

CollectionId

Type of entity that will be affected by this message.

Name

Name of collection

Description

Description of collection

Organizations

Array of Organization types

Categories

Array of Category types

Examples

Create a new Collection

Create a new collection (/api/collections) - POST HTTP method

JSON Example
{
	"Name": "My First Collection",
	"Description": "This is my first collection"
}
Add New Collection Mappings

Add new Collection mappings to an existing Collection (https://api.bbb.org/api/collection/{CollectionId}/mappings) - add one Organization Id and one Category subscription to an existing collection. This would append to the existing list of organizations and categories.

JSON Example
{
	"OrganizationIds": [
		456,
		9988
		],
	"Categories": [
		{
			"CategoryId": "3133",
			"CategoryTypeId": 5502
		},
		{
			"CategoryId": "721",
			"CategoryTypeId": 5502
		},
		{
			"CategoryId": "00101-000",
			"CategoryTypeId": 5501
		}
	]
}
Add new Collection mappings to an existing Collection

(https://api.bbb.org/api/collection/{CollectionId}/mappings) - add one "Organizations By Category" mapping that will take a snapshot of all Organizations in the Category and add them to the collection. This would append to the existing list of organizations

JSON Example
{
	"OrganizationIds": [
		123,
		456,
		9988
	],
	"OrganizationsByCategory": [
		{
			"CategoryId": "00128-200",
			"CategoryTypeId": 5501
		}
	]
}
View an Existing Collection

View an existing Collection (https://api.bbb.org/api/collections/1) - GET HTTP method query for an existing collection by specifying the collectionId. JSON returned is below:

JSON Example
{
	"CollectionId": 1,
	"Name": "My First Collection",
	"Description": "This is my first collection",
	"Organizations": [
		{
			"OrgId": 555,
			"OrgName": "Lisa's House of Pencils"
		},
		{
			"OrgId": 433,
			"OrgName": "Bill's House of Batteries"
		},
		{
			"OrgId": 321,
			"OrgName": "Fred's House of Tea Cups"
		}
	],
	"Categories": [
		{
			"CategoryId": "3133",
			"CategoryTypeId": 5502
		},
		{
			"CategoryId": "721",
			"CategoryTypeId": 5502
		},
		{
			"CategoryId": "00101-000",
			"CategoryTypeId": 5501
		}
	]
}
Add/Remove an Organization(s)
{
	"OrganizationIds": [
		123,
		456,
		9988
	],
	"Categories": [
		{
			"CategoryId": "3133
			"CategoryTypeId": 5502
		},
		{
			"CategoryId": "721",
			"CategoryTypeId": 5502
		},
		{
			"CategoryId": "00101-000",
			"CategoryTypeId": 5501
		}
	]

}
Delete a Collection

Delete an entire Collection (https://api.bbb.org/api/collections/1) - DELETE HTTP method

No JSON required

Delete Collection Mappings

Delete collection mappings from an existing collection

(https://api.bbb.org/api/collection/{CollectionId}/mappings) - specify two OrganizationIds and one Category subscription. This operation would remove the specified OrganizationIds and Category subscriptions from the collection.

JSON Example
{
	"OrganizationIds": [
		123,
		456
	],
	"Categories": [
		{
			"CategoryId": "3133",
			"CategoryTypeId": 5502
		}
	]
}
Delete collection mappings from an existing collection (https://api.bbb.org/api/collection/{CollectionId}/mappings)

Specify an "Organizations By Category" mapping. This operation would remove all OrganizationIds that currently belong to the specified Category.

JSON Example
{
	"OrganizationsByCategory": [
		{
			"CategoryId": "461190",
			"CategoryTypeId": 5502
		}
	]
}

Responses

201 Created – if successful

200 - Ok

400 Bad Request – Invalid input type; could not be processed

500 – Internal Error

Errors/Status

Outbound Message for Error Messages ("ErrorMessages" array)

FieldDescription 

Message

Description of error

 

Organizations

Array of Organization types

List of organizations that were not mapped to the collection for reason stated in "Message"

Categories

Array of Category types

List of categories that were not mapped to the collection for reason stated in "Message"

Additional Notes