Microbizz GO API specification

Note regarding previous API’s

Please note that this API is different from the core Microbizz API.

This API is a proper restful API where all objects in the API follows the exact same command structure.

This should lead to a more consistent experience.

Basic API structure

The API is structured like this:

https://go-api.microbizz.dk/api.php/OBJECT_NAME/OBJECT_ID

The OBJECT_NAME will always refer to the object type you are trying to access, and if you are working with a specific instance of the object, this can be identified with the OBJECT_ID

Objects are manipulated using the HTTP protocol where we use the following three methods:

Method:	Use:
GET	Used to retrieve information about an object.
POST	Used to post information about an object.
DELETE	Used to delete information about an object.

When using GET, parameters (if any) should be supplied in the URL query.

When using POST, the POST body should be a proper formed JSON document containing the data.

When updating objects all fields which are omitted are considered to be left as they are, so you only need to pass the fields you would actually like to change.

The API will always respond with HTTP status codes. The most common codes are:

Code:	Meaning:
200	OK. The operation completed as expected.
201	Created. The operation completed as expected, and something was created.
400	Bad request. Your request wasn’t understood.
401	Unauthorized. You must supply a valid access token to enter.
403	Forbidden. You are not allowed to see the requested data, with the supplied access token.
404	Not found. The requested data was not found.
405	Invalid method. The specified method is not allowed on this endpoint.
500	Internal server error. Something went wrong in the application. Refer to the error message.

If an error occur an extended error message is provided as a JSON document.

If the command succeeds the requested data is provided as a JSON document.

API security

In order to use most API commands an access token is required. The value of this token can either be supplied as a COOKIE named access_token or it can be supplied in a GET parameter also named access_token.

An access token is returned when registering with the API. If this token is lost or expires, a new access token can be retrieved using the login object to login with an user name and password.

An access token can be expected to expire anytime, so the app should constantly monitor the API for 401 errors and request a new login from the user if this occurs, in order to obtain a new access token.

Handling files and images

In order to add files and images to the API, a special JSON object must be passed to the field containing the file or image

action	Either "add" to add a new file to the field or "remove" to remove the file entirely.
filename	The filename of the file to add. Can be omitted when using remove.
mimetype	The mimetype of the file content. Can be omitted when using remove.
binary	A base64 encoded string containing the file binary data. Can be omitted when using remove.

When fetching data from the API all file fields will contain an internal ID representing the file. In order to retrieve the binary data behind the file, you need to set the include_binary_data GET variable to 1. Please be aware that using this can yield very large responses.

API reference.

Common objects

Assignment

Endpoint:

https://go-api.microbizz.dk/api.php/assignment

Methods allowed:

GET POST DELETE

Purpose:

An assignment binds a task to a user to indicate that the user is assigned to the task.

assignment_id	Assignment ID. Key.
task_ref	Task ID
user_ref	User ID

Connection

Endpoint:

https://go-api.microbizz.dk/api.php/connection

Methods allowed:

GET POST DELETE

Purpose:

A connection is a connection between a company and a foreign company, showing that the two are connected.

connection_id	Connection ID. Key.
company_ref	Company ID.
foreigncompany_ref	Foreign company ID.
outgoing_connection	Indicates if the connection is outgoing. Otherwise it is ingoing.
connection_status	The status on the connection.
text	Additional text.

Cancel subscription

Endpoint:

https://go-api.microbizz.dk/api.php/cancel_subscription

Methods allowed:

POST

Purpose:

Used for terminating subscriptions. The object ID should be a company id as below.

Company

Endpoint:

https://go-api.microbizz.dk/api.php/company

Methods allowed:

GET POST

Purpose:

The companies are the companies that the users are working for, and each user only have access to exactly that company

company_id	Company ID. Key.
vat_id	Company VAT id.
companyname	Company name.
branch	Company branch type.
address	Address.
address2	Address 2.
zip	Zip.
city	City.
country	Country.
phone	Company phone.
email	Company email.
contactperson	Company contact person name.
additionaltext	Additional description of company.

Current user

Endpoint:

https://go-api.microbizz.dk/api.php/current_user

Methods allowed:

GET

Purpose:

Always return the current user as a single user object. See user endpoint for data format.

Device ID

Endpoint:

https://go-api.microbizz.dk/api.php/device_id

Methods allowed:

POST

Purpose:

Use this to post device IDs for push communication. The device ID will be added to the current user. Feel free to post the same device id several times - this will just update the last change date of it. Write-only

platform_name	Either android or ios
device_id_string	The device ID as a string.

When the system sends a push message, it may include data with the message. The data is may include the following fields:

related_object	Details about a related object
related_object.object	The object type, eg task or tasknote etc.
related_object.object	The object ID

Foreigncompany

Endpoint:

https://go-api.microbizz.dk/api.php/foreigncompany

Methods allowed:

GET

Purpose:

Foreign companies are companies that a company can be connected to, using a Connection. One company can be connected to many foreigncompanies

foreigncompany_id	Foreign company ID. Key.
vat_id	Company VAT id.
companyname	Company name.
branch	Company branch type.
address	Address.
address2	Address 2.
zip	Zip.
city	City.
country	Country.
phone	Company phone.
email	Company email.
contactperson	Company contact person name.
additionaltext	Additional description of company.

Notification

Endpoint:

https://go-api.microbizz.dk/api.php/notification

Methods allowed:

GET DELETE POST

Purpose:

App notifications.

notification_id	Notification ID. Key.
user_ref	Reference to user owning this notification.
text	The text of the notification.
is_read	Can be used to indicate if the notification is read by the user.
related_object	The notification can be related to another object. If it is not, this field is null.
related_object.object	If a notification is related to another object, then this field describe the endpoint from which such an object originates.
related_object.id	If a notification is related to another object, this field contains the ID of that object.

Notification types

Notification	Comment	Usertype	Text	Action when pressed
New task	A new task is sent to an admin. Status NEW	Admin	%contractorname% has sent you the task %taskname%	Open the specific task
New note (external)	A note on a task from a contractor is written/replied	Admin	%contractorname% has sent you a new note on the task %taskname%	Open the specific note
New note (internal)	A note on a task from an internal user is written/replied	Admin, user	%Username% has sent you a note on the task %taskname%	Open the specific note
New connection	A new connection request has been sent to the admins	Admin	%contractorname% has sent you a new connection request	Open clients menu
Assigned to task	The user has been assigned to a task	Amin, user	%username% has assigned you to the task %taskname%	Open the specific task

Payment URL

Endpoint:

https://go-api.microbizz.dk/api.php/payment_url

Methods allowed:

GET

Purpose:

Get an URL for making payments.

url	URL for making payment.

Subscription information

Endpoint:

https://go-api.microbizz.dk/api.php/subscription_info

Methods allowed:

GET

Purpose:

Get information about subscription

got_subscription	Return true if a subscription is attached to the current user/company. The rest of the fields aren't returned, if this is false.
renewing	Returns true if the subscription is configured for renewing automatically.
end_date	The current subscription expire date (date of renewal) on form YYYY-MM-DD or false if no such date.
unit_price	Price for a single user.
total_price	Price of all users attached to current company.

Task

Endpoint:

https://go-api.microbizz.dk/api.php/task

Methods allowed:

GET POST

Purpose:

A task which is given from the foreign company to the company.

task_id	Task ID. Key.
company_ref	Company ID.
foreigncompany_ref	Foreign company ID.
title	Task title.
description	Description.
startdate	Start date.
deadline	Deadline date.
closeddate	Closed date.
address	Address.
address2	Address 2.
zip	Zip.
city	City.
country	Country.
latitude	Task latitude
longitude	Task longitude
contactperson	Contact person name.
phone	Contact person phone.
status	Task status.
billing_address	Billing address.
billing_address2	Billing address 2.
billing_zip	Billing zip code
billing_city	Billing city
billing_country	Billing country

Task File

Endpoint:

https://go-api.microbizz.dk/api.php/taskfile

Methods allowed:

GET POST DELETE

Purpose:

A file attached to a task.

file_id	File ID. Key.
task_ref	Task ID.
folder	Folder of file as string ie. "subfolder/subsubfolder".
folder_ref	Reference to containing folder object. If this is null the file is in the root folder. On new objects don't set this. Instead specify correct folder in folder attribute.
content	File information.

Task Folder

Endpoint:

https://go-api.microbizz.dk/api.php/taskfolder

Methods allowed:

GET

Purpose:

A folder attached to a task. Please note that this API is not writeable - folders are built automatic by specifying the folder parameter on a file.

folder_id	Folder ID. Key.
task_ref	Task ID.
parent_folder	ID of parent folder. If this is 0 then the parent is the root folder.
folder_name	Name of this folder ie. "subsubfolder".
complete_path	Complete path to folder ie. "subfolder/subsubfolder".

Task Note

Endpoint:

https://go-api.microbizz.dk/api.php/tasknote

Methods allowed:

GET POST DELETE

Purpose:

A note attached to a task.

note_id	Note ID. Key.
task_ref	Task ID.
parent_note_ref	Parent note ID. There are only one note level, so a child note cannot also be a parent note.
author_name	Author of this note.
content	Note text.
read_by	User ID array. ID of all users who have read the note.
is_public	Is note public for connect?

Task Note File

Endpoint:

https://go-api.microbizz.dk/api.php/tasknotefile

Methods allowed:

GET POST DELETE

Purpose:

This is used for files attached directly to notes.

file_id	File ID. Key.
note_ref	Note ID.
task_ref	Task ID. Convenience. Read only.
content	File information.

Task Note + Task note files

Endpoint:

https://go-api.microbizz.dk/api.php/tasknote_tasknotefile

Methods allowed:

GET

Purpose:

This is a convenience endpoint for fetching task notes and task note files in one call. The API is read-only and a task id should be specified as the object id. The endpoint will then return all task notes and all task note files related to that task embedded in each note.

Data structure is the same as Task Note, where each object will have a field tasknotefiles containing the task note files. These objects will correspond to the data structure from Task Note Files.

User

Endpoint:

https://go-api.microbizz.dk/api.php/user

Methods allowed:

GET POST DELETE

Purpose:

The users are the users of the app. An administrator user has access to edit and delete other users.

user_id	User ID. Key.
username	Username (email).
password	Password (writeonly).
user_type	1 = administrator. 2 = normal user. 3 = pending user.
subscription_valid	Indicate if the user subscription is valid.
company_ref	A reference to the company to which this user is attached.
fullname	Full name.
phone_number	Phone number.
picture	Profile picture.
last_email_date	Date for last invitation email.
number_of_mails	Number of invitation emails sent.

Creating new users.

A new user should be created with user_type = 3 (pending user). This will cause the backend to initiate the registration procedure. When the procedure is complete, the user will become a normal user.

Please note that pending users should not be shown in the app.

Registration and login commands.

Endpoint:	https://go-api.microbizz.dk/api.php/login
Methods allowed:	GET
Purpose:	Used to obtain a new access token by providing an existing username and password. This endpoint can be accessed without providing an access token.
Input:	{username: USER NAME, password: PASSWORD}
Output:	{access_token: ACCESS_TOKEN}

Register

Endpoint:	https://go-api.microbizz.dk/api.php/register
Methods allowed:	POST
Purpose:	Register a new company along with their initial user. Return an access token which can be used to subsequent query the API. This endpoint can be accessed without providing an access token.
Input:	{company: {COMPANY OBJECT}, user: {USER OBJECT}}
Output:	{access_token: ACCESS_TOKEN}

Forgot password

Endpoint:	https://go-api.microbizz.dk/api.php/f orgot_password
Methods allowed:	POST
Purpose:	Send a forgot password mail to the user who matches the given email. If no user matches, nothing happens.
Input:	{email: {EMAIL TO SEND TO}}
Output:	{status: true}

Technical flow.

Initial registration.

New user registers with the application, by creating a new company and an initial user.

This is done using the endpoint register.

If more users are to be created this is done using the user endpoint, where user modification can also be done. So one or more user can exist under one company.

The company information can be changed using the company endpoint.

Receiving a new connection request.

The endpoint connection can be monitored for new connection requests. Connections are managed using the status variable called connection_status.

Incoming connection will have a status of 1, and can be answered providing the following status’es:

2	Accept request
3	Reject request
4	Block request (prevent requester for trying again).

Sending a connection request.

A connection request can be sent to any foreign company (as found using the foreigncompany endpoint) by creating a new connection with a status of 1.

The status will be updated to one of the values above to indicate the response from the counterpart.

Receiving task shares.

Task are received from the task endpoint and status on tasks are communicated using the field status.

Status can have several values:

0	No request. The task is just shared, so it can be viewed in the app.
1	Send quote. When this is received the status should be changed to 11. The app user should send a quote by taking a picture or writing a note, and thereafter the status should be updated to 2.
2	Quote sent. This is always set by the app.
3	Perform task. When this is received the status should be changed to 31. The app user should carry out the task and when done the status should be updated to 4
4	Task done. This is always set by the app.
11	Send quote (acknowledge). This is the response to 1 and is always set by the app.
23	Task accepted. When this is received the task is accepted as done.
31	Perform task (acknowledge). This is the response to 3, and is always set by the app.
99	Task rejected. This indicates that the task is rejected. This can be set by both parties.

Assigning users to tasks

Users can be assigned to tasks using the assignment endpoint. Only the app uses these.

Files and notes on tasks

Files and notes can be received and send on tasks using the file and note endpoint.

App terms vs. technical terms.

Filtering tasks

App term	Meaning	API status	Notes
All	All tasks.	*	For admin = Shows all tasks in the app For user = Shows all the task for the user
Overdue	Task is over deadline.	11,31	For admin = Shows all tasks in the app For user = Shows all the task for the user Deadline is set on task, and before today.
Unassigned	The task has been accepted by the subcontractor. The offer has been accepted by the contractor. Or all assigned users were removed	11,31	Only visible for admin. Task must not be assigned to anyone. (Task not mentioned in Assignment endpoint).
New	The task is new and awaits admin approval or rejection	1,3	Only visible for admin

Task status

App term	Meaning	API status	Notes
New	The task is new and awaits admin approval or rejection	1,3	Only visible for admin
Rejected	The task has been rejected by the admin	99	Only visible for admin
Pending offer	The contractor is awaiting for an offer from the subcontractor	11	Only visible for admin (Not in use for now)
Waiting offer feedback	The subcontractor has sent the offer and waits for the contractor to accept	2	Only visible for admin (Not in use for now)
Unassigned	The task has been accepted by the subcontractor. The offer has been accepted by the contractor. Or all assigned users were removed	11,31	Only visible for admin. Task must not be assigned to anyone. (Task not mentioned in Assignment endpoint).
Ongoing	Task is assigned and can be executed by the subcontractor employee	31
Finished	Task is marked done by the app user	4

Offline functionality (work in progress)

User perspective

When being offline the user should experience that navigation in the app is still possible with data already synched.

It should be visible that connection is not available, and that there are commands waiting to be sent.

Functions available offline

When the app is offline, it should be visible for the user.

When performing some actions, the user should be informed that the action is queued and will be sent later when connection is available again.

This will be represented with the last column.

OBS. In general the app should show information as per the last time it was synchronized.

Module	Function	UI information
Task - Assign	Assign tasks	x
Task - Notes	Viewing notes
Task - Notes	Write replies	x
Task - Files	Viewing files
Task - Files	Uploading files/pictures	x
Task - Status change	Changing status on a task. For example finishing it

Note regarding previous API’s

Basic API structure

API security

Handling files and images

API reference.

Common objects

Assignment

Connection

Cancel subscription

Company

Current user

Device ID

Foreigncompany

Notification

Notification types

Payment URL

Subscription information

Task

Task File

Task Folder

Task Note

Task Note File

Task Note + Task note files

User

Creating new users.

Registration and login commands.

Login

Register

Forgot password

Technical flow.

Initial registration.

Receiving a new connection request.

Sending a connection request.

Receiving task shares.

Assigning users to tasks

Files and notes on tasks

App terms vs. technical terms.

Filtering tasks

Task status

Offline functionality (work in progress)

User perspective

Functions available offline