Get started with Conta’s API

Conta is a web based accounting system encompassing a number of services, including invoicing, accounting, and more. Through our API, other systems can interact with these features.

Each API key is linked to a user in Conta, with the same access level as that user. This means that the key can access the same services, organizations and data as the user who created it, where external routes are available.

Usage requires a subscription plan

An active subscription to Conta’s services is required in order to use the API gateway. 

Access to individual features may depend on the chosen subscription plan. Certain API features may be unavailable if the chosen subscription does not include access to them.

Authentication

Access to the API gateway is granted via API keys.

API keys can be created in the Conta app under Settings -> User account -> Manage API keys (Administrer API-nøkler)

The API key needs to be sent with each API call as an HTTP header: ‘apiKey’.

Organization access

The API keys will have the same level of access to the system as the user creating the key.

One user can have access to multiple organizations (businesses/virksomheter) in the system, so it is required to specify the organization id in the URL for most of the APIs.

Environments

Base URI’s for API access:

• Production: https://api.gateway.conta.no
• Sandbox: https://api.gateway.conta-sandbox.no

Swagger documentation:

• Production: http://docs.gateway.conta.no
• Sandbox: http://docs.gateway.conta-sandbox.no

Free sandbox environment

Our sandbox development environment is available free of charge. The sandbox environment is not capable of sending emails, so you can safely use it to test your integrations.

The free sandbox environment is available at:

https://app.conta-sandbox.no

To gain access to the sandbox environment:

• Register an account for free on the sandbox website by clicking the link above.

• Email customer support at [email protected] to request your email verification link so you can validate your account and enable your access to the sandbox environment.

Getting started with Conta’s API gateway

1. Create a Conta Subscription

Sign up for the Sandbox environment to test your queries without any risk of modifying your data.

2. Create an API key

Log into the web and go to Settings -> User account -> Manage API keys (Administrer API-nøkler)

3. Test your calls using Swagger in the Sandbox environment.

Our swagger documentation supports testing the queries.

4. Call an API using the API key an HTTP ‘apiKey’ header

Use the base path of the environment (see Environments above) + the relative route of the API you are going to call. 

Send the API key as ‘apiKey’ HTTP header.

Simple example

To call an API, use the base path of the environment (see Environments above) + the relative route of the API you are going to call. Here is a simple CURL request to get information about a customer with id=123 from the organization with id=11:

Example Request:

Example Response:

Request Structure and HTTP status codes.

Conta API is a REST api based on JSON data type. An HTTP method of the request is used to define the action.

HTTP request methods:

HTTP method	Description
POST	Create an object
GET	Get an object or a list of objects
PUT	Update an object
DELETE	Delete an object

Examples:

• POST /invoice/organizations/11/customers – create a customer for org id = 11.
• GET /invoice/organizations/11/customers?q=Lisa – search for customers  starting with ‘Lisa’.
• GET /invoice/organizations/11/customers/123 – get a customer for org id = 11 and customer id = 123.
• PUT /invoice/organizations/11/customers/123 – update customer for org id = 11 with customer id = 123.
• DELETE /invoice/organizations/11/customers/123 – delete customer for org id = 11 with customer id = 123.

HTTP Response Status Codes

HTTP response code can be used to determine if the request was a success or an error.

HTTP Status Code	Description	Cause
200	Success
400	Bad Request	Generic client error – something is wrong or missing in the request.Check the response data for more information on the error.
401	Unauthorized	Not logged in.
403	Forbidden	Access to a resource is not allowed.
404	Not Found	Object does not exist / URL not found.
405	Method Not Allowed	The HTTP method is not available on the URL.Check if you are using the correct request method.
409	Conflict	Trying to create an object that already exists (duplicate).
413	Payload Too Large	Uploaded data is too large.
422	Unprocessable Entity	Uploaded content was not recognized.
500	Internal Server Error	Server error. Contact customer support for more information.
503	Service Unavailable	Service is currently unavailable, try again later.

HTTP Error Response Data.

In case of an error, the response data usually contains detailed information about the error that can be used to correct the request.

It is expected that the client system verifies the data before sending it to Conta, and does not rely on Conta’s validation. However, this extra information can be used for debugging to understand what went wrong.

Example of 401 error:

Search and List APIs.

Most of the list API’s support a full-text search by multiple fields using a partial word match. List APIs usually also support paging and sorting arguments.

Parameter	Description
q	A full-text query for partial word match.
hits	Number of items per page, starting with 0 for the first page.
page	Page number to return.
sort	Field name to sort by.

Example: list of customers for org id = 11, starting with ‘Lisa’, page 3 with 10 items per page (items 21-30), ordered by id.

GET <base_url>/invoice/organizations/11/customers?q=Lisa&hits=10&page=2&sort=id

NOTE: Not all fields are supported for full text search and sorting. You can test your queries using Swagger.

Usage Examples

Here are some usage examples of Conta’s API.

Get Your Organization ID

In order to use most of other API’s, you need to get the id of your organization (business) to use it later to include it in the URL’s.

You can get the list of organizations you have access to using the Organizations List API.

Example CURL request:

Example response:

Send an Invoice by Email

This example shows how to create an invoice and send it to an email recipient. Invoice recipients list contains a single recipient with type EMAIL.

API URL contains the organization id to create the invoice for (see previous example on how to find your organization id).

Example request data:

Send an Invoice by EHF

In order to send an invoice by EHF, you need to verify if the customer you are trying to send it to can receive EHF. 

Using the EHF recipient lookup API you can verify if an organization number is a valid EHF recipient.

The value of ‘canReceiveEhf30’ field in the response indicates if an organization can receive EHF 3.0 invoices and credit notes.

Example CURL request:

Example response:

Once you have verified that the organization can receive EHF, you can send the invoice by specifying the ‘EHF’ recipient type and the organization number in the invoiceRecipients list.

Example request data:

Create a customer

You need to create a customer to send invoices to. Customers can be individuals or businesses created using the Create Customer API.

Example request individual customer:

Example request organization customer:

Create an Invoice draft

In some scenarios you may not want to send the invoice right away. 

You can create an Invoice Draft using the API, and later review it and send the actual invoice using Conta’s web interface.

Example request data:

Bookkeeping transactions

If you are using Conta Regnskap, you can create any kind of transaction using the Tansactions-Advanced API.

You can either send the transaction lines with Credit and Debit, or as separate lines with only Credit and only Debit.

Create Transaction – Single Line

Example of creating a manual transaction with a single line for debit and credit amounts. When the data is saved, it will be split automatically into separate transaction lines.

Example request data:

Create Transaction – Multiple Lines

Example registering purchase in Conta Regnskap as a custom transaction with separate lines for Debit and Credit.

Example request data: