Karrier Number System API

The Karrier Number System API provides a secure way to register users, create and manage approvals, and verify identities and transactions using zk addresses, approval references, and signatures.

How It Works

Each endpoint supports either POST or GET methods with JSON bodies or query parameters. The API handles identity registration, approval workflows (like SIM swaps), and cryptographic verification.

🧾 Register User Login

post

Body

application/json

emailstringOptional

The user's email address.

phoneNumberstring · E.164Optional

The user's phone number in E.164 format.

Example: [phone]Pattern: ^\+?[1-9]\d{5,14}$

Responses

200

Ok

application/json

400Error

application/json

post

/kns/register-user-login

HTTPcURLJavaScriptPython

POST /kns/register-user-login HTTP/1.1
Host: kns-api.karrier.one
Content-Type: application/json
Accept: */*
Content-Length: 45

{
  "email": "text",
  "phoneNumber": "[phone]"
}

{
  "success": true,
  "message": "text",
  "userId": "text",
  "identifiers": [
    {
      "type": "email",
      "identifier": "text"
    }
  ],
  "zkAddress": "text"
}

✅ Create Approval – Phone

post

Authorizations

api_key

x-api-keystringRequired

Body

application/json

titlestring · string · min: 1 · max: 255Required

The title of the approval request.

Example: SIM Replacement Approval

messagestring · stringRequired

A description of what the approval request is for.

Example: Would you like to deactivate your previous SIM card and activate a new SIM card?

successRedirectUrlstring · string · min: 1 · max: 255Required

The URL to redirect to if the user approves the request.

Example: https://example.com/approvedPattern: ^https?:\/\/.*$

cancelRedirectUrlstring · string · min: 1 · max: 255Required

The URL to redirect to if the user cancels the approval request.

Example: https://example.com/cancelPattern: ^https?:\/\/.*$

referenceNumberstring · string · min: 1 · max: 255Required

The reference number for the approval request.

Example: SIM-1234

methodstring · enumRequired

The method to use for the approval request. This can be either "sign" or "event".

Example: signPossible values:

phoneNumberstring · E.164Required

The user's phone number in E.164 format.

Example: [phone]Pattern: ^\+?[1-9]\d{5,14}$

Responses

200

Ok

application/json

400Error

application/json

post

/kns/approval-phone

HTTPcURLJavaScriptPython

POST /kns/approval-phone HTTP/1.1
Host: kns-api.karrier.one
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 304

{
  "title": "SIM Replacement Approval",
  "message": "Would you like to deactivate your previous SIM card and activate a new SIM card?",
  "successRedirectUrl": "https://example.com/approved",
  "cancelRedirectUrl": "https://example.com/cancel",
  "referenceNumber": "SIM-1234",
  "method": "sign",
  "phoneNumber": "[phone]"
}

{
  "approvalUrl": "text",
  "approvalNumber": "text",
  "error": "text"
}

🪪 Create Approval – Object ID

post

Authorizations

api_key

x-api-keystringRequired

Body

application/json

titlestring · string · min: 1 · max: 255Required

The title of the approval request.

Example: SIM Replacement Approval

messagestring · stringRequired

A description of what the approval request is for.

Example: Would you like to deactivate your previous SIM card and activate a new SIM card?

successRedirectUrlstring · string · min: 1 · max: 255Required

The URL to redirect to if the user approves the request.

Example: https://example.com/approvedPattern: ^https?:\/\/.*$

cancelRedirectUrlstring · string · min: 1 · max: 255Required

The URL to redirect to if the user cancels the approval request.

Example: https://example.com/cancelPattern: ^https?:\/\/.*$

referenceNumberstring · string · min: 1 · max: 255Required

The reference number for the approval request.

Example: SIM-1234

methodstring · enumRequired

The method to use for the approval request. This can be either "sign" or "event".

Example: signPossible values:

objectIdstring · string · min: 66 · max: 66Required

The Sui object ID of the KNS NFT.

Example: 0xa8c5cda072275d83ea87c6ee357edb344fa243aab071d552bdc4a7d69f741d82Pattern: ^0x[0-9a-fA-F]{64}$

Responses

200

Ok

application/json

400Error

application/json

post

/kns/approval-object-id

HTTPcURLJavaScriptPython

POST /kns/approval-object-id HTTP/1.1
Host: kns-api.karrier.one
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 355

{
  "title": "SIM Replacement Approval",
  "message": "Would you like to deactivate your previous SIM card and activate a new SIM card?",
  "successRedirectUrl": "https://example.com/approved",
  "cancelRedirectUrl": "https://example.com/cancel",
  "referenceNumber": "SIM-1234",
  "method": "sign",
  "objectId": "0xa8c5cda072275d83ea87c6ee357edb344fa243aab071d552bdc4a7d69f741d82"
}

{
  "approvalUrl": "text",
  "approvalNumber": "text",
  "error": "text"
}

🔍 Get Transaction Details

get

Query parameters

refstringRequired

Responses

200

Ok

application/json

404Error

application/json

get

/kns/transaction_details

HTTPcURLJavaScriptPython

GET /kns/transaction_details?ref=text HTTP/1.1
Host: kns-api.karrier.one
Accept: */*

{
  "title": "text",
  "message": "text",
  "objectId": "0xa8c5cda072275d83ea87c6ee357edb344fa243aab071d552bdc4a7d69f741d82",
  "successRedirectUrl": "text",
  "cancelRedirectUrl": "text",
  "approvalNumber": "text",
  "createdAt": "2026-01-16T01:34:03.212Z",
  "approved": true,
  "method": "text",
  "phoneNumber": "[phone]",
  "wallet": "text",
  "vendorBrand": "text"
}

✍️ Verify Signature

post

Body

application/json

signaturestringRequired

approvalNumberstringRequired

Responses

200

Ok

application/json

400Error

application/json

post

/kns/verify_signature

HTTPcURLJavaScriptPython

POST /kns/verify_signature HTTP/1.1
Host: kns-api.karrier.one
Content-Type: application/json
Accept: */*
Content-Length: 44

{
  "signature": "text",
  "approvalNumber": "text"
}

{
  "success": true,
  "error": "text"
}

🔐 Verify Transaction Digest

post

Body

application/json

digeststringRequired

approvalNumberstringRequired

Responses

200

Ok

application/json

400Error

application/json

post

/kns/verify_transaction

HTTPcURLJavaScriptPython

POST /kns/verify_transaction HTTP/1.1
Host: kns-api.karrier.one
Content-Type: application/json
Accept: */*
Content-Length: 41

{
  "digest": "text",
  "approvalNumber": "text"
}

{
  "success": true,
  "error": "text"
}

Conclusion

The Karrier Number System API enables secure and seamless identity verification, approvals, and transaction validation. For questions or support, please reach out to [email protected].

🔗 Reference

42KB

kns-api-swagger.json

Open

Karrier Number System OpenAPI Specification