Migrate from API v1 to v2

API v2 is the recommended version of the Greip API. It uses the same dashboard API key and billing as v1, but different base URLs, routes, authentication rules, and JSON shapes. You can run v1 and v2 in parallel while you migrate endpoint by endpoint.

Use the version switcher at the top of these docs to compare API v2 (default) with API v1 (Legacy) reference pages side by side.

Why migrate to v2?

v2 is the default in these docs and the recommended target for new and existing integrations. You keep the same Greip account, API key, plans, and usage limits; you point traffic at https://v2.greipapi.com and update how you authenticate and parse responses.

Response time and observability

v2 is built for low-latency production traffic, including high-volume geo and scoring on checkout, signup, and login flows. Every successful v2 response includes execution_ms, so you can measure Greip processing time per request and compare v1 vs v2 in your own dashboards. Run both versions in staging with mode=test before you cut over.

Richer data for fraud and geo decisions

v2 responses expose more structure and decision-ready fields than the flat v1 geo object:

Area	What you gain on v2
Geo / IP lookup	Nested `data.ip` (including `bogon`) and `data.geo`; optional modules (`security`, `device`, `asn`, and others) from `params`
Custom rules	`custom_rules_applied` on geo lookups so you can see which dashboard rules fired
Security module	Clear snake_case flags such as `vpn_or_proxy`, `tor`, `bot`, `relay`, `hosting`, `is_blacklisted`
Email / phone / IP scoring	`risk_level`, `recommendation`, `reasons`, and `rules` instead of legacy validity-only flags
Domain lookup	Fields such as `is_disposable` and `is_forwarding` (also surfaced in email scoring where relevant)
BIN / IBAN	Validation helpers such as `is_valid` and `reason` on BIN lookup
Caller IP	`GET /ip` returns caller IP metadata with no API key (see Free Get-IP)

Clearer, more secure API design

Bearer-only authentication keeps keys out of query strings, server access logs, and referrer headers.
Path-based resources (/lookup/ip/{ip}, /score/email/{email}) match common REST client patterns and OpenAPI tooling.
Consistent JSON: snake_case fields and a boolean success flag make parsing and SDK generation straightforward.

Long-term support

New API improvements and documentation focus on v2. Legacy v1 remains available for existing integrations, but upgrading now avoids a larger migration later and lets you use the latest response fields and routes described in the API Reference. The sections below cover exact URL, auth, and field mappings for your upgrade.

Base URL

Version	Base URL	Notes
v1 (legacy)	`https://greipapi.com`	Legacy paths such as `/geoip`, `/lookup/ip`
v2 (recommended)	`https://v2.greipapi.com`	Updated REST-style paths (see endpoint map below)

All v2 endpoint URLs in the API Reference use the v2 host.

Authentication

Topic	v1	v2
API key location	Query `key=`, JSON body `key`, or `Authorization: Bearer`	`Authorization: Bearer` only
`key` in query or body	Works when the key is valid	Always `invalid_params` (104), even if the key itself is valid. Remove `key` from the URL/body and use Bearer.
Missing or wrong API key	`invalid_key` (101)	`invalid_key` (101) when authenticating with Bearer

Send the same key from your dashboard:

Authorization: Bearer <api_key>

See Authentication for key safety practices.

Request shape

Topic	v1	v2
JSON / query naming	Mostly camelCase (`userID`, `countryCode`)	snake_case (`user_id`, `country_code`)
Legacy aliases	N/A	Many v1 names still accepted temporarily during migration
Resource IDs	Often query parameters (`ip=`, `email=`)	Path parameters where documented (`/lookup/ip/{ip}`, `/score/email/{email}`)
Geo for caller IP	`GET /geoip`	`GET /geo/ip` (no `ip` argument)
Bulk geo	`GET /lookup/ip/bulk`	`GET /geo/ip/bulk`
IP scoring	`GET /lookup/ip/threats`	`GET /score/ip/{ip}`
Profanity	`GET /scoring/profanity`	`POST /score/text` with JSON body `{ "text": "..." }`
Payment fraud	`POST /scoring/payment`	`POST /score/payments`
Delete user data	`DELETE /account/users/delete`	`DELETE /account/users`

Shared query options (params, lang, format, mode, callback, source, user_id) behave like v1 unless noted on the v2 endpoint page. See Customize response modules and Development environment.

Response envelope

Success and error wrappers differ. Update any code that checks response.status === "success".

Field	v1	v2
Outcome	`"status": "success"` or `"status": "error"`	`"success": true` or `"success": false`
Timing	`executionTime` (integer, ms)	`execution_ms`
Errors	`status`, `code`, `type`, `description`	`success` (false), `code`, `type`, `description`

v2 success example:

{
  "success": true,
  "data": { },
  "execution_ms": 12
}

v2 error example:

{
  "success": false,
  "code": 101,
  "type": "invalid_key",
  "description": "The API Key is missing or invalid."
}

Error codes and types are the same across versions. See Error codes.

Geo and IP lookup `data` (largest schema change)

v1 returns a flat object (countryCode, continentName, ipType, optional modules at the top level). v2 returns nested objects:

v2 key	Purpose
`data.ip`	`address`, `version`, `numeric`, `bogon`
`data.geo`	Continent, country, region, city, coordinates, postal
`data.location`, `data.currency`, `data.asn`, `data.timezone`, `data.security`, `data.device`	Optional modules from `params`
`data.custom_rules_applied`	Custom rules metadata

Security module (query params=security, response key security):

v1 field	v2 field
`isProxy`	`vpn_or_proxy`
`proxyType`	`vpn_or_proxy_type`
`isTor`	`tor`
`isBot`	`bot`
`isRelay`	`relay`
`isHosting`	`hosting`
`blacklisted`	`is_blacklisted`

Bulk IP lookup: v2 data is an object whose keys are IP strings; each value has the same shape as a single IP lookup. Free Get-IP: v2 GET /ip returns data.ip metadata (no auth). See the Free Get-IP page.

Scoring and validation endpoints

Area	v1 behavior	v2 notes
Email / phone	Flat fields, legacy validity flags	`risk_level`, `recommendation`, `reasons`, `rules`; path-based email/phone
IP threats	Threat fields at top level	`score`, `risk_level`, `recommendation`, `rules` plus `security`
BIN / IBAN	camelCase fields	snake_case; BIN includes `is_valid`, `reason`
Payment	Similar fraud payload	Same business logic; snake_case body fields and `score/payments` URL

Use the matching v2 API Reference page for full request and response property lists.

Endpoint map (v1 path to v2)

v1 (legacy)	v2 (recommended)
`GET /geoip`	`GET /geo/ip`
`GET /lookup/ip`	`GET /lookup/ip/{ip}`
`GET /lookup/ip/bulk`	`GET /geo/ip/bulk`
`GET /lookup/asn`	`GET /lookup/asn/{asn}`
`GET /lookup/iban`	`GET /lookup/iban/{iban}`
`GET /lookup/bin`	`GET /lookup/bin/{bin}`
`GET /lookup/country`	`GET /lookup/countries/{country_code}`
`GET /lookup/domain`	`GET /lookup/domains/{domain}`
`GET /lookup/ip/threats`	`GET /score/ip/{ip}`
`GET /scoring/email`	`GET /score/email/{email}`
`GET /scoring/phone`	`GET /score/phone/{phone}`
`GET /scoring/profanity`	`POST /score/text`
`POST /scoring/payment`	`POST /score/payments`
`DELETE /account/users/delete`	`DELETE /account/users`
(varies)	`GET /ip` (free caller IP, no auth)

Migration checklist

Pick an endpoint

Start with read-only traffic (for example GeoIP or IP lookup) before payment or deletion APIs.

Change base URL and path

Point requests to https://v2.greipapi.com and the v2 path from the table above or API Reference.

Move authentication to Bearer

Remove key from query strings and JSON bodies for v2 calls.

Use mode=test

Set mode=test while you update parsers; v2 returns deterministic sample data in test mode like v1.

Update response parsing

Check success instead of status, read execution_ms, and map nested data fields (geo/security/scoring).

Ship gradually

Run v1 and v2 in parallel per route, compare responses in staging, then cut over and remove v1 calls.

What stays the same

Same Greip account, API key, plans, usage limits, and custom rules behavior for equivalent endpoints.
Same error codes and types (only the success wrapper field name changes on v2).
Response formats (JSON, XML, CSV, Newline) and JSONP callback where supported on the endpoint.

Need help?

Introduction and API Reference for v2.
Community on Slack for integration questions.

Get Started

API Features

Why migrate to v2?

Response time and observability

Richer data for fraud and geo decisions

Clearer, more secure API design

Long-term support

Base URL

Authentication

Request shape

Response envelope

Geo and IP lookup `data` (largest schema change)

Scoring and validation endpoints

Endpoint map (v1 path to v2)

Migration checklist

What stays the same

Need help?

​Why migrate to v2?

​Response time and observability

​Richer data for fraud and geo decisions

​Clearer, more secure API design

​Long-term support

​Base URL

​Authentication

​Request shape

​Response envelope

​Geo and IP lookup data (largest schema change)

​Scoring and validation endpoints

​Endpoint map (v1 path to v2)

​Migration checklist

​What stays the same

​Need help?

Why migrate to v2?

Response time and observability

Richer data for fraud and geo decisions

Clearer, more secure API design

Long-term support

Base URL

Authentication

Request shape

Response envelope

Geo and IP lookup `data` (largest schema change)

Scoring and validation endpoints

Endpoint map (v1 path to v2)

Migration checklist

What stays the same

Need help?