API for uploading documents

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. Such documents can be invoices, permits, shipping bills, documentation of origin or waybills.
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 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.

If you discover vulnerabilities in Tolletaten's solutions, please contact us; see info here.

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

where <env> is

• api.toll.no for production
• api-test.toll.no for playground (test environment)

and {DeclarationID} is substituted with TVINN declaration ID in the following format: "123456789-01092023-1", where the first part is the declarant number, the second part is the declaration date (format ddmmyyyy), and the third part is the sequence number.

See detailed API-documentation here.

HTTP Request

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

Headers

• Authorization: Bearer Token
  The required token must be a JWT signed by Toll with the Maskinporten scope toll:goodsdeclaration/document.write (more on authentication below).

Body

• Media Type: Form Data
• Content:
  • metadata: {"declarationId": "Insert declaration-id here", "documentType": "Insert document type here"}
  • file: Your document
• The document type must be one of the following
  • invoice
  • permits
  • freight invoice
  • proof of origin documentation
  • consignment note
• The file type must be one of following
  • pdf
  • jpg
  • png
  • txt
  • doc
  • docx
  • xls
  • xlsx
• The maximum file size per attachment is 10MB. If the attachment exceeds this limit, you will need to split it into multiple parts, with each part being 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 you will find information on

• how to get started with integration via Maskinporten 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.