Lookup

Check one identifier

Checks a single identifier. The type is detected from the input unless type is supplied.

One identifier per request. Four fields on a form means four requests, each charged at its own rate.

Cost. Phone, email and IP cost 1 credit; domain costs 2. A completed check that establishes no evidence is not charged and returns usage.not_charged.

Retries. Send Idempotency-Key and a retry replays the stored result without a second charge. Reusing a key for different inputs or options is refused with 409.

post/v1/lookup

Request

  • Base URL: https://orisift.com
  • URL: https://orisift.com/v1/lookup
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

An opaque key of your choosing. A repeat of the same request with the same key replays the original result and is not charged again. Reusing it for a different input, type, country or policy is refused with 409.

Request body

inputstring required

The identifier to check. One only.

type'phone' | 'email' | 'ip' | 'domain'

Skips detection and selects a checker. It does not assert the value is valid.

countrystring

ISO 3166-1 alpha-2. Required to interpret a phone number in national format.

retain_inputboolean

Store the submitted value against this lookup. Off by default.

explainboolean

Ask for an AI explanation. Off by default, drawn from a separate monthly allowance, and it never changes the verdict or the score.

policy'contact_standard'

Ask for a recommended action under a named policy. Omitting it returns exactly the response you received before this field existed.

policy_versioninteger

Pin a policy version. Omitted means the latest at the time of the request. The version that was used always comes back in action.policy_version.

Example request

{
  "input": "+12125550142",
  "country": "GB"
}

Response

The check completed. This includes verdicts of rejected and insufficient_evidence: a conclusion against the identifier is a successful request.

object'lookup' required
api_version'1' required
idstring required
createdstring date-time required
type'phone' | 'email' | 'ip' | 'domain' required
countrystring nullable

Resolved country, where one applies.

normalizedstring nullable

Display form. Phones use international formatting with spaces, not compact E.164; read the E.164 attribute if you need that.

verdict'verified' | 'risky' | 'rejected' | 'insufficient_evidence' required

insufficient_evidence is its own outcome and is never an automatic rejection: it means the checks could not establish enough, not that the identifier is bad.

risk_scoreinteger nullable required

Higher means more risk under the scoring rules. Not a probability of fraud. Null when the verdict is insufficient_evidence.

evidence_coverageinteger required

How much of the available evidence was obtained. Not a confidence in the verdict.

headlinestring required

Display only. Wording can change without a version bump.

summarystring required

Display only. Wording can change without a version bump.

recommendationstring required

Display only. For a machine-readable decision, send policy and read action.

latency_msinteger required

Execution duration. Not an uptime or latency guarantee.

Example response

{
  "id": "lk_67e75a1d70e94a0692b178e6",
  "signals": [
    {
      "source": "National regulator allocations"
    }
  ],
  "coverage_limitations": [
    {
      "code": "no_carrier_provider"
    }
  ],
  "action": {
    "reasons": [
      {
        "code": "phone_reserved_range"
      }
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.