Self Assessment Returns
Minimum access level: Tax, Accounting & Users, unless stated otherwise.
This endpoint allows API applications to retrieve information on a user's Self Assessment Returns, including details on payments due and filing status.
Attributes
| Attribute | Description | Kind |
|---|---|---|
| url | Unique identifier for the record | URI |
| period_ends_on | The end date of the period covered by the return | Date |
| period_starts_on | The start date of the period covered by the return | Date |
| payments | An array of Payments | Array |
| filing_due_on | The date on which submission is due | Date |
| filing_status | One of unfiled, pending, rejected, provisionally_filed, filed or marked_as_filed. |
String |
| filed_at | For returns which have been filed online, the date and time at which that happened | Datetime |
| filed_reference | For returns which have been filed online, the IRMark returned by the submission | String |
Payment Attributes
| Attribute | Description | Kind |
|---|---|---|
| label | A human-readable name for the payment | String |
| due_on | The date on which a payment is due | Date |
| amount_due | The amount due on that date. May be negative in the case of a balancing payment. | Decimal |
| status | One of unpaid or marked_as_paid. paid is reserved for future use. Key is omitted if amount_due is zero or negative. |
String |
List Self Assessment Returns for a User
GET https://api.freeagent.com/v2/users/:user_id/self_assessment_returns
Response
Status: 200 OK
{
"self_assessment_returns": [
{
"url": "https://api.freeagent.com/v2/users/119/self_assessment_returns/2022-04-05",
"period_ends_on": "2022-04-05",
"period_starts_on": "2021-04-06",
"payments": [
{
"label": "Balancing Payment",
"amount_due": "-2250.0",
"due_on": "2023-01-31"
}
],
"filing_due_on": "2023-01-31",
"filing_status": "filed",
"filed_at": "2023-10-10T10:32:49.000+00:00",
"filed_reference": "YFM7CAZY2AQXUCRCQJOVS45UZUS4JWQN"
},
{
"url": "https://api.freeagent.com/v2/users/119/self_assessment_returns/2023-04-05",
"period_ends_on": "2023-04-05",
"period_starts_on": "2022-04-06",
"payments": [
{
"label": "Balancing Payment",
"amount_due": "6181.82",
"due_on": "2024-01-31",
"status": "unpaid"
}
],
"filing_due_on": "2024-01-31",
"filing_status": "unfiled"
},
{
"url": "https://api.freeagent.com/v2/users/119/self_assessment_returns/2024-04-05",
"period_ends_on": "2024-04-05",
"period_starts_on": "2023-04-06",
"payments": [
{
"label": "Payment on Account",
"amount_due": "3009.01",
"due_on": "2024-01-31",
"status": "unpaid"
},
{
"label": "Payment on Account",
"amount_due": "3009.01",
"due_on": "2024-07-31",
"status": "unpaid"
},
{
"label": "Balancing Payment",
"amount_due": "-6018.02",
"due_on": "2025-01-31"
}
],
"filing_due_on": "2025-01-31",
"filing_status": "unfiled"
}
]
}
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
<self-assessment-returns type="array">
<self-assessment-return>
<url>https://api.freeagent.com/v2/users/119/self_assessment_returns/2022-04-05</url>
<period-ends-on type="date">2022-04-05</period-ends-on>
<period-starts-on type="date">2021-04-06</period-starts-on>
<payments type="array">
<payment>
<label>Balancing Payment</label>
<amount-due type="decimal">-2250.0</amount-due>
<due-on type="date">2023-01-31</due-on>
</payment>
</payments>
<filing-due-on type="date">2023-01-31</filing-due-on>
<filing-status>filed</filing-status>
<filed-at type="dateTime">2023-10-10T10:32:49+00:00</filed-at>
<filed-reference>YFM7CAZY2AQXUCRCQJOVS45UZUS4JWQN</filed-reference>
</self-assessment-return>
<self-assessment-return>
<url>https://api.freeagent.com/v2/users/119/self_assessment_returns/2023-04-05</url>
<period-ends-on type="date">2023-04-05</period-ends-on>
<period-starts-on type="date">2022-04-06</period-starts-on>
<payments type="array">
<payment>
<label>Balancing Payment</label>
<amount-due type="decimal">6181.82</amount-due>
<due-on type="date">2024-01-31</due-on>
<status>unpaid</status>
</payment>
</payments>
<filing-due-on type="date">2024-01-31</filing-due-on>
<filing-status>unfiled</filing-status>
</self-assessment-return>
<self-assessment-return>
<url>https://api.freeagent.com/v2/users/119/self_assessment_returns/2024-04-05</url>
<period-ends-on type="date">2024-04-05</period-ends-on>
<period-starts-on type="date">2023-04-06</period-starts-on>
<payments type="array">
<payment>
<label>Payment on Account</label>
<amount-due type="decimal">3009.01</amount-due>
<due-on type="date">2024-01-31</due-on>
<status>unpaid</status>
</payment>
<payment>
<label>Payment on Account</label>
<amount-due type="decimal">3009.01</amount-due>
<due-on type="date">2024-07-31</due-on>
<status>unpaid</status>
</payment>
<payment>
<label>Balancing Payment</label>
<amount-due type="decimal">-6018.02</amount-due>
<due-on type="date">2025-01-31</due-on>
</payment>
</payments>
<filing-due-on type="date">2025-01-31</filing-due-on>
<filing-status>unfiled</filing-status>
</self-assessment-return>
</self-assessment-returns>
</freeagent>
Fetch details for a Self Assessment Return
GET https://api.freeagent.com/v2/users/:user_id/self_assessment_returns/:period_ends_on
Response
Status: 200 OK
{
"self_assessment_return": {
"url": "https://api.freeagent.com/v2/users/119/self_assessment_returns/2024-04-05",
"period_ends_on": "2024-04-05",
"period_starts_on": "2023-04-06",
"payments": [
{
"label": "Payment on Account",
"amount_due": "3009.01",
"due_on": "2024-01-31",
"status": "unpaid"
},
{
"label": "Payment on Account",
"amount_due": "3009.01",
"due_on": "2024-07-31",
"status": "unpaid"
},
{
"label": "Balancing Payment",
"amount_due": "-6018.02",
"due_on": "2025-01-31"
}
],
"filing_due_on": "2025-01-31",
"filing_status": "unfiled"
}
}
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
<self-assessment-return>
<url>https://api.freeagent.com/v2/users/119/self_assessment_returns/2024-04-05</url>
<period-ends-on type="date">2024-04-05</period-ends-on>
<period-starts-on type="date">2023-04-06</period-starts-on>
<payments type="array">
<payment>
<label>Payment on Account</label>
<amount-due type="decimal">3009.01</amount-due>
<due-on type="date">2024-01-31</due-on>
<status>unpaid</status>
</payment>
<payment>
<label>Payment on Account</label>
<amount-due type="decimal">3009.01</amount-due>
<due-on type="date">2024-07-31</due-on>
<status>unpaid</status>
</payment>
<payment>
<label>Balancing Payment</label>
<amount-due type="decimal">-6018.02</amount-due>
<due-on type="date">2025-01-31</due-on>
</payment>
</payments>
<filing-due-on type="date">2025-01-31</filing-due-on>
<filing-status>unfiled</filing-status>
</self-assessment-return>
</freeagent>
Mark a Self Assessment Return as Filed
Minimum access level: Full Access
PUT https://api.freeagent.com/v2/users/:user_id/self_assessment_returns/:period_ends_on/mark_as_filed
Response
Status: 200 OK
{
"self_assessment_return": {
"url": "https://api.freeagent.com/v2/users/119/self_assessment_returns/2024-04-05",
"period_ends_on": "2024-04-05",
"period_starts_on": "2023-04-06",
"payments": [
{
"label": "Payment on Account",
"amount_due": "3009.01",
"due_on": "2024-01-31",
"status": "unpaid"
},
{
"label": "Payment on Account",
"amount_due": "3009.01",
"due_on": "2024-07-31",
"status": "unpaid"
},
{
"label": "Balancing Payment",
"amount_due": "-6018.02",
"due_on": "2025-01-31"
}
],
"filing_due_on": "2025-01-31",
"filing_status": "marked_as_filed"
}
}
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
<self-assessment-return>
<url>https://api.freeagent.com/v2/users/119/self_assessment_returns/2024-04-05</url>
<period-ends-on type="date">2024-04-05</period-ends-on>
<period-starts-on type="date">2023-04-06</period-starts-on>
<payments type="array">
<payment>
<label>Payment on Account</label>
<amount-due type="decimal">3009.01</amount-due>
<due-on type="date">2024-01-31</due-on>
<status>unpaid</status>
</payment>
<payment>
<label>Payment on Account</label>
<amount-due type="decimal">3009.01</amount-due>
<due-on type="date">2024-07-31</due-on>
<status>unpaid</status>
</payment>
<payment>
<label>Balancing Payment</label>
<amount-due type="decimal">-6018.02</amount-due>
<due-on type="date">2025-01-31</due-on>
</payment>
</payments>
<filing-due-on type="date">2025-01-31</filing-due-on>
<filing-status>marked_as_filed</filing-status>
</self-assessment-return>
</freeagent>
Mark a Self Assessment Return as Unfiled
Minimum access level: Full Access
PUT https://api.freeagent.com/v2/users/:user_id/self_assessment_returns/:period_ends_on/mark_as_unfiled
Response
Status: 200 OK
{
"self_assessment_return": {
"url": "https://api.freeagent.com/v2/users/119/self_assessment_returns/2024-04-05",
"period_ends_on": "2024-04-05",
"period_starts_on": "2023-04-06",
"payments": [
{
"label": "Payment on Account",
"amount_due": "3009.01",
"due_on": "2024-01-31",
"status": "unpaid"
},
{
"label": "Payment on Account",
"amount_due": "3009.01",
"due_on": "2024-07-31",
"status": "unpaid"
},
{
"label": "Balancing Payment",
"amount_due": "-6018.02",
"due_on": "2025-01-31"
}
],
"filing_due_on": "2025-01-31",
"filing_status": "unfiled"
}
}
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
<self-assessment-return>
<url>https://api.freeagent.com/v2/users/119/self_assessment_returns/2024-04-05</url>
<period-ends-on type="date">2024-04-05</period-ends-on>
<period-starts-on type="date">2023-04-06</period-starts-on>
<payments type="array">
<payment>
<label>Payment on Account</label>
<amount-due type="decimal">3009.01</amount-due>
<due-on type="date">2024-01-31</due-on>
<status>unpaid</status>
</payment>
<payment>
<label>Payment on Account</label>
<amount-due type="decimal">3009.01</amount-due>
<due-on type="date">2024-07-31</due-on>
<status>unpaid</status>
</payment>
<payment>
<label>Balancing Payment</label>
<amount-due type="decimal">-6018.02</amount-due>
<due-on type="date">2025-01-31</due-on>
</payment>
</payments>
<filing-due-on type="date">2025-01-31</filing-due-on>
<filing-status>unfiled</filing-status>
</self-assessment-return>
</freeagent>
Mark a Self Assessment Return Payment as Paid
PUT https://api.freeagent.com/v2/users/:user_id/self_assessment_returns/:period_ends_on/payments/:payment_date/mark_as_paid
Response
Status: 200 OK
{
"self_assessment_return": {
"url": "https://api.freeagent.com/v2/users/119/self_assessment_returns/2024-04-05",
"period_ends_on": "2024-04-05",
"period_starts_on": "2023-04-06",
"payments": [
{
"label": "Payment on Account",
"amount_due": "3009.01",
"due_on": "2024-01-31",
"status": "marked_as_paid"
},
{
"label": "Payment on Account",
"amount_due": "3009.01",
"due_on": "2024-07-31",
"status": "unpaid"
},
{
"label": "Balancing Payment",
"amount_due": "-6018.02",
"due_on": "2025-01-31"
}
],
"filing_due_on": "2025-01-31",
"filing_status": "marked_as_filed"
}
}
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
<self-assessment-return>
<url>https://api.freeagent.com/v2/users/119/self_assessment_returns/2024-04-05</url>
<period-ends-on type="date">2024-04-05</period-ends-on>
<period-starts-on type="date">2023-04-06</period-starts-on>
<payments type="array">
<payment>
<label>Payment on Account</label>
<amount-due type="decimal">3009.01</amount-due>
<due-on type="date">2024-01-31</due-on>
<status>marked_as_paid</status>
</payment>
<payment>
<label>Payment on Account</label>
<amount-due type="decimal">3009.01</amount-due>
<due-on type="date">2024-07-31</due-on>
<status>unpaid</status>
</payment>
<payment>
<label>Balancing Payment</label>
<amount-due type="decimal">-6018.02</amount-due>
<due-on type="date">2025-01-31</due-on>
</payment>
</payments>
<filing-due-on type="date">2025-01-31</filing-due-on>
<filing-status>marked_as_filed</filing-status>
</self-assessment-return>
</freeagent>
Mark a Self Assessment Return Payment as Unpaid
PUT https://api.freeagent.com/v2/users/:user_id/self_assessment_returns/:period_ends_on/payments/:payment_date/mark_as_unpaid
Response
Status: 200 OK
{
"self_assessment_return": {
"url": "https://api.freeagent.com/v2/users/119/self_assessment_returns/2024-04-05",
"period_ends_on": "2024-04-05",
"period_starts_on": "2023-04-06",
"payments": [
{
"label": "Payment on Account",
"amount_due": "3009.01",
"due_on": "2024-01-31",
"status": "unpaid"
},
{
"label": "Payment on Account",
"amount_due": "3009.01",
"due_on": "2024-07-31",
"status": "unpaid"
},
{
"label": "Balancing Payment",
"amount_due": "-6018.02",
"due_on": "2025-01-31"
}
],
"filing_due_on": "2025-01-31",
"filing_status": "marked_as_filed"
}
}
<?xml version="1.0" encoding="UTF-8"?>
<freeagent>
<self-assessment-return>
<url>https://api.freeagent.com/v2/users/119/self_assessment_returns/2024-04-05</url>
<period-ends-on type="date">2024-04-05</period-ends-on>
<period-starts-on type="date">2023-04-06</period-starts-on>
<payments type="array">
<payment>
<label>Payment on Account</label>
<amount-due type="decimal">3009.01</amount-due>
<due-on type="date">2024-01-31</due-on>
<status>unpaid</status>
</payment>
<payment>
<label>Payment on Account</label>
<amount-due type="decimal">3009.01</amount-due>
<due-on type="date">2024-07-31</due-on>
<status>unpaid</status>
</payment>
<payment>
<label>Balancing Payment</label>
<amount-due type="decimal">-6018.02</amount-due>
<due-on type="date">2025-01-31</due-on>
</payment>
</payments>
<filing-due-on type="date">2025-01-31</filing-due-on>
<filing-status>marked_as_filed</filing-status>
</self-assessment-return>
</freeagent>