Teydex Backend API Documentation

Overview

This document outlines the backend services provided by Teydex, which are consumed by both the client middleware layer (or any other desired server-side applications) and the Teydex SDK, which is embedded into client-facing mobile applications (iOS and Android).

The APIs described here enable a robust and secure Know Your Customer (KYC) workflow. The services allow for application-level authorization, per-user flow initialization, step submission from the mobile SDK, and status requesting to track verification progress and retrieve results.

The structure of this document follows the KYC sequence as illustrated in the flowchart, presenting each step in the order it's typically called. Request and response formats are detailed under each relevant section.

---

---

Table of Contents

a. App-Level Authorization
b. End-User Flow Initialization
c. SDK Entry Point Invocation
d. KYC Transaction Start
e. KYC Step Submission (Process Request)
f. Final Transaction Retrieval

---

a. App-Level Authorization

Flowchart Reference: Steps 1 to 3
Endpoint: POST /auth/token
Consumed By: Client Middleware
Purpose: Authenticates the middleware application and returns a token for secure interaction with other backend endpoints.

Request Body

{
  "username": "user@example.com",
  "password": "your-password"
}

Response Body

{
  "access": "access_token_xyz",
  "refresh": "refresh_token_xyz"
}

b. End-User Flow Initialization

Flowchart Reference: Steps 4 to 6 Endpoint: POST /flow/initialize
Consumed By: Client Middleware
Purpose: Initializes a new KYC transaction for an individual end-user. This endpoint returns a unique transaction ID and a JWT token to be used by the Teydex SDK on the client device. Application field is the UUID created for different flows that can be generated from the panel.

Request Headers

Name	Type	Required	Description
Authorization	string	✅	Bearer token (Bearer <access_token>)

Request Body

{
  "application": "b8c1118a-eaa1-4c10-a2ae-eab5d7f6f131",
  "options": {
    "queue": 3,
    "identity_number": "12345678901"
  }
}

Response Body

{
  "application": "b8c1118a-eaa1-4c10-a2ae-eab5d7f6f131",
  "options": {
    "queue": 3,
    "identity_number": "12345678901"
  },
  "flow": [
    { "step": "idcard_front" },
    { "step": "idcard_back" }
  ],
  "token": "user-session-token",
  "transaction": "transaction-id-xyz"
}

• application (string) — Same as input UUID
• options (object) — Echoes back selected options
• flow (array) — Ordered list of required KYC steps
• token (string) — Session token for this transaction (used for subsequent KYC steps)
• transaction (string) — Transaction ID for tracking status and details

---

c. SDK Entry Point Invocation

Flowchart Reference: Steps 7

Once the transaction is initialized, the Teydex SDK on the mobile device takes over.
Depending on the platform, this may involve calling a method like kyc.enter() (iOS) or kyc.process() (Android), using the JWT provided by the backend.

The SDK uses this token to authenticate itself and begin the guided step-by-step KYC flow, which may include scanning documents, taking selfies, or reading NFC data.

---

d. KYC Transaction Start

Flowchart Reference: Steps 8 to 9
Endpoint: POST /mobile/transaction/start
Consumed By: Teydex SDK
Purpose: Initiates the mobile-side transaction by sending device metadata and environment info. This endpoint validates the transaction context and returns the current step along with the full KYC flow status.

Headers

Name	Type	Required	Description
X-Token	string	✅	Token for the current transaction (received during init)
X-Application-Id	string	✅	Application ID in Base64 format

Request Body

{
  "device": {
    "resolution": {
      "width": 1080,
      "height": 1920
    },
    "location": {
      "lat": 41.0082,
      "lon": 28.9784
    },
    "identifier": "device-123",
    "brand": "Samsung",
    "model": "Galaxy S21",
    "sdk": "android",
    "sdk_version": "2.3.1",
    "os": "android",
    "os_version": "13",
    "nfc": true
  }
}

Response Body

{
  "id": "e73f0a5a-bc8a-4a96-bb30-44ad8b9e1f7d",
  "current_step": "idcard_front",
  "flow": [
    {
      "step": "idcard_front",
      "status": "CREATED",
      "number_of_remaining_attempts": 5
    },
    {
      "step": "idcard_back",
      "status": "CREATED",
      "number_of_remaining_attempts": 5
    }
  ],
  "status": "IN_PROGRESS"
}

• id (string) — UUID of the mobile transaction
• current_step (string) — The step the SDK should handle next
• flow (array) — Steps in the process with status and retry data
• status (string) — Overall transaction status (IN_PROGRESS, COMPLETED, etc.)

---

e. KYC Step Submission (Process Request)

Flowchart Reference: Step 10 - 11
Endpoint: POST /mobile/transaction/process
Consumed By: Teydex SDK
Purpose: Submits data for the current KYC step, such as document images, video files, facial images, or parsed NFC data. Step and status is updated after each consecutive call.

Headers

Name	Type	Required	Description
X-Token	string	Yes	Token for the current transaction
X-Application-Id	string	Yes	Application ID in Base64 format

Request Parameters (multipart/form-data)

Name	Type	Required	Applies To	Description
image	file	No	idcard_front/back/nfc	Document image upload
video	file	No	hologram	Video upload for hologram step
front_face_image	file	No	face	Face scan - front view
up_face_image	file	No	face	Face scan - up view
down_face_image	file	No	face	Face scan - down view
left_face_image	file	No	face	Face scan - left view
right_face_image	file	No	face	Face scan - right view
birth_date	string	No	nfc	Parsed from NFC
expiry_date	string	No	nfc	Parsed from NFC
gender	string	No	nfc	Parsed from NFC
issuer	string	No	nfc	Parsed from NFC
name	string	No	nfc	Parsed from NFC
surname	string	No	nfc	Parsed from NFC
nationality	string	No	nfc	Parsed from NFC
identity_number	string	No	nfc	Parsed from NFC
serial_number	string	No	nfc	Parsed from NFC
appointment_id	integer	No	video_call	Identifier for appointment

Response Body

{
  "transaction": {
    "id": "c4fffb3a-9cd1-4b83-8a0e-55e30d192f8c",
    "current_step": "nfc",
    "flow": [
      {
        "step": "idcard_front",
        "status": "DONE",
        "number_of_remaining_attempts": 5
      },
      {
        "step": "nfc",
        "status": "CREATED",
        "number_of_remaining_attempts": 5
      }
    ],
    "status": "IN_PROGRESS"
  },
  "status": "success",
  "data": {
    // Depends on the step processed
  },
  "preparation_data": {
    "nfc_hint": "Place your card close to the NFC scanner"
  }
}

• transaction: Updated mobile transaction details including flow status
• status: Submission result (e.g., "success", "retry", or "fail")
• data: Result-specific data (may vary by step)
• preparation_data: Optional instructions or hints for upcoming steps

---

f. Final Transaction Retrieval

Flowchart Reference: Step 12-14
Endpoint: GET /mobile/transaction/
Consumed By: Client Middleware
Purpose: Retrieves the most up-to-date state of the transaction, including current step, flow history, and status. Typically used after the SDK completes all steps but can be used during the KYC flow at any time desired.

Headers

Name	Type	Required	Description
X-Token	string	Yes	Token for the current transaction
X-Application-Id	string	Yes	Application ID in Base64 format

Response Body

{
  "id": "a2b06bb4-7d7a-466b-93d1-9f4d2765dbf4",
  "current_step": "completed",
  "flow": [
    {
      "step": "idcard_front",
      "status": "DONE",
      "number_of_remaining_attempts": 0
    },
    {
      "step": "idcard_back",
      "status": "DONE",
      "number_of_remaining_attempts": 0
    },
    {
      "step": "nfc",
      "status": "DONE",
      "number_of_remaining_attempts": 0
    }
  ],
  "status": "COMPLETED"
}

• id (string) — Transaction ID
• current_step (string) — Indicates which step is active or if the flow is completed
• flow (array) — List of all steps and their statuses
• status (string) — Final transaction status (COMPLETED, FAILED, etc.)