openapi: 3.2.0 info: title: Identity Documents API description: Registration, verification and management of CFX identities associated with financial transactions on the CFX network. termsOfService: '' contact: name: API Owner email: api@cfxlabs.com license: name: '' url: '' version: '@VERSION@' summary: CFX Identity API servers: - url: https://api.dev.cfx.to description: Customer Sandbox - url: https://api.cfx.to description: Production security: - ApiKeyAuth: [] ApiSecretAuth: [] tags: - name: Identity Documents description: Upload and manage KYC documents for an identity. paths: /v1/identity/{identityId}/documents: post: summary: Initiate an identity document upload tags: - Identity Documents description: Reserve a presigned PUT URL for uploading an identity document. After the client uploads the bytes, call the complete endpoint. requestBody: required: true content: application/json: schema: type: object required: - fileName - fileType - fileSize - type properties: fileName: type: string description: Original filename of the document example: passport-front.pdf fileType: type: string description: 'MIME type — must match the Content-Type header used when uploading to the presigned URL. Accepted values depend on `type`: `USER_SELFIE_VIDEO` takes `video/mp4` or `video/webm`; every other type takes `application/pdf`, `image/png`, or `image/jpeg`.' example: application/pdf fileSize: type: integer minimum: 1 description: Size in bytes — must match the Content-Length used when uploading to the presigned URL example: 102400 description: type: string description: Optional free-form description of the document. Required when `type` is `OTHER`. example: Shareholder agreement type: enum: - BANK_STATEMENT_DOCUMENT - OPERATING_LICENSE_DOCUMENT - SOURCE_OF_FUNDS_DOCUMENT - BUSINESS_REGISTRATION_DOCUMENT - ADDRESS_PROOF_DOCUMENT - FRAUD_CHECK_DOCUMENT - BANK_ACCOUNT_DETAILS - OTHER - PASSPORT - DRIVER_LICENSE - NATIONAL_ID - ID_CARD - VOTER_ID_CARD - RESIDENT_CARD - VISA_DOCUMENT - USER_SELFIE - USER_SELFIE_VIDEO - TAX_CERTIFICATE type: string side: enum: - FRONT - BACK type: string title: InitiateIdentityDocumentUploadRequest description: Reserve a presigned upload slot for an identity document. `side` is required for two-sided document types (PASSPORT, DRIVER_LICENSE, NATIONAL_ID, ID_CARD, VOTER_ID_CARD, RESIDENT_CARD) and rejected for all others. description: Reserve a presigned upload slot for an identity document. `side` is required for two-sided document types (PASSPORT, DRIVER_LICENSE, NATIONAL_ID, ID_CARD, VOTER_ID_CARD, RESIDENT_CARD) and rejected for all others. parameters: - schema: type: string example: id_HYFDutVuh5oWCu266VdmC in: path name: identityId required: true description: The unique Identity ID provided upon identity registration - schema: type: string in: header name: Idempotency-Key required: false responses: '200': description: Default Response content: application/json: schema: type: object required: - uploadId - uploadUrl - expiresAt properties: uploadId: type: string description: Upload identifier. Use this as the document ID on the complete endpoint. example: doc_JITym5MfDBJ4jOqiji2hP uploadUrl: type: string description: Presigned upload URL (HTTP PUT). Upload bytes with `Content-Type` and `Content-Length` matching the initiate request before it expires. expiresAt: type: string format: date-time description: ISO-8601 timestamp after which the presigned URL is no longer valid. title: InitiateDocumentUploadResponse '400': description: Default Response content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INVALID_REQUEST - INVALID_FILE_TYPE - INVALID_FILE_SIZE - SIDE_REQUIRED - SIDE_NOT_ALLOWED - DESCRIPTION_REQUIRED description: '- `INVALID_REQUEST`: The service cannot understand the request - `INVALID_FILE_TYPE`: The provided `fileType` is not allowed for this document `type`. `USER_SELFIE_VIDEO` accepts only `video/mp4` and `video/webm`; all other types accept only `application/pdf`, `image/png`, and `image/jpeg`. - `INVALID_FILE_SIZE`: The provided `fileSize` is zero or exceeds the maximum allowed size — 25 MB for `USER_SELFIE_VIDEO`, 20 MB for every other type. - `SIDE_REQUIRED`: `side` is required when `type` is a two-sided document (PASSPORT, DRIVER_LICENSE, NATIONAL_ID, ID_CARD, VOTER_ID_CARD, RESIDENT_CARD). - `SIDE_NOT_ALLOWED`: `side` is only valid for two-sided document types. Remove it for this document type. - `DESCRIPTION_REQUIRED`: `description` is required when `type` is `OTHER`.' message: type: string errors: type: array items: type: object properties: {} additionalProperties: true title: InitiateIdentityDocumentUploadError '401': description: The access to this resource has been denied content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - UNAUTHORIZED message: type: string title: UNAUTHORIZED description: The access to this resource has been denied '403': description: The credentials are valid but the caller is not permitted to transact content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - FORBIDDEN message: type: string title: FORBIDDEN description: The credentials are valid but the caller is not permitted to transact '404': description: The resource was not found content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - NOT_FOUND message: type: string title: NOT_FOUND description: The resource was not found '409': description: A duplicate request with this idempotency key is already in progress content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - IDEMPOTENCY_IN_PROGRESS message: type: string title: IDEMPOTENCY_IN_PROGRESS description: A duplicate request with this idempotency key is already in progress '422': description: Another request with this idempotency key was made using a different body content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - IDEMPOTENCY_KEY_REUSED message: type: string title: IDEMPOTENCY_KEY_REUSED description: Another request with this idempotency key was made using a different body default: description: Catch-all error response for any unexpected internal errors content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INTERNAL message: type: string enum: - An unexpected internal error has occurred title: INTERNAL description: Catch-all error response for any unexpected internal errors operationId: postV1IdentityByIdentityIdDocuments x-operation-id-source: derived get: summary: List identity documents tags: - Identity Documents description: List all documents associated with an identity. parameters: - schema: enum: - BANK_STATEMENT_DOCUMENT - OPERATING_LICENSE_DOCUMENT - SOURCE_OF_FUNDS_DOCUMENT - BUSINESS_REGISTRATION_DOCUMENT - ADDRESS_PROOF_DOCUMENT - FRAUD_CHECK_DOCUMENT - BANK_ACCOUNT_DETAILS - OTHER - PASSPORT - DRIVER_LICENSE - NATIONAL_ID - ID_CARD - VOTER_ID_CARD - RESIDENT_CARD - VISA_DOCUMENT - USER_SELFIE - USER_SELFIE_VIDEO - TAX_CERTIFICATE type: string in: query name: type required: false - schema: type: integer minimum: 1 default: 1 in: query name: page required: false description: Result page number to return, starting from 1 - schema: type: integer minimum: 1 maximum: 100 default: 50 in: query name: pageSize required: false description: Items per page to return - schema: type: string example: id_HYFDutVuh5oWCu266VdmC in: path name: identityId required: true description: The unique Identity ID provided upon identity registration responses: '200': description: Default Response content: application/json: schema: type: object required: - items - hasNext properties: items: type: array items: type: object required: - id - type - status - fileName - createdAt - updatedAt properties: id: type: string description: The unique document ID example: doc_JITym5MfDBJ4jOqiji2hP type: enum: - BANK_STATEMENT_DOCUMENT - OPERATING_LICENSE_DOCUMENT - SOURCE_OF_FUNDS_DOCUMENT - BUSINESS_REGISTRATION_DOCUMENT - ADDRESS_PROOF_DOCUMENT - FRAUD_CHECK_DOCUMENT - BANK_ACCOUNT_DETAILS - OTHER - PASSPORT - DRIVER_LICENSE - NATIONAL_ID - ID_CARD - VOTER_ID_CARD - RESIDENT_CARD - VISA_DOCUMENT - USER_SELFIE - USER_SELFIE_VIDEO - TAX_CERTIFICATE type: string side: enum: - FRONT - BACK type: string status: enum: - ACTIVE - DELETED type: string fileName: type: string contentType: type: string description: MIME type of the stored file. Absent on documents uploaded before this field was recorded. example: image/png description: type: string downloadUrl: type: string description: Presigned download URL (valid for a short window). Returned on single-document GET. createdAt: type: string format: date-time updatedAt: type: string format: date-time title: IdentityDocument hasNext: type: boolean '400': description: The service cannot understand the request content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INVALID_REQUEST message: type: string errors: type: array items: type: object properties: {} additionalProperties: true title: INVALID_REQUEST description: The service cannot understand the request '401': description: The access to this resource has been denied content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - UNAUTHORIZED message: type: string title: UNAUTHORIZED description: The access to this resource has been denied '403': description: The credentials are valid but the caller is not permitted to transact content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - FORBIDDEN message: type: string title: FORBIDDEN description: The credentials are valid but the caller is not permitted to transact '404': description: The resource was not found content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - NOT_FOUND message: type: string title: NOT_FOUND description: The resource was not found default: description: Catch-all error response for any unexpected internal errors content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INTERNAL message: type: string enum: - An unexpected internal error has occurred title: INTERNAL description: Catch-all error response for any unexpected internal errors operationId: getV1IdentityByIdentityIdDocuments x-operation-id-source: derived /v1/identity/{identityId}/documents/{uploadId}/complete: post: summary: Complete an identity document upload tags: - Identity Documents description: Call after the client has uploaded the file bytes to the presigned `uploadUrl`. Verifies the upload landed and activates the document. parameters: - schema: type: string example: id_HYFDutVuh5oWCu266VdmC in: path name: identityId required: true description: The unique Identity ID provided upon identity registration - schema: type: string example: doc_JITym5MfDBJ4jOqiji2hP in: path name: uploadId required: true description: The upload ID returned by the initiate endpoint - schema: type: string in: header name: Idempotency-Key required: false responses: '201': description: Default Response content: application/json: schema: type: object required: - id - type - status - fileName - createdAt - updatedAt properties: id: type: string description: The unique document ID example: doc_JITym5MfDBJ4jOqiji2hP type: enum: - BANK_STATEMENT_DOCUMENT - OPERATING_LICENSE_DOCUMENT - SOURCE_OF_FUNDS_DOCUMENT - BUSINESS_REGISTRATION_DOCUMENT - ADDRESS_PROOF_DOCUMENT - FRAUD_CHECK_DOCUMENT - BANK_ACCOUNT_DETAILS - OTHER - PASSPORT - DRIVER_LICENSE - NATIONAL_ID - ID_CARD - VOTER_ID_CARD - RESIDENT_CARD - VISA_DOCUMENT - USER_SELFIE - USER_SELFIE_VIDEO - TAX_CERTIFICATE type: string side: enum: - FRONT - BACK type: string status: enum: - ACTIVE - DELETED type: string fileName: type: string contentType: type: string description: MIME type of the stored file. Absent on documents uploaded before this field was recorded. example: image/png description: type: string downloadUrl: type: string description: Presigned download URL (valid for a short window). Returned on single-document GET. createdAt: type: string format: date-time updatedAt: type: string format: date-time title: IdentityDocument '400': description: Default Response content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INVALID_REQUEST - UPLOAD_NOT_FOUND - FRONT_REQUIRED_FOR_BACK description: '- `INVALID_REQUEST`: The service cannot understand the request - `UPLOAD_NOT_FOUND`: No uploaded file was found for this upload ID. The client may not have completed the upload or the URL expired. - `FRONT_REQUIRED_FOR_BACK`: A BACK was uploaded for a two-sided document type with no FRONT of that type on file. Upload the FRONT first — a back cannot be verified on its own.' message: type: string errors: type: array items: type: object properties: {} additionalProperties: true title: CompleteIdentityDocumentUploadError '401': description: The access to this resource has been denied content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - UNAUTHORIZED message: type: string title: UNAUTHORIZED description: The access to this resource has been denied '403': description: The credentials are valid but the caller is not permitted to transact content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - FORBIDDEN message: type: string title: FORBIDDEN description: The credentials are valid but the caller is not permitted to transact '404': description: The resource was not found content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - NOT_FOUND message: type: string title: NOT_FOUND description: The resource was not found '409': description: A duplicate request with this idempotency key is already in progress content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - IDEMPOTENCY_IN_PROGRESS message: type: string title: IDEMPOTENCY_IN_PROGRESS description: A duplicate request with this idempotency key is already in progress '422': description: Another request with this idempotency key was made using a different body content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - IDEMPOTENCY_KEY_REUSED message: type: string title: IDEMPOTENCY_KEY_REUSED description: Another request with this idempotency key was made using a different body default: description: Catch-all error response for any unexpected internal errors content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INTERNAL message: type: string enum: - An unexpected internal error has occurred title: INTERNAL description: Catch-all error response for any unexpected internal errors operationId: postV1IdentityByIdentityIdDocumentsByUploadIdComplete x-operation-id-source: derived /v1/identity/{identityId}/documents/{documentId}: get: summary: Get an identity document tags: - Identity Documents description: Fetch a single document. The response includes a short-lived presigned `downloadUrl`. parameters: - schema: type: string example: id_HYFDutVuh5oWCu266VdmC in: path name: identityId required: true description: The unique Identity ID provided upon identity registration - schema: type: string example: doc_JITym5MfDBJ4jOqiji2hP in: path name: documentId required: true description: The unique document ID responses: '200': description: Default Response content: application/json: schema: type: object required: - id - type - status - fileName - createdAt - updatedAt properties: id: type: string description: The unique document ID example: doc_JITym5MfDBJ4jOqiji2hP type: enum: - BANK_STATEMENT_DOCUMENT - OPERATING_LICENSE_DOCUMENT - SOURCE_OF_FUNDS_DOCUMENT - BUSINESS_REGISTRATION_DOCUMENT - ADDRESS_PROOF_DOCUMENT - FRAUD_CHECK_DOCUMENT - BANK_ACCOUNT_DETAILS - OTHER - PASSPORT - DRIVER_LICENSE - NATIONAL_ID - ID_CARD - VOTER_ID_CARD - RESIDENT_CARD - VISA_DOCUMENT - USER_SELFIE - USER_SELFIE_VIDEO - TAX_CERTIFICATE type: string side: enum: - FRONT - BACK type: string status: enum: - ACTIVE - DELETED type: string fileName: type: string contentType: type: string description: MIME type of the stored file. Absent on documents uploaded before this field was recorded. example: image/png description: type: string downloadUrl: type: string description: Presigned download URL (valid for a short window). Returned on single-document GET. createdAt: type: string format: date-time updatedAt: type: string format: date-time title: IdentityDocument '400': description: The service cannot understand the request content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INVALID_REQUEST message: type: string errors: type: array items: type: object properties: {} additionalProperties: true title: INVALID_REQUEST description: The service cannot understand the request '401': description: The access to this resource has been denied content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - UNAUTHORIZED message: type: string title: UNAUTHORIZED description: The access to this resource has been denied '403': description: The credentials are valid but the caller is not permitted to transact content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - FORBIDDEN message: type: string title: FORBIDDEN description: The credentials are valid but the caller is not permitted to transact '404': description: The resource was not found content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - NOT_FOUND message: type: string title: NOT_FOUND description: The resource was not found default: description: Catch-all error response for any unexpected internal errors content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INTERNAL message: type: string enum: - An unexpected internal error has occurred title: INTERNAL description: Catch-all error response for any unexpected internal errors operationId: getV1IdentityByIdentityIdDocumentsByDocumentId x-operation-id-source: derived delete: summary: Delete an identity document tags: - Identity Documents description: Soft-delete a document and remove its stored file. parameters: - schema: type: string example: id_HYFDutVuh5oWCu266VdmC in: path name: identityId required: true description: The unique Identity ID provided upon identity registration - schema: type: string example: doc_JITym5MfDBJ4jOqiji2hP in: path name: documentId required: true description: The unique document ID responses: '200': description: Default Response content: application/json: schema: type: object required: - message properties: message: type: string description: Status message example: OK '400': description: The service cannot understand the request content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INVALID_REQUEST message: type: string errors: type: array items: type: object properties: {} additionalProperties: true title: INVALID_REQUEST description: The service cannot understand the request '401': description: The access to this resource has been denied content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - UNAUTHORIZED message: type: string title: UNAUTHORIZED description: The access to this resource has been denied '403': description: The credentials are valid but the caller is not permitted to transact content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - FORBIDDEN message: type: string title: FORBIDDEN description: The credentials are valid but the caller is not permitted to transact '404': description: The resource was not found content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - NOT_FOUND message: type: string title: NOT_FOUND description: The resource was not found default: description: Catch-all error response for any unexpected internal errors content: application/json: schema: type: object required: - code - message properties: code: type: string enum: - INTERNAL message: type: string enum: - An unexpected internal error has occurred title: INTERNAL description: Catch-all error response for any unexpected internal errors operationId: deleteV1IdentityByIdentityIdDocumentsByDocumentId x-operation-id-source: derived components: securitySchemes: ApiKeyAuth: name: x-api-key type: apiKey in: header ApiSecretAuth: name: x-api-secret type: apiKey in: header externalDocs: description: Find out more about CFX url: https://www.cfxlabs.com/