Credentially DBS API
DBS check lookup and refresh endpoints
OpenAPI Specification
openapi: 3.1.0
info:
title: Credentially Public Compliance-packages DBS API
description: Public API Proxy with Rate Limiting and Audit
version: 2.0.0
servers:
- url: https://app.credentially.io/gateway
description: Generated server url
tags:
- name: DBS
description: DBS check lookup and refresh endpoints
paths:
/api/dbs/{profileId}:
get:
tags:
- DBS
summary: Get Profile DBS Checks
description: 'Returns all DBS checks for the requested profile in the authenticated organisation context. The public `profileId` path parameter maps to the upstream `employeePublicId`.
**Rate Limit:** `profile-dbs-load` (100 req / 1s)'
operationId: getProfileDbsChecks
parameters:
- name: profileId
in: path
description: Credentially profile ID. This maps to the upstream employeePublicId.
required: true
schema:
type: string
example: a7b80d86-92ad-452b-8b30-580146e5e1fb
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
responses:
'200':
description: DBS checks retrieved successfully
content:
'*/*':
schema:
type: array
items:
$ref: '#/components/schemas/DbsCheckDto'
examples:
dbsChecks:
description: dbsChecks
value:
- id: 501
certificateNumber: '001122334455'
status: NEW_INFO
surname: Doe
forename: Jane
printDate: '2026-04-01'
organisationId: 100
requestAttempts: 1
lastCheckDateTime: '2026-04-01T12:08:10.178Z'
createDateTime: '2026-04-01T12:08:10.178Z'
level: Enhanced
'404':
description: Returned when the profile has no DBS checks or when the upstream profile cannot be found
'500':
description: Internal server error
'429':
description: Too many requests - the rate limit for this endpoint has been exceeded. Use the Retry-After header to determine when to retry.
headers:
Retry-After:
description: Number of seconds to wait before retrying the request.
schema:
type: integer
format: int32
example: 1
security:
- bearer-key: []
post:
tags:
- DBS
summary: Create Or Refresh Profile DBS Check
description: 'Creates or refreshes a DBS check for the requested profile in the authenticated organisation context. The public `profileId` path parameter maps to the upstream `employeePublicId`. Provide the certificate details exactly as shown on the DBS certificate.
**Rate Limit:** `profile-dbs-load` (100 req / 1s)'
operationId: updateProfileDbsCheck
parameters:
- name: profileId
in: path
description: Credentially profile ID. This maps to the upstream employeePublicId.
required: true
schema:
type: string
example: a7b80d86-92ad-452b-8b30-580146e5e1fb
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
requestBody:
description: Certificate details used to create or refresh the DBS check
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateDbsCheckRequest'
examples:
updateDbsCheckRequest:
description: updateDbsCheckRequest
value:
certificateNumber: '001122334455'
birthDate: '1990-01-15'
employeeSurname: Doe
issueDate: '2026-04-01'
required: true
responses:
'200':
description: DBS check updated successfully
content:
'*/*':
schema:
$ref: '#/components/schemas/DbsCheckDto'
examples:
updatedDbsCheck:
description: updatedDbsCheck
value:
id: 501
certificateNumber: '001122334455'
status: NON_BLANK_NO_NEW_INFO
surname: Doe
forename: Jane
printDate: '2026-04-01'
organisationId: 100
requestAttempts: 3
lastCheckDateTime: '2026-04-01T12:08:10.178Z'
createDateTime: '2026-04-01T12:08:10.178Z'
'400':
description: Invalid request data
'404':
description: Profile not found in the authenticated organisation context
'429':
description: Too many DBS refresh attempts for the submitted certificate
headers:
Retry-After:
description: Number of seconds to wait before retrying the request.
schema:
type: integer
format: int32
example: 1
'500':
description: Internal server error
security:
- bearer-key: []
/api/dbs/{profileId}/{dbsCheckId}:
get:
tags:
- DBS
summary: Get Profile DBS Check
description: 'Returns a single DBS check for the requested profile in the authenticated organisation context. The public `profileId` path parameter maps to the upstream `employeePublicId`.
**Rate Limit:** `profile-dbs-by-id` (100 req / 1s)'
operationId: getProfileDbsCheck
parameters:
- name: profileId
in: path
description: Credentially profile ID. This maps to the upstream employeePublicId.
required: true
schema:
type: string
example: a7b80d86-92ad-452b-8b30-580146e5e1fb
- name: dbsCheckId
in: path
description: Credentially DBS check ID for a single DBS result.
required: true
schema:
type: integer
format: int64
example: 501
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
responses:
'200':
description: DBS check retrieved successfully
content:
'*/*':
schema:
$ref: '#/components/schemas/DbsCheckDto'
examples:
dbsCheck:
description: dbsCheck
value:
id: 501
certificateNumber: '001122334455'
status: NEW_INFO
surname: Doe
forename: Jane
printDate: '2026-04-01'
organisationId: 100
requestAttempts: 1
lastCheckDateTime: '2026-04-01T12:08:10.178Z'
createDateTime: '2026-04-01T12:08:10.178Z'
level: Enhanced
'404':
description: Returned when the DBS check cannot be found or when the upstream profile cannot be found
'500':
description: Internal server error
'429':
description: Too many requests - the rate limit for this endpoint has been exceeded. Use the Retry-After header to determine when to retry.
headers:
Retry-After:
description: Number of seconds to wait before retrying the request.
schema:
type: integer
format: int32
example: 1
security:
- bearer-key: []
components:
schemas:
DbsCheckDto:
type: object
description: DBS check payload returned by the Credentially public API.
properties:
id:
type: integer
format: int64
description: Credentially DBS check identifier.
example: 501
certificateNumber:
type: string
description: DBS certificate number used for the check.
example: '001122334455'
status:
type: string
description: Current DBS status for this certificate lookup.
enum:
- BLANK_NO_NEW_INFO
- NON_BLANK_NO_NEW_INFO
- NEW_INFO
- UNKNOWN
- NO_MATCH_FOUND
example: NEW_INFO
surname:
type: string
description: Surname returned for the DBS check.
example: Doe
forename:
type: string
description: Forename returned for the DBS check.
example: Jane
printDate:
type: string
format: date
description: Date printed on the DBS certificate.
example: '2026-04-01'
organisationId:
type: integer
format: int64
description: Credentially organisation identifier that owns the DBS check.
example: 100
requestAttempts:
type: integer
format: int32
description: Number of DBS refresh attempts made for this certificate.
example: 3
lastCheckDateTime:
type: string
format: date-time
description: Timestamp of the latest DBS check lookup in UTC.
example: '2026-04-01T12:08:10.178Z'
createDateTime:
type: string
format: date-time
description: Timestamp when the DBS check record was created in UTC.
example: '2026-04-01T12:08:10.178Z'
level:
type: string
description: Level of this specific DBS check (for example Enhanced, Standard or Basic), sourced from the DBS application whose certificate matches this check's certificate number. Absent when the level is unknown - i.e. this check's certificate was not issued via a DBS application in Credentially.
example: Enhanced
UpdateDbsCheckRequest:
type: object
properties:
certificateNumber:
type: string
description: DBS certificate number
example: '001122334455'
minLength: 1
pattern: \d{12}
birthDate:
type: string
format: date
description: Profile birth date
example: '1990-01-15'
employeeSurname:
type: string
description: Profile surname used for the DBS request
example: Doe
maxLength: 60
minLength: 0
pattern: ^[A-Za-z0-9\- ']*$
issueDate:
type: string
format: date
description: Issue date to send when no downstream print date is returned
example: '2026-04-01'
required:
- birthDate
- certificateNumber
- employeeSurname
securitySchemes:
bearer-key:
type: http
scheme: bearer
bearerFormat: JWT