Create Portal Domain

Beta

POST/v1/settings/portal-domains

Idempotent with Idempotency-Key header. Learn more

Connects a custom domain to the account's customer portal and returns the DNS records to publish.

An account can only have one custom domain at a time: adding a second one — or claiming a domain another account already uses — returns a conflict error. The new domain starts in pending; publish the returned records at your DNS provider, then run the verify action to move it towards serving.

Permissions requiredValues:self:update

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

domainstring

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

A subdomain such as shop.acme.com is routed with a CNAME record and an apex domain such as acme.com with an A record; either way the records to publish come back on the response. The value is lowercased and any trailing dot is stripped before it is stored, and OpenMRP-owned hostnames are rejected.

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

201

Successful response for Create Portal Domain

Create 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.create({ domain: 'shop.acme.com' });

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.create({ domain: 'shop.acme.com' });

console.log(portalDomain.id);

201 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"
}

Create Portal Domain

Authorization

Request Body

Returns

Responses