Skip to content
User Guide
Integrations
REST API

REST API

Overview

The Evident REST API lets you enrich IP addresses programmatically — from your server-side code, data pipeline, or any HTTP client. It supports single-IP lookups and batch enrichment.

Base URL: https://api.useevident.com

Authentication

All API requests require an API key passed as a Bearer token in the Authorization header.

Authorization: Bearer <your-api-key>

API keys are generated in Settings → API in the Evident dashboard.

Rate limits

Plan Rate limit
Free 1 req/sec (burst: 5)
Starter 5 req/sec (burst: 20)
Growth —
Professional —
Custom 100 req/sec (burst: 500)

When you exceed the rate limit, the API returns 429 Too Many Requests. The response includes a Retry-After header indicating when to retry.

Endpoints

Single IP lookup 

GET /api/v1/lookup?ip={ip_address}

Parameters

Parameter Type Required Description
ip string Yes The IP address to enrich

Example request

curl -H "Authorization: Bearer <your-api-key>" \
  "https://api.useevident.com/api/v1/lookup?ip=203.0.113.42"

Example response

{
  "ip": "203.0.113.42",
  "business_name": "Acme Corp",
  "org_name": "Acme Corporation Ltd",
  "domain": "acmecorp.com",
  "industry": "technology",
  "country": "US",
  "region": "California",
  "city": "San Francisco",
  "confidence": 0.87,
  "quality": 0.91,
  "is_cloud": false,
  "is_cdn": false,
  "is_vpn": false,
  "is_proxy": false,
  "is_hosting": false,
  "cached": true,
  "quota": {
    "limit": 5000,
    "used": 1247,
    "remaining": 3753,
    "resets_at": "2026-03-30T00:00:00Z"
  }
}

The cached field indicates whether this result was served from cache. The quota object reflects your monthly tracked accounts usage.

Batch enrichment 

POST /api/v1/batch

Submit up to 512 IP addresses in a single request. Exceeding this limit returns HTTP 400. Batch jobs are queued and processed asynchronously.

Request body

{
  "ips": ["203.0.113.1", "203.0.113.2", "203.0.113.3"]
}

Response

{
  "job_id": "job_abc123",
  "status": "queued",
  "ip_count": 3
}

Poll for results using the job ID:

GET /api/v1/batch/{job_id}

Quota in API responses

Every single-lookup response includes current tracked accounts usage in the quota object. Monitor remaining to avoid hitting your monthly limit unexpectedly. See Quotas for plan limits.

Error responses

HTTP status Meaning
400 Bad Request Missing or malformed parameter, or batch exceeds 512 IPs
401 Unauthorized Missing or invalid API key
429 Too Many Requests Rate limit exceeded or monthly account limit reached
500 Internal Server Error Unexpected server error — retry with backoff

CLI tool

Evident also ships a command-line tool for bulk CSV enrichment. See CLI for installation and usage.

Need help?

Contact support@useevident.com with your API key and request details if you’re seeing unexpected errors.

ClayCLI