Unibeam Authentication Documentation

Welcome to Unibeam SIA, an inSIM Identity Authentication platform designed to securely verify subscribers' digital identities. Unibeam Auth leverages the inherent security of the (e)SIM, delivering authentication that is hardware bound and software embedded on the subscriber's (e)SIM Secure Element. A SIM uses a secure microchip on a portable piece of plastic, while an eSIM uses a microchip already soldered in the motherboard of your phone. Both provide the same Secure Element strength of a dedicated highly secure cryptographic hardware.

Unibeam reduces reliance on traditional 2FA methods by supporting two authentication models:

•Silent Authentication – SIM‑based verification with no subscriber interaction
•Touch Authentication – SIM‑based push notifications that require explicit subscriber approval

Why Unibeam?

Unibeam provides a full REST API–based implementation that simplifies onboarding and enables fast, scalable enterprise integration, including:

•Touch Authentication – SIM‑based push notifications that require explicit mobile subscriber approval
•SIM‑based approval requests delivered directly to the device, requiring explicit user action
•Delivery and read confirmation, with non‑ignored status returned to the enterprise

One solution, flexible authentication levels — Unibeam Silent, Touch, Multi Secure and Item Select

Authentication API Models

Unibeam enables enterprises to authenticate subscribers using multiple authentication mechanisms, applied at different stages of the user's account lifecycle and usage:

•Silent Auth – Confirms the subscriber with no popup and no user interaction (100% silent).
•Touch Auth – Displays a popup notification presenting a Yes / No question to the subscriber.
•MultiSecure Auth – Displays a popup notification presenting a question and collects a free‑form subscriber response.
•ItemSelect Auth – Displays a popup notification presenting a question followed by multiple selectable answers, and collects the subscriber's selection.

BASE URLs

Use these base URLs in front of all API URLs in this documentation

Callback (Asynchronous)ihttps://api.global.unibeam.com

Synchronous (SyncAPI)ihttps://sapi.global.unibeam.com

All Endpoints at a Glance

POST /oauth2/token POST /lookup POST /consent POST /auth/silent POST /auth/touch POST /business/transaction-touch POST /business/transaction-multisecure POST /business/select-item

🚀 Getting Started

This guide outlines the prerequisites for integrating Unibeam Auth and walks you through your first authenticated request.

How to get your credentials

Contact your Unibeam representative to onboard your organization.
Once onboarded, you will receive a unique CustomerId from your Unibeam contact.
Sign in to the Unibeam Customer Dashboard and navigate to API Access → Generate Credentials.
Generate your ClientId and ClientSecret. Treat the secret as confidential and store it in a secure secret manager.

Prerequisites

You will need:

CustomerIdi

Issued by your Unibeam contact at onboarding. Sent on every API request via the customerId header.

Required

ClientIdi

Generated in the Customer Dashboard. Used in the OAuth2 token exchange.

Required

ClientSecreti

Generated alongside ClientId. Treat as confidential and store in a secure secret manager.

Required

A public callback URL

Required for asynchronous flows so Unibeam can deliver the final result. Alternatively, use the /sync variant of any endpoint to skip callbacks and receive the result directly in the HTTP response.

BASE URLs

Use these base URLs in front of all API URLs in this documentation

Callback (Asynchronous)ihttps://api.global.unibeam.com

Synchronous (SyncAPI)ihttps://sapi.global.unibeam.com

Your first request

Two requests will validate your integration end to end: obtain a Bearer token, then silently verify a test subscriber.

1. Obtain an access token

cURL

curl -X POST https://api.global.unibeam.com/oauth2/token \
  -d 'grant_type=client_credentials' \
  -u "$CLIENT_ID:$CLIENT_SECRET"

2. Silently verify a subscriber

With Callback — POST to https://api.global.unibeam.com/auth/silent

JSON

{
  "msisdn": "+15551234567",
  "requestId": "01JCD5XP5GZ2EW3PQMPJMQ5K7P",
  "cbUrl": "https://your-app.example.com/unibeam/callback"
}

Sync — POST to https://sapi.global.unibeam.com/auth/silent

JSON

{
  "msisdn": "+15551234567",
  "requestId": "01JCD5XP5GZ2EW3PQMPJMQ5K7P"
}

✅

A 200 OK with "status": "VALID" indicates the SIM was matched successfully. Your integration is operational.

Where to go next

•Status Codes — every response code returned by the platform and the recommended client-side handling.
•Templates & Input Types — message limits, encoding rules, and how prompts render on the subscriber's device.
•OAuth2 → Lookup → Auth flow — the recommended call sequence for production deployments.

📋 Statuses & Codes

All status values that can appear in callback and response payloads across all Unibeam API endpoints.

Status Values

📚 Primary Terms

Definitions of the primary terms referenced in status payloads and across the API.

Displayable name

The "displayablename" is a name chosen by the customer and approved during the customer contractual onboarding. For instance, a customer with a legal contractual name "The Hongkong and Shanghai Banking Corporation Limited" may choose a displayable name of "HSBC".

Every message displayed on a pop-up on a user's phone will have the following format:

First row: Unibeam Auth – [Displayable name]
Third row: text content sent in the API

The [Displayable name] is chosen by the customer at the time of onboarding and configured in the Unibeam portal/dashboard.

5:33

Unibeam Auth – HSBC

If you have initiated this request, please approve the login attempt to hsbc.com

Cancel

Accept

Example

Company name: Hongkong and Shanghai Banking Corporation Limited

Displayable name chosen by the Company: HSBC

1st pop-up row: Unibeam Auth - HSBC

The displayable name is enforced to prove which enterprise is sending the remaining of text in the popup. Displayable name is attached to the OAuth clientID that sends the API, it cannot be spoofed or manipulated.

Identifiers

Unibeam Auth creates unique identifiers that allow enterprises to verify subscriber registration and device association:

SIM Identifier — a cryptographic identifier bound to the subscriber's (e)SIM.
Device Identifier — a cryptographic identifier representing the device hosting the (e)SIM.
lastImeiChange — the date/time since when the user phone number has been in the same device, enabling enterprises to detect SIM swap (device change) and define policies that trigger either independently (based solely on change recency) or in conjunction with anomaly detection (e.g., suspicious recent SIMswap etc).

Integration Options

Enterprises can leverage these identifiers in two complementary ways, depending on whether they wish to maintain server-side state for each subscriber:

Identifier-based validation — at user onboarding the enterprise retrieves the SIM & Device Identifiers and stores them in the enterpise database, then for future APIs, the enterprise compares the live identifiers returned by Unibeam Auth (Touch, Silent, etc.) against the stored records for that user number.
Device change validation via lastImeiChange — the enterprise does not store any identifiers data in their database and instead relies on the lastImeiChange response to be confirmed by a business rule (e.g., reject logins where the IMEI changed within the past N day. For instance if a phone number has been on the user phone for 6 months, trust the number/user response. If the last Imeicghange is only 5 minutes ago, this is suspicious, do not trust the response as-is and proceed with a step-up authentication ).

SIA — SIM Identity and Authentication

SIA (SIM Identity and Authentication) is the Unibeam component installed on the subscriber's (e)SIM that performs the cryptographic operations behind every authentication. It generates the (e)SIM Identifier and Device Identifier, signs requests, and produces the responses returned from the (e)SIM to the SIA server and from the SIA server to the enterprise.

Callback (Asynchronous API)

Callback refers to an asynchronous integration model where Unibeam sends the final result of an operation (e.g. consent or authentication answers and identifiers) to a predefined callback URL (cbUrl) provided by the enterprise.

The API request returns immediately after triggering the flow
The subscriber's response is delivered later via an HTTP callback
Suitable for scalable, non-blocking architectures
Recommended when the enterprise can expose and manage a webhook endpoint

Synchronous API

Synchronous API refers to a model where the API HTTP session remains open until the SIA responses are received and the operation is completed.

The request uses long-polling
The connection stays open until:
- The subscriber responds, or
- A timeout is reached (e.g. 40 seconds)
The final result is returned directly in the HTTP response
Suitable when a callback URL is not available or not desired

Full URL

The Full URL is the complete request URL the enterprise sends each API call to. It is built by combining the appropriate Base URL (which differs for Callback vs. Synchronous integrations) with the endpoint path of the specific API (e.g., /api/v1/auth/touch, /api/v1/lookup).

Callback (Asynchronous) — uses the asynchronous Base URL https://api.global.unibeam.com, e.g., POST https://api.global.unibeam.com/api/v1/auth/touch.
Synchronous (SyncAPI) — uses the synchronous Base URL https://sapi.global.unibeam.com, e.g., POST https://sapi.global.unibeam.com/api/v1/auth/touch. The sapi. subdomain itself signals the synchronous behavior — no path suffix is required.

Each API page in this documentation lists its exact Full URLs (Callback and Synchronous variants) in the “🔗 Full URL & how to call this endpoint” callout at the top of the section.

⚠️ Heads up: When using the Synchronous SyncAPI, there is no need to include a callback URL in the request body. If a callback URL is included it will be ignored.

Callback API vs. Synchronous API — Pros & Cons

Side-by-side comparison to help select the right integration model for your environment.

Callback API Async

Pros

Doesn’t block the thread/session while waiting for a response

Better for high concurrency

Can handle many simultaneous operations efficiently

Streaming support

Enables progressive data delivery as it arrives

Responsive UIs

UI stays interactive while requests are in-flight

Scalable architecture

Aligns well with event-driven and microservice patterns

Cons

Callback function needs to be supported

The enterprise needs to already support or implement a callback function

Synchronous API Sync

Pros

Simple, linear code flow

Execution proceeds top-to-bottom, easy to follow

Easier error handling

Standard try/catch blocks work intuitively

Predictable execution order

Results are available immediately after the call

Easier to test and debug

Deterministic behavior makes unit testing straightforward

Lower cognitive overhead

Easier for beginners and smaller teams to work with

Cons

Resources heavy for large volumes

For large volumes of concurrent sessions, requires heavy resources on the enterprise side

🖊️ Templates & Input Types

Using Unibeam Business APIs, the enterprise can choose the text and create its own messages for the popup messages that SIA will trigger on the user phone screen, subject to the following limits.

Phone pop-ups messages text

Each notification includes a hard-coded header prefix (Unibeam Auth - ) followed by the customer's display name (e.g. displayable name). The header is prepended automatically to every message the enterprise sends. The displayable name is configured in the Unibeam dashboard.
The total characters that the enterprise can send in the API request are:

UTF-8 max: 207 chars UTF-16 max: 102 chars

ℹ️

Character limits depend on the message encoding:

UTF-8 (GSM-7, 1 byte/char) — up to 207 characters.
UTF-16 (UCS-2, 2 bytes/char) — up to 102 characters. Used automatically when the message contains any character outside GSM-7.

Message Input Types

Used with the messageInputTypes parameter in the Business Transaction Multisecure endpoint.
The enterprise can restrict the type of answer that a user can write on its phone as the answer to a Multisecure popup API request.

Value	Type	Notes

Popup message text length tester

The hard-coded header Unibeam Auth - displayable name is prepended automatically. Use the tester below to validate your custom message body against the UTF-8 / UTF-16 character limits.

Display Name (replaces displayable name) Custom Message

Detected encoding: UTF-8 Length: 0 / 207 chars (message) OK

API / Flow

🔑 OAuth2 Token API

Retrieve a Bearer token for API authentication using the OAuth 2.0 Client Credentials grant. All Unibeam Auth APIs require this token in the Authorization header.

https://auth.global.unibeam.com/oauth2/token

POST /oauth2/token Exchange client credentials for a short-lived access token ▼

Request:

HTTP

POST /oauth2/token HTTP/1.1
Host: auth.global.unibeam.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=your_id&client_secret=your_secret

HTTP Status Codes: 200 OK | 400 Bad Parameters | 401 Unauthorized | 429 Too Many Requests

⚠️ Credentials are sent in the request body as plain text. Always use HTTPS.

Request Parameters:

Parameter	Type	Required	Description
`grant_type`	String	Required	Must be `client_credentials`
`client_id`	String	Required	Generated via Customer Dashboard → API Access → Generate Credentials
`client_secret`	String	Required	Generated via Customer Dashboard → API Access → Generate Credentials

Response Fields:

Field	Type	Required	Description
`access_token`	String	Required	Bearer token for API calls
`expires_in`	Long	Required	Token lifetime in seconds
`token_type`	String	Required	Always "Bearer"

JSON

{
  "access_token": "eyJraWQiOiJrZXkiLCJhbGciOiJIUzI1NiJ9...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

ℹ️ Pass the token as Authorization: Bearer <access_token> on every API request. Token lifetime: 3600 s — cache and reuse.

🔍 Lookup & Consent API.

Lookup API

To verify whether the mobile phone of a user is supported and authorized to use Unibeam Auth, enterprises can first perform a Lookup operation.

The Lookup API returns the subscriber's current status and indicates whether explicit consent is required before authentication can proceed.

🔗 Full URL & how to call these endpoints

Each API request must use the appropriate Base URL, combined with the endpoint path below, to form the complete request URL.

Lookup

Callback (Asynchronous)iPOST https://api.global.unibeam.com/api/v1/lookup

Synchronous (SyncAPI)iPOST https://sapi.global.unibeam.com/api/v1/lookup

Consent

Callback (Asynchronous)iPOST https://api.global.unibeam.com/api/v1/consent

Synchronous (SyncAPI)iPOST https://sapi.global.unibeam.com/api/v1/consent

For more on the difference between Callback (Asynchronous) and Synchronous APIs, see Primary Terms.

POST /api/v1/lookup Check if the subscriber has the Unibeam SIM application installed ▼

Request Body:

HTTP

POST /api/v1/lookup HTTP/1.1
customerId: xyz
Content-Type: application/json
Authorization: Bearer <token>

{
  "msisdn": "123456789",
  "requestId": "1234"
}

HTTP Status Codes: 200 OK | 400 Bad Parameters | 401 Unauthorized | 429 Too Many Requests

Request Parameters:

Parameter	Type	Required	Description
`requestId`	String	Required	Unique request identifier
`msisdn`	String	Required	Phone number of the end-user

Response Fields:

Field	Type	Required	Description
`requestId`	String	Required	Echo of the request ID
`status`	String	Required	NOT_FOUND · OPTED_OUT · ALREADY_CONSENTED · REQUIRE_CONSENT · VALID
`responseType`	String	Required	Always "LOOKUP"

Consent API

The API triggers a predefined popup on the subscriber's device, asking the subscriber to approve Consent using their (e)SIM. The consent result is delivered asynchronously to the configured callback URL (cbUrl).

POST /api/v1/consent Trigger consent popup on the subscriber's device ▼

Request Body:

HTTP

POST /api/v1/consent HTTP/1.1
customerId: xyz
Content-Type: application/json
Authorization: Bearer

{
  "msisdn": "123456789",
  "cbUrl": "https://xyz.com/callback",
  "requestId": "1234"
}

HTTP Status Codes: 200 OK | 400 Bad Parameters | 401 Unauthorized | 429 Too Many Requests

Response Fields:

Field	Type	Required	Description
`requestId`	String	Required	Echo of the request ID
`status`	String	Required	WAITING_FOR_RESPONSE · NOT_FOUND · IN_PROGRESS · OPTED_OUT · ALREADY_CONSENTED · NOT_SUPPORTED
`responseType`	String	Required	Always "CONSENT"

Callback Fields:

Field	Type	Required	Description
`responseType`	String	Required	Always "CONSENT"
`requestId`	String	Required	Echo of the request ID
`status`	String	Required	APPROVE · NOT_APPROVED · IGNORE · NOT_AVAILABLE

JSON

{
  "responseType": "CONSENT",
  "requestId": "01JCD5XP5GZ2EW3PQMPJMQ5K7P",
  "status": "APPROVE"
}

ℹ️ Unibeam retries delivery up to 3 times unless HTTP 200 is received. If no response is received within 60 seconds, the phone may be off or have a connectivity issue.

👤 User Experience & Use Cases

When a subscriber's status returns REQUIRE_CONSENT from Lookup, the enterprise must trigger the Consent API. A native popup is presented directly from the subscriber's (e)SIM, asking the subscriber to approve or reject the use of Unibeam Auth on their line. Approval is a one-time gate — once granted, subsequent authentication calls (Silent, Touch, etc.) proceed without re-prompting.

📲 Subscriber Consent — SIM-level Approval

The subscriber receives the consent popup on their device. Tapping OK records consent in Unibeam and unlocks future authentication. Tapping Cancel returns NOT_APPROVED and the enterprise can re-prompt or fall back to another flow.

9:41

Displayname.org

UnibeamAuth

Do you consent to use Unibeam Auth with Displayname.org?

Cancel

OK

SIM-level consent popup

Pushed by Unibeam's SIM directly to the subscriber's device. Tapping OK records consent for the line.

🤫 Silent API

The Silent API returns subscriber identifiers to the enterprise without any user interaction. Authentication occurs transparently in the background.

🔗 Full URL & how to call this endpoint

Each API request must use the appropriate Base URL, combined with the endpoint path below, to form the complete request URL.

Callback (Asynchronous)iPOST https://api.global.unibeam.com/api/v1/auth/silent

Synchronous (SyncAPI)iPOST https://sapi.global.unibeam.com/api/v1/auth/silent

For more on the difference between Callback (Asynchronous) and Synchronous APIs, see Primary Terms.

POST /api/v1/auth/silent Authenticate the subscriber silently via SIM — no user interaction ▼

Request Body:

HTTP

POST /api/v1/auth/silent HTTP/1.1
customerId: xyz
Content-Type: application/json
Authorization: Bearer <token>

{
  "msisdn": "123456789",
  "cbUrl": "https://xyz.com/callback",
  "requestId": "1"
}

HTTP Status Codes: 200 OK | 400 Bad Parameters | 401 Unauthorized | 429 Too Many Requests

Request Parameters:

Parameter	Type	Required	Description
`requestId`	String	Required	Unique request identifier (1 to 64 chars)
`cbUrl`	String	Required	URL of the callback. Must start with https and exist in the allowed domains list (no longer than 4096 chars)
`msisdn`	String	Required	Phone number of end-user (no longer than 20 digits)
`rejectOnActiveCall`	Boolean	Optional	True to reject flow upon an active call
`rejectOnActiveCallType`	String	Optional	If `rejectOnActiveCall` is true, this is the mode: `MT`=Incoming, `MO`=Outgoing, `MOMT`=Incoming and Outgoing. Default if left blank is `MT` (Incoming)

Response Fields:

Field	Type	Required	Description
`requestId`	String	Required	Echo of the request ID
`status`	String	Required	WAITING_FOR_RESPONSE · NOT_FOUND · IN_PROGRESS · OPTED_OUT · CONSENT_REQUIRED · NOT_SUPPORTED
`responseType`	String	Required	Always "auth/silent"

Callback Fields:

Field	Type	Required	Description
`responseType`	String	Required	Always "auth/silent"
`requestId`	String	Required	Echo of the request ID
`status`	String	Required	VALID · NOT_AVAILABLE
`simIdentifier`	String	Required	Cryptographic SIM identifier
`deviceIdentifier`	String	Required	Device identifier
`lastImeiChange`	Long	Required	Timestamp of last IMEI change (ms)

JSON

{
  "responseType": "auth/silent",
  "requestId": "01JCD5Y3QN8XV8TX175WB7V6AS",
  "status": "VALID",
  "simIdentifier": "3C8DC580C0EF80F029D4B189...",
  "deviceIdentifier": "F6475784840D2C1BC2F72577...",
  "lastImeiChange": 1738245013000
}

ℹ️ Callback: 3 retries unless HTTP 200 is received. Timeout: 10 seconds.

👤 User Experience & Use Cases

The Silent API runs entirely in the background — there is no popup, no prompt, and no tap required from the subscriber. The SIM applet responds to the authentication challenge without surfacing any UI.

Use Cases

Silent verification of the subscriber — During an onboarding a Enterprises verifies the lastEMEI date of a number to prove that a user is registering a valid and long active mobile phone...it is not a bot with stale mobile numbers.
Validating on active transaction — during a session in which the subscriber has already started a transaction, the enterprise re-validates the SIM/device binding silently in the background to confirm continuity of the same line/device before the transaction is committed.

For the integration models (identifier-based vs. device change validation via lastImeiChange), see Primary Terms → Identifiers → Integration Options.

📞 Active Call

Active call API provides silent authentication of a device (e)SIM, along with the information of call status of that (e)SIM. Is the device (e)SIM on a call at the of the API request.

- an active outgoing call (MO Mobile Originated). The user is in a call with someone that the user has called
- an active incoming call (MT Mobile Terminated). The user is in a call with someone that has called the user
- not in any active call. The user phone has no ongoing calls at that time

In all the cases the API does not provide the number of whom is calling the user or whom the user has called. The information available is only if the user is on a active call.

🔗 Full URL & how to call this endpoint

Each API request must use the appropriate Base URL, combined with the endpoint path below, to form the complete request URL.

Callback (Asynchronous)iPOST https://api.global.unibeam.com/api/v1/auth/active-call

Synchronous (SyncAPI)iPOST https://sapi.global.unibeam.com/api/v1/auth/active-call

For more on the difference between Callback (Asynchronous) and Synchronous APIs, see Primary Terms.

POST /api/v1/auth/active-call Verify if the subscriber's SIM is in the middle of an active call and which type ▼

Request Body:

HTTP

POST /api/v1/auth/active-call HTTP/1.1
customerId: xyz
Content-Type: application/json
Authorization: Bearer <token>

{
  "msisdn": "123456789",
  "cbUrl": "https://xyz.com/callback",
  "requestId": "1"
}

HTTP Status Codes: 200 OK | 400 Bad Parameters | 401 Unauthorized | 429 Too Many Requests

Request Parameters:

Parameter	Type	Required	Description
`requestId`	String	Required	Unique request identifier (1 to 64 chars)
`cbUrl`	String	Required	URL of the callback. Must start with https and exist in the allowed domains list. Valid URL scheme, no longer than 4096 chars
`msisdn`	String	Required	Phone number of end-user (no longer than 20 digits)

Response Fields:

Field	Type	Required	Description
`requestId`	String	Required	Unique request identifier
`status`	String	Required	WAITING_FOR_RESPONSE · NOT_FOUND · IN_PROGRESS · OPTED_OUT · CONSENT_REQUIRED · NOT_SUPPORTED
`responseType`	String	Required	Always "auth/active-call"

Callback Fields:

Field	Type	Required	Description
`requestId`	String	Required	Unique request identifier
`status`	String	Required	VALID · NOT_AVAILABLE
`simIdentifier`	String	Optional	Unique SIM identifier
`deviceIdentifier`	String	Optional	Unique Device identifier
`lastImeiChange`	Long	Optional	Last time IMEI change detected (unix UTC, ms)
`responseType`	String	Required	Always "auth/active-call"
`activeCallType`	String	Required	`UNAVAILABLE` – Unable to tell if there is an active call on device · `MT` – Incoming · `MO` – Outgoing · `NONE` – No active call on device

JSON

{
  "responseType": "auth/active-call",
  "requestId": "01JCD5Y3QN8XV8TX175WB7V6AS",
  "status": "VALID",
  "simIdentifier": "3C8DC580C0EF80F029D4B189...",
  "deviceIdentifier": "F6475784840D2C1BC2F72577...",
  "lastImeiChange": 1738245013000,
  "activeCallType": "MT"
}

ℹ️ Callback: 3 retries unless HTTP 200 is received. If a callback response is not received within 10 seconds, it may indicate that we were unable to retrieve a response from the SIM card (phone powered off or connectivity issue).

👤 User Experience & Use Cases

The Active Call API runs entirely in the background — there is no popup, no prompt, and no tap required from the subscriber. The SIM applet responds to the authentication challenge without surfacing any UI.

Use Cases

Call impersonation risk detection — during a session when a user calls its bank call center and the banks sees a number that is the User mobile number, the call center can trigger an Active Call Detection to the SIM of the user. If the user SIM is not an active outgoing call, it warns the call center that this is abnormal and potentialy a CLI (calling line identifier) impersonation SCAM, since the real user phone is not calling anybody at that time.
Validating on active transaction — during a session in which the subscriber has already started a transaction, the enterprise re-validates the SIM/device binding silently in the background to confirm continuity of the same line/device before the transaction is committed.

For the integration models (identifier-based vs. device change validation via lastImeiChange), see Primary Terms → Identifiers → Integration Options.

👆 Auth-Touch

The Auth-Touch returns subscriber identifiers to the enterprise only when the subscriber responds to a push notification on their mobile device. The Auth-Touch uses Unibeam's predetermined notification templates — I you want to use your own text in the popup notifications, use the Transaction Auth-Touch.

Displayable name

The "displayablename" is a name chosen by the customer and approved during the customer contractual onboarding. For instance, a customer with a legal contractual name "The Hongkong and Shanghai Banking Corporation Limited" may choose a displayable name of "HSBC".

Templates

Auth-Touch use pre-established text templates for what is displayed in the popup. New templates will be made available as needed. If you prefer to choose your own text and included it in each API request, choose Business Transaction Touch which let you set your own text.

Based on the templateID submitted by the customer, the matching text will be displayed on the end-user's phone pop-up.

TemplateID	Text to be displayed on the popup
`login1`	If you have initiated this request, please approve the login attempt to [displayablename]?
`login2`	Si vous avez initié cette demande, veuillez approuver la demande d'accès à votre compte [displayablename]
`login3`	Si ha iniciado este acceso, por favor apruebe el inicio de sesión para [displayablename]

🔗 Full URL & how to call this endpoint

Each API request must use the appropriate Base URL, combined with the endpoint path below, to form the complete request URL.

Callback (Asynchronous)iPOST https://api.global.unibeam.com/api/v1/auth/touch

Synchronous (SyncAPI)iPOST https://sapi.global.unibeam.com/api/v1/auth/touch

For more on the difference between Callback (Asynchronous) and Synchronous APIs, see Primary Terms.

POST /api/v1/auth/touch Send push notification approval challenge to the subscriber's device ▼

Request Body:

HTTP

POST /api/v1/auth/touch HTTP/1.1
customerId: xyz
Content-Type: application/json
Authorization: Bearer <token>

{
  "msisdn": "123456789",
  "cbUrl": "https://xyz.com/callback",
  "requestId": "1234",
  "templateID": "login1",
  "playTone": true,
  "rejectOnActiveCall": true
}

HTTP Status Codes: 200 OK | 400 Bad Parameters | 401 Unauthorized | 429 Too Many Requests

Request Parameters:

Parameter	Type	Required	Restrictions	Description
`requestId`	String	Required	1 to 64 chars	Unique request identifier
`cbUrl`	String	Required	Valid URL scheme, no longer than 4096 chars	URL of the callback. URL must start with https and exist in allowed domains list (unless not provided)
`msisdn`	String	Required	Number no longer than 20 digits	Phone number of end-user
`templateID`	String	Required	Not empty, max 20 chars	templateID from the predefined Auth-Touch templates translated to message text
`rejectOnActiveCall`	Boolean		true or false	True to reject flow upon an active call
`rejectOnActiveCallType`	String		One of the Enum values	If `rejectOnActiveCall` is true this is the mode: `MT` = Incoming, `MO` = Outgoing, `MOMT` = Incoming and Outgoing. Default if left blank is `MT` – Incoming
`playTone`	Boolean			Play a tone on the device before showing the message. Default `false`

ℹ️ Templates are hard-coded. Contact the Unibeam team to request changes or additions.

Response Fields:

Field	Type	Required	Description
`requestId`	String	Required	Echo of the request ID
`status`	String	Required	WAITING_FOR_RESPONSE · NOT_FOUND · IN_PROGRESS · OPTED_OUT · CONSENT_REQUIRED
`responseType`	String	Required	Always "auth/touch"

Callback Fields:

Field	Type	Required	Description
`responseType`	String	Required	Always "auth/touch"
`requestId`	String	Required	Echo of the request ID
`status`	String	Required	APPROVE · NOT_APPROVED · IGNORED · REJECTED_BY_CALL · NOT_AVAILABLE
`simIdentifier`	String	Required	Cryptographic SIM identifier
`deviceIdentifier`	String	Required	Device identifier
`lastImeiChange`	Long	Required	Timestamp of last IMEI change (ms)

JSON

{
  "responseType": "auth/touch",
  "requestId": "01JCD5Y72NFASVWKAB5XDENCD2",
  "status": "APPROVE",
  "simIdentifier": "CC31119342E6C7FC5A3B70C4C6804AAC...",
  "deviceIdentifier": "3CB5E0E1AAE5FB70719B7F409FDC0C12...",
  "lastImeiChange": 1738245013000
}

ℹ️ Callback: 3 retries unless HTTP 200 is received. Timeout: 60 seconds.

👤 User Experience & Use Cases

The Auth-Touch surfaces a SIM-level approval popup directly on the subscriber's device, returning identifiers only after the subscriber explicitly taps Approve. It is designed for two primary scenarios:

Use Cases

Login — authenticate a subscriber attempting to sign in to a web property or native app, using the SIM-bound approval as the strong factor.
Approve request as part of user journey — confirm a sensitive action mid-session (e.g., adding a payee, changing account settings, releasing a high-value action) by re-prompting the subscriber for SIM-level approval.

For the integration models (identifier-based vs. device change validation via lastImeiChange), see Primary Terms → Identifiers → Integration Options.

🧭 Prototype Flow — Subscriber Login Journey

End-to-end visual walk-through of how a subscriber experiences a Touch-protected login on an enterprise web property. The enterprise initiates the request, Unibeam pushes the approval challenge to the subscriber's SIM, and the response unlocks the session.

1

Subscriber initiates login

Web or app login screen prompts for the enterprise parameter — e.g., a username — to be authenticated by.

displayname.org/login

D

Sign in

Continue

2

Enterprise calls Auth-Touch

Server requests a SIM-bound approval challenge.

Touch endpoint

POST /api/v1/auth/touch

↓

If you have initiated this request..

3

Subscriber approves on device

Native popup is shown directly from the subscriber's SIM.

Displayname.org

UnibeamAuth

Please Approve or reject the login

Cancel

OK

4

Login completes

Enterprise validates identifiers & grants the session.

displayname.org/dashboard

✓

Signed in

Welcome back

💼 Transaction Touch

Transaction Touch allows the enterprise to send custom text popup messages to the subscriber. Unlike the standard Auth-Touch, the message content is defined per-request rather than using a fixed template. The enterprise decide on a per API which text to display on the popup

🔗 Full URL & how to call this endpoint

Each API request must use the appropriate Base URL, combined with the endpoint path below, to form the complete request URL.

Callback (Asynchronous)iPOST https://api.global.unibeam.com/api/v1/business/transaction-touch

Synchronous (SyncAPI)iPOST https://sapi.global.unibeam.com/api/v1/business/transaction-touch

For more on the difference between Callback (Asynchronous) and Synchronous APIs, see Primary Terms.

POST /api/v1/business/transaction-touch Send custom popup message to the subscriber for approval ▼

Request Body:

HTTP

POST /api/v1/business/transaction-touch HTTP/1.1
customerId: xyz
Content-Type: application/json
Authorization: Bearer <token>

{
  "msisdn": "123456789",
  "cbUrl": "https://xyz.com/callback",
  "requestId": "1234",
  "rejectOnActiveCall": true,
  "message": "Do you approve the login to xxx?"
}

HTTP Status Codes: 200 OK | 400 Bad Parameters | 401 Unauthorized | 429 Too Many Requests

Request Parameters:

Parameter	Type	Required	Description
`msisdn`	String	Required	Subscriber phone number
`cbUrl`	String	Required	Callback URL to receive the result
`requestId`	String	Required	Unique request identifier
`rejectOnActiveCall`	Boolean		True to reject flow upon an active call
`rejectOnActiveCallType`	String		If `rejectOnActiveCall` is true this is the mode: `MT` = Incoming, `MO` = Outgoing, `MOMT` = Incoming and Outgoing. Default if left blank is `MT` – Incoming
`playTone`	Boolean		Play a tone on the device before showing the message. Default `false`
`message`	String	Required	Custom message to display to the subscriber

Response Fields:

Field	Type	Required	Description
`requestId`	String	Required	Echo of the request ID
`status`	String	Required	WAITING_FOR_RESPONSE · NOT_FOUND · IN_PROGRESS · OPTED_OUT · CONSENT_REQUIRED
`responseType`	String	Required	Always "business/transaction-touch"

Callback Fields:

Field	Type	Required	Description
`responseType`	String	Required	Always "business/transaction-touch"
`requestId`	String	Required	Echo of the request ID
`status`	String	Required	APPROVE · NOT_APPROVED · IGNORED · REJECTED_BY_CALL · NOT_AVAILABLE
`simIdentifier`	String	Required	Cryptographic SIM identifier
`deviceIdentifier`	String	Required	Device identifier
`lastImeiChange`	Long	Required	Timestamp of last IMEI change (ms)

JSON

{
  "responseType": "business/transaction-touch",
  "requestId": "01JCD5Y72NFASVWKAB5XDENCD2",
  "status": "APPROVE",
  "simIdentifier": "CC31119342E6C7FC5A3B70C4C6804AAC...",
  "deviceIdentifier": "3CB5E0E1AAE5FB70719B7F409FDC0C12...",
  "lastImeiChange": 1738245013000
}

ℹ️ Callback: 3 retries unless HTTP 200 is received. Timeout: 60 seconds.

👤 User Experience & Use Cases

The Business Transaction Touch API is used for step-up authentication on high-value or sensitive transactions, where the enterprise needs to display a custom message to the subscriber and obtain explicit approval. Common scenarios:

Use Cases

Payment / fund transfer confirmation — display the recipient and amount, prompt the subscriber to approve before the transfer is executed.
Sensitive account change confirmation — confirm password resets, beneficiary changes, plan upgrades/cancellations, or address changes with a custom prompt.
Login approval request — An enterprise sends to a user popup request asking the user to approve a login. An highly secure hardware based MFA usecase.

For the integration models (identifier-based vs. device change validation via lastImeiChange), see Primary Terms → Identifiers → Integration Options.

🧭 Example — Subscriber Approves a Business Transaction

The subscriber initiates a sensitive action on an enterprise web or mobile app; the enterprise calls Business Transaction Touch with a custom message; Unibeam pushes a SIM-bound approval dialog with that message; the subscriber's approval unlocks the transaction.

1

Subscriber requests action

Web or app login screen prompts for the enterprise parameter — e.g., a username — to be authenticated by.

displayname.org/login

D

Sign in

Continue

2

Enterprise calls Business Transaction Touch

Server sends a SIM-bound challenge with a custom message.

Business Transaction Touch

POST /api/v1/business/transaction-touch

↓

{
  "msisdn": "1555…",
  "requestId": "abc",
  "message": "Approve your login",
  "cbUrl": "https://…"
}

3

Subscriber approves on device

Custom-message popup is shown directly from the subscriber's SIM.

UnibeamAuth

Approve your login

Cancel

OK

4

Transaction completes

Enterprise validates approval & executes the action.

displayname.org/dashboard

✓

Confirmed

Action approved

🔐 Business transaction Multisecure

Business transaction Multisecure grants the enterprise the ability to present a notification to the subscriber that includes a free-text input field. The field can accept numeric and/or character input, making it suitable for keyword, PIN, OTP or any entry request flows. Multisecure is not a traditional KBA. Traditional Knowledge Based Authentication simply test the knowledge "what is your favorite color", it is easy for a fraudster to know that the answer is Blue. Multisecure combines KBA and Hardware possession. To be authenticated, the user has to answer "blue" through a popup of the authenticated hardware device. Multisecure is next generation KBA MFA, it actually combines two MFAs: Knowledge answered though the Possession of an authenticated device.

🔗 Full URL & how to call this endpoint

Each API request must use the appropriate Base URL, combined with the endpoint path below, to form the complete request URL.

Callback (Asynchronous)iPOST https://api.global.unibeam.com/api/v1/business/transaction-multisecure

Synchronous (SyncAPI)iPOST https://sapi.global.unibeam.com/api/v1/business/transaction-multisecure

For more on the difference between Callback (Asynchronous) and Synchronous APIs, see Primary Terms.

POST /api/v1/business/transaction-multisecure Present notification with free-text input (PIN / OTP confirmation) ▼

Request Body:

HTTP

POST /api/v1/business/transaction-multisecure HTTP/1.1
customerId: xyz
Content-Type: application/json
Authorization: Bearer <token>

{
  "msisdn": "123456789",
  "cbUrl": "https://xyz.com/callback",
  "requestId": "1234",
  "message": "What is the middle name of your oldest cousin?",
  "rejectOnActiveCall": true,
  "playTone": false
}

HTTP Status Codes: 200 OK | 400 Bad Parameters | 401 Unauthorized | 429 Too Many Requests

Request Parameters:

Parameter	Type	Required	Description
`msisdn`	String	Required	Subscriber phone number
`cbUrl`	String	Required	Callback URL to receive the result
`requestId`	String	Required	Unique request identifier
`message`	String	Required	Prompt message displayed to the subscriber
`messageInputTypes`	Integer	Required	Input field type (0–7). See Message Input Types for the full list.
`rejectOnActiveCall`	Boolean		True to reject flow upon an active call
`rejectOnActiveCallType`	String		If `rejectOnActiveCall` is true this is the mode: `MT` = Incoming, `MO` = Outgoing, `MOMT` = Incoming and Outgoing. Default if left blank is `MT` – Incoming
`playTone`	Boolean		Play a tone on the device before showing the message. Default `false`

Response Fields:

Field	Type	Required	Description
`requestId`	String	Required	Echo of the request ID
`status`	String	Required	WAITING_FOR_RESPONSE · NOT_FOUND · IN_PROGRESS · OPTED_OUT · CONSENT_REQUIRED
`responseType`	String	Required	Always "business/transaction-multisecure"

Callback Fields:

Field	Type	Required	Description
`responseType`	String	Required	Always "business/transaction-multisecure"
`requestId`	String	Required	Echo of the request ID
`status`	String	Required	WAITING_FOR_RESPONSE · NOT_FOUND · IN_PROGRESS · OPTED_OUT · CONSENT_REQUIRED
`inputText`	String	Required	Free-text input entered by the subscriber
`simIdentifier`	String	Required	Cryptographic SIM identifier
`deviceIdentifier`	String	Required	Device identifier
`lastImeiChange`	Long	Required	Timestamp of last IMEI change (ms)

JSON

{
  "responseType": "business/transaction-multisecure",
  "requestId": "01JCD5Y72NFASVWKAB5XDENCD2",
  "status": "APPROVE",
  "inputText": "marie",
  "simIdentifier": "CC31119342E6C7FC5A3B70C4C6804AAC...",
  "deviceIdentifier": "3CB5E0E1AAE5FB70719B7F409FDC0C12...",
  "lastImeiChange": 1741350403000
}

ℹ️ Callback: 3 retries unless HTTP 200 is received. Timeout: 60 seconds.

👤 User Experience & Use Cases

The Multisecure API extends the SIM-based approval popup with a free-text input field, allowing the enterprise to challenge the subscriber for a value (numeric and/or alphanumeric) directly from the SIM-pushed dialog. Typical use cases include:

Use Cases

Login with a prompted code — the enterprise issues a one-time code (OTP) and asks the subscriber to type it back into the SIM-level popup, confirming both possession of the SIM and knowledge of the code.
Change subscription or transfer a small amount of money — the subscriber confirms a change-of-plan or low-value funds transfer by entering a short PIN inside the popup, providing a SIM-bound second factor without leaving the merchant flow.
Login or transaction validation using an explicit known question — the popup poses a question the subscriber should know the answer to (e.g., code given by a callcenter agent on the phone with the user ) and validates the typed answer against the enterprise's expectations.

For the integration models (identifier-based vs. device change validation via lastImeiChange), see Primary Terms → Identifiers → Integration Options.

🧭 Example — A subscriber answers a challenge and possesion question

End-to-end visual walk-through of how a subscriber experiences a Multisecure-protected action. The enterprise initiates the request with a custom prompt, Unibeam pushes the input dialog to the subscriber's SIM, and the entered value is returned to the enterprise for verification.

1

Subscriber initiates action

Web or app login screen prompts for the enterprise parameter — e.g., a username — to be authenticated by.

displayname.org/login

D

Sign in

Continue

2

Enterprise calls Multisecure API

Server requests a SIM-bound input challenge.

Multisecure endpoint

POST /api/v1/business/transaction-multisecure

↓

{
  "msisdn": "1555…",
  "requestId": "abc",
  "message": "what is the middle name of your oldest cousin?",
  "messageInputTypes": 0,
  "cbUrl": "https://…"
}

3

Subscriber enters value on device

Native popup with an input field is shown directly from the subscriber's SIM.

UnibeamAuth

What is the middle name of your oldest cousin?

••••

Cancel

OK

4

Action completes

Enterprise validates the entered value & SIM identifiers, then grants the action.

displayname.org/dashboard

✓

Confirmed

Welcome back

☑️ Transaction Multiselect API

Transaction Multiselect grants the enterprise the ability to present a notification to the subscriber containing a multiple-choice question. The subscriber selects one option from the list. Multiselect is not a traditional KBA. Traditional Knowledge Based Authentication simply test the knowledge "what is your favorite color", it is easy for a fraudster to know that the answer is Blue. Multiselect combines KBA and Hardware possession. To be authenticated, the user has to select "blue" among various options through a popup of the authenticated hardware device. Multiselect is next generation KBA MFA, it actually combines two MFAs: Knowledge answered though the Possession of an authenticated device.

🔗 Full URL & how to call this endpoint

Each API request must use the appropriate Base URL, combined with the endpoint path below, to form the complete request URL.

Callback (Asynchronous)iPOST https://api.global.unibeam.com/api/v1/business/select-item

Synchronous (SyncAPI)iPOST https://sapi.global.unibeam.com/api/v1/business/select-item

For more on the difference between Callback (Asynchronous) and Synchronous APIs, see Primary Terms.

POST /api/v1/business/select-item Present a multiple-choice question to the subscriber ▼

Request Body:

HTTP

POST /api/v1/business/select-item HTTP/1.1
customerId: xyz
Content-Type: application/json
Authorization: Bearer <token>

{
  "msisdn": "123456789",
  "cbUrl": "https://xyz.com/callback",
  "requestId": "1234",
  "menuHeader": "Choose your preferred language",
  "menuItems": [
    { "id": 1, "text": "English" },
    { "id": 2, "text": "French" },
    { "id": 3, "text": "Spanish" }
  ]
}

HTTP Status Codes: 200 OK | 400 Bad Parameters | 401 Unauthorized | 429 Too Many Requests

Request Parameters:

Parameter	Type	Required	Description
`msisdn`	String	Required	Subscriber phone number
`cbUrl`	String	Required	Callback URL to receive the result
`requestId`	String	Required	Unique request identifier
`menuHeader`	String	Required	Question/header text displayed to the subscriber
`menuItems`	Array	Required	List of options: each item has id (integer) and text (string)
`rejectOnActiveCall`	Boolean		True to reject flow upon an active call
`rejectOnActiveCallType`	String		If `rejectOnActiveCall` is true this is the mode: `MT` = Incoming, `MO` = Outgoing, `MOMT` = Incoming and Outgoing. Default if left blank is `MT` – Incoming
`playTone`	Boolean		Play a tone on the device before showing the message. Default `false`

Response Fields:

Field	Type	Required	Description
`requestId`	String	Required	Echo of the request ID
`status`	String	Required	WAITING_FOR_RESPONSE · NOT_FOUND · IN_PROGRESS · OPTED_OUT · CONSENT_REQUIRED · NOT_SUPPORTED
`responseType`	String	Required	Always "business/select-item"

Callback Fields:

Field	Type	Required	Description
`responseType`	String	Required	Always "business/select-item"
`requestId`	String	Required	Echo of the request ID
`status`	String	Required	APPROVE · REJECT · TIMEOUT · NOT_FOUND
`selectedItemId`	Integer	Required	The id of the option selected by the subscriber

👤 User Experience & Use Cases

The Multiselect API extends the SIM-based approval popup with a multiple-choice question, allowing the enterprise to challenge the subscriber with a list of options. The main use is to level up the enterprise's assurance of identifying their subscribers — the questions and selectable answers can be changed for each subscriber and varied each time, so an attacker who has obtained the subscriber's credentials cannot anticipate or replay an answer. Typical use cases include:

Use Cases

Validation by one option prompt on the app or web page with the subscriber — the enterprise web/app screen displays one prompt to the subscriber, and the SIM-pushed popup asks them to pick the same value from a list of options. Matching the answer the subscriber made on-screen confirms both possession of the SIM and active presence in the session.
Validation by a unique question using enterprise internal information of the subscriber — e.g., financial (last transaction amount, purchase of united ticket in May, March, January or not in the last 6 months), usage (most-used service this month, last device used), or temporal (last time of login, last time of password change). Because the answer comes from data only the enterprise and the subscriber know, this provides a strong knowledge-based factor on top of the SIM-bound channel.

For the integration models (identifier-based vs. device change validation via lastImeiChange), see Primary Terms → Identifiers → Integration Options.

🧭 Example — Subscriber Multiselect Journey

End-to-end visual walk-through of how a subscriber experiences a Multiselect-protected action. The enterprise initiates the request with a custom question and option list, Unibeam pushes the menu to the subscriber's SIM, and the chosen option is returned to the enterprise for verification.

1

Subscriber initiates action

Web or app login screen prompts for the enterprise parameter — e.g., a username — to be authenticated by.

displayname.org/login

D

Sign in

Continue

2

Enterprise calls Multiselect API

Server requests a SIM-bound multiple-choice challenge.

Multiselect endpoint

POST /api/v1/business/select-item

↓

{
  "msisdn": "1555…",
  "requestId": "abc",
  "menuHeader": "Your last login was…",
  "menuItems": [ Today, Yesterday, last month… ],
  "cbUrl": "https://…"
}

3

Subscriber picks an option on device

Native popup with a list of options is shown directly from the subscriber's SIM.

Displayname.org

UnibeamAuth

You last login was?

Today

Yesterday

Last week

Earlier

Cancel

OK

4

Action completes

Enterprise validates the chosen option against its records, then grants the action.

displayname.org/dashboard

✓

Confirmed

Welcome back

📞 Branded Calls API

The Branded Calls API enables the enterprise to place an outbound call to the subscriber with a verified caller-ID and branded display (company name, logo, reason for call). The subscriber's response is delivered asynchronously to the callback URL.

🔗 Full URL & how to call this endpoint

Each API request must use the appropriate Base URL, combined with the endpoint path below, to form the complete request URL.

Callback (Asynchronous)iPOST https://api.global.unibeam.com/api/v1/business/branded-call

Synchronous (SyncAPI)iPOST https://sapi.global.unibeam.com/api/v1/business/branded-call

For more on the difference between Callback (Asynchronous) and Synchronous APIs, see Primary Terms.

POST /api/v1/business/branded-call Place a branded, verified call to the subscriber ▼

HTTP Status Codes: 200 OK | 400 Bad Parameters | 401 Unauthorized | 429 Too Many Requests

Request Parameters:

Parameter	Type	Required	Description
`msisdn`	String	Required	Subscriber phone number
`cbUrl`	String	Required	Callback URL to receive the result
`requestId`	String	Required	Unique request identifier
`brandName`	String	Required	Display name shown to the subscriber
`reason`	String		Optional reason-for-call text

Response Fields:

Field	Type	Required	Description
`requestId`	String	Required	Echo of the request ID
`status`	String	Required	WAITING_FOR_RESPONSE · NOT_FOUND · IN_PROGRESS · OPTED_OUT · CONSENT_REQUIRED · NOT_SUPPORTED
`responseType`	String	Required	Always "business/branded-call"

Callback Fields:

Field	Type	Required	Description
`responseType`	String	Required	Always "business/branded-call"
`requestId`	String	Required	Echo of the request ID
`status`	String	Required	APPROVE · NOT_APPROVED · IGNORED · REJECTED_BY_CALL · NOT_AVAILABLE

ℹ️ Callback: 3 retries unless HTTP 200 is received. Timeout: 60 seconds.

👤 User Experience & Use Cases

User experience flows and use cases for the Branded Calls API will be documented here.

✨ Additional Features

Optional add-on capabilities that can be layered onto any authentication model to enrich the transaction context and improve fraud detection.

📞 Call State – Reject on Active Call

When enabled, if a subscriber is on an active phone call at the moment of an authentication request, the notification is suppressed and the authentication is automatically rejected. This prevents voice-phishing (vishing) attacks and scams.

How to enable:

Add "rejectOnActiveCall": true to any Auth-Touch, Business Transaction Touch, Business Transaction Multisecure, or Business Transaction Multiselect request body.

When rejectOnActiveCall: true is set:

If the subscriber is not on a call → the notification is delivered normally.
If the subscriber is on an active call → the notification is suppressed, and the callback returns REJECTED_BY_CALL.

📍 Location 🚧 Work in Progress · On Dev Roadmap

🚧

Under development roadmap. The Location feature is not generally available yet, as a flag to be set to Unibeam live APIs.

The Location feature allows the enterprise to retrieve the subscriber's current country and city cellId directly from the SIM applet at the time of an authentication event.

How to enable:

Add "includeLocation": true to any Business Transaction Touch, Business Transaction Multisecure, or Silent API request body.

📡 Signals Auth

The Signals Auth API provides real-time signals from the SIM (e.g. SIM Status, Identifiers & LastImeiChange, Call State and Location) without invoking a separate authentication flow.

🔗 Full URL & how to call this endpoint

Each API request must use the appropriate Base URL, combined with the endpoint path below, to form the complete request URL.

Callback (Asynchronous)iPOST https://api.global.unibeam.com/api/v1/auth/signals

Synchronous (SyncAPI)iPOST https://sapi.global.unibeam.com/api/v1/auth/signals

For more on the difference between Callback (Asynchronous) and Synchronous APIs, see Primary Terms.

POST /api/v1/auth/signals Retrieve real-time SIM signals — identifiers, call state, location — without prompting the subscriber ▼

Request Body:

HTTP

POST /api/v1/auth/signals HTTP/1.1
customerId: xyz
Content-Type: application/json
Authorization: Bearer <token>

{
  "msisdn": "123456789",
  "cbUrl": "https://xyz.com/callback",
  "requestId": "1"
}

HTTP Status Codes: 200 OK | 400 Bad Parameters | 401 Unauthorized | 429 Too Many Requests

Request Parameters:

Parameter	Type	Required	Restrictions	Description
`requestId`	String	Required	1 to 64 chars	Unique request identifier
`cbUrl`	String	Required	Valid URL scheme, no longer than 4096 chars	URL of the callback. Must start with `https` and exist in the allowed-domains list (unless not provided).
`msisdn`	String	Required	No longer than 20 digits	Phone number of the end-user

Response Fields:

Field	Type	Required	Description
`requestId`	String	Required	Echo of the request ID
`status`	String	Required	WAITING_FOR_RESPONSE · NOT_FOUND · IN_PROGRESS · OPTED_OUT · CONSENT_REQUIRED · NOT_SUPPORTED
`responseType`	String	Required	Always "auth/signals"

Callback Fields:

Field	Type	Required	Description
`responseType`	String	Required	Always "auth/signals"
`requestId`	String	Required	Echo of the request ID
`status`	String	Required	VALID · NOT_AVAILABLE
`simIdentifier`	String	—	Unique cryptographic SIM identifier
`deviceIdentifier`	String	—	Unique device identifier
`lastImeiChange`	Long	—	Last detected IMEI change (Unix UTC, ms)
`activeCallType`	String	Required	UNAVAILABLE (unable to determine) · MT (incoming) · MO (outgoing) · NONE (no active call)
`locationInfo`	JSON	—	Optional location info (omitted if the applet is unable / not configured to access this information)

locationInfo object:

Field	Type	Required	Description
`country`	JSON	—	Country section (see below)
`coarseLocation`	JSON	—	Coarse location section (see below)

country object:

Field	Type	Required	Description
`iso`	String	—	ISO country code (e.g. IL, US)
`name`	String	—	Country name (e.g. Israel, United States)
`code`	Integer	—	Country calling code (e.g. 972, 1)

coarseLocation object:

Field	Type	Required	Description
`cellId`	Long	Required	Cell identifier from the network (raw or normalized format)
`lat`	Double	—	Latitude of the estimated location
`lon`	Double	—	Longitude of the estimated location
`map`	String	—	Google Maps link: `https://www.google.com/maps/search/{lat},{lon}`

JSON

{
  "responseType": "auth/signals",
  "requestId": "01JCD5Y3QN8XV8TX175WB7V6AS",
  "status": "VALID",
  "simIdentifier": "3C8DC580C0EF80F029D4B18951BB35771D4873640B07544902B1AB7E560CFEB5",
  "deviceIdentifier": "F6475784840D2C1BC2F72577FACC83AABB788902E7EB7388207CF6C54A53048C",
  "lastImeiChange": 1738245013000,
  "activeCallType": "NONE",
  "locationInfo": {
    "country": { "iso": "IL", "name": "Israel", "code": 972 },
    "coarseLocation": {
      "cellId": 23456789,
      "lat": 32.0853,
      "lon": 34.7818,
      "map": "https://www.google.com/maps/search/32.0853,34.7818"
    }
  }
}

ℹ️ Callback: 3 retries unless HTTP 200 is received. If a callback response is not received within 10 seconds, it may indicate the SIM is unreachable — phone powered off or experiencing a connectivity issue.

👤 User Experience & Use Cases

Signals Auth runs entirely in the background — no popup, no prompt, no tap from the subscriber. The SIM applet returns identifiers, call state, and (when available) coarse location to the enterprise as part of a silent verification.

Use Cases

A silent login to apps with high sensitivity — for apps where any visible prompt would create friction or risk (e.g., banking, brokerage, healthcare), the enterprise resolves the SIM/device identifiers and call/location signals silently to grant the session, with strong assurance the user phone is in a location authorized and/or safe to login.
A silent auth as part of validating an abnormal purchase — when a fintech fraud heuristics flags a risk transaction, the fintech uses Signals Auth to confirm the subscriber phone is at the same location where the purchase is taking place (location signal). If for instance the Use relocation returns New York City and the purchase Point Of Sale request is Seatle or abroad, the fintech can cancel the purchase request or trigger a step-up verification with a Business Transaction Touch to get user approval.

For the integration models (identifier-based vs. device change validation via lastImeiChange), see Primary Terms → Identifiers → Integration Options.