About the service

The API supports the submission of documents.

Norwegian Customs now makes it possible to submit relevant supporting documentation for declarations in advance, making it available to customs before the goods arrive at the border. This is intended to reduce the number of times it will be necessary for Norwegian Customs to contact the submitter for document inspection, as the relevant documentation is already available.

We urge as many Digitoll and direct customs clearance users (those who declare against units 441002 and 441003) as possible to use this API to submit supporting documentation related to the customs declaration. Documents such as invoices, permits, freight invoices, proof of origin documentation, or waybills can be submitted unsolicited and in advance.

The documents may also be submitted via the API when Norwegian Customs requires a document inspection, if they are not submitted in advance.

The documents must be linked to the customs declaration in TVINN.
To use the service, the scope for authentication in Maskinporten must be set to toll:goodsdeclaration/document.write

Interface description

The services are made available as REST services over HTTPS, with data in JSON format.

POST https://<env>/api/goodsdeclaration/document/v2/declaration-id/{DeklarasjonsID}/document
        

where

• <env> is replaced with
  • api.toll.no for production
  • api-test.toll.no for playground (testing environment)
• {DeclarationID} is TVINN declaration ID, divided into three parts in the following format: "123456789-01092023-1":
  1. The first part is the declarant number
  2. The second part is the declaration date in the format "ddmmyyyy"
  3. The third part is the sequence number.

See detailed API documentation here.

If you discover security issues in our solutions, please contact us; see info here

HTTP Request

Method: POST
Endpoint: /goodsdeclaration/document/v2/declaration-id/{DeclarationID}/document

Headers:

Header	Value
Authorization	Bearer "TOLL ACCESS TOKEN"

The required token must be a Toll-signed JWT with the scope toll:goodsdeclaration/document.write from Maskinporten (see description of authentication further down the page).

Body:

Key	Value
Media Type	Form Data
Content	metadata: {"declarationId": "Insert declaration-id here", "documentType": "Insert document type here"} file: Your document
Document type must be one of	invoice permits freight invoice proof of origin documentation waybill
File type must be one of	pdf jpg png txt doc docx xls xlsx
Maximum file size	Maximum 10MB per attachment. If the attachment is larger, you must split it into multiple parts, each smaller than 10MB. Note! The order of the fields in the content must be the same as specified above

Postman Example

Body

Auth

Authentication – Data exchange between the business sector and Norwegian Customs

Our APIs use Maskinporten for identity and access management. On the page Maskinporten - Norwegian Customs you will find information on

• how to get started with integration via Maskinporten if you have not done so before, including a registration form for access to Norwegian Customs
• Access management for our APIs
• Setting up a client for authentication via Maskinporten
• Operations and monitoring/troubleshooting.

The scope used for this API is toll:goodsdeclaration/document.write.