What this guide covers
This guide covers:- How name.com contact verification works (timelines, email types, and how to observe verification status).
- How to integrate status updates via the
contact.verification.status_changewebhook. - What changes when you handle verification yourself (approved/contracted resellers): logging requirements, required email content, and account-restricted endpoints.
GET /core/v1/contacts/unverified→ List Unverified ContactsPOST /core/v1/contacts/verify/{verificationId}→ Verify ContactPOST /core/v1/contacts/verify/{verificationId}:resend→ Resend Verification Emailcontact.verification.status_change→ Contact Verification Status Change webhook
When this guide applies
You should follow this guide if you do any of the following:- Need to understand when verification emails are sent and what the 15-day verification timeline means for domains.
- Want to monitor verification status in your product using endpoints and/or webhooks.
- Have an approved / contracted setup where you send your own verification emails and/or sync verified state to name.com.
For most reseller integrations, name.com sends the ICANN-required verification emails for you. If you want to handle verification emails (or verification state syncing) yourself, this is typically an approved / contracted workflow so we can confirm you will meet ICANN requirements (including logging and required email content).
Part 1: How contact verification works (most resellers)
This section is for most resellers. It explains how verification works, the ICANN-required email timeline, and how to observe verification status in your integration.What “verification” means
Verification means the registrant has demonstrated control of the email address (or phone number, where applicable) associated with the registrant contact. If verification is not completed within the required window, a verification lock will be applied and the domain will stop resolving. See Understanding Domain Locks.ICANN verification email timeline (what gets sent)
These requirements apply when ICANN requires verification of the registrant contact (typically email).| Trigger | Required content | |
|---|---|---|
| Registrant verification (expires in 15 days) | Domain registration, incoming transfer with an unverified registrant email, or changes to the registrant’s email, name, or organization | A clear statement that ICANN requires verification of the registrant contact. A unique verification link or token the user must click or use. A warning that failure to verify within 15 days will result in domain suspension. |
| Verification reminder | Before the 15‑day window expires | A clear statement that ICANN requires verification of the registrant contact. A unique verification link or token the user must click or use. A warning that failure to verify within 15 days will result in domain suspension, including how many days remain. |
| Verification expired / suspension notice | Day 16+ (when the domain is disabled) | Notification that the domain is suspended and the reason (failure to verify registrant contact). Mention that this is ICANN-required. Provide a path to resolve (for example: a verification link). |
For new registrants, you must also communicate:
The Organization field in your domain’s contact details relates to legal ownership. If this field contains information, the listed organization is considered the legal “Registered Name Holder” (domain owner).
How to observe verification status
GET /core/v1/contacts/unverified→ List Unverified Contacts
After a new domain registration or contact change, unverified contacts may take up to ~10 minutes to appear in the API. Build your UI and automation with this delay in mind.
Status updates via webhook
To avoid polling, subscribe to the contact verification status webhook:- Event:
contact.verification.status_change - Reference: Contact Verification Status Change webhook
Part 2: Handling your own verification (approved / contracted resellers)
This section is for resellers who have agreed to additional terms and are handling contact verification themselves. This typically includes additional compliance requirements and may include account-restricted endpoint access. If you want to discuss enablement, email [email protected].Logging requirements
If you send your own verification emails (and disable name.com-sent emails) and/or use account-restricted contact verification endpoints, you must maintain the following logs.Email logs (ICANN verification emails)
Keep logs for every verification-related email you send:- Domain
- Email send event
- Timestamp
- Recipient
- Subject
- Content (or a reference to a stored template + the rendered variables used)
Verification logs
Keep logs that show how you verified the registrant contact off-platform:- Domain and the
verificationIdbeing verified - Verification method (email or phone)
- Email address or phone number used for verification
- Verification timestamp
Retention and access
- Retention: All required logs must be kept for the duration of the domain registration and for at least two (2) years thereafter.
- Access: name.com may request access to these logs at any time.
What you must provide before enablement
Before we grant you access to programmatic contact verification and allow you to disable name.com-sent emails, you must provide:- Sample logs demonstrating the format above
- Sample email copies (templates and/or example sends)
Endpoint usage & policy
Some Contact Verification endpoints are account-restricted. The reference pages will call this out, and you can email [email protected] to request access.List Unverified Contacts
Purpose: Identify contacts that require verification under ICANN rules.- Endpoint:
GET /core/v1/contacts/unverified→ List Unverified Contacts - Typical use: Drive your own verification flow (email or phone) before calling Verify Contact (if approved).
Verify Contact
Purpose: Programmatically marks a contact’s email address as verified for domains under your account (to satisfy ICANN contact-verification requirements).- Endpoint:
POST /core/v1/contacts/verify/{verificationId}→ Verify Contact - Availability: Account-restricted (approved reseller accounts only)
- Retry safety: Send
X-Idempotency-Keyso retries are safe
This endpoint is account-restricted. Enablement is typically associated with handling your own verification process and meeting ICANN compliance requirements (logging and required email content).
Allowed use
- You are the reseller of record and the contact belongs to a domain in your account.
- You have already verified control of the email address or phone number off-platform (for example: your own email verification link flow) and are syncing that verified state to name.com.
- You are acting on behalf of the registrant and have their permission to mark the contact as verified.
Not allowed
- Verifying contacts you don’t manage
- Marking contacts verified without actually verifying the email/phone
- Acting without registrant authorization
Enforcement
We may suspend access to this endpoint if we detect misuse.Resend the initial verification email
If a contact verification is pending and you need to resend the initial verification email, use:POST /core/v1/contacts/verify/{verificationId}:resend→ Resend Verification Email
This endpoint is throttled (for example: per-
verificationId and per-account rate limits). See the endpoint reference for the current limits and the nextEligibleAt cooldown timestamp returned in responses.