Skip to content
FormSentry FormSentry FormSentry Docs

Verify Endpoint

Verify Endpoint

Section titled “Verify Endpoint”

The verify endpoint is the core of FormSentry’s spam detection. It analyzes form submissions and returns whether they’re spam or legitimate.

Endpoint

Section titled “Endpoint”
POST https://api.formsentry.ai/v1/verify

Request Format

Section titled “Request Format”

Headers

Section titled “Headers”
Content-Type: application/json

Body Parameters

Section titled “Body Parameters”
ParameterTypeRequiredDescription
apiKeystringYesYour FormSentry API key
formIdstringYesYour form identifier
payloadobjectYes*The form submission data
fieldDataobjectYes*Alternative to payload for dynamic form fields

*Either payload or fieldData must be provided.

Example Request

Section titled “Example Request”
{
  "apiKey": "fs_e7a9c4b1f0d6a2c89e5b3d7f4a1c6e2b9085df3a9c4e7b1a6d2f508c9e3b4",
  "formId": "contact_form_homepage",
  "payload": {
    "name": "John Doe",
    "email": "john@example.com",
    "message": "I'm interested in your services",
    "phone": "+1234567890"
  }
}

Response Format

Section titled “Response Format”

Success Response (200 OK)

Section titled “Success Response (200 OK)”
{
  "status": "legitimate",
  "confidence": 0.95,
  "reasoning": "The submission appears to be from a legitimate user with valid contact information",
  "submissionId": "550e8400-e29b-41d4-a716-446655440000",
  "processingTime": 245,
  "formId": "contact_form_homepage"
}

Response Fields

Section titled “Response Fields”
FieldTypeAlways PresentDescription
statusstringYesEither "spam" or "legitimate"
confidencenumberYesConfidence score between 0 and 1
reasoningstringYesHuman-readable explanation of the decision
submissionIdstringYesUUID v4 unique identifier for this submission
processingTimenumberYesProcessing time in milliseconds
formIdstringNoEcho of the form ID from the request (may be omitted)

Status Values

Section titled “Status Values”

legitimate

Section titled “legitimate”

The submission passed all spam checks and appears to be from a real user.

Recommended Action: Process the submission normally.

spam

Section titled “spam”

The submission failed one or more spam checks.

Recommended Action: Silently reject or flag for manual review.

Code Examples

Section titled “Code Examples”

Node.js

Section titled “Node.js”
const response = await fetch('https://api.formsentry.ai/v1/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  signal: AbortSignal.timeout(5000),
  body: JSON.stringify({
    apiKey: process.env.FORMSENTRY_API_KEY,
    formId: process.env.FORMSENTRY_FORM_ID,
    payload: formData
  })
});


if (!response.ok) {
  throw new Error(`FormSentry error: ${response.status}`);
}


const result = await response.json();

Python

Section titled “Python”
import requests
import os


def verify_submission(form_data):
    response = requests.post(
        'https://api.formsentry.ai/v1/verify',
        json={
            'apiKey': os.environ['FORMSENTRY_API_KEY'],
            'formId': os.environ['FORMSENTRY_FORM_ID'],
            'payload': form_data
        },
        timeout=5
    )
    response.raise_for_status()
    return response.json()

PHP

Section titled “PHP”
<?php
function verifySubmission(array $formData): array {
    $ch = curl_init('https://api.formsentry.ai/v1/verify');


    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_TIMEOUT => 5,
        CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS => json_encode([
            'apiKey' => getenv('FORMSENTRY_API_KEY'),
            'formId' => getenv('FORMSENTRY_FORM_ID'),
            'payload' => $formData
        ])
    ]);


    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);


    if ($httpCode !== 200) {
        throw new Exception("FormSentry error: $httpCode");
    }


    return json_decode($response, true);
}
?>

Error Responses

Section titled “Error Responses”

400 Bad Request

Section titled “400 Bad Request”

Missing or invalid parameters.

{
  "error": "Missing required fields: apiKey and either payload or fieldData"
}

401 Unauthorized

Section titled “401 Unauthorized”

Invalid API key.

{
  "error": "Invalid API key"
}

403 Forbidden

Section titled “403 Forbidden”

The request origin is not in the form’s allowed referrer list.

{
  "success": false,
  "classification": "blocked",
  "confidence": 1.0,
  "reason": "Referrer domain not allowed",
  "processingTime": 12
}

404 Not Found

Section titled “404 Not Found”

Form not found or does not belong to your account.

{
  "error": "Form 'contact_form_homepage' not found or doesn't belong to your account"
}

429 Too Many Requests

Section titled “429 Too Many Requests”

Rate limit exceeded. See Rate Limiting for details.

{
  "error": "Rate limit exceeded",
  "retryAfter": 60,
  "message": "Too many requests. Please wait before trying again.",
  "processingTime": 5
}

500 Internal Server Error

Section titled “500 Internal Server Error”

Server error. The submission has not been processed.

{
  "error": "Internal server error",
  "status": "error",
  "confidence": 0,
  "submissionId": "550e8400-e29b-41d4-a716-446655440000",
  "processingTime": 120
}

Best Practices

Section titled “Best Practices”

Handle Timeouts

Section titled “Handle Timeouts”

Set appropriate timeouts for your HTTP requests (recommended: 5 seconds).

Implement Retry Logic

Section titled “Implement Retry Logic”

For network errors or 5xx responses, implement exponential backoff retry logic.

Log Submission IDs

Section titled “Log Submission IDs”

Store the submissionId for debugging and support purposes.

Fail Open

Section titled “Fail Open”

If FormSentry is unreachable, allow the submission through rather than blocking your users. See the SDK guides for examples.

Next Steps

Section titled “Next Steps”