Verification cases

When a registry or ICANN asks to verify the registrant of a domain, OpusDNS opens a verification case on that domain. The case records what has to be verified, by when, and how the request ended.

This guide explains the case, how it appears on domain reads, how to read a domain's case history, and how each registry opens and closes cases. For claims, methods and proofs, see Contact verification. To submit evidence, see the Attestation workflow.

The case

A domain has at most one active case per source. Today, OpusDNS opens cases for registry requests; the ICANN source is reserved for ICANN registrant verification.

Statuses

OPEN, SUBMITTED and OVERDUE are active statuses; the other statuses close the case.

Triggers

Close reasons

Deadlines

Each deadline is an object with a type and a date, listed in the order verification, dedelegation, deletion.

A registry either states the date to act by itself (nic.at, Internetstiftelsen) or only names the consequences (DENIC). In the second case, the verification deadline is the earliest consequence date, usually the dedelegation date:

"deadlines": [
  { "type": "verification", "date": "2026-11-20T13:01:05Z" },
  { "type": "dedelegation", "date": "2026-11-20T13:01:05Z" },
  { "type": "deletion", "date": "2027-02-18T13:01:05Z" }
]

When the registry moves or drops a date, the deadlines follow.

Active cases on domain reads

Every domain read, GET /v1/domains and GET /v1/domains/{domain_reference}, carries the domain's active cases in active_verifications:

{
  "domain_id": "domain_01jxe1nzrmf78scaqbkjx0va0f",
  "name": "example.at",
  "active_verifications": [
    {
      "verification_id": "domain_verification_01jxe1p4a2f7r8s9t0v1w2x3y4",
      "source": "REGISTRY",
      "trigger": "REGISTRY_REQUEST",
      "status": "OPEN",
      "claims": ["address", "name", "email"],
      "deadlines": [
        { "type": "verification", "date": "2026-11-05T08:00:00Z" }
      ],
      "contact_id": "contact_01jxe1nzrmf78scaqbkjx0va0f",
      "opened_on": "2026-10-22T09:14:03Z"
    }
  ]
}

• The list is always present, and empty when no case is active.
• It holds at most one case per source.
• It is ordered oldest first, by opened_on.
• It lists only the cases of the domain's current owner.

To list every domain with an active case, filter by the status tag:

curl --get "$OPUSDNS_API_BASE/v1/domains" \
  --header "X-Api-Key: $OPUSDNS_API_KEY" \
  --data-urlencode "status_tags=VERIFICATION_REQUIRED"

Case history

GET /v1/domains/{domain_reference}/verifications lists a domain's cases, active and closed, newest first. domain_reference is the domain's ID or name, and the endpoint needs the domains:read permission. It is paginated with page and page_size (default 10, at most 1000).

curl "$OPUSDNS_API_BASE/v1/domains/example.de/verifications" \
  --header "X-Api-Key: $OPUSDNS_API_KEY"

{
  "results": [
    {
      "verification_id": "domain_verification_01jxe1p4a2f7r8s9t0v1w2x3y4",
      "source": "REGISTRY",
      "trigger": "REGISTRY_REQUEST",
      "status": "SATISFIED",
      "claims": ["address", "name"],
      "deadlines": [
        { "type": "verification", "date": "2026-11-20T13:01:05Z" },
        { "type": "dedelegation", "date": "2026-11-20T13:01:05Z" },
        { "type": "deletion", "date": "2027-02-18T13:01:05Z" }
      ],
      "contact_id": "contact_01jxe1nzrmf78scaqbkjx0va0f",
      "opened_on": "2026-10-21T13:01:05Z",
      "closed_on": "2026-10-24T08:42:17Z",
      "close_reason": "REGISTRY_CLEARED"
    }
  ],
  "pagination": {
    "current_page": 1,
    "page_size": 10,
    "total_items": 1,
    "total_pages": 1,
    "has_next_page": false,
    "has_previous_page": false
  }
}

The history holds only the cases from while your organization owns the domain.

Status tag

The status tag VERIFICATION_REQUIRED is set on a domain exactly while it has an active case, and removed when the last active case closes. The registrant contact carries the same tag while one of its cases is active. See Status tags.

Events

Every change to a case logs a DOMAIN event of type VERIFICATION, whose object_id is the domain name:

The event's details carry the case ID, the source, the claims, the deadlines and the registrant. See Verification details.

When a registry asks to verify a contact rather than a domain (DENIC, DNS Belgium and Punktum dk can), OpusDNS also emails your organization. See Notifications.

Case lifecycle

• Registrant change. When the registrant changes, the active registry case moves to the new registrant with the same claims and deadlines. If the new registrant has the same email address or registry handle, the case continues. Otherwise the case closes as CANCELED with SUPERSEDED, and a new case opens with the trigger REGISTRANT_CHANGE.
• Domain deleted or transferred out. The domain's active cases close with DOMAIN_DELETED or TRANSFERRED_OUT. A transfer that does not complete closes its case with TRANSFER_ABORTED.
• Domain moved to another organization. The active cases move with the domain and stay open.

Registries

Attestations for registries that do not take them from OpusDNS are stored with the contact, but they do not close the case. The case closes when the registry reports the verification as done.

Related API reference

• GET /v1/domains/{domain_reference}/verifications
• GET /v1/domains/{domain_reference}
• GET /v1/domains
• POST /v1/contacts/{contact_id}/verifications/attest
• GET /v1/events