Credentially Profiles API
Profile management proxy endpoints
OpenAPI Specification
openapi: 3.1.0
info:
title: Credentially Public Compliance-packages Profiles 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: Profiles
description: Profile management proxy endpoints
paths:
/api/profile/{profileId}/tags:
get:
tags:
- Profiles
summary: List Profile Tags
description: 'Returns the tags currently assigned to a profile.
**Rate Limit:** `load-profile-tags` (100 req / 1s)'
operationId: loadProfileTags
parameters:
- name: profileId
in: path
required: true
schema:
type: string
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
responses:
'200':
description: Tags loaded successfully
content:
'*/*':
schema:
type: array
items:
type: string
example: locum
'404':
description: Profile not 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: []
put:
tags:
- Profiles
summary: Set Profile Tags
description: 'Replaces the full set of tags on a profile with the supplied tags. Send an empty array to clear all tags.
**Rate Limit:** `load-profile-tags` (100 req / 1s)'
operationId: updateProfileTags
parameters:
- name: profileId
in: path
required: true
schema:
type: string
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateProfileTagsRequestDto'
required: true
responses:
'200':
description: Tags updated successfully
content:
'*/*':
schema:
type: array
items:
type: string
example: locum
'400':
description: Invalid request data
'404':
description: Profile not 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: []
/api/profile/{profileId}/force-activate:
put:
tags:
- Profiles
summary: Force-activate Profile
description: 'Forces a not-yet-active candidate to ACTIVE, bypassing the invitation-acceptance step: an IMPORTED candidate (added but never invited) or an INVITED candidate (invited but not yet accepted) becomes ACTIVE immediately, so they can be emailed and can sign in. Distinct from PUT /{profileId}/activate, which only reactivates a previously ARCHIVED profile. Idempotent on profiles that are already ACTIVE.
**Rate Limit:** `force-activate-profile` (25 req / 1s)'
operationId: forceActivateProfile
parameters:
- name: profileId
in: path
required: true
schema:
type: string
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
responses:
'200':
description: Profile force-activated
'404':
description: Profile not 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: []
/api/profile/{profileId}/archive:
put:
tags:
- Profiles
summary: Archive Profile
description: 'Archives a profile within the organisation.
**Rate Limit:** `archive-profile` (25 req / 1s)'
operationId: archiveProfile
parameters:
- name: profileId
in: path
required: true
schema:
type: string
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
responses:
'200':
description: Profile archived
'404':
description: Profile not 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: []
/api/profile/{profileId}/activate:
put:
tags:
- Profiles
summary: Activate Profile (un-archive)
description: 'Reactivates a previously ARCHIVED profile (reverses archive). This does NOT activate a candidate who was never invited or has not yet accepted their invitation — for that use PUT /{profileId}/force-activate.
**Rate Limit:** `activate-profile` (25 req / 1s)'
operationId: activateProfile
parameters:
- name: profileId
in: path
required: true
schema:
type: string
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
responses:
'200':
description: Profile activated
'404':
description: Profile not 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: []
/api/profile:
get:
tags:
- Profiles
summary: Load Profiles
description: 'Fetches a paginated list of profiles for the organisation.
**Rate Limit:** `create-profile` (25 req / 1s)'
operationId: loadProfiles
parameters:
- name: page
in: query
required: false
schema:
type: integer
format: int32
default: 0
- name: size
in: query
required: false
schema:
type: integer
format: int32
default: 20
- name: name
in: query
description: Smart search of first name, last name and email
required: false
schema:
type: string
description: Smart search of first name, last name and email
- name: complianceStatus
in: query
description: Compliance status
required: false
schema:
type: string
description: Compliance status
enum:
- COMPLIANT
- NOT_COMPLIANT
- name: complianceTag
in: query
required: false
schema:
type: array
description: Compliance tags
example:
- REFERENCE_AWAITING_APPROVAL
- REFERENCE_BOUNCED
- REFERENCE_NOT_ENOUGH
- DOCUMENTS_DECLINED
- DOCUMENTS_AWAITING_APPROVAL
- DOCUMENTS_MISSING
items:
type: string
- name: groups
in: query
required: false
schema:
type: array
description: Groups
example:
- group01-public-id
- group02-public-id
- group03-public-id
items:
type: string
- name: jobPositionStatus
in: query
required: false
schema:
type: array
items:
type: string
description: Job position status
enum:
- ACTIVE
- INVITED
- IMPORTED
- ARCHIVED
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
responses:
'200':
description: Profiles loaded
content:
'*/*':
schema:
$ref: '#/components/schemas/ProfileListPageDto'
'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: []
put:
tags:
- Profiles
summary: Create Profile
description: 'Creates a new profile and optionally populates custom fields in a single transaction.
**Rate Limit:** `create-profile` (25 req / 1s)'
operationId: createProfile
parameters:
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProfileRequestDto'
required: true
responses:
'201':
description: Profile created successfully
content:
'*/*':
schema:
$ref: '#/components/schemas/CreateProfileResponseDto'
'400':
description: Invalid request data (e.g. invalid role)
'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: []
patch:
tags:
- Profiles
summary: Update Profile Fields
description: 'Updates fields for an existing profile identified by email.
**Rate Limit:** `create-profile` (25 req / 1s)'
operationId: updateProfileFields
parameters:
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateProfileFieldsRequestDto'
required: true
responses:
'200':
description: Fields updated successfully
content:
'*/*':
schema:
$ref: '#/components/schemas/CreateProfileResponseDto'
'404':
description: Profile not found for email
'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: []
/api/profile/{profileId}/notes:
get:
tags:
- Profiles
summary: Load Profile Notes
description: 'Loads notes for a profile.
**Rate Limit:** `load-profile-notes` (100 req / 1s)'
operationId: loadProfileNotes
parameters:
- name: profileId
in: path
required: true
schema:
type: string
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
responses:
'200':
description: Notes loaded successfully
content:
'*/*':
schema:
type: array
items:
$ref: '#/components/schemas/ProfileNoteDto'
'404':
description: Profile not 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:
- Profiles
summary: Create Profile Note
description: 'Creates a note for a profile.
**Rate Limit:** `load-profile-notes` (100 req / 1s)'
operationId: createProfileNote
parameters:
- name: profileId
in: path
required: true
schema:
type: string
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateProfileNoteRequestDto'
required: true
responses:
'201':
description: Note created successfully
content:
'*/*':
schema:
$ref: '#/components/schemas/ProfileNoteDto'
examples:
createProfileNoteRequest:
description: createProfileNoteRequest
value:
mentionedPublicIds:
- user-1
note: Candidate confirmed their availability for the next onboarding step.
'400':
description: Invalid request data
'404':
description: Profile not 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: []
/api/profile/{profileId}:
get:
tags:
- Profiles
summary: Get Profile by ID
description: 'Fetches detailed profile information for a profile by their ID, including enriched custom fields.
**Rate Limit:** `profile-by-id` (100 req / 1s)'
operationId: getProfileById
parameters:
- name: profileId
in: path
required: true
schema:
type: string
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
responses:
'200':
description: Profile found
content:
'*/*':
schema:
$ref: '#/components/schemas/ProfileDetailDto'
'404':
description: Profile not 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: []
delete:
tags:
- Profiles
summary: Delete Profile
description: 'Deletes a profile from the organisation.
**Rate Limit:** `profile-by-id` (100 req / 1s)'
operationId: deleteProfile
parameters:
- name: profileId
in: path
required: true
schema:
type: string
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
responses:
'204':
description: Profile deleted
'404':
description: Profile not 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: []
/api/profile/metadata:
get:
tags:
- Profiles
summary: Get Profile Metadata
description: 'Fetches and aggregates profile metadata fields (schema) and available roles for the organisation.
**Rate Limit:** `profile-metadata` (100 req / 1s)'
operationId: getProfileMetadata
parameters:
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
responses:
'200':
description: Metadata retrieved successfully
content:
'*/*':
schema:
$ref: '#/components/schemas/OrganisationMetadataDto'
'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: []
/api/profile/find:
get:
tags:
- Profiles
summary: Get Profile by Email
description: 'Fetches detailed profile information, including enriched custom fields.
**Rate Limit:** `profile-by-email` (100 req / 1s)'
operationId: getProfileByEmail
parameters:
- name: email
in: query
required: true
schema:
type: string
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
responses:
'200':
description: Profile found
content:
'*/*':
schema:
$ref: '#/components/schemas/ProfileDetailDto'
'404':
description: Profile not 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: []
/api/profile/all:
get:
tags:
- Profiles
summary: List All Profiles (Lightweight)
description: 'Fetches a non-paginated list of all profiles for the organisation with lightweight information.
**Rate Limit:** `load-all-profiles` (5 req / 1s)'
operationId: loadAllProfiles
parameters:
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
responses:
'200':
description: Profiles loaded
content:
'*/*':
schema:
type: array
items:
$ref: '#/components/schemas/ProfileLightDto'
'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: []
/api/profile/{profileId}/tags/{tagName}:
delete:
tags:
- Profiles
summary: Remove Profile Tag
description: 'Removes a single tag from a profile. The tag name must be URL-encoded.
**Rate Limit:** `delete-profile-tag` (25 req / 1s)'
operationId: deleteProfileTag
parameters:
- name: profileId
in: path
required: true
schema:
type: string
- name: tagName
in: path
required: true
schema:
type: string
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
responses:
'200':
description: Tag removed successfully
'404':
description: Profile not 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: []
/api/profile/{profileId}/notes/{noteId}:
delete:
tags:
- Profiles
summary: Delete Profile Note
description: 'Deletes a note from a profile.
**Rate Limit:** `delete-profile-note` (25 req / 1s)'
operationId: deleteProfileNote
parameters:
- name: profileId
in: path
required: true
schema:
type: string
- name: noteId
in: path
required: true
schema:
type: string
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
responses:
'204':
description: Note deleted successfully
'404':
description: Profile or note not 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:
OrganisationRoleDto:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
description:
type: string
staffType:
type: string
reserved:
type: boolean
accessTags:
type: array
items:
type: string
employeesCount:
type: integer
format: int32
signUpAllowed:
type: boolean
GradeDto:
type: object
properties:
code:
type: string
name:
type: string
JobPositionDto:
type: object
properties:
id:
type: integer
format: int64
status:
type: string
archivedDateTime:
type: string
startDate:
type: string
trialEndDate:
type: string
endDate:
type: string
signedOff:
type: boolean
skipOnboarding:
type: boolean
workSiteId:
type: integer
format: int64
role:
$ref: '#/components/schemas/RoleDto'
complianceStatus:
type: string
complianceStatusTags:
type: array
items:
$ref: '#/components/schemas/ComplianceTagDto'
uniqueItems: true
HcpcRegistrationDetailsDto:
type: object
properties:
fullName:
type: string
surname:
type: string
givenName:
type: string
speciality:
type: string
profCode:
type: string
town:
type: string
status:
type: string
registeredFrom:
type: string
format: date
registeredTo:
type: string
format: date
localAnaesthetic:
type: string
prescriptionOnlyMedicine:
type: string
supplementaryPrescribing:
type: string
independentPrescribing:
type: string
modalities:
type: string
lastCheckDateTime:
type: string
format: date-time
RoleExtendedDto:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
description:
type: string
staffType:
type: string
reserved:
type: boolean
accessTags:
type: array
items:
type: string
ChecklistStepStatusApprovalDto:
type: object
properties:
type:
type: string
approver:
$ref: '#/components/schemas/EmployeeBasicDto'
NmcRegistrationDetailsDto:
type: object
properties:
fullName:
type: string
birthDate:
type: string
format: date
status:
type: string
qualifications:
type: array
items:
$ref: '#/components/schemas/NmcQualificationDto'
lastCheckDateTime:
type: string
format: date-time
CreateProfileRequestDto:
type: object
properties:
email:
type: string
minLength: 1
roleName:
type: string
minLength: 1
firstName:
type: string
lastName:
type: string
birthDate:
type: string
format: date
registrationNumber:
type: string
phone:
type: string
skipOnboarding:
type: boolean
sendInviteEmail:
type: boolean
forceActivate:
type: boolean
default: false
description: When true, the created candidate is immediately force-activated (IMPORTED/INVITED → ACTIVE), bypassing the invitation-acceptance step, so they can be emailed and can sign in straight away. Intended for provisioning an already-active member without sending an invitation — typically used with sendInviteEmail = false/null. Defaults to false.
example: false
groups:
type: array
items:
$ref: '#/components/schemas/OrganisationGroupDto'
fields:
type: array
items:
$ref: '#/components/schemas/CustomFieldInputDto'
required:
- email
- roleName
ProfileMetadataResultDto:
type: object
properties:
name:
type: string
jsonSchema:
type: object
additionalProperties: {}
CreateProfileResponseDto:
type: object
properties:
customFieldUpdateResult:
type: string
profileDto:
$ref: '#/components/schemas/ProfileDto'
CreateProfileNoteRequestDto:
type: object
description: Request body for creating a profile note.
properties:
mentionedPublicIds:
type: array
description: Optional list of public user IDs mentioned in the note.
example:
- user-1
- user-2
items:
type: string
uniqueItems: true
note:
type: string
description: Note message to add to the profile.
example: Candidate confirmed their availability for the next onboarding step.
maxLength: 2048
minLength: 0
required:
- note
CustomFieldDto:
type: object
properties:
shortName:
type: string
name:
type: string
value: {}
ConditionsDetailDto:
type: object
properties:
ftpConditionsExist:
type: boolean
ftpUndertakingsExist:
type: boolean
ftpWarningsExist:
type: boolean
HistoryActorDto:
type: object
properties:
id:
type: string
fullName:
type: string
roleName:
type: string
avatarUrl:
type: string
active:
type: boolean
ProfileDetailDto:
type: object
properties:
id:
type: string
firstName:
type: string
lastName:
type: string
title:
$ref: '#/components/schemas/UserTitleDto'
gender:
type: string
birthDate:
type: string
format: date
gradeName:
$ref: '#/components/schemas/GradeDto'
otherGrade:
type: string
medicalCategory:
type: string
medicalSpecialty:
type: string
personnelType:
$ref: '#/components/schemas/RoleExtendedDto'
jobs:
type: array
items:
$ref: '#/components/schemas/JobPositionDto'
uniqueItems: true
complianceStatus:
type: string
email:
type: string
complianceStatusTags:
type: array
items:
$ref: '#/components/schemas/ComplianceTagDto'
uniqueItems: true
customProfileFields:
type: array
items:
$ref: '#/components/schemas/CustomFieldDto'
registrationNumber:
type: string
writeOnly: true
registrationNumberType:
type: string
writeOnly: true
registrationNumberStatus:
type: string
writeOnly: true
gmcInfo:
$ref: '#/components/schemas/GmcRegistrationDetailsDto'
writeOnly: true
nmcData:
$ref: '#/components/schemas/NmcRegistrationDetailsDto'
writeOnly: true
hcpcInfo:
$ref: '#/components/schemas/HcpcRegistrationDetailsDto'
writeOnly: true
professionalRegistration:
$ref: '#/components/schemas/ProfessionalRegistrationDto'
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/credentially/refs/heads/main/openapi/credentially-profiles-api-openapi.yml