Timebeans API


Timebeans offers a powerful set of API that allows you to connect and integrate your Timebeans account with other applications and programatically get access to your Timebeans data and perform key actions. All Timebeans accounts include API access, including the free account.

Authentication

In order to access a Timebeans account via API the request must first be authenticated to ensure it is allowed by the user. Timebeans offers multiple ways for users to authenticate via the API.

Please browse the below article for a detail view on these different authentication options:

Timebeans API Authentication

API Methods

Timebeans API methods are REST based and are available at the following end-points. In each of the end-points below the "{{hostname}}" is the address of your Timebeans account/server. For example, if your Timebeans account is hosted at Timebeans secure cloud then your API hostname would be something like:

your-account.timebeans.com

On the other hand if you are hosting Timebeans at your local premises in-house then the hostname would be something like:

timebeans-app.myserver.com

The following API end-points are available. 

End-pointhttps://{{hostname}}/api/status
REST MethodGET
Pre-requisiteUser must be authenticated
DescriptionChecks the API and user's authentication status
ParametersNone
Returned Object TypeStatus JSON Object
Returned Object
  • fullName (the full name of the authenticated user)
  • emailAddress (the unique email address of the authenticated user)

 

End-pointhttps://{{hostname}}/api/projects
REST MethodGET
Pre-requisiteUser must be authenticated
DescriptionGet all projects the user is a member of
ParametersNone
Returned Object TypeJSON Array
Returned Object
  • projectId (a unique numeric ID of the project)
  • projectName (the name of the project)
  • status (a text value representing the status of the project)

 

End-pointhttps://{{hostname}}/api/projects
REST MethodPOST
Pre-requisiteUser must be authenticated and either in a PM or a higher role 
DescriptionCreates a new project
Parameters

New project JSON object:

  • ProjectName (required, name of the new project)
  • ClientID (required, numeric based client ID for the new project)
  • BillingStandardHourlyRate (required, the decimal project billing rate. If zero, the project will set as non-billable)
Returned Object TypeNewly created project
Returned Object
  • projectId (a unique numeric ID of the newly created project)
  • projectName (a the name of the newly created project)

 

End-pointhttps://{{hostname}}/api/clients
REST MethodGET
Pre-requisiteUser must be authenticated and either in a PM or a higher role 
DescriptionGet all clients
ParametersNone
Returned Object TypeJSON Array
Returned Object
  • clientID (a unique numeric ID of the client)
  • clientName (the name of the client)

 

End-pointhttps://{{hostname}}/api/expenses/{{ProjectID}}
REST MethodGET
Pre-requisiteUser must be authenticated
DescriptionGet all expenses the user has added in the past 7 days
ParametersProjectID (required, the numeric ID of the project to get expenses for) 
Returned Object TypeJSON Array
Returned Object
  • expenseID (the numeric ID of the project)
  • expenseDate - (the date of the expense in format: yyyy-mm-dd)
  • projectID (the numeric ID of the project for which the expense is recorded)
  • projectName (the name of the project for which the expense is recorded)
  • expenseTypeID (the numeric ID of the expense type/category)
  • expenseType (the expense type/category)
  • amount (the decimal expense amount)
  • status (the text based status of the expense)
  • currencySymbol (the currency symbol of the expense amount)
  • isBillable (if the expense is billable to the client)
  • description (a short description of the expense)

 

End-pointhttps://{{hostname}}/api/expensetypes
REST MethodGET
Pre-requisiteUser must be authenticated
DescriptionGet all expense types
ParametersNone
Returned Object TypeJSON Array
Returned Object
  • expenseTypeID (a unique ID of the expense type)
  • title (the expense type)
  • statusID (a numeric flag representing if the expense type is active or not. A value greater than zero means active)

 

End-pointhttps://{{hostname}}/api/expenses
REST MethodPOST
Pre-requisiteUser must be authenticated
DescriptionCreates a new expense
Parameters

New expense object

  • expenseTypeID (required, a numeric ID representing the type of the expense)
  • projectID (required, a numeric project ID)
  • totalAmount (required, a decimal value for the expense amount)
  • expenseDate (optional expense date in format: yyyy-mm-dd, if not provided current date will be used)
  • description (optional short description of the expense)
Returned Object TypeNewly saved expense object
Returned Object
  • expenseID (a unique numeric ID of the newly saved expense)
  • totalAmount (a decimal value of the total amount of the expense)

 

End-pointhttps://{{hostname}}/api/invoices
REST MethodGET
Pre-requisiteUser must be authenticated and either in a PM or a higher role 
DescriptionGet all invoices created in the past 7 days
ParametersNone
Returned Object TypeJSON Array
Returned Object
  • InvoiceID (a unique numeric ID of the invoice)
  • InvoiceNumber (a unique alpha-numeric invoice number)
  • ClientID (a numeric ID representing the client for this invoice)
  • ClientName (the name of the client for this invoice)
  • IssueDate (the date when this invoice is issued/submitted to the client in format: yyyy-mm-dd)
  • DueDate (the date when this invoice is due for payment in format: yyyy-mm-dd)
  • PONumber (the alpha-numeric PO number associated with this invoice)
  • TotalAmount (the total due amount of the invoice after applying any discount and tax)
  • BalanceRemaining (the balance remaining on the invoice)
  • CurrencySymbol (the currency symbol of the amount)

 

End-pointhttps://{{hostname}}/api/tasks/{{ProjectID}}
REST MethodGET
Pre-requisiteUser must be authenticated and a member of the project
DescriptionGet all tasks in the project.
ParametersProjectID (required, the numeric ID of the project to get tasks for) 
Returned Object TypeArray
Returned Object
  • projectID (the project ID to which the task belongs to)
  • projectName (the project name to which the task belongs to)
  • taskID (the unique numeric ID of the task)
  • taskTitle (the name of the task)

 

End-pointhttps://{{hostname}}/api/tasks
REST MethodPOST
Pre-requisiteUser must be authenticated and either in a PM or a higher role 
DescriptionCreates a new task
ParametersNew task object
Returned Object Type

The newly created task object

  • projectID (required, the numeric ID of the project to which this task belongs to)
  • taskTitle (required, the title of the task)
  • isBillable (optional, if the task is billable. Will be automatically set to false if the project is non-billable)
Returned Object
  • taskID (the unique ID of the newly created task)
  • taskTitle (the title of the newly created task)

 

End-point https://{{hostname}}/api/timesheet/{{mode}}/{{startdate}}
 
REST Method GET 
Pre-requisite User must be authenticated 
Description Get timesheet entries for the day or week from the given start date 
Parameters 
  • mode (required, either "day" or "week")
  • startdate (optional date in format: yyyy-mm-dd used as a timesheet entry date or week start date
Returned Object Type Array 
Returned Object 
  • entryDate (the timesheet entry date in the format: yyyy-mm-dd)
  • entryID (a unique long numeric ID of the entry)
  • taskID (the taskID for which the time entry was recorded)
  • taskTitle (the task title for which the time entry was recorded)
  • projectID (the projectID to which the task belongs to)
  • projectName (the project name to which the task belongs to)

 

End-point https://{{hostname}}/api/timesheet
 
REST Method POST 
Pre-requisite User must be authenticated 
Description Creates a new timesheet entry 
Parameters 
  • taskID (required, numeric Task ID to log the time entry for)
  • timeSpanAsMinutes (required, numeric value representing the minutes)
  • description (optional, a short description of the time entry)
Returned Object Type None 
Returned Object None