Skip to content
Website BuddyWebsite BuddyWebsite builder
Sign inGet started
API reference/Domain names

Buy a domain for a site

Try it

Registers the domain in the client's name (WHOIS privacy on), sets its DNS so the site answers on it, connects it to the site VERIFIED (with www. unless with_www is false) and requests the HTTPS certificate. Adds year_cents × years to this month's statement. expected_year_cents must be the price search_domain_names gave — a different price answers 409 price_changed and buys nothing. Optional email_forwards set up business email addresses.

POST/api/v1/sites/{site_id}/domain-names

Authentication

An API key as Authorization: Bearer or x-api-key. It needs the domains:buy scope — search, buy and renew domain names (each adds the registration to your bill).

domains:buyAdds to your billIdempotency-Key requiredMCP tool: buy_domain_name

Parameters

Named placeholders go in the path; the rest in a JSON body.

site_idstringPath · required
The site's id.1 to 100 characters
domainstringBody · required
e.g. rosiesdiner.com4 to 80 characters
yearsintegerBody · optional
1 to 5Default 1
expected_year_centsintegerBody · required
The year_cents search_domain_names quoted.At least 0
with_wwwbooleanBody · optional
Default true
auto_renewbooleanBody · optional
Default true
ownerobjectBody · required
The registrant — the client business, not you.
email_forwardsarray of objectBody · optional
Business email addresses to set up: box@domain arrives in `to`.Default []

Response

201 with JSON on success (schema on the right). Errors use the standard envelope; a retry with the same Idempotency-Key gets the first answer back (how retries work).

curl
curl -X POST 'https://websites.workflowcorp.com/api/v1/sites/SITE_ID/domain-names' \
  -H "Authorization: Bearer $WEBSITEBUDDY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"domain":"","expected_year_cents":0,"owner":{"first_name":"","last_name":"","address":"","city":"","state":"","zip":"","phone":"","email":""}}'
Example arguments
{
  "site_id": "SITE_ID",
  "domain": "",
  "expected_year_cents": 0,
  "owner": {
    "first_name": "",
    "last_name": "",
    "address": "",
    "city": "",
    "state": "",
    "zip": "",
    "phone": "",
    "email": ""
  }
}
Response schema
{
  "type": "object",
  "properties": {
    "domain_name": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "domain": {
          "type": "string"
        },
        "site_id": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "active",
            "expired",
            "failed"
          ]
        },
        "year_cents": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "What we charge per year (cents), as last quoted."
        },
        "auto_renew": {
          "type": "boolean",
          "description": "Renewed by itself, one year, 30 days before it ends."
        },
        "registered_at": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "expires_at": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "renew_error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "dns_error": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ]
        },
        "dns_records": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "host": {
                "type": "string"
              },
              "type": {
                "type": "string"
              },
              "answer": {
                "type": "string"
              }
            },
            "required": [
              "host",
              "type",
              "answer"
            ],
            "additionalProperties": false
          },
          "description": "The records we set at the registrar (host is relative to the domain; empty = the bare domain)."
        },
        "email_forwards": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "box": {
                "type": "string"
              },
              "to": {
                "type": "string"
              }
            },
            "required": [
              "box",
              "to"
            ],
            "additionalProperties": false
          },
          "description": "Business email addresses: box@domain arrives in `to`."
        },
        "created_at": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "domain",
        "site_id",
        "status",
        "year_cents",
        "auto_renew",
        "registered_at",
        "expires_at",
        "renew_error",
        "dns_error",
        "dns_records",
        "email_forwards",
        "created_at"
      ],
      "additionalProperties": false
    },
    "charged_cents": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "hostnames": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "domain_name",
    "charged_cents",
    "hostnames"
  ],
  "additionalProperties": false
}