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

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

post

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

Body

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

post

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

Body

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

post

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

get

HTTPcURLJavaScriptPython

GET /kns/transaction_details HTTP/1.1
Host: kns-api.karrier.one
Accept: */*

{
  "title": "text",
  "message": "text",
  "objectId": "0xa8c5cda072275d83ea87c6ee357edb344fa243aab071d552bdc4a7d69f741d82",
  "successRedirectUrl": "text",
  "cancelRedirectUrl": "text",
  "approvalNumber": "text",
  "createdAt": "2025-04-28T10:18:12.180Z",
  "approved": true,
  "method": "text",
  "phoneNumber": "[phone]",
  "wallet": "text",
  "vendorBrand": "text"
}

✍️ Verify Signature

post

Body

signaturestringRequired

approvalNumberstringRequired

Responses

post

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

digeststringRequired

approvalNumberstringRequired

Responses

post

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 [e-mail].

🔗 Reference

42KB

kns-api-swagger.json

Karrier Number System OpenAPI Specification