Create a new Challenge for the Factor

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

TODO: Resource-level docs

Create a new Challenge for the Factor

Path parameters

  • ServiceSid string Required

    The unique SID identifier of the Service.

  • Identity string Required

    Customer unique identity for the Entity owner of the Challenge. 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

  • AuthPayload string

    Optional payload used to verify the Challenge upon creation. Only used with a Factor of type totp to carry the TOTP code that needs to be verified. For TOTP this value must be between 3 and 8 characters long.

  • Details.Fields array

    A list of objects that describe the Fields included in the Challenge. Each object contains the label and value of the field, the label can be up to 36 characters in length and the value can be up to 128 characters in length. Used when factor_type is push. There can be up to 20 details fields.

  • Details.Message string

    Shown to the user when the push notification arrives. Required when factor_type is push. Can be up to 256 characters in length

  • ExpirationDate string(date-time)

    The date-time when this Challenge expires, given in ISO 8601 format. The default value is five (5) minutes after Challenge creation. The max value is sixty (60) minutes after creation.

  • FactorSid string Required

    The unique SID identifier of the Factor.

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

  • HiddenDetails

    Details provided to give context about the Challenge. Not shown to the end user. It must be a stringified JSON with only strings values eg. {"ip": "172.168.1.234"}. 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}$.

    • date_created string(date-time) | null

      The date this Challenge was created

    • date_responded string(date-time) | null

      The date this Challenge was responded

    • date_updated string(date-time) | null

      The date this Challenge was updated

    • details

      Details about the Challenge.

    • 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}$.

    • expiration_date string(date-time) | null

      The date-time when this Challenge expires

    • factor_sid string | null

      Factor Sid.

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

    • factor_type string | null

      The Factor Type of this Challenge

      Values are push or totp.

    • hidden_details

      Hidden details about the Challenge

    • identity string | null

      Unique external identifier of the Entity

    • links object(uri-map) | null

      Nested resource URLs.

    • metadata

      Metadata of the challenge.

    • responded_reason string | null

      The Reason of this Challenge status

      Values are none, not_needed, or not_requested.

    • 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 Challenge.

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

    • status string | null

      The Status of this Challenge

      Values are pending, expired, approved, or denied.

    • url string(uri) | null

      The URL of this resource.
POST /v2/Services/{ServiceSid}/Entities/{Identity}/Challenges 
curl \
 -X POST https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Challenges \
 --user "username:password" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d 'AuthPayload=string&&Details.Message=string&ExpirationDate=2023-05-04T09%3A42%3A00%2B00%3A00&FactorSid=string'
Request example 
{
  "AuthPayload": "string",
  "Details.Fields": [],
  "Details.Message": "string",
  "ExpirationDate": "2023-05-04T09:42:00+00:00",
  "FactorSid": "string"
}
Request examples 
{
  "AuthPayload": "string",
  "Details.Fields": [],
  "Details.Message": "string",
  "ExpirationDate": "2024-05-04T09:42:00+00:00",
  "FactorSid": "string"
}
Response examples (201) 
{
  "account_sid": "string",
  "date_created": "2023-05-04T09:42:00+00:00",
  "date_responded": "2023-05-04T09:42:00+00:00",
  "date_updated": "2023-05-04T09:42:00+00:00",
  "entity_sid": "string",
  "expiration_date": "2023-05-04T09:42:00+00:00",
  "factor_sid": "string",
  "factor_type": "push",
  "identity": "string",
  "links": {},
  "responded_reason": "none",
  "service_sid": "string",
  "sid": "string",
  "status": "pending",
  "url": "https://example.com"
}
Response examples (201) 
{
  "account_sid": "string",
  "date_created": "2024-05-04T09:42:00+00:00",
  "date_responded": "2024-05-04T09:42:00+00:00",
  "date_updated": "2024-05-04T09:42:00+00:00",
  "entity_sid": "string",
  "expiration_date": "2024-05-04T09:42:00+00:00",
  "factor_sid": "string",
  "factor_type": "push",
  "identity": "string",
  "links": {},
  "responded_reason": "none",
  "service_sid": "string",
  "sid": "string",
  "status": "pending",
  "url": "https://example.com"
}