Endpoint
POST https://requiems.xyz/v1/systems/input/validate
Input Validate
Validates and scores a single email address, phone number, or text input — or any combination of the three. Returns per-field quality scores, normalized values, risk flags, and an overall quality score for gating or enriching input data.
Parameters
| Name |
Type |
Required |
Location |
Description |
email |
string |
no |
body |
The email address to validate. At least one of email, phone, or text must be provided. |
phone |
string |
no |
body |
The phone number to validate. Must include country code in E.164 format. At least one of email, phone, or text must be provided. |
text |
string |
no |
body |
The text content to analyze for profanity, toxicity, and sentiment. At least one of email, phone, or text must be provided. |
Request Example
{
"email": "user@example.com",
"phone": "+12015551234",
"text": "I just wanted to say that your customer service team was incredibly helpful and resolved my issue faster than expected."
}
Response Example
{
"data": {
"email": {
"valid": true,
"normalized": "user@example.com",
"original": "user@example.com",
"syntax_valid": true,
"mx_valid": true,
"disposable": false,
"suggestion": null,
"flags": null,
"quality_score": 1
},
"phone": {
"valid": true,
"normalized": "+1 201-555-1234",
"country": "US",
"type": "landline_or_mobile",
"carrier": null,
"risk": {
"is_voip": false,
"is_virtual": false
},
"flags": null,
"quality_score": 1
},
"text": {
"is_safe": true,
"toxicity_score": null,
"sentiment": "positive",
"flags": null
},
"overall_quality_score": 1
},
"metadata": {
"timestamp": "2026-06-09T23:20:55Z"
}
}
Response Fields
| Field |
Type |
Description |
email |
object |
Email validation result. Null when email was not provided. |
email.valid |
boolean |
True when the email passes syntax and MX validation. |
email.normalized |
string |
Normalized form of the email address. Null when syntax is invalid. |
email.original |
string |
The original email address as provided in the request. |
email.syntax_valid |
boolean |
True when the email address has a valid structure. |
email.mx_valid |
boolean |
True when the email domain has valid MX records. |
email.disposable |
boolean |
True when the email domain is a known disposable or temporary provider. |
email.suggestion |
string |
Suggested correction when a typo is detected in the domain (e.g. gmial.com → gmail.com). Null otherwise. |
email.flags |
array |
Triggered flags. Possible values: email_syntax_invalid, email_mx_invalid, email_disposable, email_has_suggestion. |
email.quality_score |
number |
Email quality score from 0.0 to 1.0. Penalized by invalidity, disposable domain, and suggestions. |
phone |
object |
Phone validation result. Null when phone was not provided. |
phone.valid |
boolean |
True when the phone number is valid and dialable. |
phone.normalized |
string |
Normalized phone number in international format. Null when the number is invalid. |
phone.country |
string |
ISO 3166-1 alpha-2 country code detected from the number (e.g. US, CO). Null when the number is invalid. |
phone.type |
string |
Line type. Null when the number is invalid. Possible values: mobile, landline, voip, toll_free, unknown. |
phone.carrier |
object |
Carrier information. Null when not available. |
phone.carrier.name |
string |
Name of the carrier or operator associated with the number. |
phone.risk |
object |
Risk signals associated with the phone number. Null when the validator could not determine risk information. |
phone.risk.is_voip |
boolean |
True when the number is confirmed as a VoIP line. False when explicitly confirmed as non-VoIP. |
phone.risk.is_virtual |
boolean |
True when the number is confirmed as a virtual number. False when explicitly confirmed as non-virtual. |
phone.flags |
array |
Triggered flags. Possible values: phone_invalid, phone_voip, phone_virtual, phone_unknown_type, phone_landline. |
phone.quality_score |
number |
Phone quality score from 0.0 to 1.0. Penalized by invalidity, VoIP, virtual, landline, and unknown type. |
text |
object |
Text analysis result. Null when text was not provided. |
text.is_safe |
boolean |
False when any moderation flag is triggered. True otherwise. |
text.toxicity_score |
number |
Reserved for future use. Currently always null. |
text.sentiment |
string |
Detected sentiment: positive, negative, or neutral. |
text.flags |
array |
Triggered moderation flags. Possible values: text_profanity. |
overall_quality_score |
number |
Weighted quality score from 0.0 to 1.0 combining email and phone fields only. Weights are email 0.5 and phone 0.4, adjusted proportionally when one field is absent. Text does not currently contribute to this score — scoring will be enabled once toxicity_score is available from the sentiment service. Returns 0.0 when only text is provided. |
Errors
undefined 422 — All fields (email, phone, text) are absent or empty. At least one must be provided.undefined 401 — Missing or invalid API key.
1---2name: data-integrity-post-validate3description: Validates and scores a single email address, phone number, or text input — or any combination of the three. Returns per-field quality scores, normalized values, risk flags, and an overall quality score for gating or enriching input data.4---5
6## Endpoint
7
8**POST https://requiems.xyz/v1/systems/input/validate**
9
10## Input Validate
11
12Validates and scores a single email address, phone number, or text input — or any combination of the three. Returns per-field quality scores, normalized values, risk flags, and an overall quality score for gating or enriching input data.
13
14## Parameters
15
16| Name | Type | Required | Location | Description |
17| ---- | ---- | -------- | -------- | ----------- |
18| `email` | string | no | body | The email address to validate. At least one of email, phone, or text must be provided. |
19| `phone` | string | no | body | The phone number to validate. Must include country code in E.164 format. At least one of email, phone, or text must be provided. |
20| `text` | string | no | body | The text content to analyze for profanity, toxicity, and sentiment. At least one of email, phone, or text must be provided. |
21
22## Request Example
23
24```json
25{
26 "email": "user@example.com",
27 "phone": "+12015551234",
28 "text": "I just wanted to say that your customer service team was incredibly helpful and resolved my issue faster than expected."
29}
30```
31
32## Response Example
33
34```json
35{
36 "data": {
37 "email": {
38 "valid": true,
39 "normalized": "user@example.com",
40 "original": "user@example.com",
41 "syntax_valid": true,
42 "mx_valid": true,
43 "disposable": false,
44 "suggestion": null,
45 "flags": null,
46 "quality_score": 1
47 },
48 "phone": {
49 "valid": true,
50 "normalized": "+1 201-555-1234",
51 "country": "US",
52 "type": "landline_or_mobile",
53 "carrier": null,
54 "risk": {
55 "is_voip": false,
56 "is_virtual": false
57 },
58 "flags": null,
59 "quality_score": 1
60 },
61 "text": {
62 "is_safe": true,
63 "toxicity_score": null,
64 "sentiment": "positive",
65 "flags": null
66 },
67 "overall_quality_score": 1
68 },
69 "metadata": {
70 "timestamp": "2026-06-09T23:20:55Z"
71 }
72}
73```
74
75## Response Fields
76
77| Field | Type | Description |
78| ----- | ---- | ----------- |
79| `email` | object | Email validation result. Null when email was not provided. |
80| `email.valid` | boolean | True when the email passes syntax and MX validation. |
81| `email.normalized` | string | Normalized form of the email address. Null when syntax is invalid. |
82| `email.original` | string | The original email address as provided in the request. |
83| `email.syntax_valid` | boolean | True when the email address has a valid structure. |
84| `email.mx_valid` | boolean | True when the email domain has valid MX records. |
85| `email.disposable` | boolean | True when the email domain is a known disposable or temporary provider. |
86| `email.suggestion` | string | Suggested correction when a typo is detected in the domain (e.g. gmial.com → gmail.com). Null otherwise. |
87| `email.flags` | array<string> | Triggered flags. Possible values: email_syntax_invalid, email_mx_invalid, email_disposable, email_has_suggestion. |
88| `email.quality_score` | number | Email quality score from 0.0 to 1.0. Penalized by invalidity, disposable domain, and suggestions. |
89| `phone` | object | Phone validation result. Null when phone was not provided. |
90| `phone.valid` | boolean | True when the phone number is valid and dialable. |
91| `phone.normalized` | string | Normalized phone number in international format. Null when the number is invalid. |
92| `phone.country` | string | ISO 3166-1 alpha-2 country code detected from the number (e.g. US, CO). Null when the number is invalid. |
93| `phone.type` | string | Line type. Null when the number is invalid. Possible values: mobile, landline, voip, toll_free, unknown. |
94| `phone.carrier` | object | Carrier information. Null when not available. |
95| `phone.carrier.name` | string | Name of the carrier or operator associated with the number. |
96| `phone.risk` | object | Risk signals associated with the phone number. Null when the validator could not determine risk information. |
97| `phone.risk.is_voip` | boolean | True when the number is confirmed as a VoIP line. False when explicitly confirmed as non-VoIP. |
98| `phone.risk.is_virtual` | boolean | True when the number is confirmed as a virtual number. False when explicitly confirmed as non-virtual. |
99| `phone.flags` | array<string> | Triggered flags. Possible values: phone_invalid, phone_voip, phone_virtual, phone_unknown_type, phone_landline. |
100| `phone.quality_score` | number | Phone quality score from 0.0 to 1.0. Penalized by invalidity, VoIP, virtual, landline, and unknown type. |
101| `text` | object | Text analysis result. Null when text was not provided. |
102| `text.is_safe` | boolean | False when any moderation flag is triggered. True otherwise. |
103| `text.toxicity_score` | number | Reserved for future use. Currently always null. |
104| `text.sentiment` | string | Detected sentiment: positive, negative, or neutral. |
105| `text.flags` | array<string> | Triggered moderation flags. Possible values: text_profanity. |
106| `overall_quality_score` | number | Weighted quality score from 0.0 to 1.0 combining email and phone fields only. Weights are email 0.5 and phone 0.4, adjusted proportionally when one field is absent. Text does not currently contribute to this score — scoring will be enabled once toxicity_score is available from the sentiment service. Returns 0.0 when only text is provided. |
107
108## Errors
109
110- `undefined` **422** — All fields (email, phone, text) are absent or empty. At least one must be provided.
111- `undefined` **401** — Missing or invalid API key.
gabrielmoreira