API Docs

Brigades (Collection programs)

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 Brigades list

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.

Request

GET https://api.terracycle.com/en-US/v2/brigades?access_token=...access_token...
Request parameters
parameter description
access_token the access_token acquired through OAuth
joined optional parameter if a user is logged in - prohibited parameter if a user is not logged in; possible values:
true only list brigades the user is a member of (is allowed to send in waste for)
false only list brigades the user is not a member of
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
format is comma-separated list of IDs, e.g.: 1,3,7
Example
$ curl -G \
 --data 'access_token=acce55acce55acce55acce55acce55acce55acce55acce55acce55acce55acce' \
 https://api.terracycle.com/en-US/v2/brigades

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
  "brigades": [
    {
      "id": 1,
      "name": "A Brigade®",
      "joined": true
    },
    {
      "id": 2,
      "name": "Another Brigade®",
      "joined": false
    }
  ]
}
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 brigade
true - 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

Get Brigade

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.

Request

GET https://api.terracycle.com/en-US/v2/brigades/:brigade_id?access_token=...access_token...
Request parameters
parameter description
:brigade_id the (numeric) ID of the brigade listed in the brigade list
access_token the access_token acquired through OAuth
Example
$ curl -G \
 --data 'access_token=acce55acce55acce55acce55acce55acce55acce55acce55acce55acce55acce' \
 https://api.terracycle.com/en-US/v2/brigades/1

Response

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 brigade
true - 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
collection_locations number of members in this brigade
open_slots 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
units_collected estimated waste units collected in this brigade
money_raised 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
my_collection 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 never_joined
if the request was made without a logged in user, this container is missing entirely (both name and contents)
points_earned 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
units_collected 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
shipping_options 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
confirmation_message 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

Collection/membership statuses

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.
You are not authorized to list members of this 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."
}
Wrong token type. Please use OAuth2 Client Credentials flow.

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 Brigade

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

Request

POST https://api.terracycle.com/en-US/v2/brigades/:brigade_id/join
Request parameters
parameter description
:brigade_id the (numeric) ID of the brigade listed in the brigade list
access_token the access_token acquired through OAuth
Example
$ curl \
 --data 'access_token=acce55acce55acce55acce55acce55acce55acce55acce55acce55acce55acce' \
 https://api.terracycle.com/en-US/v2/brigades/1/join

Response

Active

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"
}
Waitlisted

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"
}
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 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"
}
No Shippable Address

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"
}
Cannot Activate

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 brigade

Leave a brigade (relinquishing one's membership slot to the first waitlisted user if any).

Scope: leave_brigade

Request

DELETE https://api.terracycle.com/en-US/v2/brigades/:brigade_id/leave
Request parameters
parameter description
:brigade_id the (numeric) ID of the brigade listed in the brigade list
access_token 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.

Example
$ curl -X DELETE \
 --data 'access_token=acce55acce55acce55acce55acce55acce55acce55acce55acce55acce55acce' \
 https://api.terracycle.com/en-US/v2/brigades/1/leave

Response

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.