Teamgage Customer API Guide

Teamgage Customer API Guide


The Teamgage Customer API can be used for :
  1. managing users (Eg. Create, Manage, Delete)
  2. managing reports* (Eg. Create, Manage, Delete)
  3. viewing a team's Huddle Dashboard, Comments & Timeline data
  4. viewing a team's Huddle Actions
*Within Teamgage platform, Reports are now referred to as Teams.

Getting Started

  1. Review this API guide (contact support@teamagge.com for any questions)
  2. Nominate a user to be granted API access. You may want to new create a dedicated user for this role.
  3. Advise support@teamagge.com which user(s) should be granted API access 
  4. Get building

Getting your API Key 

  1. Login to Teamgage
  2. On the far-right of the menu bar, click on Your Name , then Manage Account

  3. On the left menu, click on Manage, then API Key
  4. Click Show to see your API Key (Bearer Token)

    If you API key is blank, click Create to generate one.
Important: Your API key is like a password, so keep it safe and never share it with anyone. 

We recommend using secure configuration management practices when deploying applications which use it.

Getting your Organisation ID

  1. Login to Teamgage
  2. On the menu bar, click on Viewing , then Organisation List
  3. Find your organisation in the list, then note the ID value. 

Authenticating API Requests

All Teamgage API requests need to be authenticated by including:
  1. a request header bearer token (your API Key)
  2. a tenant ID provided in the JSON body (your Organisation ID)
Your bearer token is specific to your user account. Keep your bearer token secure as it contains sensitive information.

API access must be enabled on a per-user basis. To request API access please contact Teamgage support, providing the email address of the account you wish to use.

EXAMPLE REQUEST:
-H " Authorization :Bearer 460ba4e8e433g9c892e360d5346oec5"
{
      " tenantid ":1064,
      " criteria ":{ "__comment__":"Find all reports with a name containing the word ‘division’", "reportname_match":"division" }
}

User API Methods

List Users

HTTP METHOD:       POST
ENDPOINT:                /api/users/list
FUNCTION:               List organisation user records.
HEADER:                   A mandatory header token is required to authenticate the request.
FORMAT:                  JSON

PARAMETERS:
PARAMETER
REQUIREMENTS
TYPE
DESCRIPTION
tenantId
Required
integer
Teamgage internal organisation identifier
criteria
Required
<user object>


RETURNS :               A list of user objects matching the search criteria supplied in the request.
FORMAT:                  JSON

PARAMETER
TYPE
DESCRIPTION
response
string
Response status message
records
array <user object>
A list of user records matching the search criteria supplied in the request


EXAMPLE REQUEST:
-H " Authorization :Bearer 460ba4e8e433g9c892e360d5346oec5"
{
      " tenantid ":1064,
      " criteria ": {
            " __comment__ " : "Find all users with an email ending with ‘@division-companyname.com‘ who also have the tags HR & Sales",
            " email " : "@division-companyname.com",
            " structuraltags " : "HR|Sales"
      }
}

EXAMPLE RESPONSE:
{
      " response " : "true",
      " records " : [
            {
                  " firstname ":"Sofia", 
                  " lastname ":"Harris",
                  " email ":"s.harris@division-companyname.com",
                  " preferredname ":"",
                  " mobile ":"",
                  " active ":true,
                  " protected ":false,
                  " ai_otherid ":"aharr2682",
                  " structuraltags ":"Corporate|HR|International|Sales",
                  " communication ":"Email|SMS"
            },
            {
                  " firstname ":"Michel",
                  " lastname ":"Valls",
                  " email ":"m.valls@division-companyname.com",
                  " preferredname ":"",
                  " mobile ":"",
                  " active ":true,
                  " protected ":false,
                  " ai_otherid ":"mvall428",
                  " structuraltags ":"HR|Admin|Sales",
                  " communication ":"Email"
            }
      ]
}

Add or Update Users

HTTP METHOD:        POST
ENDPOINT:                /api/users/update
FUNCTION:                Add or update organisation user records.
HEADER:                      A mandatory header token is required to authenticate the request.
FORMAT:                     JSON

PARAMETERS:
PARAMETER
REQUIREMENTS
TYPE
DESCRIPTION
tenantId
Required
integer
 Teamgage internal organisation identifier
users
Required
array <user object>
directteamassignment
Updates :
optional
boolean
Tag Handling.

Values:
  1. false : (default) Users are assigned to teams indirectly using StructuralTags. "TagHandling" field is used
  2. true : Users are assigned to teams directly using TeamName. "TeamHandling" field is used.
taghandling
Updates :
optional
string
Tag handling determines how StructuralTags and DemographicTags fields are processed on each user record.

Values:
  1. OVERWRITE  : Tags specified for each user will replace all existing user tags
  2. ADD (default)  : Tags specified for each user will be added to the users existing tags
  3. SUBTRACT  : Tags specified for each user will be removed the users existing tags
teamhandling
Updates :
optional
string
Team handling determines how TeamName field is processed on each user record.

Acceptable values:
  1. OVERWRITE  : Teams specified for each user will replace all existing user  teams
  2. ADD (default)  : Teams specified for each user will be added to the users existing teams
  3.   SUBTRACT  : Teams specified for each user will be removed the users existing teams
deleteold
Optional
boolean
Delete all existing users which have not been specified in the import list. Users marked as protected will not be deleted even if they are not specified in the import list. The default value is False if omitted. Note: It is advised to only set the value to True if the full organisation user listing is supplied.
ReceiveSubmissionWelcome
Optional
boolean
Sets whether a user should receive a submission welcome communication with their next reminder schedule. If omitted, no changes to communications will occur.
ReceiveManagerWelcome
Optional
boolean
Sets whether a user should receive a manager welcome communication with their next reminder schedule. If omitted, no changes to communications will occur.
ReceiveFirstSubmission
Optional
boolean
Sets whether a user should receive a first submission welcome communication with their next reminder schedule. If omitted, no changes to communications will occur.

RETURNS : A success flag indicating if the request has been accepted and a response object

FORMAT : JSON
PARAMETER
TYPE
DESCRIPTION
success
boolean
Flag indicating the request has been accepted
response
<response object>
See response object definition for more details.


EXAMPLE REQUEST :
-H " Authorization :Bearer 460ba4e8e433g9c892e360d5346oec5"
{
      " tenantid ":1064,
      " users ":
            [ {
                  " __comment__ ":"Add a new user record to the system",
                  " firstname ":"Mithali",
                  " lastname ":"Sharma",
                  " email ":" m.sharma@companyname.com ",
                  " ai_otherid ":"mshar427",
                  " structuraltags ":"Engineering|International|Sales",
                  " communication ":"Email|SMS"
            },
            {
                  " __comment__ ":"Update the tags of the user matching the supplied email value",
                  " email ":" h.marsh@companyname.com ",
                  " structuraltags ":"Corporate|Services|HR"
            },
            {
                  " __comment__ ":"Update the tags of the user overriding the header tag handling",
                  " userid_match ": 2528,
                  " structuraltags ":"Services",
                  " taghandling ":"SUBTRACT"
            },
            {
                  " __comment__ ":"Update the users preferred name and otherid values matching on the supplied current otherid value",
                  " ai_otherid_match ":"arod1342",
                  " ai_otherid ":"arodge0011",
                  " preferredname ":"Sally"
            }
      ],
      " taghandling ":"ADD"
} 

EXAMPLE RESPONSE:
{
      " success ":true,
      " response ":
            {
                  " requestId ":176,
                  " message ":" https://teamgage.com/Portal/swf/BatchImports/Details/176"
            }
}

Delete Users

HTTP METHOD:        POST
ENDPOINT:                /api/users/delete
FUNCTION:             Delete organisation user records.
HEADER:                   A mandatory header token is required to authenticate the request.
FORMAT:                  JSON

PARAMETERS:
PARAMETER
REQUIREMENTS
TYPE
DESCRIPTION
tenantid
Required
integer
Teamgage internal organisation identifier.
users
Required
array <user del object>
A user deletion object, see definition below.

Acceptable parameters are:
  1. userid_match
  2. email_match
  3. ai_employeeid_match
  4. ai_sso_match
  5. ai_otherid_match
  6. ai_email_match

See order of precedence for lookup or alternative identifier values.

RETURNS : A success flag indicating if the request has been accepted and a response object.

FORMAT :  JSON
PARAMETER
TYPE
DESCRIPTION
successbooleanFlag indicating the request has been accepted
response<response object>See  response object  definition for more details.


EXAMPLE REQUEST:
-H "Authorization:Bearer 460ba4e8e433g9c892e360d5346oec5"
{
      "tenantid":1064,
      "users":[
            {
                  "__comment__":"User will be deleted only if the email, alternative otherid identifier & userid match the values",
                  "ai_otherid_match":"akett134",
                  "userid_match": 4231,
                  "email_match":" g.ketting@companyname.com "
            },
            {
                  "__comment__":"User will be deleted if the alternative otherid identifier matches the supplied value",
                  "ai_otherid_match":"apjil241"
            }
       }]
}

EXAMPLE RESPONSE:
{
      "success":true,
      "response": {
            "requestId":176,
      }
}

User Object Definition

FORMAT :      JSON
USAGE :         User record additions, modifications and user listings

PARAMETERS :
PARAMETER
REQUIREMENTS
TYPE
DESCRIPTION
firstname
Record Additions: required
Record Updates & Listings: optional
string
User's first name.
Max Length: 100
lastname
Record Additions: required
Record Updates & Listings: optional
string
User's last name.
Max Length: 100
email
Required
string
User's email address.
Max Length: 255
email_match
Record Updates & Listings: optional
string
Optional email lookup value for locating a user.
preferredname
Optional
string
User's preferred name.
Max Length: 100

Note : To clear all previously stored values, pass the singular key word 'NULLIFY'
mobile
Optional
string
User's mobile/contact number.
Max Length: 50

Note : To clear all previously stored values, pass the singular key word 'NULLIFY'
timezone
Record Additions & Updates: optional
string
A valid IANA time zone identifier to indicate the user's primary location. If omitted the organisation's time zone will be used.

Only canonical time zones are permitted.

Note : To clear all previously stored values, pass the singular key word 'NULLIFY'
structuraltags
Optional
Requires header: directteamassignment: false
string
Structural tag names to be associated with the user. Multiple tags should be split using the pipe '|' character.
demographictags
Optional
string
Demographic tag names to be associated with the user. Multiple tags should be split using the pipe ‘|’ character.
taghandling
Record Updates: optional
string
Tag handling.
If omitted the header taghandling value will be used.

Acceptable values:

  1. OVERWRITE  : Tags specified for each user will replace all existing user tags
  2. ADD  : Tags specified for each user will be added to the users existing tags
  3. SUBTRACT  : Tags specified for each user will be removed the users existing tags
teamname
Optional
Requires header:  directteamassignment: true
string
Team names to associated with the user. Multiple teams should be split using the pipe ‘|’ character. The user will be assigned all structural tags for each team specified.
teamhandling
Record Updates: optional
string
Tag handling. If omitted the header teamhandling value will be used.

Acceptable values:

  1. OVERWRITE  : Teams specified for each user will replace all existing user teams
  2. ADD  : Teams specified for each user will be added to the users existing teams
  3. SUBTRACT  : Teams specified for each user will be removed the users existing teams
communication
Record Additions & Updates: optional
string
Types of communication the user can receive.

Acceptable values:

  1. EMAIL (default): User will receive email communications
  2. SMS : User will receive SMS communications. The user must have a valid mobile number for SMS messages to be sent
communicationhandling
Record Updates: optional
string
Communication handling.

Acceptable values:

  1. OVERWRITE  : communications specified for each user will replace all existing user communications
  2. ADD  (  default  ): Communications specified for each user will be added to the users existing communications
  3. SUBTRACT  : Communications specified for each user will be removed the users existing communications
active
Record Additions & Updates: optional
boolean
Flag indicating if the user record is active. The default value is True if omitted.
userid_match
Record Updates: optional lookup value for locating the user by userid
integer
Teamgage internal user identifier.
ai_employeeid
Optional
string
Client internal employee alternative identifier.
Max length 100.

Note : When updating this field any previous values which are to be retained must be supplied again otherwise they will be removed when applying the supplied values. To clear all previously stored values pass the singular key word 'NULLIFY'.
ai_employeeid_match
Record Updates: optional
string
Optional client internal employee alternative identifier lookup value for locating a user. 
ai_otherid
Optional
string
Client internal employee other alternative identifier.
Max length 100.

Note : When updating this field any previous values which are to be retained must be supplied again otherwise they will be removed when applying the supplied values. To clear all previously stored values pass the singular key word 'NULLIFY'.
ai_otherid_match
 Record Updates: optional
string
Optional client internal other alternative identifier lookup value for locating a user.
ai_email
Optional
string
Client internal employee email alternative identifier.
Max length 100.

Note : When updating this field any previous values which are to be retained must be supplied again otherwise they will be removed when applying the supplied values. To clear all previously stored values pass the singular key word 'NULLIFY'
ai_email_match
Record Updates: optional 
string
Optional client internal email alternative identifier lookup value for locating a user.
ai_sso
Optional
string
Client internal employee single sign-on alternative identifier. Max length 100. Note: When updating this field any previous values which are to be retained must be supplied again otherwise they will be removed when applying the supplied values. To clear all previously stored values pass the singular key word 'NULLIFY'
ai_sso_match
Record Updates: optional 
string
Optional client internal single sign-on alternative identifier lookup value for locating a user.
protected
Record Additions & Updates: optional
boolean
Flag to indicate whether the user should be protected from auto deletion when processing old users.

Default value is False if omitted.
usessubmissioncard
Optional
Requires Organisation to have Submission Cards feature enabled 
boolean
Flag to indicate whether user can use a Submission Card for their Teamgage Submission.

If omitted, user flag is left unchanged.
submissioncardid
Optional
Requires Organisation to have Submission Cards feature enabled
Requires user to have usessubmissioncard flag (above) set to true 
integer
Sequence number of Submission Card allocated to user for their Teamgage Submission.

If omitted, allocated card is left unchanged.
Note: REQUIREMENTS actions not listed are 'not applicable'


User Deletion Object Definition

FORMAT :            JSON
USAGE :               User record deletions
PARAMETERS :   
PARAMETER
REQUIREMENTS
TYPE
DESCRIPTION
userid_match
Required only if all other fields have been omitted.
integer
Lookup value for locating the user by the Teamgage internal user identifier.
email_match
Optional
string
Lookup value for locating the user by email.
ai_employeeid_match
Optional
string
Lookup value for locating the user by the client internal employee alternative identifier. 
ai_otherid_match
Optional
string
Lookup value for locating the user by the client other alternative identifier. 
ai_email_match
Optional
string
Lookup value for locating the user by the client email alternative identifier.
ai_sso_match
Optional
string
Lookup value for locating the user by the client single sign-on alternative identifier. 


Report API Methods

List Reports

HTTP METHOD :     POST
ENDPOINT :             /api/reports/list
FUNCTION :             List organisation reports.
HEADER :                  A mandatory header token is required to authenticate the request.
FORMAT :                 JSON

PARAMETERS:
PARAMETER
REQUIREMENTS
TYPE
DESCRIPTION
tenantid
Required
integer
Teamgage internal organisation identifier. 
criteria
Required
<report object>

RETURNS : A list of report objects matching the search criteria supplied in the request.

FORMAT : JSON
PARAMETER 
TYPE
DESCRIPTION
response
string
Response status message.
records
array <report object>
A list of reports matching the search criteria supplied in the request.


EXAMPLE REQUEST:
-H " Authorization :Bearer 460ba4e8e433g9c892e360d5346oec5"
{
      " tenantid ":1064,
      " criteria ": {
            " __comment__ ":"Find all reports with a name containing ‘organisation’ ",
            " reportname_match ":"organisation"
      }
}

EXAMPLE RESPONSE:
{
       " response ":"true",
       " records ":[ {
              " reportname ":"Entire Organisation",
              " structuraltags ":"Entire Organisation",
              " metricsetid ": 45,
              " managerwelcomeid ": 273,
              " managerpromptid": 274
       },
       {
              " reportname ":"Entire Organisation > Corporate",
              " structuraltags ":"Entire Organisation | Corporate",
              " metricsetid ": null,
              " managerwelcomeid ": null,
              " managerpromptid": null
       },
       {
              " __comment__ ": "Different metric set and templates",
              " reportname ":"Entire Organisation > Engineering",
              " structuraltags ":"Entire Organisation | Engineering",
              " metricsetid ": 47,
              " managerwelcomeid ": 185,
              " managerpromptid": 186
       } ]
} 

Add or Update Reports

HTTP METHOD :     POST
ENDPOINT :             /api/reports/update
FUNCTION :             Add or update organisation reports.
HEADER :                  A mandatory header token is required to authenticate the request.
FORMAT :                 JSON

PARAMETERS:
PARAMETER
REQUIREMENTS
TYPE
DESCRIPTION
tenantId
Required
integer
Teamgage internal organisation identifier.
reports
Required
<report object>
taghandling
Record Updates: optional
string
T ag handling.

Acceptable values:
  1. OVERWRITE  : Tags specified for each report will replace all current report tags
  2. ADD  (  default  ): Tags specified for each report will be added to the reports current tags
  3. SUBTRACT  : Tags specified for each report will be removed from the reports current tags

deleteold
Optional
boolean
Delete all existing reports which have not been specified in the import list. Reports marked as protected will not be deleted even if they are not specified in the import list.

The default value is  False  if omitted.
Note  : It is advised to only set the value to True if the full organisation report listing is supplied.
Note: REQUIREMENTS actions not listed are 'not applicable'

RETURNS : A success flag indicating if the request has been accepted and a response object.

FORMAT : JSON

PARAMETER
TYPE
DESCRIPTION
success
boolean
Flag indicating if the request has been accepted
response
<response object>
See response object definition for more details.


EXAMPLE REQUEST:
-H " Authorization :Bearer 460ba4e8e433g9c892e360d5346oec5"
{
      " tenantid ":1064,
      " reports ":[
                  {
                        " __comment__ ":"Add a new report to the system",
                        " reportname ":"Engineering Sales Report",
                        " metricsetid ": "45",
                        " structuraltags ":"Engineering|International|Sales",
                        " managerwelcomeid ": "87",
                        " managerpromptid": "91"
                  },
                  {
                        " __comment__ ":"Locate a report using the current name value and update the name, metric set, and template ID",
                        " reportname_match ":"Corporate Report Q2",
                        " reportname ":"Corporate Report Quarter 2",
                        " metricsetid ": "43",
                        " managerwelcomeid ": "87",
                        " managerpromptid": "91"
                  },
                  {
                        " __comment__ ":"Update a reports metric set and tags values. Overriding the header tag handling",
                        " metricsetid ": "43",
                     " reportname_match ": "Corporate Offshore Report",
                        " tags ":"Corporate|Offshore",
                        " reportid_match ": "23",
                        " taghandling ":"SUBTRACT"
              }
       ],
       " taghandling ":"ADD"
}


EXAMPLE RESPONSE:
{
       " success ":true,
       " response ":  {
              " requestId ":194,
       }
}

Delete Reports

HTTP METHOD :     POST
ENDPOINT :             /api/reports/delete
FUNCTION :             Delete organisation report.
HEADER :                  A mandatory header token is required to authenticate the request.
FORMAT :                 JSON

PARAMETERS:
PARAMETERS
REQUIREMENTS
TYPE
DESCRIPTION
tenantId
Required
integer
Teamgage internal organisation identifier.
reports
Required
<report object>
A report deletion object, see definition below.

Acceptable parameters are:
  1. reportid_match
  2. reportname_match

See order of precedence for lookup values

RETURNS : A success flag indicating if the request has been accepted and a response object.

FORMAT : JSON

PARAMETER
TYPE
DESCRIPTION
success
boolean
Flag indicating if the request has been accepted. 
response
<response object>
See response object definition for more details.


EXAMPLE REQUEST:
-H " Authorization :Bearer 460ba4e8e433g9c892e360d5346oec5"
{
      " tenantid ":1064,
      " reports ":[ {
            " __comment__ ":"Report will be deleted only if the reportname matches the supplied value",
            " reportname_match ":"Finance Sales Report"
      } ]
} 


EXAMPLE RESPONSE:
{
      " success ":true,
      " response ":{ 
            " requestId ":197,
      }
}


Report Results

HTTP METHOD :     POST
ENDPOINT :             /api/reports/results
FUNCTION :             Get report data.
HEADER :                  A mandatory header token is required to authenticate the request.
FORMAT :                 JSON

PARAMETERS:
PARAMETER
REQUIREMENTS
TYPE
DESCRIPTION
tenantid
Required
integer
Teamgage internal organisation identifier.
criteria
Required
<results object>
See report results object definition below.

RETURNS : An export data object matching the report criteria supplied in the request.

FORMAT : JSON

PARAMETER
TYPE
DESCRIPTION
response
string
Response status message.
resultdata
<results>
A results data object matching the report criteria supplied in the request


EXAMPLE REQUEST:
-H " Authorization :Bearer 460ba4e8e433g9c892e360d5346oec5"
{
    " tenantid ": 1064,
    " criteria ":
    {
        " __comment__": "dashboard snapshot based on the last submission for each team member leading up to 25th January 2018",
        " resulttype ": "Snapshot",
        " reportname_match ": "division",
        " startdate ": "2024-03-01 00:00:00Z",
        " enddate ": "2024-04-01 00:00:00Z",
        " withdata ": "both"
    }
}

EXAMPLE RESPONSE:
{
    " response ": "true",
    " resultdata ":
    {
        " memberactivity ":
        {
            " possiblerespondents ": 27,
            " actualresponses ": 25,
            " respondentpercentage ": 92.6
        },
        " snapshotData ":
        [
            {
                " metric ": "Empowered",
                " value ": 59,
                " uniqueusersubmissions ": 25,
                " spread1 ": 12,
                " spread2 ": 0,
                " spread3 ": 3.9,
                " spread4 ": 0,
                " spread5 ": 8.1,
                " spread6 ": 28,
                " spread7 ": 8.1,
                " spread8 ": 16,
                " spread9 ": 3.9,
                " spread10 ": 19.9
            }
        ],
        [
            {
                " __comment__": "The best onboarding process I have had and I really appreciate all the materials that have been produced for me.",
                " metric ": "Communication",
                " month ": "March",
                " year ": 2024
            }
        ]
    }
}

Report Object Definition

FORMAT :          JSON
USAGE :             Report record additions & modifications, and report listings

PARAMETERS : 
PARAMETER
REQUIRMENTS
TYPE
DESCRIPTION
reportname
Record Additions:
required

Record Listings & Updates:
optional
string
Name of the report.
Max length 500.
reportname_match
Record Listings & Updates:
optional 
string
Optional reportname lookup value for locating a report. 
reporttype
Required
string
Indicates the type of report:
  1. Structural : Can send reminders. Use these to model your organisation structure.
  2. Analysis : Can filter by Demographic Tags.
Use these to analyse employee demographics.
Default : Structural
metricsetid
Record Additions:
required

Record Updates & Listings:
optional
integer?
The metric set ID, or null if inherited from the parent report.
structuraltagsinclude
Optional
string
Tag names to determine which users are included in the report results. Multiple tags should be split using the pipe ‘|’ character.
structuraltagsexclude
Optional
string
Tag names to determine which users are excluded from the report results. Multiple tags should be split using the pipe ‘|’ character.
structuraltaghandling
Record Updates:
optional
string
Tag handling.
If omitted the header taghandling value will be used.

Acceptable values:
  1. OVERWRITE  : Tags specified for each report will replace all current report tags
  2. ADD  : Tags specified for each report will be added to the reports current tags
  3. SUBTRACT  : Tags specified for each report will be removed from the reports current tags
demographictagsinclude 
Optional
string
Tag names to determine which users are included in the report results. Multiple tags should be split using the pipe ‘|’ character.
demographictagsexclude
Optional
string
Tag names to determine which users are excluded from the report results. Multiple tags should be split using the pipe ‘|’ character. 
demographictaghandling
 Record Updates:
optional
string
Tag handling.
If omitted the header taghandling value will be used.

Acceptable values:
  1. OVERWRITE  : Tags specified for each report will replace all current report tags
  2. ADD  : Tags specified for each report will be added to the reports current tags
  3. SUBTRACT  : Tags specified for each report will be removed from the reports current tags
blocksubmissionreminderinheritance
Required
string
Specifies whether a report should prevent/block members from receiving scheduled submission reminders from above reports:
 
  1. Inherited : Team members will receive submission reminders according to schedules configured on above reports.
  2. B locked : Team members will only receive submission reminder from schedules configured on this report or below.

Default : Inherited
userwelcomeid
Optional for all, only valid for Structural reports with BlockSubmissionInheritance 
integer?
Teamgage email template ID for the submission welcome email.

Note : Email reminders will only be sent if a submission reminder schedule is configured and email template identifiers are set.
usersubmissionnotificationid
Optional for all, only valid for Structural reports with BlockSubmissionInheritance
integer?
Teamgage email template ID for the submission reminder email.
userfirstsubmissionthankyouid
Teamgage email template ID for the first-submission “Thank You” email.
integer?
Teamgage email template ID for the first-submission “Thank You” email.
blockmanagerreminderinheritance
Required
string
Specifies whether a report should prevent/block managers from receiving scheduled manager reminders from above reports:

  1. Inherited : Managers will receive results reminders according to schedules configured on above reports.
  2. Blocked : Managers will only receive results reminder from schedules configured on this report or below.
Default : Inherited
managerwelcomeid
Optional for all, only valid for Structural reports with BlockManagerInheritance 
integer?
Teamgage email template ID for the manager welcome email.

Note : Email reminders will only be sent if a manager reminder schedule is configured and email template identifiers are set.
managerpromptid
Optional for all, only valid for Structural reports with BlockManagerInheritance 
integer?
Teamgage email template ID for the manager reminder email.
reportid_match
Record Updates & Listings:
optional
string
Optional internal report identifier lookup value for locating a report.
protected
Record Additions & Updates: optional
boolean
Flag to indicate whether the report should be protected from auto deletion when processing old reports.

Default :  False
parentreportid

integer


Note: REQUIREMENTS actions not listed are 'not applicable'

Report Results Object Definition

FORMAT :          JSON
USAGE :             Report record additions & modifications, and report listings

PARAMETERS : 
PARAMETER
REQUIREMENTS
TYPE
DESCRIPTION
reportname_match
Required lookup value only if the reportid_match parameter have been omitted 
string
Name of the report.
Max length 500.
reportid_match
Optional
integer
Teamgage internal report identifier
resulttype
Required
string
Type of report result to export.

Acceptable values:
  1. Snapshot  : single date.
  2. Timeline  : data series sampled between two dates.

Default : Snapshot
withdata
Required
string
Type of data to return.

Acceptable values:
  1. VALUES  (  default  ): Only result values will be returned
  2. COMMENTS  : Only result comments will be returned
  3. BOTH  : Both result values and comments will be returned format.
Default : VALUES 
startdate
Required
ISO 8601 date string
Start datetime for the range of results to calculate. The date supplied must be in ISO 8601 format. Datetimes are interpreted as UTC.
enddate
Required
ISO 8601 date string
End datetime for the range of results to calculate. The date supplied must be in ISO 8601 format. Datetimes are interpreted as UTC.
comparisonStartDate
Optional (for snapshot only)
ISO 8601 date string
Start datetime for the range of results to compare the primary date range to. The date supplied must be in ISO 8601 format. Datetimes are interpreted as UTC.

comparisonEndDate
Optional (for snapshot only)
ISO 8601 date string
Start datetime for the range of results to compare the primary date range to. The date supplied must be in ISO 8601 format. Datetimes are interpreted as UTC.
tagfilters
Optional
string
Tag filter with which to further restrict the report data. Multiple tags should be split using the pipe ‘|’ character. 


Report Deletion Object Definition

FORMAT :          JSON
USAGE :             Report record deletions

PARAMETERS : 
PARAMETER
REQUIREMENTS
TYPE
DESCRIPTION
reportname_match
Required only if all other fields have been omitted.
string
Lookup value for locating the report by reportname .
reportid_match
Optional
integer
Lookup value for locating the report by the Teamgage internal report identifier.


Report Manager API Methods

List Report Managers

HTTP METHOD :     POST
ENDPOINT :             /api/reportmanagers/list
FUNCTION :              List organisation report managers.
HEADER :                  A mandatory header token is required to authenticate the request.
FORMAT :                 JSON

PARAMETERS:
PARAMETERREQUIREMENTSTYPEDESCRIPTION
tenantid
RequiredintegerTeamgage internal organisation identifier.
criteria
Requireduser objectSee manager object definition below.


RETURNS : A list of manager objects matching the search criteria supplied in the request.

FORMAT : JSON

PARAMETERTYPEDESCRIPTION
responsestringResponse status message.
recordsarray <manager object>A list of manager records matching the search criteria supplied in the request.



EXAMPLE REQUEST:

-H " Authorization :Bearer 460ba4e8e433g9c892e360d5346oec5"
{
    " tenantid ": 1064,
    " criteria ":
    {
        " __comment__ ": "Find all managers associated with the supplied report name",
        " reportname ": "Sales Eastern Division"
    }
}

EXAMPLE RESPONSE:
{
    " response ": "true",
    " records ":
    [
        {
            " reportname ": "Sales Eastern Division",
            " reportid ": 205,
            " managerid ": 791,
            " manager_ai_otherid ": "abutl734",
            " manageremail ": "a.butlering@division-companyname.com",
            " protected ": false,
            " apionly ": false,
            " withnotifications ": true,
            " withchildren ": true,
            " withsubfiltering ": false
        },
        {
            " reportname ": "Sales Eastern Division",
            " reportid ": 205,
            " managerid ": 492,
            " manageremail ": " e.macron@companyname.com ",
            " protected ": false,
            " apionly ": false,
            " withnotifications ": true,
            " withchildren ": true,
            " withsubfiltering ": false
        },
        {
            " reportname ": "Sales Eastern Division",
            " reportid ": 205,
            " managerid ": 782,
            " manager_ai_otherid ": "jmel271",
            " manageremail ": "j.melenchon@division-companyname.com",
            " protected ": false,
            " apionly ": false,
            " withnotifications ": true,
            " withchildren ": true,
            " withsubfiltering ": false
        }
    ]
}



Add or Update Report Managers

HTTP METHOD :     POST
ENDPOINT :             /api/reportmanagers/update
FUNCTION :              Add or update organisation report managers.
HEADER :                  A mandatory header token is required to authenticate the request.
FORMAT :                 JSON

PARAMETERS:
PARAMETER
REQUIRMENTS
TYPE
DESCRIPTION
tenantid 
Required
integer
Teamgage internal organisation identifier.
managers
Required
<manager object>
flaghandling
Record Updates: optional 
string
Flag handling.

Acceptable values:
  1. OVERWRITE  : Flags specified for each report manager will replace all current report managers flags
  2. ADD   (default): Flags specified for each report manager will be added to the report mangers current flags
  3. SUBTRACT  : Flags specified for each report manager will be removed from the report managers current flags
deleteold
Optional
boolean
Delete all existing report managers which have not been specified in the import list.
Report managers marked as protected will not be deleted even if they are not specified in the import list.

The default value is FALSE  if omitted.

Note : It is advised to only set the value to True if the full organisation report manager listing is supplied. 

RETURNS :       A success flag indicating if the request has been accepted and a response object.
FORMAT :       JSON 

PARAMETER
TYPE
DESCRIPTION
success
boolean
Flag indicating if the request has been accepted.
response
<response object>
See response object definition for more details.


EXAMPLE REQUEST:
-H " Authorization :Bearer 460ba4e8e433g9c892e360d5346oec5"  
{
    " tenantid ": 1064,
    " managers ":
    [
        {
            " __comment__ ": "Add a new manager to the report matching the report name, with the notification flags Subfilter & Notify",
            " reportname ": "Engineering Sales Report",
            " flags ": "SUBFILTER|NOTIFY",
            " email ": " b.southers@companyname.com "
        },
        {
            " __comment__ ": "Update the notification flag for all uses matching the current report Engineering Sales Report",
            " reportname ": "Engineering Sales Report",
            " flags ": "SUBTEAMS"
        }
    ]
}

EXAMPLE RESPONSE:
{
    " success ": true,
    " response ":
    {
        " requestId ": 283,
    }
}


Delete Report Managers

HTTP METHOD :     POST
ENDPOINT :             /api/reportmanagers/delete
FUNCTION :              Add or update organisation report managers.
HEADER :                  A mandatory header token is required to authenticate the request.
FORMAT :                 JSON

PARAMETERS:
PARAMETERREQUIRMENTSTYPEDESCRIPTION
tenantid RequiredintegerTeamgage internal organisation identifier.
managersRequired<manager object>
A manager deletion object, see definition below.

If more than one parameter is supplied, all values must match the manager record for that record to be deleted.

RETURNS :       A success flag indicating if the request has been accepted and a response object.
FORMAT :       JSON

PARAMETERTYPEDESCRIPTION
successbooleanFlag indicating if the request has been accepted.
response<response object>See response object definition for more details.


EXAMPLE REQUEST:
-H " Authorization :Bearer 460ba4e8e433g9c892e360d5346oec5"  
{
    " tenantid ": 1064,
    " managers ":
    [
        {
            " __comment__ ": "Manager will be removed from all reports where the email matches",
            " email ": " b.singh@companyname.com "
        },
        {
            " __comment__ ": "Manager will only be removed from the report if the reportname & email match",
            " reportname ": "Corporate Report",
            " email ": " t.bianchi@companyname.com "
        },
        {
            " __comment__ ": "All managers will only be removed from the report matching the reportotherid",
            " reportid ": 587
        }
    ]
}

EXAMPLE RESPONSE:
{
    " success ": true,
    " response ":
    {
        " requestId ": 233,
    }
}

Manager Object Definition

FORMAT :    JSON
USAGE :       Report manager record additions & modifications, and report manager listings

PARAMETERS :
PARAMETER
REQUIREMENTS
TYPE
DESCRIPTION
reportname
Record Additions:
required only if reportid has been omitted.

Record Updates & Listings:
optional lookup value for locating reports by report name.
string
Name of the report to assign the manager to. Max length 500.
reportid
Optional
integer
Teamgage internal report identifier.
flags
Record Additions & Updates:
required 
string
Notification flags. Multiple flags should be split using the pipe ‘|’ character.

Acceptable values:

  1. SUBFILTER : Users may apply further filters to the report results
  2. NOTIFY : Users will be sent Manager Reminder and Manager Welcome emails according to the reminder schedule of the report.
  3. SUBTEAMS : Users will be set as a manager of reports for all sub-teams starting from the current level and below. 
      
flaghandling
Record Additions & Updates:
optional
string
Flag handling. If omitted the header flaghandling value will be used.

Acceptable values:

  1. OVERWRITE : Flags specified for each report manager will replace all current report managers flags
  2. ADD : Flags specified for each report manager will be added to the report mangers current flags
  3. SUBTRACT : Flags specified for each report manager will be removed from the report managers current flags
email
Record Additions:
required only if all other user identifiers have been omitted.

Record Updates & Listings:
optional
string
Users email address. Max length 255.
managerid
Optional
integer
Teamgage internal user identifier.
ai_employeeid
Optional
string
Client internal employee alternative identifier lookup value for locating a user.
ai_otherid
Optional
string
Client internal other alternative identifier lookup value for locating a user.
ai_email
Optional
string
Client internal email alternative identifier lookup value for locating a user.
ai_sso
Optional
string
Client internal single sign-on alternative identifier lookup value for locating a user.
protected
Record Additions & Updates:
optional
boolean
Flag to indicate whether the report manager should be protected from auto deletion when processing old report managers.

Default value is False if omitted. 
Note: REQUIREMENTS not listed are 'not applicable'


Action API Methods

List Actions

HTTP METHOD :     POST
ENDPOINT :             /api/reports/actions
FUNCTION :              List all actions for a particular team.
HEADER :                  A mandatory header token is required to authenticate the request.
FORMAT :                 JSON

PARAMETERS:
PARAMETERREQUIREMENTSTYPEDESCRIPTION
tenantid
RequiredintegerTeamgage internal organisation identifier.
criteria
RequiredAction Criteria (see below)An object which can be provided to filter search results.

RETURNS : A list of manager objects matching the search criteria supplied in the request.

FORMAT : JSON

PARAMETERTYPEDESCRIPTION
responsestringResponse status message.
recordsarray <Action object> (see below)A list of actions matching the search criteria supplied in the request.


EXAMPLE REQUEST:
-H " Authorization :Bearer 460ba4e8e433g9c892e360d5346oec5" 
{
    "tenantid": 1064,
    "criteria":
    {
        "status": "incomplete"
    }
}

EXAMPLE RESPONSE:
{
    " response ": "true",
    " records ":
    [
        {
            " ActionId ": 146,
            " ActionText ": "Start doing daily standups",
            " ReportId ": 3259,
            " ReportName ": "Entire Organisation",
            " MetricId ": null,
            " MetricName ": "General",
            " DateTimeCreated ": "2020-11-02T23:44:13.013",
            " DateTimeCompleted ": null,
            " DueDate ": null,
            " AssignedToName ": "Jake Lepping",
            " AssignedToEmail ": " jake.lepping@example.com ",
            " Assignees ":
            [
                {
                    " name ": "Jake Lepping",
                    " email ": " jake.lepping@example.com "
                },
                {
                    " name ": "Anthea Apple",
                    " email ": " anthea.apple@example.com "
                }
            ],
            " AssignedByName ": "Mary Smith",
            "AssignedByEmail": " mary.smith@example.com ",
            " Status ": "Incomplete"
        },
        {
            " ActionId ": 147,
            " ActionText ": "Meet with client X to discuss new features",
            " ReportId ": 3260,
            " ReportName ": "Entire Organisation > London",
            " MetricId ": 431,
            " MetricName ": "Customer Outcomes",
            " DateTimeCreated ": "2020-11-02T23:44:21.533",
            " DateTimeCompleted ": null,
            " DueDate ": "2020-12-01",
            " AssignedToName ": "Emily Young",
            " AssignedToEmail ": " emily.young@example.com ",
            " Assignees ":
            [
                {
                    " name ": "Emily Young",
                    " email ": " emily.young@example.com "
                }
            ],
            " AssignedByName ": "David Cotting",
            " AssignedByEmail ": " david.cotting@example.com ",
            " Status ": "Incomplete"
        }
    ]
}


Action Criteria Object Definition

FORMAT :      JSON
FIELDS :
PARAMETER
REQUIRMENTS
TYPE
DESCRIPTION
searchPhrase
Optional
string
Search phrase to filter by. Will filter results to only include actions which have either a description or an assignee matching the provided phrase.
dateTimeCreatedFrom
Optional
ISO8601 date-string
If provided, only actions created after the date will be returned
dateTimeCreatedTo
Optional
ISO8601 date-string
If provided, only actions created before the date will be created
status
Optional
string
Acceptable values:
        • complete
        • incomplete

If “ complete ”, only completed actions will be returned and vice versa for “incomplete”. If not provided, actions of all status types are returned.
reportIds
Optional
string
A comma-separated list of report IDs to filter the actions to (e.g. “1013,1014,1025”) 
includeChildReportIds
Optional
boolean
Only has an effect if the reportIds parameter is also used.

If true , actions from child-teams of the provided reportIds will also be included in the result. Defaults to false.
metricIds
Optional
string
A comma-separated list of metric IDs to filter the actions to (e.g. “523,567,704”) 


Action Object Definition

FORMAT :      JSON
FIELDS :
PARAMETER
REQUIREMENTS
TYPE
DESCRIPTION
actionId
Required
integer
Unique ID of the action
actionText
Required
string
Text describing what the action is
reportId
Required
integer
ID of the report the action was made from
reportName
Required
string
Name of the report the action was made from
metricId
Required
integer
ID of the metric the action was linked to.
metricName
Required
string
Name of the metric the action was linked to. 
dateTimeCreated
Required
ISO8601 date string
DateTime the action was created at.
dateTimeCompleted
Optional
ISO8601 date string
DateTime the action was completed, or null if it is incomplete.
dueDate
Optional
ISO8601 date string
Due date for the action, or null if it does not have a due date
assignedToName (legacy, use assignees instead) 
Required
string
Name of the first assignee.
assignedToEmail (legacy, used assignees instead) 
Required
string
Email of the first assignee.
assignees
Required
array of ActionAssignees (See below)
List of the current assignees.
assignedByName
Required
string
Name of the user who most recently edited the action’s assignees.
assignedByEmail
Required
string
Email of the user who most recently edited the action’s assignees. 
status
Required
string
Current status of the action, may be “Complete” or “Incomplete”


ActionAssignee object definition

FORMAT :      JSON

FIELDS :
PARAMETER
TYPE
DESCRIPTION
name
string
Name of the assignee.
email
string
Email of the assignee


Request API Methods

Status

HTTP METHOD :     POST
ENDPOINT :             /api/request/status
FUNCTION :             Processing status of a request.
HEADER :                  A mandatory header token is required to authenticate the request.
FORMAT :                 JSON

PARAMETERS:
PARAMETERREQUIREMENTSTYPEDESCRIPTION
tenantid
RequiredintegerTeamgage internal organisation identifier.
requestidRequiredintegerThe Teamgage internal identifier of the API request.

RETURNS : A success flag indicating if the request has been accepted and a response object.

FORMAT : JSON

PARAMETERTYPEDESCRIPTION
responsestringReturns “ true “ if it is a valid request or an error message indicating why the request failed.
status<status object>See status object definition for more details. If the request failed a null object will be returned.

EXAMPLE REQUEST:
-H " Authorization :Bearer 460ba4e8e433g9c892e360d5346oec5"
{
      " tenantid ":1064,
      " requestid ":242
}  

EXAMPLE RESPONSE:
{
    " response ": "true",
    " status ":
    {
        " id ": 242,
        " name ": "Update Users – API Request 2017-11-05",
        " createddatetime ": "2017-11-05 10:05:57 AM",
        " status ": "Succeeded",
        " progress ": "100%",
        " notes ": "Row 3 excluded – Users email is not in the correct format."
    }
}

Status Object Definition

FORMAT :   JSON
USAGE :      Request processing status

PARAMETERS :
PARAMETER
TYPE
DESCRIPTION
id
integer
The Teamgage internal identifier of the API request. 
name
string
The name of the API request.
createddatetime
string
The date and time the API request was created.
status
string
Descriptive status of the request.

Possible responses are:
  1. Not Started
  2. Running
  3. Succeeded
  4. Failed
  5. Paused
progress
string
The current completion percentage of the request
notes
string
Any warnings or errors generated during the request processing

Appendix

Response Object Definition

Each Add/Update/Delete request will result in a response object.
The requestid returned in the response object can be used by the Request Status call to return the current status of the request process.

FORMAT :          JSON
USAGE :              API request response


PARAMETERS :
PARAMETER
TYPE
DESCRIPTION
requestid
integer
The unique identifier for the request which can be used when calling the Request Status. If the request was unsuccessful the requestid will be zero.
message
string
If the request has been successful a unique URL will be returned linking to the import process results. Otherwise a message indicating why the import failed will be returned

Order of Precedence for Locating Users

The following order of precedence will be used for locating user records by supplied lookup or alternative identifier values.
  1. UserID_Match
  2. AI_EmployeeID_Match 
  3. Email_Match 
  4. AI_SSO_Match
  5. AI_OtherID_Match 
  6. AI_Email_Match 
  7. AI_EmployeeID 
  8. Email 
  9. AI_SSO 
  10. AI_OtherID 
  11. AI_Email


Order of Precedence for Locating Reports

The following order of precedence will be used for locating record records by supplied lookup values.
  1. ReportID_Match
  2. ReportName_Match
  3. ReportName





    • Related Articles

    • Teamgage App for Slack Integration & Notification setup

      This artilce explains how to set up an integration between Teamgage and Slack, so that notifications are sent to all users in your organisation via Slack. Please contact support@teamgage.com if you want to alter communication preferences in a bulk ...

    • Teamgage Huddle Meeting Guide

      Teamgage Huddle puts you and your team at the heart of the improvement process. It’s your process to own and shape with the team, but we want to share a guide based on what works well. How to facilitate a team huddle using a 20:2:1 framework ...

    • Teamgage Huddle Senior Leader Guide

      Teamgage Huddle gives Senior leaders real-time visibility of how their teams are performing and supports you to identify what's working well and where teams need additional support. Below are our recommendations for using Teamgage as a senior leader. ...

    • How to disable or reset Teamgage App for Slack

      You must be a Teamgage Administrator to complete this setup & you will need your Slack Workspace Admin's approval. After installation, you may enable and disable the integration at any time. The sections below also outline some basic troubleshooting ...

    • Using the Teamgage Brand

      ? We're excited for you to use our brand to promote Teamgage! Please read the following information and then access the high resolution logos and images within the attachments section at the end of the page. Our logo This one looks great on a light ...