Add Application

Related pages

Add Application shares the addApplicantV2 server implementation with Add Applicant 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.

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 & 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.

Add Application vs Add Applicant

Compared with Add Applicant, 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 — 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.

%%{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)

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 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 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).

Failure against either stage returns an error (see the 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.

<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.

<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>).

<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. 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 & standard only)

WorkingWithChildren

Must be one of

y / n (enhanced & standard only)

Volunteer

Must be one of

y / n (enhanced & standard only)

WorkingAtHomeAddress

Must be one of

y / n (enhanced & standard only)

DBSAdultFirstCheck

Must be one of

y / n (enhanced & 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>.

  4. Address history must be sequential with no gaps and cover 5 years.

  5. Any previous UK (also IM, GG, JE) address must have a valid postcode; non-UK addresses need a <County> instead of a postcode.

  6. Dates must not be in the future or before the date of birth.

  7. If a National Insurance number is supplied it must be valid.

  8. If a passport is supplied: a UK-issued passport number must be valid, and the passport date of birth must match <DateOfBirth>.

  9. 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).

Success & error responses

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

<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 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:

Version history

Version

Date

Description

1.6

Add Application specification (DBS Standard / Enhanced, DBS Basic, DS Basic).