This version is in beta - expect some breaking changes.

Create Test User API

Dates and amounts
Date Amount
Version and status
Available in Sandbox Yes
Sandbox base URL https://test-api.service.hmrc.gov.uk
Available in Production No

Overview

Use this API to create test users for testing in our sandbox with user-restricted endpoints.

What is a test user?

A test user is a dummy Government Gateway account that you can use for testing in our sandbox. To access user-restricted endpoints your application’s users must complete the OAuth journey, which includes signing into their Government Gateway account.

Each test user has a:

  • type of Government Gateway account - individual, organisation or agent
  • Government Gateway user ID and password - for sign in during the OAuth journey
  • set of service enrolments and related tax identifiers - as different APIs require different enrolments

What types of test user can I create?

With this API you can create a wide range of test users, including individuals, organisations and agents together with a wide variety of service enrolments and corresponding tax identifiers. You can also create test users for use during automated testing.

You can also use our create a test user service to create test individuals or organisations with a simpler default set of enrolments.

How long does a test user last?

Test users and other test data are no longer cleared down every two weeks.

Versioning

When an API changes in a way that is backwards-incompatible, we increase the version number of the API. See our reference guide for more on versioning.

Errors

We use standard HTTP status codes to show whether an API request succeeded or not. They are usually in the range:

  • 200 to 299 if it succeeded, including code 202 if it was accepted by an API that needs to wait for further action
  • 400 to 499 if it failed because of a client error by your application
  • 500 to 599 if it failed because of an error on our server

Errors specific to each API are shown in the Endpoints section, under Response. See our reference guide for more on errors.

Skip to main content

Endpoints

/create-test-user/individuals

Create a test user which is an individual
POST

This resource creates and returns a test user which is an individual. The caller can specify the required service enrolments in the request body. If no request body is supplied, the test user is created with no service enrolments.

Authorisation

This endpoint is application-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token.

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.1.0+json
Content-Type
required

Specifies the format of the request body, which must be JSON.

For example: application/json
Authorization
required
An OAuth 2.0 Bearer Token.

For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2

See also fraud prevention.

Request

{
  "serviceNames": [
    "national-insurance",
    "self-assessment",
    "mtd-income-tax",
    "customs-services",
    "goods-vehicle-movements",
    "mtd-vat",
    "common-transit-convention-traders"
  ],
  "eoriNumber": "GB123456789012"
}

Request table
Name Description
serviceNames
array
required

A list of services that the user should be enrolled for. To create a test user with no services, leave the list empty.

Limited to the following possible values:

national-insurance - Generates a National Insurance number and enrols the user for National Insurance.
self-assessment - Generates a Self Assessment UTR and enrols the user for Self Assessment.
mtd-income-tax - Generates a National Insurance number and a Making Tax Digital Income Tax ID and enrols the user for Making Tax Digital Income Tax.
customs-services - Generates an EORI number and enrols the user for Customs Services.
goods-vehicle-movements - Generates an EORI number and enrols the user for Goods Vehicle Movements.
mtd-vat - Generates a VAT Registration Number and a date of registration for VAT and enrols the user for Making Tax Digital VAT.
common-transit-convention-traders - Generates an EORI number and enrols the user for Common Transit Convention Traders.
eoriNumber
string
optional

Economic Operator Registration and Identification (EORI) number.

Must conform to the regular expression ^(GB|XI)[0-9]{12,15}$

nino
string
optional

National Insurance number. Must be enrolled with 'national-insurance' or 'mtd-income-tax' services for this to be used.

Response

HTTP status: 201 (Created)

{
  "userId":"945350439195",
  "password":"bLohysg8utsa",
  "userFullName": "Ida Newton",
  "emailAddress": "ida.newton@example.com",
  "individualDetails": {
    "firstName": "Ida",
    "lastName": "Newton",
    "dateOfBirth": "1960-06-01",
    "address": {
      "line1": "45 Springfield Rise",
      "line2": "Glasgow",
      "postcode": "TS1 1PA"
    }
  },
  "saUtr":"1000057161",
  "nino":"PE938808A",
  "mtdItId":"XJIT00000328268",
  "vrn":"666119668",
  "vatRegistrationDate":"2001-11-02",
  "eoriNumber":"GB123456789012"
}

Response table
Name Description
userId
string
required

Government Gateway ID.

password
string
required

Government Gateway password.

userFullName
string
required

Government Gateway user's full name.

emailAddress
string
required

Government Gateway user's email address.

individualDetails
object
required
firstName
string
required

Individual's first name.

lastName
string
required

Individual's last name.

dateOfBirth
string
required

Individual's date of birth.

address
object
required
line1
string
required

Individual's first line of address.

line2
string
required

Individual's second line of address.

postcode
string
required

Individual's postcode.

saUtr
string
optional

Self Assessment UTR.

nino
string
optional

National Insurance number.

mtdItId
string
optional

Making Tax Digital Income Tax ID.

eoriNumber
string
optional

Economic Operator Registration and Identification (EORI) number.

vrn
string
optional

VAT Reference Number.

vatRegistrationDate
string
optional

Date of registration for VAT.


Close Section
/create-test-user/organisations

Create a test user which is an organisation
POST

This resource creates and returns a test user which is an organisation. The caller can specify the required service enrolments in the request body. If no request body is supplied, the test user is created with no service enrolments.

Authorisation

This endpoint is application-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token.

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.1.0+json
Content-Type
required

Specifies the format of the request body, which must be JSON.

For example: application/json
Authorization
required
An OAuth 2.0 Bearer Token.

For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2

See also fraud prevention.

Request

{
  "serviceNames": [
    "corporation-tax",
    "paye-for-employers",
    "submit-vat-returns",
    "national-insurance",
    "self-assessment",
    "mtd-income-tax",
    "mtd-vat",
    "lisa",
    "secure-electronic-transfer",
    "relief-at-source",
    "customs-services",
    "goods-vehicle-movements",
    "safety-and-security",
    "common-transit-convention-traders"
  ],
  "eoriNumber": "GB123456789012",
  "taxpayerType": "Individual"
}

Request table
Name Description
serviceNames
array
required

A list of services that the user should be enrolled for. To create a test user with no services, leave the list empty.

Limited to the following possible values:

corporation-tax - Generates a Corporation Tax Unique Taxpayer Reference (CTUTR), a Company Registration Number (CRN) and enrols the user for Corporation Tax.
paye-for-employers - Generates an Employer Reference and enrols the user for PAYE for Employers.
submit-vat-returns - Generates a VAT Registration Number and enrols the user for Submit VAT Returns.
national-insurance - Generates a National Insurance number and enrols the user for National Insurance.
self-assessment - Generates a Self Assessment UTR and enrols the user for Self Assessment.
mtd-income-tax - Generates a National Insurance number and a Making Tax Digital Income Tax ID and enrols the user for Making Tax Digital Income Tax.
mtd-vat - Generates a VAT Registration Number and a date of registration for VAT and enrols the user for Making Tax Digital VAT.
lisa - Generates a LISA Manager Reference Number and enrols the user for Lifetime ISA.
secure-electronic-transfer - Generates a Secure Electronic Transfer Reference Number and enrols the user for HMRC Secure Electronic Transfer.
relief-at-source - Generates a Pension Scheme Administrator Identifier and enrols the user for Relief at Source.
customs-services - Generates an EORI number and enrols the user for Customs Services.
goods-vehicle-movements - Generates an EORI number and enrols the user for Goods Vehicle Movements.
safety-and-security - Generates an EORI number and enrols the user for Safety and Security.
common-transit-convention-traders - Generates an EORI number and enrols the user for Common Transit Convention Traders.
eoriNumber
string
optional

Economic Operator Registration and Identification (EORI) number.

Must conform to the regular expression ^(GB|XI)[0-9]{12,15}$

nino
string
optional

National Insurance number. Must be enrolled with 'national-insurance' or 'mtd-income-tax' services for this to be used.

taxPayerType
string
optional

Type of Self Assessment taxpayer One of 'Individual' or 'Partnership'

Response

HTTP status: 201 (Created)

{
  "userId":"085603622877",
  "password":"nyezgdfrlsmc",
  "userFullName": "Ida Newton",
  "emailAddress": "ida.newton@example.com",
  "organisationDetails": {
    "name":"Company ABF123",
    "address": {
      "line1":"1 Abbey Road",
      "line2":"Aberdeen",
      "postcode": "TS1 1PA"
    }
  },
  "saUtr":"8000083480",
  "nino":"XM110477D",
  "empRef":"538/EMKXYNSVTH",
  "ctUtr":"4000082459",
  "vrn":"666119668",
  "vatRegistrationDate":"2001-11-02",
  "mtdItId":"XJIT00000328268",
  "lisaManagerReferenceNumber":"Z123456",
  "secureElectronicTransferReferenceNumber":"123456789012",
  "pensionSchemeAdministratorIdentifier":"A1234567",
  "eoriNumber":"GB123456789012",
  "crn": "12345678",
  "taxPayerType":"Individual"
}

Response table
Name Description
userId
string
required

Government Gateway ID.

password
string
required

Government Gateway password.

userFullName
string
required

Government Gateway user's full name.

emailAddress
string
required

Government Gateway user's email address.

organisationDetails
object
required
name
string
required

Organisation name.

address
object
required
line1
string
required

Organisation's first line of address.

line2
string
required

Organisation's second line of address.

postcode
string
required

Organisation's postcode.

saUtr
string
optional

Self Assessment UTR.

nino
string
optional

National Insurance number.

mtdItId
string
optional

Making Tax Digital Income Tax ID.

empRef
string
optional

Employer Reference.

ctUtr
string
optional

Corporation Tax UTR.

vrn
string
optional

VAT Reference Number.

vatRegistrationDate
string
optional

Date of registration for VAT.

lisaManagerReferenceNumber
string
optional

LISA Manager Reference Number, in either 4-digit format (Znnnn) or 6-digit format (Znnnnnn).

secureElectronicTransferReferenceNumber
string
optional

Secure Electronic Transfer reference number.

pensionSchemeAdministratorIdentifier
string
optional

Pension Scheme Administrator Identifier.

eoriNumber
string
optional

Economic Operator Registration and Identification (EORI) number.

crn
string
optional

Company Reference Number

taxPayerType
string
optional

Type of Self Assessment taxpayer One of 'Individual' or 'Partnership'


Close Section
/create-test-user/agents

Create a test user which is an agent
POST

This resource creates and returns a test user which is an agent. The caller can specify the required service enrolments in the request body. If no request body is supplied, the test user is created with no service enrolments.

Authorisation

This endpoint is application-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token.

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.1.0+json
Content-Type
required

Specifies the format of the request body, which must be JSON.

For example: application/json
Authorization
required
An OAuth 2.0 Bearer Token.

For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2

See also fraud prevention.

Request

{
  "serviceNames": [
    "agent-services"
  ]
}

Request table
Name Description
serviceNames
array
required

A list of services that the user should be enrolled for. To create a test user with no services, leave the list empty.

Limited to the following possible values:

agent-services - Generates an agent services account reference number and enrols the user for agent services.

Response

HTTP status: 201 (Created)

{
  "userId":"945350439195",
  "password":"bLohysg8utsa ",
  "userFullName": "Ida Newton",
  "emailAddress": "ida.newton@example.com",
  "agentServicesAccountNumber":"NARN0396245"
}

Response table
Name Description
userId
string
required

Government Gateway ID.

password
string
required

Government Gateway password.

userFullName
string
required

Government Gateway user's full name.

emailAddress
string
required

Government Gateway user's email address.

agentServicesAccountNumber
string
optional

Agent services account reference number.


Close Section
/create-test-user/services

Get available services
GET

This resource provides a list of all the available services together with which test user types can enrol to each.

Authorisation

This endpoint is application-restricted and requires an Authorization header containing an OAuth 2.0 Bearer Token.

Request headers

Request headers Table
Name Description
Accept
required

Specifies the response format and the version of the API to be used.

For example: application/vnd.hmrc.1.0+json
Authorization
required
An OAuth 2.0 Bearer Token.

For example: Bearer 59fc92c1cdf0b8ef1f138a702effdbd2

See also fraud prevention.

Response

HTTP status: 200 (OK)

[
  {
    "key" : "service1",
    "name": "Service 1",
    "allowedUserTypes": [
      "INDIVIDUAL",
      "ORGANISATION"
    ]
  },
  {
    "key" : "service2",
    "name": "Service 2",
    "allowedUserTypes": [
      "AGENT"
    ]
  }
]

Response table
Name Description
key
string
optional

The key of the service

name
string
optional

The human readable name of the service

allowedUserTypes
array
optional

The user type


Close Section

Skip to main content