ID Proofingv2.0.0pilot-root.1kosmos.net/idproofingapiOpenAPI
1Kosmos · Identity Proofing

ID Proofing API

Orchestrate end-to-end identity-proofing sessions from reusable templates.

Authentication → All products

ID Proofing orchestrates end-to-end identity-proofing sessions. Spin up a session from a reusable template, route it through the right verification connectors, and collect the result — the way you compose document, biometric and data checks into a single proofing flow.

33 endpoints

across 12 resource groups.

ECDSA-signed

every request is signed with your key pair.

JSON over HTTPS

predictable REST, conventional status codes.

OpenAPI 3.0

Download the spec →

Reference

Base URL

All ID Proofing endpoints are relative to your environment host. Examples on this page use the 1Kosmos pilot environment — swap in your production root when you go live.

Pilot https://pilot-root.1kosmos.net/idproofingapi

Content type

Requests and responses use application/json.

GEThttps://pilot-root.1kosmos.net/idproofingapi/healthz
curl -X GET 'https://pilot-root.1kosmos.net/idproofingapi/healthz' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'
Security

Authentication

ID Proofing uses ECDSA key-pair authentication. Each request carries your credentials as HTTP headers; verification-grade calls additionally sign the request body. Retrieve the system signing key from /publickeys.

Credentials
keyIdECDSA Public Keyheader
keySecretECDSA Private Keyheader
licenseLicense key from License Microserviceheader
GEThttps://pilot-root.1kosmos.net/idproofingapi/healthz
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/idproofingapi/healthz' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'
Reference

Errors

ID Proofing uses conventional HTTP status codes: 2xx success, 4xx a problem with the request, 5xx a service-side error.

StatusMeaningDescription
200 / 204OKThe request succeeded.
400Bad RequestValidation failed.
401UnauthorizedMissing or invalid credentials.
403ForbiddenAuthenticated, but not permitted.
404Not FoundThe resource does not exist.
500Server ErrorSomething went wrong on our side.
4XXerror response
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation error"
}
ID Proofing

Proofing Session

Create and drive identity-proofing sessions.

GET/proofingsession/{sessionId}

Get proofing session details

Retrieves proofing session data including configuration settings for document capture. Returns session status, user information, workflow details, and capture configuration.

Headers Required:

  • requestid: ECDSA encrypted JSON with appid, uuid, and timestamp
  • publickey: ECDSA public key

Returns

Returns a proofing session data, which contains:

  • status: Current status of the session
  • user: User information
  • id: Session id
  • documentType: Which document is being uploaded
  • license: Capture engine license
  • workflowId: Workflow Id (nullable)
  • wfInstanceId: Workflow Instance Id (nullable)
  • useHighResolutionImages: Whether high resolution images from bucket storage are used
  • bypassConfig: Array of bypass config objects
  • autoDetectTimeout: Timeout in seconds for auto-detection
  • postTimeoutCaptureMode: Capture mode after timeout (none/manual/auto)
  • autoCaptureCountdownSeconds: Countdown seconds for auto-capture (nullable)
  • autoCaptureCountdownVisible: Whether countdown is visible to user (nullable)
  • selfieCaptureMode: Selfie capture mode (auto/manualWithFaceDetection)
Path parameters
NameTypeDescription
sessionIdrequiredstringUnique identifier for the proofing session
Headers
NameTypeDescription
requestidrequiredstringECDSA encrypted request data - use Authorize button 🔒
publickeyrequiredstringECDSA public key - use Authorize button 🔒
GEThttps://pilot-root.1kosmos.net/idproofingapi/proofingsession/{sessionId}
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/idproofingapi/proofingsession/xxxxxxxxxx' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET'
RESPONSE
200
400
500
Session details retrieved successfully
{
  "status": "INPROGRESS",
  "user": {
    "uid": "user-123",
    "username": "johndoe",
    "firstname": "John",
    "lastname": "Doe"
  },
  "id": "session-abc123",
  "documentType": "dl_object",
  "license": "license-key-xyz",
  "selfieCaptureMode": "auto",
  "workflowId": "workflow-xyz",
  "wfInstanceId": "instance-789",
  "useBucket": false,
  "bypassConfig": [],
  "autoDetectTimeout": 40,
  "postTimeoutCaptureMode": "none",
  "autoCaptureCountdownSeconds": 5,
  "autoCaptureCountdownVisible": true
}
GET/proofingsession/{sessionId}/complete

Complete proofing session

This endpoint returns proofing session status

Headers

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns a proofing session data

Path parameters
NameTypeDescription
sessionIdrequiredstringID of proofing session
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
GEThttps://pilot-root.1kosmos.net/idproofingapi/proofingsession/{sessionId}/complete
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/idproofingapi/proofingsession/xxxxxxxxxx/complete' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET'
RESPONSE
200
400
401
500
Success
{
  "completionStatus": "xxxxxxxxxx"
}
GET/proofingsession/{sessionId}/decline

Decline proofing session

This endpoint returns proofing session data

Headers

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns a proofing session data

Path parameters
NameTypeDescription
sessionIdrequiredstringID of proofing session
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
GEThttps://pilot-root.1kosmos.net/idproofingapi/proofingsession/{sessionId}/decline
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/idproofingapi/proofingsession/xxxxxxxxxx/decline' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>'
RESPONSE
200
400
401
500
Success
{
  "status": "xxxxxxxxxx",
  "user": {
    "uid": "xxxxxxxxxx",
    "username": "xxxxxxxxxx",
    "firstname": "xxxxxxxxxx",
    "lastname": "xxxxxxxxxx"
  },
  "id": "xxxxxxxxxx",
  "documentType": "dl_object"
}
GET/proofingsession/{sessionId}/retry

Retry proofing session

This endpoint is used to retry proofing session

Headers

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns 200 if retry is available. Else it will throw an error.

Path parameters
NameTypeDescription
sessionIdrequiredstringID of proofing session
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
GEThttps://pilot-root.1kosmos.net/idproofingapi/proofingsession/{sessionId}/retry
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/idproofingapi/proofingsession/xxxxxxxxxx/retry' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET'
RESPONSE
200
400
500
Success
// no response body
GET/proofingsession/{sessionId}/retry/cancel

To cancel retried proofing session

This endpoint is used to cancel the retries proofing session

Headers

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns 200 if retry is cancelled successfully. Else it will throw an error.

Path parameters
NameTypeDescription
sessionIdrequiredstringID of proofing session
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
GEThttps://pilot-root.1kosmos.net/idproofingapi/proofingsession/{sessionId}/retry/cancel
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/idproofingapi/proofingsession/xxxxxxxxxx/retry/cancel' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET'
RESPONSE
200
400
500
Success
// no response body
GET/proofingsession/{sessionId}/start

start proofing session

This endpoint returns marks the session url as used

Headers

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns a verifier url and session id

Path parameters
NameTypeDescription
sessionIdrequiredstringID of proofing session
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
GEThttps://pilot-root.1kosmos.net/idproofingapi/proofingsession/{sessionId}/start
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/idproofingapi/proofingsession/xxxxxxxxxx/start' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET'
RESPONSE
200
400
401
500
Success
{
  "data": {
    "_id": "xxxxxxxxxx",
    "id": "xxxxxxxxxx",
    "url": "xxxxxxxxxx",
    "tenantDNS": "xxxxxxxxxx",
    "tenantId": "xxxxxxxxxx",
    "communityName": "xxxxxxxxxx",
    "communityId": "xxxxxxxxxx",
    "documentType": "dl_object",
    "status": "PENDING",
    "did": "did:example:123456789abcdefghi",
    "dvcID": "dvc_123",
    "expiryTS": 1640995200000,
    "createdTS": 1640908800000,
    "startedTS": 1640912400000,
    "abandonedTS": 1640916000000,
    "resultStatus": "xxxxxxxxxx",
    "user": {
      "uid": "xxxxxxxxxx",
      "username": "xxxxxxxxxx",
      "firstname": "xxxxxxxxxx",
      "lastname": "xxxxxxxxxx"
    },
    "history": [
      {
        "activity": "STARTED",
        "ipAddress": "192.168.1.1",
        "userAgent": "Mozilla/5.0...",
        "screenName": "WELCOME",
        "ts": 1640912400000
      }
    ]
  }
}
GET/proofingsession/{sessionId}/validate

validate proofing session

This endpoint returns result from validation of the proofing session

Headers

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns a proofing session data

Path parameters
NameTypeDescription
sessionIdrequiredstringID of proofing session
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
GEThttps://pilot-root.1kosmos.net/idproofingapi/proofingsession/{sessionId}/validate
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/idproofingapi/proofingsession/xxxxxxxxxx/validate' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET'
RESPONSE
200
400
401
500
Success
{
  "status": "INPROGRESS",
  "user": {
    "uid": "user-123",
    "username": "johndoe",
    "firstname": "John",
    "lastname": "Doe"
  },
  "id": "session-abc123",
  "documentType": "dl_object",
  "license": "license-key-xyz",
  "selfieCaptureMode": "auto",
  "workflowId": "workflow-xyz",
  "wfInstanceId": "instance-789",
  "useBucket": false,
  "bypassConfig": [],
  "autoDetectTimeout": 40,
  "postTimeoutCaptureMode": "none",
  "autoCaptureCountdownSeconds": 5,
  "autoCaptureCountdownVisible": true
}
POST/presignedurls/{sessionId}

create presigned URLs

This endpoint returns presigned URLs

Headers

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns a verified certificate

Path parameters
NameTypeDescription
sessionIdrequiredstringID of proofing session
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body

Request body contains object below: for specific document attributes check individual connectors requirements/validations

{
    "imagesUrl": array required - ["document_front_image", "document_front_image_compressed", "document_front_face", "document_back_image", "document_back_image_compressed", "document_back_imageBarcode", "document_back_imageBarcode_compressed", "selfie_liveness_image"]
}
FieldTypeDescription
imagesUrlarray<string>Image URLs array ["document_front_image", "document_front_image_compressed", "document_front_face", "document_back_image", "document_back_image_compressed", "document_back_imageBarcode", "document_back_imageBarcode_compressed", "selfie_liveness_image"]
POSThttps://pilot-root.1kosmos.net/idproofingapi/presignedurls/{sessionId}
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/idproofingapi/presignedurls/xxxxxxxxxx' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'Content-Type: application/json' \
  -d '{"imagesUrl": ["string"]}'
RESPONSE
200
400
401
403
404
500
Success
{
  "document_front_image": "https://bucket/document_front_image.png",
  "document_front_image_compressed": "https://bucket/document_front_image_compressed.jpeg",
  "document_front_face": "https://bucket/document_front_face.jpeg",
  "document_back_image": "https://bucket/document_back_image.png",
  "document_back_image_compressed": "https://bucket/document_back_image_compressed.jpeg",
  "document_back_imageBarcode": "https://bucket/document_back_imageBarcode.png",
  "document_back_imageBarcode_compressed": "https://bucket/document_back_imageBarcode_compressed.jpeg"
}
POST/proofingsession/fetch

Fetch session list

Fetch session list. This endpoint also has filters.

  • Only a system or service key can be used to get sessions list.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Request Body

tenantId (required)
communityId (required)
pIndex (required)
pSize (required)
query.id (optional)

Filter by session ID

query.status (optional)

Filter by session status: PENDING | INPROGRESS | EXPIRED | ABANDONED | COMPLETED | DECLINED

query.overallRecommendation (optional)

Filter by overall outcome: COMPLETED_PASS | COMPLETED_FAILED | COMPLETED_NOT_PERFORMED | REVIEW

query.documentType (optional)

Filter by document type: dl_object | ppt_object | idcard_object

query.name (optional)

Filter by user's first or last name (partial match)

query.uid (optional)

Filter by user UID (partial match)

query.dvcID (optional)

Filter by verification config ID

query.startDate (optional)

Filter by start date (format: YYYY-MM-DD HH:mm:ss.SSS)

query.endDate (optional)

Filter by end date (format: YYYY-MM-DD HH:mm:ss.SSS)

Returns

Returns the sessions list with pagination info or errors if any.

This API throws an error if something goes wrong.

Headers
NameTypeDescription
licensekeyrequiredstringLicense key encrypted with ECDSA / Try Authorize &#128274;
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body

Request body contains below fields to fetch sessions with filters

{
   "data": {
         "query": {
             "id": "session_id (optional)",
             "status": "PENDING | INPROGRESS | EXPIRED | ABANDONED | COMPLETED | DECLINED (optional)",
             "overallRecommendation": "COMPLETED_PASS | COMPLETED_FAILED | COMPLETED_NOT_PERFORMED | REVIEW (optional)",
             "documentType": "dl_object | ppt_object | idcard_object (optional)",
             "name": "user_name (optional)",
             "uid": "user_uid (optional)",
             "dvcID": "verification_config_id (optional)",
             "startDate": "2024-12-13 00:00:00.000 (optional)",
             "endDate": "2024-12-19 23:59:59.000 (optional)"
         },
         "pIndex": 0,
         "pSize": 100,
         "tenantId": "tenant_id",
         "communityId": "community_id"
     }
}
FieldTypeDescription
dataobject—
POSThttps://pilot-root.1kosmos.net/idproofingapi/proofingsession/fetch
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/idproofingapi/proofingsession/fetch' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"query": {"id": "xxxxxxxxxx", "status": "COMPLETED_PASS | COMPLETED_FAILED | COMPLETED_NOT_PERFORMED | PENDING | EXPIRED | INPROGRESS | DECLINED | COMPLETED | ABANDONED", "documentType": "dl_object | ppt_object | idcard_object", "name": "xxxxxxxxxx", "startDate": "2024-12-19 23:59:59.000", "endDate": "2024-12-19 23:59:59.000", "dvcID": "xxxxxxxxxx", "uid": "xxxxxxxxxx"}, "pIndex": 0, "pSize": 100, "tenantId": "xxxxxxxxxx", "communityId": "xxxxxxxxxx"}}'
RESPONSE
200
400
401
500
Success - Returns session list with pagination
{
  "data": {
    "data": [
      {
        "_id": "xxxxxxxxxx",
        "id": "xxxxxxxxxx",
        "dvcID": "xxxxxxxxxx",
        "tenantDNS": "xxxxxxxxxx",
        "tenantId": "xxxxxxxxxx",
        "communityName": "xxxxxxxxxx",
        "communityId": "xxxxxxxxxx",
        "documentType": "dl_object",
        "expiryTS": "xxxxxxxxxx",
        "createdTS": "xxxxxxxxxx",
        "user": {
          "uid": "xxxxxxxxxx",
          "firstname": "xxxxxxxxxx",
          "lastname": "xxxxxxxxxx",
          "username": "xxxxxxxxxx"
        },
        "startedTS": "xxxxxxxxxx",
        "completedTS": "xxxxxxxxxx",
        "resultStatus": "xxxxxxxxxx",
        "session-result": [
          {}
        ]
      }
    ],
    "page": {
      "index": 1,
      "total": 100,
      "size": 10
    }
  }
}
POST/proofingsession/{sessionId}/submit/document

submit documents

This endpoint returns certificate

Headers

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns a verified certificate

Path parameters
NameTypeDescription
sessionIdrequiredstringID of proofing session
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
POSThttps://pilot-root.1kosmos.net/idproofingapi/proofingsession/{sessionId}/submit/document
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/idproofingapi/proofingsession/xxxxxxxxxx/submit/document' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>'
RESPONSE
200
400
401
403
500
Success
// no response body
POST/proofingsession/{sessionId}/submit/event/{eventName}

Store Event

Store one event to events.

Headers

### requestid (required) JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

### publickey (required) Public key

Returns

Response gives status OK if everything is ok

Path parameters
NameTypeDescription
sessionIdrequiredstringID of proofing session
eventNamerequiredstringevent name
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body

Request body contains *data* field with encrypted object below:

{
    "screen_name": "string required",
    "status": "string - required",
    "error": "string - required"
}
FieldTypeDescription
screen_namestring—
statusboolean—
errorstring—
POSThttps://pilot-root.1kosmos.net/idproofingapi/proofingsession/{sessionId}/submit/event/{eventName}
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/idproofingapi/proofingsession/xxxxxxxxxx/submit/event/xxxxxxxxxx' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"screen_name": "xxxxxxxx", "status": false, "error": "xxxxxxxx"}'
RESPONSE
200
400
401
500
Success
// no response body
POST/proofingsession/{sessionId}/submit/verification/{verificationName}

submit documents (selfie)

This endpoint returns certificate

Headers

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns a verified certificate

Path parameters
NameTypeDescription
sessionIdrequiredstringID of proofing session
verificationNamerequiredstring('document_liveness_front', 'document_liveness_back', 'selfie_liveness')
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body

Request body contains object below: for specific document attributes check individual connectors requirements/validations

{
    "result": "object - extraction result",
    "images": { "image": "", "cropped": "", "face": "", "imageBarcode": ""},
    "imageNames": "Image URLs array ["selfie_liveness_image"]",
    "event": {
        "screen_name": "",
        "event_name": ""
    }
}
FieldTypeDescription
resultobject—
imagesobject—
imageNamesarray<string>—
POSThttps://pilot-root.1kosmos.net/idproofingapi/proofingsession/{sessionId}/submit/verification/{verificationName}
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/idproofingapi/proofingsession/xxxxxxxxxx/submit/verification/xxxxxxxxxx' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'Content-Type: application/json' \
  -d '{"result": {}, "images": {"image": "xxxxxxxxxx", "cropped": "xxxxxxxxxx", "face": "xxxxxxxxxx", "imageBarcode": "xxxxxxxxxx"}, "imageNames": ["string"]}'
RESPONSE
200
400
401
403
500
Success
// no response body
POST/proofingsession/{sessionId}/upload/cancel

Cancel proofing session upload

This endpoint allows users to cancel an in-progress proofing session when image uploads to S3 are taking too long or the user wants to abandon the verification process.

Use Case:

  • User is uploading high-resolution images to S3 bucket
  • Upload is taking too long or user wants to exit
  • User clicks cancel/end button in the UI
  • This endpoint is called to gracefully terminate the session

Requirements:

  • Session must be in INPROGRESS state
  • useHighResolutionImages flag must be enabled in verification config
  • Valid AWS S3 bucket configuration must exist

Actions Performed:

  • Marks session as COMPLETED with NOT_PERFORMED result status
  • Generates session summary certificate with error code IDV0016 ("Session ended without image upload")
  • Handles PII retention based on configuration (sets expiry or deletes data)
  • Asynchronously deletes any uploaded images from S3 bucket

Headers

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns the session status (COMPLETED)

Path parameters
NameTypeDescription
sessionIdrequiredstringID of proofing session
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body

Request body contains screenName field (optional)

FieldTypeDescription
screenNamestringScreen name from which the cancel request is made (optional). Helps track where in the UI the user canceled the upload.
POSThttps://pilot-root.1kosmos.net/idproofingapi/proofingsession/{sessionId}/upload/cancel
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/idproofingapi/proofingsession/xxxxxxxxxx/upload/cancel' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'Content-Type: application/json' \
  -d '{"screenName": "Document Upload"}'
RESPONSE
200
400
401
404
405
500
501
Upload successfully canceled, session marked as completed
{
  "data": {
    "status": "COMPLETED"
  }
}
POST/proofingsession/{sessionId}/v2/submit/document

submit documents (images as base64) [NOT IN-USE]

This endpoint returns certificate

Headers

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns a verified certificate

Path parameters
NameTypeDescription
sessionIdrequiredstringID of proofing session
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body

Request body contains object below: for specific document attributes check individual connectors requirements/validations

{
    "document_front": {
       "result": "object - extraction result",
       "images": "array required - ['images', 'cropped', 'face', 'imageBarcode']
    },
    "document_back": {
       "result": "object - extraction result",
       "images": "array required - ['images', 'cropped', 'face', 'imageBarcode']
    },
    "fallbackCaptureMode": "string optional - 'manual' | 'auto'"
}
FieldTypeDescription
document_frontobject—
document_backobject—
fallbackCaptureModestringFallback capture mode used during document submission One of: manual, auto
POSThttps://pilot-root.1kosmos.net/idproofingapi/proofingsession/{sessionId}/v2/submit/document
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/idproofingapi/proofingsession/xxxxxxxxxx/v2/submit/document' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'Content-Type: application/json' \
  -d '{"document_front": {"result": {}, "images": {"image": "xxxxxxxxxx", "cropped": "xxxxxxxxxx", "face": "xxxxxxxxxx", "imageBarcode": "xxxxxxxxxx"}}, "document_back": {"result": {}, "images": {"image": "xxxxxxxxxx", "cropped": "xxxxxxxxxx", "face": "xxxxxxxxxx", "imageBarcode": "xxxxxxxxxx"}}, "fallbackCaptureMode": "manual"}'
RESPONSE
200
400
401
403
500
Success
// no response body
POST/proofingsession/{sessionId}/v3/submit/document

submit documents (images as AWS S3 / GCP Bucket urls)

This endpoint returns certificate

Headers

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns a verified certificate

Path parameters
NameTypeDescription
sessionIdrequiredstringID of proofing session
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body

Request body contains object below: for specific document attributes check individual connectors requirements/validations

{
    "document_front": {
       "result": "object - extraction result",
       "imageNames": "Image URLs array ["document_front_image", "document_front_face"]"
    },
    "document_back": {
       "result": "object - extraction result",
       "imageNames": "Image URLs array ["document_back_image", "document_back_imageBarcode"]"

    },
    "fallbackCaptureMode": "string optional - 'manual' | 'auto'"
}
FieldTypeDescription
document_frontobject—
document_backobject—
fallbackCaptureModestringFallback capture mode used during document submission One of: manual, auto
POSThttps://pilot-root.1kosmos.net/idproofingapi/proofingsession/{sessionId}/v3/submit/document
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/idproofingapi/proofingsession/xxxxxxxxxx/v3/submit/document' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'Content-Type: application/json' \
  -d '{"document_front": {"result": {}, "imageNames": ["string"]}, "document_back": {"result": {}, "imageNames": ["string"]}, "fallbackCaptureMode": "manual"}'
RESPONSE
200
400
401
403
500
Success
// no response body
ID Proofing

Proofing Template

Reusable proofing-flow templates.

GET/proofingtemplates/{sessionId}

Fetch workflow proofing templates

This endpoint returns available proofing templates for tenant and community by dvcID and documentType

Returns

Returns a list of proofing templates

Path parameters
NameTypeDescription
sessionIdrequiredstringID of proofing session
GEThttps://pilot-root.1kosmos.net/idproofingapi/proofingtemplates/{sessionId}
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/idproofingapi/proofingtemplates/xxxxxxxxxx' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'
RESPONSE
200
400
401
500
Success
{
  "list": [
    {
      "_id": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "tenantId": "xxxxxxxxxxx",
      "communityId": "xxxxxxxxxxx",
      "documentType": "dl_object | ppt_object | idcard_object",
      "workflow": [
        {
          "name": "xxxxxx",
          "html": "html base64",
          "type": "HTML | CAPTURE_FRONT | CAPTURE_BACK | CAPTURE_SELFIE | PROCESSING",
          "actions": [
            {
              "name": null,
              "on": null,
              "call": null,
              "jumpTo": null,
              "script": null
            }
          ],
          "params": [
            {
              "name": null,
              "field": null
            }
          ]
        }
      ]
    }
  ]
}
PUT/proofingtemplates/tenant/{tenantId}/community/{communityId}

Create proofing template

Create proofing template.

Headers

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns the created proofing template and errors if any.

This API throw an error if something goes wrong.

Path parameters
NameTypeDescription
tenantIdrequiredstringID of tenant
communityIdrequiredstringID of community
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body

General Request body contains below fields to create proofing template.

{
    "documentType": "string required eg 'dl_object | ppt_object | idcard_object'",
    "dvcID": "string required",
    "workflow": [{
       "name": "string required",
       "type": "string required - HTML | CAPTURE_FRONT | CAPTURE_BACK | CAPTURE_SELFIE | PROCESSING"
       "html": "base64 of html required"
       "params": [{
         "name": "string",
         "field": "string"
       }]
       "actions": [{
         "name": "string",
         "on": "string",
         "jumpTo": "string",
         "call": "string"
       }]
    }]
}
FieldTypeDescription
documentTypestring—
dvcIDstring—
workflowarray<object>—
PUThttps://pilot-root.1kosmos.net/idproofingapi/proofingtemplates/tenant/{tenantId}/community/{communityId}
cURL
Node.js
Python
curl -X PUT 'https://pilot-root.1kosmos.net/idproofingapi/proofingtemplates/tenant/xxxxxxxxxx/community/xxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"documentType": "dl_object | ppt_object | idcard_object", "dvcID": "xxxxx", "workflow": {"name": "xxxx", "type": "xxxx", "html": "base64", "params": {"name": "xxxx", "field": "xxxx"}, "actions": {"name": "xxxx", "on": "xxxx", "jumpTo": "xxxx", "call": "xxxx"}}}'
RESPONSE
200
400
401
403
500
Success
{
  "_id": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "tenantId": "xxxxxxxxxxx",
  "communityId": "xxxxxxxxxxx",
  "documentType": "dl_object | ppt_object | idcard_object",
  "workflow": [
    {
      "name": "xxxxxx",
      "html": "html base64",
      "type": "HTML | CAPTURE_FRONT | CAPTURE_BACK | CAPTURE_SELFIE | PROCESSING",
      "actions": [
        {
          "name": "xxxxxxxx",
          "on": "xxxxxxx",
          "call": "xxxxxxxx",
          "jumpTo": "xxxxxxxx",
          "script": "xxxxxxxx"
        }
      ],
      "params": [
        {
          "name": "xxxxxxxx",
          "field": "xxxxxxxx"
        }
      ]
    }
  ]
}
PATCH/proofingtemplates/tenant/{tenantId}/community/{communityId}/dvcId/{dvcId}

Update proofing template by dvcID

Update proofing template by dvcID.

  • Only a system, service or service_ext license key can be used.
  • Request body must be encrypted with ECDSA.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns the updated proofing template and errors if any.

This API throws an error if something goes wrong.

Path parameters
NameTypeDescription
tenantIdrequiredstringID of tenant
communityIdrequiredstringID of community
dvcIdrequiredstringDevice verification configuration ID
Headers
NameTypeDescription
licensekeyrequiredstringLicense key encrypted with ECDSA / Try Authorize &#128274;
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body

Request body contains *data* field with encrypted object below:

{
   "data": {
       "documentType": "dl_object",
       "workflow": [
         {
           "name": "string required",
           "type": "string required - HTML",
           "html": "base64 of html required",
           "params": [
             {
               "name": "string",
               "field": "string"
             }
           ],
           "actions": [
             {
               "name": "string",
               "on": "string",
               "jumpTo": "string",
               "call": "string"
             }
           ]
         }
       ]
   }
}
FieldTypeDescription
datarequiredobject—
PATCHhttps://pilot-root.1kosmos.net/idproofingapi/proofingtemplates/tenant/{tenantId}/community/{communityId}/dvcId/{dvcId}
cURL
Node.js
Python
curl -X PATCH 'https://pilot-root.1kosmos.net/idproofingapi/proofingtemplates/tenant/xxxxxxxxxx/community/xxxxxxxxxxxxxxxxxxxxxxxx/dvcId/xxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"documentType": "dl_object", "workflow": [{"name": "step1", "type": "HTML", "html": "<div>hello</div>", "params": [{"name": "param1", "field": "field1"}], "actions": [{"name": "action1", "on": "click", "jumpTo": "step2", "call": "submit"}]}]}}'
RESPONSE
200
400
401
403
404
500
Success
{
  "_id": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "tenantId": "xxxxxxxxxxx",
  "communityId": "xxxxxxxxxxx",
  "documentType": "dl_object | ppt_object | idcard_object",
  "workflow": [
    {
      "name": "xxxxxx",
      "html": "html base64",
      "type": "HTML | CAPTURE_FRONT | CAPTURE_BACK | CAPTURE_SELFIE | PROCESSING",
      "actions": [
        {
          "name": "xxxxxxxx",
          "on": "xxxxxxx",
          "call": "xxxxxxxx",
          "jumpTo": "xxxxxxxx",
          "script": "xxxxxxxx"
        }
      ],
      "params": [
        {
          "name": "xxxxxxxx",
          "field": "xxxxxxxx"
        }
      ]
    }
  ]
}
PATCH/proofingtemplates/tenant/{tenantId}/community/{communityId}/id/{id}

update proofing template

update proofing template.

Headers

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns the updated proofing template and errors if any.

This API throw an error if something goes wrong.

Path parameters
NameTypeDescription
tenantIdrequiredstringID of tenant
communityIdrequiredstringID of community
idrequiredstringID of proofing template
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body

General Request body contains below fields to update proofing template.

{
    "workflow": [{
       "name": "string required",
       "type": "string required - HTML"
       "html": "base64 of html required"
       "params": [{
         "name": "string",
         "field": "string"
       }]
       "actions": [{
         "name": "string",
         "on": "string",
         "jumpTo": "string",
         "call": "string"
       }]
}
FieldTypeDescription
workflowarray<object>—
PATCHhttps://pilot-root.1kosmos.net/idproofingapi/proofingtemplates/tenant/{tenantId}/community/{communityId}/id/{id}
cURL
Node.js
Python
curl -X PATCH 'https://pilot-root.1kosmos.net/idproofingapi/proofingtemplates/tenant/xxxxxxxxxx/community/xxxxxxxxxxxxxxxxxxxxxxxx/id/xxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{"workflow": {"name": "string", "type": "xxxx", "html": "base64", "params": {"name": "xxxx", "field": "xxxx"}, "actions": {"name": "xxxx", "on": "xxxx", "jumpTo": "xxxx", "call": "xxxx"}}}'
RESPONSE
200
400
401
403
404
500
Success
{
  "_id": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "tenantId": "xxxxxxxxxxx",
  "communityId": "xxxxxxxxxxx",
  "documentType": "dl_object | ppt_object | idcard_object",
  "workflow": [
    {
      "name": "xxxxxx",
      "html": "html base64",
      "type": "HTML | CAPTURE_FRONT | CAPTURE_BACK | CAPTURE_SELFIE | PROCESSING",
      "actions": [
        {
          "name": "xxxxxxxx",
          "on": "xxxxxxx",
          "call": "xxxxxxxx",
          "jumpTo": "xxxxxxxx",
          "script": "xxxxxxxx"
        }
      ],
      "params": [
        {
          "name": "xxxxxxxx",
          "field": "xxxxxxxx"
        }
      ]
    }
  ]
}
DELETE/proofingtemplates/tenant/{tenantId}/community/{communityId}/id/{id}

Delete proofing template

Delete proofing template.

Headers

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns the fetched proofing templates and errors if any.

This API throw an error if something goes wrong.

Path parameters
NameTypeDescription
idrequiredstringID of Proofing Template
tenantIdrequiredstringID of tenant
communityIdrequiredstringID of community
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
DELETEhttps://pilot-root.1kosmos.net/idproofingapi/proofingtemplates/tenant/{tenantId}/community/{communityId}/id/{id}
cURL
Node.js
Python
curl -X DELETE 'https://pilot-root.1kosmos.net/idproofingapi/proofingtemplates/tenant/xxxxxxxxxx/community/xxxxxxxxxxxxxxxxxxxxxxxx/id/xxxxxxxxxx' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET'
RESPONSE
204
400
401
403
404
500
No Content
// no response body
ID Proofing

Buckets

Buckets endpoints.

GET/bucket/tenant/{tenantId}/community/{communityId}

get bucket at community level

get bucket at community level.

  • Only a system or service key can be used to get document certificate.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns the bucket details or errors if any.

This API throw an error if something goes wrong.

Path parameters
NameTypeDescription
tenantIdrequiredstringID of tenant
communityIdrequiredstringID of community
Headers
NameTypeDescription
licensekeyrequiredstringLicense key encrypted with ECDSA / Try Authorize &#128274;
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
GEThttps://pilot-root.1kosmos.net/idproofingapi/bucket/tenant/{tenantId}/community/{communityId}
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/idproofingapi/bucket/tenant/xxxxxxxxxx/community/xxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'
RESPONSE
200
400
401
403
500
Success
{
  "data": {
    "_id": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "tenantId": "xxxxxxxxxxx",
    "communityId": "xxxxxxxxxxx",
    "type": "aws | gcp | azure",
    "bucketName": "xxxxxxxx",
    "isEnabled": false,
    "createdBy": "xxxxxxxx",
    "createdTS": "xxxxxxxx",
    "updatedTS": "xxxxxxxx",
    "aws_credential": {
      "accessKey": "xxxxxxxx",
      "secretKey": "xxxxxxxx",
      "region": "xxxxxxxx"
    },
    "gcp_credential": {
      "projectid": "xxxxxxxx",
      "clientEmail": "xxxxxxxx",
      "privateKey": "xxxxxxxx"
    },
    "azure_credential": {
      "accountName": "string",
      "accountKey": "string"
    }
  }
}
PUT/bucket/tenant/{tenantId}/community/{communityId}

Create bucket at community level

Create bucket at community level.

  • Only a system or service key can be used to get document certificate.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Request Body

type (required)

Type value can be aws, gcp and azure.

bucketName (required)

The bucketName string.

isEnabled (required)

The isEnabled boolean.

createdBy (required)

The createdBy boolean.

aws_credential (optional)

The aws_credential object.

gcp_credential (optional)

The gcp_credential object.

azure_credential (optional)

The azure_credential object.

Returns

Returns the buckets details or errors if any.

This API throw an error if something goes wrong.

Path parameters
NameTypeDescription
tenantIdrequiredstringID of tenant
communityIdrequiredstringID of community
Headers
NameTypeDescription
licensekeyrequiredstringLicense key encrypted with ECDSA / Try Authorize &#128274;
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body

Request body contains below fields to create bucket for aws, gcp or azure

{
  "type": "string required",
  "bucketName": "string required",
  "isEnabled": "boolean required - default false",
  "createdBy": "string required",
  "aws_credential": {
    "accessKey": "string required",
    "secretKey": "string required",
    "region": "string required"
  } // optional,
  "gcp_credential": {
    "projectid": "string required",
    "clientEmail": "string required",
    "privateKey": "string required"
  } // optional,
  "azure_credential": {
    "accountName": "string required",
    "accountKey": "string required"
  } // optional
}
FieldTypeDescription
dataobject—
PUThttps://pilot-root.1kosmos.net/idproofingapi/bucket/tenant/{tenantId}/community/{communityId}
cURL
Node.js
Python
curl -X PUT 'https://pilot-root.1kosmos.net/idproofingapi/bucket/tenant/xxxxxxxxxx/community/xxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"data": {"type": "aws | gcp | azure", "bucketName": "xxxxxxxx", "isEnabled": false, "createdBy": "xxxxxxxx", "aws_credential": {"accessKey": "xxxxxxxx", "secretKey": "xxxxxxxx", "region": "xxxxxxxx"}, "gcp_credential": {"projectid": "xxxxxxxx", "clientEmail": "xxxxxxxx", "privateKey": "xxxxxxxx"}, "azure_credential": {"accountName": "xxxxxxxx", "accountKey": "xxxxxxxx"}}}'
RESPONSE
200
400
401
403
500
Success
{
  "data": {
    "_id": "xxxxxxxxxxxxxxxxxxxxxxxx",
    "tenantId": "xxxxxxxxxxx",
    "communityId": "xxxxxxxxxxx",
    "type": "aws | gcp | azure",
    "bucketName": "xxxxxxxx",
    "isEnabled": false,
    "createdBy": "xxxxxxxx",
    "createdTS": "xxxxxxxx",
    "updatedTS": "xxxxxxxx",
    "aws_credential": {
      "accessKey": "xxxxxxxx",
      "secretKey": "xxxxxxxx",
      "region": "xxxxxxxx"
    },
    "gcp_credential": {
      "projectid": "xxxxxxxx",
      "clientEmail": "xxxxxxxx",
      "privateKey": "xxxxxxxx"
    },
    "azure_credential": {
      "accountName": "string",
      "accountKey": "string"
    }
  }
}
ID Proofing

Service Key

Service Key endpoints.

GET/servicekeys

Get service keys

This endpoint returns available service keys. The license you are using must be of authLevel 'system'

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns array with service keys

Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
licensekeyrequiredstringLicense key encrypted with ECDSA / Try Authorize &#128274;
GEThttps://pilot-root.1kosmos.net/idproofingapi/servicekeys
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/idproofingapi/servicekeys' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'
RESPONSE
200
400
401
500
Success
[
  {
    "tag": "xxxxx",
    "keyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "keySecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "type": "xxxxx"
  }
]
DELETE/servicekey/{keyId}

Reset Service Key

This endpoint resets service key for given keyId. Deletes current one and recreates a new one. The license you are using must be of authLevel 'system'

Parameters

keyId (required)

The keyId of service key to reset

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Returns

Returns re-created service key

Path parameters
NameTypeDescription
keyIdrequiredstringkeyId of service key to reset
Headers
NameTypeDescription
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
licensekeyrequiredstringLicense key encrypted with ECDSA / Try Authorize &#128274;
DELETEhttps://pilot-root.1kosmos.net/idproofingapi/servicekey/{keyId}
cURL
Node.js
Python
curl -X DELETE 'https://pilot-root.1kosmos.net/idproofingapi/servicekey/<keyId>' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'
RESPONSE
200
400
401
500
Success
[
  {
    "tag": "xxxxx",
    "keyId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "keySecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxx",
    "type": "xxxxx"
  }
]
ID Proofing

Session

Session endpoints.

POST/document_share_session/create

Create scan session for DL | PPT | IDCARD

Create scan session for DL | PPT | IDCARD.

  • Only a system or service key can be used to get document certificate.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Request Body

connector (required)

The connector object.

verification (required)

The verification object.

sessionRequest (required)

The sessionRequest object.

Returns

Returns the sessionId, url and errors if any.

This API throw an error if something goes wrong.

Headers
NameTypeDescription
licensekeyrequiredstringLicense key encrypted with ECDSA / Try Authorize &#128274;
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body

Request body contains below fields to get dl_authenticate | ppt_authenticate | idcard_authenticate connector certificate.

{
  "connector": {
    "id": "string required",
    "type": "string required",
    "config": {
      "license": "string required",
      "clientId": "string",
      "clientSecret": "string",
      "verifierUrl": "string required",
      "document_share_session_enabled": "boolean required",
      "dl": {},
      "idcard": {},
      "ppt": {},
    }
  },
  "verification": {
    "id": "string required",
    "tag": "string required",
    "config": {
      "verifier": "string required",
      "debug": "boolean required",
      "skip": "boolean required",
      "returnRawData": "boolean",
      "fraudDetectFailureBypass": "boolean",
      "expireSessionInMin": "number optional",
      "abandonSessionInMin": "number optional",
      "maxRetries": "number optional",
      "checks": [
        "document_liveness_front",
        "document_liveness_back",
        "selfie_liveness",
        "face_compare",
        "fraud_detection"
      ]
    }
  },
  "sessionRequest": {
    "tenantDNS": "string required",
    "communityName": "string required",
    "documentType": "string required",
    "did": "string optional",
    "user": {
      "uid": "string optional",
      "username": "string optional",
      "firstname": "string optional",
      "lastname": "string optional",
    },
    "tenantId": "string required",
    "communityId": "string required",
    "workflowMetadata": {
      "wfInstanceId": "string optional",
      "workflowId": "string optional",
      // ...any additional metadata fields
    }
  }
}
FieldTypeDescription
connectorobject—
verificationobject—
sessionRequestobject—
POSThttps://pilot-root.1kosmos.net/idproofingapi/document_share_session/create
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/idproofingapi/document_share_session/create' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"connector": {"id": "xxxxxxxxxxxxxxxxxxxxxxxx", "type": "xxxxxx", "config": {}}, "verification": {"id": "xxxxxxxxxxxxxxxxxxxxxxxx", "tag": "xxxxxx", "type": "xxxxxx", "config": {}}, "sessionRequest": {"tenantDNS": "idpass.1kosmos.net", "communityName": "default", "documentType": "dl_object", "userUID": "xxxxxx", "did": "xxxxxxx", "workflowMetadata": {"wfInstanceId": "xxxxxx", "workflowId": "xxxxxx"}}}'
RESPONSE
200
400
401
403
500
Success
{
  "sessionId": "xxxxx",
  "url": "xxxxxxxxxxxxxxxxxxxxxxxx"
}
POST/document_share_session/result

Check Session Status

Check Session Status

  • Only a system or service key can be used to get document certificate.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Request Body

connector (required)

The connector object.

verification (required)

The verification object.

sessionId (required)

The sessionId string.

Returns

Returns the status of session and errors if any.

This API throw an error if something goes wrong.

Headers
NameTypeDescription
licensekeyrequiredstringLicense key encrypted with ECDSA / Try Authorize &#128274;
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body

Request body contains below fields to get dl_authenticate | ppt_authenticate | idcard_authenticate connector certificate.

{
    "connector": {
        "id": "string required",
        "type": "string required - 'authenticid'",
        "config": {
            "airAccessKey": "string required",
            "airSecretToken": "string required",
            "airAPI": "string required",
            "faceAPI": "string required",
            "faceAPIKey": "string required",
            "documentLivenessCheckAPI": "string optional",
            "document_share_session_enabled": "string for scan-sessions",
            "accountCode": "string for scan-sessions",
            "cfweb_url": "string for scan-sessions",
            "cfweb_cert": "string for scan-sessions",
            "cfweb_key": "string for scan-sessions",
            "cfweb_channelConfiguration": {
              "enableSelfieCapture": boolean for scan-sessions,
              "enableFarSelfie": boolean for scan-sessions,
              "requestExpiryTimeInMin": number for scan-sessions,
              "reviewScreenFront": boolean for scan-sessions,
              "reviewScreenBack": boolean for scan-sessions,
              "frontCaptureMode": "string for scan-sessions",
              "backCaptureMode": "string for scan-sessions",
              "transactionExpiryTimeInMin": number for scan-sessions,
              "frontCaptureAttempt": "number for scan-sessions",
              "backCaptureAttempt": "number for scan-sessions",
              "selfieCaptureAttempt": "number for scan-sessions",
              "transactionAttempts": "number for scan-sessions",
              "frontSetManualTimeout": number for scan-sessions,
              "backSetManualTimeout": number for scan-sessions
            },
            "cfweb_channelResponse": [ //  for scan-sessions
              "DQL_Classification_DocumentClassName",
              "DQL_Classification_DocumentName",
              "DQL_Final_DocumentNumber_Result",
              "DQL_Final_ExpirationDate_Result",
              "DQL_Final_IssueDate_Result",
              "DQL_Final_BirthDate_Result",
              "DQL_Final_FirstName_Result",
              "DQL_Final_Surname_Result",
              "DQL_Final_MiddleName_Result",
              "DQL_Final_GivenName_Result",
              "DQL_Final_FullName_Result",
              "ImageFront",
              "ImageBack",
              "ImageHeadshot",
              "ImageSelfie",
              "ImageLiveness",
              "DQL_Final_Sex_Result",
              "DQL_Final_EyeColor_Result",
              "DQL_Final_AddressLine1_Result",
              "DQL_Final_AddressCity_Result",
              "DQL_Final_AddressState_Result",
              "DQL_Classification_DocumentIssuerCountryCode",
              "DQL_Final_AddressPostalCode_Result",
              "ControlNumber",
              "BirthPlace"
            ]
        }
    },
    "verification": {
        "id": "string required",
        "tag": "string required -  custom tag",
        "type": "string required - 'dl_authenticate | ppt_authenticate | idcard_authenticate'",
        "config": {
            "verifier": "string required - custom tag from verifier",
            "skip": false,                          // boolean
            "debug": false,                         // boolean
            "action_code": 99,                      // number required
            "document_type": "11"                   // string optional 00 - License/Idcard, 01- License/Passport, 11 - Passport - default will be 00
        }
    },
    "sessionId": "string required",
    "includeMetadata": "boolean optional",
    "apiVersion": "string optional",
    "alwaysReturnAssets": "boolean optional - when enabled, returns assets (images) regardless of session outcome",
    "granularStatus": "boolean optional - when true, returns the actual session status (PENDING vs INPROGRESS) without legacy masking"
}
FieldTypeDescription
connectorobject—
verificationobject—
sessionIdstring—
includeMetadataboolean—
apiVersionstring—
alwaysReturnAssetsboolean—
granularStatusbooleanWhen true, returns the actual session status (PENDING vs INPROGRESS) without legacy masking. Defaults to false.
POSThttps://pilot-root.1kosmos.net/idproofingapi/document_share_session/result
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/idproofingapi/document_share_session/result' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"connector": {"id": "xxxxxxxxxxxxxxxxxxxxxxxx", "type": "xxxxxx", "config": {}}, "verification": {"id": "xxxxxxxxxxxxxxxxxxxxxxxx", "tag": "xxxxxx", "type": "xxxxxx", "config": {}}, "sessionId": "xxxxxxx", "includeMetadata": false, "apiVersion": "v3", "alwaysReturnAssets": false, "granularStatus": false}'
RESPONSE
200
400
401
403
500
Success
{
  "responseStatus": "xxxxx",
  "sessionId": "xxxxx",
  "dl_object": {},
  "idcard_object": {},
  "ppt_object": {},
  "liveid_object": {},
  "token": "xxxxx",
  "raw_data": {},
  "publicKey": "xxxx"
}
ID Proofing

Connector

Verification connectors behind a session.

GET/info

Get connector information

This endpoint returns available connector information.

Returns

Returns array with connector information

GEThttps://pilot-root.1kosmos.net/idproofingapi/info
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/idproofingapi/info' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'
RESPONSE
200
Success
[
  {
    "verifierType": "xxxxx",
    "docType": "xxxxx"
  }
]
ID Proofing

ECDSA Helper

ECDSA Helper endpoints.

POST/ecdsa_helper/{method}

Encrypt and decrypt the data string by public key and private key.

Encrypt and decrypt the data string by public key and private key.

Parameters

method (optional)

The method parameter is type of enum. Default value is encrypt.

This parameter only accepts following values

encrypt, decrypt

Request Body

dataStr (required)

The dataStr key is type of string.

publicKey (required)

The publicKey is type of string.

privateKey (required)

The privateKey is type of string.

Returns

Returns the encrypted/decrypted string.

This API throw an error if something goes wrong. A common source of error is public or private key is not valid.

Path parameters
NameTypeDescription
methodstring—
Request body
FieldTypeDescription
dataStrstring—
publicKeystring—
privateKeystring—
POSThttps://pilot-root.1kosmos.net/idproofingapi/ecdsa_helper/{method}
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/idproofingapi/ecdsa_helper/<method>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"dataStr": "Hey, This is example data string.", "publicKey": "xxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx=", "privateKey": "xxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx="}'
RESPONSE
200
successful operation
{
  "data": "xxxxxxxxxxxxxxxxxxxx",
  "publicKey": "xxxxxxxxxxxxxxxxxxxx"
}
ID Proofing

Environment

Environment endpoints.

GET/environment

/environment

Provide details regarding the environments.

Returns

Returns an environment object

GEThttps://pilot-root.1kosmos.net/idproofingapi/environment
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/idproofingapi/environment' \
  -H 'license: YOUR_LICENSE_KEY'
RESPONSE
200
Success
// no response body
ID Proofing

Healthz

Healthz endpoints.

GET/healthz

Get healthz.

Get healthz

Returns

Returns a healthz object

  • ``version = <git-tag>.<commit-id>.<dob>``
  • ``git-tag``: When code is compiled from a git-tag, this must carry the tag name. This should match one of the git tags.
  • ``commit-id``: This is the git-commit-id. eg: When code is built from this, the hex code, in the end, is the commit it.
  • ``dob``: Date Of Build. This is epoc-time-in-se conds that tell the time when the build was created.
  • ​if the code is not built from a git-tag, then the ``version =<commit-id>.<dob>``
GEThttps://pilot-root.1kosmos.net/idproofingapi/healthz
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/idproofingapi/healthz' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'
RESPONSE
200
Success ``` { "status": "all services operational", "publicKey": "string" //same as <service>/publickeys endpoint, "code": "200", "version": "<version>" //as defined above } ```
{
  "status": "all services operational",
  "publicKey": "//same as <service>/publickeys endpoint",
  "code": "200",
  "version": "xxxx.xxxx.xxxx"
}
ID Proofing

Public Key

Public Key endpoints.

GET/publickeys

Get system's public key.

Get system's public key.

Returns

Returns a public key object

GEThttps://pilot-root.1kosmos.net/idproofingapi/publickeys
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/idproofingapi/publickeys' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'
RESPONSE
200
401
{
  "publicKey": ""
}
ID Proofing

Service Directory

Service Directory endpoints.

GET/sd

Get all service directories.

Get all service directories.

Returns

Returns all service directories.

GEThttps://pilot-root.1kosmos.net/idproofingapi/sd
cURL
Node.js
Python
curl -X GET 'https://pilot-root.1kosmos.net/idproofingapi/sd' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY'
RESPONSE
200
{
  "name1": "https://xxx.xxxxxx.xxx/xxxxx",
  "name2": "https://xxx.xxxxxx.xxx/xxxxx",
  "name3": "https://xxx.xxxxxx.xxx/xxxxx"
}
ID Proofing

Verify

Verify endpoints.

POST/verify

Verify Connector

Get Connector certificate.

  • Only a system or service key can be used to get document certificate.

Headers

licensekey (required)

License key encrypted with ECDSA

requestid (required)

JSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now

publickey (required)

Public key

Request Body

connector (required)

The connector object.

verification (required)

The verification object.

document (required)

The document object.

Returns

Returns the document certificate and errors if any.

This API throw an error if something goes wrong.

Headers
NameTypeDescription
licensekeyrequiredstringLicense key encrypted with ECDSA / Try Authorize &#128274;
requestidrequiredstringJSON string encrypted with ECDSA which should contain "appid" (string), "uuid" (string) and "ts" (number) representing epoch timestamp in seconds - it shouldn't be more or less than 'environment.allowed_time_span' seconds from now / Try Authorize &#128274;
publickeyrequiredstringPublic Key / Try Authorize &#128274;
Request body

Request body contains below fields to get dl_authenticate connector certificate.

{
    "connector": {
        "id": "string required",
        "type": "string required - 'microblink'",
        "config": {
            "verifierUrl": "string required",
            "verifierUrlV2": "string required",
            "clientId": "string",
            "clientSecret": "string"
        }
    },
    "verification": {
        "id": "string required",
        "tag": "string required",
        "type": "string required - 'dl_authenticate'",
        "config": {
            "verifier": "string required - custom tag from verifier",
            "skip": false,                                                 // boolean
            "debug": true,                                                 // boolean
            "returnRawData": false                                         // boolean
            "useV1BlinkIdVerify": false                                    // boolean
        }
    },
    "document": {
        "id": "string required",
        "type": "string required - dl",                                    // case-insensitive
        "front_image": "string optional",                                  // base64
        "back_image": "string optional",                                   // base64
        "barcode_image": "string optional",                                // base64
        "front_image_flash": "string optional",                            // base64
        "front_image_url": "string optional",                              // base64
        "back_image_url": "string optional",                               // base64
        "barcode_image_url": "string optional",                            // base64
        "front_image_flash_url": "string optional"                         // base64
    }
}

Request body contains below fields to get ppt_authenticate connector certificate.

{
    "connector": {
        "id": "string required",
        "type": "string required - 'microblink'",
        "config": {
            "verifierUrl": "string required",
            "verifierUrlV2": "string required",
            "clientId": "string",
            "clientSecret": "string"
        }
    },
    "verification": {
        "id": "string required",
        "tag": "string required",
        "type": "string required - 'ppt_authenticate'",
        "config": {
            "verifier": "string required - custom tag from verifier",
            "skip": false,                                                 // boolean
            "debug": true,                                                 // boolean
            "useV1BlinkIdVerify": false                                    // boolean
    },
    "document": {
        "id": "string required",
        "type": "string required - ppt",                                   // case-insensitive
        "front_image": "string required",                                  // base64
        "front_image_url": "string required"                               // base64
    }
}

Request body contains below fields to get idcard_authenticate connector certificate.

{
    "connector": {
        "id": "string required",
        "type": "string required - 'microblink'",
        "config": {
            "verifierUrl": "string required",
            "verifierUrlV2": "string required",
            "clientId": "string",
            "clientSecret": "string"
        }
    },
    "verification": {
        "id": "string required",
        "tag": "string required",
        "type": "string required - 'idcard_authenticate'",
        "config": {
            "verifier": "string required - custom tag from verifier",
            "skip": false,                                                 // boolean
            "debug": false,                                                // boolean
            "useV1BlinkIdVerify": false                                    // boolean
        }
    },
    "document": {
        "id": "string required",
        "type": "string required - idcard",                                // case-insensitive
        "front_image": "string optional",                                  // base64
        "back_image": "string optional",                                   // base64
        "barcode_image": "string optional",                                // base64
        "front_image_flash": "string optional",                            // base64
        "front_image_url": "string optional",                              // base64
        "back_image_url": "string optional",                               // base64
        "barcode_image_url": "string optional",                            // base64
        "front_image_flash_url": "string optional"                         // base64
    }
}

Request body contains below fields to get id_capture connector certificate.

{
    "connector": {
        "id": "string required",
        "type": "string required - 'microblink'",
        "config": {
            "url": "string required",
            "clientId": "string",
            "clientSecret": "string"
        }
    },
    "verification": {
        "id": "string required",
        "tag": "string required",
        "type": "string required - 'id_capture'",
        "config": {
            "verifier": "string required - custom tag from verifier",
            "skip": false,                                                 // boolean
            "debug": false,                                                // boolean
            "useV1BlinkIdVerify": false                                    // boolean
        }
    },
    "document": {
        "id": "string required",
        "type": "string required - idcard",                                // case-insensitive
        "front_image": "string optional",                                  // base64
        "back_image": "string optional",                                   // base64
        "barcode_image": "string optional",                                // base64
        "front_image_flash": "string optional",                            // base64
        "front_image_url": "string optional",                              // base64
        "back_image_url": "string optional",                               // base64
        "barcode_image_url": "string optional",                            // base64
        "front_image_flash_url": "string optional"                         // base64
    }
}
FieldTypeDescription
connectorobject—
verificationobject—
documentobject—
referrerPublicKeystring—
POSThttps://pilot-root.1kosmos.net/idproofingapi/verify
cURL
Node.js
Python
curl -X POST 'https://pilot-root.1kosmos.net/idproofingapi/verify' \
  -H 'licensekey: YOUR_LICENSE_KEY' \
  -H 'requestid: <ecdsa-requestid>' \
  -H 'publickey: <public-key>' \
  -H 'keyId: YOUR_KEY_ID' \
  -H 'keySecret: YOUR_KEY_SECRET' \
  -H 'license: YOUR_LICENSE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"connector": {"id": "xxxxxxxxxxxxxxxxxxxxxxxx", "type": "xxxxxx", "config": {}}, "verification": {"id": "xxxxxxxxxxxxxxxxxxxxxxxx", "tag": "xxxxxx", "type": "xxxxxx", "config": {}}, "document": {"id": "xxxxxxxxx", "type": "xxxxxx", "...": null}, "referrerPublicKey": "xxxxxxxxxxx"}'
RESPONSE
200
400
401
403
500
Success
{
  "docType": "xxxxx",
  "docId": "xxxxxxxxxxxxxxxxxxxxxxxx",
  "type": "xxxxx",
  "authority": "xxxxx",
  "ts": "xxxxxxxxxx",
  "verified": true,
  "result": {},
  "metadata": {},
  "token": "xxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxx=",
  "raw_data": {},
  "publicKey": "xxxxx",
  "proof_jwt": "xxxxxxxxxxxxxxxxxxxxxx="
}
© 2026 1Kosmos · IDProofing Service v2.0.0Generated from the OpenAPI spec · idproofingapi.json