Become a Reseller

Introduction

This document describes the Freenom API at a technical level. It explains the supported data formats and how to interact with the API. For each function supported by the API a description is given including an example how such a function call and response may look.

Examples are given using the command line tool ‘curl’. Curl is an easy tool to access any URL and is installed on most Unix like environments.

 

Data formats

The API delivers output in JSON format by default. If the API User prefers, output can be given in XML. The method of output is defined in the function call.

Example: Ping the service

Input
Request
Output
Response

Example: Ping the service expecting XML output. Note the .xml behind the method name.

Input
Request
Output
Response

Examples in this manual are given in XML for readability.


 

Interacting with Freenom API

Interaction with the API should be trivial. The service is a RESTful-like service that interacts over HTTPS. Of all the HTTP methods available, only GET and POST are used. GET calls retrieve information and do not change anything, while POST calls are meant to change data.

POST calls are idempotent for 30 seconds. This allows a caller to resubmit a transaction having it not being executed twice.


 

Common errors

Each function supported by the API has been documented thoroughly. Some errors can occur for a multiple of functions and are described in this chapter. This information will not be repeated in the related function description.

Function not found

In case an unsupported function is called, the service will reply the following:

Not authorized

Most functions can only be executed by authorized users. For these functions authorization must take place. If the user is not authorized to make the call, the content returned will be:

Invalid data submitted

If the function itself is supported, but data submitted is invalid or missing an error will be reported. For example:

Input
Request
Output
Response

The status field will state ‘error’ when an error occurred. Whenever this field is set to ‘error, an element will display the error found.

The service will always reply directly when a first error is found. If there are multiple errors in the function call, only one is returned. This stops the service from doing unnecessary work, as the call will fail in any case.


 

Function parameters

Commonly used parameters

A number of parameters are used in a multiple of functions. Other parameters deserve special attention. Those parameters are explained in this chapter.

domainname

The domain name involved. The domain name should consist of only a-z and 0-9 characters and the – (dash). The dash may not be in the beginning or end of the domain name. Domain names are not case sensitive

forward_url

If the domain is configured for forwarding, the URL to forward traffic for the domain to is given via the forward_url. The forward_url can be any HTTP or HTTPS URL.

nameserver

The nameserver. A nameserver needs to be a hostname that is resolvable if it’s a hostname not under the domain name specified.

period

The period of domain registration or renewal. Paid domains are registered in number of years. Supported periods for Paid domains: 1Y, 2Y, 3Y, 4Y, 5Y, 9Y and 10Y.

 

Supporting parameters

Supporting parameters are parameters that are not specific to a function call but to the API behavior.

test_mode

When set to 1, the function is discarded after execution. Any changes done to Freenom’s database are rolled back.

method

If caller is unable to specify the method of the function by that method, this parameter can help. Setting the method parameter to ‘post’ will tell the service that a POST method is meant by caller. Same counts for ‘get’.

 

The multiple flag

Function parameters are described in a table for each function. One of the columns in this table is labeled “multiple”. This indicates whether or not the parameter can be specified more than once.

An example call would look like this: