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": "[email protected]",
"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 classified as valid.",
"customer_message": "Email looks valid.",
"decision_reasons": ["Provider classified the address as valid."],
"auto_resolution": {
"applied": false
},
"rollout": {
"mode": "enforce"
},
"checks": [
{
"name": "mx_record",
"status": "passed",
"message": "Domain accepts mail."
}
],
"base_score": 96,
"score_adjustments": [],
"score": 96,
"raw_data": {},
"upstream": {
"available": true
}
},
"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 | Policy key used for the decision. Defaults to default when omitted. |
| 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 | Bounded upstream validation data for internal audit and troubleshooting workflows. |
| data.upstream | Upstream health metadata such as service availability or fallback state. |
| 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 a caller-supplied correlation ID when provided. |
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.