Verify Portal Domain

Beta

POST/v1/settings/portal-domains/{id}/actions/verify

Idempotent with Idempotency-Key header. Learn more

Re-checks a portal domain against the serving provider and advances its status.

Run this after publishing the DNS records, and keep polling it: the domain stays pending while its records are missing or misconfigured, moves to securing once they are correct and its TLS certificate is being issued, and reaches verified only once that certificate is live and the portal answers on the domain. The response carries the updated domain along with the records still required. Verifying an already-verified domain returns it unchanged.

Permissions requiredValues:self:update

The role behind your API key or agent must grant every one of these permissions.

idstring

Portal domain ID.

idstring

Portal domain ID.

objectstringenumValues:portal_domain

Resource type identifier.

domainstring

The fully-qualified domain name (e.g. shop.acme.com).

statusstringenumValues:pendingsecuringverified

How far the domain has progressed towards serving the portal.

pending: the domain is waiting on DNS. Publish the listed records, then run the verify action.
securing: DNS is correct and the TLS certificate is being issued. The portal is not yet reachable over HTTPS.
verified: the certificate is live and the portal is served on the domain.
failed: the domain was rejected and cannot be used.

dns_recordslistnullable

The DNS records that must be published for the domain to route to the portal and verify.

The list is refreshed from the serving provider every time the domain is created or verified. It always contains the routing record; ownership records appear only while a verification challenge is outstanding.

objectstringenumValues:list

Resource type identifier.

page_infoobject

Pagination metadata.

next_page_urlstringnullable

Relative URL that fetches the next page of results.

previous_page_urlstringnullable

Relative URL that fetches the previous page of results.

has_next_pageboolean

Whether more results exist after this page.

has_prev_pageboolean

Whether results exist before this page.

dataarray of dns_record

Resources in this page.

objectstringenumValues:dns_record

Resource type identifier.

typestringenumValues:CNAMEATXT

The kind of DNS record to publish.

CNAME: points a subdomain at the portal's serving infrastructure.
A: points an apex domain at the portal's serving infrastructure.
TXT: carries an ownership-verification challenge.

namestring

Record name (host) to publish.

valuestring

Record value to publish.

reasonstringenumValues:routingownership

Why the record must be published.

routing: the record points traffic at the portal's serving infrastructure.
ownership: the record proves control of a domain that is already claimed elsewhere.

verified_atstring (date-time)nullable

When the domain became fully verified — its TLS certificate live and the portal serving on it.

created_atstring (date-time)

Creation timestamp.

updated_atstring (date-time)

Last updated timestamp.

Responses

200

Successful response for Verify Portal Domain

Verify Portal Domain

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const portalDomain = await client.settings.portalDomains.actions.verify('podn_ml44z5ggf169');

console.log(portalDomain.id);

import OpenMRP from '@openmrp/sdk';

const client = new OpenMRP({
  bearerToken: 'YOUR_API_KEY', // Your API key goes here
});

const portalDomain = await client.settings.portalDomains.actions.verify('podn_ml44z5ggf169');

console.log(portalDomain.id);

200 example

{
  "id": "podn_ml44z5ggf169",
  "object": "portal_domain",
  "domain": "shop.acme.com",
  "status": "pending",
  "dns_records": {
    "object": "list",
    "page_info": {
      "next_page_url": null,
      "previous_page_url": null,
      "has_next_page": false,
      "has_prev_page": false
    },
    "data": [
      {
        "object": "dns_record",
        "type": "CNAME",
        "name": "shop.acme.com",
        "value": "cname.vercel-dns.com",
        "reason": "routing"
      }
    ]
  },
  "verified_at": null,
  "created_at": "2026-05-10T00:00:00Z",
  "updated_at": "2026-05-10T00:23:00Z"
}

{
  "id": "podn_ml44z5ggf169",
  "object": "portal_domain",
  "domain": "shop.acme.com",
  "status": "pending",
  "dns_records": {
    "object": "list",
    "page_info": {
      "next_page_url": null,
      "previous_page_url": null,
      "has_next_page": false,
      "has_prev_page": false
    },
    "data": [
      {
        "object": "dns_record",
        "type": "CNAME",
        "name": "shop.acme.com",
        "value": "cname.vercel-dns.com",
        "reason": "routing"
      }
    ]
  },
  "verified_at": null,
  "created_at": "2026-05-10T00:00:00Z",
  "updated_at": "2026-05-10T00:23:00Z"
}

Verify Portal Domain

Authorization

Path Parameters

Returns

Responses