> ## Documentation Index > Fetch the complete documentation index at: https://docs.bizzyco.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create subdomain > Add a sending subdomain under a verified apex domain. domain is the full name and must sit exactly one label under the parent (mail.acme.com under acme.com). The subdomain inherits the parent's verification — no TXT challenge is issued and it is active at once — and never holds a registration or DNS zone of its own, so capabilities.dns reports the parent's. purpose defaults to general (sends and receives); transactional and marketing are sending-only. Refused with 409 when the parent is itself a subdomain (DOMAIN_NOT_APEX), is not yet verified (DOMAIN_NOT_VERIFIED), has a transfer to another registrar under way (REGISTERED_DOMAIN_TRANSFER_IN_FLIGHT), or the name is already in the organization (DOMAIN_ALREADY_EXISTS); with 400 and code SUBDOMAIN_NOT_UNDER_PARENT when the name is not exactly one label under the parent; and with 404 when the parent is not in the organization. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/domains/{id}/subdomains openapi: 3.1.0 info: title: Bizzy API version: 1.0.0 description: Bizzy API for managing businesses, customers, contacts, and more. servers: - url: https://api.bizzyco.ai description: Production security: [] tags: - name: Automations description: Manage workflow automation rules x-group: Automations - name: Automation Executions description: View automation execution history x-group: Automations - name: Businesses description: Manage business profiles x-group: Businesses - name: Business Offerings description: Manage products and services offered by businesses x-group: Businesses - name: Business Online Presences description: Manage websites and social media links x-group: Businesses - name: Business Physical Presences description: Manage physical locations and addresses x-group: Businesses - name: Business Profile description: View and update business profile details x-group: Businesses - name: Business Properties description: Set and review custom property values on businesses x-group: Businesses - name: Contacts description: Manage contact records x-group: Contacts - name: Contact Addresses description: Manage mailing addresses for contacts x-group: Contacts - name: Contact Emails description: Manage email addresses for contacts x-group: Contacts - name: Contact Phone Numbers description: Manage phone numbers for contacts x-group: Contacts - name: Contact Properties description: Set and review custom property values on contacts x-group: Contacts - name: Customers description: Manage customer records x-group: Customers - name: Customer Transactions description: View customer transaction history x-group: Customers - name: Customer Properties description: Set and review custom property values on customers x-group: Customers - name: Domains description: Manage domain names x-group: Domains - name: Domain Contacts description: Manage contacts associated with domains x-group: Domains - name: Domain Registrations description: Manage domain registration records x-group: Domains - name: Email Templates description: Manage reusable email templates x-group: Email Templates - name: Email Opt-ins description: Record and withdraw recipients' marketing email opt-ins x-group: Email Templates - name: Files description: Manage file uploads and downloads x-group: Files - name: File Access Links description: Manage shareable file access links x-group: Files - name: Folders description: Organize files into folders x-group: Files - name: Messages description: Manage email messages x-group: Messages - name: Message Attachments description: Access message file attachments x-group: Messages - name: Message Contacts description: View contacts associated with messages x-group: Messages - name: Property Definitions description: Manage the custom properties contacts, customers, and businesses can hold x-group: Properties - name: Tasks description: Manage task records x-group: Tasks - name: Task Assignees description: Manage user assignments to tasks x-group: Tasks - name: Task Activity description: View task activity and change history x-group: Tasks paths: /v1/domains/{id}/subdomains: post: tags: - Domains summary: Create subdomain description: >- Add a sending subdomain under a verified apex domain. domain is the full name and must sit exactly one label under the parent (mail.acme.com under acme.com). The subdomain inherits the parent's verification — no TXT challenge is issued and it is active at once — and never holds a registration or DNS zone of its own, so capabilities.dns reports the parent's. purpose defaults to general (sends and receives); transactional and marketing are sending-only. Refused with 409 when the parent is itself a subdomain (DOMAIN_NOT_APEX), is not yet verified (DOMAIN_NOT_VERIFIED), has a transfer to another registrar under way (REGISTERED_DOMAIN_TRANSFER_IN_FLIGHT), or the name is already in the organization (DOMAIN_ALREADY_EXISTS); with 400 and code SUBDOMAIN_NOT_UNDER_PARENT when the name is not exactly one label under the parent; and with 404 when the parent is not in the organization. operationId: createDomainSubdomain parameters: - schema: type: string format: uuid description: Domain UUID required: true description: Domain UUID name: id in: path - schema: type: string minLength: 1 maxLength: 255 description: >- Key that makes this request safe to retry. Reuse the same value when retrying a request that may already have succeeded — the original response is replayed with an `Idempotency-Replay: true` header. Use a new value for a new operation. example: 9f8c2b1a-4d3e-4a6b-8c1d-2e3f4a5b6c7d required: false description: >- Key that makes this request safe to retry. Reuse the same value when retrying a request that may already have succeeded — the original response is replayed with an `Idempotency-Replay: true` header. Use a new value for a new operation. name: idempotency-key in: header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubdomainCreate' responses: '201': description: Create subdomain headers: X-RateLimit-Limit: schema: type: integer description: Maximum burst of requests the tier allows per minute X-RateLimit-Remaining: schema: type: integer description: Requests remaining in the current window after this request X-RateLimit-Reset: schema: type: integer description: Seconds until the allowance is fully replenished Idempotency-Replay: schema: type: boolean description: >- Present and `true` when this response is a replay of an earlier request with the same Idempotency-Key content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Domain' meta: type: object properties: pagination: type: object properties: total: type: number limit: type: number offset: type: number hasMore: type: boolean required: - limit - offset - hasMore required: - data '400': description: Invalid input content: application/json: schema: $ref: '#/components/schemas/ApiError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ApiError' '403': description: Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ApiError' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ApiError' '409': description: >- Refused because the parent is itself a subdomain (error code DOMAIN_NOT_APEX), is not verified (DOMAIN_NOT_VERIFIED), has a transfer to another registrar under way (REGISTERED_DOMAIN_TRANSFER_IN_FLIGHT), or the name is already in the organization (DOMAIN_ALREADY_EXISTS); or a request with the same Idempotency-Key is still in progress (IDEMPOTENCY_KEY_IN_FLIGHT) content: application/json: schema: $ref: '#/components/schemas/ApiError' '422': description: >- This Idempotency-Key was already used for a different request (error code IDEMPOTENCY_KEY_REUSED) content: application/json: schema: $ref: '#/components/schemas/ApiError' '429': description: Rate limit exceeded for the account tier (error code RATE_LIMITED) headers: X-RateLimit-Limit: schema: type: integer description: Maximum burst of requests the tier allows per minute X-RateLimit-Remaining: schema: type: integer description: Requests remaining in the current window after this request X-RateLimit-Reset: schema: type: integer description: Seconds until the allowance is fully replenished Retry-After: schema: type: integer description: Seconds to wait before the next request will be accepted content: application/json: schema: $ref: '#/components/schemas/ApiError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ApiError' security: - bearerAuth: [] components: schemas: SubdomainCreate: type: object properties: domain: type: string minLength: 1 maxLength: 253 pattern: >- ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*$ description: >- The full name, exactly one label under the parent — mail.example.com under example.com. purpose: type: string enum: - general - transactional - marketing default: general description: >- Defaults to general (sends and receives). transactional and marketing are sending-only. required: - domain additionalProperties: false Domain: type: object properties: id: type: string format: uuid createdAt: type: string format: date-time updatedAt: type: string format: date-time domain: type: string source: type: string enum: - registered - verified status: type: string enum: - active - expiring - expired - pending kind: type: string enum: - apex - subdomain description: >- apex: a name you verify or register in its own right. subdomain: a sending identity one label under an apex the organization already holds; it inherits that apex's verification and never carries a registration or DNS zone of its own. parentDomainId: type: - string - 'null' format: uuid description: The apex domain a subdomain belongs to; null for an apex. purpose: type: string enum: - general - transactional - marketing description: >- What the sending identity is for. general sends and receives mail; transactional and marketing are sending-only. marketing is available on subdomains only. capabilities: type: object properties: dns: type: boolean description: >- Whether DNS records can be managed through Bizzy — true for domains registered through Bizzy and for domains whose DNS is hosted in Bizzy. A subdomain holds no zone of its own, so this reports whether its parent's DNS is hosted in Bizzy. email: type: boolean registration: type: boolean renewal: type: boolean description: >- Whether this domain can be renewed on demand. False for domains that renew only automatically (one year at a time while autoRenew is on) — the renewal-price and renew endpoints reject those with MANUAL_RENEWAL_NOT_SUPPORTED. required: - dns - email - registration - renewal verification: $ref: '#/components/schemas/DomainVerification' registration: type: object properties: registered: type: boolean state: type: - string - 'null' registeredAt: type: - string - 'null' format: date-time expiresAt: type: - string - 'null' format: date-time autoRenew: type: - boolean - 'null' whoisPrivacy: type: - boolean - 'null' transferLock: type: - boolean - 'null' periodYears: type: - number - 'null' registrantVerificationDeadline: type: - string - 'null' format: date-time required: - registered - state - registeredAt - expiresAt - autoRenew - whoisPrivacy - transferLock - periodYears - registrantVerificationDeadline email: $ref: '#/components/schemas/DomainEmailAuth' required: - id - createdAt - updatedAt - domain - source - status - kind - parentDomainId - purpose - capabilities - verification - registration - email ApiError: type: object properties: error: type: object properties: message: type: string code: type: string details: {} required: - message - code required: - error DomainVerification: type: object properties: status: type: string enum: - pending - verified - failed instruction: type: - object - 'null' properties: type: type: string enum: - TXT name: type: string value: type: string required: - type - name - value attempts: type: number verifiedAt: type: - string - 'null' format: date-time expiresAt: type: - string - 'null' format: date-time required: - status - instruction - attempts - verifiedAt - expiresAt DomainEmailAuth: type: object properties: domainId: type: string format: uuid domain: type: string source: type: string enum: - registered - verified managed: type: boolean resendStatus: type: string enum: - none - initializing - creating - dns_pending - verifying - active - failed readiness: type: string enum: - ready - in_progress - action_needed - not_configured failureReason: type: - string - 'null' enum: - provider - dns - stalled - unverified - unknown - null drift: type: - object - 'null' properties: brokenAt: type: string format: date-time kinds: type: array items: type: string enum: - SPF - DKIM - DMARC minItems: 1 required: - brokenAt - kinds fromEmail: type: - string - 'null' records: type: array items: type: object properties: kind: type: string enum: - SPF - DKIM - Receiving - DMARC state: type: string enum: - verified - pending - missing - recommended - auto_managed managed: type: boolean required: type: boolean name: type: string type: type: string enum: - TXT - CNAME - MX value: type: string ttl: type: string priority: type: number inheritedFrom: type: - string - 'null' effectivePolicy: type: - string - 'null' enum: - none - quarantine - reject - null required: - kind - state - managed - required - name - type - value - ttl required: - domainId - domain - source - managed - resendStatus - readiness - failureReason - drift - fromEmail - records securitySchemes: bearerAuth: type: http scheme: bearer description: API key authentication via Bearer token ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.