Anti-fraud API — Checks before you commit to an operation (1.0)

Download OpenAPI specification:Download

INTRODUCTION

Checks you run before taking a piece of data at face value: signing someone up, sending them a verification code or accepting a payment.

Every check goes through the same call. The SERVICIO parameter picks which one, and parameters that do not belong to that check are ignored: you can always send the same structure and only change SERVICIO. New checks (email, IP…) will arrive here, with no second URL for you to integrate.

AVAILABLE CHECKS

SERVICIO	What it checks
`DatosTelefono`	Who is behind a number: the carrier serving it, its porting history (which carrier it came from and when it was ported) and the line type.
`DatosEmail`	What is behind an address: whether the domain receives mail and is free, disposable or its own, whether the account belongs to a person or to a department, and whether the mailbox exists.
`DatosIP`	Where someone connects from: country, city, carrier, whether it is a home line, a mobile or a data centre, and whether it arrives through an anonymous network.

WHY PORTING DATE AND LINE TYPE

Of everything you can learn about a number without calling it, these two are the ones that actually change a decision.

The porting date. A number that changed carrier three days ago, right before a significant operation, is the signature of a SIM swap: the attacker moves the victim's number to another carrier and from then on receives their verification codes. If you are about to send a code to that number, verify through another channel first.

The line type. An Internet line (VoIP) where a mobile should be is usually a throwaway number: minutes to get, minutes to abandon. And premium-rate or machine-to-machine numbering is nobody's personal phone.

On top of that, the response carries a calculated risk from 0 to 100 with the reasons in plain text. It is not a verdict and it does not decide for you: it is what the data supports, explained, so your system can apply your own policy.

WHAT THE EMAIL CHECK LOOKS AT

It is the same check we run before every Certified Email delivery, made available to you. It goes from cheap to expensive and stops as soon as it has the answer:

1. Syntax of the address.
2. The domain receives mail: its mail records are looked up in DNS. A domain without them cannot receive anything, so the address does not exist —and that is known without asking anyone.
3. Disposable domain, the kind created in a second that nobody ever reads again.
4. Free domain and account type: a person, a department (info@, support@…) or a tagged alias (john+shop@).
5. Whether that address already bounced a delivery of ours. This is our own information, and it beats any prediction: it is not that it will probably fail, it is that it already did.
6. And only then, whether the mailbox exists, by asking the destination mail server.

Step 6 uses two different verifiers: some servers greylist, some drop the connection, some answer differently depending on who is asking, so when the first one says «I don't know» the second one is consulted. Even so, catch-all domains accept any address: there nobody can confirm a specific account exists, and we say exactly that instead of inventing a yes.

WHERE THE DATA COMES FROM

For Spanish mobile numbers we use our own porting registry, which is what lets us tell you the carrier the number came from and the exact date of the change. For Spanish landlines and any foreign number we query international numbering data. You do not have to choose: send the number and it is resolved wherever it has to be.

The Fuente field of the response tells you which was used. Not every country publishes porting history: when there is no data, Portabilidad.Consta comes back as 0 —which is not the same as «not ported», and that is why they are told apart.

PRICE

You are charged per resolved check. If it cannot be resolved the call returns -4 and nothing is charged.

The same check repeated within a minute (a double submit, a retry from your system) returns the previous result flagged with Repetida=1 and is not charged either. After that minute it is looked up again for real and charged again: the data may have changed, and yesterday's porting is precisely the one you care about.

AUTHENTICATION

Same as the rest of our APIs: Basic authentication with your user and your API Token, which you will find in your panel under Your data → Configure → Security. Remember to authorise there the public IP address you will be calling from.

Check

/Consultar

Runs an anti-fraud check. The SERVICIO parameter picks which one: DatosTelefono returns the carrier, the porting history and the line type of the number; DatosEmail returns the domain, the account type and whether the mailbox exists; DatosIP returns where someone connects from and what kind of connection they use. All three also return the calculated risk and its reasons.

Response fields depend on the check: Numero, Linea, Operadora and Portabilidad only come with DatosTelefono, Email, Dominio, Cuenta, Buzon, Historial and Reputacion only with DatosEmail, and IP, Ubicacion, Operador, Conexion and ListasNegras only with DatosIP. Res, Servicio, Consulta, Riesgo, Fuente, Creditos and Cred always come back.

Authorizations:

basicAuth

query Parameters

Servicio	string Enum: "DATOSTELEFONO" "DATOSEMAIL" "DATOSIP" Example: Servicio=DatosTelefono Check you want to run. Case insensitive. `DatosTelefono` - Carrier, porting history and line type of a number. Requires `TELEFONO`. `DatosEmail` - Domain, account type and mailbox existence of an address. Requires `EMAIL`.
Telefono	string Example: Telefono=600000000 Number to check, required with `SERVICIO=DatosTelefono`. You may send it in national format (`600000000`) together with `PREFIJO`, or in full international format (`+34600000000` or `0034600000000`), in which case `PREFIJO` is not needed. Spaces, dashes and brackets are ignored.
Prefijo	string Example: Prefijo=+34 International dialling code of the number's country, with or without `+`. Only used when `TELEFONO` is in national format.
Email	string Example: Email=name@domain.com Email address to check, required with `SERVICIO=DatosEmail`.
Listasnegras	string Enum: 0 1 Example: Listasnegras=1 Only with `SERVICIO=DatosEmail`. Set to `1` to also check whether the domain —or the mail server its mail leaves from— is on public abuse blocklists. No credit cost, but the call takes considerably longer: several external servers have to be asked and waited for.
Filtraciones	string Enum: 0 1 Example: Filtraciones=1 Only with `SERVICIO=DatosEmail`. Set to `1` to check whether the address has appeared in known data breaches. Costs an extra on top of the check price. Read it the right way round: appearing in a breach is no stain on the owner —the one who lost the data was the service they were registered with—. What it gives you is the opposite: proof of how long that address has existed, which is why in the risk calculation it subtracts when the oldest breach is a few years old. An address created this morning for a scam cannot have that trail. If it cannot be checked (the service rate-limits requests), the call returns the rest of the check, explains it in `Aviso` and the extra is not charged.
Ip	string Example: Ip=80.24.10.5 IPv4 address to check, required with `SERVICIO=DatosIP`. Private and reserved ranges are rejected: they do not identify an Internet connection.
Resp	string Enum: "TXT" "JSON" "XML" Example: Resp=JSON Response format for this call. `JSON` - You will get the response in JSON `XML` - You will get the response in XML `TXT` - You will get the response in plain text

Request Body schema:
application/json

Parameters are sent in the body of the POST request, either as a JSON object (Content-Type application/json, RECOMMENDED) or as an application/x-www-form-urlencoded form. In the form format, array or object parameters are sent as a JSON-encoded string. Parameter names are case-insensitive. The detailed description of each parameter is in the parameters section of this operation.

Servicio	string
Telefono	string
Prefijo	string
Email	string
Listasnegras	string
Filtraciones	string
Ip	string
Resp	string

Responses

Response Schema:
application/json

Array

Res required	integer <int32> Result of the call `1` Check completed. `-1` Authentication error or IP not authorised. `-2` Not enough credits. `-3` Parameter error. The detail comes in Error. `-4` The check could not be resolved. Nothing was charged; try again in a few minutes. `-5` The given SERVICIO does not exist.
Servicio	string Check that was run.
Consulta	string The data that was checked, normalised to international format.
Email	Array of arrays Only with `SERVICIO=DatosEmail`. The address taken apart. `Sugerencia` carries the correction when it looks like a typo (`gmial.com` → `gmail.com`) and comes back empty otherwise.
Dominio	Array of arrays Only with `SERVICIO=DatosEmail`. `RecibeCorreo` set to `0` means the domain has no mail configured in its DNS: the address does not exist. `Tipo` is the stable value for your code: `gratuito` (free), `temporal` (disposable) or `propio` (its own). `AntiguedadDias` is `-1` when it could not be determined.
Cuenta	Array of arrays Only with `SERVICIO=DatosEmail`. What is behind the part before the at sign. `Tipo`: `personal`, `rol` (a department mailbox: `info@`, `support@`…, read by several people and identifying nobody) or `alias` (tagged address, `john+shop@`: one mailbox yields endless variants).
Buzon	Array of arrays Only with `SERVICIO=DatosEmail`. `Estado`: `valido`, `noexiste`, `catchall` (the domain accepts any address and nobody can confirm this account exists), `desconocido` (the destination server would not let us check) or `nocomprobado` (not needed: the domain receives no mail or is disposable, so nothing was spent verifying it).
Historial	Array of arrays Only with `SERVICIO=DatosEmail`. Whether that address already bounced a delivery of ours, with the reason the destination server gave. A fact, not a prediction.
Reputacion	Array of arrays Email checks only. `Trampa` set to `1` means the address is catalogued as a spam trap or as a source of complaints: writing to it harms the delivery of all your mail.
Numero	Array of arrays Only with `SERVICIO=DatosTelefono`. The number in its different formats and its country. `Nacional` is the digits without the dialling code, which is what your program will want to store; `Formato` is the readable version for display and may come back empty. `Valido` set to `0` means the number is not allocated or is not valid in its country.
Linea	Array of arrays Only with `SERVICIO=DatosTelefono`. Line type. `Tipo` is the stable value for your code: `movil`, `fijo`, `voip`, `gratuito`, `compartido`, `premium`, `personal`, `m2m` or `desconocido`. `TipoTexto` is the readable version.
Operadora	Array of arrays Only with `SERVICIO=DatosTelefono`. Carrier serving the number. `MCC`/`MNC` identify the mobile network and come back empty for landlines.
Portabilidad	Array of arrays Only with `SERVICIO=DatosTelefono`. Porting history. `Consta` set to `0` means that country does not publish the data, which is not the same as not having been ported. `Dias` is the number of days since the change (`-1` if unknown): the key figure for spotting a SIM swap.
IP	Array of arrays Only with `SERVICIO=DatosIP`. The address that was checked.
Ubicacion	Array of arrays Only with `SERVICIO=DatosIP`. Where the address is. Handle with care: anyone changes their location with a VPN, so it does not decide on its own; the field that decides is `Conexion.Tipo`.
Operador	Array of arrays Only with `SERVICIO=DatosIP`. Who owns the address: the carrier, its network (autonomous system) and the block it belongs to, with the date that block was allocated. A freshly allocated block accuses nobody, but plenty of the ranges rented out for abuse come from there.
Conexion	Array of arrays Only with `SERVICIO=DatosIP`. The most important part of this check. `Tipo`: `domestica` (home), `movil` (mobile), `centrodatos` (data centre), `anonima` (anonymous network) or `desconocida`. A person connects from home or from their phone; behind a `centrodatos` there is a server, which may be a legitimate corporate VPN or something automated posing as someone. `InversoConfirmado` is `1` when the reverse name of the IP leads back to that same address, `0` when it does not match —a name that does not correspond is set by someone who does not control that range— and `-1` when there is no reverse name.
ListasNegras	Array of arrays Public abuse blocklists. With `DatosIP` the address itself is checked; with `DatosEmail`, the domain and the IPs of its mail servers —a clean domain whose mail leaves from a flagged machine is not a clean domain—. `SinComprobar` is the number of lists that refused the query. It matters: `Listada=0` together with `SinComprobar>0` is not the same as a clean «not listed», so we say so. Some lists reject queries from anyone without a prior agreement and answer with a code that a careless system would read as «listed»: here they are told apart.
Filtraciones	Array of arrays Only with `SERVICIO=DatosEmail` and `FILTRACIONES=1`. `Consultado` set to `0` means it was not requested or could not be done. `AnosVisible` is how many years the address has demonstrably been in use, counted from the oldest breach: that is the useful figure here.
Aviso	string A warning about the call itself when there is one: for instance, that breaches could not be checked and therefore the extra was not charged. Empty or absent otherwise.
Riesgo	Array of arrays Risk from 0 to 100, its `Nivel` (`BAJO` below 25, `MEDIO` up to 49, `ALTO` from 50) and the `Motivos` explaining it, in plain text. It is input for your policy, not a decision.
Fuente	string Where the data comes from: `propia` (our own porting registry, Spanish mobiles) or `proveedor` (international numbering lookup).
Repetida	integer Set to `1` when this is the same check run less than a minute ago: the previous result is returned and nothing was charged.
Creditos	number Credits charged for this call.
Cred	number Credits left after the check.
Error	string Description of the problem when Res is negative.

Request samples

Content type

application/json

{"Servicio": "DatosTelefono",
"Telefono": "600000000",
"Prefijo": "+34",
"Email": "name@domain.com",
"Listasnegras": "1",
"Filtraciones": "1",
"Ip": "80.24.10.5",
"Resp": "JSON"
}

Response samples