API Documentation - V2

Handler: contacts/GetContacts

Description: Get all contacts for the current user with optional pagination and sorting. Admins can filter by user to view contacts for specific users. When using API key authentication, requires "contacts.view" permission.

Parameters & Try It Out:

Possible Errors:

Handler: contacts/GetContact

Description: Get a specific contact by ID

Try It Out:

Possible Errors:

Handler: contacts/CreateContact

Description: Create a new contact for the current user. When using API key authentication, requires "contacts.create" permission.

Parameters & Try It Out:

Possible Errors:

Field Validation Error Response Format:

When field validation fails (error code INPUT_001), the response includes field-specific error details:

{
    "status": "error",
    "code": "INPUT_001",
    "message": "Invalid input data",
    "fields": {
        "phone_number": [
            "phone.constraint.invalid"
        ],
        "address.postal_code": [
            "postalCode.constraint.invalid"
        ],
        "address.country_id": [
            "country.not.found"
        ]
    }
}

Validation Details:

• Phone Numbers: Validated using libphonenumber against the country's phone format
• Postal Codes: Validated against country-specific postal code formats
• VAT Numbers: For EU countries, validated via VIES API. Must be valid to qualify for 'company' VAT type
• VAT Type Logic:
  • EU Countries: Requires valid VAT number + company name for 'company' type
  • Non-EU Countries: Any company name results in 'company' type
• Boolean Fields: Values like is_default are converted to 0/1 for database storage

Handler: contacts/UpdateContact

Description: Update contact fields (email, phone, VAT info, address). Country changes are not allowed - create a new contact instead. VAT percentage and type are automatically recalculated when postal_code or vat_number change. Changes are synced with domain registries if applicable. When using API key authentication, requires "contacts.modify" permission.

Parameters & Try It Out:

Possible Errors:

Automatic Behaviors:

• Country Change Validation: When address.country_id is changed, the existing phone number is automatically re-validated against the new country's phone format. If invalid, returns error code INPUT_001.
• VAT Recalculation: VAT percentage and type are automatically recalculated when any of these fields change:
  • address.country_id
  • address.postal_code
  • vat_number
  • company_name
• Registry Sync: Changes to contact information are automatically synced with domain registries if the contact is used for domain registration.

Example Request:

{
    "vat_number": "DE123456789",
    "company_name": "New Company GmbH",
    "address": {
        "country_id": 81
    }
}

Handler: contacts/UpdateContactRequiredInfo

Description: Add registry-specific required information to a contact. This endpoint uses database-driven organizationAllowed fields to determine when to use clone contacts. For .it domains, requirements are handled through raw_additional_required_info instead of registry files. The endpoint performs comprehensive validation including registry quote checks, and if validation fails, all changes are rolled back. Returns structured field validation errors with INPUT_002 (INVALID_PARAMETERS) error code when field-level issues occur. Use GET /tlds/required_info first to determine what fields are needed - fields not listed there may be auto-generated. When using API key authentication, requires "contacts.required_info" permission.

Request Body & Try It Out:

Possible Errors:

Handler: contacts/DeleteContactById

Description: Delete a specific contact by ID. When using API key authentication, requires "contacts.delete" permission.

Try It Out:

Possible Errors:

Handler: countries/GetCountries

Description: Get all countries with optional sorting

Parameters & Try It Out:

Possible Errors:

Handler: countries/GetCountry

Description: Get a specific country by ID

Try It Out:

Possible Errors:

Handler: dns_templates/GetDnsTemplates

Description: Get DNS templates for the authenticated user. Returns templates with integer domain IDs and public DNS records only. When using API key authentication, requires "dns_templates.view" permission.

Try It Out:

Possible Errors:

Handler: dns_templates/GetDnsTemplate

Description: Get a single DNS template by ID. Returns integer domain IDs and public DNS records only. When using API key authentication, requires "dns_templates.view" permission.

Try It Out:

Possible Errors:

Handler: dns_templates/CreateDnsTemplate

Description: Create a DNS template for the authenticated user. Applies application-host default DNS records. domain_names must be an array of integer domain IDs owned by the user. When using API key authentication, requires "dns_templates.modify" permission.

Parameters & Try It Out:

Possible Errors:

Handler: dns_templates/UpdateDnsTemplate

Description: Update DNS template metadata (name and/or linked domains). domain_names must be an array of integer domain IDs owned by the user. Does not modify dns_records. When using API key authentication, requires "dns_templates.modify" permission.

Parameters & Try It Out:

Possible Errors:

Handler: dns_templates/UpdateDnsTemplateDnsRecords

Description: Replace DNS records of a DNS template. Uses the same DNS validation/normalization logic as PATCH /domain_names/{id}/dns_records and preserves %domain% placeholders. Returns public records only. When using API key authentication, requires "dns_templates.modify" permission.

Parameters & Try It Out:

Possible Errors:

Handler: dns_templates/DeleteDnsTemplate

Description: Delete DNS template by ID. Domain links are cleared by database foreign-key constraints. When using API key authentication, requires "dns_templates.modify" permission.

Try It Out:

Possible Errors:

Handler: domain_name_emails/GetDomainNameEmails

Description: Get email addresses, forwarders, and catch-all addresses for owned regular and external domains. API key authentication requires domains.view.

Parameters & Try It Out:

Possible Errors:

Handler: domain_name_emails/GetSyncProcess

Description: Get the status of a domain email sync process. API key authentication requires domains.email.sync.

Try It Out:

Possible Errors:

Handler: domain_name_emails/CreateDomainNameEmail

Description: Create a mailbox, forwarder, or catch-all address on a regular or external domain. Requires an active plan, active regular domain status, linked mail server, and available plan email quota. API key authentication requires domains.email.manage.

Parameters & Try It Out:

Possible Errors:

Handler: domain_name_emails/StartSync

Description: Start an async mailbox import from the remote mailbox into the local mailbox. Returns HTTP 202 with sync_direction, local_mailbox, remote_mailbox, and process status details. API key authentication requires domains.email.sync.

Parameters & Try It Out:

Possible Errors:

Handler: domain_name_emails/ChangeTarget

Description: Change the target for a forwarder or catch-all address. API key authentication requires domains.email.manage.

Parameters & Try It Out:

Possible Errors:

Handler: domain_name_emails/ChangePassword

Description: Change mailbox password. Forwarders and catch-all addresses are rejected. API key authentication requires domains.email.manage.

Parameters & Try It Out:

Possible Errors:

Handler: domain_name_emails/DeleteDomainNameEmail

Description: Delete a mailbox, forwarder, or catch-all address. Mailbox deletion also creates a mail-server todo delete task. API key authentication requires domains.email.delete.

Try It Out:

Possible Errors:

Handler: domain_name_orders/GetDomainNameOrder

Description: Get a domain name order by ID. Only rows currently visible in the sidebar pending/problem product or pending domain views are returned. Includes generic domain registry process attempt metadata and live registry process information with transfer information when available. When using API key authentication, requires "domains.view" permission.

Parameters & Try It Out:

Possible Errors:

Handler: domain_names/GetDomainNames

Description: Get all domain names for the current user. Returns an array of domain objects with full details including owner information, TLD properties, status, and associated plans. Supports searching through domain names and TLDs (e.g., "site", "eu", "ite.e", ".nl"). Admins can filter by user to view domains for specific users. When using API key authentication, requires "domains.view" permission.

Parameters & Try It Out:

Possible Errors:

Handler: domain_names/CheckAvailability

Description: Check domain name availability at the domain registry. The endpoint validates that the TLD is offered by the current application host before calling the registry. Returns only available and, when present for unavailable domains, reason.

Parameters & Try It Out:

Possible Errors:

Handler: domain_names/GetDomainName

Description: Get detailed information for a specific domain by ID. Returns the domain with all its details including DNS records (if DNS control is enabled), domain name tags, and email blocking status.

Try It Out:

Possible Errors:

Handler: domain_names/GetDomainNameLogs

Description: Get the log book entries for a domain. Only the domain owner or an admin can view the logs. When using API key authentication, requires "domains.view" permission.

Parameters & Try It Out:

Possible Errors:

Handler: domain_names/ConvertPunycode

Description: Convert a Unicode domain label or full domain name into ASCII punycode (UTS46 non-transitional mode). Example: "münchen" -> "xn--mnchen-3ya". If input contains a dot, TLD is extracted from input (first-pass) for IDN policy checks. language_codes is returned only when the extracted TLD matches domain_top_level and idn_language_codes contains a non-empty list.

Request Body & Try It Out:

Possible Errors:

Handler: domain_names/ConvertPunycodeToUnicode

Description: Convert an ASCII punycode domain name to Unicode. Input must start with "xn--", contain a dot, and use a TLD that exists in domain_top_level. Example: "xn--mnchen-3ya.com" -> "münchen.com".

Request Body & Try It Out:

Possible Errors:

Handler: domain_names/AssignToPlan

Description: Link an active registered domain name to an active all-in-one plan. The domain and plan must belong to the authenticated user unless the caller is an admin. The plan domain limit counts both registered and external domains. Returns the same domain payload shape as GET /domain_names/{id}. Requires API key permissions: domains.plan.manage and domains.view.

Parameters, Request Body & Try It Out:

Possible Errors:

Handler: domain_names/RemoveFromPlan

Description: Unlink a registered domain name from its all-in-one plan. Email and website builder must be disabled first; active webhosting does not block unlinking. Returns the same domain payload shape as GET /domain_names/{id}. Requires API key permissions: domains.plan.manage and domains.view.

Try It Out:

Possible Errors:

Handler: domain_names/UpdateDnsRecords

Description: Update DNS records for a domain. This endpoint performs a complete replacement of all DNS records - any records not included in the request will be deleted. The domain must have DNS control enabled and be in active status. Record names must be subdomains of the domain (e.g., "www.example.com." or "example.com."). NS records cannot be set at the root level. CNAME records cannot be set at the root level and cannot coexist with other record types at the same subdomain. Duplicate records (same name, type, and value) are not allowed. When using API key authentication, requires "domains.dns.modify" permission. Example request: {"dns_records":[{"name":"www.example.com.","type":"A","ttl":3600,"value":"192.0.2.1"},{"name":"example.com.","type":"MX","ttl":3600,"value":"10 mail.example.com."}]}

Parameters & Try It Out:

Possible Errors:

Handler: domain_names/UpdateDnsControl

Description: Enable or disable DNS control for a domain. When enabling, the endpoint updates registry nameservers to the application host defaults, recreates the DNS zone using default records, and enables DNSSEC when supported by the TLD. When disabling, it removes the DNS zone, clears registry key data for DNSSEC TLDs, and removes domain redirections. Returns the same domain payload shape as GET /domain_names/{id}. Requires API key permissions: domains.dns.control and domains.view.

Parameters & Try It Out:

Possible Errors:

Handler: domain_names/UpdateNameServers

Description: Update nameservers for an active domain. If DNS control is currently enabled, the endpoint disables DNS control, removes the PowerDNS zone, clears registry DNSSEC key data for DNSSEC TLDs, and enables advanced settings before storing the new nameserver settings. Glue records are created or updated at the registry when ips are supplied. Returns the same domain payload shape as GET /domain_names/{id}. Requires API key permissions: domains.dns.control and domains.view.

Parameters & Try It Out:

Possible Errors:

Handler: domain_names/UpdateAdvancedSettings

Description: Enable or disable access to advanced settings for a domain. Only the domain owner can update this setting, and the domain must be active. Disabling also unlinks DNS template sync fields and repairs DNS records for linked services. Returns the same domain payload shape as GET /domain_names/{id}. API key authentication is allowed and requires domains.dns.control and domains.view permissions.

Parameters & Try It Out:

Possible Errors:

Handler: external_domain_names/GetExternalDomainNames

Description: Get all external domain names for the current user. Returns an array of brief external domain objects with linked plan and mail server information where available. Admins can filter by user to view external domains for specific users. When using API key authentication, requires domains.view permission.

Parameters & Try It Out:

Possible Errors:

Handler: external_domain_names/GetExternalDomainName

Description: Get detailed information for a specific external domain name by ID. Returns the external domain with linked plan, mail server, DNS records, domain redirections, email accounts, DNS record checks, and outgoing email block status. Only the owner or an admin can view the external domain. API key authentication is allowed and requires domains.view permission.

Try It Out:

Possible Errors:

Handler: external_domain_names/CreateExternalDomainName

Description: Create an external domain name for the current user. This endpoint only creates the external domain record; it does not enable DNS control, create PowerDNS zones, attach plans, or update webhosting accounts. When using API key authentication, requires domains.create permission.

Request Body & Try It Out:

Possible Errors:

Handler: external_domain_names/AssignToPlan

Description: Link an external domain name to an active all-in-one plan. The external domain and plan must belong to the authenticated user unless the caller is an admin. External domains do not have a domain status check; the plan domain limit counts both registered and external domains. Returns the same external-domain payload shape as GET /external_domain_names/{id}. Requires API key permissions: domains.plan.manage and domains.view.

Parameters, Request Body & Try It Out:

Possible Errors:

Handler: external_domain_names/RemoveFromPlan

Description: Unlink an external domain name from its all-in-one plan. Email and website builder must be disabled first; active webhosting does not block unlinking. Returns the same external-domain payload shape as GET /external_domain_names/{id}. Requires API key permissions: domains.plan.manage and domains.view.

Try It Out:

Possible Errors:

Handler: external_domain_names/UpdateDnsControl

Description: Enable or disable DNS control for an external domain. When enabling, the endpoint recreates the PowerDNS zone using application host default nameservers and DNS records. When disabling, it removes the PowerDNS zone. Returns the same external-domain payload shape as GET /external_domain_names/{id}. Requires API key permissions: domains.dns.control and domains.view.

Parameters & Try It Out:

Possible Errors:

Handler: external_domain_names/UpdateAdvancedSettings

Description: Enable or disable access to advanced settings for an external domain. Disabling ensures external DNS control is enabled, repairs DNS records for linked services, and returns the same external-domain payload shape as GET /external_domain_names/{id}. Requires API key permissions: domains.dns.control and domains.view.

Parameters & Try It Out:

Possible Errors:

Handler: external_domain_names/UpdateDnsRecords

Description: Update DNS records for an external domain. This endpoint performs a complete replacement of all DNS records except system-managed apex NS/SOA records. The external domain must have DNS control enabled. Record validation matches PATCH /domain_names/{id}/dns_records. When using API key authentication, requires domains.dns.modify permission.

Parameters & Try It Out:

Possible Errors:

Handler: mcp/ProcessMCPRequest

Description: MCP (Model Context Protocol) endpoint for supplier, domain, invoice, and translation management. Same permission requirements as POST method.

Try It Out:

Handler: mcp/ProcessMCPRequest

Description: MCP (Model Context Protocol) endpoint for supplier, domain, invoice, and translation management. API-key authenticated MCP tool calls require the corresponding mcp_tools permission. Direct API endpoint calls use api_endpoints permissions.

Try It Out:

Possible Errors:

Handler: mcp/ProcessMCPRequest

Description: MCP (Model Context Protocol) endpoint - HEAD request for connection verification

Try It Out:

Handler: mcp/ProcessMCPRequest

Description: MCP (Model Context Protocol) endpoint - CORS preflight support

Try It Out:

Handler: plans/GetPlans

Description: Get all all-in-one plans for the current user. Returns an array of plan objects with full details including plan specifications (CPU, RAM, disk, bandwidth), associated domain names, webhosting accounts, and available upgrade options. Admins can filter by user to view plans for specific users. When using API key authentication, requires "domains.view" permission.

Parameters & Try It Out:

Possible Errors:

Handler: plans/GetPlan

Description: Get detailed information for a specific all-in-one plan by ID. Returns the plan with all its details including plan specifications, associated domain names (both internal and external), webhosting/reseller accounts, and available upgrade options.

Try It Out:

Possible Errors:

Handler: tlds/GetTlds

Description: Get all top-level domains with pricing information and related TLD recommendations

Parameters & Try It Out:

Possible Errors:

Handler: tlds/GetTld

Description: Get a specific top-level domain by ID, including related TLD recommendations

Try It Out:

Possible Errors:

Handler: tlds/GetRequiredInfo

Description: Check what additional information is required for a contact to register a specific TLD. This endpoint now returns ALL fields from raw_additional_required_info (both mandatory and non-mandatory fields). Domains with only non-mandatory missing fields are automatically validated at the registry in the background, and if successful, their handles are saved and they are filtered out from the response. Domains that already have handles saved in extra_handles are also skipped. Different registries have different requirements based on domain extension, contact type (individual/company), and contact country. Without parameters, checks current shopping cart. This endpoint automatically handles field auto-generation in the background - fields that can be auto-generated (e.g., identification numbers for non-Spanish contacts on .es domains) will not appear in the required fields list.

Parameters & Try It Out:

Possible Errors: