API Docs

Account

Account (or User Account or User) is the name in our system for a person or a group of people who participate in collecting waste.

Most of our collection programs award points after waste collected and sent in according to the rules of the program. For this the program registers the units of waste sent in, and then awards points according to the program's tiered units/points conversion table. These units and points then accrue on the Account as units_collected and points_earned respectively. Accrued points can later be redeemed (spent) for charitable items and goals - the remaining unredeemed (unspent) points are shown as available_points.

Since we both want to show people their contribution to eliminating waste, as well as how much they can still redeem for charitable items and goals, we provide two numbers: points_earned shows the total of the points the account was ever awarded for waste sent in, while available_points shows the "current balance" - the amount of points they currently can redeem.

Get account info

Get detailed information on the account of the user currently logged in through your application.

Scope: account_read

Request

GET https://api.terracycle.com/en-US/v2/account?access_token=...access_token...
Request parameter
parameter description
access_token the access_token acquired through OAuth

Example

curl -G \
  -d 'access_token=acce55acce55acce55acce55acce55acce55acce55acce55acce55acce55acce' \
  https://api.terracycle.com/en-US/v2/account

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Language: en-US
{
  "account": {
    "uuid": "262dcf0f6a32cc15daae58f1bc05b0dc6017f70cc4f4a91dbb397ea0be6dd827",
    "email": "jeffrey.moody@domain.com",
    "complete": true
    "profile": {
      "first_name": "Jeffrey",
      "last_name": "Moody",
      "addresses": [
        {
          "contact_name": "Jeffrey Moody",
          "street_address": "2714 Bee Street",
          "extended_address": "bldg C, PTA room",
          "locality": "Muskegon",
          "region": "MI",
          "postal_code": "49470",
          "phone_number": "231-799-9376"
        }
      ]
      "organization_name": "Bee Street School",
      "organization_type": "Primary School"
    },
    "stats": {
      "available_points": 1000,
      "units_collected": 500,
      "points_earned": 2000
    }
  }
}
field name description
account top-level container for all account info
uuid permanent unique identifier for this account;
always present, always unique between accounts, guaranteed never to change
email always present, always unique between accounts, but users can change it;
users sign in with this and their password
complete true if the profile is complete and the account can join brigades and collect waste
false if the profile is incomplete (some information is missing or wrong) and the account will not be able to join brigades and collect waste - see Incomplete profile/account below.
profile container containing contact and ancillary information of the account
addresses accounts can have one or more addresses; one address is mandatory currently to participate in waste collection
contact_name person addressed on mailing labels
street_address street address on mailing labels, typically down to house number - this is often called "address line 1" in other systems
extended_address detail part of street address omitted from street_address above, e.g. building, floor, appt number - this is often called "address line 2" in other systems
locality name of city/town/settlement
region commonly used name or postal abbreviation/code for region within country (e.g. the two-letter codes for the states in the USA and provinces in Canada, etc.); present but null if the country does not use this
postal_code commonly used postal code for this address (e.g. 5-digit ZIP code in the USA)
phone_number telephone number for this address as the user entered it on their profile page - required by most of our carriers to be able to contact the recipient about delivery
organization_name the information the account owner entered under "organization name" on their profile page
organization_type the information the account owner entered under "organization type" on their profile page
stats waste collection statistics totalled over all activities of this account
available_points number of points the account currently has available to redeem for charitable items/goals; this number increases when points are awarded to the account for waste that was sent in, and decreases when the account owner redeems points for charitable items/goals
units_collected total number of units of waste this account has collected and sent in; this number normally only increases, except when an administrator issues a necessary negative correction
points_earned total number of points this account was ever awarded for waste collected and sent in; 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

Incomplete profile/account

Incomplete accounts can be legacy accounts (created before this API was introduced) as well as accounts created in applications that elected not to require contact information as a mandatory part of signing up (including your application if you configured it this way during Register your application). If you are planning your application to work with such accounts, prepare your application to be able to handle incomplete accounts as described below.

To conduct our collection programs, we need shipping and contact information of our participants. As without this information our business processes for collection will not work, accounts without this information will not be able to participate in waste collection. Therefore this information is required for accounts participating in our collection programs.

Accounts where all of this information is present we call "complete"; accounts where one or more pieces of this information is missing we call "incomplete".

Our system refuses any requests where this information would be needed but is not available. E.g. requests to join collection programs (among others) will be refused if the request was issued by a user with an "incomplete" account.

When this happens, your application should tell the user that the requested functionality is only available with a complete profile, and offer the user the choice to edit/complete their profile. Then if the user agrees, you should redirect the user to the profile edit page on our servers. (Alternatively you may decide to redirect the user right away without asking their confirmation first.)

The URL for the profile edit page is specific to your application, and is displayed as "Edit Profile URL" on your application's detail page (the same page where you can see your application's "Client ID" and "Client Secret").

Example "Edit Profile URL":

https://api.terracycle.com/en-US/oauth/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef/account.html

In the "Edit Profile URL" you should also supply two parameters:

  • title - We will display this on the top of the profile edit page. You should provide text here that helps the user understand the context, e.g. "To be able to join brigades, please complete your profile below"
  • redirect_uri - This is the URL we will redirect the user to after successfully editing their profile (see explanation for redirect_uri in Register your Application)

Example "Edit Profile URL" with parameters:

https://api.terracycle.com/en-US/oauth/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef/account.html?redirect_uri=https%3A%2F%2Fwww.example.com%2Foauth%2Fcallback%2Fafter_profile_edit%3Fuser%3D12345&title=To+be+able+to+join+brigades%2C+please+complete+your+profile+below

Then we will display to the user their profile edit page where they can fill out and submit their contact and shipment information.

Once the user successfully edited their profile, we will redirect them back to your server (the redirect_uri you specified when you redirected the user to us), at which point your application will probably want to reissue the request to our servers to retry the operation previously refused by our servers.