FastDDNS Client API

Overview

The FastDDNS Client API allows any HTTP-capable device — routers, IP cameras, scripts, or dedicated updater software — to keep your DNS hostname pointed at your current IP address. The API follows a simple GET-request design: your client sends credentials and a hostname, and the server responds with a short status code indicating the result.

The server automatically detects the client's public IP address from the incoming connection. No extra parameters are needed to specify your IP.

Authentication

The API supports two authentication methods. Both are accepted equally — choose whichever is easier to configure on your device or router.

Method 1 — HTTP Basic Auth (URL-embedded)

Credentials are embedded in the URL using the standard user:password@host format. This is widely supported by routers, cameras, and HTTP client libraries. Use the Updater Client Key from your dashboard as the password.

Method 2 — Query String Parameters

Credentials are passed as plain query parameters alongside hostname. This is useful for devices and firmware that cannot configure HTTP Basic Auth headers but allow a fully custom URL string.

Example using query string auth:

Perform Update

Send a single GET request to update the IP address of a hostname registered to your account. Each request updates one hostname at a time.

Endpoint

URL Format — Method 1: HTTP Basic Auth

URL Format — Method 2: Query String

Query Parameters

Example Requests

Method 1 — HTTP Basic Auth over HTTPS:

Method 2 — Query string over HTTPS:

Using plain HTTP (testing / trusted networks only):

Return Codes

All update responses return HTTP status 200 OK with a plain text body. Your client must parse this text body to determine the actual outcome of the update.

Response Summary

Get Client IP

FastDDNS provides a simple utility endpoint that returns the public IP address as seen by the server. This is useful for debugging, for verifying which IP your device is sending from, or for use in custom scripts before calling the update endpoint.

Endpoint

Response

Returns HTTP 200 OK with the detected public IP address as plain text in the response body.

# Example response body
203.0.113.45RESPONSE

Example Requests

Using curl:

curl https://client.fastddns.net/dyndns/getipSHELL

Code Examples

Shell / cURL

# Method 1: HTTP Basic Auth (HTTPS, IP auto-detected)
curl "https://fastddnstest:[email protected]/?hostname=testhost.fastddns.org"
# Method 2: Query string credentials
curl "https://client.fastddns.net/?hostname=testhost.fastddns.org&user_name=fastddnstest&user_pass=569832"
# Check what IP the server sees from your device
curl "https://client.fastddns.net/dyndns/getip"SHELL

Python

import requests
HOSTNAME  = "testhost.fastddns.org"
USER_NAME = "fastddnstest"
USER_PASS = "569832"
# Method 1: HTTP Basic Auth
resp = requests.get(
    "https://client.fastddns.net/",
    auth=(USER_NAME, USER_PASS),
    params={"hostname": HOSTNAME}
)
# Method 2: Query string
# resp = requests.get("https://client.fastddns.net/", params={
#     "hostname": HOSTNAME, "user_name": USER_NAME, "user_pass": USER_PASS
# })
body = resp.text.strip()
if body.startswith("good"):
    print(f"Updated successfully: {body}")
elif body.startswith("nochg"):
    print(f"No change needed: {body}")
elif body == "badauth":
    print("Authentication failed. Check credentials.")
elif body == "nohost":
    print("Hostname not found.")
elif body == "911":
    print("Server error. Try again later.")PYTHON

PHP

<?php
$hostname  = 'testhost.fastddns.org';
$user_name = 'fastddnstest';
$user_pass = '569832';
// Method 1: HTTP Basic Auth embedded in URL
$url = "https://{$user_name}:{$user_pass}@client.fastddns.net/?hostname=" . urlencode($hostname);
// Method 2: Query string credentials
// $url = "https://client.fastddns.net/?hostname=" . urlencode($hostname)
//      . "&user_name=" . urlencode($user_name)
//      . "&user_pass=" . urlencode($user_pass);
$ctx = stream_context_create(['http' => ['timeout' => 10]]);
$body = trim(file_get_contents($url, false, $ctx));
switch (true) {
    case str_starts_with($body, 'good'):
        echo "Updated: {$body}\n"; break;
    case str_starts_with($body, 'nochg'):
        echo "No change: {$body}\n"; break;
    case $body === 'badauth':
        echo "Auth failed. Check hostname credentials.\n"; break;
    case $body === 'nohost':
        echo "Hostname not found.\n"; break;
    case $body === '911':
        echo "Server error, retry later.\n"; break;
}PHP

Bash (Cron / Router Script)

#!/bin/bash
HOSTNAME="testhost.fastddns.org"
USER_NAME="fastddnstest"
USER_PASS="569832"
# Method 1: HTTP Basic Auth
RESULT=$(curl -s "https://${USER_NAME}:${USER_PASS}@client.fastddns.net/?hostname=${HOSTNAME}")
# Method 2: Query string (uncomment to use instead)
# RESULT=$(curl -s "https://client.fastddns.net/?hostname=${HOSTNAME}&user_name=${USER_NAME}&user_pass=${USER_PASS}")
case "$RESULT" in
  good*)   echo "[OK] $RESULT" ;;
  nochg*)  echo "[OK] $RESULT" ;;
  badauth) echo "[ERR] Bad credentials — check hostname user/pass"; exit 1 ;;
  nohost)  echo "[ERR] Hostname not found"; exit 1 ;;
  911)     echo "[ERR] Server error, retry later"; exit 1 ;;
  *)       echo "[WARN] Unknown response: $RESULT" ;;
esacBASH

Troubleshooting

I receive badauth

The user_name or user_pass supplied do not match the credentials assigned to that hostname. Each hostname has its own independent credentials — find them in your dashboard under Hostnames → Details. Note that these credentials are specific to the hostname and cannot be used to log in to the FastDDNS management portal. If you recently reset the credentials, update all devices using that hostname.

I receive nohost

The hostname in the hostname parameter does not exist or does not belong to the account identified by the supplied credentials. Check for typos in the hostname, confirm it is listed in your dashboard, and verify that the user_name and user_pass match that specific hostname.

The server is detecting the wrong IP

The server uses the source IP of the TCP connection. If your device is behind a NAT router, the router's public IP will be detected — which is usually the desired behavior. If you are on a VPN or proxy, the server will see the VPN/proxy exit IP instead. Use the getip endpoint to verify which IP the server sees from your device.

I receive 911

This indicates a temporary server-side problem. Wait at least 5 minutes before retrying. Do not loop requests rapidly — this may trigger rate limiting. Check the FastDDNS status page for any active incidents.

How often should I poll the update endpoint?

We recommend checking for IP changes every 5 minutes. When your IP has not changed, the server returns nochg, which is a lightweight no-op. Polling more frequently than once per minute is discouraged and may result in rate limiting.