List Portal Domains

Beta

GET/v1/settings/portal-domains

This endpoint is idempotent. Learn more

Lists the account's portal domains.

An account can only hold one custom portal domain, so this returns either zero or one entry. Reading it is the usual way to discover whether a domain is connected and what state it is in.

Permissions requiredValues:self:read

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

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 portal_domain

Resources in this page.

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 List Portal Domains

List Portal Domains

import OpenMRP from '@openmrp/sdk';

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

const listPortalDomain = await client.settings.portalDomains.list();

console.log(listPortalDomain.data);

import OpenMRP from '@openmrp/sdk';

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

const listPortalDomain = await client.settings.portalDomains.list();

console.log(listPortalDomain.data);

200 example

{
  "object": "list",
  "page_info": {
    "next_page_url": "/v1/settings/portal-domains?cursor=eyJjIjoiMjAyNi0wNS0xMFQwMDowMDowMFoiLCJzIjoicG9kbl9tbDQ0ejVnZ2YxNjkiLCJkIjoiZiJ9.h8DPRAKMN-OEHhXg3fcYoo4qAj3Bv_oN0txYGOnvM90",
    "previous_page_url": null,
    "has_next_page": true,
    "has_prev_page": false
  },
  "data": [
    {
      "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"
    }
  ]
}

{
  "object": "list",
  "page_info": {
    "next_page_url": "/v1/settings/portal-domains?cursor=eyJjIjoiMjAyNi0wNS0xMFQwMDowMDowMFoiLCJzIjoicG9kbl9tbDQ0ejVnZ2YxNjkiLCJkIjoiZiJ9.h8DPRAKMN-OEHhXg3fcYoo4qAj3Bv_oN0txYGOnvM90",
    "previous_page_url": null,
    "has_next_page": true,
    "has_prev_page": false
  },
  "data": [
    {
      "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"
    }
  ]
}

List Portal Domains

Authorization

Returns

Responses