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.

Skip to main content

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

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

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

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

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
}

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.

Authorisation

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

Path parameters

Name Description
nino
string
required

Partner’s (potential recipient’s) National Insurance number. This must match the National Insurance number of an individual created using the Create Test User API.

For example: AA000003D

taxYear
string
required

The tax year for which the Marriage Allowance eligibility is being created.

Tax year in the format YYYY-YY

For example: 2016-17

Request headers

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

{
  "eligible": true
}

Name Description
eligible
boolean
required

Whether the taxpayer's partner is eligible to become a recipient of Marriage Allowance

Response

HTTP status: 201 (Created)

{
  "eligible": true
}

Name Description
eligible
boolean
required

Whether the taxpayer's partner is eligible to become a recipient of Marriage Allowance

Error scenarios

Scenario HTTP status Code

No test individual exists with the specified National Insurance number

400 (Bad Request)

TEST_USER_NOT_FOUND

For error scenarios that are common across all APIs, and for error formats, see our reference guide.


Close Section

Skip to main content

Is this page not working properly? (opens in new tab)