Use the Soryxa validation endpoint from your backend to turn an email address into an allow, block, or review decision with reason codes and usage fields.
Decision payload
Send one email address per request. policy_key is optional and context metadata is not accepted by the current API contract.
POST /api/v1/validate
Authorization: Bearer $SORYXA_API_KEY
Content-Type: application/json
{
"email": "user@example.com",
"policy_key": "signup"
}Read the decision first, then use the reason code and checks for routing and logging.
{
"success": true,
"data": {
"policy_key": "signup",
"decision": "allow",
"reason_code": "CLASSIFICATION_VALID",
"decision_message": "Email passed all validation checks",
"customer_message": null,
"decision_reasons": ["Valid email with high quality score"],
"auto_resolution": null,
"rollout": {
"mode": "enforce",
"status": "active",
"percentage": 100,
"shadow_decision": null
},
"checks": [
{
"name": "Domain MX",
"status": "passed",
"message": "Domain has valid MX records"
}
],
"base_score": 96,
"score_adjustments": [],
"score": 96,
"raw_data": {
"classification": "valid",
"score": 96
},
"upstream": {
"provider": "elvesora_api",
"state": "closed",
"status": "ok",
"status_code": 200,
"duration_ms": 148,
"failure_count": 0
}
},
"usage": {
"remaining": 249,
"limit": 250
}
}These fields are intended for API clients, customer admin tools, and workflow automation that needs repeatable decisions instead of raw validation signals alone.
| Field | Description |
|---|---|
| success | Boolean indicating whether the API request completed successfully. |
| data.policy_key | Caller-supplied flow label echoed in the response. Defaults to default when omitted and does not select a separate ruleset. |
| data.decision | Workflow decision: allow, block, or review. |
| data.reason_code | Stable machine-readable reason for the decision. |
| data.decision_message | Human-readable explanation suitable for logs and admin tools. |
| data.customer_message | Customer-facing message selected from the team rule policy when configured. |
| data.decision_reasons | List of supporting reasons for the final decision. |
| data.auto_resolution | Metadata when hashed review auto-resolution changes a review decision to allow or block. |
| data.rollout | Rule rollout metadata for shadow or staged policy changes. |
| data.checks[] | Named validation checks with status and message fields. |
| data.base_score | Provider score before team rule adjustments are applied. |
| data.score_adjustments | Score adjustments applied by team rule weights. |
| data.score | 0-100 score derived from validation signals and team rules. |
| data.raw_data | Raw upstream validation data used for audit and troubleshooting workflows. |
| data.upstream | Upstream provider, circuit state, status, HTTP status, duration, and failure metadata. |
| usage.remaining | Validation allowance remaining after the request. |
| usage.limit | Plan limit used to calculate remaining validations. |
Headers are useful for tracing and simple routing, but the JSON response remains the primary contract for decisions, scores, and checks.
| Header | Description |
|---|---|
| X-Soryxa-Reason-Code | Echoes the final reason_code for clients that route from headers. |
| X-Soryxa-Correlation-Id | Echoes X-Soryxa-Correlation-Id or X-Request-Id, or returns a generated fallback ID. |
Treat the validation endpoint as a decision service. The response should be mapped into the same place your product already handles signup acceptance, review queues, CRM syncs, and account policy.
Keep this logic close to the workflow that owns the outcome. A signup form, CRM import job, and pre-send check can all call the same endpoint, but each workflow may need a different review owner and user-facing fallback.