Skip to content

Add X-With-Server-Date guidance for testing API with future dates #2250

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tashonrp wants to merge 2 commits into
base: main
Choose a base branch
from
+26 −0
Open

Add X-With-Server-Date guidance for testing API with future dates #2250

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d66a8da
Added X-With-Server-Date guidance for testing API with future dates
tashonrp Feb 16, 2026
aa10525
Revise API testing instructions for future dates
tashonrp Feb 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions ...ews/api/guidance/guidance_for_lead_providers/how_to_test_the_api_effectively.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,32 @@ By default, the API returns up to 100 items per page. You need to test fetching

Try calling `GET /participants?page[per_page]=100&page[page]=2` to make sure your system correctly follows pagination links and doesn’t stop after the first batch.

## Test declaration submissions using X-With-Server-Date

`X-With-Server-Date` is a custom JSON header supported in the sandbox environment. It lets you test your integrations and ensure you're able to submit declarations for future milestone dates.

The `X-With-Server-Date` header lets you simulate future dates, and therefore allows you to test declaration submissions for future milestone dates.

It's only valid in the sandbox environment. Attempts to submit future declarations in the production environment (or without this header in sandbox) will be rejected as part of milestone validation.

To test declaration submission functionality, include:

- the header `X-With-Server-Date` as part of your declaration submission request
- the value of your chosen date in ISO8601 Date with time and Timezone (RFC3339 format)

### Example

Make a declaration submission using this header: `X-With-Server-Date: 2027-01-10T10:42:00Z`

### Response

Successful requests will return a response body including updates to the declaration state, which will become:
Copy link
Contributor

@claire-hughez claire-hughez Feb 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm a bit confused by the guidance here because what if they're just posting a declaration? I think it needs to be clearer the state changes happen when voiding a declaration (so PUT /api/v3/participant-declarations/{id}/void

I actually wonder if this section is relevant at all - this is less about how to test it and more just how the declaration endpoint works. The state transition should be in the declaration guidance I reckon


- `voided` if it had been `submitted`, `ineligible`, `eligible`, or `payable`
- `awaiting_clawback` if it had been `paid`

[View more information on declaration states](https://manage-training-for-early-career-teachers.education.gov.uk/api-reference/ecf/definitions-and-states/#declaration-states).

## Check seed data is adequate or request seed data that’s more tailored to your needs

Make sure the test data (seed data) in the sandbox fits what you need to test. If it doesn’t, ask DfE for adjustments.
Expand Down