SMS Templates

The SMS Templates API provides operations to manage custom SMS templates for verification.

Note: Only SMS custom Templates are available through the API.

SMS Templates customize the SMS message that is sent to users. One default SMS Template is provided. All custom Templates must have the variable ${code} as part of the text. The ${code} variable is replaced with the actual SMS code when the message is sent. Optionally, you can also use the variable ${org.name}. If a Template contains ${org.name}, it is replaced with the organization name before the SMS message is sent.

SMS Template macros

Only two macros are supported for SMS Templates:

Type
 Description
${code} The one-time verification code that's required for a user to sign in.
${org.name} The Okta org name that the user is trying to authenticate into.

Note: The length of your SMS message can't exceed 160 characters. If the verification code portion of the message falls outside of the 160-character limit, your message isn't sent.

List all SMS Templates
OAuth 2.0: okta.templates.read

Lists all custom SMS templates. A subset of templates can be returned that match a template type.

Request
query Parameters
templateType
string (SmsTemplateType) [ 1 .. 50 ] characters

Type of the Template

Value: "SMS_VERIFY_CODE"
Responses
200

Success

403

Forbidden

429

Too Many Requests

get/api/v1/templates/sms
Request samples 
Response samples 
application/json
[
  • {
    • "id": "6NQUJ5yR3bpgEiYmq8IC",
    • "name": "Custom",
    • "type": "SMS_VERIFY_CODE",
    • "template": "${org.name}: your verification code is ${code}",
    • "translations": {
      },
    • "created": "2024-04-25T17:35:02.000Z",
    • "lastUpdated": "2024-04-25T17:35:02.000Z"
    }
]
Create an SMS Template
OAuth 2.0: okta.templates.manage
Creates a new custom SMS template


Request 
Request Body schema: application/json
required
name
string  [ 1 .. 50 ] characters 
Human-readable name of the Template


 
template
string  [ 1 .. 161 ] characters 
Text of the Template, including any macros


 
translations
object (SmsTemplateTranslations) 
    

  • Template translations are optionally provided when you want to localize the SMS messages. Translations are provided as an object that contains key:value pairs: the language and the translated Template text. The key portion is a two-letter country code that conforms to ISO 639-1. The value is the translated SMS Template.
    • 

  • Just like with regular SMS Templates, the length of the SMS message can't exceed 160 characters.
    • 



 
type
string (SmsTemplateType)   [ 1 .. 50 ] characters 
Type of the Template


 Value: "SMS_VERIFY_CODE"  
Responses 
200
Success


400
Bad Request


403
Forbidden


429
Too Many Requests


post/api/v1/templates/sms
Request samples 
application/json
{
  • "name": "Custom",
  • "type": "SMS_VERIFY_CODE",
  • "template": "${org.name}: your verification code is ${code}",
  • "translations": {
    • "es": "${org.name}: el código de verificación es ${code}",
    • "fr": "${org.name}: votre code de vérification est ${code}",
    • "it": "${org.name}: il codice di verifica è ${code}"
    }
}
Response samples 
application/json
{
  • "id": "6NQUJ5yR3bpgEiYmq8IC",
  • "name": "Custom",
  • "type": "SMS_VERIFY_CODE",
  • "template": "${org.name}: your verification code is ${code}",
  • "translations": {
    • "es": "${org.name}: el código de verificación es ${code}",
    • "fr": "${org.name}: votre code de vérification est ${code}",
    • "it": "${org.name}: il codice di verifica è ${code}"
    },
  • "created": "2024-04-25T17:35:02.000Z",
  • "lastUpdated": "2024-04-25T17:35:02.000Z"
}
Retrieve an SMS Template
OAuth 2.0: okta.templates.read
Retrieves a specific template by id


Request 
path Parameters
templateId
required
string
id of the Template


 
 Example:  6NQUJ5yR3bpgEiYmq8IC
Responses 
200
Success


403
Forbidden


404
Not Found


429
Too Many Requests


get/api/v1/templates/sms/{templateId}
Request samples 
Response samples 
application/json
{
  • "id": "6NQUJ5yR3bpgEiYmq8IC",
  • "name": "Custom",
  • "type": "SMS_VERIFY_CODE",
  • "template": "${org.name}: your verification code is ${code}",
  • "translations": {
    • "es": "${org.name}: el código de verificación es ${code}",
    • "fr": "${org.name}: votre code de vérification est ${code}",
    • "it": "${org.name}: il codice di verifica è ${code}"
    },
  • "created": "2024-04-25T17:35:02.000Z",
  • "lastUpdated": "2024-04-25T17:35:02.000Z"
}
Update an SMS Template
OAuth 2.0: okta.templates.manage
Updates only some of the SMS Template properties:


    

  • All properties within the custom SMS Template that have values are updated.
    • 

  • Any translation that doesn't exist is added.
    • 

  • Any translation with a null or empty value is removed.
    • 

  • Any translation with non-empty/null value is updated.
    • 



Request 
path Parameters
templateId
required
string
id of the Template


 
 Example:  6NQUJ5yR3bpgEiYmq8IC
Request Body schema: application/json
required
name
string  [ 1 .. 50 ] characters 
Human-readable name of the Template


 
template
string  [ 1 .. 161 ] characters 
Text of the Template, including any macros


 
translations
object (SmsTemplateTranslations) 
    

  • Template translations are optionally provided when you want to localize the SMS messages. Translations are provided as an object that contains key:value pairs: the language and the translated Template text. The key portion is a two-letter country code that conforms to ISO 639-1. The value is the translated SMS Template.
    • 

  • Just like with regular SMS Templates, the length of the SMS message can't exceed 160 characters.
    • 



 
type
string (SmsTemplateType)   [ 1 .. 50 ] characters 
Type of the Template


 Value: "SMS_VERIFY_CODE"  
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/api/v1/templates/sms/{templateId}
Request samples 
application/json
{
  • "translations": {
    • "de": "${org.name}: ihre bestätigungscode ist ${code}."
    }
}
Response samples 
application/json
{
  • "id": "6NQUJ5yR3bpgEiYmq8IC",
  • "name": "Custom",
  • "type": "SMS_VERIFY_CODE",
  • "template": "${org.name}: your verification code is ${code}",
  • "translations": {
    • "es": "${org.name}: el código de verificación es ${code}",
    • "fr": "${org.name}: votre code de vérification est ${code}",
    • "it": "${org.name}: il codice di verifica è ${code}",
    • "de": "${org.name}: ihre bestätigungscode ist ${code}."
    },
  • "created": "2024-04-25T17:35:02.000Z",
  • "lastUpdated": "2024-04-25T17:35:02.000Z"
}
Replace an SMS Template
OAuth 2.0: okta.templates.manage
Replaces the SMS Template




Notes: You can't update the default SMS Template.




Request 
path Parameters
templateId
required
string
id of the Template


 
 Example:  6NQUJ5yR3bpgEiYmq8IC
Request Body schema: application/json
required
name
string  [ 1 .. 50 ] characters 
Human-readable name of the Template


 
template
string  [ 1 .. 161 ] characters 
Text of the Template, including any macros


 
translations
object (SmsTemplateTranslations) 
    

  • Template translations are optionally provided when you want to localize the SMS messages. Translations are provided as an object that contains key:value pairs: the language and the translated Template text. The key portion is a two-letter country code that conforms to ISO 639-1. The value is the translated SMS Template.
    • 

  • Just like with regular SMS Templates, the length of the SMS message can't exceed 160 characters.
    • 



 
type
string (SmsTemplateType)   [ 1 .. 50 ] characters 
Type of the Template


 Value: "SMS_VERIFY_CODE"  
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


put/api/v1/templates/sms/{templateId}
Request samples 
application/json
{
  • "name": "Custom",
  • "type": "SMS_VERIFY_CODE",
  • "template": "${org.name}: your verification code is ${code}",
  • "translations": {
    • "es": "${org.name}: el código de verificación es ${code}",
    • "fr": "${org.name}: votre code de vérification est ${code}",
    • "it": "${org.name}: il codice di verifica è ${code}"
    }
}
Response samples 
application/json
{
  • "id": "6NQUJ5yR3bpgEiYmq8IC",
  • "name": "Custom",
  • "type": "SMS_VERIFY_CODE",
  • "template": "${org.name}: your verification code is ${code}",
  • "translations": {
    • "es": "${org.name}: el código de verificación es ${code}",
    • "fr": "${org.name}: votre code de vérification est ${code}",
    • "it": "${org.name}: il codice di verifica è ${code}"
    },
  • "created": "2024-04-25T17:35:02.000Z",
  • "lastUpdated": "2024-04-25T17:35:02.000Z"
}
Delete an SMS Template
OAuth 2.0: okta.templates.manage
Deletes an SMS template


Request 
path Parameters
templateId
required
string
id of the Template


 
 Example:  6NQUJ5yR3bpgEiYmq8IC
Responses 
204
No Content


403
Forbidden


404
Not Found


429
Too Many Requests


delete/api/v1/templates/sms/{templateId}
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}