Tymeshift API

Base URL: https://[account_name].tymeapp.com/api, Version: 1.0.0

Zendesk account name (user), Your tymeshift token (token) and Account creator email (requester_email) is required parameters and must be included to every api request.

You can find this information at settings page of your tymeshift account: ADMIN -> SETTINGS -> SHOW ADVANCED OPTIONS
You see "API TOKEN" and "ACCOUNT CREATOR EMAIL"

With these Informations provided, you need submit requests with base Url which should contain your account name.

Example: Demo account name = ts99, so basicreport request will look like this :
https://ts99.tymeapp.com/api/basicreport?token=b77b1e79ffffe0962bd3b49fc765cc69&requester_email=ts99@mpacomputers.com&payroll_period_start=1

Default response content-types: application/json
Schemes: https

Summary

Tag: List Timesheets

Operation Description
GET /listtimesheets

List Timesheets

Tag: Users

Operation Description
GET /listusers

List users

Tag: Groups

Operation Description
GET /listgroups

List groups

Tag: Organizations

Operation Description
GET /organization

List organizations

Tag: Report

Operation Description
GET /basicreport

Generate basic report

Tag: List Timecategories

Operation Description
GET /listtimecategories

List Timecategories

Tag: Metric

Operation Description
GET /listMetrics

Load metrics

GET /getMetrics

Load metrics

Paths

Generate basic report

GET /basicreport

Tags: Report

Generate report with total hours used for the time period, ticket numbers, ticket names, and time tracked on those tickets.

user

Zendesk account name

query string
token

Your tymeshift token

query string
requester_email

Account creator email

query string
agent_id

Tymeshift user ID

query integer
group_id

Zendesk group ID

query integer
payroll_period_start

Payroll period start selector. Can be one of the following values: 0 - not using (in this case used start_time and end_time properties) 1 - current payroll period 2 - previous payroll period 3 - 2 weeks ago payroll period 4 - 3 weeks ago payroll period -1 - last 7 days -2 - last 14 days -3 - last 21 days -4 - last 28 days

query integer (int)
start_time

Start time (unix format). Not used if payroll_period_start != 0

query integer (int32)
end_time

End time (unix format). Not used if payroll_period_start != 0

query integer (int32)
ticket_status

Ticket Status can be one of the following values: 0 - any status 1 - new 2 - open 3 - pending 4 - solved 5 - closed 6 - hold

query integer (int32)
tags_all

String separated by comma with tags what EACH present at the ticket (if one of this tags not present at the ticket then the ticket is NOT relevant)

query string
tags_any

String separated by comma with tags what ANY present at the ticket (if one of this tags is present at the ticket then the ticket IS relevant)

query string
tags_none

String separated by comma with tags what NOT present at the ticket (if one of this tags IS present at the ticket then the ticket is NOT relevant)

query string
show_general_job_codes

1/0 - show or not general jobcodes at report

query integer (int)

Uses default content-types: application/json

200 OK

Basic report

default

Unexpected error

Load metrics

GET /getMetrics

Tags: Metric

Generate report with metrics for the selected time period.

Example: link

Here is an example of how to use this data to calculated AHT (average handle time).

First, you need to get ticket metric results from [metrics][tickets][data].
Next, go through the ticket metric array and get SUM[total] and SUM[tickets_num] of all objects where "ticket_type"="TICKETS" and "zchannel" = "web".
Once you receive the result, calculate AHT like this: AHT = SUM[total]/SUM[tickets_num].

Additional clarifications:
This example shows how to get AHT for Tickets using the zchannel of web.

Tickets: "zchannel" = "web"
Chat: "zchannel" = "chat"
Voice: "zchannel" = "voice"

user

Zendesk account name

query string
token

Your tymeshift token

query string
requester_email

Account creator email

query string
start_time

Start time (MM/DD/YYYY).

query string
end_time

End time (MM/DD/YYYY).

query string
prim_groupby

Grouping Level 1 can be one of the following values: 0 - Customer (default) 2 - Agent 3 - Group 4 - Day 5 - Ticket Field 10 - Ticket Time Category

query integer (int32)
sub_groupby

Grouping Level 2 can be one of the following values: 0 - Ticket ID 3 - Agent 4 - Group 5 - Day 6 - Ticket Field 11 - Ticket Time Category . By default it group by Ticket ID

query integer (int32)
sub_sub_groupby

Grouping Level 3 can be one of the following values: 3 - Agent 4 - Group 5 - Day 6 - Ticket Field 11 - Ticket Time Category

query integer (int32)
prim_groupby_val

Value for Grouping Level 1

query int32
sub_groupby_val

Value for Grouping Level 2

query int32
sub_sub_groupby_val

Value for Grouping Level 3

query int32

Uses default content-types: application/json

200 OK

List of metrics

default

Unexpected error

List groups

GET /listgroups

Tags: Groups

List zendesk groups from tymeshift database for requesting account

user

Zendesk account name

query string
token

Your tymeshift token

query string
requester_email

Account creator email

query string

Uses default content-types: application/json

200 OK

An array of groups

status: string

Status of operation ("ok" / "fail").

result: object[]
default

Unexpected error

Load metrics

GET /listMetrics

Tags: Metric

Generate report with metrics for the time period Example: https://tymeshiftdemo.tymeapp.com/api/listMetrics?token=6def763ca82ab6ccbd9fe3427bd14581&requester_email=alex%40askmpa.com&start_time=08%2F01%2F2017&end_time=08%2F08%2F2017&prim_groupby=2&sub_groupby=0&sub_sub_groupby=0&prim_groupby_val=0&sub_groupby_val=0&sub_sub_groupby_val=0

user

Zendesk account name

query string
token

Your tymeshift token

query string
requester_email

Account creator email

query string
start_time

Start time (MM/DD/YYYY).

query integer (int32)
end_time

End time (MM/DD/YYYY).

query integer (int32)
prim_groupby

Grouping Level 1 can be one of the following values: 0 - Customer (default) 2 - Agent 3 - Group 4 - Day 5 - Ticket Field 10 - Ticket Time Category

query integer (int32)
sub_groupby

Grouping Level 2 can be one of the following values: 0 - Ticket ID 3 - Agent 4 - Group 5 - Day 6 - Ticket Field 11 - Ticket Time Category . By default it group by Ticket ID

query integer (int32)
sub_sub_groupby

Grouping Level 3 can be one of the following values: 3 - Agent 4 - Group 5 - Day 6 - Ticket Field 11 - Ticket Time Category

query integer (int32)
prim_groupby_val

Value for Grouping Level 1

query int32
sub_groupby_val

Value for Grouping Level 2

query int32
sub_sub_groupby_val

Value for Grouping Level 3

query int32

Uses default content-types: application/json

200 OK

List of metrics

default

Unexpected error

List Timecategories

GET /listtimecategories

Tags: List Timecategories

Show timecategories from tymeshift database for requesting account.

user

Zendesk account name

query string
token

Your tymeshift token

query string
requester_email

Account creator email

query string
parent

ID of parent timecategory

query integer (int)

Uses default content-types: application/json

200 OK

An array of timecategories

status: string

Status of operation ("ok" / "fail").

result: object[]
default

Unexpected error

List Timesheets

GET /listtimesheets

Tags: List Timesheets

Show timesheets from tymeshift database for requesting account.

user

Zendesk account name

query string
token

Your tymeshift token

query string
requester_email

Account creator email

query string
payroll_period_start

Payroll period start selector. Can be one of the following values: 0 - not using (in this case used start_time and end_time properties) 1 - current payroll period 2 - previous payroll period 3 - 2 weeks ago payroll period 4 - 3 weeks ago payroll period -1 - last 7 days -2 - last 14 days -3 - last 21 days -4 - last 28 days

query integer (int)
start_time

Start time (unix format). Not used if payroll_period_start != 0

query integer (int32)
end_time

End time (unix format). Not used if payroll_period_start != 0

query integer (int32)
limit

Limit or response. Default 100

query integer (int32)
offset

Offset of response. Default 0

query integer (int32)

Uses default content-types: application/json

200 OK

An array of timesheets

status: string

Status of operation ("ok" / "fail").

result: object[]
default

Unexpected error

List users

GET /listusers

Tags: Users

Show users from tymeshift database for requesting account.

user

Zendesk account name

query string
token

Your tymeshift token

query string
requester_email

Account creator email

query string
agent_id

Tymeshift user ID

query integer
group_id

Zendesk group ID

query integer

Uses default content-types: application/json

200 OK

An array of users

status: string

Status of operation ("ok" / "fail").

result: object[]
default

Unexpected error

List organizations

GET /organization

Tags: Organizations

List zendesk organizations from tymeshift database for requesting account

user

Zendesk account name

query string
token

Your tymeshift token

query string
requester_email

Account creator email

query string
id

Zendesk organization id (if not present or equal to zero then response list of all organizations)

query integer
limit

Limit output (default 100)

query integer
offset

Offset output (default 0)

query integer

Uses default content-types: application/json

200 OK

An array of organizations

status: string

Status of operation ("ok" / "fail").

result: object[]
default

Unexpected error

Schema definitions

afrtaMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric

Summ of time to first comment from ticket assignee

event_num: numeric

Number of tickets

username: string

Agent name (if group by agent)

attendedMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric
event_num: numeric

Number of attended tickets

username: string

Agent name (if group by agent)

BasicReport: object

start_time: integer

Start time (unix format) of generated report

end_time: integer

Start time (unix format) of generated report

result_total: object
status: string

Status of operation ("ok" / "fail").

data: object
totals: object
job_codes: object[]
users: object[]
zend_tickets: ZendTicket

chats_durationMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric

Sum of durations of chats in selected period

event_num: numeric

Number of chats in selected period

username: string

Agent name (if group by agent)

chats_frtMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric

Sum of average response time on chats

event_num: numeric

Number of chats with average response time > 0

username: string

Agent name (if group by agent)

chats_handledMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric

Sum of time on handled chats

event_num: numeric

Number of handled chats (with time of it)

username: string

Agent name (if group by agent)

chats_messagesMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric

Sum of total messages on chats

event_num: numeric
username: string

Agent name (if group by agent)

chats_missedMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric
event_num: numeric

Number of missed chats

username: string

Agent name (if group by agent)

chats_ratingMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric

Number of chats with 'good' rating

event_num: numeric

Number of chats with 'bad' rating

username: string

Agent name (if group by agent)

chats_touchedMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric
event_num: numeric

Number of touched chats

username: string

Agent name (if group by agent)

chats_waitMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric

Sum of chats first response time

event_num: numeric

Number of chats with first response time > 0

username: string

Agent name (if group by agent)

crtMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric

Summ of time to last solved from ticket create

event_num: numeric

Number of tickets

username: string

Agent name (if group by agent)

csat_scoreMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric

Number of GOOD scores

event_num: numeric

Number of BAD scores

username: string

Agent name (if group by agent)

Error: object

code: integer (int32)
message: string
fields: string

escalatedMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric
event_num: numeric

Number of escalated tickets

username: string

Agent name (if group by agent)

fatMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric

Summ of times to First Assigned Time from ticket create

event_num: numeric

Number of tickets

username: string

Agent name (if group by agent)

frtMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric

Summ of time to attended from ticket create

event_num: numeric

Number of tickets

username: string

Agent name (if group by agent)

getMetrics: object

status: string

Status of operation ("ok" / "fail").

metrics: object

List of metrics.

tickets: ticketsMetric

Tickets metrics.

tickets_assignee: tickets_assigneeMetric

Tickets metrics.

public_comment: public_commentMetric

Tickets metrics.

private_comment: private_commentMetric

Tickets metrics.

csat_score: csat_scoreMetric

Tickets metrics.

fat: fatMetric

Tickets metrics.

frt: frtMetric

Tickets metrics.

afrta: afrtaMetric

Tickets metrics.

crt: crtMetric

Tickets metrics.

solved: solvedMetric

Tickets metrics.

escalated: escalatedMetric

Tickets metrics.

attended: attendedMetric

Tickets metrics.

reopened: reopenedMetric

Tickets metrics.

handled: handledMetric

Tickets metrics.

one_touch: one_touchMetric

Tickets metrics.

lhold: lholdMetric

Tickets metrics.

unattended: unattendedMetric

Tickets metrics.

unassigned_unattended: unassigned_unattendedMetric

Tickets metrics.

chats_handled: chats_handledMetric

Chats Handled

chats_duration: chats_durationMetric

Chats duration.

chats_touched: chats_touchedMetric

Chats touched.

chats_frt: chats_frtMetric

Chats First Response Time

chats_rating: chats_ratingMetric

Chats rating.

chats_messages: chats_messagesMetric

Chats messages.

chats_missed: chats_missedMetric

Chats missed.

chats_wait: chats_waitMetric

Chats wait.

Group: object

id: number

Group ID.

group_name: string

Group name.

handledMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric
event_num: numeric

Number of handled tickets

username: string

Agent name (if group by agent)

JobCodeTotal: object

zend_ticket_id: number

Zend ticket ID

nice_id: number

Zend nice ID

total: number

Total time on ticket in seconds

ticket_name: string

Ticket name

lholdMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric

Summ of time to last solved from ticket create

event_num: numeric

Number of hold tickets

username: string

Agent name (if group by agent)

listMetrics: object

status: string

Status of operation ("ok" / "fail").

total: object

List of totals by ticket type

metrics: object

List of grouped metrics.

one_touchMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric

Summ of time to first solved

event_num: numeric

Number of one_touch tickets

username: string

Agent name (if group by agent)

Organization: object

id: number

Organization ID.

name: string

Organization name.

private_commentMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric
event_num: numeric

Total number private comments for group

username: string

Agent name (if group by agent)

public_commentMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric
event_num: numeric

Total number public comments for group

username: string

Agent name (if group by agent)

reopenedMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric
event_num: numeric

Number of reopened tickets

username: string

Agent name (if group by agent)

solvedMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric
event_num: numeric

Number of solved tickets

username: string

Agent name (if group by agent)

tickets_assigneeMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric
event_num: numeric

Total number assigned tickets for group

username: string

Agent name (if group by agent)

ticketsMetric: object

prim_groupby: string

Primary group ID

total: numeric

Total time for group (if grouped by agent then total time on agent for selected time period)

tickets_num: numeric

Total number of tickets for group (if grouped by agent then total number of tickets on what agent work for selected time period)

tickets_list: string

List of tickets ID's comma separated.

etotal: numeric

Total exclude occupancy time for group

ptotal: numeric

Total productive time for group

username: string

Agent name (if group by agent)

ticket_type: string

Ticket Type (can be TICKETS, GENERAL TASKS, UNTRACKED)

zchannel: string

Channel Name (can be web, chat, voice)

channel: string

Zendesk Channel Name

Timecategory: object

id: number

Timecategory ID.

name: string

Timecategory name.

parent_id: string

ID of parent timecategory

mychildscount: number

Number of child timecategories

Timesheets: object

result: object
total: number

Total items for input criteria

data: object
id: number

Tymesheet ID.

start_time: number

Start time. Unix format

end_time: number

End time. Unix format

seconds: number

Timesheet length. In seconds

tz: number

Timesheet timezone

tymeshift_user_id: number

Tymeshift user ID

zend_user_id: number

Zendesk user ID

username: string

Timesheet creator username

zend_assignee_id: number

Zendesk assignee user ID

assignee_name: string

Zendesk assignee user name

zend_group_id: number

Zendesk group ID

group_name: string

Zendesk group name

status: string

Zendesk ticket status

ticket_type: string

Zendesk ticket type

subject: string

Zendesk ticket subject

timesheet_type: string

Timesheet type (Possible values: UNTRACKED, TICKETS, GENERAL TASKS)

tymeshift_ticket_id: number

Tymeshift ticket ID

zend_nice_id: number

Zendesk ticket nice ID

jobcode: string

Job name

assignee_updated_at: string

Assignee updated at time

initially_assigned_at: string

Initially assigned at time

assigned_at: string

Assigned at time

unassigned_unattendedMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric
event_num: numeric

Number of unassigned_unattended tickets

username: string

Agent name (if group by agent)

unattendedMetric: object

prim_groupby: string

Primary group ID

event_sum: numeric
event_num: numeric

Number of unattended tickets

username: string

Agent name (if group by agent)

User: object

id: number

Tymeshift user ID.

user_id: number

Zendesk user ID.

email: string

User email.

username: string

User name.

UserTotal: object

zend_user_id: number

Tymeshift user ID

total: number

Total time on user in seconds

username: string

User name

email: string

User email

ZendTicket: object

id: number

Zend Ticket nice ID.

subject: string

Ticket subject

description: string

Ticket description