Create a new Challenge for the Factor

POST /v2/Services/{ServiceSid}/Entities/{Identity}/Challenges
Account sid auth token

Create a new Challenge for the Factor

Path parameters

  • ServiceSid string Required

    The unique SID identifier of the Service.

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

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

application/x-www-form-urlencoded

Body

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

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

  • 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

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

  • 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

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

Responses

  • 201 application/json

    Created

    Hide headers attributes Show headers attributes
    • Access-Control-Allow-Origin string

      Specify the origin(s) allowed to access the resource

    • Access-Control-Allow-Methods string

      Specify the HTTP methods allowed when accessing the resource

    • Access-Control-Allow-Headers string

      Specify the headers allowed when accessing the resource

    • Access-Control-Allow-Credentials boolean

      Indicates whether the browser should include credentials

    • Access-Control-Expose-Headers string

      Headers exposed to the client

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

      A 34 character 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}$.

    • account_sid string | null

      The unique SID identifier of the Account.

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

    • service_sid string | null

      The unique SID identifier of the Service.

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

    • entity_sid string | null

      The unique SID identifier of the Entity.

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

    • identity string | null

      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.

    • factor_sid string | null

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

    • date_created string(date-time) | null

      The date that this Challenge was created, given in ISO 8601 format.

    • date_updated string(date-time) | null

      The date that this Challenge was updated, given in ISO 8601 format.

    • date_responded string(date-time) | null

      The date that this Challenge was responded, given in ISO 8601 format.

    • expiration_date string(date-time) | null

      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.

    • status string

      The Status of this Challenge. One of pending, expired, approved or denied.

      Values are pending, expired, approved, or denied.

    • responded_reason string

      Reason for the Challenge to be in certain status. One of none, not_needed or not_requested.

      Values are none, not_needed, or not_requested.

    • details

      Details provided to give context about the Challenge. Intended to be shown to the end user.

    • hidden_details

      Details provided to give context about the Challenge. Intended to be hidden from the end user. It must be a stringified JSON with only strings values eg. {"ip": "172.168.1.234"}

    • metadata

      Custom metadata associated with the challenge. 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.

    • factor_type string

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

      Values are push or totp.

    • url string(uri) | null

      The URL of this resource.

    • links object(uri-map) | null

      Contains a dictionary of URL links to nested resources of this Challenge.
POST /v2/Services/{ServiceSid}/Entities/{Identity}/Challenges 
curl \
 --request POST 'https://verify.twilio.com/v2/Services/{ServiceSid}/Entities/{Identity}/Challenges' \
 --user "username:password" \
 --header "Content-Type: application/x-www-form-urlencoded" \
 --data 'FactorSid=YF03aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&HiddenDetails=%7B%22ip%22%3A+%22172.168.1.234%22%7D&Details.Fields=%7B%22label%22%3A+%22Action%22%2C+%22value%22%3A+%22Sign+up+in+portal%22%7D&ExpirationDate=2015-07-30T20%3A00%3A00Z&Details.Message=Hi%21+Mr.+John+Doe%2C+would+you+like+to+sign+up%3F'
Request examples 
{"FactorSid"=>"YF03aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "HiddenDetails"=>"{\"ip\": \"172.168.1.234\"}", "Details.Fields"=>["{\"label\": \"Action\", \"value\": \"Sign up in portal\"}"], "ExpirationDate"=>"2015-07-30T20:00:00Z", "Details.Message"=>"Hi! Mr. John Doe, would you like to sign up?"}
{"FactorSid"=>"YF02aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "HiddenDetails"=>"{\"ip\": \"172.168.1.234\"}", "Details.Fields"=>["{\"label\": \"Action\", \"value\": \"Sign up in portal\"}"], "ExpirationDate"=>"2015-07-30T20:00:00Z", "Details.Message"=>"Hi! Mr. John Doe, would you like to sign up?"}
{"FactorSid"=>"YF02aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "AuthPayload"=>"12345678", "HiddenDetails"=>"{\"ip\": \"172.168.1.234\"}", "Details.Fields"=>["{\"label\": \"Action\", \"value\": \"Sign up in portal\"}"], "ExpirationDate"=>"2015-07-30T20:00:00Z", "Details.Message"=>"Hi! Mr. John Doe, would you like to sign up?"}
Response examples (201) 
{
  "sid": "YC03aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Challenges/YC03aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "links": {
    "notifications": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Challenges/YC03aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications"
  },
  "status": "pending",
  "details": {
    "date": "2020-07-01T12:13:14Z",
    "fields": [
      {
        "label": "Action",
        "value": "Sign up in portal"
      }
    ],
    "message": "Hi! Mr. John Doe, would you like to sign up?"
  },
  "identity": "ff483d1ff591898a9942916050d2ca3f",
  "metadata": null,
  "entity_sid": "YEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "factor_sid": "YF03aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "factor_type": "push",
  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "date_created": "2015-07-30T20:00:00Z",
  "date_updated": "2015-07-30T20:00:00Z",
  "date_responded": "2015-07-30T20:00:00Z",
  "hidden_details": {
    "ip": "172.168.1.234"
  },
  "expiration_date": "2015-07-30T20:00:00Z",
  "responded_reason": "none"
}
{
  "sid": "YC02aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Challenges/YC02aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "links": {
    "notifications": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Challenges/YC02aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications"
  },
  "status": "pending",
  "details": {
    "date": "2020-07-01T12:13:14Z",
    "fields": [
      {
        "label": "Action",
        "value": "Sign up in portal"
      }
    ],
    "message": "Hi! Mr. John Doe, would you like to sign up?"
  },
  "identity": "ff483d1ff591898a9942916050d2ca3f",
  "metadata": null,
  "entity_sid": "YEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "factor_sid": "YF02aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "factor_type": "totp",
  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "date_created": "2015-07-30T20:00:00Z",
  "date_updated": "2015-07-30T20:00:00Z",
  "date_responded": "2015-07-30T20:00:00Z",
  "hidden_details": {
    "ip": "172.168.1.234"
  },
  "expiration_date": "2015-07-30T20:00:00Z",
  "responded_reason": "none"
}
{
  "sid": "YC02aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "url": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Challenges/YC02aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "links": {
    "notifications": "https://verify.twilio.com/v2/Services/VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Entities/ff483d1ff591898a9942916050d2ca3f/Challenges/YC02aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Notifications"
  },
  "status": "approved",
  "details": {
    "date": "2020-07-01T12:13:14Z",
    "fields": [
      {
        "label": "Action",
        "value": "Sign up in portal"
      }
    ],
    "message": "Hi! Mr. John Doe, would you like to sign up?"
  },
  "identity": "ff483d1ff591898a9942916050d2ca3f",
  "metadata": null,
  "entity_sid": "YEaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "factor_sid": "YF02aaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "factor_type": "totp",
  "service_sid": "VAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "date_created": "2015-07-30T20:00:00Z",
  "date_updated": "2015-07-30T20:00:00Z",
  "date_responded": "2015-07-30T20:00:00Z",
  "hidden_details": {
    "ip": "172.168.1.234"
  },
  "expiration_date": "2015-07-30T20:00:00Z",
  "responded_reason": "none"
}