Credentially Documents API
Document management proxy endpoints
OpenAPI Specification
openapi: 3.1.0
info:
title: Credentially Public Compliance-packages Documents 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: Documents
description: Document management proxy endpoints
paths:
/api/documents/{profileId}:
get:
tags:
- Documents
summary: Get Profile Documents
description: 'Fetches documents for a profile, enriched with extra OCR fields.
**Rate Limit:** `get-documents` (100 req / 1s)'
operationId: getDocuments
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: Documents retrieved successfully
content:
'*/*':
schema:
type: array
items:
$ref: '#/components/schemas/DocumentDto'
'404':
description: Documents or 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:
- Documents
summary: Upload Profile Document
description: 'Uploads a document for a specific profile and triggers processing.
**Rate Limit:** `get-documents` (100 req / 1s)'
operationId: uploadDocument
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:
multipart/form-data:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/DocumentUploadRequest'
file:
type: string
format: binary
required:
- data
- file
encoding:
data:
contentType: application/json
responses:
'200':
description: Document uploaded and processing started
'400':
description: Invalid request data
'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/documents/reject:
patch:
tags:
- Documents
summary: Reject document of file.
description: 'Decline specific document and file.
**Rate Limit:** `reject-document` (5 req / 1s)'
operationId: reject
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/FileRequest'
encoding:
note:
contentType: application/json
required: true
responses:
'200':
description: Document declined successfully
'400':
description: Bad request, e.g. 'VerifierPublicId not found'
'404':
description: Document or file 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/documents/approve:
patch:
tags:
- Documents
summary: Approve document of file.
description: 'Approve specific document and file.
**Rate Limit:** `approve-document` (5 req / 1s)'
operationId: approve_1
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/FileRequest'
encoding:
note:
contentType: application/json
required: true
responses:
'200':
description: Document approved successfully
'400':
description: Bad request, e.g. 'VerifierPublicId not found'
'404':
description: Document or file 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/documents/download:
get:
tags:
- Documents
summary: Download file by its id
description: 'Download file by its id.
**Rate Limit:** `download-file` (5 req / 1s)'
operationId: downloadFile
parameters:
- name: fileId
in: query
required: true
schema:
type: integer
format: int64
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
responses:
'200':
description: File downloaded successfully
content:
'*/*':
schema:
type: string
format: binary
'500':
description: File not found
'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/documents/document-types:
get:
tags:
- Documents
summary: Get Organisation Document Types
description: 'Fetches document types for an organisation.
**Rate Limit:** `get-document-types` (100 req / 1s)'
operationId: getDocumentTypes
parameters:
- name: X-API-Version
in: header
schema:
type: string
default: 2.0.0
enum:
- 2.0.0
responses:
'200':
description: Document types retrieved successfully
content:
'*/*':
schema:
type: array
items:
$ref: '#/components/schemas/OrganisationDocumentTypeDto'
'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:
DocumentTypeDto:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
description:
type: string
key:
type: string
shortName:
type: string
ocrModelCode:
type: string
ocrModelName:
type: string
expiryPeriodInMonths:
type: integer
format: int32
expireSoonPeriodInDays:
type: integer
format: int32
category:
type: string
reminderText:
type: string
ocrSupported:
type: boolean
common:
type: boolean
profileOwnerRestricted:
type: boolean
ocrModel:
type: object
additionalProperties: {}
writeOnly: true
VerificationDto:
type: object
properties:
verificationType:
type: string
note:
type: string
created:
type: string
format: date-time
verifier:
$ref: '#/components/schemas/UserSummaryDto'
FileRequest:
type: object
description: 'Request body for approving/declining a file.
''documentPublicId'', ''fileId'' and ''organisationId'' are mandatory; ''note'' is mandatory only for rejecting.
'
properties:
documentPublicId:
type: string
fileId:
type: integer
format: int64
organisationId:
type: integer
format: int64
note:
type: string
verifierPublicId:
type: string
description: 'The public Id from the profile that will be marked as the verifier on approval.
This field is required when the session token is from a public-api (server-to-server).
In other cases this parameter is not required and even ignored to use the id from the user in session.
'
UserSummaryDto:
type: object
properties:
id:
type: string
firstName:
type: string
lastName:
type: string
smallAvatarUrl:
type: string
roleName:
type: string
active:
type: boolean
OrganisationDocumentTypeDto:
type: object
properties:
id:
type: integer
format: int64
name:
type: string
description:
type: string
key:
type: string
shortName:
type: string
ocrModelCode:
type: string
ocrModelName:
type: string
expiryPeriodInMonths:
type: integer
format: int32
expireSoonPeriodInDays:
type: integer
format: int32
category:
type: string
reminderText:
type: string
ocrSupported:
type: boolean
common:
type: boolean
profileOwnerRestricted:
type: boolean
createdBy:
type: string
restrictAccessRoles:
type: array
items:
$ref: '#/components/schemas/BaseRoleDto'
approvalRoles:
type: array
items:
$ref: '#/components/schemas/BaseRoleDto'
ocrModel:
type: object
additionalProperties: {}
writeOnly: true
ActiveFileDto:
type: object
properties:
id:
type: integer
format: int64
publicId:
type: string
originName:
type: string
extraOcrFields:
type: object
additionalProperties: {}
issued:
type: string
format: date
expiry:
type: string
format: date
monthToExpire:
type: integer
format: int32
daysToExpire:
type: integer
format: int32
created:
type: string
format: date-time
issuesReason:
type: string
verifications:
type: array
items:
$ref: '#/components/schemas/VerificationDto'
actualVerificationStatuses:
type: array
items:
$ref: '#/components/schemas/VerificationStatusDto'
statusType:
type: string
uploader:
$ref: '#/components/schemas/UserSummaryDto'
VerificationStatusDto:
type: object
properties:
status:
type: string
verifier:
$ref: '#/components/schemas/UserSummaryDto'
approvalRole:
type: string
verifiedDate:
type: string
format: date-time
DocumentUploadRequest:
type: object
description: Request body for uploading a document.
properties:
uploaderId:
type: string
description: Mandatory profile ID of the uploader
minLength: 1
documentTypeKey:
type: string
otherDocumentTypeName:
type: string
skipDuplicates:
type: boolean
required:
- uploaderId
DocumentDto:
type: object
properties:
id:
type: string
description:
type: string
type:
$ref: '#/components/schemas/DocumentTypeDto'
otherTypeName:
type: string
profileId:
type: string
versions:
type: integer
format: int32
activeFile:
$ref: '#/components/schemas/ActiveFileDto'
statusType:
type: string
BaseRoleDto:
type: object
properties:
roleId:
type: integer
format: int64
roleName:
type: string
securitySchemes:
bearer-key:
type: http
scheme: bearer
bearerFormat: JWT