Mobile Number Management

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Creating and verifying a mobile number is a mandatory step in the customer onboarding process. 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.

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 (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.

Lifecycle management

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

Request URL

POST /v1/persons/{person_id}/mobile_number

Request example

{
  "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.

{
    "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

Request URL

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

Request example

{
  "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

Request URL

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

Request example

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

Response example

{
    "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. This triggers a 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.

Webhooks

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

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

Explore the full technical definition for the mobile number resource.