API

The Web API is a new REST based interface to key parts of the TeamHaven Server business layer. It is available under the /api URL of a TeamHaven server. Eg: http://www.teamhaven.com/api.

Eventually it will be available via HTTPS as well, but currently it is not.

Authorisation

Authorisation is done using the standard HTTP Authorization header. There are two authorisation schemes, both of which use the same basic format for a set of TeamHaven credentials:

username/account:password

Typically, authorisation should be performed with HTTP Basic authorisation, using Base64 encoded TeamHaven credentials.

Authorization: Basic c3RvbnkvdGVzdDp0ZXJyaWVy

However, for debugging purposes, it is also possible to provide unencoded credentials using "TeamHaven" as the authentication scheme name rather than "Basic".

Authorization: TeamHaven username/account:password

In addition, a standard TeamHaven authentication cookie can also be used, so that if web pages on the TeamHaven website wish to use the WebAPI, they may do so without having to provide any authorisation information, as their requests will already contain the required cookie. This means it is possible to log into the TeamHaven website and review the output of any GET requests via a web browser, provided it can request and display XML or JSON output.

Content-Type

Request content must be UTF-8 encoded and presented as text/json or application/json.

Content-Type: application/json; charset=UTF-8

Status codes

2xx

Success

4xx

Something was wrong with your request. Check the Message property of the response for more information about what was wrong.

5xx

An exception prevented the server from processing your request, contact support@teamhaven.com for assistance.

API index

1. Collector API
2. Logging API
3. Auditing API
4. Checkin API
5. Search API
6. Localisation API
7. Stats API
8. Android API

---

Collector API

• Who am I?
• List calls
• Get a specific call
• Edit a call
• Get the questionnaire for a call
• Get the answers for a call
• Update the answers for a call
• List projects
• Get information about a specific project

Who am I?

GET /api/user

Gets information about the logged in user.

Query String Parameters

schema

true to include the User Attribute Schema in the response.

Projects

GET /api/user/projects

List all projects the user has access to

GET /api/user/project/:id

Gets information about the specified project.

URL parameters

id

The Project ID to retrieve.

Response

{
  ProjectID: 1,            // Project ID
  Name: "A test project",  // Project name
  CheckinMode: 0           // Checkin Mode: 0 = Off, 1 = Required
}

---

Logging API

GET /api/log

List all login sessions matching the specified criteria

Query String Parameters

severity

Return only login sessions with an error at least a severe as level N. The lower the severity number, the worse the issue. Levels 0-3 are actual errors, Levels 4-7 are warnings and debug messages.

user

Only return sessions associated with the specified User ID.

GET /api/log/:ticket

List individual log entries for the given login session.

---

Auditing API

The Audit Log tracks actions that have affected certain TeamHaven objects, providing an audit trail of who has modified them.

GET /api/audit/:type/:id

List actions that modified the specified object.

URL parameters

type

call for the call audit log

id

The TeamHaven ID of the object being audited. Ie, a Call ID when type=call

Response

[
  {
    Action: 1,                           // Enum value for the action performed
    Description: "/Actions/ImportCall",  // Localisation label describing the action
    Date: "2013-02-14T12:02:49.807",     // UTC timestamp of when the action was performed
    Count: 42,                           // The total number of objects that were affected by the action
    UserID: 2,                           // The User ID of the user who performed the action
    Username: "admin",                   // The Username of the user who performed the action
    DisplayName: "Administrator",        // The Display Name of the user who performed the action
  },
  {
    /* Next action */
  }
]

---

Checkin API

Checkins allow a user to send status updates about a specific call to the server without having to complete the call itself.

POST /api/user/calls/:id/checkins

Send a status update.

URL parameters

id

The Call ID that the user is sending a status update for

Body

{
  Type: 1,
  Date: '2013-02-01T14:49:40.223',
  LatLng: { Lat: 52.5, Lng: 0.2 },
  Message: 'Arrived at store'
}

Type

The type of checkin being posted:

• 1 Arrival - Marks the visit as "In progress"
• 2 Departure - Marks the visit as "Completed" (although the answers may not have been received yet)
• 3 Status update

Date

Optional UTC date and time of the checkin.

LatLng

An optional object giving the latitude and longitude of the user's current position.

Message

An optional message

GET /api/calls/:id/checkins

List the checkins made against the call.

DELETE /api/calls/:id/checkins

Delete all the user's checkins for the call.

---

Search API

GET /api/search?q=:term

Search for Calls, Targets and Users matching a simple search term. Any users whose Username or Displayname contains the term are returned, as are any Targets whose Name or Details containing the term.

Query String parameters

q

Search term. If numeric, then matching Call ID, Target ID and User IDs will also be returned.

Response

Calls: // An array of matching Calls, or null if no matches
[
  { CallID: 1, ProjectID: 2, ProjectName: "Demo project" }
],
Targets: // An array of matching Targets or null if no matches
[
  { TargetID: 5, Name: "Target 1", Details: "These are the target details", ProjectID: 5, ProjectName: "Demo project" }
],
Users: // An array of matching Users or null if no matches
[
  { UserID: 1, Username: "admin", DisplayName: "Administrator" }
],

---

Localisation API

GET /api/localisation/text/:culture/:path

Lists the localised text for a set of labels.

URL parameters

culture

An ISO 639-2 language code, eg enfor English, or fr for French.

path

Further parts of the path allow a subset of labels to be returned, eg /api/localisation/text/en/CallStatus will return the English translations of all labels beginning with /CallStatus.

Query String parameters

platform

An optional platform identifier that filters the results to just those flagged as required by the given platform:

• pocketpcWindows Mobile
• androidGoogle Android
• windows8Windows RT and Windows 8
• iosApple iOS

Stats API

The Stats API gives weekly call completion stats trended over the past 52 weeks.

GET /stats

Get completion statistics for the entire account.

GET /stats?project=:project

Get completion statistics for all calls in the specified project.

GET /stats?user=:user

Get completion statistics for all calls assigned to the specified user.

GET /stats?project=:project&user=:user

Gets completion statistics for all calls in the specified project assigned to the specified user.

URL Parameters

project

An optional filter, limiting results to calls in the project with the specified ProjectID.

user

An optional filter, limiting results to calls assigned to the specified UserID.

Response

The response is an array of 52 integers indicating the number of calls that were completed that week. The first element of the array is the oldest data (from 52 weeks ago), the last element is the most recent week's data.

Android API

The Android API provides TeamHaven Mobile for Android with specialised interface.

Latest version

GET /api/platforms/android/version

Returns information about the most recent version of TeamHaven Mobile for Android.

Response

{
  // Name of the platform
  Platform: "android",

  // Semantic version number of latest release
  Version: "2.0.0",

  // Date users on old versions must upgrade by
  UpgradeBy: "2013-02-01T14:49:40.223",

  // Localisation label of an upgrade notification
  UpgradeNotice: "/Android/UpgradeWarning",

  // Localisation label of a message to display once the UpgradeBy date has passed
  UpgradeError: "/Android/UpgradeError",

  // Url where the latest version can be downloaded from
  UpgradeUrl: "https://play.google.com/store/apps/details?id=com.teamhaven",

  // Url to the user guide
  UserGuideUrl: "https://dl.dropbox.com/s/slrxl22daquhdxh/TeamHaven%20Mobile%20for%20Android%20user%20guide.pdf"
}