# Mobile Number Management

Creating and verifying a mobile number is a mandatory step in the [customer onboarding process](/guides/get-started/digital-banking/onboard-person#step-2-create-and-verify-mobile-number). A verified mobile number enables customers to receive **SMS OTPs** (One-Time Passwords) required for **Two-Factor Authentication (2FA)** and sensitive account actions.

This guide explains how to manage the `mobile_number` resource and lists the standardized SMS content Solaris sends to your customers.

Mandatory Requirement
A verified mobile number is **required** for all customers across all branches (DE, FR, IT, ES) to comply with [PSD2 Strong Customer Authentication (SCA)](/guides/authentication/strong-customer-authentication).

## Data model & storage

Solaris stores mobile numbers as a dedicated **`mobile_number` resource**, separate from the `person` resource. This design allows for strict validation and lifecycle management.

### Key constraints

1. **Uniqueness:** A person can have only **one** verified mobile number at a time.
2. **Format:** Solaris strictly validates numbers against the [E.164 standard](https://en.wikipedia.org/wiki/E.164) (e.g., `+491512345678`).
3. **Sanitization:** The API automatically sanitizes input. Always use the formatted number returned in the API response, not the raw user input.


Integration Pitfall
The `person` resource contains a legacy attribute also named `mobile_number`.
**Do not use this attribute.** It is not linked to the verified `mobile_number` resource and cannot be used for SCA. Always interact with the `mobile_number` endpoints.

## Lifecycle management

Sandbox Testing
To test the following authorization flow on the Sandbox environment, use these static values:

- Mobile number: `+15550101`
- SMS OTP: `212212`


### Add a mobile number

To attach a mobile number to a customer, follow this authorize-confirm flow.

#### 1. Create mobile number

Collect the customer's mobile number in your frontend and pass it to Solaris. You must include the customer's `person_id` in the request URL.

**API Reference:** [POST Create mobile number](/api-reference/onboarding/persons/person-mobile-numbers/paths/~1v1~1persons~1%7Bperson_id%7D~1mobile_number/post)

**Request URL**


```shell
POST /v1/persons/{person_id}/mobile_number
```

**Request example**


```json
{
  "number": "+15550101"
}
```

**Response example**
The API returns a `mobile_number` resource with a unique `id` and attaches it to the `person` resource. The status is initially `verified: false`.


```json
{
    "id": "91e4d939d781b8eb30d1ee86809761c2cmno",
    "number": "+15550101",
    "verified": false
}
```

#### 2. Authorize mobile number

Verify the ownership of the provided mobile phone number. This endpoint initiates the OTP flow: Solaris sends a six-digit OTP to the customer's number, which they must enter in your UI.

**API Reference:** [POST Authorize mobile number](/api-reference/onboarding/persons/person-mobile-numbers/paths/~1v1~1persons~1%7Bperson_id%7D~1mobile_number~1authorize/post)

**Request URL**


```shell
POST /v1/persons/{person_id}/mobile_number/authorize
```

**Request example**


```json
{
  "number": "+15550101"
}
```

#### 3. Confirm mobile number

Submit the SMS OTP the customer received to finalize the authorization process. Pass the customer's `number` and `token` (the SMS OTP) in the request body. The mobile number becomes `verified` and ready for SCA.

**API Reference:** [POST Confirm mobile number](/api-reference/onboarding/persons/person-mobile-numbers/paths/~1v1~1persons~1%7Bperson_id%7D~1mobile_number~1confirm/post)

**Request URL**


```shell
POST /v1/persons/{person_id}/mobile_number/confirm
```

**Request example**


```json
{
  "number": "+15550101",
  "token": "212212"
}
```

**Response example**


```json
{
    "id": "91e4d939d781b8eb30d1ee86809761c2cmno",
    "number": "+15550101",
    "verified": true
}
```

### Change a mobile number

Mobile numbers are immutable once verified. To update a number, you must delete the existing one and create a new one.

1. **Delete:** Call [`DELETE Remove mobile number`](/api-reference/onboarding/persons/person-mobile-numbers/paths/~1v1~1persons~1{person_id}~1mobile_number/delete). This triggers a [Change Request](/guides/authentication/strong-customer-authentication#change-request) process (often requiring 2FA if the user is already active).
2. **Re-create:** Repeat the Add a mobile number flow with the new number.


Customer Support
If a customer has lost their device and cannot complete 2FA to authorize the deletion, they must contact Customer Support for a manual reset.

## Webhooks

Subscribe to these events to sync your local database with the mobile number status.

| Event | Description |
|  --- | --- |
| [`PERSON_MOBILE_NUMBER_CREATED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_mobile_number_created/post) | A mobile number resource was created but is **not yet verified**. |
| [`PERSON_MOBILE_NUMBER_DELETED`](/api-reference/onboarding/webhooks/webhook-events/paths/person_mobile_number_deleted/post) | A customer's mobile number was successfully removed. 2FA is now disabled for this customer until a new number is verified. |


## Appendix: SMS templates

Solaris sends standardized SMS messages for specific events. You **cannot** customize these texts, as they adhere to strict compliance and security standards.

**Localization:**
Solaris automatically selects the language (EN, DE, FR, IT, ES) based on the customer's [Language Settings](/api-reference/onboarding/persons/person-language-settings).

| Case | English (EN) | German (DE) | French (FR) | Italian (IT) | Spanish (ES) |
|  --- | --- | --- | --- | --- | --- |
| **Verify mobile number** | Please verify your mobile number with the following SMS OTP: `OTP` | Bitte verifizieren Sie Ihre Handynummer mit folgender TAN: `OTP` | Veuillez confirmer votre numéro de portable avec le code OTP suivant : `OTP` | La preghiamo di verificare il Suo numero di cellulare usando il seguente SMS OTP: `OTP` | Verifique su número de móvil con el siguiente SMS OTP: `OTP` |
| **Authenticate (2FA)** | `OTP` is your OTP for authorization | `OTP` ist Ihre OTP zur Autorisierung | Voici votre code OTP `OTP` pour l'autorisation | Il codice per confermare il Suo numero di telefono è: `OTP` | `OTP` es su OTP para la autorización. |
| **Confirm Deletion** | To verify you would like to delete the mobile number you have on file, use the following SMS OTP: `OTP` | Um die Löschung Ihrer Handynummer freizugeben, nutzen Sie bitte folgende TAN: `OTP` | Veuillez utiliser le code OTP suivant afin de confirmer la suppression de votre numéro de portable : `OTP` | Per confermare la Sua intenzione di cancellare il numero di cellulare registrato usare il seguente codice OTP: `OTP` | Para verificar que desea eliminar el número de móvil que tiene archivado, utilice el siguiente SMS OTP: `OTP` |
| **Deleted Notification** | Your mobile number `number` has been removed and can no longer be used for SMS OTP authentication | Ihre Handynummer `number` wurde entfernt und kann nicht mehr für das TAN-Verfahren genutzt werden | Votre numéro de portable `number` a été supprimé | Il Suo numero di cellulare `number` è stato rimosso e non puó piú essere usato per l'autentificazione codice OTP | Su número de móvil `number` ha sido eliminado y ya no puede ser utilizado para la autenticación de sms tan |
| **Changed Notification** | Your mobile number `old_number` has been replaced by `new_number` | Ihre Handynummer `old_number` wurde durch `new_number`s ersetzt | Votre numéro de portable `old_number`s a été remplacé par le numéro `new_number`s | Il Suo numero di cellulare `old_number`s è stato sostituito con `new_number`s | Su número de móvil `old_number` ha sido sustituido por `new_number` |
| **Data Change (General)** | To authorize the data change, please use the following SMS OTP: `OTP` | Um die Datenänderung freizugeben, nutzen sie bitte folgende TAN: `OTP` | Utilisez le code OTP suivant afin de confirmer le changement des données : `OTP` | Per autorizzare la modifica dei dati usare il seguente codice OTP: `OTP` | Para autorizar el cambio de datos, por favor use el siguiente SMS OTP: `OTP` |
| **Account Closure** | To complete the account closure of `iban`, use the following SMS OTP: `OTP` | Um die Kontoschließung von `iban` freizugeben, nutzen Sie bitte folgende TAN: `OTP` | Afin de confirmer la fermeture du compte ayant pour IBAN `iban`, utilisez le code OTP suivant : `OTP` | Per completare il processo di chiusura per `iban` usare il seguente codice OTP: `OTP` | Para completar el cierre de la cuenta `iban`, use el siguiente SMS OTP: `OTP` |
| **Add Legal Representative** | To add `name` as a legal representative on your account `iban`, use the following SMS OTP: `OTP` | Um `name` als Verfügungsberechtigten zu Ihrem Konto `iban` hinzuzufügen, nutzen Sie bitte folgende TAN: `OTP` | Afin d'autoriser `name` à réaliser des opérations sur le compte `iban`, utilisez le code OTP suivant : `OTP` | Per aggiungere `name` come rappresentante legale sul tuo conto `iban` usare il seguente codice OTP: `OTP` | Para añadir `name` como representante legal en su cuenta `iban`, use el siguiente SMS OTP: `OTP` |
| **Unauthorized Biz Change** | There must be at least one legal representative person with a confirmed mobile number present | - 
 | La présence d'au moins un représentant légal avec un numéro de téléphone mobile confirmé est requise. | - 
 | Debe haber al menos una persona representante legal con un número de móvil confirmado. |
| **SEPA Transaction** | To complete the payment for `iban` of `amount`, use the following SMS OTP: `OTP` | Um die Überweisung von `amount` auf IBAN `iban` freizugeben, nutzen Sie bitte folgende TAN: `OTP` | Afin d'activer le paiement de `amount` depuis le compte `iban`, utilisez le code OTP suivant : `OTP` | Per completare il pagamento per `iban` dell'importo di `amount` usare il seguente codice OTP: `OTP` | Para completar el pago de `iban` de `amount`, use el siguiente SMS OTP: `OTP` |
| **Batch SEPA Transaction** | To complete the batch transaction of `count` transactions with a cumulative value of `amount`, use the following SMS OTP: `OTP` | Um die Sammelüberweisung von `count` Transaktion über `amount` freizugeben, nutzen Sie bitte folgende TAN: `OTP` | Afin d'autoriser l'ensemble des `count` virements d'un montant total de `amount`, utilisez le code OTP suivant : `OTP` | Per completare il gruppo di transazioni per i seguenti conti `count` del valore cumulativo di `amount` usare il seguente codice OTP: `OTP` | Para completar la transacción por grupo de las transacciones `count` con un valor acumulativo de `amount`, use el siguiente SMS OTP: `OTP` |
| **Create Standing Order** | To issue the standing order of `amount` for account `iban`, use the following SMS OTP: `OTP` | Um den Dauerauftrag von `amount` auf IBAN `iban` freizugeben, nutzen Sie bitte folgende TAN: `OTP` | Afin d'autoriser l'ordre de virement permanent d'un montant de `amount` vers le compte `iban`, utilisez le code OTP suivant : `OTP` | Per procedere con l'ordine di pagamento permanente dell'importo di `amount` per `iban` usare il seguente codice OTP: `OTP` | Para emitir la orden permanente de `amount` para la cuenta `iban`, use el siguiente SMS OTP: `OTP` |
| **Cancel Standing Order** | To delete the standing order of `amount` for account `iban`, use the following SMS OTP: `OTP` | Um die Löschung des Dauerauftrags von `amount` auf IBAN `iban` freizugeben, nutzen Sie bitte folgende TAN: `OTP` | Afin d'autoriser l'ordre de virement permanent d'un montant de `amount` vers le compte `iban`, utilisez le code OTP suivant : `OTP` | Per annullare l'ordine di pagamento permanente dell'importo di `amount` per `iban` usare il seguente codice OTP: `OTP` | Para emitir la orden permanente de `amount` para la cuenta `iban`, use el siguiente SMS OTP: `OTP` |
| **Update Standing Order** | To change the standing order of `amount` for account `iban`, use the following SMS OTP: `OTP` | Um die Änderung des Dauerauftrags von `amount` auf IBAN `iban` freizugeben, nutzen Sie bitte folgende TAN: `OTP` | Afin de confirmer la modification du virement permanent d'un montant de `amount` vers le compte `iban`, utilisez le code OTP suivant : `OTP` | Per modificare l'ordine di pagamento permanente dell'importo di `amount` per `iban` usare il seguente codice OTP: `OTP` | Para cambiar la orden permanente de `amount` para la cuenta `iban`, use el siguiente SMS OTP: `OTP` |
| **Timed Order** | To issue the timed order of `amount` for account `iban`, use the following SMS OTP: `OTP` | Um die Terminüberweisung von `amount` auf IBAN `iban` freizugeben, nutzen sie bitte folgende TAN: `OTP` | Afin d'activer l'ordre de virement d'un montant de `amount` vers le compte `iban`, utilisez le code OTP suivant : `OTP` | Per generare l'ordine di pagamento temporaneo di `amount` per `iban` usare il seguente codice OTP: `OTP` | Para emitir la transferencia programada de `amount` para la cuenta `iban`, use el siguiente SMS OTP: `OTP` |
| **3DS Online Purchase** | Use code `passcode` to authenticate your purchase of `amount` `currency` at `merchant` | Nutzen Sie den Code `passcode` um die Überweisung von `amount` `currency` an `merchant` zu authorisieren | Utilisez le code `passcode` pour authentifier votre achat de `amount` `currency` chez `merchant` | Usa il codice `passcode` per autenticare il tuo acquisto di `amount` `currency` presso `merchant` | Utilice el código `passcode` para autenticar su compra de `amount` `currency` en `merchant` |
| **Apple/Google Pay** | Your one-time verification code to add your card to `Wallet_Name` is `code`. The code will expire in 30 minutes. | Ihr einmaliger Bestätigungscode um Ihrer Karte zu `Wallet_Name` hinzuzufügen lautet `code`. Der Code läuft in 30 Minuten ab. | Votre code de vérification à usage unique pour ajouter votre carte à `Wallet_Name` est le `code`. Ce code expirera dans 30 minutes. | Il tuo codice di verifica una tantum per aggiungere la tua carta a `Wallet_Name` è `code`. Il codice scadrà tra 30 minuti. | Su código de verificación único para agregar su tarjeta a `Wallet_Name` es `code`. El código caducará en 30 minutos. |


## API Reference

Explore the full technical definition for the mobile number resource.

Person Mobile Numbers
View all endpoints for creating, retrieving, and verifying mobile numbers.