Skip to main content

EMCS API testing guide

Learn how to test the compatibility of your software with Excise Movement Control System (EMCS) API.

Before you start

When you are ready to test your software, first read and understand the EMCS API service guide and EMCS API technical interface specification if you have not already done so.

You must complete the following steps before testing the API.

  1. Ensure that you have an HMRC developer account - if you do not have one, you must register for an account, activate it by email, and sign in.
  2. Create an application in our test environment called the sandbox.
  3. Subscribe to the Excise Movement Control System API on the manage API subscriptions page.
  4. Obtain your Client ID and Client secret credentials.
  5. Use the Create Test User API to create one or more test users for your sandbox application.

You must create a separate Test User for EMCS API. You may not be able to use Test Users from other API services.

Testing your software.

  1. Test the authorisation process.
  2. Use your application to make calls to our stubbed test API in the testing process.
  3. Test the test scenarios.

Test environment

To allow users to be able to rapidly test the new EMCS API, we have stubbed the back end. To act as a realistic representation of the production API, the stub provides the same validation for level 1 and level 2 validation as the production API will. It does not provide level 3 validation.

You can simulate common error responses by sending messages with standard inputs. These are detailed in the test scenarios.

Getting help and support

Before contacting us, find out if there is planned API downtime or a technical issue by checking HMRC API Platform Status and Excise Movement Control System service availability.

If you have specific questions about the EMCS API, contact our Software Developer Support (SDS) Team. You’ll get an initial response within 2 working days.

You can also email questions to SDSTeam@hmrc.gov.uk. We might ask for more detailed information when we respond.

Changelog

You can find the changelog for this document in the emcs-api-testing-guide GitHub wiki.