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/password:account

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 take any action, as their requests will already contain the required cookie. This means you can log into the TeamHaven website and review the output of any GET requests via your web browser, provided it can display XML or JSON output.

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

• Collector 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:

• 1Arrival
• 2Departure
• 3Status 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 posted for specific 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
• androidAndroid
• windows8Windows RT and Windows 8