API

https://www.dosomething.org/api/v1/

Authentication
Campaigns
- index
- show/retrieve
Signups
- index
- show/retrieve
Kudos
- index
- show/retrieve
Reportbacks
- index
- show/retrieve
Reportback Items
- index
- show/retrieve
Terms
System
Users

Authentication

User login

POST https://www.dosomething.org/api/v1/auth/login

username: (string) required. The user username.
password: (string) required. The user password.

Response:

If login was successful, the response contains values to use when making subsequest authenticated requests during the session. See https://www.drupal.org/node/910598 for details.

token: (string). The header value to post as X-CSRF-Token.
sessid: (string). The value to set for the Cookie header.
session_name: (string). The name of the Cookie header to post.
user: (object). The logged in user.

Example request:

curl https://www.dosomething.org/api/v1/auth/login 
 -d '{
  "username":"[email protected]",
  "password":"imB@tman789Kittycat$"
  }' -H "Content-type: application/json" 
  --header "Accept: application/json"

Example response:

{
    "sessid": "OlRJjdQNZyYgxjmF7c0GtUSiO1pCczRCOzqetJJMs5w",
    "session_name": "SESS8de1794320df15914c40c2b37d51eff2",
    "token": "-XmDawHfJ3MRBFGgBvHaF4_RlHq0Dp_xfffGimzr6mM",
    "user": {
        "uid": "38",
        "name": "batman",
        "mail": "[email protected]",
        "theme": "",
        "signature": "",
        "signature_format": "plain_text",
        "created": "1392999246",
        "access": "1405601994",
        "login": "1405601911",
        "status": "1",
        "timezone": "UTC",
        "language": "",
        "picture": "0",
        "data": false,
        "uuid": "8a88c274-d4b4-4f66-b8b7-59029173248c",
        "sid": "KWB0uMKU5IyS2Xgw27v7wnhF9HKoVfJ23dFFt0r7o8s",
        "ssid": "",
        "hostname": "10.0.2.2",
        "timestamp": "1405601911",
        "cache": "0",
        "session": "",
        "roles": {
            "2": "authenticated user"
        }
    }
}

User logout

POST https://www.dosomething.org/api/v1/auth/logout

Example request:

curl https://www.dosomething.org/api/v1/auth/logout -X POST --header "Content-type: application/json" --header "Accept: application/json" --header "X-CSRF-Token: -XmDawHfJ3MRBFGgBvHaF4_RlHq0Dp_xfffGimzr6mM" --header "Cookie: SESS8de1794320df15914c40c2b37d51eff2=OlRJjdQNZyYgxjmF7c0GtUSiO1pCczRCOzqetJJMs5w"

Example response:

[true]

Get authentication token

Returns the X-CSRF Token for the logged in user.

POST http://www.dosomething.org/api/v1/auth/token

Example response:

{"token":"TX5fHzUYtOmQyAi9LZkt1hZZlpHiNj9RhmjNocKK-a4"}

Campaigns

Retrieve a campaign collection

GET https://www.dosomething.org/api/v1/campaigns

Note: Only campaigns with a campaign type of campaign are returned (e.g. sms_game campaigns are filtered)

Optional Query Parameters

ids (string|csv)
- Specify the campaign(s) to return
- ex: /campaigns?ids=123,456,789
count (default is 25)
- Set the number of campaigns to return in a single response
- ex: /campaigns?count=25
page (integer)
- For pagination, specify page of campaigns to return in the response
- ex: /campaigns?page=2
staff_pick (boolean)
- If set to true, will only return staff pick campaigns
- ex: /campaigns?staff_pick=true
mobile_app (boolean)
- If set to true, will only return campaigns tagged for the mobile app
- ex: /campaigns?mobile_app=true
mobile_app_date (date)
- Return mobile campaigns valid for a given date
- ex: /campaigns?mobile_app_date=2015-09-02
term_ids (string|csv)
- Return only campaigns that are tagged with the term IDs specified
- ex: /campaigns?term_ids=123,456,789
random (boolean)
- If set to true, will return campaigns in random order
- ex: /campaigns?random=true
cache (boolean)
- Defaults to true
- If set to false will not cache request and if already cached, it will be removed from cache
- ex: /campaigns?cache=false

Retrieve a specific campaign

GET https://www.dosomething.org/api/v1/campaigns/:id

id (int) [Required]
The id of the campaign node to retrieve data for.

Example request:

https://www.dosomething.org/api/v1/campaign/1247

Example response:

{
  data: {
    id: "362",
    title: "Comeback Clothes",
    campaign_runs: {
      current: {
        en: {
          id: "1227"
        }
      },
      past: [ ]
    },
    language: {
      language_code: "en",
      prefix: "us"
    },
    translations: {
      original: "en",
      en: {
        language_code: "en",
        prefix: "us"
      },
      en-global: {
        language_code: "en-global",
        prefix: null
      }
    },
    tagline: "Recycle old or worn-out clothes to help all the planets.",
    created_at: "1393518858",
    updated_at: "1452893294",
    status: "closed",
    time_commitment: 5,
    cover_image: {
      default: {
        uri: "http://dev.dosomething.org:8888/sites/default/files/styles/300x300/public/ComebackClothes_hero_square.jpg?itok=4FFah0EJ",
        sizes: {
          landscape: {
            uri: "http://dev.dosomething.org:8888/sites/default/files/styles/1440x810/public/ComebackClothes_hero_landscape.jpg?itok=f9LusEHG"
          },
          square: {
            uri: "http://dev.dosomething.org:8888/sites/default/files/styles/300x300/public/ComebackClothes_hero_square.jpg?itok=4FFah0EJ"
          }
        },
        type: "image",
        dark_background: false
      },
      alternate: null
    },
    staff_pick: true,
    competition: true,
    facts: {
      problem: "11.1 million tons of fabric that could be recycled ends up in landfills every year. That's the equivalent of over 70 billion t-shirts.",
      solution: null,
      sources: [
        {
          formatted: "<p>"Textiles." United States Environmental Protection Agency. Accessed February 24, 2014. http://www.epa.gov/osw/conserve/materials/textiles.htm</p> "
        }
      ]
    },
    solutions: {
      copy: {
        raw: "Instead of trashing old clothes, give them a second life by recycling them. You’ll save water, energy, and landfill space.",
        formatted: "<p>Instead of trashing old clothes, give them a second life by recycling them. You’ll save water, energy, and landfill space.</p> "
      },
      support_copy: {
        raw: "Run a drive at your school to collect recycled clothes and drop them off at your local H&M.",
        formatted: "<p>Run a drive at your school to collect recycled clothes and drop them off at your local H&amp;M.</p> "
      }
    },
    pre_step: {
      header: "Run Your Drive!",
      copy: {
        raw: "If you’re lucky, you’ll see more mustard-, blood-, and mystery-liquid-stained stuff than ever before! Gross! Hooray!",
        formatted: "<p>If you’re lucky, you’ll see more mustard-, blood-, and mystery-liquid-stained stuff than ever before! Gross! Hooray!</p> "
      }
    },
    latest_news: {
      latest_news: null
    },
    causes: {
      primary: {
        id: "4",
        name: "environment"
      },
      secondary: [
        {
          id: "4",
          name: "environment"
        }
      ]
    },
    action_types: {
      primary: {
        id: "7",
        name: "donate something"
      },
      secondary: [
        {
          id: "7",
          name: "donate something"
        },
        {
          id: "11",
          name: "host an event"
        },
        {
        id: "8",
        name: "improve a space"
        }
      ]
    },
    issue: {
      id: "347",
      name: "recycling"
    },
    tags: [
      {
        id: "48",
        name: "trash"
      },
      {
        id: "348",
        name: "recycling"
      },
      {
        id: "349",
        name: "clothes"
      },
      {
        id: "350",
        name: "h&m"
      },
      {
        id: "102",
        name: "drive"
      },
      {
        id: "49",
        name: "earth"
      },
      {
        id: "351",
        name: "planet"
      },
      {
        id: "97",
        name: "environment"
      },
      {
        id: "352",
        name: "eco"
      },
      {
        id: "366",
        name: "collection"
      },
      {
        id: "668",
        name: "music" 
      } 
    ],
    timing: {
      high_season: {
        start: "2015-07-18T00:00:00+0000",
        end: "2015-07-25T00:00:00+0000"
      },
      low_season: null
    },
    services: {
      mobile_commons: {
        opt_in_path_id: "165501",
        friends_opt_in_path_id: null
      },
      mailchimp: {
        grouping_id: null,
        group_name: null
      }
    },
    mobile_app: {
      dates: {
        start: "2015-11-01T00:00:00+0000",
        end: "2016-02-01T00:00:00+0000"
      }
    },
    reportback_info: {
      copy: "Submit your photo before June 20 to qualify for the scholarship.",
      confirmation_message: "Going green is always in style! Thanks for helping the Earth.",
      noun: "Items",
      verb: "Recycled"
    },
    uri: "http://dev.dosomething.org:8888/api/v1/campaigns/362"
  }
}

Retrieve a campaign (will be deprecated)

GET https://www.dosomething.org/api/v1/content/:nid

nid (int) Required. The Node nid to retrieve content for.

Example request:

curl https://www.dosomething.org/api/v1/content/5140 \
 -H "Accept: application/json"

@todo: Make this live under api/v1/campaigns/:nid as well to keep consistent.

Campaign signup

Creates a User Signup for the given Campaign nid if a Signup does not exist.

POST https://www.dosomething.org/api/v1/campaigns/[nid]/signup

Must be authenticated to post.

uid: (int). The user uid reporting back. If not included, the uid of the current user will be used.
source: (string) required. The signup source, e.g. iphone, android

Example request:

curl https://www.dosomething.org/api/v1/campaigns/23/signup -X POST 
--header "Content-type: application/json" 
--header "Accept: application/json" 
--header "X-CSRF-Token: G136HF5yB5ZZawvrsOfU4gw0poUOaQygPrsJlaFakMU" 
--header "Cookie:SESSd57f2aef87e6d4352ce5db4659184fa7=mKI5_yfoXYBz3r4o95utui4fwBV_lUO1JNN1nEVsPRg" 
-d '{
  "uid": 1702889,
  "source": "sms"
}'

Response: Signup sid, if success.

[
    "1307"
]

Campaign reportback

Creates or updates a User Reportback for the given Campaign nid.

POST https://www.dosomething.org/api/v1/campaigns/[nid]/reportback

Must be authenticated to post.

uid: (int). The user uid reporting back. If not included, the uid of the current user will be used.
nid: (int) required. The node nid the user is reporting back to.
quantity: (int) required. The number of reportback nouns verbed.
why_participated: (string) required. The reason why the user participated.
file_url: (string) required if file is not provided. An image URL for the reportback.
file: (string) required if file_url is not provided. Base64 encoded file string to save.
filename: (string) required if file is provided. Necessary for Drupal File API save (see dosomething_reportback_get_file_dest).
caption: (string). Corresponding caption for the reportback image.

Response: The reportback rbid if success, FALSE if not.

Example request:

curl https://www.dosomething.org/api/v1/campaigns/23/reportback -X POST 
--header "Content-type: application/json" 
--header "Accept: application/json" 
--header "X-CSRF-Token: G136HF5yB5ZZawvrsOfU4gw0poUOaQygPrsJlaFakMU" 
--header "Cookie:SESSd57f2aef87e6d4352ce5db4659184fa7=mKI5_yfoXYBz3r4o95utui4fwBV_lUO1JNN1nEVsPRg" 
-d '{
  "quantity": 30,
  "uid": 1702889,
  "file_url": "http://voldemortwearsarmani.files.wordpress.com/2013/01/batman-chronicles.jpg",
  "why_participated": "Test from API",
  "caption": "API Testing!"
}'

Example response:

["127"]

Signups

Retrieve a signup collection

GET https://www.dosomething.org/api/v1/signups

Optional query parameters

user (string|csv)
User id to get a specific user's signups
eg: /signups?user=98
campaigns (string|csv)
Comma separated list of campaign ids to get signups
eg: /signups?campaigns=362,1172

Example request:

http://dev.dosomething.org:8888/api/v1/signups?user=98&campaigns=1173

Example response:

{
  data: [
    {
      id: "243",
      created_at: "1400103603",
      campaign_run: {
        id: "1816",
        current: true
      },
      uri: "http://dev.dosomething.org:8888/api/v1/signups/243",
      campaign: {
        id: "1173",
        title: "Thumb Wars",
        campaign_runs: {
          current: {
            en: {
              id: "1816"
            },
            en-global: {
              id: "1816"
            }
          },
          past: [ ]
        },
        language: {
          language_code: "en",
          prefix: "us"
        },
        translations: {
          original: "en",
          en: {
            language_code: "en",
            prefix: "us"
          },
          en-global: {
            language_code: "en-global",
            prefix: null
          }
        },
        tagline: "Send friends Thumb Socks to remind them not to text and drive.",
        status: "active",
        type: "campaign",
        reportback_info: {
          copy: "Send us a shot of your friend rockin' their Socks!",
          confirmation_message: "Thumbs up, Thumb Warrior! Thanks for keeping your friends -- and the streets -- safe.",
          noun: "Thumb Socks",
          verb: "shared"
        }
      },
      reportback: {
        id: "75",
        created_at: "1400106458",
        updated_at: "1435775063",
        quantity: 12,
        uri: "http://dev.dosomething.org:8888/api/v1/reportbacks/75",
        why_participated: "This is just a test",
        flagged: false,
        reportback_items: {
          total: 5,
          data: [
            {
              id: "498",
              status: "approved",
              caption: "DoSomething? Just did!",
              uri: "http://dev.dosomething.org:8888/api/v1/reportback-items/498",
              media: {
                uri: "http://dev.dosomething.org:8888/sites/default/files/styles/480x480/public/reportbacks/1173/uid_98-nid_1173-0.jpg?itok=4fGl_sNv",
                type: "image"
              },
              created_at: "1402439166",
              kudos: {
                data: [ ]
              }
            },
            {
              id: "499",
              status: "approved",
              caption: "DoSomething? Just did!",
              uri: "http://dev.dosomething.org:8888/api/v1/reportback-items/499",
              media: {
                uri: "http://dev.dosomething.org:8888/sites/default/files/styles/480x480/public/reportbacks/1173/uid_98-nid_1173-1.jpg?itok=KMfogXPn",
type: "image"
              },
              created_at: "1402439166",
              kudos: {
                data: [ ]
              }
            }
          ]
        }
      }
    }
  ]
}

Retrieve a specific signup

GET https://www.dosomething.org/api/v1/signups/:sid

Example request:

http://dev.dosomething.org:8888/api/v1/signups/42

Example response:

{
  data: {
    id: "42",
    created_at: "1394567434",
    campaign_run: {
      id: "0",
      current: false
    },
    uri: "http://dev.dosomething.org:8888/api/v1/signups/42",
    campaign: {
      id: "1173",
      title: "Thumb Wars",
      campaign_runs: {
        current: {
          en: {
            id: "1816"
          },
          en-global: {
            id: "1816"
          }
        },
          past: [ ]
        },
        language: {
          language_code: "en",
          prefix: "us"
        },
        translations: {
          original: "en",
          en: {
            language_code: "en",
            prefix: "us"
          },
          en-global: {
            language_code: "en-global",
            prefix: null 
          }
        },
        tagline: "Send friends Thumb Socks to remind them not to text and drive.",
        status: "active",
        type: "campaign",
        reportback_info: {
          copy: "Send us a shot of your friend rockin' their Socks!",
          confirmation_message: "Thumbs up, Thumb Warrior! Thanks for keeping your friends -- and the streets -- safe.",
          noun: "Thumb Socks",
          verb: "shared"
        }
      },
      reportback: {
        id: "75",
        created_at: "1400106458",
        updated_at: "1435775063",
        quantity: 12,
        uri: "http://dev.dosomething.org:8888/api/v1/reportbacks/75",
        why_participated: "This is just a test",
        flagged: false,
        reportback_items: {
          total: 5,
          data: [
            {
              id: "498",
              status: "approved",
              caption: "DoSomething? Just did!",
              uri: "http://dev.dosomething.org:8888/api/v1/reportback-items/498",
              media: {
                uri: "http://dev.dosomething.org:8888/sites/default/files/styles/480x480/public/reportbacks/1173/uid_98-nid_1173-0.jpg?itok=4fGl_sNv",
                type: "image"
              },
              created_at: "1402439166",
              kudos: {
                data: [ ]
              }
            },
          ]
        }
      }
    }
  ]
}

Create a kudos record

POST https://www.dosomething.org/api/v1/kudos

Required parameters

reportback_item_id
user_id
term_ids

Kudos

Retrieve a kudos collection

GET https://www.dosomething.org/api/v1/kudos

Optional query parameters

reportbackitems (string|csv)
Comma separated list of reportback ids to get kudos
eg: /kudos?reportbackitems=714,2381
count (integer) default = 25
Number of kudos to retrieve
eg: /kudos?count=3

Retrieve a specific kudos

GET https://www.dosomething.org/api/v1/kudos/10

Create a kudos record

POST https://www.dosomething.org/api/v1/kudos

Required parameters

reportback_item_id
user_id
term_ids

Reportbacks

Retrieve a reportback collection

Optional Query Parameters

campaigns (string|csv)
- The ids of specified campaigns to get reportbacks
- ex: /reportbacks?campaigns=1080,362
status (string|csv)
- Comma delimited list of reportback statuses to collect reportbacks for
- ex: /reportbacks?status=promoted
count (integer)
- The number of reportbacks to retrieve
- ex: /reportbacks?count=5
random (boolean)
- Boolean to indicate whether to retrieve reportbacks in random order
- ex: /reportbacks?random=true
page (integer)
- For pagination, specify page of reportbacks to return in the response
- ex: /reportbacks?page=3
load_user (boolean)
- Flag to indicate whether to make call to northstar to retrieve full user data.
- ex: /reportbacks?load_user=true
flagged (boolean)
- Boolean to indicate whether to also retrieve flagged reportbacks.
- ex: /reportbacks?flagged=true

Retrieve a specific reportback

GET `https://www.dosomething.org/api/v1/reportbacks/:id

Example request:

https://www.dosomething.org/api/v1/reportbacks/1982

Example response:

{
  data: {
    id: "1982",
    created_at: "1427226250",
    updated_at: "1428442705",
    quantity: 12,
    why_participated: "Nulla vitae elit libero, a pharetra augue.",
    flagged: false,
    reportback_items: {
      total: 2,
      data: [
        {
          id: "1990",
          caption: "Sed posuere consectetur est.",
          uri: "https://www.dosomething.org/api/v1/reportback-items/1990",
          media: {
            uri: "https://www.dosomething.org/sites/default/files/styles/480x480/public/image1990.jpeg",
            type: "image"
          },
          created_at: "1427226250",
          status: "approved"
        },
        {
          id: "1992",
          caption: "Cras justo odio, facilisis.",
          uri: "https://www.dosomething.org/api/v1/reportback-items/1992",
          media: {
            uri: "https://www.dosomething.org/sites/default/files/styles/480x480/public/image1992.jpeg",
            type: "image"
          },
          created_at: "1427226629",
          status: "approved"
        }
      ]
    },
    campaign: {
      id: "58",
      title: "Shelter Pet PR"
    },
    user: {
      id: "128847239"
    }
  }
}

Reportback-Items

Retrieve a collection of Reportback Items

GET https://www.dosomething.org/api/v1/reportback-items

Optional query Parameters

campaigns (string|csv)
- Comma separated list of campaign ids
- eg: /reportback-items?campaigns=1080,362
status (string) default = promoted,approved
- Comma separated list of statuses
- These include promoted, approved, excluded, flagged
- Only promoted and approved are available to anonymous requests.
- eg: /reportback-items?status=promoted
count (integer) default = 25
- Number of items to retrieve
- If paginated, number to show per page
- eg: /reportback-items?count=10
random (boolean) default = false
- Boolean to indicate whether to retrieve items randomly
- eg: /reportback-items?random=true
page (integer) default = 1
- If data is paginated, can specify a specific page of retrieved data
load_user (boolean)
- Flag to indicate whether to make call to northstar to retrieve full user data.
- ex: /reportbacks?load_user=true

Example request:

https://www.dosomething.org/api/v1/reportback-items?campaigns=1321,362,1283&status=promoted,approved&count=3&random=true

Example response:

  {
  pagination: {
    total: 166,
    per_page: 3,
    current_page: 1,
    total_pages: 56,
    prev_uri: null,
    next_uri: "https://www.dosomething.org/api/v1/reportback-items?&campaigns=1321,362,1283&status=promoted,approved&count=3&page=2"
  },
  retrieved_count: 3,
  data: [
    {
      id: "572",
      caption: "DoSomething? Just did!",
      uri: "https://www.dosomething.org/api/v1/reportback-items/572",
      media: {
        uri: "https://www.dosomething.org/sites/default/files/styles/480x480/public/reportbacks/362/image12.jpeg",
        type: "image"
      },
      created_at: "1402439166",
      status: "approved",
      reportback: {
        id: "78",
        created_at: "1395858155",
        updated_at: "1423857962",
        quantity: 20,
        why_participated: "Nulla vitae elit libero, a pharetra augue.",
        flagged: false
      },
      campaign: {
        id: "362",
        title: "Comeback Clothes"
      },
      user: {
        id: "2688313"
      }
    },
    {
      id: "658",
      caption: "DoSomething? Just did!",
      uri: "https://www.dosomething.org/api/v1/reportback-items/658",
      media: {
        uri: "https://www.dosomething.org/sites/default/files/styles/480x480/public/reportbacks/362/image42.jpeg",
        type: "image"
      },
      created_at: "1402428343",
      status: "approved",
      reportback: {
        id: "89",
        created_at: "1394658072",
        updated_at: "1394743866",
        quantity: 12,
        why_participated: "Because I want everybody to look cool!",
        flagged: false
      },
      campaign: {
        id: "362",
        title: "Comeback Clothes"
      },
      user: {
        id: "486418",
        first_name: "John",
        last_name: "Dow", 
        photo: "https://avatar.dosomething.org/uploads/avatars/55566327bffebc0b3e8b45a5.jpeg",
        country: "US"
      }
    },
    {
      id: "5874",
      caption: "Morbi leo risus porta ac.",
      uri: "https://www.dosomething.org/api/v1/reportback-items/5874",
      media: {
        uri: "https://www.dosomething.org/sites/default/files/styles/480x480/public/reportbacks/1321/image679.jpeg",
        type: "image"
      },
      created_at: "1423757294",
      status: "approved",
      reportback: {
        id: "895",
        created_at: "1423757294",
        updated_at: "1423757423",
        quantity: 1,
        why_participated: "Duis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit.",
        flagged: false
      },
      campaign: {
        id: "1321",
        title: "Hunt Day 5: Band-Aid Brigade"
      },
      user: {
        id: "4878998"
        first_name: "John",
        last_name: "Smith", 
        photo: "https://avatar.dosomething.org/uploads/avatars/55566327bffebc0b3e8b45a7.jpeg",
        country: "US"
      }
    }
  ]
}

Retrieve a specific Reportback Item

GET http://dev.dosomething.org:8888/api/v1/reportback-items/:id

Example request:

https://www.dosomething.org/api/v1/reportback-items/85071

Example response:

{
  data: {
    id: "85071",
    caption: "For a great cause!",
    uri: "https://www.dosomething.org/api/v1/reportback-items/85071",
    media: {
      uri: "https://dosomething-a.akamaihd.net/sites/default/files/styles/480x480/public/reportbacks/362/image.jpg",
      type: "image"
    },
    created_at: "1426110120",
    status: "approved",
    reportback: {
      id: "63344",
      created_at: "1425694214",
      updated_at: "1426697649",
      quantity: 151,
      why_participated: "So many clothes and other textiles go to waste every year because they are unwanted and too worn to go to Goodwill. This is a great way to get rid of those clothes and help out the environment too!",
      flagged: false
    },
    campaign: {
      id: "362",
      title: "Comeback Clothes"
    },
    user: {
      id: "1892717"
      first_name: "John",
      last_name: "Dow", 
      photo: "https://avatar.dosomething.org/uploads/avatars/55566327bffebc0b3e8b45a5.jpeg",
      country: "US"
    }
  }
}

Review a Reportback File

Only available to Users with view any reportback permissions.

POST https://www.dosomething.org/api/v1/reportback_files/[fid]/review

status: (string) required. The status to set on the Reportback File. Possible values: approved, promoted, excluded, flagged
flagged_reason: (string) If status is set to flagged, the reason why.
delete: (int) If status is set as flagged, sending a delete value of 1 will delete the Reportback File from the server.

System

Connection status

POST https://www.dosomething.org/api/v1/system/connect

Anonymous user

Example request:

curl https://www.dosomething.org/api/v1/system/connect -X POST --header "Content-type: application/json" --header "Accept: application/json"

Example response:

{
    "sessid": "3gX-K6doyyVopXe_NpXkFeEyzomTDJTkLgIzW22RXsc",
    "session_name": "SESS8de1794320df15914c40c2b37d51eff2",
    "user": {
        "uid": "0"
    }
}

Authenticated user

Example request:

curl https://www.dosomething.org/api/v1/system/connect -X POST --header "Content-type: application/json" --header "Accept: application/json" --header "X-CSRF-Token: -XmDawHfJ3MRBFGgBvHaF4_RlHq0Dp_xfffGimzr6mM" --header "Cookie: SESS8de1794320df15914c40c2b37d51eff2=OlRJjdQNZyYgxjmF7c0GtUSiO1pCczRCOzqetJJMs5w"

Example response:

{
    "sessid": "TBusFTgEF6-ihAE2VwxXSq-NaZr3hxX6A1fkrdwAc9g",
    "session_name": "SESS6fca668d7b440bf013b2728c61429728",
    "user": {
        "uid": "38",
        "name": "batman",
        "mail": "[email protected]",
        "theme": "",
        "signature": "",
        "signature_format": "plain_text",
        "created": "1392999246",
        "access": "1405601994",
        "login": "1405601911",
        "status": "1",
        "timezone": "UTC",
        "language": "",
        "picture": "0",
        "data": false,
        "uuid": "8a88c274-d4b4-4f66-b8b7-59029173248c",
        "sid": "KWB0uMKU5IyS2Xgw27v7wnhF9HKoVfJ23dFFt0r7o8s",
        "ssid": "",
        "hostname": "10.0.2.2",
        "timestamp": "1405601911",
        "cache": "0",
        "session": "",
        "roles": {
            "2": "authenticated user"
        }
    }
}

Set a variable

Must be authenticated as an administrator.

POST https://www.dosomething.org/api/v1/system/set_variable

name: (string) required. The name of the variable to set. value: (string) required. The value to set it to.

Example request:

curl http://dev.dosomething.org:8888/api/v1/system/set_variable -X POST --header "Content-type: application/json" --header "Accept: application/json" --header "X-CSRF-Token: G136HF5yB5ZZawvrsOfU4gw0poUOaQygPrsJlaFakMU" --header "Cookie:SESSd57f2aef87e6d4352ce5db4659184fa7=mKI5_yfoXYBz3r4o95utui4fwBV_lUO1JNN1nEVsPRg" -d '{"name": "dosomething_user_random_variable", "value": 5234232}'

Terms

List of terms

Currently only returns Cause terms. Available to public, but users with relevant access will see a Inbox Count.

GET https://www.dosomething.org/api/v1/terms

Retrieve Individual Term

GET https://www.dosomething.org/api/v1/taxonomy_term/[term_id]

Example

Request:

https://www.dosomething.org/api/v1/taxonomy_term/123

Response:

{
  tid: "123",
  vid: "5",
  name: "Sports",
  description: "",
  format: "markdown",
  weight: "0",
  uuid: "9fb331e7-e09e-4a98-8cae-0234e3855305",
  vocabulary_machine_name: "tags",
  metatags: [ ]
}

Get Term pending Reportback Files

Must have access to review reportbacks.

GET https://www.dosomething.org/api/v1/terms/:tid/inbox?count=1

Users

Find a user

Allows for finding a User uid by mobile or email. Only available to a logged in administrator.

GET https://www.dosomething.org/api/v1/users

parameters (array). Required. Possible keys:
- email (string)
- mobile (string)

Response: An array of Users (with only uid exposed). If no Users found, an empty array is returned.

Example URL:

http://staging.beta.dosomething.org/api/v1/users?parameters[mobile]=2125550001

Example response:

[
    {
        "uid": "5"
    }
]

Create a user

Currently available to anonymous users.

POST https://www.dosomething.org/api/v1/users

email: (string) required.
password: (string) This is the raw password that the user will use to login.
birthdate: (int) string. Expected format YYYY-MM-DD
first_name: (string)
last_name: (string)
mobile: (string)
user_registration_source (string) Used to indicate if an import or external app has created the User.

Response: The created User object.

Example request:

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json" -d '{"email":"[email protected]","password":"password","birthdate":"1995-12-31","first_name":"Aaroni","last_name":"Schachterelli","user_registration_source":"services"}' http://dev.dosomething.org:8888/api/v1/users

Example response:

{
    "mail": "[email protected]",
    "name": "[email protected]",
    "status": 1,
    "created": 1406642100,
    "pass": "$S$DjfasdfaQrls3ynt2asdfasdfve6dxyPURoosasdfasdfZGiFTxC6dxyPURoq7iY1yX3j",
    "field_birthdate": {
        "und": [{
            "value": "1995-12-31",
            "timezone": "UTC",
            "timezone_db": "UTC",
            "date_type": "datetime"
        }]
    },
    "field_first_name": {
        "und": [{
            "value": "Aaroni"
        }]
    },
    "field_last_name": {
        "und": [{
            "value": "Schachterelli"
        }]
    },
    "field_user_registration_source": {
        "und": [{
            "value": "services"
        }]
    },
    "uuid": "6b105ed7-e9c5-4946-a1e3-439e49af4ceb",
    "uid": "1700329",
    "theme": "",
    "signature": "",
    "access": 0,
    "login": 0,
    "language": "",
    "picture": 0,
    "init": "",
    "roles": {
        "2": "authenticated user"
    },
    "field_under_thirteen": {
        "und": [{
            "value": 0
        }]
    },
    "field_address": {
        "und": [{
            "element_key": "user|user|field_address|und|0",
            "thoroughfare": "",
            "premise": "",
            "locality": "",
            "administrative_area": "",
            "postal_code": "",
            "country": "US"
        }]
    }
}

Get member count

POST https://beta.dosomething.org/api/v1/users/get_member_count

Response:

    {
       "formatted": "2,900,343",
       "readable": "2.9 million"
    }

Get User activity

Returns signup and reportback data, if exists, for given uid and nid.

GET https://www.dosomething.org/api/v1/users/current/activity?nid=362

Response:

{
  sid: "1361",
  signed_up: "1422312631",
  source: null,
  rbid: "681",
  created: "1422046181",
  updated: "1422046181",
  quantity: "1",
  why_participated: "12",
  num_participants: null,
  flagged: "0",
  flagged_reason: null,
  fids: [
    "1881"
  ],
  node_title: "Comeback Clothes",
  noun: "Items",
  verb: "Recycled",
  quantity_label: "Items Recycled"
}

Get password reset URL

Only available to a logged in administrator.

Must include UID of the user

POST http://beta.dosomething.org/api/v1/users/[uid]/password_reset_url

Response:

[ 'http://dev.dosomething.org:8888/user/reset/1700226/1425495228/P-f-5d6kHLrOXl0VrQfXavgmMjiNz042uihpxJW4jBc' ]

Under Construction

Reportback retrieve

POST https://www.dosomething.org/api/v1/reportback/[rbid]

Check out the Engineering Blog!

Dev Environment

Building your local Environment
NFS
~~SSHFS~~ — Deprecated
Troubleshooting
Environment breaking changes
Troubleshooting your local

Development

Bender
Backend Development
Conventions
Solr information
DoSomething Profile
Contrib Modules
DoSomething Modules
- Campaign
- Campaign Group
- Global
- Payment
- Profile
- Signup
- Taxonomy
- Zendesk
- Customizations to be aware of
Fender
Front End Development
Forge Pattern Library
Testing
General information
Xdebug Guide
Vagrant
Disc performance benchmark
Vagrant and file sharing(SSHFS)
Documentation
Memorable pull requests
Documenting on this Wiki & in Code
2016 Product Wiki

Global

Product information
Faking your geo location
For local dev: Fastly header information and configuration
For everywhere else: VPN Server for Testing International Sites
Translations
Making content translatable
Localization Guidelines
Old International Setup Resources archive
Setting up international

External Systems

Deployments

Releases
Deployments Tech
[Deployment Process] (https://github.com/DoSomething/phoenix/wiki/Deployment-Process)
Code Testing Framework
Automated Testing

API

Authentication

User login

User logout

Get authentication token

Campaigns

Retrieve a campaign collection

Optional Query Parameters

Retrieve a specific campaign

Retrieve a campaign (will be deprecated)

Campaign signup

Campaign reportback

Signups

Retrieve a signup collection

Optional query parameters

Retrieve a specific signup

Create a kudos record

Required parameters

Kudos

Retrieve a kudos collection

Optional query parameters

Retrieve a specific kudos

Create a kudos record

Required parameters

Reportbacks

Retrieve a reportback collection

Optional Query Parameters

Retrieve a specific reportback

Reportback-Items

Retrieve a collection of Reportback Items

Optional query Parameters

Retrieve a specific Reportback Item

Review a Reportback File

System

Connection status

Anonymous user

Authenticated user

Set a variable

Terms

List of terms

Retrieve Individual Term

Example

Get Term pending Reportback Files

Users

Find a user

Create a user

Get member count

Get User activity

Get password reset URL

Under Construction

Reportback retrieve

Dev Environment

Development

Global

External Systems

Deployments

Usage Guides

External wiki's

Clone this wiki locally