WiseTime Connect
API docs by Redocly

WiseTime Connect API (1.3.0)

Download OpenAPI specification:Download

WiseTime Connect API Support: contact@wisetime.com URL: https://wisetime.com/docs/connect

Use the WiseTime Connect API to build connectors to your application.

Team Info

Retrieve information about the team

Authorizations:
ConnectApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "teamName": "string"
}

Tags

Create a new tag, or update the tag if it already exists

Authorizations:
ConnectApiKeyAuth
Request Body schema: application/json
name
string

Tag name to create. If a tag by this name already exists, the tag will be updated.

description
string

Displayed in the GUI and search functions. An empty (or null) description will be ignored, the description will remain with the previous value instead of replacing it.

excludeTagNameKeyword
boolean

The default behaviour when creating a tag is for the tagName to be added as a keyword for the tag. If excludeTagNameKeyword is set to true, the tagName will not be added as a keyword, unless it is explicitly defined in the additionalKeywords list of the request.

tagCategoryId
string

The ID of the category that this tag belongs to. This field is empty if the tag does not belong to a category.

path
string
Deprecated

Default is '/'. Can be used to group tags into logical groups. Deprecated. Will be removed in future.

managedBy
string

Identifier of the resource that manages this tag.

externalId
string

Identifier of the tag in the connected system. The external ID will be sent when time is posted with this tag, so that the posted time can be recorded against the relevant record in the connected system.

defaultActivityTypeCode
string

Default activity type code is applied to time entry with this tag when user haven't assigned any activity type explicitly.

object (TagMetadataSet)

You can assign metadata to a tag. You provide this information as a name-value (key-value) pair. The metadata names are case sensitive and will be displayed in reports, it is recommended the names be descriptive to clarify its meaning. In the case of providing any name-value where the name is already assigned as metadata to the tag, the value will be updated with value supplied. To delete/remove a name-value pair stored as metadata on a tag, you must use the tag-metadata-delete operation.

additionalKeywords
Array of strings

A tag is applied to a time row if one of its keywords matches text in the time row activity description. Keywords provided via this property will be added to the list of existing keywords for the tag. Existing keywords won't be removed.

url
string

If a URL is provided, the tag will be a clickable link in the WiseTime console. Clicking on the tag will open the URL.

visibility
string
Enum: "PUBLIC" "PRIVATE"

Defines tag visibility. Default is PUBLIC. Private matters are only accessible by explicitly authorized team members.

assigneeExternalIds
Array of strings

IDs in external system of users associated with the matter.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "excludeTagNameKeyword": true,
  • "tagCategoryId": "string",
  • "path": "string",
  • "managedBy": "string",
  • "externalId": "string",
  • "defaultActivityTypeCode": "string",
  • "metadata": {
    },
  • "additionalKeywords": [
    ],
  • "url": "string",
  • "visibility": "PUBLIC",
  • "assigneeExternalIds": [
    ]
}

Response samples

Content type
application/json
{ }

Create new tags, or update existing in batch (up to 2000 items at once)

Authorizations:
ConnectApiKeyAuth
Request Body schema: application/json
Array of objects (UpsertTagRequest)

Responses

Request samples

Content type
application/json
{
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Delete an existing tag

Authorizations:
ConnectApiKeyAuth
Request Body schema: application/json
One of
name
string

Tag name to delete.

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{ }

Permanently deletes the specified metadata from an existing tag.

Provide the metadata names that you want to delete.

Authorizations:
ConnectApiKeyAuth
Request Body schema: application/json
tagName
required
string

The tag from which to delete the tag metadata.

metadataNames
required
Array of strings

The name(s) of the tag metadata to delete.

Responses

Request samples

Content type
application/json
{
  • "tagName": "string",
  • "metadataNames": [
    ]
}

Response samples

Content type
application/json
{ }

Add one or more keywords to an existing tag

Authorizations:
ConnectApiKeyAuth
Request Body schema: application/json
tagName
string

The tag to which to add the keywords.

externalId
string

The identifier of the tag in the connected system.

additionalKeywords
Array of strings

One or more new keywords for the tag. Keywords provided via this property will be added to the list of existing keywords for the tag. Existing keywords won't be removed.

Responses

Request samples

Content type
application/json
{
  • "tagName": "string",
  • "externalId": "string",
  • "additionalKeywords": [
    ]
}

Response samples

Content type
application/json
{ }

Delete an existing keyword from a tag

Authorizations:
ConnectApiKeyAuth
Request Body schema: application/json
tagName
string

The tag from which to delete the keywords.

keyword
string

The keyword to delete.

Responses

Request samples

Content type
application/json
{
  • "tagName": "string",
  • "keyword": "string"
}

Response samples

Content type
application/json
{ }

Tag Categories

Create new tag categories, or update existing in batch (up to 2000 items at once). If tag category is not found by external ID, it is created. externalId is a required field to use the batch creation endpoint. No partial update, if some of categories failed to be processed, entire batch considered faulty.

Authorizations:
ConnectApiKeyAuth
Request Body schema: application/json
Array of objects (TagCategory)

An array of tag categories to be created/updated.

Responses

Request samples

Content type
application/json
{
  • "tagCategories": [
    ]
}

Response samples

Content type
application/json
{
  • "tagCategories": [
    ]
}

Delete tag category and all related tags

Authorizations:
ConnectApiKeyAuth
Request Body schema: application/json
externalId
string

The ID of the tag category in the connected system, for the tag category to delete

Responses

Request samples

Content type
application/json
{
  • "externalId": "string"
}

Response samples

Content type
application/json
{ }

Activity Types

Start activity types sync session

Initiates a sync session and responds with syncSessionId that can be used for further activity types uploads within the session. While activity types can be sent to WiseTime in batches without a sync session, starting a sync session for the batch uploads means that WiseTime will be able to detect activity types that are no longer in the connected system, and delete these when the sync session is completed by the connector.

Authorizations:
ConnectApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "syncSessionId": "string"
}

Complete activity types sync session

Completes a sync session so its syncSessionId can not be used anymore. All the activity types that were lastly created/updated before the session start will be deleted.

Authorizations:
ConnectApiKeyAuth
Request Body schema: application/json
syncSessionId
string

Sync session identifier that can be used for the patch uploads or session completion/cancellation.

Responses

Request samples

Content type
application/json
{
  • "syncSessionId": "string"
}

Cancel activity types sync session

Cancels a sync session so its syncSessionId can not be used anymore. This API call has no impact on activity types.

Authorizations:
ConnectApiKeyAuth
Request Body schema: application/json
syncSessionId
string

Sync session identifier that can be used for the patch uploads or session completion/cancellation.

Responses

Request samples

Content type
application/json
{
  • "syncSessionId": "string"
}

Create new activity types, or update existing in batch (up to 2000 items at once)

Authorizations:
ConnectApiKeyAuth
Request Body schema: application/json
Array of objects (ActivityType)

An array of activity types to be created/updated.

syncSessionId
string

Optional. Identifier of the sync session.

Responses

Request samples

Content type
application/json
{
  • "activityTypes": [
    ],
  • "syncSessionId": "string"
}

Response samples

Content type
application/json
{
  • "errors": [
    ]
}

Posted Time

Returns posted time with pending status.

Use this endpoint to fetch posted time for processing. This is a long polling call (an alternative to using the webhook mechanism). The connection will be held open for a maximum of 60 seconds or until there is a new posted time event. When calling this method without first calling the /postedtime/registerfetchclient endpoint, recording posted time for fetching will implicitly be turned on.

Authorizations:
ConnectApiKeyAuth
query Parameters
limit
integer

Maximum amount of posted time entries to retrieve. If not set, the API will return up to a maximum of 25 entries for each request.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Returns list of posted time with pending or success status.

Returns all time groups for team in descending order of submission time starting from now. This is not a long polling endpoint.

Authorizations:
ConnectApiKeyAuth
query Parameters
limit
integer

Maximum number of items to return. Should be between 1 and 500. Default is 100.

submittedBefore
integer

Filter response to return only time groups submitted before requested timestamp. If empty - returns latest time groups. Note that the submisisonTime may be the same for multiple time groups as users may submit more than 1 time group as a single operation. Measured in milliseconds since the Epoch.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Register the intent to fetch time from the /postedtime endpoint.

WiseTime will start recording posted time events that can be fetched via the /postedtime endpoint.

Authorizations:
ConnectApiKeyAuth
Request Body schema: application/json
object (RegisterFetchClientRequest)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Delete existing fetch client, unsubscribing your application from posted time fetching.

WiseTime will stop recording posted time events for fetch when users post time to your team.

Authorizations:
ConnectApiKeyAuth
Request Body schema: application/json
object (UnregisterFetchClientRequest)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Updates the status of a received time group. Providing its success or failure to be processed.

This is intended for use with the fetch mechanism only. Not to be used with webhooks. If this endpoint isn't called for a time group within a certain amount of time after fetching it the time group will be made available again for fetching.

Authorizations:
ConnectApiKeyAuth
Request Body schema: application/json
timeGroupId
string

ID of the time group to be updated.

status
string
Enum: "SUCCESS" "FAILURE" "RETRIABLE_FAILURE"

This field describes the status of the posted time group. On SUCCESS the time group will be marked as successfully posted. On FAILURE the time group will be marked as failed and the attached message will displayed to the user. On RETRIABLE_FAILURE the time group will be marked as temporary failed and scheduled for retry. The attached message might be displayed to the user.

message
string

Reason for the failure, will be displayed to the user.

externalId
string

An identifier in the connected system that relates to the posted time group.

Responses

Request samples

Content type
application/json
{
  • "timeGroupId": "string",
  • "status": "SUCCESS",
  • "message": "string",
  • "externalId": "string"
}

Subscribe to be notified when a user posts time information to your team.

WiseTime will call your webhook with a payload of the posted time information. See the posted time webhook documentation for details. Each team is limited to one webhook callback.

Authorizations:
ConnectApiKeyAuth
Request Body schema: application/json
callbackUrl
required
string

The webhook URL that WiseTime will call to notify you of user posted time.

callerKey
string

WiseTime will send this key back to you when it calls your webhook. That way you can authenticate that the request comes from WiseTime.

Responses

Callbacks

Request samples

Content type
application/json
{
  • "callbackUrl": "string",
  • "callerKey": "string"
}

Response samples

Content type
application/json
{ }

Callback payload samples

Callback
POST: post-callback
Content type
application/json
{
  • "callerKey": "string",
  • "groupId": "string",
  • "description": "string",
  • "formattedNarrative": "string",
  • "totalDurationSecs": 0,
  • "totalDurationHours": 0.1,
  • "tzOffsetMins": 0,
  • "localDate": "2019-08-24",
  • "timestamp": 0,
  • "groupName": "string",
  • "narrativeType": "NARRATIVE_AND_TIME_ROW_ACTIVITY_DESCRIPTIONS",
  • "status": "PENDING",
  • "submissionTime": 0,
  • "tags": [
    ],
  • "timeRows": [
    ],
  • "activityType": {
    },
  • "user": {
    },
  • "originatingUser": {
    },
  • "durationSplitStrategy": "DIVIDE_BETWEEN_TAGS"
}

Delete existing webhook for given connector (specified by api key), unsubscribing your application from posted time notifications.

WiseTime will stop calling your webhook when users post time to your team.

Authorizations:
ConnectApiKeyAuth
Request Body schema: application/json
object (UnsubscribeRequest)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Connector Management

Retrieve configuration particulars to suppport the managed connector service.

Authorizations:
ConnectApiKeyAuth
Request Body schema: application/json
object

A dictionary of client runtime environment properties.

connectorType
string

The paired system type that the connector supplies activity data to.

connectorVersion
string

The connector version.

connectorLibraryVersion
string

The WiseTime connector library version that the connector is using.

clientTimestamp
integer <int64>

The current system timestamp from epoch of the client environment.

clientTimeZoneOffset
string

The local time offset of the environment that the client is running within.

Responses

Request samples

Content type
application/json
{
  • "environment": {
    },
  • "connectorType": "string",
  • "connectorVersion": "string",
  • "connectorLibraryVersion": "string",
  • "clientTimestamp": 0,
  • "clientTimeZoneOffset": "string"
}

Response samples

Content type
application/json
{
  • "serviceId": "string",
  • "serviceKey": "string",
  • "serviceIdExpiry": "2019-08-24T14:15:22Z",
  • "serviceSessionToken": "string",
  • "groupName": "string",
  • "regionName": "string",
  • "connectorConfiguration": {
    }
}

Report non-transient health check failure. For unknown error codes the provided error message will be shown to users on time posting. For known error codes connect-api-server will determine the appropriate message.

Authorizations:
ConnectApiKeyAuth
Request Body schema: application/json
errorType
string
Enum: "UNKNOWN" "TARGET_UNREACHABLE" "TARGET_AUTH_FAILURE" "TARGET_PERMISSIONS_FAILURE" "TARGET_SUBSCRIPTION_FAILURE"

Type of non-transient health check failure that occurred.

userErrorMessage
string

Error message shown to team members when trying to post time (until the failure is rescinded / cleared). Optional, will overwrite the default error message of the provided errorType.

Responses

Request samples

Content type
application/json
{
  • "errorType": "UNKNOWN",
  • "userErrorMessage": "string"
}

Rescind (clear) a previously reported health check failure.

Authorizations:
ConnectApiKeyAuth
Request Body schema: application/json
object (HealthCheckFailureRescind)

Responses

Request samples

Content type
application/json
{ }