Check several signals against each other

Takes any subset of an email address, a phone number, an IP address, a postal address and a business identifier, runs each through the product that owns it, and reports where the answers agree and where they do not.

The per-signal blocks under signals are exactly what the single-lookup endpoints return, field for field. All five keys are always present: a signal you did not ask for, or one the call did not reach, is null. The signals run in a fixed order — ip, phone, entity, address, email — because a keyed body has no input order, and because email is the only leg that does DNS and a mailbox probe, so a call that runs out of credits stops at the slowest leg last.

The consistency block on top is free. comparisons lists each check with both sides quoted — the signal, the field and the value that decided it — so nothing is asserted that you cannot see the working for. A comparison appears only when both of its signals answered; a signal nobody asked about produces silence, not a row. Where one side is null the result is not_compared with withheld: "missing_value", never a disagreement, because a null field means "not evaluated" and never "no". Where the IP is a VPN exit, a relay or a datacenter egress, the country comparisons answer not_compared with withheld: "low_confidence": that location belongs to the operator rather than to the person, and reporting a difference there would manufacture evidence against everyone who uses a VPN.

country_agreement rolls up the three country comparisons between the person's own signals — differ if any of them differed, agree if at least one agreed and none differed, and null when none of them could be made. flags names the disagreements and the pairings that held: phone_country_differs_from_address_country, ip_country_differs_from_address_country, ip_country_differs_from_phone_country, disposable_email_from_datacenter_ip, disposable_email_from_anonymous_network, mail_drop_address_with_free_email_provider, disposable_phone_with_disposable_email, entity_country_differs_from_address_country, entity_name_differs_from_address_organization. The ip_address_distance comparison carries distance_km as evidence only, and never raises a flag: there is no honest distance at which a person stops being themselves.

The business identifier is compared against the postal address, the only other signal carrying a company name and a country of its own. entity_address_country puts the country of registration beside the country the address stands in; it is deliberately not part of country_agreement, because where a company is registered is not where a person is, and a Delaware company with a London office would otherwise read as a top-level disagreement. entity_address_organization compares the registered legal name with the organisation written on the address, and the only claim it makes is a normalised exact match: both sides are folded to their letters and digits and compared as strings, with case, accents (Société and Societe fold together), an ampersand against the word and, apostrophes, full stops in initials, and company-form words such as limited, ltd, plc, llp and inc taken out first — so a difference here is a difference in the name rather than in how it was typed. There is no similarity score, because no threshold honestly decides whether two names are one company — so differ means the two names are not the same name, not that the address belongs to somebody else. A value that folds away to nothing, such as an organisation line reading only "Ltd", withholds the comparison as a missing value.

There is no score, no risk level, no verdict and no recommendation, and there will not be one. The flags are the whole output, and a difference between two fields is a fact about the fields, not a judgement about a person — people travel, move house, keep a foreign number and browse through a VPN. Nothing about the call is stored beyond what each product already logs for its own lookup.

curl -X POST https://spaw.co/api/v1/consistency \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "[email protected]",
  "phone": "+442079460018",
  "country": "GB",
  "ip": "81.2.69.142",
  "address": {
    "address": "10 Downing Street, London, SW1A 2AA",
    "organization": "ACME HOLDINGS LTD",
    "country": "GB"
  },
  "entity": {
    "identifier": "213800QILIUD4ROSUO03",
    "type": "lei"
  }
}'

const response = await fetch('https://spaw.co/api/v1/consistency', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_…',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "email": "[email protected]",
    "phone": "+442079460018",
    "country": "GB",
    "ip": "81.2.69.142",
    "address": {
      "address": "10 Downing Street, London, SW1A 2AA",
      "organization": "ACME HOLDINGS LTD",
      "country": "GB"
    },
    "entity": {
      "identifier": "213800QILIUD4ROSUO03",
      "type": "lei"
    }
  }),
});
const result = await response.json();

import requests

response = requests.post(
    'https://spaw.co/api/v1/consistency',
    headers={'Authorization': 'Bearer sk_live_…'},
    json={
        'email': '[email protected]',
        'phone': '+442079460018',
        'country': 'GB',
        'ip': '81.2.69.142',
        'address': {
            'address': '10 Downing Street, London, SW1A 2AA',
            'organization': 'ACME HOLDINGS LTD',
            'country': 'GB'
        },
        'entity': {
            'identifier': '213800QILIUD4ROSUO03',
            'type': 'lei'
        }
    },
)
result = response.json()

$ch = curl_init('https://spaw.co/api/v1/consistency');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer sk_live_…', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'email' => '[email protected]',
        'phone' => '+442079460018',
        'country' => 'GB',
        'ip' => '81.2.69.142',
        'address' => [
            'address' => '10 Downing Street, London, SW1A 2AA',
            'organization' => 'ACME HOLDINGS LTD',
            'country' => 'GB'
        ],
        'entity' => [
            'identifier' => '213800QILIUD4ROSUO03',
            'type' => 'lei'
        ]
    ]),
]);
$result = json_decode(curl_exec($ch), true);

from spaw import Client

client = Client('sk_live_…')
result = client.check_consistency(email='[email protected]', phone='+442079460018', country='GB', ip='81.2.69.142', address={
    'address': '10 Downing Street, London, SW1A 2AA',
    'organization': 'ACME HOLDINGS LTD',
    'country': 'GB'
})

import Spaw from 'spaw';

const spaw = new Spaw({ apiKey: 'sk_live_…' });
const result = await spaw.checkConsistency({
    email: '[email protected]',
    phone: '+442079460018',
    country: 'GB',
    ip: '81.2.69.142',
    address: {
        address: '10 Downing Street, London, SW1A 2AA',
        organization: 'ACME HOLDINGS LTD',
        country: 'GB'
    }
});

use Spaw\Client;

$spaw = new Client('sk_live_…');
$result = $spaw->checkConsistency(email: '[email protected]', phone: '+442079460018', country: 'GB', ip: '81.2.69.142', address: [
    'address' => '10 Downing Street, London, SW1A 2AA',
    'organization' => 'ACME HOLDINGS LTD',
    'country' => 'GB'
]);

{
    "success": true,
    "data": {
        "consistency": {
            "signals_compared": [
                "email",
                "phone",
                "ip",
                "address",
                "entity"
            ],
            "country_agreement": "differ",
            "flags": [
                "ip_country_differs_from_address_country",
                "ip_country_differs_from_phone_country"
            ],
            "comparisons": [
                {
                    "comparison": "phone_address_country",
                    "left": {
                        "signal": "phone",
                        "field": "country",
                        "value": "GB"
                    },
                    "right": {
                        "signal": "address",
                        "field": "country",
                        "value": "GB"
                    },
                    "result": "agree",
                    "withheld": null,
                    "flag": null,
                    "distance_km": null
                },
                {
                    "comparison": "ip_address_country",
                    "left": {
                        "signal": "ip",
                        "field": "country",
                        "value": "DE"
                    },
                    "right": {
                        "signal": "address",
                        "field": "country",
                        "value": "GB"
                    },
                    "result": "differ",
                    "withheld": null,
                    "flag": "ip_country_differs_from_address_country",
                    "distance_km": null
                }
            ]
        }
    },
    "meta": {
        "requested": 5,
        "processed": 5,
        "credits_used": 5,
        "credits_remaining": 995,
        "stopped_reason": null,
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "Provide a valid API key as a bearer token.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "INSUFFICIENT_CREDITS",
        "message": "Your credit balance is empty.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "The email field is required.",
        "errors": {
            "email": [
                "The email field is required."
            ]
        },
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}

{
    "success": false,
    "error": {
        "code": "RATE_LIMITED",
        "message": "Too many requests. Retry after the limit resets.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}