v1

latestOpenAPI 3.0.32026-07-134223.0 KB

Marriage Allowance

Create Marriage Allowance

This endpoint allows the customer to transfer up to £1,260 of their personal allowance to their spouse or civil partner. A National Insurance Number must be provided.

Test data

Scenario simulation using Gov-Test-Scenario headers is only available in the sandbox environment.

Header Value (Gov-Test-Scenario)	Scenario
N/A - DEFAULT	Simulates success response.
DECEASED_RECIPIENT	Simulates the scenario in which the supplied spouse or civil partner has been flagged as deceased.
CLAIM_ALREADY_EXISTS	Simulates the scenario in which a Marriage Allowance claim already exists for the supplied NINO.
INVALID_REQUEST	Simulates the scenario in which a request cannot be made as the current NINO supplied is invalid.

post/individuals/disclosures/marriage-allowance/{nino}

Path parameters

ninostring required

Example:TC663795B

National Insurance number, in the format AA999999A

Headers

Accept'application/vnd.hmrc.2.0+json' required

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

Authorizationstring required

Example:Bearer bb7fed3fe10dd235a2ccda3d50fb

An OAuth 2.0 Bearer Token with the write:self-assessment scope.

Content-Type'application/json' required

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

Gov-Test-Scenariostring

Example:-

Only in sandbox environment. See Test Data table for all header values.

Request body

spouseOrCivilPartnerNinostring required

Your spouse or civil partner's National Insurance number.

spouseOrCivilPartnerFirstNamestring

Your spouse or civil partner's first name. Must not be empty or contain only whitespace.

spouseOrCivilPartnerSurnamestring required

Your spouse or civil partner's surname. Must not be empty or contain only whitespace.

spouseOrCivilPartnerDateOfBirthstring date

The date of birth of your spouse or civil partner in the format YYYY-MM-DD.

Example request

{
  "spouseOrCivilPartnerNino": "AA999999A",
  "spouseOrCivilPartnerFirstName": "John",
  "spouseOrCivilPartnerSurname": "Smith",
  "spouseOrCivilPartnerDateOfBirth": "1998-04-06"
}

Response

Success