Choose your API version.
Choose the version in Settings → API version, or send X-API-Version for a request. When neither version header is sent, the request uses your team's saved default. A request header overrides that setting. Keep the same keys, lookup URLs and authentication.
New teams start on the latest version, 2.3.0. Existing teams keep their saved default until an owner or admin upgrades it. Publishing a new API version does not upgrade existing teams.
Choose a version in your application
Use an exact supported version, such as 2.1.0. Configure the header once in your HTTP client so it accompanies every lookup.
curl "https://api.parseapi.com/name/Grace%20Hopper" \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-API-Version: 2.1.0"The request header takes precedence over the team default for that request. The X-API-Version response header identifies the exact version that answered, such as 2.1.0. The request does not change the saved default or any key.
Existing integrations can still send Parse-Version. If both headers are sent, their values must match.
The public, keyless IP and User-Agent self-lookups also accept the header. With neither version header, they use 1.0.0.
Use the 2.3 email contract
Send X-API-Version: 2.3.0 or upgrade your team's API version to 2.3.0 for requests without a version header. This selects independent email facts and the four verification assessments. Both GET /email/verify and the existing POST /email/verify remain supported. Requests pinned to 2.1 or 2.2 retain their existing responses and validators.
curl --get "https://api.parseapi.com/email/verify" \
--data-urlencode "email=sales+news@verification.example" \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-API-Version: 2.3.0"deliverable and catchall each mean true, false, or unknown (null). Neither rewrites the other. The response keeps all 17 fields in their existing order:
{
"email": "sales+news@verification.example",
"didyoumean": null,
"valid": true,
"free": false,
"disposable": false,
"role": true,
"domain": "verification.example",
"domain_type": null,
"domain_valid": true,
"deliverable": null,
"catchall": null,
"status": "unknown",
"reason": "unconfirmed",
"first_name": null,
"no_reply": false,
"tag": "news",
"mail_provider": "Google"
}- deliverable
- Delivery was confirmed, without a higher-priority concern. Confirmed delivery can coexist with a catchall domain.
- undeliverable
- Invalid format, a permanent mail-route failure, or an independent negative delivery verdict. A reported full mailbox receives its specific caution instead.
- risky
- A full mailbox, a disposable address without a definitive failure, or unresolved delivery on a catchall domain. Free and role addresses alone do not add risk.
- unknown
- No dependable delivery verdict or known concern. The reason is
temporary_failureonly when a transient failure was recorded; otherwise it isunconfirmed. Unconfirmed does not assert that a mailbox probe ran.
In 2.3, a supplied bounded invalid value is a successful check: HTTP 200 with valid: false. This applies to Email, Phone, Carrier, Caller, HLR, Name, Date and Address. Missing or wrong-shaped requests, invalid options, authentication failures and outages retain errors.
Current SDK and MCP releases stay on their documented API versions; the current line sends a 2.2 header even after a team upgrades its default to 2.3. Use direct HTTP or an existing transport override to select 2.3. Installing a package leaves the team default unchanged. The OpenAPI document includes the separate EmailVerification23 schema.
Upgrade the team default
Settings → API version controls requests with neither version header. Team owners and admins can review the release notes and explicitly confirm the upgrade. Applications that send a version keep using that version.
The saved default only moves forward; downgrades are not available. Leave it unchanged while older integrations without a version header depend on it. A request header can still select any supported version without changing the default. Requests already in progress can finish with their original version.
Read the matching reference
| API version | Contract | JSON reference |
|---|---|---|
| 2.3.0 | Independent Email facts, four verification assessments and successful negative checks. Select it with a request header or an upgraded team default. | Browse 2.3.0 |
| 2.2.0 | County routes and fields, with ISO codes where recorded. Select it with a request header or matching SDK. | Browse 2.2.0 |
| 2.1.0 | Plan detail at natural field homes, complete Carrier/HLR results and explicit Email verification. | Browse 2.1.0 |
| 2.0.0 | Simpler core responses, expanded deep detail and consistent local-name fields. | Browse 2.0.0 |
| 1.0.0 | Existing response fields and depth. | Browse 1.0.0 |
The API root and unversioned endpoint help show the latest reference. Versioned links stay on their named version, such as Carrier 1.0.0 and Carrier 2.0.0. Browsing the reference does not change your team's API version or lookup URLs.
A version preserves the documented contract, not a historical copy of the data. Current facts, observations and corrections continue to update.
Test in staging, then deploy
- Read the release notes and compare the references for the endpoints your app uses. Check field names, types, nulls, depth and error behavior.
- Pin the existing application to its current contract before preparing an upgrade. Keep that version alongside the application code so rollback restores both.
- In staging, set
X-API-Version: 2.1.0or use an SDK that pins that contract. Update field access and test the results. - Deploy the tested code and its version setting. Keep your existing production key. Verify the response header and the application's results.
In API 2.1, paid profiles include available plan detail at their resource's natural field paths. Existing explicit HTTP depth options retain their behavior. A list item owns its own fields; Weather measurements stay in current. Unavailable optional fields are omitted; included unknown values remain null. Carrier and HLR return the complete purchased result without a deep option. Email mailbox checks move to explicit GET /email/verify with an email query parameter.
// Earlier response
result.deep?.population
// API 2.1.0
result.populationDuring a rolling deployment, old and new instances can request their own contracts. While the earlier version is supported, rolling back the application also restores its version pin. A build with no version pin still depends on the team default.
Match your SDK and API version
SDK package numbers and API contract numbers are separate. New SDK releases target API 2.2 through the existing factories and methods. Version-pinned SDKs send their supported contract automatically, including X-API-Version: 2.2.0 in the new releases. Previously installed packages keep their documented contracts. Review old .deep and District field reads before upgrading. Installing a package leaves the team default unchanged. Keep the package version in your application's dependency lockfile and review its release notes before upgrading.
Previously published SDK/MCP 0.4.0 packages target API 2.0.0 and 0.3.2 packages target API 1.0.0, but omit the version header and depend on the team default. Installing a package leaves that saved default alone. Use a package whose documented API contract matches your application.
What a version number means
The release history records each version's changes. Read the 2.0.0 release notes or the 1.0.0 baseline.
- 1.0.1
- Patch: a compatible correction.
- 1.1.0
- Minor: compatible additions. Allow new response fields and documented open-string values.
- 2.0.0
- Major: changes that can require an application update, such as moving or removing fields.
An invalid or unsupported header value returns invalid_request (400). Use one exact version, not latest, a range or a list. A selected retired version returns api_version_retired (410). Neither error silently selects another contract.