layercall-com Scoring API

openapi: 3.2.0
info:
  title: LayerCall Scoring API
  version: 1.0.0
  summary: Trust and risk intelligence for IPs, emails, phones, domains and devices.
  description: 'Score any IP address, email, phone number, domain or device — or a whole signup in one call — and get back a 0–100 risk score plus an allow / review / block verdict.


    Authenticate with an API key from https://www.layercall.com/get-key. Free tier: 1,000 lookups per month, no card required. Test-mode keys are never billed.


    Every endpoint accepts an optional `strictness` parameter (`lenient`, `balanced`, `strict`) that shifts the verdict thresholds without changing the underlying signals.'
  termsOfService: https://www.layercall.com/terms
  contact:
    name: LayerCall Support
    email: support@layercall.com
    url: https://www.layercall.com/contact
  license:
    name: Proprietary
    url: https://www.layercall.com/terms
  x-logo:
    url: https://www.layercall.com/logo-icon.png
    altText: LayerCall
servers:
- url: https://www.layercall.com
  description: Production
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Scoring
  description: Risk scores for a single signal type.
paths:
  /v1/score/ip:
    get:
      tags:
      - Scoring
      operationId: scoreIp
      summary: Score an IP address
      description: Detects VPNs, proxies, Tor exit nodes and datacenter ranges, and returns geo/ASN context plus reputation from LayerCall's first-seen network.
      parameters:
      - name: ip
        in: query
        required: true
        schema:
          type: string
        description: IPv4 or IPv6 address. IPv4-mapped IPv6 (`::ffff:1.2.3.4`) is canonicalised.
        example: 185.220.101.5
      - $ref: '#/components/parameters/Strictness'
      responses:
        '200':
          description: Score
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpScore'
          headers:
            x-ratelimit-limit:
              description: Requests allowed per minute (600).
              schema:
                type: integer
            x-ratelimit-remaining:
              description: Requests left in the current minute.
              schema:
                type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/verify/email:
    get:
      tags:
      - Scoring
      operationId: verifyEmail
      summary: Verify and score an email address
      description: Checks syntax, MX records and mailbox deliverability, and flags disposable, role-based, free-provider and homograph (lookalike) addresses.
      parameters:
      - name: email
        in: query
        required: true
        schema:
          type: string
          format: email
        example: test@mailinator.com
      - $ref: '#/components/parameters/Strictness'
      responses:
        '200':
          description: Result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailResult'
          headers:
            x-ratelimit-limit:
              description: Requests allowed per minute (600).
              schema:
                type: integer
            x-ratelimit-remaining:
              description: Requests left in the current minute.
              schema:
                type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/lookup/phone:
    get:
      tags:
      - Scoring
      operationId: lookupPhone
      summary: Validate and score a phone number
      description: Parses the number, identifies line type (mobile, VoIP, premium rate, toll free) and carrier, and scores fraud risk.
      parameters:
      - name: phone
        in: query
        required: true
        schema:
          type: string
        description: E.164 recommended. Without a leading `+`, pass `country`.
        example: '+14155552671'
      - name: country
        in: query
        required: false
        schema:
          type: string
          minLength: 2
          maxLength: 2
        description: ISO 3166-1 alpha-2, required for national-format numbers.
        example: US
      - $ref: '#/components/parameters/Strictness'
      responses:
        '200':
          description: Result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhoneResult'
          headers:
            x-ratelimit-limit:
              description: Requests allowed per minute (600).
              schema:
                type: integer
            x-ratelimit-remaining:
              description: Requests left in the current minute.
              schema:
                type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/score/domain:
    get:
      tags:
      - Scoring
      operationId: scoreDomain
      summary: Score a domain
      description: Resolution, MX, SPF/DMARC posture, registration age, disposable and risky-TLD checks, plus homograph detection for lookalike domains.
      parameters:
      - name: domain
        in: query
        required: true
        schema:
          type: string
        example: example.com
      - $ref: '#/components/parameters/Strictness'
      responses:
        '200':
          description: Result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainResult'
          headers:
            x-ratelimit-limit:
              description: Requests allowed per minute (600).
              schema:
                type: integer
            x-ratelimit-remaining:
              description: Requests left in the current minute.
              schema:
                type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    PhoneResult:
      type: object
      required:
      - phone
      - risk_score
      - verdict
      properties:
        phone:
          type: string
        risk_score:
          $ref: '#/components/schemas/RiskScore'
        verdict:
          $ref: '#/components/schemas/Verdict'
        parse_status:
          type: string
          enum:
          - ok
          - country_required
          - impossible
          - invalid_pattern
          description: Distinguishes 'you omitted country' from 'this number is bad'.
        signals:
          type: object
          properties:
            syntax_valid:
              type: boolean
            is_possible:
              type: boolean
            is_voip:
              type:
              - boolean
              - 'null'
              description: 'In a range the national plan reserves for VoIP. null where the plan has no VoIP range (+1 US, India, Germany and others) or the number is only fixed-line-or-mobile: unknown, not no.'
            is_premium_rate:
              type: boolean
            is_toll_free:
              type: boolean
            assigned_area_code:
              type:
              - boolean
              - 'null'
              description: NANP only. null when not applicable.
        number:
          type: object
          properties:
            e164:
              type:
              - string
              - 'null'
            country:
              type:
              - string
              - 'null'
        cached:
          type: boolean
        request_id:
          type: string
        processing_time_sec:
          type: number
          example: 0.116
        first_seen:
          nullable: true
        times_seen:
          type: integer
          example: 1
        abuse_reports:
          type: integer
          example: 0
        billable_lookups:
          type: integer
          example: 1
    IpScore:
      type: object
      required:
      - ip
      - risk_score
      - verdict
      - signals
      - geo
      - cached
      - request_id
      properties:
        ip:
          type: string
        risk_score:
          $ref: '#/components/schemas/RiskScore'
        verdict:
          $ref: '#/components/schemas/Verdict'
        signals:
          type: object
          properties:
            is_vpn:
              type: boolean
            is_proxy:
              type: boolean
            is_datacenter:
              type: boolean
            is_tor:
              type: boolean
            recent_abuse:
              type: boolean
            is_private_or_reserved:
              type: boolean
              description: RFC1918 / loopback / reserved. Cannot be meaningfully scored.
        geo:
          type: object
          properties:
            country:
              type:
              - string
              - 'null'
              description: ISO 3166-1 alpha-2.
            city:
              type:
              - string
              - 'null'
            asn:
              type:
              - string
              - 'null'
            isp:
              type:
              - string
              - 'null'
        first_seen:
          type:
          - string
          - 'null'
          format: date-time
          description: First time this value was seen across the LayerCall network.
        times_seen:
          type: integer
        abuse_reports:
          type: integer
          description: Confirmed-fraud reports from distinct accounts.
        cached:
          type: boolean
          description: Served from cache. Cached lookups are never billed.
        request_id:
          type: string
        warning:
          type: string
          description: Present only when the input needs attention.
        vpn_provider:
          type:
          - string
          - 'null'
          description: Name of the VPN operating this exit node (e.g. "NordVPN", "Mullvad", "Surfshark"), taken from the operator's own published server list. null when is_vpn was inferred from an ASN or third-party feed rather than confirmed by the operator — absence is not evidence the IP is not a VPN.
          example: NordVPN
        signals_unavailable:
          type: array
          items:
            type: string
          description: 'Signals that could not be measured on this request — e.g. ["tor", "vpn_providers"]. Absent entirely when every feed answered, so the happy-path shape is unchanged. Present means the score was built on incomplete data: a "clean" answer and a "we could not check" answer are otherwise identical.'
        hijacked_source:
          nullable: true
        processing_time_sec:
          type: number
          example: 0.261
        billable_lookups:
          type: integer
          example: 1
    DomainResult:
      type: object
      required:
      - domain
      - risk_score
      - verdict
      properties:
        domain:
          type: string
        risk_score:
          $ref: '#/components/schemas/RiskScore'
        verdict:
          $ref: '#/components/schemas/Verdict'
        signals:
          type: object
          properties:
            resolves:
              type: boolean
            mx_found:
              type: boolean
            has_spf:
              type: boolean
            has_dmarc:
              type: boolean
            is_disposable:
              type: boolean
            is_homograph:
              type: boolean
            is_free_provider:
              type: boolean
            is_risky_tld:
              type: boolean
            newly_registered:
              type:
              - boolean
              - 'null'
              description: Registered less than 30 days ago. null means the registration date could not be determined (RDAP unreachable, or the TLD publishes no RDAP) — it does NOT mean the domain is established. Treat null as unknown, not as a negative finding.
        registration:
          type: object
          properties:
            created_at:
              type:
              - string
              - 'null'
              format: date-time
        cached:
          type: boolean
        request_id:
          type: string
        signals_unavailable:
          type: array
          items:
            type: string
          description: 'Signals that could not be measured on this request — e.g. ["tor", "vpn_providers"]. Absent entirely when every feed answered, so the happy-path shape is unchanged. Present means the score was built on incomplete data: a "clean" answer and a "we could not check" answer are otherwise identical.'
        processing_time_sec:
          type: number
          example: 0.094
        first_seen:
          nullable: true
        times_seen:
          type: integer
          example: 1
        abuse_reports:
          type: integer
          example: 0
        billable_lookups:
          type: integer
          example: 1
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable message, safe to log.
    EmailResult:
      type: object
      required:
      - email
      - risk_score
      - verdict
      properties:
        email:
          type: string
        normalized_email:
          type: string
        risk_score:
          $ref: '#/components/schemas/RiskScore'
        verdict:
          $ref: '#/components/schemas/Verdict'
        status:
          type: string
          description: e.g. valid, invalid, do_not_mail, unknown.
        sub_status:
          type:
          - string
          - 'null'
          description: e.g. disposable, role_based, mailbox_not_found.
        deliverability_score:
          type: integer
          minimum: 0
          maximum: 100
        did_you_mean:
          type:
          - string
          - 'null'
          description: Suggested correction for a likely typo.
        signals:
          type: object
          properties:
            syntax_valid:
              type: boolean
            mx_found:
              type: boolean
            is_disposable:
              type: boolean
            is_homograph:
              type: boolean
              description: Lookalike domain — mixed script or a spelling that folds onto a real ASCII domain.
            is_role_account:
              type: boolean
            is_free_provider:
              type: boolean
        cached:
          type: boolean
        request_id:
          type: string
        signals_unavailable:
          type: array
          items:
            type: string
          description: 'Signals that could not be measured on this request — e.g. ["tor", "vpn_providers"]. Absent entirely when every feed answered, so the happy-path shape is unchanged. Present means the score was built on incomplete data: a "clean" answer and a "we could not check" answer are otherwise identical.'
        domain:
          type: string
          example: gmail.com
        domain_age_days:
          nullable: true
        mx_provider:
          type: string
          example: Google Workspace
        mx_records:
          type: array
          items:
            type: string
            example: gmail-smtp-in.l.google.com.
        first_seen:
          nullable: true
        times_seen:
          type: integer
          example: 1
        abuse_reports:
          type: integer
          example: 0
        digital_footprint:
          type: object
          properties:
            has_gravatar:
              type:
              - boolean
              - 'null'
              example: false
              description: Whether the address has a public Gravatar. null means the check did not run — the request's time budget was exhausted — which is not the same as no avatar.
            gravatar_profile_url:
              nullable: true
            breach_count:
              nullable: true
            seen_in_breach:
              nullable: true
        processing_time_sec:
          type: number
          example: 0.097
        billable_lookups:
          type: integer
          example: 1
    RiskScore:
      type: integer
      minimum: 0
      maximum: 100
      description: 0 = clean, 100 = certain fraud.
    Verdict:
      type: string
      enum:
      - allow
      - review
      - block
      description: Recommended action. Thresholds move with `strictness`.
  parameters:
    Strictness:
      name: strictness
      in: query
      required: false
      schema:
        type: string
        enum:
        - lenient
        - balanced
        - strict
        default: balanced
      description: Shifts the allow/review/block thresholds. Signals and risk_score are unchanged.
  responses:
    RateLimited:
      description: Monthly quota or spend cap reached, or the 600 requests-per-minute rate limit exceeded.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        x-ratelimit-limit:
          description: Requests allowed per minute (600).
          schema:
            type: integer
        x-ratelimit-remaining:
          description: Requests left in the current minute.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Missing or malformed input.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, invalid, or revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your API key from https://www.layercall.com/get-key
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Same key, sent as `Authorization: Bearer <key>`.'
externalDocs:
  description: Guides and examples
  url: https://www.layercall.com/docs