IPinfo residential proxy detection 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 residential proxy detection…
  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: residential proxy detection
  description: Residential Proxy Detection API.
  externalDocs:
    description: Find more info here
    url: https://ipinfo.io/developers/residential-proxy-api
paths:
  /{ip}/resproxy:
    get:
      tags:
      - residential proxy detection
      summary: IPinfo Returns Residential Proxy Detection Information for the Selected IP
      description: 'The Residential Proxy Detection API provides detailed insights into IP addresses associated with residential, mobile, or datacenter proxy networks.

        This includes activity patterns (last seen date, percentage of days active), and proxy service identification.

        Services are suffixed with `_mobile` for carrier/mobile proxies or `_datacenter` for datacenter proxies.'
      operationId: getResidentialProxyByIp
      security:
      - BasicAuth: []
      - BearerAuth: []
      - ApiKeyAuth: []
      parameters:
      - $ref: '#/components/parameters/Ip'
      responses:
        '200':
          $ref: '#/components/responses/ResidentialProxy'
        '404':
          $ref: '#/components/responses/NotFound'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  responses:
    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'
    ResidentialProxy:
      description: Residential Proxy detection response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResidentialProxyResponse'
  schemas:
    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
    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
    ResidentialProxyResponse:
      type: object
      required:
      - ip
      - last_seen
      - percent_days_seen
      - service
      properties:
        ip:
          type: string
          description: The IPv4 or IPv6 address associated with a residential proxy
          example: 175.107.211.204
        last_seen:
          type: string
          format: date
          description: The last recorded date when the residential proxy IP was active (YYYY-MM-DD, UTC)
          example: '2025-06-24'
        percent_days_seen:
          type: integer
          minimum: 0
          maximum: 100
          description: The percentage of days the IP was active in the last 7-day period
          example: 14
        service:
          type: string
          description: The name of the residential proxy service. Suffixed with _mobile for carrier/mobile or _datacenter for datacenter proxies
          example: ipfoxy
  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