Integration with Mobile SDK

1. What is RS-ID Mobile SDK

RS-ID Mobile SDK lets your mobile app (Android / iOS) confirm that a real, live person is who they claim to be, using their face and the national identity registry of Uzbekistan.

You do not build any camera, liveness or face-matching logic. Your backend creates a session, your app starts the RS-ID SDK (a native library added to your app), the user takes a selfie, and RS-ID:

checks that the selfie is a live person, not a photo, screen or mask (anti-spoofing);

fetches the citizen's official passport photo and data from the government registry;

compares the selfie with the passport photo;

returns the result to your app, and gives your backend the verified citizen profile.

Use cases

Use case	Example
Remote customer onboarding (KYC)	A bank, microfinance or insurance app opens an account without a branch visit.
Identity confirmation before a sensitive action	Confirming the account owner before a large transfer, a password reset or changing a phone number.
Online contract signing	Making sure the person signing a loan or rental agreement in the app is the actual citizen.
Age / identity checks	Marketplaces, telecom, gaming or delivery apps that must verify age or a real identity.
Pre-filled registration	The user only takes a selfie; your registration form is filled with verified name, document and birth date.
Repeat verification	A returning user is verified again with the data from their earlier session, without entering it again.

2. Terminology

Term	Who it is
Client	The company integrating RS-ID (you). Registered in RS-ID and issued a `client_id` / `client_secret` for Mobile SDK. Includes the client backend (calls the RS-ID API) and the client app (your Android / iOS app with the RS-ID SDK inside).
User	The end person being identified — your customer, a citizen of Uzbekistan.
Server	The RS-ID server: the Mobile SDK API (`<rsid_base_url>`).
RS-ID SDK	The native RS-ID library added to the client app. It shows the RS-ID screens (data entry, camera) and sends the selfie to the server.
Session	One identification attempt created by the client backend. Identified by `session_id` (UUID). Has a limited lifetime and a limited number of attempts.
PINFL	Personal identification number of an individual — 14 digits.
Document number (`id_number`)	Passport or ID card series and number, e.g. `AA1234567`.

3. Integration type — native SDK

The RS-ID screens run inside your app through the RS-ID SDK. The user never leaves the app.

Add the RS-ID SDK to your Android / iOS project. The package and installation instructions are provided by RS-ID together with your credentials.

Allow camera access in the app:

Android — android.permission.CAMERA in AndroidManifest.xml;

iOS — NSCameraUsageDescription in Info.plist (the text shown to the user when the camera is requested).

Start the SDK with the session_id from your backend (7.4).

Handle the result the SDK returns to your app — success, failure or cancelled by the user (7.6).

Confirm the result on your backend with GET /v1/user/{session_id} (7.7).

Unlike Web SDK, Mobile SDK sessions are not bound to an IP address and there is no redirect_url — the result comes back to your app from the SDK.

4. Integration diagram

5. Environments

Environment	API base URL
Stage (testing)	`https://sdk.stage.rsid.uz/mobile/api`
Production	`https://sdk.rsid.uz/mobile/api`

Stage and production use different client_id / client_secret. Mobile SDK credentials are separate from Web SDK credentials — a Web SDK client cannot create mobile sessions (-1002).

6. General rules

Response envelope

Every API response has the same structure:

{ "data": { }, "code": 0, "message": "Success" }

Field	Type	Description
`code`	integer	`0` — success. Any other value is an error (see the error tables). Always check `code`, not only the HTTP status.
`message`	string	Human-readable text in the request language (uz / ru / en). Do not parse it.
`data`	any	Response payload. Absent on errors.

Headers

Header	Value	Used in
`Content-Type`	`application/json`	All POST requests
`Authorization`	`Bearer {access_token}`	All requests except `sign-in` and `refresh`
`Accept-Language`	`uz` / `ru` / `en`	Optional — language of `message`

Security. client_secret must stay on the client backend. Never put it into the app — app files can be extracted. Call sign-in and create session only from your backend.

7. API definitions

Exchanges client credentials for an access token.

Method - POST
Endpoint - {base_url}/v1/auth/sign-in — no Authorization header
Content-Type (Headers) - application/json

Request body

Field	Type	Required	Length / format	Description
`client_id`	string	Yes	Non-empty; must not start with a digit	Mobile SDK client identifier issued by RS-ID.
`client_secret`	string	Yes	Non-empty	Client secret issued by RS-ID.

{
  "client_id": "mobile-sdk-client",
  "client_secret": "s3cr3t-value"
}

Response

Field	Type	Description
`data.access_token`	string (JWT)	Token for the `Authorization: Bearer` header.
`data.token_type`	string	Always `Bearer`.
`data.expires_in`	integer	Token lifetime in seconds.
`data.scope`	string	Granted scopes, space-separated.
`data.refresh_token`	string (JWT)	Token to get a new `access_token` without sending credentials again.
`code`	integer	`0` on success.
`message`	string	Result text.

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "read write",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "code": 0,
  "message": "Success"
}

Reuse the access_token until it expires instead of signing in for every session.

7.2 Refresh token

Gets a new access_token with the refresh_token, without sending a new sign-in. Call it when the access_token has expired (after expires_in seconds).

Method - POST
Endpoint - {base_url}/v1/auth/refresh?token={refresh_token} — no Authorization header.
Content-Type (Headers) - application/json

Query parameters

Field	Type	Required	Length / format	Description
`token`	string	Yes	JWT	`refresh_token` from the sign-in (7.1) or a previous refresh response.

Request body

Field	Type	Required	Length / format	Description
`client_id`	string	Yes	Non-empty; must not start with a digit	Mobile SDK client identifier issued by RS-ID.
`client_secret`	string	Yes	Non-empty	Client secret issued by RS-ID.

{
  "client_id": "mobile-sdk-client",
  "client_secret": "s3cr3t-value"
}

Response

Field	Type	Description
`data.access_token`	string (JWT)	New token for the `Authorization: Bearer` header.
`data.token_type`	string	Always `Bearer`.
`data.expires_in`	integer	Token lifetime in seconds.
`data.scope`	string	Granted scopes, space-separated.
`data.refresh_token`	string (JWT)	New refresh token. Use it for the next refresh.
`code`	integer	`0` on success.
`message`	string	Result text.

{
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "read write",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "code": 0,
  "message": "Success"
}

If the refresh token is expired or invalid, sign in again (7.1).

7.3 Create session

Creates an identification session for one user. The session belongs to your client: only requests made with your client's token can use it.

Method - POST
Endpoint - {base_url}/v1/sessions
Authorization (Headers) - Bearer {access_token}
Content-Type (Headers) - application/json

Request body

Field	Type	Required	Length / format	Description
`client_type`	string (enum)	Yes	`MOBILE`	Integration channel. Always `MOBILE` for Mobile SDK.
`user_info`	object	No	—	Citizen data. Send it to create a session with user_info; omit it for a session without user_info.
`user_info.pinfl`	string	Conditional	Exactly 14 digits	PINFL. Send either `pinfl` or `id_number`, not both.
`user_info.id_number`	string	Conditional	9 chars: 2 letters + 7 digits, e.g. `AA1234567`	Passport / ID card number. Send either `pinfl` or `id_number`, not both.
`user_info.birth_date`	string	Yes, if `user_info` is sent	`dd.MM.yyyy`	Date of birth. User must be at least 16 years old.
`session_id`	string	No	UUID, 36 chars	An earlier session of your client for the same user. The new session takes the citizen data from it, so the user does not enter it again. Ignored if `user_info` is sent.
`external_id`	string	No	—	Your own reference (order, application or customer id) to link the session to your records. Recommended random `uuid`.
`retry_count`	integer	No	> 0	Maximum number of attempts. If omitted, 0 or above the system maximum, the system maximum is used.
`threshold`	number	No	`0.0` – `1.0`	Minimum face-similarity score to pass. Default `0.5`. See the note below.
`locale`	string (enum)	No	`UZ`, `RU`, `EN`	Default `UZ`.
`additional_params`	object	No	Only the keys below	Settings for the RS-ID SDK screens. Any other key is rejected.
`additional_params.lang`	string	No	`uz`, `ru`, `en`	Language of the SDK screens.
`additional_params.theme`	string	No	e.g. `light`, `dark`	Theme of the SDK screens.
`additional_params.primary_color`	string	No	Hex color, e.g. `#1A73E8`	Accent color of the SDK screens.

Threshold. threshold is the minimum face-similarity score (from 0.0 to 1.0) the selfie must reach against the passport photo for identification to pass. If you don't send it, the default 0.5 is used. If you do send it, we recommend a value above 0.5. For high-quality (strict) identification, send a value above 0.7. A higher value is stricter and lowers the risk of a wrong person passing, but genuine users may need more attempts.

No IP binding, no redirect. Mobile sessions do not use ip_address or redirect_url. The result is returned to your app by the SDK (7.6).

Request examples — choose an option:

Session with user_info

Option 1 — Session with user_info

The client backend already knows the user's data. The SDK will only open the camera.

{
  "client_type": "MOBILE",
  "external_id": "ORDER-123",
  "retry_count": 3,
  "threshold": 0.7,
  "locale": "UZ",
  "user_info": {
    "pinfl": "12345678901234",
    "birth_date": "01.01.1990"
  },
  "additional_params": {
    "lang": "uz"
  }
}

Using a document number instead of PINFL:

"user_info": { "id_number": "AA1234567", "birth_date": "01.01.1990" }

Session without user_info

Repeat verification (session_id)

Response

Field	Type	Length / format	Description
`data`	string	UUID, 36 chars	`session_id` of the new session. Pass it to the RS-ID SDK and use it to get the result.
`code`	integer		`0` on success.
`message`	string		Result text.

{
  "data": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "code": 0,
  "message": "Success"
}

Errors

Code	Reason
`-1000`	Invalid request — e.g. both or neither of `pinfl` / `id_number` in `user_info`.
`-1002`	Credentials do not belong to a Mobile SDK client, or `session_id` belongs to another client.
`-1024`	Invalid `id_number` format.
`-1025`	Invalid `pinfl` format.
`-1026`	`birth_date` is missing.
`-1029`	`session_id` not found.
`-1034`	Unknown key in `additional_params`.
`-1052`	`threshold` outside 0–1.
`-1090`	User is younger than 16.
`400`	Field validation error, or `client_type` is missing.

7.4 Start the RS-ID SDK

With the session_id, the client app starts the RS-ID SDK.

Your backend creates the session (7.3) and returns session_id to the app.

The app starts the RS-ID SDK with:

Parameter	Description
`session_id`	From 7.3.
`access_token`	A valid access token of your Mobile SDK client. The SDK uses it to call the RS-ID server; the server accepts requests for a session only with the token of the client that created it.
Environment	Stage or production — must match the environment where the session was created.

The session has a limited lifetime and number of attempts. Start the SDK right after creating the session; if it expires, create a new one.

7.5 User flow in the RS-ID SDK

The SDK has two modes. Which one the user sees depends on how the session was created in 7.3:

SDK mode	Shown when	What the user does
with_info	Session created without `user_info` and without `session_id` (Option 2)	Enters their data, then takes a selfie
without_info	Session created with `user_info` (Option 1) or with an earlier `session_id` (Option 3)	Only takes a selfie

with_info — data entry, then camera

The SDK starts with the data-entry screen.

The user enters their passport series and number or PINFL (JSHSHIR) and their date of birth (DD.MM.YYYY).

The user accepts the User agreement and Privacy policy with the switch. The Continue (Davom etish) button becomes active; the user taps it.

The app asks for camera access (system permission dialog). The user allows it.

The camera opens with the hint "Hold your face inside the circle" (Yuzingizni doira ichida tuting). While no face is found, the circle is red; once the face is in position, the selfie is taken.

RS-ID checks liveness and compares the face with the passport photo of the entered person. The SDK shows "Identification in progress" (Identifikatsiya amalga oshirilmoqda).

On success the SDK shows "Identification completed successfully!" (Identifikatsiya qilish muvaffaqiyatli amalga oshirildi!) and returns the result to the app (7.6).

without_info — camera only

The app asks for camera access (system permission dialog). The user allows it.

The camera opens. The user places their face inside the frame and the selfie is taken.

RS-ID checks liveness and compares the face with the passport photo.

The SDK returns the result to the app (7.6).

Failed attempts

If the user denies camera access, the SDK cannot continue — the user must allow the camera in the phone settings for your app.

If the selfie is rejected (spoof detected, face does not match, citizen not found), the SDK shows the reason and lets the user try again while attempts remain (retry_count). When attempts run out or the session expires, the SDK returns a failure and the client must create a new session.

7.6 Result in the app

When the user finishes, the SDK returns the result to your app:

Result	What to do
Success	Tell your backend the session is finished; the backend fetches the profile (7.7).
Failure	Attempts ran out or the session expired. Create a new session (7.3) if the user wants to try again.
Cancelled	The user closed the SDK. You can start the SDK again with the same `session_id` while it is active.

Do not treat the result in the app alone as proof of identification — the app runs on the user's device and can be modified. Always confirm the result from your backend with 7.7.

7.7 Get identification result

The client backend gets the verified citizen profile.

Method - GET
Endpoint - {base_url}/v1/user/{session_id}
Authorization (Headers) - Bearer {access_token}

Path parameters

Field	Type	Required	Length / format	Description
`session_id`	string	Yes	UUID, 36 chars	From 7.3.

Response

Field	Type	Description
`data.session_id`	string	Session id.
`data.comparison_value`	number	Face similarity score, 0–1.
`data.note`	string	Failure note, if any.
`data.profile.user_info.first_name`	string	First name.
`data.profile.user_info.last_name`	string	Last name.
`data.profile.user_info.middle_name`	string	Patronymic.
`data.profile.user_info.pinfl`	string	PINFL, 14 digits.
`data.profile.user_info.gender`	string	Gender.
`data.profile.user_info.birth_date`	string	`yyyy-MM-dd`.
`data.profile.user_info.birth_place`	string	Place of birth.
`data.profile.user_info.birth_country`	string	Country of birth.
`data.profile.user_info.nationality`	string	Nationality.
`data.profile.user_info.citizenship`	string	Citizenship.
`data.profile.document_info.document`	string	Document series and number.
`data.profile.document_info.type`	string	Document type.
`data.profile.document_info.issued_by`	string	Issuing authority.
`data.profile.document_info.issued_at`	string	Issue date, `yyyy-MM-dd`.
`data.profile.document_info.expiry_at`	string	Expiry date, `yyyy-MM-dd`.
`data.profile.permanent_address`	object	`country`, `country_id`, `region_id`, `district_id`, `address`.
`data.profile.temporary_address`	object	May be `null`.

{
  "data": {
    "session_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "comparison_value": 0.93,
    "profile": {
      "user_info": {
        "first_name": "ALISHER",
        "last_name": "KARIMOV",
        "middle_name": "BAXTIYOROVICH",
        "pinfl": "12345678901234",
        "gender": "MALE",
        "birth_date": "1990-01-01",
        "birth_place": "TOSHKENT",
        "birth_country": "UZBEKISTAN",
        "nationality": "UZBEK",
        "citizenship": "UZBEKISTAN"
      },
      "document_info": {
        "document": "AA1234567",
        "type": "PASSPORT",
        "issued_by": "IIV 26283",
        "issued_at": "2018-05-10",
        "expiry_at": "2028-05-09"
      },
      "contact_info": {},
      "permanent_address": {
        "country": "UZBEKISTAN",
        "country_id": 182,
        "region_id": 26,
        "district_id": 2603,
        "address": "..."
      },
      "temporary_address": null
    }
  },
  "code": 0,
  "message": "Success"
}

Errors

Code	Reason
`-1005`	Identification was not successful.
`-1027`	Session expired — fetch the result right after the SDK returns success.
`-1029`	Session not found.
`-1002`	Session belongs to another client.

8. Error codes

Code	Name	Meaning
`0`	SUCCESS	Success.
`-5`	BAD_CREDENTIALS	Invalid credentials or token user not found.
`-9`	SYSTEM_ERROR	Unexpected server error.
`-1000`	BAD_REQUEST	Invalid request.
`-1002`	CLIENT_NOT_PERMITTED	Not allowed for this client.
`-1005`	UNSUCCESS_JOB	Identification not successful.
`-1008`	IDENTIFICATION_FAILED	Face did not match.
`-1024`	INVALID_ID_NUMBER	Invalid document number.
`-1025`	INVALID_PINFL	Invalid PINFL.
`-1026`	BIRTH_DATE_NOT_NULL	Birth date required.
`-1027`	SESSION_EXPIRED	Session expired.
`-1029`	JOB_SESSION_NOT_FOUND	Session not found.
`-1031`	RETRY_COUNT_EXPIRED	No attempts left.
`-1032`	SUCCESS_JOB_EXISTS_FOR_SESSION	Session already identified.
`-1033`	SPOOFED_FILE_DETECTED	Liveness check failed.
`-1034`	ADDITIONAL_PARAMS_INVALID	Unknown `additional_params` key.
`-1052`	INVALID_THRESHOLD_LIMIT	`threshold` outside 0–1.
`-1090`	USER_AGE_OLDER_THAN_16	User must be at least 16.
`-2001`	AI_ERROR	Face service error.

Usage guide

Integration with Mobile SDK#

1. What is RS-ID Mobile SDK#

Use cases#

2. Terminology#

3. Integration type — native SDK#

4. Integration diagram#

5. Environments#

6. General rules#

Response envelope#

Headers#

7. API definitions#

7.1 Sign in#

7.2 Refresh token#

7.3 Create session#

Option 1 — Session with user_info#

7.4 Start the RS-ID SDK#

7.5 User flow in the RS-ID SDK#

with_info — data entry, then camera#

without_info — camera only#

Failed attempts#

7.6 Result in the app#

7.7 Get identification result#

8. Error codes#

Integration with Mobile SDK

1. What is RS-ID Mobile SDK

Use cases

2. Terminology

3. Integration type — native SDK

4. Integration diagram

5. Environments

6. General rules

Response envelope

Headers

7. API definitions

7.1 Sign in

7.2 Refresh token

7.3 Create session

Option 1 — Session with user_info

7.4 Start the RS-ID SDK

7.5 User flow in the RS-ID SDK

with_info — data entry, then camera

without_info — camera only

Failed attempts

7.6 Result in the app

7.7 Get identification result

8. Error codes