API

From wiki.groundcrew.us

Groundcrew provides a beta Web API for organizing your squad. Currently, the only public methods revolve around managing your squad members. We will be adding more functionality and documentation in the coming months.

Contents 1 Overview 1.1 API Location 1.2 Authentication 1.3 Rate Limiting 1.4 Support 2 Available API Methods 2.1 Squad-Level Methods 3 Terminology 3.1 API Key 3.2 Squad 3.3 Person 3.4 Agent 3.5 Organizer 3.6 Leader

Overview

API Location

The Groundcrew API is accessed from:

 http://wwww.groundcrew.us/api

Authentication

Groundcrew uses a key to authenticate API calls for a particular organizational account. The key provides permissions for all methods -- there are currently no role-based permissions. Every API request must include the "api_key" token. To receive an API key for your organization, please contact api@citizenlogistics.com. Please keep this key secret.

Although we do not presently support HTTPS, in the future we will be recommending that all API calls be sent via SSL to ensure that all information, including the API key, is encrypted.

Rate Limiting

We do not currently enforce any rate limit for client API calls, but please be courteous and contact us at api@citizenlogistics.com if you plan to regularly issue more than 60 calls per minute.

Support

We welcome support and feedback to api@citizenlogistics.com. Please send us a detailed message if you are having trouble.

Available API Methods

Squad-Level Methods

All squad methods are relative to:

 http://wwww.groundcrew.us/api/squad/{squad_id}/

Managing squad members and leaders

get people data

• people: get details on one or more people
• people/ids: get a list of internal agent IDs
• people/signups: get a list of recent signups and invitations

post people data

• people/join: sign up an agent for a squad
• people/import: import bulk agent data, either creating new agents or updating existing agents
• people/invite: invite people by email address to become agents and optionally organizers in a squad

Terminology

API Key

A secret value that authenticates your API calls for your squad. The key is a large hexadecimal value (e.g. 42b7fb4184816a6f565f857368c3efb0) and is organizational account-specific. For more details, see Authentication.

Squad

A squad is a collection of agents tied together by an organization or a locality.

Person

A person is anyone associated with your squad, who may be an agent and may have organizer or leader permissions.

Agent

A squad agent has accepted placement in your squad. When agents are available and have a location, they appear in the Groundcrew Viewer and may be sent assignments.

There may be many people tied to your squad who are not classified as agents because they either do not have a geographic location (e.g. we only have an email address) or because they have not directly expressed interest in being an agent. Depending on each person's exact status you may be able to infrequently offer them assignments.

Organizer

An squad organizer is a member of your squad who may use the Groundcrew Viewer to organize agents around assignments.

Leader

A squad leader has full administrative control over a squad, and may: invite new agents; deputize new and existing agents as organizers; deputize organizers as additional squad leaders.