{"openapi":"3.0.0","servers":[{"url":"/api"}],"info":{"title":"iTimekeep Time Templates API","version":"1.0.0","description":"API for creating and managing time templates<br><br>**NOTE:** This API is currently in development and is subject to change.<br>Download the [swagger.json](/swagger.json) file to see the latest version of the API."},"paths":{"/codes":{"get":{"security":[{"bearerAuth":[]}],"description":"Returns codes for the given ITK subscription","parameters":[{"$ref":"#/components/parameters/subscriptionIdHeader"},{"$ref":"#/components/parameters/userIdHeader"},{"$ref":"#/components/parameters/userEmailHeader"},{"name":"codeTypeId","in":"query","required":false,"schema":{"type":"string"},"description":"Database ID of the code type to filter by"},{"name":"code","in":"query","required":false,"schema":{"type":"string"},"description":"Filter responses where the given value is a substring of the code"},{"name":"description","in":"query","required":false,"schema":{"type":"string"},"description":"Filter responses where the given value is a substring of the description"}],"tags":["Codes"],"responses":{"200":{"description":"Codes for the given ITK subscription","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Code"}}}}},"401":{"$ref":"#/components/responses/status401"},"403":{"$ref":"#/components/responses/status403"}}},"post":{"security":[{"bearerAuth":[]}],"description":"Creates code for the given ITK subscription","parameters":[{"$ref":"#/components/parameters/subscriptionIdHeader"},{"$ref":"#/components/parameters/userIdHeader"},{"$ref":"#/components/parameters/userEmailHeader"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Code"}}}},"tags":["Codes"],"responses":{"201":{"description":"Created code","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Code"}}}},"400":{"description":"Invalid request <ul> <li>Invalid code id in request parameters</li> <li>The code type ID in the request body is missing or references a code type that does not exist in the database</li> <li>Missing or invalid request body</li> </ul>"},"401":{"$ref":"#/components/responses/status401"},"403":{"$ref":"#/components/responses/status403"}}}},"/codes/{id}":{"get":{"security":[{"bearerAuth":[]}],"description":"Returns code for the given ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Database ID of the code to retrieve"},{"$ref":"#/components/parameters/subscriptionIdHeader"},{"$ref":"#/components/parameters/userIdHeader"},{"$ref":"#/components/parameters/userEmailHeader"}],"tags":["Codes"],"responses":{"200":{"description":"Code for the given ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Code"}}}},"400":{"description":"Invalid codeType id"},"401":{"$ref":"#/components/responses/status401"},"403":{"$ref":"#/components/responses/status403"},"404":{"description":"Code not found"}}},"put":{"security":[{"bearerAuth":[]}],"description":"Updates code for the given code ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Database ID of the code to update"},{"$ref":"#/components/parameters/subscriptionIdHeader"},{"$ref":"#/components/parameters/userIdHeader"},{"$ref":"#/components/parameters/userEmailHeader"}],"tags":["Codes"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Code"}}}},"responses":{"200":{"description":"Updated code for the given ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Code"}}}},"400":{"description":"Invalid request <ul> <li>Invalid code id in request parameters</li> <li>The code type ID in the request body is missing or references a code type that does not exist in the database</li> <li>Missing or invalid request body</li> </ul>"},"401":{"$ref":"#/components/responses/status401"},"403":{"$ref":"#/components/responses/status403"},"404":{"description":"Code not found"}}},"delete":{"security":[{"bearerAuth":[]}],"description":"Deletes code for the given id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Code id of the code to delete"},{"$ref":"#/components/parameters/subscriptionIdHeader"},{"$ref":"#/components/parameters/userIdHeader"},{"$ref":"#/components/parameters/userEmailHeader"}],"tags":["Codes"],"responses":{"200":{"description":"Database ID of the successfully deleted code"},"400":{"description":"Invalid codeType id"},"401":{"$ref":"#/components/responses/status401"},"403":{"$ref":"#/components/responses/status403"},"404":{"description":"Code not found"}}}},"/codes/bulk":{"post":{"security":[{"bearerAuth":[]}],"description":"Bulk import/update codes for the given ITK subscription and code type","parameters":[{"$ref":"#/components/parameters/subscriptionIdHeader"},{"$ref":"#/components/parameters/userIdHeader"},{"$ref":"#/components/parameters/userEmailHeader"}],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Code"}}}}},"tags":["Codes"],"responses":{"200":{"description":"Codes were successfully imported/updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkCodesResponse"}}}},"400":{"description":"Invalid request <ul> <li>Invalid code id in request parameters</li> <li>The code type ID in the request body is missing or references a code type that does not exist in the database</li> <li>The request body includes codes for mulitple code types</li> <li>Missing or invalid request body</li> <li>Bulk import codes succeeded, but cascade updates to templates failed</li> </ul>"},"401":{"$ref":"#/components/responses/status401"},"403":{"$ref":"#/components/responses/status403"}}}},"/codeTypes":{"get":{"security":[{"bearerAuth":[]}],"description":"Returns all code types for the given ITK subscription","parameters":[{"$ref":"#/components/parameters/subscriptionIdHeader"},{"$ref":"#/components/parameters/userIdHeader"},{"$ref":"#/components/parameters/userEmailHeader"}],"tags":["CodeTypes"],"responses":{"200":{"description":"Code types for the given ITK subscription","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CodeType"}}}}},"401":{"$ref":"#/components/responses/status401"},"403":{"$ref":"#/components/responses/status403"}}},"post":{"security":[{"bearerAuth":[]}],"description":"Creates code type for the given ITK subscription","parameters":[{"$ref":"#/components/parameters/subscriptionIdHeader"},{"$ref":"#/components/parameters/userIdHeader"},{"$ref":"#/components/parameters/userEmailHeader"}],"tags":["CodeTypes"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeType"}}}},"responses":{"201":{"description":"Created code type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeType"}}}},"400":{"description":"Missing or invalid request body"},"401":{"$ref":"#/components/responses/status401"},"403":{"$ref":"#/components/responses/status403"}}}},"/codeTypes/{id}":{"get":{"security":[{"bearerAuth":[]}],"description":"Returns code type for the given codeType ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Database ID of the code type to retrieve"},{"$ref":"#/components/parameters/subscriptionIdHeader"},{"$ref":"#/components/parameters/userIdHeader"},{"$ref":"#/components/parameters/userEmailHeader"}],"tags":["CodeTypes"],"responses":{"200":{"description":"Code type for the given ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeType"}}}},"400":{"description":"Invalid codeType id"},"401":{"$ref":"#/components/responses/status401"},"403":{"$ref":"#/components/responses/status403"},"404":{"description":"Code type not found"}}},"put":{"security":[{"bearerAuth":[]}],"description":"Updates code type for the given codeType ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Code type id"},{"$ref":"#/components/parameters/subscriptionIdHeader"},{"$ref":"#/components/parameters/userIdHeader"},{"$ref":"#/components/parameters/userEmailHeader"}],"tags":["CodeTypes"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeType"}}}},"responses":{"200":{"description":"Updated code type for the given ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeType"}}}},"400":{"description":"Invalid request <ul> <li>Invalid codeType id in request parameters</li> <li>Missing or invalid request body</li> </ul>"},"401":{"$ref":"#/components/responses/status401"},"403":{"$ref":"#/components/responses/status403"},"404":{"description":"Code type not found"}}},"delete":{"security":[{"bearerAuth":[]}],"description":"Deletes code type for the given codeType id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Code type id of the code type to delete"},{"$ref":"#/components/parameters/subscriptionIdHeader"},{"$ref":"#/components/parameters/userIdHeader"},{"$ref":"#/components/parameters/userEmailHeader"}],"tags":["CodeTypes"],"responses":{"200":{"description":"Code type successfully deleted"},"400":{"description":"Invalid codeType id"},"401":{"$ref":"#/components/responses/status401"},"403":{"$ref":"#/components/responses/status403"},"404":{"description":"Code type not found"}}}},"/codeTypes/bulk":{"post":{"security":[{"bearerAuth":[]}],"description":"Merges multiple code types with the database entries for the given ITK subscription <ul> <li>Code type in request does not exist in database - create new code type in database</li> <li>Code type in request exists in database but with different values - update existing code type in database</li> <li>Code type in request exists in database but with different values - no database update</li> <li>Code type in database does not exist in request - delete code type from database</li> </ul>","parameters":[{"$ref":"#/components/parameters/subscriptionIdHeader"},{"$ref":"#/components/parameters/userIdHeader"},{"$ref":"#/components/parameters/userEmailHeader"}],"tags":["CodeTypes"],"requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CodeType"}}}}},"responses":{"200":{"description":"Created code type","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeTypesBulkResponse"}}}},"400":{"description":"Missing or invalid request body"},"401":{"$ref":"#/components/responses/status401"},"403":{"$ref":"#/components/responses/status403"}}}},"/templates":{"get":{"security":[{"bearerAuth":[]}],"description":"Returns templates for the given ITK subscription and user","parameters":[{"$ref":"#/components/parameters/subscriptionIdHeader"},{"$ref":"#/components/parameters/userIdHeader"},{"$ref":"#/components/parameters/userEmailHeader"},{"name":"templateType","in":"query","required":false,"schema":{"type":"string","enum":["subscription","user"]},"description":"The type of the template. Must be either \"subscription\" or \"user\"."},{"name":"name","in":"query","required":false,"schema":{"type":"string"},"description":"Matches on a substring of the name of the template"},{"name":"codes.value.code","in":"query","required":false,"schema":{"type":"string"},"description":"Matches on a substring of any of the code values used in the template (e.g. a101)"}],"tags":["Templates"],"responses":{"200":{"description":"Templates for the given ITK subscription and user","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Template"}}}}},"401":{"$ref":"#/components/responses/status401"},"403":{"$ref":"#/components/responses/status403"}}},"post":{"description":"Creates template for the given ITK subscription","parameters":[{"$ref":"#/components/parameters/subscriptionIdHeader"},{"$ref":"#/components/parameters/userIdHeader"},{"$ref":"#/components/parameters/userEmailHeader"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"tags":["Templates"],"responses":{"200":{"description":"Created template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"400":{"description":"Bad request <ul> <li>Missing template body</li> <li>Template body contains validation errors</li> </ul>"},"401":{"$ref":"#/components/responses/status401"},"403":{"$ref":"#/components/responses/status403"},"409":{"description":"Conflict <ul> <li>For firm templates, the template name must be unique for the subscription</li> <li>For user templates, the template name must be unique for the subscription user</li> </ul>"}}}},"/templates/{id}":{"get":{"security":[{"bearerAuth":[]}],"description":"Returns templates for the given ID","parameters":[{"$ref":"#/components/parameters/subscriptionIdHeader"},{"$ref":"#/components/parameters/userIdHeader"},{"$ref":"#/components/parameters/userEmailHeader"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Database ID of the template to retrieve"}],"tags":["Templates"],"responses":{"200":{"description":"Template for the given ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"400":{"description":"Invalid template ID"},"401":{"$ref":"#/components/responses/status401"},"403":{"$ref":"#/components/responses/status403"},"404":{"description":"Template not found"}}},"put":{"description":"Updates template for the given ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Database ID of the template to update"},{"$ref":"#/components/parameters/subscriptionIdHeader"},{"$ref":"#/components/parameters/userIdHeader"},{"$ref":"#/components/parameters/userEmailHeader"}],"tags":["Templates"],"responses":{"200":{"description":"Updated template","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Template"}}}},"400":{"description":"Bad request <ul> <li>Template ID is not a valid MongoDB database ID</li> <li>Missing template body</li> <li>Changing template type is not supported</li> <li>Template includes a code that does not exist</li> <li>Template body contains validation errors</li> </ul>"},"401":{"$ref":"#/components/responses/status401"},"403":{"$ref":"#/components/responses/status403"},"404":{"description":"Template not found"},"409":{"description":"Conflict <ul> <li>For firm templates, the template name must be unique for the subscription</li> <li>For user templates, the template name must be unique for the subscription user</li> </ul>"}}},"delete":{"description":"Deletes template for the given id","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Template id of template to delete"},{"$ref":"#/components/parameters/subscriptionIdHeader"},{"$ref":"#/components/parameters/userIdHeader"},{"$ref":"#/components/parameters/userEmailHeader"}],"tags":["Templates"],"responses":{"200":{"description":"Database ID of the successfully deleted template"},"400":{"description":"Invalid codeType id"},"401":{"$ref":"#/components/responses/status401"},"403":{"$ref":"#/components/responses/status403"},"404":{"description":"Code not found"}}}}},"components":{"schemas":{"BulkCodesResponse":{"type":"object","description":"Response schema for bulk code import","properties":{"success":{"type":"boolean","description":"Indicates if the bulk import was successful"},"code":{"type":"string","description":"HTTP status code"},"message":{"type":"string","description":"Success/failure message"},"dbResponse":{"type":"object","description":"Database response for bulk code import","properties":{"inserted":{"type":"array","items":{"type":"string"},"description":"Database ID of the successfully inserted codes"},"updated":{"type":"array","items":{"type":"string"},"description":"Database ID of the successfully updated codes"},"unchanged":{"type":"array","items":{"type":"string"},"description":"Database ID of the codes that were unchanged"},"deleted":{"type":"array","items":{"type":"string"},"description":"Database ID of the codes that were deleted because they were not included in the bulk import"},"updatedTemplates":{"type":"array","items":{"type":"string"},"description":"Database ID of the templates that were updated because they referenced the updated/deleted codes"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Code"},"description":"The codes that were imported/updated"},"errors":{"type":"array","items":{"type":"string","description":"Error messages"}}}}}},"CodeTypesBulkResponse":{"type":"object","properties":{"success":{"type":"boolean"},"dbResponse":{"type":"object","properties":{"insertedIds":{"type":"array","items":{"type":"string"},"description":"Array of code type ids that were inserted into the database"},"updatedIds":{"type":"array","items":{"type":"string"},"description":"Array of code type ids that were updated in the database"},"deletedIds":{"type":"array","items":{"type":"string","description":"Array of code type ids that were deleted from the database because they were not in the request"}},"unchangedIds":{"type":"array","items":{"type":"string","description":"Array of code type ids that were in the request but with the same values as in the database"}}}},"data":{"type":"array","items":{"$ref":"#/components/schemas/CodeType"}},"errors":{"type":"array","items":{"type":"string"},"description":"Array of errors that occurred during the bulk operation. Schema TBD"}}},"Code":{"type":"object","description":"Time and Billing codes used to track time entries (e.g. \"Research\", \"Drafting\", etc.)","required":["description","codeTypeId","code"],"properties":{"id":{"type":"string","description":"The auto-generated database id of the code. Use null when creating a new code. Required when updating an existing code."},"description":{"type":"string","description":"Description of the code (e.g. \"Research\")"},"codeTypeId":{"type":"string","description":"Database ID of the related code type"},"code":{"type":"string","description":"Identifier of the code (e.g. \"A101\")"}}},"CodeType":{"type":"object","description":"Code types are used to group codes together (e.g. \"Task\" code type contains \"Research\", \"Drafting\", etc. codes)","required":["description","selectionLabel"],"properties":{"id":{"type":"string","description":"The auto-generated database id of the code type. Use null when creating a new code type. Required when updating an existing code type."},"description":{"type":"string","description":"Description of the code type (e.g. \"Task\")"},"selectionLabel":{"type":"number","description":"Selection label number of the code type."}}},"Template":{"type":"object","description":"A template for creating timecards in the iTimekeep app","required":["name","templateType"],"properties":{"id":{"type":"string","description":"The auto-generated database id of the template"},"name":{"type":"string","description":"The name of the template. For firm templates, the name is unique for the firm (subscription). For user templates, the name is unique to the subscription/user."},"templateType":{"type":"string","description":"The type of the template. Must be either \"Subscription\" or \"User\"."},"matterId":{"type":"object","description":"The client matter ID of the template","properties":{"isLocked":{"type":"boolean","description":"Lock status of the matter indicating whether a timekeeper can change the value when using the template to create a timecard"},"value":{"type":"string","description":"The client matter ID of the template"}}},"workDescription":{"type":"object","description":"Work description (narrative) of the template","properties":{"isLocked":{"type":"boolean","description":"Lock status of the work description indicating whether a timekeeper can change the value when using the template to create a timecard"},"value":{"type":"string","description":"Work description (narrative) of the template"}}},"workHours":{"type":"object","description":"Work hours of the template","properties":{"isLocked":{"type":"boolean","description":"Lock status of the work hours indicating whether a timekeeper can change the value when using the template to create a timecard"},"value":{"type":"number","description":"Work hours of the template"}}},"codes":{"type":"array","description":"An array of codes for the template","items":{"type":"object","properties":{"isLocked":{"type":"boolean","description":"Lock status of the code indicating whether a timekeeper can change the value when using the template to create a timecard"},"value":{"$ref":"#/components/schemas/Code"}}}}}}},"parameters":{"subscriptionIdHeader":{"name":"x-itk-subscription-id","in":"header","required":true,"schema":{"type":"integer"},"description":"Firm's ITK subscription id"},"userIdHeader":{"name":"x-itk-user-id","in":"header","required":true,"schema":{"type":"integer"},"description":"User's ITK user id"},"userEmailHeader":{"name":"x-itk-user-email","in":"header","required":true,"schema":{"type":"string"},"description":"User's ITK user name (always the user's email address)"}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Enter the Bearer Authorization string as 'Bearer Generated-JWT-Token'"}},"responses":{"status401":{"description":"Authorization Bearer header missing or invalid"},"status403":{"description":"User is not authorized for roles required to access this API"}}},"tags":[{"name":"Codes","description":"Codes API for T&B billing codes"},{"name":"CodeTypes","description":"CodeTypes API for T&B billing code types, which map to the \"Code Type\" dropdowns in the iTimekeep app"},{"name":"Templates","description":"Templates API for CRUD operations on templates for creating timecards in the iTimekeep app"}]}