Overview
Getting started
The API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication and verbs.
To get started you need a Visma Tid account and an API-application. Follow the steps in the section below to create an API-application.
Creating an API-application
If you have an existing Visma Tid account and you're already signed in, you can just click on this link to navigate to the administration page where you manage your API-applications. Otherwise you can follow the steps below to get started.
- Login to your existing account or sign up for a 14-day free trial.
- Go to the administration panel by clicking on the cog-icon in the top right corner next to your profile. Note that this requires administrator permissions. If you don't see the cog-icon, you don't have administrator permissions.
- In the sidebar to the left, click on the "Integrationer" (Integrations) menu and then click on "API-applikationer" (API-applications).
- In the upper corner there is a button labeled "Lägg till" (Add), click it.
- Give your application a name and choose whose responsible for the API-application, then click the button labeled "Spara" (Save).
Authentication
Bearer token authentication is used for access to the API endpoints. Basic authentication is used to aquire access tokens.
Aquire access token
To aquire an access token, a request should be made to POST /v1/Auth/Token
with
the Authorization-header scheme set to Basic and the value should be the Base64-output of your application id and
secret joined by a colon (:).
Authorization: Basic bXlhcHBpZDpteWFwcHNlY3JldA==
Authenticate a request
To authenticate a request, the Authorization-header scheme is set to Bearer and the access token as the value.
Authorization: Bearer pk_00000000-0000-0000-0000-000000000000.pa_00000000-0000-0000-0000-000000000000
Important!
Your API-applications can carry many privileges, so be sure to keep the application id, secret and issued access tokens secure! Do not share these in publicly accessible areas such as GitHub, client-side code, and so forth.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail.
All API endpoints requires authentication unless specified otherwise. Failure to provide a valid acces token in a request
will result in a 401 Unauthorized
response.
Rate limiting
All access-tokens are subjected to rate limiting. This is determined on a per-request basis and is enforced when an access-token has made more than four (4) requests during a given second.
When in effect, the response code to your requests will be 429 Too Many Requests
,
with a response body telling you for how long you have to wait until the rate limiting is no longer in effect.
A Retry-After
header will also be sent along with the response if you prefer
to read the timeout from there.
The timeout is in seconds.
Status codes
A range of standard HTTP status codes are used by the API to inform the client of the result of their action.
200 OK
The status code 200 OK
is the most common status code
and is returned when the request was successful. The response body may contain data such
as an entity.
Examples to the right shows that a GET-request to /v1/Core/contacts/page=1 returns an object in its response whereas the DELETE-request does not.
400 BAD REQUEST
The status code 400 BAD REQUEST
is returned for any request where
the server cannot or will not process the request due to an apparent client error.
The "client error" may be missing required parameters, missing required properties in a request body, invalid parameter/property values and so forth.
401 UNAUTHORIZED
A 401 UNAUTHORIZED
response will be produced
when the client has failed to send the authentication header or if the
authentication token is invalid.
403 FORBIDDEN
A 403 FORBIDDEN
response will be produced
when either the API-application does not have the required permissions to
perform the action, or if the API-application has a list of allowed IP-addresses
and the machine making the request is not on that list.
404 NOT FOUND
A 404 NOT FOUND
response will be produced
when the resource URL does not exist.
429 TOO MANY REQUESTS
A 429 TOO MANY REQUESTS
response will be produced
when your access token has been requesting too many resources too fast.
500 INTERNAL SERVER ERROR
A 500 INTERNAL SERVER ERROR
response will be produced
when something has gone wrong when processing the request.
502 BAD GATEWAY | 503 SERVICE UNAVAILABLE
A 502 BAD GATEWAY
and/or 503 SERVICE UNAVAILABLE
responses will be produced when the API is restarting because of a hardware/software update or stopped
because of a planned maintenance.
Lists, sorting and filtering
Lists
Most resources in this API has an endpoint for fetching a list of that resource. These lists are divided into pages. You control which page to fetch and optionally how many items the page should include.
Sorting
You can also specify what property to sort lists by. The available properties to sort by are specific to each endpoint. You can also choose in what order to perform the sort, either in ascending order (a-z, 0-9) or in descending order (z-a, 9-0).
Filtering
Lists can also be filtered and is done so with the
filter.{filter-name}={value}
syntax.
Available filters are specific to each endpoint.
Datatype | Example value | |
---|---|---|
string | mystr | |
integer | 120 | |
decimal | 42.5 | |
boolean | false | |
integer array | 5,21,46,231 | |
datetime | 2021-01-01 14:00:00 |
List response
All list endpoints will return a standard list response comprised of properties which tells you where you are in the list and how much is left.
Core resources
Contacts
Available operations to the contact registry are listed to the right.
List contacts
Gets a list of contacts.
name
customerNumber
created
updated
ascending
descending
person
company
person
company
person
then this property represents a social security number, otherwise it represents a company's organizational number.
person
then this property represents the company that the person belongs to, otherwise it is null
company
then this property represents the parent company of the contact, otherwise it is null.
Get contact
Gets a single contact.
person
or company
.
person
then this property represents
a social security number, otherwise it represents a company's organizational number.
person
then this property represents
the company that the person belongs to, otherwise it is null.
For detailed description of properties, see id-name object.
company
then this property represents
the parent company of the contact, otherwise it is null.
For detailed description of properties, see id-name object.
Create contact
Creates a new contact.
person
or company
.
person
then this property represents
a social security number, otherwise it represents a company's organizational number.
person
then this property represents
the Id of the company that the person belongs to, otherwise it should be null.
company
then this property represents
the Id of the parent company of the contact, otherwise it should be null.
The response body will be equal to the response from Get contact.
Update contact
Updates an existing contact.
person
or company
.
person
then this property represents
a social security number, otherwise it represents a company's organizational number.
person
then this property represents
the Id of the company that the person belongs to, otherwise it should be null.
company
then this property represents
the Id of the parent company of the contact, otherwise it should be null.
Delete contact
Deletes an existing contact.
Invoices
Available operations to the registry of invoices are listed to the right.
List invoices
Gets a list of invoices.
createdDate
invoiceDate
customer
sum
sentToEconomySystem
ascending
descending
Get invoice
Gets a single invoice.
Set SentToEconomySystem
Sets the requested date value to the field SentToEconomySystem.
Logs
Available operations to the registry of logs are listed to the right.
List logs
Gets a list of logs.
createdDate
ascending
descending
project_All
project_Created
project_Updated
project_Added_Note
project_Deleted
project_Mentioned
project_Changed_Status
project_Updated_StartDate
project_Updated_EndDate
project_Removed_StartDate
project_Removed_EndDate
Offers
Available operations to the offers are listed to the right.
List offers
Gets a list of offers.
title
offerNumber
createdDate
updatedDate
ascending
descending
draft
locked
sentToCustomer
openedByCustomer
accepted
acceptedSigned
denied
draft
locked
sentToCustomer
openedByCustomer
accepted
acceptedSigned
denied
Download offer
Downloads the pdf version of the offer.
Opportunities
Available operations to the opportunities are listed to the right.
List opportunities
Gets a list of opportunities.
title
createdDate
updatedDate
ascending
descending
open
won
lost
open
won
lost
Get opportunity
Gets a single opportunity.
open
won
lost
Create opportunity
Create new opportunity.
Update opportunity
Updates an existing opportunity.
Project collections
Available operations to the registry of project collections are listed to the right.
List project collections
Gets a list of project collections.
name
projectNumber
ascending
descending
normal
absence
internal
Get next project number in collection
Gets the next project number in the selected project collection.
Get project collection
Gets a single project collection.
normal
absence
internal
Projects
Available operations to the registry of projects are listed to the right.
List projects
Gets a list of projects.
orderNumber
title
createdDate
updatedDate
ascending
descending
ongoing
fixedPrice
none
ongoing
fixedPrice
none
Get project
Gets a single project.
ongoing
fixedPrice
none
Create project
Creates a new project.
The created project will not have a booking project, meaning this will have to be added manually after the project is created.
All projects are created with the invoice method set to "Ongoing". This can also be altered after creation.
Update project
Updates an existing project.
Get next project number
Gets the next suggested project number.
List project comments
Gets a list of comments for a specific project.
createdDate
updatedDate
ascending
descending
Create project comment
Creates a new project comment.
Update project comment
Updates an existing project comment.
Delete project comment
Deletes the specified project comment.
Get project time calculation
Gets a time calculation for a specific project.
Task boards
Available operations to the registry of task boards are listed to the right.
List task boards
Gets a list of task boards.
createdDate
updatedDate
name
ascending
descending
Tasks
Available operations to the registry of tasks are listed to the right.
List tasks
Gets a list of tasks.
createdDate
title
startDate
endDate
ascending
descending
Create task
Creates a new task.
Update task
Updates an existing task.
Delete task
Deletes the specified task.
List task comments
Gets a list of comments for a specific task.
createdDate
ascending
descending
Create task comment
Creates a new task comment.
Update task comment
Updates an existing task comment.
Delete task comment
Deletes the specified task comment.
List task checklists
Gets a list of checklists for a specific task.
name
ascending
descending
Create task checklist
Creates a new task checklist.
Update task checklist
Updates an existing task checklist and its items.
Delete task checklist
Deletes the specified task checklist.
List task attachments
Gets a list of attachments for a specific task.
name
ascending
descending
Download task attachment
Downloads the specified attachment.
Create task attachment
Creates a new task attachment.
googleDrive
dropbox
oneDrive
Update task attachment
Updates an existing task attachment.
Delete task attachment
Deletes the specified task attachment.
Vacation requests
Available operations to the vacation requests are listed to the right.
List vacation requests
Gets a list of vacation requests.
fromDate
toDate
createdDate
updatedDate
attestedDate
deniedDate
ascending
descending
attested
awaitingAttest
denied
Material reports
Available operations to the registry of material reports are listed to the right.
List material reports
Gets a list of material reports.
sortOrder
articleNumber
title
createdDate
updatedDate
ascending
descending
Get material report
Gets a single material report.
Create material report
Creates a new material report.
Update material report
Updates the specified material report.
Delete material report
Deletes the specified material report.
Payment plans
Available operations to the registry of payment plans are listed to the right.
List payment plans
Gets a list of payment plans.
description
createdDate
updatedDate
ascending
descending
Supplier invoices
Available operations to the registry of supplier invoices are listed to the right.
List supplier invoices
Gets a list of supplier invoices.
invoiceNumber
invoiceDate
totalAmount
invoiceCostAddition
cost
createdDate
updatedDate
ascending
descending
Add unhandled supplier invoice
Add an unhandled supplier invoice.
Time reports
Available operations to the registry of time reports are listed to the right.
List time reports
Gets a list of time reports.
date
userName
hours
invoiceableHours
sentToAttestDate
attestedDate
createdDate
updatedDate
ascending
descending
project
internalProject
absenceProject
Get time report
Gets a single time report.
Create time report
Creates a new time report.
Update time report
Updates an existing time report.
Delete time report
Deletes the specified time report.
List user day statistics
Gets a list of users, containing time reporting information about each day of a date span.
name
ascending
descending
Admin resources
Absence projects
Available operations to the registry of absence projects are listed to the right.
List absence projects
Gets a list of absence projects.
name
ascending
descending
Activities
Available operations to the registry of activities are listed to the right.
List activities
Gets a list of activities.
name
createdDate
updatedDate
ascending
descending
Articles
Available operations to the registry of articles are listed to the right.
List articles
Gets a list of articles.
Defaults to material
if omitted.
all
allowance
material
equipment
addition
time
name
articleNumber
createdDate
updatedDate
ascending
descending
Get article
Gets an article.
Create addition article
Creates a new addition article.
Will be set to true if omitted.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Update addition article
Updates a addition article.
Will be ignored if omitted.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Create allowance article
Creates a new allowance article.
Will be set to true if omitted.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Update allowance article
Updates an allowance article.
Will be ignored if omitted.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Create equipment article
Creates a new equipment article.
Will be set to true if omitted.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Update equipment article
Updates an equipment article.
Will be ignored if omitted.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Create material article
Creates a new material article.
Will be set to true if omitted.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Update material article
Updates a material article.
Will be ignored if omitted.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Create time article
Creates new time article.
Will be set to true if omitted.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Update time article
Update a time article.
Will be ignored if omitted.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Maximum 50 characters.
Two decimals places allowed.
Maximum 200 characters.
Maximum 500 characters.
Two decimals places allowed.
Booking projects
Available operations to the registry of booking projects are listed to the right.
List booking projects
Gets a list of booking projects.
name
bookingNumber
isActive
startDate
endDate
createdDate
updatedDate
ascending
descending
Get booking project by id
Gets a single booking project.
Get booking project by booking number
Gets a single booking project.
Create booking project
Creates new booking project.
Will be set to true if omitted.