Create a new Factor for the Entity

POST /v2/Services/{ServiceSid}/Entities/{Identity}/Factors

TODO: Resource-level docs

Create a new Factor for the Entity

Path parameters

  • ServiceSid string Required

    The unique SID identifier of the Service.

  • Identity string Required

    Customer unique identity for the Entity owner of the Factor. This identifier should be immutable, not PII, length between 8 and 64 characters, and generated by your external system, such as your user's UUID, GUID, or SID. It can only contain dash (-) separated alphanumeric characters.

Body

  • Binding.Alg string

    The algorithm used when factor_type is push. Algorithm supported: ES256

  • Binding.PublicKey string

    The Ecdsa public key in PKIX, ASN.1 DER format encoded in Base64.

    Required when factor_type is push

  • Binding.Secret string

    The shared secret for TOTP factors encoded in Base32. This can be provided when creating the Factor, otherwise it will be generated.

    Used when factor_type is totp

  • Config.Alg string

    The algorithm used to derive the TOTP codes. Can be sha1, sha256 or sha512. Defaults to sha1.

    Used when factor_type is totp

    Values are sha1, sha256, or sha512.

  • Config.AppId string

    The ID that uniquely identifies your app in the Google or Apple store, such as com.example.myapp. It can be up to 100 characters long.

    Required when factor_type is push.

  • Config.CodeLength integer

    Number of digits for generated TOTP codes. Must be between 3 and 8, inclusive. The default value is defined at the service level in the property totp.code_length. If not configured defaults to 6.

    Used when factor_type is totp

  • Config.NotificationPlatform string

    The transport technology used to generate the Notification Token. Can be apn, fcm or none.

    Required when factor_type is push.

    Values are apn, fcm, or none.

  • Config.NotificationToken string

    For APN, the device token. For FCM, the registration token. It is used to send the push notifications. Must be between 32 and 255 characters long.

    Required when factor_type is push.

  • Config.SdkVersion string

    The Verify Push SDK version used to configure the factor

    Required when factor_type is push

  • Config.Skew integer

    The number of time-steps, past and future, that are valid for validation of TOTP codes. Must be between 0 and 2, inclusive. The default value is defined at the service level in the property totp.skew. If not configured defaults to 1.

    Used when factor_type is totp

  • Config.TimeStep integer

    Defines how often, in seconds, are TOTP codes generated. i.e, a new TOTP code is generated every time_step seconds. Must be between 20 and 60 seconds, inclusive. The default value is defined at the service level in the property totp.time_step. Defaults to 30 seconds if not configured.

    Used when factor_type is totp

  • FactorType string Required

    The Type of this Factor. Currently push and totp are supported.

    Values are push or totp.

  • FriendlyName string Required

    The friendly name of this Factor. This can be any string up to 64 characters, meant for humans to distinguish between Factors. For factor_type push, this could be a device name. For factor_type totp, this value is used as the “account name” in constructing the binding.uri property. At the same time, we recommend avoiding providing PII.

  • Metadata

    Custom metadata associated with the factor. This is added by the Device/SDK directly to allow for the inclusion of device information. It must be a stringified JSON with only strings values eg. {"os": "Android"}. Can be up to 1024 characters in length.

Responses

  • 201

    Created

    Hide response attributes Show response attributes object
    • account_sid string | null

      Account Sid.

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^AC[0-9a-fA-F]{32}$.

    • binding

      Binding of the factor

    • config

      Configurations for a factor_type.

    • date_created string(date-time) | null

      The date this Factor was created

    • date_updated string(date-time) | null

      The date this Factor was updated

    • entity_sid string | null

      Entity Sid.

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^YE[0-9a-fA-F]{32}$.

    • factor_type string | null

      The Type of this Factor

      Values are push or totp.

    • friendly_name string | null

      A human readable description of this resource.

    • identity null | string

      Unique external identifier of the Entity

    • metadata

      Metadata of the factor.

    • service_sid string | null

      Service Sid.

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^VA[0-9a-fA-F]{32}$.

    • sid string | null

      A string that uniquely identifies this Factor.

      Minimum length is 34, maximum length is 34. Format should match the following pattern: ^YF[0-9a-fA-F]{32}$.

    • status string | null

      The Status of this Factor

      Values are unverified or verified.

    • url string(uri) | null

      The URL of this resource.
POST /v2/Services/{ServiceSid}/Entities/{Identity}/Factors 
curl \
 -X POST https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Factors \
 --user "username:password" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'Binding.Alg=string&Binding.PublicKey=string&Binding.Secret=string&Config.Alg=sha1&Config.AppId=string&Config.CodeLength=42&Config.NotificationPlatform=apn&Config.NotificationToken=string&Config.SdkVersion=string&Config.Skew=42&Config.TimeStep=42&FactorType=push&FriendlyName=string'
Request example 
{
  "Binding.Alg": "string",
  "Binding.PublicKey": "string",
  "Binding.Secret": "string",
  "Config.Alg": "sha1",
  "Config.AppId": "string",
  "Config.CodeLength": 42,
  "Config.NotificationPlatform": "apn",
  "Config.NotificationToken": "string",
  "Config.SdkVersion": "string",
  "Config.Skew": 42,
  "Config.TimeStep": 42,
  "FactorType": "push",
  "FriendlyName": "string"
}
Request examples 
{
  "Binding.Alg": "string",
  "Binding.PublicKey": "string",
  "Binding.Secret": "string",
  "Config.Alg": "sha1",
  "Config.AppId": "string",
  "Config.CodeLength": 42,
  "Config.NotificationPlatform": "apn",
  "Config.NotificationToken": "string",
  "Config.SdkVersion": "string",
  "Config.Skew": 42,
  "Config.TimeStep": 42,
  "FactorType": "push",
  "FriendlyName": "string"
}
Response examples (201) 
{
  "account_sid": "string",
  "date_created": "2023-05-04T09:42:00+00:00",
  "date_updated": "2023-05-04T09:42:00+00:00",
  "entity_sid": "string",
  "factor_type": "push",
  "friendly_name": "string",
  "identity": "string",
  "service_sid": "string",
  "sid": "string",
  "status": "unverified",
  "url": "https://example.com"
}
Response examples (201) 
{
  "account_sid": "string",
  "date_created": "2025-05-04T09:42:00Z",
  "date_updated": "2025-05-04T09:42:00Z",
  "entity_sid": "string",
  "factor_type": "push",
  "friendly_name": "string",
  "identity": null,
  "service_sid": "string",
  "sid": "string",
  "status": "unverified",
  "url": "https://example.com"
}