EMCS API service guide
Learn how to use the Excise Movement Control System (EMCS) API with your software.
The EMCS API is based on REST principles.
The endpoints accept data in XML format, and return data in XML wrapped in JSON.
The API uses standard HTTP error response codes.
Use the EMCS API to:
- submit movement information to the Excise Movement and Control System (EMCS)
- retrieve information about movements
This version of the EMCS API:
- is in the beta phase
- is currently ready for testing
- will not be ready for use in production until EMCS FS 4.0 goes live. In the meantime, you should continue to use the SOAP EMCS API.
Using EMCS API for the first time
If you are new to the EMCS API, you should follow these steps:
- Read all of this document before reviewing other documents for EMCS API
- Follow all of the steps in Using the Developer Hub.
- Read the EMCS API testing guide
- Read the EMCS API technical interface specification
- Read Making API requests
Migrating from an earlier version
If you are migrating from the old SOAP EMCS API, you should read:
- the migrating from SOAP API page before reviewing other documents for EMCS API
- the EMCS API testing guide
- the EMCS API technical interface specification
- Making API requests
Using the Developer Hub
When you have completed the relevant steps above, you should follow these steps:
- If you haven’t already, sign up for an HMRC developer account, activate it by email, and sign in).
- Learn about the user-restricted authentication used by the API.
- Create an application in our sandbox environment.
- Add your subscription to this API to your application software.
- Use the Create Test User API to create one or more test users for your sandbox application. You should follow the instructions in the testing guide for creating a test user.
Use the Developer Hub to:
- add your production application
- subscribe it to the APIs you want to integrate with
We’ll check your application, which takes up to 10 working days.
Making API requests
Before sending any requests to EMCS API, you should ensure that you are using the following in your software:
- the correct URL for the environment and API version number
- the correct header contents and payload information, contained in the EMCS API reference
These endpoints are available to use:
- submit a new draft excise movement
- get excise movements
- submit a message for an excise movement
- get all messages for an excise movement
- get information relating to an Excise Trader