Set up SMS provider

To send a verification or authentication SMS to your users, you must have an SMS provider solution. Purse Identity provides Twilio as the default solution. However, you can use any SMS provider solution that you wish.

SMS Prerequisites

  • You must have access to the Purse Identity Console.

  • You must have the SMS feature enabled.

  • You must have an SMS provider account.

    Please contact support if you do not see SMS enabled.

Set up Twilio

Twilio

  1. Log in to your Twilio account.

  2. From your Twilio console dashboard, copy your Account SID, Auth Token, and My Twilio phone number.

    This is typically found on your Project’s home page, under Account Info.

    Expand to see visual.

    account info
Purse Identity Console

  1. Go to Settings  SMS  Providers and choose Twilio from the Client type dropdown.

  2. Enter your Twilio Account SID.

  3. Enter your Twilio Auth Token.

  4. Enter the phone number from your Twilio Account that you configured to be your sender.

    By default, Twilio assigns you a number. However, you can configure your own number to be used if so desired.

  5. Type something and click the Send Test SMS button.

    You might have a local test server to see these messages.

  6. Don’t forget to Save your input.

    Expand to see visual.

    console twilio

Set up Custom SMS provider

Custom message payload forward compatibility

We sometimes enhance our services by adding new variables and fields to custom Email and SMS payloads.

To ensure your integration remains stable:

  • Do not use strict schema validation on the JSON payloads received from Purse Identity.

  • Ignore unknown fields: Your integration must be designed to gracefully ignore any variables or keys it does not recognize.

Failure to follow this practice may cause your service to break when new features are released. This approach ensures that your integration continues to function correctly even as we introduce new features and enhancements.

Instructions

  1. Go to Settings  SMS  Providers and choose Custom SMS Provider from the Client type dropdown.

  2. Enter the endpoint for your custom provider’s SMS API.

  3. Enter the HTTP Authorization value (if applicable).

    If the API uses a non-standard authorization header, ensure you tick the Use non-standard name for the Authorization header box and enter the header name.

  4. Under Fields, choose which keys are sent in personalizations. The same list is used for every template.

    Fields groups keys into Standard fields, Message fields, and Custom fields. In the dropdown those groups are headed Profile Fields, Message Fields, and Custom Fields. Standard fields and Message fields start selected. Custom fields stay unselected until you add them. phone_number and template_id are always sent, and they are not in this list. An empty Fields list sends only those two keys. A provider saved before this change keeps the fields it already sent, plus any custom fields you had already selected. A selected custom_fields entry is sent only when that field is present on the profile. The SMS list does not include email-only keys such as client_id, verification_code, redirect_url, lockout_end_date, or device metadata.

  5. Select the Send Test SMS button.

  6. Don’t forget to Save your input.

Select the endpoint where you would like Purse Identity to send requests

An example request and payload are as follows. This sample is one possible Fields selection. personalizations includes only the keys you selected. A selected key is omitted when that template has no value for it. phone_number and template_id are always sent.

POST https://YOUR_DOMAIN

{
  "phone_number": "+33688888884",
  "template_id": "password_reset", (1)
  "personalizations": {
     "id": "id",
     "external_id": "externalId",
     "given_name": "Max",
     "last_name": "Robertson",
     "gender": "M",
     "sms_code": "smsCode",
     "lang": "fr",
     "locale": "fr-FR",
     "has_password": true, (2)
   }
}
1 The template_id is the SMS template. This is the ID for the template found at Settings  SMS  Templates or alternatively for MFA at Settings  MFA  sms templates.
2 The has_password value is included only for the password_reset template, and only when you selected that field.

The has_password boolean gives custom providers the option to let users create a password.

  • true: The user already has a password; the user should be asked to reset the existing password.

  • false: The user does not have a password associated with their account; the user should be asked to create a password.

Custom personalization fields

These are the personalizations keys you can select under Fields. The Purse Identity Console groups them into Standard fields (profile data), Message fields (values from the message), and Custom fields. Purse Identity sends a selected key only when that template has a value for it.

SMS

Standard fields

  • id

  • external_id

  • given_name

  • last_name

  • gender

  • has_password

  • lite_only

Message fields

  • sms_code

  • link

  • lang

  • locale

  • action

  • accept_url

  • reject_url

  • consent_title

  • consent_description

Custom fields

  • custom_fields*

* custom_fields are the custom fields you select. They are sent as an object, and only when they are present on the profile.

Retry policy

When Purse Identity cannot deliver a message through your provider, it retries automatically before giving up.

This policy applies to the following templates:

Purse Identity makes up to 4 delivery attempts: one initial attempt, then 3 retries. After each failed attempt, Purse Identity waits 10 seconds before trying again. Each failed attempt creates an sms_failure user event.

See User events for event fields and a sample payload.
Other transactional messages (such as signup verification or MFA codes) are sent once. If delivery fails, a single failure event is still emitted.
AI Assistant
The Purse Identity AI assistant can make mistakes, verify answers.

Confirm Deletion