/
Microbizz GO API specification

Microbizz GO API specification

Jul 13, 2022

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:

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:

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

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.