layercall-com Unified API

openapi: 3.2.0
info:
  title: LayerCall Unified 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: Unified
  description: One call across every signal on a signup.
paths:
  /v1/score/user:
    post:
      tags:
      - Unified
      operationId: scoreUser
      summary: Score a whole signup in one call
      description: Combines every signal you supply into a single risk score and verdict, with each component returned alongside. This is the endpoint most integrations use at registration or checkout.
      parameters:
      - $ref: '#/components/parameters/Strictness'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Supply any combination. Every field is optional, but at least one is required.
              properties:
                ip:
                  type: string
                  example: 185.220.101.5
                email:
                  type: string
                  format: email
                  example: test@mailinator.com
                phone:
                  type: string
                  example: '+14155552671'
                phone_country:
                  type: string
                  minLength: 2
                  maxLength: 2
                  example: US
                domain:
                  type: string
                  example: example.com
                device_id:
                  type: string
                  description: Fingerprint from fp.js.
                device_signals:
                  type: object
                  description: Optional browser characteristics from fp.js.
                device_automation:
                  type: object
                  description: Optional automation markers from fp.js.
      responses:
        '200':
          description: Combined score
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserScore'
          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'
    get:
      tags:
      - Unified
      operationId: scoreUserGet
      summary: Score a signup via query parameters
      description: Same as the POST form, for quick testing from a browser or curl.
      parameters:
      - name: ip
        in: query
        schema:
          type: string
      - name: email
        in: query
        schema:
          type: string
          format: email
      - name: phone
        in: query
        schema:
          type: string
      - name: phone_country
        in: query
        schema:
          type: string
          minLength: 2
          maxLength: 2
      - name: domain
        in: query
        schema:
          type: string
      - name: device_id
        in: query
        schema:
          type: string
      - $ref: '#/components/parameters/Strictness'
      responses:
        '200':
          description: Combined score
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserScore'
          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
    DeviceScore:
      type: object
      required:
      - device_id
      - risk_score
      - verdict
      - bot_probability
      - signals
      properties:
        device_id:
          type: string
        risk_score:
          $ref: '#/components/schemas/RiskScore'
        verdict:
          $ref: '#/components/schemas/Verdict'
        bot_probability:
          type: integer
          minimum: 0
          maximum: 100
          description: 'Reported separately from risk: plenty of automated traffic is legitimate.'
        signals:
          type: object
          properties:
            is_bot:
              type: boolean
              description: bot_probability >= 60.
            is_automated:
              type: boolean
            is_headless:
              type: boolean
            timezone_mismatch:
              type:
              - boolean
              - 'null'
              description: Browser timezone country differs from the IP's. Silent (false) when either is genuinely unknown; null when the country could NOT be resolved — a GeoIP outage — so no comparison was made.
            repeat_device:
              type: boolean
              description: Seen before across the LayerCall network.
        first_seen:
          type:
          - string
          - 'null'
          format: date-time
        times_seen:
          type: integer
        abuse_reports:
          type: integer
        request_id:
          type: string
          example: req_9319c108-cc66-4cbf-af64-37729a17c855
        processing_time_sec:
          type: number
          example: 0.031
        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
    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
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable message, safe to log.
    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
    UserScore:
      type: object
      required:
      - risk_score
      - verdict
      - components
      properties:
        risk_score:
          $ref: '#/components/schemas/RiskScore'
        verdict:
          $ref: '#/components/schemas/Verdict'
        components:
          type: object
          description: Each supplied signal, scored independently. Absent keys were not supplied.
          properties:
            ip:
              $ref: '#/components/schemas/IpScore'
            email:
              $ref: '#/components/schemas/EmailResult'
            phone:
              $ref: '#/components/schemas/PhoneResult'
            domain:
              $ref: '#/components/schemas/DomainResult'
            device:
              $ref: '#/components/schemas/DeviceScore'
        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.'
        summary:
          type: string
          example: Allowed (34/100) — Datacenter ASN and machine-generated handle, not enough to hold it.
        components_checked:
          type: array
          items:
            type: string
            example: email
        linkage:
          type: object
          properties:
            device_email_count:
              nullable: true
            email_device_count:
              type: integer
              example: 0
            email_ip_count:
              type: integer
              example: 1
            subnet_rate_1h:
              type: integer
              example: 17
            domain_rate_1h:
              type: integer
              example: 14
        actor:
          type: object
          properties:
            type:
              type: string
              example: unknown
            proven:
              type: boolean
              example: false
            basis:
              type: string
              example: none
            operator:
              nullable: true
            trigger:
              nullable: true
            detail:
              type: string
              example: No signature and no device fingerprint. Drop fp.js on the page, or pass the agent's signed request, to get an answer here.
        top_signals:
          type: array
          items:
            type: string
            example: 'ip: datacenter asn'
        processing_time_sec:
          type: number
          example: 0.033
        billable_lookups:
          type: integer
          example: 0
    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