Skip to content
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

Jump to bottom

Initial guidance page drafts #1339

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
+3,106 −41
Open

Initial guidance page drafts #1339

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
05351ba
Initial guidance page drafts
mark-avery-dfe Apr 30, 2024
ee786c5
Added the word 'amazing'.
mark-avery-dfe Apr 30, 2024
0fed2b7
Commit
mark-avery-dfe May 15, 2024
553765a
Updated links
mark-avery-dfe May 16, 2024
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
1,037 changes: 1,037 additions & 0 deletions app/views/api/guidance/api_requests.md
View file
Open in desktop

Large diffs are not rendered by default.

185 changes: 185 additions & 0 deletions app/views/api/guidance/data_states.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,185 @@
# Data states

## Concepts and definitions

<table class="govuk-table">
<thead class="govuk-table__head">
<tr class="govuk-table__row">
<th scope="col" class="govuk-table__header">Concept</th>
<th scope="col" class="govuk-table__header">Definition</th>
</tr>
</thead>
<tbody class="govuk-table__body">
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>application</code></th>
<td class="govuk-table__cell">The application a person makes to be trained on an NPQ course. Applications include funding details</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>participant</code></th>
<td class="govuk-table__cell">A person registered for an NPQ course</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>schedule</code></th>
<td class="govuk-table__cell">The expected timeframe in which a participant will complete their NPQ course. Schedules include defined [milestone dates](ADD LINK) against which DfE validates the declarations submitted by providers</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>course_identifier</code></th>
<td class="govuk-table__cell">The NPQ course a participant applies for and is registered for</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>outcome</code></th>
<td class="govuk-table__cell">The assessment result a participant achieves at the end of an NPQ course</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>declaration</code></th>
<td class="govuk-table__cell">The notification submitted by providers via the API to trigger output payments from DfE. Declarations are submitted where there is evidence of a participant’s engagement in training for a given milestone period</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>statement</code></th>
<td class="govuk-table__cell">A record of output payments (based on declarations), service fees and any adjustments DfE may pay lead providers at the end of a contractually agreed payment period. Statements sent to providers by DfE at the end of milestone periods can be used for invoicing purposes</td>
</tr>
</tbody>
</table>

## Application data states

This API uses a `state` model to reflect the NPQ participant journey, meet contractual requirements for how providers should report participants’ training and how DfE will pay for this training.

Application states are defined by the `status` attribute.

A application’s status value will determine whether a provider can:

* [accept or reject applications](ADD LINK)

* [submit a declaration](ADD LINK). For example, notifying DfE that a participant has started their training

<table class="govuk-table">
<caption class="govuk-table__caption govuk-table__caption--m">Application status values</caption>
<thead class="govuk-table__head">
<tr class="govuk-table__row">
<th scope="col" class="govuk-table__header">Status</th>
<th scope="col" class="govuk-table__header govuk-table__header--numeric">Definition</th>
<th scope="col" class="govuk-table__header govuk-table__header--numeric">What providers can do</th>
</tr>
</thead>
<tbody class="govuk-table__body">
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>pending</code></th>
<td class="govuk-table__cell govuk-table__cell--numeric">Applications which have been made for an NPQ course</td>
<td class="govuk-table__cell govuk-table__cell--numeric">Accept or reject applications</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>accepted</code></th>
<td class="govuk-table__cell govuk-table__cell--numeric">Applications which have been accepted by a provider</td>
<td class="govuk-table__cell govuk-table__cell--numeric">Submit declarations and update participant data</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>rejected</code></th>
<td class="govuk-table__cell govuk-table__cell--numeric">Applications which have been rejected by a provider, or which have been accepted by another provider</td>
<td class="govuk-table__cell govuk-table__cell--numeric">No action required</td>
</tr>
</tbody>
</table>

[View more detailed specifications for the NPQ application schema](ADD LINK)

## Participant data states

Participant states are defined by the `training_status` attribute.

A participant’s `training_status` value will determine whether a provider can:

* [update their details](ADD LINK). For example, notifying DfE that a participant has withdrawn from the course

* [submit a declaration](ADD LINK). For example, notifying DfE that a participant has started their training

<table class="govuk-table">
<caption class="govuk-table__caption govuk-table__caption--m">Training status values</caption>
<thead class="govuk-table__head">
<tr class="govuk-table__row">
<th scope="col" class="govuk-table__header">Training status</th>
<th scope="col" class="govuk-table__header govuk-table__header--numeric">Definition</th>
<th scope="col" class="govuk-table__header govuk-table__header--numeric">What providers can do</th>
</tr>
</thead>
<tbody class="govuk-table__body">
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>active</code></th>
<td class="govuk-table__cell govuk-table__cell--numeric">Participants currently in training</td>
<td class="govuk-table__cell govuk-table__cell--numeric">Update participant data and submit declarations</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>deferred</code></th>
<td class="govuk-table__cell govuk-table__cell--numeric">Participants who've deferred training</td>
<td class="govuk-table__cell govuk-table__cell--numeric">Notify DfE when the participant [resumes training](ADD LINK)</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>withdrawn</code></th>
<td class="govuk-table__cell govuk-table__cell--numeric">Participants who have withdrawn from training</td>
<td class="govuk-table__cell govuk-table__cell--numeric">Submit declarations for withdrawn participants if the <code>declaration_date</code> is backdated to before the <code>withdrawal_date</code></td>
</tr>
</tbody>
</table>

[View more detailed specifications for the NPQ participant schema](ADD LINK)

## Declaration data states

Declaration states are defined by the `state` attribute.

Providers must [submit declarations](ADD LINK) to confirm a participant has engaged in training within a given milestone period. A declaration’s `state` value will reflect if and when DfE will pay providers for the training delivered.

<table class="govuk-table">
<caption class="govuk-table__caption govuk-table__caption--m">Declaration status values</caption>
<thead class="govuk-table__head">
<tr class="govuk-table__row">
<th scope="col" class="govuk-table__header">State</th>
<th scope="col" class="govuk-table__header govuk-table__header--numeric">Definition</th>
<th scope="col" class="govuk-table__header govuk-table__header--numeric">What providers can do</th>
</tr>
</thead>
<tbody class="govuk-table__body">
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>submitted</code></th>
<td class="govuk-table__cell govuk-table__cell--numeric">A declaration associated with to a participant who has not yet been confirmed to be eligible for funding</td>
<td class="govuk-table__cell govuk-table__cell--numeric">View and void</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>eligible</code></th>
<td class="govuk-table__cell govuk-table__cell--numeric">A declaration associated with a participant who has been confirmed to be eligible for funding</td>
<td class="govuk-table__cell govuk-table__cell--numeric">View and void</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>ineligible</code></th>
<td class="govuk-table__cell govuk-table__cell--numeric">A declaration associated with a participant who is not eligible for funding or a duplicate submission for a given participant</td>
<td class="govuk-table__cell govuk-table__cell--numeric">View and void</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>payable</code></th>
<td class="govuk-table__cell govuk-table__cell--numeric">A declaration that has been approved and is ready for payment by DfE</td>
<td class="govuk-table__cell govuk-table__cell--numeric">View and void</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>voided</code></th>
<td class="govuk-table__cell govuk-table__cell--numeric">A declaration that has been retracted by a provider</td>
<td class="govuk-table__cell govuk-table__cell--numeric">View</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>paid</code></th>
<td class="govuk-table__cell govuk-table__cell--numeric">A declaration that has been paid for by DfE</td>
<td class="govuk-table__cell govuk-table__cell--numeric">View and void</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>awaiting_clawback</code></th>
<td class="govuk-table__cell govuk-table__cell--numeric">A <code>paid</code> declaration that has since been voided by a provider</td>
<td class="govuk-table__cell govuk-table__cell--numeric">View</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>clawed_back</code></th>
<td class="govuk-table__cell govuk-table__cell--numeric">An <code>awaiting_clawback</code> declaration that has since had its value deducted from payment by DfE to a provider</td>
<td class="govuk-table__cell govuk-table__cell--numeric">View</td>
</tr>
</tbody>
</table>

[View more detailed specifications for the declaration schema](ADD LINK)
56 changes: 56 additions & 0 deletions app/views/api/guidance/get_started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
# Get started

## Connect to the API

Providers integrate their local CRM systems by connecting to this API's production and sandbox environments.

## Request an authentication token

Providers need to use a unique authentication token to connect to the API.

Emails us [INSERT EMAIL LINK]if you do not already have this token. We'll send it via secure email.

The tokens do not expire.

<div class="govuk-warning-text">
<span class="govuk-warning-text__icon" aria-hidden="true">!</span>
<strong class="govuk-warning-text__text">
<span class="govuk-visually-hidden">Warning</span>
Don't share tokens in publicly accessible documents or repositories.
</strong>
</div>

### How to use an authentication token

Include an authentication token in all requests to the API by adding an `Authorization` request header (not as part of the URL) in the following format:

<pre class="highlight plaintext" tabindex="0"><code>Authorization: Bearer {token}
</code></pre>

Unauthenticated requests will receive an <code>UnauthorizedResponse</code> with a <code>401</code> error code.

## Access YAML format API specs

Provider development teams can also access the OpenAPI spec in YAML formats:

* view the OpenAPI v1.0.0. spec [ADD LINK]
* view the OpenAPI v2.0.0. spec [ADD LINK]
* view the OpenAPI v3.0.0. spec [ADD LINK]

Providers can use API testing tools such as Postman to make test API calls. Providers can import the API as a collection by using Postman’s [ADD LINK] import feature and copying in the YAML URL of the API spec.

## Production environment

The production environment is the live environment which processes real data:

* API v1 [ADD LINK]
* API v2 [ADD LINK]
* API v3 [ADD LINK]

Do not perform testing in the production environment. Real participant and payment data may be affected if you do this.

### Rate limits

Providers are limited to 1,000 requests per 5 minutes when using the API in the production environment. If the limit is exceeded, providers will see `429` HTTP status codes.

This limit on requests for each authentication key is calculated on a rolling basis.
66 changes: 66 additions & 0 deletions app/views/api/guidance/glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
## Glossary

## Concepts and definitions

<table class="govuk-table">
<caption class="govuk-table__caption govuk-table__caption--m">ADD TABLE TITLE</caption>
<thead class="govuk-table__head">
<tr class="govuk-table__row">
<th scope="col" class="govuk-table__header">Concept</th>
<th scope="col" class="govuk-table__header">Definition</th>
</tr>
</thead>
<tbody class="govuk-table__body">
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>application</code></th>
<td class="govuk-table__cell">The application a person makes to be trained on an NPQ course. Applications include funding details</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>course_identifier</code></th>
<td class="govuk-table__cell">The NPQ course a participant applies for and is registered for</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>declaration</code></th>
<td class="govuk-table__cell">The notification submitted by providers via the API to trigger output payments from DfE. Declarations are submitted where there is evidence of a participant’s engagement in training for a given milestone period</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header">Milestone</th>
<td class="govuk-table__cell">Contractual retention periods during which providers must submit relevant declarations evidencing training delivery and participant retention</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header">Milestone dates</th>
<td class="govuk-table__cell">The deadline date a valid declaration can be made for a given milestone in order for DfE to be liable to make a payment the following month. Milestone dates are dependent on the participant’s schedule</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header">Milestone period</th>
<td class="govuk-table__cell">The period of time between the milestone start date and deadline date</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header">Milestone validation</th>
<td class="govuk-table__cell">The API’s process to validate declarations submitted by providers for participants in standard training schedules</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>outcome</code></th>
<td class="govuk-table__cell">The assessment result a participant achieves at the end of an NPQ course</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header">Output payment</th>
<td class="govuk-table__cell">The sum of money paid by DfE to providers per valid declaration</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>participant</code></th>
<td class="govuk-table__cell">A person registered for an NPQ course</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header">Payment date</th>
<td class="govuk-table__cell">The date DfE will make payment for valid declarations submitted by providers for a given milestone</td>
</tr>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>schedule</code></th>
<td class="govuk-table__cell">The expected timeframe in which a participant will complete their NPQ course. Schedules include defined [milestone dates](ADD LINK) against which DfE validates the declarations submitted by providers</td>
<tr class="govuk-table__row">
<th scope="row" class="govuk-table__header"><code>statement</code></th>
<td class="govuk-table__cell">A record of output payments (based on declarations), service fees and any adjustments DfE may pay lead providers at the end of a contractually agreed payment period. Statements sent to providers by DfE at the end of milestone periods can be used for invoicing purposes</td>
</tr>
</tbody>
</table>
Loading
Loading