Skip to main content

POST /v1/verify/{app_id}/verifications/intent

Create an email verification request with intent

Overview​

This endpoint creates an email verification request for a user with a specific intent. It's designed for integration with Thread and other services that need to verify user email addresses.

Authentication​

This endpoint requires M2M (Machine-to-Machine) authentication. Create an M2M token from your Scute dashboard and include it in the X-Authorization header.

# Get M2M token first
curl -X POST "https://api.scute.io/v1/auth/m2m/token" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "your_api_key"}'

# Use the returned access_token in X-Authorization header

Request​

Method​

POST

URL​

/v1/verify/\{app_id\}/verifications/intent

Path Parameters​

ParameterTypeRequiredDescription
app_idstringYesThe ID of the app

Request Body​

{
  "intent_name": "string",
  "meta_data": {
    "contact_email": "string",
    "additional_context": "any additional intent data"
  }
}

Body Parameters​

ParameterTypeRequiredDescription
intent_namestringYesName/identifier for the verification intent
meta_dataobjectYesMetadata containing user information and intent context
meta_data.contact_emailstringYesEmail address to verify

Response​

Success Response (200 OK)​

{
  "verification_id": "uuid-string"
}

Error Responses​

400 Bad Request - Missing Meta Data​

{
  "error": "Meta data is required",
  "error_code": "meta_data_required"
}

400 Bad Request - Missing Email​

{
  "error": "Email is required",
  "error_code": "email_required"
}

400 Bad Request - Missing Intent Name​

{
  "error": "Intent name is required",
  "error_code": "intent_name_required"
}

400 Bad Request - Invalid Email​

{
  "error": "Invalid email format",
  "error_code": "invalid_email"
}

Example Usage​

cURL​

curl -X POST "https://api.scute.io/v1/verify/c24ee9a6-31a6-4be8-b21e-1796c6a91273/verifications/intent" \
  -H "Content-Type: application/json" \
  -H "X-Authorization: your_m2m_access_token" \
  -d '{
    "intent_name": "user_signup_verification",
    "meta_data": {
      "contact_email": "user@example.com",
      "user_name": "John Doe",
      "signup_source": "website"
    }
  }'

JavaScript​

const response = await fetch('https://api.scute.io/v1/verify/c24ee9a6-31a6-4be8-b21e-1796c6a91273/verifications/intent', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Authorization': 'your_m2m_access_token'
  },
  body: JSON.stringify({
    intent_name: 'user_signup_verification',
    meta_data: {
      contact_email: 'user@example.com',
      user_name: 'John Doe',
      signup_source: 'website'
    }
  })
});

const data = await response.json();
console.log(data.verification_id);

Behavior​

  1. Email Validation: The endpoint validates the email format using sanitize_email() and is_valid_email()
  2. User Creation: If the user doesn't exist, it creates a new app user with the provided email
  3. Verification Creation: Creates an email verification request with a unique reason (intent_name + random hex)
  4. Event Recording: Records a "verification.email.requested" event for tracking
  5. Response: Returns the verification ID for tracking purposes

Notes​

  • The endpoint automatically finds or creates an app user based on the email
  • The verification reason is generated by combining intent_name with a random hex string for uniqueness
  • Email addresses are automatically sanitized (lowercased and trimmed)
  • An event is recorded for analytics/tracking purposes
  • GET /v1/verify/\{app_id\}/verifications/\{id\} - Get verification details
  • POST /v1/verify/\{app_id\}/verifications/verify - Verify the email verification code