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_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/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/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/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/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: mcp/ProcessMCPRequest

Description: MCP (Model Context Protocol) endpoint for supplier management. Same permission requirements as POST method.

Try It Out:

Handler: mcp/ProcessMCPRequest

Description: MCP (Model Context Protocol) endpoint for supplier and domain management. IMPORTANT: MCP tools require BOTH an MCP tool permission AND the corresponding API endpoint permission. For example, getDomainNames requires mcp_tools:["getDomainNames"] AND api_endpoints:["domains.view"]. This dual-permission model provides defense-in-depth security.

Try It Out:

Possible Errors:

Handler: mcp/ProcessMCPRequest

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

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

Parameters & Try It Out:

Possible Errors:

Handler: tlds/GetTld

Description: Get a specific top-level domain by ID

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: