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 (RTR) 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 RTR 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: 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/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: 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 via RTR 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: