IPinfo privacy detection extended API

openapi: 3.2.0
info:
  description: Official OpenAPI Specification for IPinfo's comprehensive IP intelligence API.
  version: 1.0.0
  title: IPinfo.io OpenAPI Specification privacy detection extended…
  contact:
    name: IPinfo
    email: support@ipinfo.io
    url: https://ipinfo.io/
servers:
- url: https://ipinfo.io/
- url: https://v6.ipinfo.io/
- url: https://api.ipinfo.io/
tags:
- name: privacy detection extended
  description: Privacy Detection Extended API with detailed methodologies.
  externalDocs:
    description: Find more info here
    url: https://ipinfo.io/developers/privacy-extended-api
paths:
  /{ip}/privacy_extended:
    get:
      tags:
      - privacy detection extended
      summary: IPinfo Returns Extended Privacy Detection Information with Detailed…
      description: 'The Privacy Detection Extended API provides detection methodology metadata to support risk scoring, confidence metrics, and IP reputation aspects.

        Uses multi-modal detection methods including internet measurement, IP behavior analysis, and internet records metadata.

        Includes detailed flags for VPN, proxy, Tor, relay, hosting, and service identification with confidence metrics.'
      operationId: getPrivacyExtendedByIp
      security:
      - BasicAuth: []
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/Ip'
      responses:
        '200':
          $ref: '#/components/responses/PrivacyExtended'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    PrivacyExtended:
      description: Privacy Detection Extended response with detailed methodologies.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PrivacyExtendedResponse'
    TooManyRequests:
      description: Allocated API rate limit has been reached for the token. The user will be prompted with options to increase their API limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error429'
    InternalServerError:
      description: Internal server error or server unavailable.
      content:
        text/plain:
          schema:
            $ref: '#/components/schemas/Error500'
    NotFound:
      description: Wrong ip. Please provide a valid IP address.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error404'
    Forbidden:
      description: Unknown token or invalid permission. We return the same error for blocking malicious IP addresses as well.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error403'
  schemas:
    PrivacyExtendedResponse:
      type: object
      required:
      - vpn
      - proxy
      - tor
      - relay
      - hosting
      - service
      properties:
        vpn:
          type: boolean
          description: Indicates Virtual Private Network (VPN) service exit node IP address
          example: true
        proxy:
          type: boolean
          description: Indicates an open web proxy IP address
          example: false
        tor:
          type: boolean
          description: Indicates a Tor (The Onion Router) exit node IP address
          example: false
        relay:
          type: boolean
          description: Indicates a location-preserving anonymous relay service
          example: false
        hosting:
          type: boolean
          description: Indicates a hosting/cloud service/data center IP address
          example: true
        service:
          type: string
          description: Name of the privacy service provider - includes VPN, Proxy, and Relay service provider names
          example: NordVPN
        confidence:
          type: integer
          minimum: 1
          maximum: 3
          description: The level of confidence attributed to the best source associated with this range. Level 3 - Direct observation of commercial use (vpn_config). Level 2 - Direct observation of VPN software running on the range (census) + registrar information associated with VPNs or specific providers OR highly convincing device activity. Level 1 - Direct observation of VPN software running on the range (census) without known association to specific providers or VPNs in general OR suspicious device data not associated with hosting ranges
          example: 3
        coverage:
          type: number
          minimum: 0
          maximum: 1
          description: For inferred ranges, represents the proportion of the range (in IP count) that we saw direct evidence of VPN activity on. For IPs/ranges we've fully directly observed VPN evidence on, this value is 1.0
          example: 1.0
        census:
          type: boolean
          description: Ranges where we've observed VPN software/ports on; we run scans on ports and protocols commonly associated with VPN software. Ranges with the census flag are those where these scans obtained positive results
          example: false
        census_ports:
          type: array
          items:
            type: integer
          description: The ports we've gotten positive results for when running our VPN detection census
          example: []
        device_activity:
          type: boolean
          description: Ranges on which we've observed device activity compatible with VPN usage (outside of known infrastructure area; simultaneous use around a large area; pingable and/or associated with hosting providers)
          example: false
        inferred:
          type: boolean
          description: Whether the range associated with the record is the result of direct observation or inference based on neighboring IPs
          example: false
        vpn_config:
          type: boolean
          description: Ranges where we confirmed VPN activity by directly running VPN software from almost 200 different providers and collecting exit IPs
          example: false
        whois:
          type: boolean
          description: Ranges where we've observed VPN software/ports on AND have a WHOIS association with either VPNs in general or specific VPN providers
          example: false
        first_seen:
          type: string
          format: date
          description: Date when the activity on an anonymous IP address was first observed. Date in YYYY-MM-DD format, ISO-8601. Within the 3-month lookback period
          example: '2025-09-19'
        last_seen:
          type: string
          format: date
          description: Date when the activity on an anonymous IP address was last/recently observed. Date in YYYY-MM-DD format, ISO-8601
          example: '2025-11-06'
    Error429:
      type: object
      required:
      - title
      - message
      properties:
        title:
          type: string
          example: Rate limit exceeded
        message:
          type: string
          example: Upgrade to increase your usage limits at https://ipinfo.io/pricing, or contact us via https://ipinfo.io/support
    Error500:
      type: string
      example: Internal server error
    Error403:
      type: object
      required:
      - title
      - message
      properties:
        title:
          type: string
          example: Unknown token
        message:
          type: string
          example: Please ensure you've entered your token correctly. Refer to https://ipinfo.io/developers for details, or contact us at support@ipinfo.io for help
    Error404:
      type: object
      required:
      - status
      - error
      properties:
        status:
          type: integer
          example: 404
        error:
          type: object
          required:
          - title
          - message
          properties:
            title:
              type: string
              example: Wrong ip
            message:
              type: string
              example: Please provide a valid IP address
  parameters:
    Ip:
      name: ip
      in: path
      description: A single IPv4 or IPv6 IP address.
      required: true
      schema:
        type: string
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer
    ApiKeyAuth:
      type: apiKey
      in: query
      name: token
externalDocs:
  description: IPinfo Developers Portal / Documentation
  url: https://ipinfo.io/developers