This version is in beta - expect some breaking changes.

Marriage Allowance Test Support API

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

Overview

Lets you set up test data for the Marriage Allowance API.

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.

Endpoints

/marriage-allowance-test-support/sa/{utr}/status/{taxYear}

Create Marriage Allowance status test data

POST

Lets you create Marriage Allowance status test data.

Supports the Get Marriage Allowance status resource method on the Marriage Allowance API.

Authorisation

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

Path parameters

Path parameters table
Name	Description
utr string required	The 10 digit self assessment UTR for the individual. For example: `2234567890`
taxYear string required	The tax year for which the Marriage Allowance status is being created. Tax year in the format `YYYY-YY` For example: `2016-17`

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 for other request headers which will become mandatory.

Request

{
  "status": "Recipient",
  "deceased": false
}

Request table
Name	Description
status string required	The role of the taxpayer as recipient or transferor Limited to the following possible values: `Transferor` - The taxpayer has transferred personal allowance in the given tax year `Recipient` - The taxpayer has received personal allowance in the given tax year `None` - The taxpayer has not transferred or received personal allowance in the given tax year
deceased boolean required	Whether the taxpayer is deceased or not

Response

HTTP status: 201 (Created)

{
  "status": "Recipient",
  "deceased": false
}

Response table
Name	Description
status string required	The role of the taxpayer as recipient or transferor Limited to the following possible values: `Transferor` - The taxpayer has transferred personal allowance in the given tax year `Recipient` - The taxpayer has received personal allowance in the given tax year `None` - The taxpayer has not transferred or received personal allowance in the given tax year
deceased boolean required	Whether the taxpayer is deceased or not

Close section

/marriage-allowance-test-support/nino/{nino}/eligibility/{taxYear}

Create Marriage Allowance eligibility test data

POST

Lets you create Marriage Allowance eligibility test data.

Supports the Check Marriage Allowance eligibility resource method on the Marriage Allowance API.