Verify an email address

Sends an email that includes a link with a one-time verification link a user can click to complete the email verification process. The destination URL for this link is configured in the verify_email_url setting of the API client used to make this call.

If you aren't the JavaScript SDK, you need to use the access/useVerificationCode endpoint to employ the verification code. If successful, the emailVerified attribute in the user's record is updated to the current date and time. If unsuccessful, this endpoint can be called again to resend an email with a new code.


Authentication

No authentication is required to call this endpoint.


Base URL

The base URL for this endpoint is your Identity Cloud Capture domain; for example:

https://educationcenter.us- dev.janraincapture.com

Your Capture domains (also known as Registration domains) can be found in the Console on the Manage Application page.


Examples

Example: Trigger verification email

This command sends an email verification notice to the user johndoe@example.com.

curl -X POST \
  --data-urlencode 'client_id=12345abcde12345abcde12345abcde12' \
  --data-urlencode 'flow=standard' \
  --data-urlencode 'flow_version=20190618143040022299' \
  --data-urlencode 'locale=en-US' \
  --data-urlencode 'redirect_uri=http://localhost' \
  --data-urlencode 'form=resendVerificationForm' \
  --data-urlencode 'signInEmailAddress=johndoe@example.com' \
  https://my-app.janraincapture.com/oauth/verify_email_native

Methods

MethodTypeRequiredDescription
client_idstringAPI client ID used to authenticate the call. This client must be configured with the login_client feature, which gives it permission to use login and registration-based API endpoints. API client permissions may be configured by using the clients/set_features endpoint.
flowstringName of the flow configured with the login experience you want to use. You can find a list of valid flow names using the Configuration API. You can omit this method if you configure the flow name in the default_flow_name setting for the API client used to make this call.
flow_versionstringVersion number of the flow set in the flow method. Note that you can't set the flow version to HEAD, which tells Identity Cloud to use the most-recent version of the flow. Instead, you must specify the version number e the most recent version. You can find a list of versions for your flow using the Configuration API. This method can be omitted if you you configure the flow version in the default_flow_version setting for the API client used to make this call.
formstringName of the form used to to generate the verification email. TYou can find a list of valid forms and their associated fields by using the Configuration API.
{form fields}arrayName of the field used to generate the verification email. Use the field name as the key and the user input as the value for this method. For example, the default resendVerificationForm configured for the standard flow uses the field signInEmailAddress. You can find a list of valid fields and associated forms for your flow using the Configuration API.
llocalestringCode for the language you want to use for the login experience. This method determines the language for any error messages returned to you and the verification emails sent to users. The default locale provisioned with the standard Registration flow is en-US. Other locales must be configured in your flow. You can find a list of valid locales for your flow using the Configuration API.
redirect_uristringRequired for legacy purposes and not used for any functionality in this call.

Responses

200 OK: Successful response

A successful call will return the simple response below:

{
  "stat": "ok"
}

210: Email does not exist

Indicates that the email address submitted is not registered. Because of that, no verification email is sent:

{
  "stat": "error",
  "code": 210,
  "error_description": "some inputs are invalid",
  "error": "invalid_credentials",
  "request_id": "v2ddw6xyc2s39tm3",
  "invalid_fields": {
    "resendVerificationForm": [
      "We don't recognize that email address. Please try again."
    ]
  }
}

540: Email already verified

Indicates that the email address submitted has already been verified:

{
  "stat": "error",
  "code": 540,
  "error_description": "an error was triggered in the flow",
  "error": "triggered_error",
  "request_id": "g3cfbjg9ptge2yte",
  "message": "Your email is already verified. You may sign in."
}

200: Invalid form

Indicates that the form value is invalid. Keep in mind that form names are case sensitive,, which means that the form name resendverificationform fails. Instead, resendVerificationForm is the valid form name:

{
  "stat": "error",
  "code": 200,
  "error_description": "no such form 'resendverificationform'",
  "error": "invalid_argument",
  "request_id": "rdfbsavfvzb2sxud"
}

100: Missing required methods

The example error response below indicates that one of the required methods for the call was omitted. The error message describes which method is missing:

{
  "stat": "error",
  "code": 100,
  "error_description": "missing arguments: flow",
  "error": "missing_argument",
  "request_id": "uyeem84bmqmnjuu4"
}

500: Invalid flow value

Indicates that the value provided for he flow, flow_version, or locale methods is invalid. Flow versions are unique across environments, verify that you are using the correct version number for your environment:

{
  "stat": "error",
  "code": 500,
  "error_description": "could not find a flow named 'standard' with version '12345abc-1234-abcd-1234-12345abcde12' and locale 'en-US'",
  "error": "unexpected_error",
  "request_id": "murynd7fhpysq6um"
}