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.

405Invalid 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

actionEither "add" to add a new file to the field or "remove" to remove the file entirely.
filenameThe filename of the file to add. Can be omitted when using remove.
mimetypeThe mimetype of the file content. Can be omitted when using remove.
binaryA 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_refTask 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_refCompany ID.

foreigncompany_ref

Foreign company ID.

outgoing_connectionIndicates if the connection is outgoing. Otherwise it is ingoing.
connection_statusThe status on the connection.
textAdditional 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_idCompany VAT id.

companyname

Company name.

branch

Company branch type.

address

Address.

address2Address 2.
zipZip.
cityCity.
countryCountry.
phoneCompany phone.
emailCompany email.
contactpersonCompany contact person name.
additionaltextAdditional 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_stringThe 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.objectThe object type, eg task or tasknote etc.
related_object.objectThe 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_idCompany VAT id.

companyname

Company name.

branch

Company branch type.

address

Address.

address2Address 2.
zipZip.
cityCity.
countryCountry.
phoneCompany phone.
emailCompany email.
contactpersonCompany contact person name.
additionaltextAdditional 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_refReference to user owning this notification.

text

The text of the notification.

is_readCan be used to indicate if the notification is read by the user.
related_objectThe notification can be related to another object. If it is not, this field is null.
related_object.objectIf a notification is related to another object, then this field describe the endpoint from which such an object originates.
related_object.idIf a notification is related to another object, this field contains the ID of that object.
Notification types
NotificationCommentUsertypeTextAction when pressed
New taskA new task is sent to an admin. Status NEWAdmin%contractorname% has sent you the task %taskname%Open the specific task
New note (external)A note on a task from a contractor is written/repliedAdmin%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/repliedAdmin, user%Username% has sent you a note on the task %taskname%Open the specific note
New connectionA new connection request has been sent to the adminsAdmin%contractorname% has sent you a new connection requestOpen clients menu
Assigned to taskThe user has been assigned to a taskAmin, 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.

renewingReturns true if the subscription is configured for renewing automatically.
end_dateThe current subscription expire date (date of renewal) on form YYYY-MM-DD or false if no such date.
unit_pricePrice for a single user.
total_pricePrice 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_refCompany ID.

foreigncompany_ref

Foreign company ID.

titleTask title.
descriptionDescription.
startdateStart date.
deadlineDeadline date.
closeddateClosed date.
addressAddress.
address2Address 2.
zipZip.
cityCity.
countryCountry.
latitudeTask latitude
longitudeTask longitude
contactpersonContact person name.
phoneContact person phone.
statusTask status.
billing_addressBilling address.
billing_address2Billing address 2.
billing_zipBilling zip code
billing_cityBilling city
billing_countryBilling 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_refTask ID.

folder

Folder of file as string ie. "subfolder/subsubfolder". 

folder_refReference 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.
contentFile 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_refTask ID.
parent_folderID of parent folder. If this is 0 then the parent is the root folder.

folder_name

Name of this folder ie. "subsubfolder". 

complete_pathComplete 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_refTask ID.

parent_note_ref

Parent note ID. There are only one note level, so a child note cannot also be a parent note. 

author_nameAuthor of this note.
contentNote text.
read_byUser ID array. ID of all users who have read the note.
is_publicIs 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_refNote ID.

task_ref

Task ID. Convenience. Read only.

contentFile 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.

usernameUsername (email).

password

Password (writeonly).

user_type

1 = administrator.

2 = normal user.

3 = pending user.

subscription_validIndicate if the user subscription is valid.
company_refA reference to the company to which this user is attached.

fullname

Full name.

phone_numberPhone number.
pictureProfile picture.
last_email_dateDate for last invitation email.
number_of_mailsNumber 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.

Login

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/forgot_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.

23Task 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 termMeaningAPI statusNotes
AllAll tasks.*
  • For admin = Shows all tasks in the app
  • For user = Shows all the task for the user
OverdueTask 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.

UnassignedThe 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).

NewThe task is new and awaits admin approval or rejection1,3
  • Only visible for admin

Task status

App termMeaningAPI statusNotes
NewThe task is new and awaits admin approval or rejection1,3
  • Only visible for admin
RejectedThe task has been rejected by the admin99
  • Only visible for admin
Pending offerThe contractor is awaiting for an offer from the subcontractor11
  • Only visible for admin
  • (Not in use for now)
Waiting offer feedbackThe subcontractor has sent the offer and waits for the contractor to accept 2
  • Only visible for admin
  • (Not in use for now)
UnassignedThe 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).

OngoingTask is assigned and can be executed by the subcontractor employee31
FinishedTask is marked done by the app user4

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. 

ModuleFunctionUI information
Task - AssignAssign tasksx
Task - NotesViewing notes
Task - NotesWrite repliesx
Task - FilesViewing files


Task - FilesUploading files/picturesx
Task - Status changeChanging status on a task. For example finishing it