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.
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:
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:
Manage Invoice Payments
Create Payment
A payment in the Conta app may be linked towards one or multiple invoices.
Only simple single-part payments can be created using the API Gateway.
Here is an example creating a simple payment for an invoice with id=44.
Example Request:
POST https://api.gateway.conta-sandbox.no/invoice/organizations/1/invoices/44/payments
Get List of Payments for an Invoice
Below is an example of a payment list for an invoice with id=44 containing one single-part payment, and one automatic bank payment for two invoices.
Example CURL Request:
Example response:
Deleting a Payment
Request CURL Example:
curl -X ‘DELETE’ \
‘https://api.gateway.conta-sandbox.no/invoice/organizations/1/payments/22’ \
-H ‘apiKey: APIKEY’
Credit an Invoice
The following API allows crediting full invoice.
Below is an example of crediting an invoice with invoice id=44.
Example Request Data:
POST https://api.gateway.conta-sandbox.no/invoice/organizations/1/invoices/44/credit-note