Appearance

Domain Verification API ​

Verify domain ownership via DNS for email sending, custom hostnames, webhooks, and more.

Endpoints ​

MethodPathDescription
POST/v1/domain-verification/domainsRegister domain
GET/v1/domain-verification/domainsList domains
GET/v1/domain-verification/domains/{domain_id}Get domain details
PATCH/v1/domain-verification/domains/{domain_id}Revoke domain
DELETE/v1/domain-verification/domains/{domain_id}Delete domain
POST/v1/domain-verification/domains/{domain_id}/verifyVerify domain
GET/v1/domain-verification/domains/{domain_id}/historyGet verification history

POST /v1/domain-verification/domains ​

Register domain

Register a domain for verification. Returns DNS setup instructions.

After registration, add the DNS record to your domain to prove ownership. Then call the verify endpoint to check.

Purposes:

  • email - For sending email from this domain
  • custom_host - For custom hostnames/CNAMEs
  • webhook - For webhook endpoint verification
  • link_branding - For branded tracking links
  • verify_channel - For communication channel verification
  • other - General domain ownership verification

Request Body:

FieldTypeDescription
domainstringRequired. Domain to verify (e.g., example.com)
purposestringRequired. Values: email, custom_host, webhook, link_branding, verify_channel, other
verification_methodstringValues: DNS_TXT, DNS_CNAME
metadataobjectOptional metadata

Example:

json
{
  "domain": "example.com",
  "purpose": "email",
  "verification_method": "DNS_TXT"
}

Response:

FieldTypeDescription
idstring
domainstringDomain name (normalized to lowercase/punycode)
purposestringValues: email, custom_host, webhook, link_branding, verify_channel, other
statusstringValues: pending, verified, failed, revoked
verification_methodstringINTERNAL_DNS_AUTHORITY when the domain is hosted in WAYSCloud DNS and verified without a record Values: DNS_TXT, DNS_CNAME, INTERNAL_DNS_AUTHORITY
verification_tokenstringToken to add to the DNS record; null for INTERNAL_DNS_AUTHORITY
instructionsobjectDNS setup instructions
internal_dns_zone_idstringYour WAYSCloud DNS zone, when verified through INTERNAL_DNS_AUTHORITY
dns_challengestringSame as verification_token
dns_record_namestringSame as instructions.record_name
verification_attemptsinteger
verified_atstring
last_checked_atstring
failed_reasonstring
created_atstring
updated_atstring
metadataobject

Example:

bash
curl -X POST https://api.wayscloud.services/v1/domain-verification/domains \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "domain": "example.com",
  "purpose": "email",
  "verification_method": "DNS_TXT"
}'

Response:

json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "domain": "example.com",
  "purpose": "email",
  "status": "pending",
  "verification_method": "DNS_TXT",
  "verification_token": "abc123xyz789",
  "instructions": {
    "method": "DNS_TXT",
    "record_type": "TXT",
    "record_name": "_wayscloud.example.com",
    "record_value": "wayscloud-domain-verification=abc123xyz789",
    "ttl_recommendation": 300,
    "example_bind": "_wayscloud.example.com. 300 IN TXT \"wayscloud-domain-verification=abc123xyz789\"",
    "auto_verified": false,
    "message": null,
    "cname_record_name": null,
    "cname_record_value": null,
    "cname_example_bind": null
  },
  "internal_dns_zone_id": null,
  "dns_challenge": "abc123xyz789",
  "dns_record_name": "_wayscloud.example.com",
  "verification_attempts": 0,
  "verified_at": null,
  "last_checked_at": null,
  "failed_reason": null,
  "created_at": "2025-12-08T10:00:00Z",
  "updated_at": null,
  "metadata": {}
}

GET /v1/domain-verification/domains ​

List domains

List all domain verifications for your account. Supports filtering by purpose and status.

Response:

FieldTypeDescription
domainsarray
totalinteger
pageinteger
page_sizeinteger

Example:

bash
curl https://api.wayscloud.services/v1/domain-verification/domains \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET"

Response:

json
{
  "domains": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "domain": "example.com",
      "purpose": "email",
      "status": "verified"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "domain": "app.example.com",
      "purpose": "custom_host",
      "status": "pending"
    }
  ],
  "total": 2,
  "page": 1,
  "page_size": 20
}

GET /v1/domain-verification/domains/ ​

Get domain details

Get details for a specific domain verification including DNS instructions.

Response:

FieldTypeDescription
idstring
domainstringDomain name (normalized to lowercase/punycode)
purposestringValues: email, custom_host, webhook, link_branding, verify_channel, other
statusstringValues: pending, verified, failed, revoked
verification_methodstringINTERNAL_DNS_AUTHORITY when the domain is hosted in WAYSCloud DNS and verified without a record Values: DNS_TXT, DNS_CNAME, INTERNAL_DNS_AUTHORITY
verification_tokenstringToken to add to the DNS record; null for INTERNAL_DNS_AUTHORITY
instructionsobjectDNS setup instructions
internal_dns_zone_idstringYour WAYSCloud DNS zone, when verified through INTERNAL_DNS_AUTHORITY
dns_challengestringSame as verification_token
dns_record_namestringSame as instructions.record_name
verification_attemptsinteger
verified_atstring
last_checked_atstring
failed_reasonstring
created_atstring
updated_atstring
metadataobject

Example:

bash
curl https://api.wayscloud.services/v1/domain-verification/domains/{domain_id} \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET"

Response:

json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "domain": "example.com",
  "purpose": "email",
  "status": "pending",
  "verification_method": "DNS_TXT",
  "verification_token": "abc123xyz789",
  "instructions": {
    "method": "DNS_TXT",
    "record_type": "TXT",
    "record_name": "_wayscloud.example.com",
    "record_value": "wayscloud-domain-verification=abc123xyz789",
    "ttl_recommendation": 300,
    "example_bind": "_wayscloud.example.com. 300 IN TXT \"wayscloud-domain-verification=abc123xyz789\"",
    "auto_verified": false,
    "message": null,
    "cname_record_name": null,
    "cname_record_value": null,
    "cname_example_bind": null
  },
  "internal_dns_zone_id": null,
  "dns_challenge": "abc123xyz789",
  "dns_record_name": "_wayscloud.example.com",
  "verification_attempts": 0,
  "verified_at": null,
  "last_checked_at": null,
  "failed_reason": null,
  "created_at": "2025-12-08T10:00:00Z",
  "updated_at": null,
  "metadata": {}
}

PATCH /v1/domain-verification/domains/ ​

Revoke domain

Revoke a verified domain. Only status change to revoked is allowed.

Request Body:

FieldTypeDescription
statusstringValues: revoked
metadataobjectReplace the metadata stored on the verification

Response:

FieldTypeDescription
idstring
domainstringDomain name (normalized to lowercase/punycode)
purposestringValues: email, custom_host, webhook, link_branding, verify_channel, other
statusstringValues: pending, verified, failed, revoked
verification_methodstringINTERNAL_DNS_AUTHORITY when the domain is hosted in WAYSCloud DNS and verified without a record Values: DNS_TXT, DNS_CNAME, INTERNAL_DNS_AUTHORITY
verification_tokenstringToken to add to the DNS record; null for INTERNAL_DNS_AUTHORITY
instructionsobjectDNS setup instructions
internal_dns_zone_idstringYour WAYSCloud DNS zone, when verified through INTERNAL_DNS_AUTHORITY
dns_challengestringSame as verification_token
dns_record_namestringSame as instructions.record_name
verification_attemptsinteger
verified_atstring
last_checked_atstring
failed_reasonstring
created_atstring
updated_atstring
metadataobject

Example:

bash
curl -X PATCH https://api.wayscloud.services/v1/domain-verification/domains/{domain_id} \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "revoked"
}'

Response:

json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "domain": "example.com",
  "purpose": "email",
  "status": "pending",
  "verification_method": "DNS_TXT",
  "verification_token": "abc123xyz789",
  "instructions": {
    "method": "DNS_TXT",
    "record_type": "TXT",
    "record_name": "_wayscloud.example.com",
    "record_value": "wayscloud-domain-verification=abc123xyz789",
    "ttl_recommendation": 300,
    "example_bind": "_wayscloud.example.com. 300 IN TXT \"wayscloud-domain-verification=abc123xyz789\"",
    "auto_verified": false,
    "message": null,
    "cname_record_name": null,
    "cname_record_value": null,
    "cname_example_bind": null
  },
  "internal_dns_zone_id": null,
  "dns_challenge": "abc123xyz789",
  "dns_record_name": "_wayscloud.example.com",
  "verification_attempts": 0,
  "verified_at": null,
  "last_checked_at": null,
  "failed_reason": null,
  "created_at": "2025-12-08T10:00:00Z",
  "updated_at": null,
  "metadata": {}
}

DELETE /v1/domain-verification/domains/ ​

Delete domain

Delete a domain verification. This is a soft delete - records are preserved for audit.

Response:

FieldTypeDescription
messagestring

Example:

bash
curl -X DELETE https://api.wayscloud.services/v1/domain-verification/domains/{domain_id} \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET"

Response:

json
{
  "message": "Domain verification deleted"
}

POST /v1/domain-verification/domains/{domain_id}/verify ​

Verify domain

Trigger a DNS verification check for the domain.

Performs DNS lookup to verify that the required record exists. Returns the verification result immediately.

DNS record must be in place before calling this endpoint.

Response:

FieldTypeDescription
idstring
domainstring
statusstring
verifiedboolean
messagestring
dns_records_foundarray
checked_atstring

Example:

bash
curl -X POST https://api.wayscloud.services/v1/domain-verification/domains/{domain_id}/verify \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET"

Response:

json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "domain": "example.com",
  "status": "verified",
  "verified": true,
  "message": "Domain verified successfully",
  "dns_records_found": [
    "wayscloud-domain-verification=abc123xyz789"
  ],
  "checked_at": "2025-12-08T10:30:00Z"
}

GET /v1/domain-verification/domains/{domain_id}/history ​

Get verification history

Get the verification history for a domain including all check attempts and status changes.

Response example:

json
[
  {
    "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "event_type": "check_completed",
    "previous_status": "pending",
    "new_status": "verified",
    "dns_response": {
      "records_found": true,
      "actual_values": [
        "wayscloud-domain-verification=abc123xyz789"
      ]
    },
    "performed_by": "api",
    "created_at": "2025-12-08T10:30:00Z"
  }
]

Example:

bash
curl https://api.wayscloud.services/v1/domain-verification/domains/{domain_id}/history \
  -H "X-API-Key: wayscloud_pat_abc12_YOUR_SECRET"

Response:

json
[
  {
    "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "event_type": "check_completed",
    "previous_status": "pending",
    "new_status": "verified",
    "dns_response": {
      "records_found": true,
      "actual_values": [
        "wayscloud-domain-verification=abc123xyz789"
      ]
    },
    "performed_by": "api",
    "created_at": "2025-12-08T10:30:00Z"
  }
]