---
updatedAt: 2025-08-27T15:58:57.000Z
agentTools:
projectIndex: https://docs.moneyhubenterprise.com/v2.5/llms.txt
---
# Request affordability income calculation for a user
Requires **affordability_income:write** and **affordability_income:read** scopes.
# OpenAPI definition
```json
{
"openapi": "3.0.0",
"info": {
"description": "Documentation for the Moneyhub data API.
Authentication is via bearer token.
",
"title": "Moneyhub Data API",
"version": "2.0.0"
},
"security": [
{
"Bearer": []
}
],
"paths": {
"/affordability/income": {
"post": {
"summary": "Request affordability income calculation for a user",
"description": "Requires **affordability_income:write** and **affordability_income:read** scopes.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AffordabilityIncomePost"
}
}
}
},
"responses": {
"200": {
"description": "Successful Affordability Income Response",
"content": {
"application/json": {
"schema": {
"properties": {
"data": {
"$ref": "#/components/schemas/AffordabilityIncome"
},
"links": {
"$ref": "#/components/schemas/Links"
},
"meta": {
"type": "object"
}
},
"type": "object"
}
}
}
},
"400": {
"description": "Unsuccessful Response - Bad Request - Mixed account currencies",
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"properties": {
"code": {
"description": "The error code",
"type": "string"
},
"subCode": {
"description": "The error subCode",
"enum": [
"CURRENCY_MISMATCH"
]
},
"message": {
"description": "The error message",
"type": "string"
},
"correlationId": {
"description": "Id that identifies the request and can be used to ask for more details related to the error",
"type": "string"
}
},
"required": [
"code"
],
"type": "object"
}
}
}
},
"401": {
"description": "Unsuccessful Response - Not authorised - Missing authorization header - Invalid access Token",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Unsuccessful Response - Forbidden - Invalid scopes",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Unsuccessful Response - Resource Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"affordability"
]
}
}
},
"servers": [
{
"url": "https://api.moneyhub.co.uk/v2.0"
}
],
"components": {
"securitySchemes": {
"Bearer": {
"type": "apiKey",
"name": "Authorization",
"in": "header"
}
},
"schemas": {
"AffordabilityIncome": {
"additionalProperties": false,
"type": "object",
"properties": {
"createdAt": {
"description": "The timestamp at which the report was generated",
"type": "string"
},
"id": {
"description": "The report id",
"type": "string"
},
"income": {
"type": "object",
"properties": {
"amountConsistency": {
"description": "Consistency of monthly income, as a number between 0 and 1",
"type": "number"
},
"longevity": {
"type": "object",
"properties": {
"consecutiveIncomeMonths": {
"description": "Longevity of income detected in number of months",
"type": "number"
},
"incomePeriodLengthMonths": {
"description": "The number of months of transaction history available for the income detection process",
"type": "number"
}
}
},
"predicted": {
"description": "The predicted monthly income amount",
"additionalProperties": false,
"type": "object",
"properties": {
"value": {
"description": "The amount in minor units of the currency, eg. pennies for GBP, negative means money going out of an account, positive means money coming into an account.",
"example": -2323,
"type": "integer"
},
"majorUnits": {
"description": "The positive major units of the value, based on the values currency, eg. pounds for GBP.",
"example": 23,
"type": "integer"
},
"minorUnits": {
"description": "The positive minor units of the value, based on the values currency, eg. pennies for GBP.",
"example": 23,
"type": "integer"
},
"currency": {
"description": "The currency of the amount",
"example": "GBP",
"type": "string"
}
},
"required": [
"value",
"currency"
]
},
"regularIncomeDetected": {
"description": "Whether or not regular income was detected",
"type": "boolean"
}
},
"required": [
"amountConsistency",
"longevity",
"predicted",
"regularIncomeDetected"
]
},
"overview": {
"type": "object",
"properties": {
"income": {
"description": "The median monthly income",
"additionalProperties": false,
"type": "object",
"properties": {
"value": {
"description": "The amount in minor units of the currency, eg. pennies for GBP, negative means money going out of an account, positive means money coming into an account.",
"example": -2323,
"type": "integer"
},
"majorUnits": {
"description": "The positive major units of the value, based on the values currency, eg. pounds for GBP.",
"example": 23,
"type": "integer"
},
"minorUnits": {
"description": "The positive minor units of the value, based on the values currency, eg. pennies for GBP.",
"example": 23,
"type": "integer"
},
"currency": {
"description": "The currency of the amount",
"example": "GBP",
"type": "string"
}
},
"required": [
"value",
"currency"
]
},
"incomeIncludingTransfers": {
"description": "The median monthly income including incoming transfers when incoming transfers exceed outgoing transfers",
"additionalProperties": false,
"type": "object",
"properties": {
"value": {
"description": "The amount in minor units of the currency, eg. pennies for GBP, negative means money going out of an account, positive means money coming into an account.",
"example": -2323,
"type": "integer"
},
"majorUnits": {
"description": "The positive major units of the value, based on the values currency, eg. pounds for GBP.",
"example": 23,
"type": "integer"
},
"minorUnits": {
"description": "The positive minor units of the value, based on the values currency, eg. pennies for GBP.",
"example": 23,
"type": "integer"
},
"currency": {
"description": "The currency of the amount",
"example": "GBP",
"type": "string"
}
},
"required": [
"value",
"currency"
]
}
},
"required": [
"income"
]
},
"primaryIncomeAccountId": {
"description": "The account id of the detected primary income account",
"type": "string"
}
},
"example": {
"createdAt": "2022-01-01T00:00:00Z",
"id": "d372d09b-f50a-4114-9c83-687828fa8ac2",
"income": {
"amountConsistency": 1,
"longevity": {
"consecutiveIncomeMonths": 12,
"incomePeriodLengthMonths": 12
},
"predicted": {
"value": 189900,
"majorUnits": 1899,
"minorUnits": 0,
"currency": "GBP"
},
"regularIncomeDetected": true
},
"overview": {
"income": {
"value": 189900,
"majorUnits": 1899,
"minorUnits": 0,
"currency": "GBP"
},
"incomeIncludingTransfers": {
"value": 210000,
"majorUnits": 2100,
"minorUnits": 0,
"currency": "GBP"
}
},
"primaryIncomeAccountId": "ac9bd177-d01e-449c-9f29-d3656d2edc2e"
},
"required": [
"createdAt",
"id"
]
},
"AffordabilityIncomePost": {
"additionalProperties": false,
"type": "object",
"properties": {
"externalUserId": {
"description": "Your reference ID for the user or individual affordability income check. The same value could be assigned to all reports created as part of the same affordability income check's lifecycle, for example",
"type": "string"
},
"name": {
"description": "The full name of the user to whom the affordability income check applies",
"type": "string"
},
"email": {
"description": "The email address of the user to whom the affordability income check applies",
"type": "string"
}
},
"example": {
"externalUserId": "LENDERNAME-123",
"name": "Joe Bloggs",
"email": "joe.blogss@example.com"
}
},
"Links": {
"additionalProperties": false,
"properties": {
"next": {
"description": "The url to retrieve the next page of results from",
"format": "uri",
"type": "string"
},
"prev": {
"description": "The url to retrieve the previous page of results from",
"format": "uri",
"type": "string"
},
"self": {
"description": "The url of the current resource(s)",
"format": "uri",
"type": "string"
}
},
"required": [
"self"
],
"type": "object"
},
"Error": {
"additionalProperties": false,
"properties": {
"code": {
"description": "The error code",
"type": "string"
},
"message": {
"description": "The error message",
"type": "string"
},
"correlationId": {
"description": "Id that identifies the request and can be used to ask for more details related to the error",
"type": "string"
},
"id": {
"description": "Id of the resource",
"type": "string"
},
"userId": {
"description": "UserId of the resource",
"type": "string"
}
},
"required": [
"code"
],
"type": "object"
}
}
},
"x-readme": {
"explorer-enabled": true,
"proxy-enabled": true
}
}
```