# Add Application

:::{admonition} Related pages
:class: seealso
Add Application shares the `addApplicantV2` server implementation with
[Add Applicant](add-applicant.md) and re-uses the same success/error envelope,
XML schema, error list and acceptable-value lists. This page is **self-contained
for the request formats** and cross-references Add Applicant only for that
identical shared content. See also
[Endpoint versions](versions-and-implementation.md).
:::

## Overview

Add Application submits a **complete disclosure application** to uCheck over
HTTP as an XML payload. It supports three application kinds, each with its own
request format:

- **DBS Standard / Enhanced** — carries the full registered-body context
  (`<PotentialEmployerDetails>` and a full `<RBdetails>`).
- **DBS Basic** — an England &amp; Wales basic check;
  `<RBdetails>` is `basic` only.
- **DS Basic (Disclosure Scotland)** — a Scotland basic check; uses the
  `<DSApplicationsBatch>` root and an `<IDTypeVerified>` identity block.

Add Application is **`v2` only**. The schema supports
batching, but the API accepts a **single** application per request.

:::{admonition} Add Application vs Add Applicant
:class: note
Compared with [Add Applicant](add-applicant.md), Add Application:

- carries `<PotentialEmployerDetails>` and a full `<RBdetails>` (Add Applicant
  has neither);
- treats `<MotherMaidenname>` as **optional** for DBS checks (Add Applicant
  makes it mandatory);
- offers a full `<ApplicantIdentityDetails>` block
  (`<PassportDetails>` / `<DriverLicenceDetails>`), not just `<NINumber>`; and
- adds the **DS Basic** format for Disclosure Scotland.
:::

### Overview diagram

Below is a flow chart of the API process. Unlike [Add Applicant](add-applicant.md)
— where only the applicant information is submitted via the API and the remaining
steps are completed on the uCheck website — Add Application submits the **entire
application** (applicant information, ID details, Section Y, employer /
employment details and approve / pay). uCheck then completes the final
countersign / submit-to-DBS step.

```{mermaid}
%%{init: {'theme':'base','themeVariables':{'fontFamily':'system-ui, -apple-system, Helvetica, Arial, sans-serif','fontSize':'15px','lineColor':'#f28e00','primaryColor':'#0094dd','primaryTextColor':'#ffffff','primaryBorderColor':'#112e51'}}}%%
flowchart TD
    A([API: addApplication]):::endpoint

    subgraph SUB [Submitted via the API]
        direction TB
        S1[Add Applicant Information]:::step
        S2[Add ID Details]:::step
        S3[Add Section Y Details]:::step
        S4[Add Employer /<br/>Employment Details]:::step
        S5[Approve / Pay]:::step
    end

    S6([Countersign /<br/>Submit to DBS]):::endpoint

    A ==> S1 ==> S2 ==> S3 ==> S4 ==> S5 ==> S6

    N6[Completed by uCheck]:::note -.-> S6

    classDef endpoint fill:#112e51,stroke:#0094dd,stroke-width:2px,color:#ffffff,rx:8,ry:8;
    classDef step fill:#0094dd,stroke:#112e51,stroke-width:2px,color:#ffffff,rx:8,ry:8;
    classDef note fill:#f2f0f0,stroke:#adadad,stroke-width:1px,color:#2b2a29,rx:6,ry:6;
    style SUB fill:#eef6fb,stroke:#0094dd,stroke-width:1px,color:#112e51;
```

## Request submission

| Property | Value |
|----------|-------|
| API URL endpoint | `https://api.ucheck.co.uk/addApplication/v2` |
| Request type | `POST` |
| POST data required | Key = `xml`, Value = the XML application document (see [Request formats](#request-formats)) |

Submit an application as a `POST` request with one POST parameter named `xml`,
containing the XML application document. The demo (UAT) endpoint is
`https://uat-api.ucheck.co.uk/addApplication/v2`; see
[Endpoint versions](versions-and-implementation.md) for the full version matrix.

## Authentication

Authenticate with your unique organisation **key** in the `<uid><key>` element of
the request. Requests are additionally verified by the registered source IP
address. See [Authentication](../getting-started/authentication.md) for details.

## Rate limiting

Each registered IP is limited to 4 submissions per second; exceeding the limit
locks the IP out for one hour and returns an HTTP 429 for each submission.

## Validation

Once a request is authenticated, the submitted data is validated in two stages
before it is processed:

1. The XML request is validated against the DBS XML schema (a slightly modified
   version). A schema failure would stop the DBS accepting the application, so
   this check catches it early.
2. The request is then validated against the same logic rules the uCheck website
   applies to a manual submission (see [Further validation](#further-validation)).

Failure against either stage returns an error (see the
[Error list](add-applicant.md#a-error-list) on the Add Applicant page).

## Data format notes

- Elements shown with an `OPTIONAL` comment may be omitted; if omitted they must
  not be sent as empty elements.
- Unless stated otherwise, values must be **UPPERCASE**.
- Address history must be **sequential with no gaps** — each
  `<ResidentFromGyearMonth>` must equal the previous entry's
  `<ResidentToGyearMonth>` — and must cover **5 years**.
- `<OtherSurnames>` / `<OtherForenames>`, if present, must contain **both**
  Forename and Surname, regardless of which name changed.
- Missing or badly-formatted dates default to `1900-01`, which can produce
  misleading "date before date of birth" errors.

## Request formats

### DBS Standard / Enhanced

Complete, well-formed example. Elements marked `OPTIONAL` may be omitted; all
other elements are required.

```xml
<DBSApplicationsBatch>
  <DBSApplications>
    <DBSApplication>
      <!-- Unique application reference supplied by the customer -->
      <ApplicationReference>123456ABC</ApplicationReference>
      <!-- Main body containing the applicant details -->
      <ApplicantDetails>
        <!-- See acceptable 'Title' list in appendix -->
        <Title>MR</Title>
        <Forename>JOHN</Forename>
        <!-- OPTIONAL. Up to 3 middlenames; non-submission (where available)
             slows application processing -->
        <Middlenames>
          <Middlename>PAUL</Middlename>
          <Middlename>PETER</Middlename>
        </Middlenames>
        <PresentSurname>SMITH</PresentSurname>
        <CurrentAddress>
          <Address>
            <AddressLine1>32 WATERLOO STREET</AddressLine1>
            <!-- OPTIONAL -->
            <AddressLine2>MIDDLETON</AddressLine2>
            <AddressTown>TOWNSVILLE</AddressTown>
            <!-- OPTIONAL if UK address -->
            <AddressCounty>COUNTY</AddressCounty>
            <!-- MUST be a valid UK postcode -->
            <Postcode>MD6 5TR</Postcode>
            <!-- See acceptable 'Country Codes' list in appendix -->
            <CountryCode>GB</CountryCode>
          </Address>
          <!-- Format YYYY-MM (month must be 2 characters) -->
          <ResidentFromGyearMonth>2015-04</ResidentFromGyearMonth>
        </CurrentAddress>
        <!-- Up to 19 previous addresses; history MUST cover 5 years -->
        <PreviousAddress>
          <Address>
            <AddressLine1>35 WATERLOO STREET</AddressLine1>
            <!-- OPTIONAL -->
            <AddressLine2>MIDDLETON</AddressLine2>
            <AddressTown>TOWNSVILLE</AddressTown>
            <!-- OPTIONAL if UK address -->
            <AddressCounty>COUNTY</AddressCounty>
            <!-- OPTIONAL if non-UK (also IM, GG, JE) address -->
            <Postcode>MD6 5TR</Postcode>
            <CountryCode>GB</CountryCode>
          </Address>
          <ResidentDates>
            <ResidentFromGyearMonth>2010-02</ResidentFromGyearMonth>
            <ResidentToGyearMonth>2015-04</ResidentToGyearMonth>
          </ResidentDates>
        </PreviousAddress>
        <!-- Format YYYY-MM-DD -->
        <DateOfBirth>1968-06-07</DateOfBirth>
        <!-- male / female (lowercase) -->
        <Gender>male</Gender>
        <!-- MUST be the applicant's valid email address -->
        <ContactEmail>johnsmith@email.com</ContactEmail>
        <AdditionalApplicantDetails>
          <!-- OPTIONAL if birth surname unchanged, else mandatory -->
          <BirthSurname>JONES</BirthSurname>
          <BirthForename>JOHN</BirthForename>
          <!-- OPTIONAL if birth surname unchanged; format YYYY-MM -->
          <BirthSurnameUntil>1984-01</BirthSurnameUntil>
          <!-- OPTIONAL. Up to 10 OtherSurname entries -->
          <OtherSurnames>
            <OtherSurname>
              <Forename>JOHN</Forename>
              <Surname>BROWN</Surname>
              <UsedFrom>2010-01</UsedFrom>
              <UsedTo>2012-01</UsedTo>
            </OtherSurname>
          </OtherSurnames>
          <!-- OPTIONAL -->
          <OtherForenames>
            <OtherForename>
              <Forename>JONATHAN</Forename>
              <Surname>SMITH</Surname>
              <UsedFrom>2010-01</UsedFrom>
              <UsedTo>2012-01</UsedTo>
            </OtherForename>
          </OtherForenames>
          <!-- y / n (lowercase) -->
          <NationalityChange>y</NationalityChange>
          <!-- OPTIONAL if NationalityChange = n -->
          <CurrentNationality>US</CurrentNationality>
          <BirthTown>CHESTER</BirthTown>
          <!-- OPTIONAL -->
          <BirthCounty>CHESHIRE</BirthCounty>
          <!-- See acceptable 'Country Codes' list in appendix -->
          <BirthCountry>GB</BirthCountry>
          <BirthNationality>GB</BirthNationality>
          <!-- OPTIONAL; valid telephone number -->
          <ContactNumber>0777777333</ContactNumber>
          <!-- y / n -->
          <UnspentConvictions>n</UnspentConvictions>
          <!-- y / n. See the appendix note on 'Applicant Declaration' -->
          <DeclarationByApplicant>y</DeclarationByApplicant>
        </AdditionalApplicantDetails>
        <ApplicantIdentityDetails>
          <EvidenceCheckedBy>EVAN CHECKER</EvidenceCheckedBy>
          <!-- Must be 'y' -->
          <IdentityVerified>y</IdentityVerified>
          <!-- OPTIONAL; your cost code / PO to appear on the invoice -->
          <CostCode>PO12345</CostCode>
          <!-- OPTIONAL; valid National Insurance number -->
          <NINumber>NP828776A</NINumber>
          <!-- OPTIONAL -->
          <PassportDetails>
            <PassportNumber>210400199</PassportNumber>
            <!-- Format YYYY-MM-DD; MUST match DateOfBirth -->
            <PassportDob>1968-06-07</PassportDob>
            <PassportNationality>GB</PassportNationality>
            <PassportIssueDate>2010-02-17</PassportIssueDate>
          </PassportDetails>
          <!-- OPTIONAL. Checked against the applicant details supplied above -->
          <DriverLicenceDetails>
            <DriverLicenceNumber>XYZ99606078PR9DT</DriverLicenceNumber>
            <DriverLicenceDOB>1968-06-07</DriverLicenceDOB>
            <!-- photo / paper -->
            <DriverLicenceType>photo</DriverLicenceType>
            <DriverLicenceValidFrom>1988-05-06</DriverLicenceValidFrom>
            <DriverLicenceIssueCountry>GB</DriverLicenceIssueCountry>
          </DriverLicenceDetails>
        </ApplicantIdentityDetails>
      </ApplicantDetails>
      <PotentialEmployerDetails>
        <!-- MUST be selected from the Workforce type list (see D1) -->
        <WorkForce>Adult Workforce</WorkForce>
        <!-- Free-text description of the position applied for -->
        <PositionAppliedFor>CARE WORKER</PositionAppliedFor>
        <!-- OPTIONAL free-text company name; defaults to the name held at uCheck -->
        <OrganisationName>NEW CARE LIMITED</OrganisationName>
      </PotentialEmployerDetails>
      <!-- See the RB Details matrix (D2) -->
      <RBdetails>
        <!-- 'enhanced' / 'standard' -->
        <DisclosureType>enhanced</DisclosureType>
        <!-- y / n (standard &amp; enhanced only) -->
        <WorkingWithVulnerableAdults>y</WorkingWithVulnerableAdults>
        <WorkingWithChildren>n</WorkingWithChildren>
        <Volunteer>n</Volunteer>
        <WorkingAtHomeAddress>n</WorkingAtHomeAddress>
        <DBSAdultFirstCheck>y</DBSAdultFirstCheck>
      </RBdetails>
    </DBSApplication>
  </DBSApplications>
  <uid>
    <!-- Unique key supplied by uCheck -->
    <key>xxxxxxxxxxxxxxxxxxxxxxxxxxxx</key>
  </uid>
</DBSApplicationsBatch>
```

### DBS Basic

Identical to the Standard / Enhanced format above, but with **no**
`<PotentialEmployerDetails>` block, and `<RBdetails>` reduced to the disclosure
type only. The `<ApplicantDetails>` body (name, address history, additional
details, identity details) is exactly as shown above.

```xml
<DBSApplicationsBatch>
  <DBSApplications>
    <DBSApplication>
      <ApplicationReference>123456ABC</ApplicationReference>
      <ApplicantDetails>
        <!-- ...as in the DBS Standard / Enhanced example above... -->
      </ApplicantDetails>
      <RBdetails>
        <DisclosureType>basic</DisclosureType>
      </RBdetails>
    </DBSApplication>
  </DBSApplications>
  <uid>
    <key>xxxxxxxxxxxxxxxxxxxxxxxxxxxx</key>
  </uid>
</DBSApplicationsBatch>
```

### DS Basic (Disclosure Scotland)

A Disclosure Scotland basic check. This format differs structurally from the DBS
formats:

- the root elements are **`<DSApplicationsBatch>` / `<DSApplications>` /
  `<DSApplication>`** (not `DBS…`);
- `<MotherMaidenname>` is required in `<AdditionalApplicantDetails>`;
- `<ContactNumber>` is required; it must contain more than 9 digits, use only
  digit and space characters, and be fewer than 16 characters long;
- `<ApplicantIdentityDetails>` includes an **`<IDTypeVerified>`** block naming
  the two identity documents checked (see E1 / E2);
- `<RBdetails>` is `basic` only (no `<PotentialEmployerDetails>`).

```xml
<DSApplicationsBatch>
  <DSApplications>
    <DSApplication>
      <ApplicationReference>123456ABC</ApplicationReference>
      <ApplicantDetails>
        <!-- Title / Forename / Middlenames / PresentSurname / addresses /
             DateOfBirth / Gender / ContactEmail are exactly as in the
             DBS Standard / Enhanced example above -->
        <AdditionalApplicantDetails>
          <!-- REQUIRED for DS Basic -->
          <MotherMaidenname>SMITH</MotherMaidenname>
          <!-- ...remaining AdditionalApplicantDetails as above... -->
          <NationalityChange>y</NationalityChange>
          <BirthTown>CHESTER</BirthTown>
          <BirthCountry>GB</BirthCountry>
          <BirthNationality>GB</BirthNationality>
          <!-- REQUIRED for DS Basic: more than 9 digits; digits and spaces only;
               fewer than 16 characters -->
          <ContactNumber>0777777333</ContactNumber>
          <UnspentConvictions>n</UnspentConvictions>
          <DeclarationByApplicant>y</DeclarationByApplicant>
        </AdditionalApplicantDetails>
        <ApplicantIdentityDetails>
          <EvidenceCheckedBy>EVAN CHECKER</EvidenceCheckedBy>
          <IdentityVerified>y</IdentityVerified>
          <!-- OPTIONAL PassportDetails / DriverLicenceDetails as above -->
          <IDTypeVerified>
            <!-- Acceptable DS ID type (see E1) -->
            <ID1>Passport</ID1>
            <!-- Acceptable DS proof of address type (see E2) -->
            <ID2>Mortgage statement</ID2>
          </IDTypeVerified>
        </ApplicantIdentityDetails>
      </ApplicantDetails>
      <RBdetails>
        <DisclosureType>basic</DisclosureType>
      </RBdetails>
    </DSApplication>
  </DSApplications>
  <uid>
    <key>xxxxxxxxxxxxxxxxxxxxxxxxxxxx</key>
  </uid>
</DSApplicationsBatch>
```

## Field constraints

The core `<ApplicantDetails>` fields (name, address, dates, nationality, contact,
identity documents, etc.) share the same constraints as
[Add Applicant](add-applicant.md#addapplicant-format). The constraints for the
fields **unique to Add Application** are:

| XML value | Constraint | Value |
|----|----|----|
| WorkForce | Length | 1–60; must be an accepted Workforce type (see D1) |
| PositionAppliedFor | Length | 1–60 |
|  | Reg Ex pattern | `([A-Z0-9\(\)\-/'&]+)\|([A-Z0-9\(\)\-/'&][A-Z 0-9\(\)\-/'&]*[A-Z0-9\(\)\-/'&])` |
| OrganisationName | Length | 1–32 |
|  | Reg Ex pattern | `([A-Z0-9\(\)\-/'&]+)\|([A-Z0-9\(\)\-/'&][A-Z 0-9\(\)\-/'&]*[A-Z0-9\(\)\-/'&])` |
| DisclosureType | Must be one of | `enhanced`, `standard`, `basic` |
| WorkingWithVulnerableAdults | Must be one of | `y` / `n` (enhanced &amp; standard only) |
| WorkingWithChildren | Must be one of | `y` / `n` (enhanced &amp; standard only) |
| Volunteer | Must be one of | `y` / `n` (enhanced &amp; standard only) |
| WorkingAtHomeAddress | Must be one of | `y` / `n` (enhanced &amp; standard only) |
| DBSAdultFirstCheck | Must be one of | `y` / `n` (enhanced &amp; standard only) |
| ID1 | Must be in list | Acceptable DS ID types – see E1 |
| ID2 | Must be in list | Acceptable DS proof of address types – see E2 |

## Further validation

Once the DBS XML schema check passes, submitted data is validated against the
following logic rules:

1. The applicant must be **16 or over and under 110**.
2. All UK (also IM, GG, JE) addresses must have valid postcodes.
3. `<Title>` must reflect `<Gender>`.
5. Address history must be sequential with no gaps and cover **5 years**.
6. Any previous UK (also IM, GG, JE) address must have a valid postcode; non-UK
   addresses need a `<County>` instead of a postcode.
7. Dates must not be in the future or before the date of birth.
8. If a National Insurance number is supplied it must be valid.
9. If a passport is supplied: a UK-issued passport number must be valid, and the
   passport date of birth must match `<DateOfBirth>`.
10. If a UK driving licence is supplied, the driver number (16 characters,
    encoding surname / date of birth / initials) must be valid and must match the
    applicant details supplied earlier in the application.

Failure against any rule returns an error (see the
[Error list](add-applicant.md#a-error-list)).

## Success &amp; error responses

The success and error response envelope is **identical** to Add Applicant. A
successful submission returns:

```xml
<SUCCESS>
  <response>
    <success>true</success>
    <ApplicationReference>123456ABC</ApplicationReference>
    <uCheckReference>HR0001000</uCheckReference>
    <CompanyCode>ABCCARE</CompanyCode>
  </response>
</SUCCESS>
```

For the full authentication / schema / validation / system error shapes, see the
[Error list](add-applicant.md#a-error-list) on the Add Applicant page.

## Appendices

### D1 Workforce type

`<WorkForce>` must be one of:

- Child Workforce
- Adult Workforce
- Child and Adult Workforce
- Other Workforce

### D2 RB Details matrix

| Disclosure Type | Vulnerable Adults | Children | Volunteer | Working from home | DBS Adult First Check |
|--|:--:|:--:|:--:|:--:|:--:|
| enhanced | Y/N | Y/N | Y/N | Y/N | Y/N |
| standard | N | N | Y/N | Y/N | N |
| basic | N/A | N/A | N/A | N/A | N/A |

Failure to meet the above criteria will result in application rejection.

### E1 Acceptable DS ID types

`<ID1>` must be one of the following (exactly as written):

- Passport (photo page only)
- Driving licence photocard (full or provisional)
- Biometric residence permit (BRP)
- National identity card from a country outside the European Economic Area (EEA)
- Birth certificate
- Adoption certificate
- Marriage certificate or civil partnership certificate
- NHS card
- UK armed forces identity card
- UK firearm or shotgun certificate

### E2 Acceptable DS proof of address types

`<ID2>` must be one of the following (exactly as written), issued within the last
12 months:

- Utility bill, such as gas, electric or phone bill
- Council tax bill or letter
- Driving licence photocard (full or provisional)
- Bank or credit card statement
- Mortgage statement
- Tenancy agreement (typed, not handwritten)
- Insurance policy document or letter
- Payslip or P60
- P45
- UK hospital or doctor's letter
- UK TV Licence
- University, college or school letter
- UK Electoral Register Office letter or UK polling card
- Home Office letter
- UK firearm or shotgun certificate
- UK solicitor's letter on headed paper

### Shared appendices

The XML **schema** (Common + SubmitDisclosureApplication), the **acceptable
Title list** and the **acceptable Country Codes list** are identical to
Add Applicant. See:

- [Schema](add-applicant.md#b-schema)
- [Acceptable Title list](add-applicant.md#c2-acceptable-title)
- [Acceptable Country Codes](add-applicant.md#c3-acceptable-country-codes)

## Version history

| Version | Date | Description |
|---------|------|-------------|
| 1.6 |  | Add Application specification (DBS Standard / Enhanced, DBS Basic, DS Basic). |