Skip to main content

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

Create a verification request (email or SMS) with intent

​
Overview

This endpoint creates a verification request for a user with a specific intent. It supports both email and SMS verification methods. It’s designed for integration with Thread and other services that need to verify user contact information.

​
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

​
Query Parameters

ParameterTypeRequiredDefaultDescription
methodstringNoemailVerification method: email or sms

​
Request Body (Email verification)

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

​
Request Body (SMS verification)

{
  "intent_name": "string",
  "meta_data": {
    "contact_phones": [
      {
        "phone_number": "string",
        "phone_type": "mobile"
      }
    ],
    "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_emailstringYes (for email method)Email address to verify
meta_data.contact_phonesarrayYes (for sms method)Array of phone objects to verify
meta_data.contact_phones[].phone_numberstringYesPhone number to send SMS to
meta_data.contact_phones[].phone_typestringNoType of phone (e.g., “mobile”)

​
Response

​
Success Response (200 OK)

{
  "verification_id": "uuid-string",
  "status": 200,
  "message": "Verification needed, sent to an email ending in user@example.com"
}
For SMS: 
{
  "verification_id": "uuid-string",
  "status": 200,
  "message": "Verification needed, sent to a number ending in 9172547061"
}

​
Error Responses

​
400 Bad Request - Missing Meta Data

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

​
400 Bad Request - Missing Intent Name

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

​
400 Bad Request - Invalid Email (email method)

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

​
400 Bad Request - Missing Email (email method)

{
  "error": "Email method requires contact_email in meta_data",
  "error_code": "email_requires_contact_email"
}

​
400 Bad Request - Missing Phones (sms method)

{
  "error": "SMS method requires contact_phones in meta_data",
  "error_code": "sms_requires_phones"
}

​
400 Bad Request - Invalid Phone (sms method)

{
  "error": "No valid phone number found in contact_phones",
  "error_code": "phone_invalid"
}

​
400 Bad Request - Empty Phone (sms method)

{
  "error": "Phone number cannot be empty",
  "error_code": "phone_empty"
}

​
400 Bad Request - Invalid Method

{
  "error": "Invalid verification method. Use 'sms' or 'email'",
  "error_code": "invalid_verification_method"
}

​
Example Usage

​
cURL (Email)

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"
    }
  }'

​
cURL (SMS)

curl -X POST "https://api.scute.io/v1/verify/c24ee9a6-31a6-4be8-b21e-1796c6a91273/verifications/intent?method=sms" \
  -H "Content-Type: application/json" \
  -H "X-Authorization: your_m2m_access_token" \
  -d '{
    "intent_name": "phone_verification",
    "meta_data": {
      "contact_phones": [
        {
          "phone_number": "9172547061",
          "phone_type": "mobile"
        }
      ],
      "contact_name": "John Doe"
    }
  }'

​
JavaScript (Email)

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); // uuid
console.log(data.message);         // "Verification needed, sent to an email ending in user@example.com"

​
JavaScript (SMS)

const response = await fetch('https://api.scute.io/v1/verify/c24ee9a6-31a6-4be8-b21e-1796c6a91273/verifications/intent?method=sms', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Authorization': 'your_m2m_access_token'
  },
  body: JSON.stringify({
    intent_name: 'phone_verification',
    meta_data: {
      contact_phones: [
        { phone_number: '9172547061', phone_type: 'mobile' }
      ],
      contact_name: 'John Doe'
    }
  })
});

const data = await response.json();
console.log(data.verification_id); // uuid
console.log(data.message);         // "Verification needed, sent to a number ending in 9172547061"

​
Behavior

​
Email Verification (default)

  1. Email Validation: Validates the email format using sanitize_email() and is_valid_email()
  2. User Creation: If the user doesn’t exist, 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, status, and message

​
SMS Verification (?method=sms)

  1. Phone Validation: Validates that contact_phones array exists and contains at least one valid phone number
  2. User Creation: If the user doesn’t exist, creates a new app user with the provided phone number
  3. Verification Creation: Creates an SMS verification request with a unique reason (intent_name + random hex)
  4. Event Recording: Records a verification.sms.requested event for tracking
  5. Response: Returns the verification ID, status, and message

​
Notes

  • The endpoint automatically finds or creates an app user based on the contact info (email or phone)
  • The verification reason is generated by combining intent_name with a random hex string for uniqueness
  • Email addresses are automatically sanitized (lowercased and trimmed)
  • When using SMS, the first valid phone number from the contact_phones array is used
  • Optional callback notifications can be sent via X-Callback-URL header or meta_data.callback_url