1. APIs
  2. People

Contents

Summary

Contains methods for working with users and other individuals within the TeamDynamix people database.

API Methods

POST https://services.dartmouth.edu/TDWebApi/api/people Copy URL

Creates a user in the system and returns an object representing that person.

Parameters

Returns

A response creating the new user.

Access Restrictions

This action can only be performed by special key-based administrative service accounts and not standard TeamDynamix users.

Rate/Submission Limitations

Invocations of this method are rate-limited, with a restriction of 45 calls per IP address every 60 seconds.

GET https://services.dartmouth.edu/TDWebApi/api/people/{uid} Copy URL

Gets a person from the system.

Parameters

Returns

The person if it was found. (TeamDynamix.Api.Users.User)

Access Restrictions

This action requires access to the TDPeople application.

Rate/Submission Limitations

Invocations of this method are rate-limited, with a restriction of 60 calls per IP address every 60 seconds.

PATCH https://services.dartmouth.edu/TDWebApi/api/people/{uid} Copy URL

Patches an existing person. This only supports patching the person itself, custom attributes, applications and organization applications. Other collections on the person are not supported.

About PATCH Support

For information on how to structure HTTP PATCH calls, see the HTTP PATCH Support page.

Parameters

Returns

The updated person. (TeamDynamix.Api.Users.User)

Access Restrictions

This action can only be performed by special key-based administrative service accounts and not standard TeamDynamix users.

Rate/Submission Limitations

Invocations of this method are rate-limited, with a restriction of 45 calls per IP address every 60 seconds.

Remarks

You will not be able to change the user's password, change user's organization, or change user type using this method.

Standard applications can be managed through this method as a full replace action. It is not possible to partially add/remove/merge applications or otherwise partially change the Applications property via this method. When including Applications, any standard applications that are omitted will be removed from the user. Providing an empty collection of Applications will remove all standard applications from the user. Omitting Applications will cause no change in standard applications for the user.

Organizationally defined applications can be managed through this method as a full replace action. It is not possible to partially add/remove/merge applications or otherwise partially change the OrgApplications property via this method. When including OrgApplications, any organizationally defined applications that are omitted or paired with an invalid security role ID will be removed from the user. Providing an empty collection of OrgApplications will remove all organizationally defined applications from the user. Omitting the OrgApplications will cause no change in organizationally defined applications for the user. Finally, external apps are not associated with security roles. Any security role ID paired with an external app ID will be ignored.

Application Access Usage Examples:
  • Standard Applications:
    1. Changes application access to only TDNext and MyWork:
      {"op": "add", "path": "/applications", "value": ["TDNext","MyWork"]}
    2. Clears all application access:
      {"op": "add", "path": "/applications", "value": []}
    3. Makes no change to application access at all:
      {"op": "add", "path": "/applications", "value": null}
  • Organizationally Defined Applications:
    1. Changes application access to only Ticket app 1 and Client Portal app 2:
      {"op": "add", "path": "/orgapplications", "value": [{"id":1,"securityroleid":"role1here"},{"id":2,"securityroleid":"role2here"}]}
    2. Clears all application access):
      {"op": "add", "path": "/orgapplications", "value": []}
    3. Makes no change to application access at all:
      {"op": "add", "path": "/orgapplications", "value": null}

POST https://services.dartmouth.edu/TDWebApi/api/people/{uid} Copy URL

Updates a person entry for the user with the specified identifier with a set of new values.

Parameters

Returns

The modified user object. (TeamDynamix.Api.Users.User)

Access Restrictions

This action can only be performed by special key-based administrative service accounts and not standard TeamDynamix users.

Rate/Submission Limitations

Invocations of this method are rate-limited, with a restriction of 45 calls per IP address every 60 seconds.

Remarks

You will not be able to change the user's password, change user's organization, or change user type using this method.

Standard applications can be managed through this method as a full replace action. It is not possible to partially add/remove/merge applications or otherwise partially change the Applications property via this method. When including Applications, any standard applications that are omitted will be removed from the user. Providing an empty collection of Applications will remove all standard applications from the user. Omitting Applications will cause no change in standard applications for the user.

Organizationally defined applications can be managed through this method as a full replace action. It is not possible to partially add/remove/merge applications or otherwise partially change the OrgApplications property via this method. When including OrgApplications, any organizationally defined applications that are omitted or paired with an invalid security role ID will be removed from the user. Providing an empty collection of OrgApplications will remove all organizationally defined applications from the user. Omitting the OrgApplications will cause no change in organizationally defined applications for the user. Finally, external apps are not associated with security roles. Any security role ID paired with an external app ID will be ignored.

Application Access Usage Examples:
  • Standard Applications:
    1. Changes application access to only TDNext and MyWork:
      "Applications": ["TDNext","MyWork"]
    2. Clears all application access:
      "Applications": []
    3. Makes no change to application access at all:
      "Applications": null
  • Organizationally-Defined Applications:
    1. Changes application access to only Ticket app 1 and Client Portal app 2:
      "OrgApplications": [{"id":1,"securityroleid":"role1here"},{"id":2,"securityroleid":"role2here"}]
    2. Clears all application access):
      "OrgApplications": : []
    3. Makes no change to application access at all:
      "OrgApplications": null

GET https://services.dartmouth.edu/TDWebApi/api/people/{uid}/functionalroles Copy URL

Gets all functional roles for a particular user.

Parameters

Returns

All functional roles for the specified user. (TeamDynamix.Api.Roles.UserFunctionalRole[])

Access Restrictions

This action can only be performed by special key-based administrative service accounts and not standard TeamDynamix users.

Rate/Submission Limitations

Invocations of this method are rate-limited, with a restriction of 180 calls per IP address every 60 seconds.

DELETE https://services.dartmouth.edu/TDWebApi/api/people/{uid}/functionalroles/{roleId} Copy URL

Removes the user from a functional role.

Parameters

Returns

A response message indicating if the operation was successful or not.

Access Restrictions

This action can only be performed by special key-based administrative service accounts and not standard TeamDynamix users.

Rate/Submission Limitations

Invocations of this method are rate-limited, with a restriction of 180 calls per IP address every 60 seconds.

PUT https://services.dartmouth.edu/TDWebApi/api/people/{uid}/functionalroles/{roleId}?isPrimary={isPrimary} Copy URL

Adds the user to functional role if they are not already in that role. If they are in that role, this will update whether or not that role is the user's primary functional role.

Parameters

Returns

A response message indicating if the operation was successful or not.

Access Restrictions

This action can only be performed by special key-based administrative service accounts and not standard TeamDynamix users.

Rate/Submission Limitations

Invocations of this method are rate-limited, with a restriction of 180 calls per IP address every 60 seconds.

GET https://services.dartmouth.edu/TDWebApi/api/people/{uid}/groups Copy URL

Gets all groups for a particular user.

Parameters

Returns

All groups for the specified user. (TeamDynamix.Api.Users.UserGroup[])

Access Restrictions

This action can only be performed by special key-based administrative service accounts and not standard TeamDynamix users.

Rate/Submission Limitations

Invocations of this method are rate-limited, with a restriction of 180 calls per IP address every 60 seconds.

DELETE https://services.dartmouth.edu/TDWebApi/api/people/{uid}/groups/{groupID} Copy URL

Removes the user from a group.

Parameters

Returns

A response message indicating if the operation was successful or not.

Access Restrictions

This action can only be performed by special key-based administrative service accounts and not standard TeamDynamix users.

Rate/Submission Limitations

Invocations of this method are rate-limited, with a restriction of 180 calls per IP address every 60 seconds.

PUT https://services.dartmouth.edu/TDWebApi/api/people/{uid}/groups/{groupID}?isPrimary={isPrimary}&isNotified={isNotified}&isManager={isManager} Copy URL

Adds the user to group if they are not already in that group. If they are in that group, this will update whether or not that group is the user's primary group, whether they are notified along with the group, and if they are the manager of the group.

Parameters

Returns

A response message indicating if the operation was successful or not.

Access Restrictions

This action can only be performed by special key-based administrative service accounts and not standard TeamDynamix users.

Rate/Submission Limitations

Invocations of this method are rate-limited, with a restriction of 180 calls per IP address every 60 seconds.

POST https://services.dartmouth.edu/TDWebApi/api/people/{uid}/groups?removeOtherGroups={removeOtherGroups} Copy URL

Adds a user to a collection of groups.

Parameters

Returns

A response message indicating if the operation was successful or not.

Access Restrictions

This action can only be performed by special key-based administrative service accounts and not standard TeamDynamix users.

Rate/Submission Limitations

Invocations of this method are rate-limited, with a restriction of 45 calls per IP address every 60 seconds.

PUT https://services.dartmouth.edu/TDWebApi/api/people/{uid}/isactive?status={status} Copy URL

Updates the active status of the specified user.

Parameters

Returns

A response message indicating if the operation was successful or not.

Access Restrictions

This action can only be performed by special key-based administrative service accounts and not standard TeamDynamix users.

Rate/Submission Limitations

Invocations of this method are rate-limited, with a restriction of 60 calls per IP address every 60 seconds.

POST https://services.dartmouth.edu/TDWebApi/api/people/import?AllowIsActiveChanges={AllowIsActiveChanges}&AllowSecurityRoleChanges={AllowSecurityRoleChanges}&AllowApplicationChanges={AllowApplicationChanges}&NotifyEmailAddresses={NotifyEmailAddresses} Copy URL

Accepts a file, stores that file on disk, and places an entry into the database to indicate to the import file processor to pick up the file and run a People Import on it.

Parameters

File Upload

This action accepts an uploaded file as part of the form's submission. For information on how to structure calls with files, see the Submitting Files page.

Access Restrictions

This action can only be performed by special key-based administrative service accounts and not standard TeamDynamix users.

Rate/Submission Limitations

Invocations of this method are rate-limited, with a restriction of 10 calls per IP address every 60 seconds.

Remarks

Requirements:
  • The file must be in .xlsx format
  • The file must have a header row with supported TeamDynamix fields as column names. Download the template file using the instructions below for more details.
This process can be used to:
  • Update existing customer and user records
  • Create new customer records if no existing customer is found and the user type is Customer
  • Create new users if no existing user is found and the user type is User
This process will not:
  • Convert existing Customer records to User records or vice-versa
Updating Existing Records:
The following matching logic is used to determine if a records should be udpated or created.
  1. Username - If there already exists one or more people, regardless of active status, with the same TeamDynamix username as a row that is being imported, those records will be updated from the spreadsheet. This field will only be used for the purposes of matching. TeamDynamix username fields will not be updated as part of this process.
  2. Authentication Username - If there already exists one or more people, regardless of active status, with the same TeamDynamix authentication username as a row that is being imported, those records will be updated from the spreadsheet. This is the Auth Username specified for the user in the TDAdmin application. This field will only be used for the purposes of matching. TeamDynamix authentication username fields will not be updated as part of this process.
  3. Organizational ID - If there already exists one or more people, regardless of active status, with the same organizational ID as a row that is being imported, those records will be updated from the spreadsheet.
  4. Primary Email Address - If there already exists one or more people, regardless of active status, with the same primary email as a row that is being imported, those records will be updated from the spreadsheet.
User organizational IDs and primary email addresses will be updated as part of this process as long as they are not the fields which records are matched on.

Creating New Records:
When creating records, the default is to create a Customer. If you do not include the User Type column and specify a user type of User, Customer records will be created.

Not Mapping Values vs. Clearing Values :
It is important to note that this process will only attempt to modify values for fields which are included in the import sheet and can be mapped to a TeamDynamix field. For instance, if you do not provide a column for a user's home phone, that value will not be mapped and thus will not be changed in any way. If you want to clear values, be sure that you provide a column for the field you want to clear and leave the cell values blank.

Schedule:
Calls to this endpoint are not processed in real-time. All import jobs are run in a batch process overnight.

Download the Template File:
See this TeamDynamix Knowledge Base article for a template upload file with the supported columns. The template will contain all necessary instructions for how to obtain column values for each column.

GET https://services.dartmouth.edu/TDWebApi/api/people/lookup?searchText={searchText}&maxResults={maxResults} Copy URL

Performs a restricted lookup of TeamDynamix people. Will not return full user information.

Parameters

Returns

A filtered set of TeamDynamix people. (TeamDynamix.Api.Users.User[])

Rate/Submission Limitations

Invocations of this method are rate-limited, with a restriction of 75 calls per IP address every 10 seconds.

Remarks

This endpoint will not return all user information. For example, the following collection properties will not be included in the results:
  • Applications
  • Attributes
  • GroupIDs
  • OrgApplications
  • Permissions
To retrieve such information, you must load a user individually.

POST https://services.dartmouth.edu/TDWebApi/api/people/search Copy URL

Gets a list of users. Will not return full user information.

Parameters

Returns

A collection of users. (TeamDynamix.Api.Users.User[])

Access Restrictions

This action requires access to the TDPeople application.

Rate/Submission Limitations

Invocations of this method are rate-limited, with a restriction of 60 calls per IP address every 60 seconds.

Remarks

If you are attempting to look up basic user information using a simple search string, consider using the GET api/people/lookup method instead.

This endpoint will not return all user information. For example, the following collection properties will not be included in the results:
  • Applications
  • Attributes
  • GroupIDs
  • OrgApplications
  • Permissions
To retrieve such information, you must load a user individually.

GET https://services.dartmouth.edu/TDWebApi/api/people/userlist?isActive={isActive}&isConfidential={isConfidential}&isEmployee={isEmployee}&userType={userType} Copy URL

Gets a list of TeamDynamix people. Will not return full user information.

Parameters

Returns

A collection of limited user information. (TeamDynamix.Api.Users.UserListing[])

Access Restrictions

This action can only be performed by special key-based administrative service accounts and not standard TeamDynamix users.

Rate/Submission Limitations

Invocations of this method are rate-limited, with a restriction of 1 call per user every 60 seconds.