Different kinds of waste require different (sometimes very specific) kinds of processing.
This is why we offer very specific collection programs, usually collecting only one kind of waste in a program.
The people collecting the same kind of waste in the same collection program are said to be working hard together on the front of eliminating one kind of waste - this is why we call them a brigade.
(Read: Brigades and collection programs are just different names for the same concept in our system.)
As new people arrive and register to collect, they are free to join or leave brigades/collection programs (with a few exceptions - see below).
Some bridages are limited to specific kinds of users
(e.g. schools only, restaurants only, etc.) -
joining these brigades requires manual confirmation from an administrator.
Joining such a brigade will not be immediate and automatic, but will result
in a pending status until an administrator confirms the user is allowed to
join the brigade, at which point the status will change to active.
All brigades have a limit on the number of allowed members ("slots"). Once a brigade is full, users attempting to join are put on a waitlist, and only allowed into the brigade one-by-one when current brigade members leave or are removed for having been inactive for too long.
Get a list of all the brigades we currently offer.
Scope: public; this endpoint does not require a logged in user: you can use OAuth2.0 Client Credentials Flow as described in our Getting Started Guide
Note: Without a logged in user (e.g. using an access_token gathered using the Client Credentials Flow), user-related details (e.g. joined) will be missing in responses, and you also cannot filter by anything user-related (e.g. joined request parameter) - you will receive an error if you do.
GET https://api.terracycle.com/en-US/v2/brigades?access_token=...access_token...
parameter|description
---|---
accesstoken|the `accesstokenacquired through OAuth
joined|optional parameter if a user is logged in - prohibited parameter if a user is not logged in; possible values:<br>trueonly list brigades the user is a member of (is allowed to send in waste for)<br>falseonly list brigades the user is *not* a member of<br>if you specify this parameter when a user is not logged in, you will receive an error
ids|optional parameter: only list brigades having these IDs<br>format is comma-separated list of IDs, e.g.:1,3,7`
page (optional)| it's used for pagination purposes and it means which page do you want to get, by default is 1
per_page (optional)| it's used for pagination purposes and it means how many items do you want to get within a page, by default is 50
$ curl -G \
--data 'access_token=acce55acce55acce55acce55acce55acce55acce55acce55acce55acce55acce' \
https://api.terracycle.com/en-US/v2/brigades?per_page=1&page=1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
"brigades": [
{
"id": 1,
"name": "A Brigade®",
"joined": true,
"cover_image": "https://link_to_cover_image_url"
},
{
"id": 2,
"name": "Another Brigade®",
"joined": false,
"cover_image": "https://link_to_cover_image_url"
}
],
"meta": {
"current_page": 1,
"next_page": 2,
"prev_page": null,
"total_pages": 2,
"total_count": 2
}
}
field|description
---|---
brigades|top-level container for the list (array) of brigades
id|ID of brigade
name|name of brigade
joined|false - user is not member of the brigadetrue - user is member of the brigade (is allowed to send in waste for)
missing (both name and value) - if the request was made without a logged in user
cover_image|brigade cover image url
meta|pagination information
Get detailed info of a brigade and the user's membership in the brigade.
Scope: public; this endpoint does not require a logged in user: you can use OAuth2.0 Client Credentials Flow as described in our Getting Started Guide
Note: Without a logged in user (e.g. using an accesstoken gathered using the Client Credentials Flow), user-related details (e.g. joined, `mycollection`) will be missing in the response.
GET https://api.terracycle.com/en-US/v2/brigades/:brigade_id?access_token=...access_token...
parameter|description
---|---
:brigadeid|the (numeric) ID of the brigade listed in the brigade list
accesstoken|the access_token acquired through OAuth
$ curl -G \
--data 'access_token=acce55acce55acce55acce55acce55acce55acce55acce55acce55acce55acce' \
https://api.terracycle.com/en-US/v2/brigades/1
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
"brigade": {
"id": 1,
"name": "A Brigade®",
"joined": true,
"description": "<p>html description of <strong>A Brigade®</strong></p>",
"collection_locations": 5708,
"open_slots": 126,
"stats": {
"units_collected": 1713156,
"money_raised": 42406.45,
"money_raised_formatted": "$42,406.45"
},
"my_collection": {
"points_earned": 1000,
"units_collected": 50,
"status": "active"
},
"shipping_options": [
{
"id": 65,
"name": "Download a shipping label",
"description": "Download a shipping label to print on your printer."
},
{
"id": 93,
"name": "Get a shipping label",
"description": "Receive a shipping label in email to print on your printer."
},
{
"id": 105,
"name": "Get 10 shipping labels",
"description": "Get 10 shipping labels preprinted and shipped to you in an envelope."
},
{
"id": 117,
"name": "5 coffee liner bags",
"description": "Get 5 coffee liner bags shipped to you, to put into your coffee collection boxes, to prevent your boxes from soiling their surroundings.",
"confirmation_message": "Do you want us to ship 5 coffee liner bags to you?"
},
{
"id": 239,
"name": "10 coffee liner bags",
"description": "Get 10 coffee liner bags shipped to you, to put into your coffee collection boxes, to prevent your boxes from soiling their surroundings.",
"confirmation_message": "Do you want us to ship 10 coffee liner bags to you?"
}
]
}
}
field|description
---|---
brigade|top-level container for the info about the brigade and the user's membership in the brigade
id|numeric ID of the brigade
name|name of brigade
joined|false - user is not member of the brigadetrue - user is member of the brigade (is allowed to send in waste for)
missing (both name and value) - if the request was made without a logged in user
description|short description of the brigade - String
collectionlocations|number of members in this brigade
openslots|number of open member slots in this brigade (brigades limit the total number of members) - if this number is zero, joining this brigade will result in the user getting waitlisted
stats|container for the collection statistics of the entire brigade
unitscollected|estimated waste units collected in this brigade
moneyraised|estimated money raised for charitable purposes through waste collection in this brigade - formatted as a computer-readable number with fractional point
money_raised_formatted|this is the same number as money_raised above, but formatted for humans using the currency symbol and formatting conventions of the country
mycollection|container for the collection statistics and membership of the user in this brigade
if the user was never a member of this brigade, the statistics will show zeroes and the status will be `neverjoined`
if the request was made without a logged in user, this container is missing entirely (both name and contents)
pointsearned|total number of points this user was ever awarded for waste collected and sent in for this brigade; this number normally only increases, after each shipment of waste was received and points were awarded for it, except when an administrator issues a necessary negative correction
unitscollected|total number of units of waste this user has collected and sent in for this brigade; this number normally only increases, except when an administrator issues a necessary negative correction
status|user's membership status in the brigade - see below
shippingoptions|see section shipping options for an overview of shipping options
id|shipping option ID - use when creating a new shipment (see creating a shipment)
name|short name of shipping option
description|detailed description of shipping option
confirmationmessage|if this field exists, display this message to the user in a confirmation (OK/Cancel) dialog. and only issue the create shipment API call if the user confirms
status|description
---|---
active|The user can send in waste for this brigade (e.g. by means of creating shipping labels, requesting collection boxes, etc.)
wait_listed|The user is on a waitlist because the brigade is full (has no open slots available for new members).
The user can not send in waste for this brigade currently.
The user will be notified via email when a slot became available and the user was allowed in as a member, at which point they will be changed to active, and will be able to send in waste for this brigade.
pending|(For brigades requiring confirmation)
The system has registered the user's intent to become member of the brigade, and now an administrator will check whether the user is entitled to be a member in the brigade.
The user can not send in waste for this brigade currently.
If the user is allowed in, the administrator will set status to active and the user will be notified in email.
if the user is not eligible to become a member of the brigade, the administrator will set the status to deleted and the user will be notified in email.
incomplete|Some information needed to collect waste for this brigade is missing from the user's account.
Most often it is one or more of the contact information fields (see section Account) - please have the user complete their profile (follow the steps from chapter Incomplete profile), and then attempt to join the brigade again.
The user can not send in waste for this brigade currently.
scrubbed|User was not sending in waste for this brigade for a long time, so their membership was revoked in order to free up slots to allow other users in to the brigade. The user can not send waste in for this brigade currently, but is free to attempt to join the brigade again.
deleted|User was (or attempted to become) a member previously, but has either left the brigade, or was not allowed in to the brigade. The user can not send waste in for this brigade currently, but is free to attempt to join the brigade again.
never_joined|User was never a member. The user can not send waste in for this brigade currently. The user is free to attempt to join the brigade.
If your application is not authorized to list members of the specified brigade you will receive a 401 Unauthorized error response.
This will happen if you try to list members of a Brigade that does not belong to your business or has not yet been associated with your Application.
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
"error": "unauthorized",
"message": "You are not authorized to list members of this brigade."
}
If you are trying to access this endpoint with an access token that was not acquired through the OAuth2 Client Credentials flow then you will receive a 401 Unauthorized error response.
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
"error": "unauthorized",
"message": "Wrong token type. Please use OAuth2 Client Credentials flow."
}
Join authorized user to a Brigade.
NOTE: Result codes and messages displayed in this section are works in progress, and are expected to change in the production release of the API. Please do not base any final work on this specification yet.
Scope: join_brigade
POST https://api.terracycle.com/en-US/v2/brigades/:brigade_id/join
parameter|description
---|---
:brigadeid|the (numeric) ID of the brigade listed in the brigade list
accesstoken|the access_token acquired through OAuth
$ curl \
--data 'access_token=acce55acce55acce55acce55acce55acce55acce55acce55acce55acce55acce' \
https://api.terracycle.com/en-US/v2/brigades/1/join
User is member of the brigade now, and can send in waste for this brigade.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
"message": "active"
}
User is on a waitlist (the Brigade had no open membership slots).
The user will be notified via email when a slot became available and the user was allowed in as a member, at which point they will be changed to active, and will be able to send in waste for this brigade.
HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
{
"message:" "waitlisted"
}
The system has registered the user's intent to become member of the brigade, and now an administrator will check whether the user is entitled to be a member in the brigade.
The user can not send in waste for this brigade currently.
If the user is allowed in, the administrator with set the status to active and the user will be notified in email.
if the user is not eligible to become a member of the brigade, the administrator will set the status to deleted and the user will be notified in email.
HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
"message:" "pending"
}
The user has no valid shippable address on their account. Without an address the user will not be able to send in waste through our carrier services, so we reject their attempts at becoming members in any brigade.
The user should fill in a valid shipping address (including contact phone number) on their account, and then attempt to join the brigade again - please follow the steps from chapter Incomplete profile.
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
"message": "incomplete",
"error:" "no-shippable-address"
}
Joining the brigade failed for an unknown reason.
This is a catch-all error that should not happen. If you as a developer encounter this during development of your application, please contact us so that we can work together to discover and eliminate the cause. If your users are encountering this while using your application, please direct them to Customer Support.
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
"error:" "cannot-activate"
}
Leave a brigade (relinquishing one's membership slot to the first waitlisted user if any).
Scope: leave_brigade
DELETE https://api.terracycle.com/en-US/v2/brigades/:brigade_id/leave
parameter|description
---|---
:brigadeid|the (numeric) ID of the brigade listed in the brigade list
accesstoken|the access_token acquired through OAuth
Note: If your HTTP library does not support issuing requests with the HTTP DELETE verb, issue a POST request instead and add a parameter _method with value delete.
$ curl -X DELETE \
--data 'access_token=acce55acce55acce55acce55acce55acce55acce55acce55acce55acce55acce' \
https://api.terracycle.com/en-US/v2/brigades/1/leave
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
"message": "deleted"
}
After leaving, the detailed brigade info will show my_collection with the user's collection statistics intact forever, but the membership status will be deleted and the user will not be able to send waste in for this brigade. The user is however free to attempt to join the brigade again.