API Queries - Manage Contacts

The manage_contacts API function lists contacts in your account and their details (name, company, email, etc.). Various sorting options are available and up to 1,000 contacts can be shown per query. You can also filter the list by providing one or more contacts (maximum 1,000) via the contact_id parameter. Additional parameters are optional for this function.

Additional Parameters

contact_id (optional) - Search for one contact with ID.
limit (optional) - Number of contacts to return. Accepted values are 1-1,000. Default is 100.
offset (optional) - This paramater is used in with the limit paramater to show each "page" of contacts. Note that the first contact is under record 0. For example if you wanted to return contacts 21-30, you would use (offset=20&limit=10). See Example 3 for more details and examples. Accepted values are 0 or greater. Default is 0.
sort_by (optional) - Sort list by various fields. Accepted values are "id" (sort by contact ID), "contact_identifier" (sort by Contact Identifier), "contact_alias" (sort by Contact Alias), "created" (sort by contact create date). Default is "id".
order (optional) - Choose to show sort_by field in ascending or descending order (alphabetically or chronologically). Accepted values are "asc" (ascending order) and "desc" (descending order). Default is "asc" (ascending order).

Your API key is required and all values should be correctly URL encoded.

Response Values

General and sorting response values:

total - If the contact parameter is used, this value is the total contacts found for your search. Otherwise, this value is the total contacts in your account.
offset - The current offset value (default value if paramater is not specified). See Additional Parameters section above.
limit - The current limit value (default value if paramater is not specified). See Additional Parameters section above.
sort_by - The current sort_by value (default value if paramater is not specified). See Additional Parameters section above.
order - The current order value (default value if paramater is not specified). See Additional Parameters section above.

In the examples, you will see that a lot of information about each contact is returned by our API. A basic explanation of each item and possible values are provided below:

id - Contact ID.
contact_identifier - Domain contact identifier show in register domain or manage domains query result.
name Contact name.
company Contact's company.
email Contact's email address.
phone Contact's phone number, area code included.
address Contact's address, address2 value included if exist.
city Contact's city.
state Contact's state.
postcode Contact's postcode.
country Contact's country code.
registrant_name AU contact's registrant name.
eligibility_type AU contact's eligibility type.
registrant_id_type AU contact's registrant id type.
registrant_id AU contact's registrant id.
eligibility_name AU contact's eligibility name.
eligibility_id_type AU contact's eligibility id type.
eligibility_id AU contact's eligibility id.

Example

In the below example, we will use the query without specifying any additonal parameters. This will list the first 100 contacts with default sorting options. (The equivalent of offset=0&limit=100&sort_by=id&order=asc).

Note: The response has been truncated in this example.

Query

https://www.above.com/registrar/api/query.html?query=manage_contacts

Use Registrar API key in place of {BEARER_TOKEN}

Response

<results code="100">
	<contacts total="2" offset="0" limit="100" sort_by="id" order="ASC">
	 <r contact="7962">
	  <id>7962</id>
	  <contact_identifier>725877</contact_identifier>
	  <name>test name</name>
	  <company>test company</company>
	  <email>test@trillion.com</email>
	  <phone>61.123456789</phone>
	  <address>test address</address>
	  <city>city</city>
	  <state>state</state>
	  <postcode>3000</postcode>
	  <country>AU</country>
	  <created>2015-09-04 10:49:46.996666</created>
	  <updated_date>2025-06-26 15:13:46</updated_date>
	  <contact_alias>725877</contact_alias>
	  <registrant_name>TEST IP REGISTRANT LTD.</registrant_name>
	  <registrant_id_type/>
	  <registrant_id/>
	  <eligibility_type>Pending TM Owner</eligibility_type>
	  <eligibility_name>TRILLION</eligibility_name>
	  <eligibility_id_type>TM</eligibility_id_type>
	  <eligibility_id>123456</eligibility_id>
	  <approved>Y</approved>
	  <elig_status>ACTIVE</elig_status>
	  <elig_error_reason/>
	 </r>
	 <r contact="7970">
	  <id>7970</id>
	  <contact_identifier>725877_464357</contact_identifier>
	  <name>Another test</name>
	  <company/>
	  <email>test@trillion.com</email>
	  <phone>44.987654321</phone>
	  <address>another test address</address>
	  <city>city</city>
	  <state>state</state>
	  <postcode>MK19 7BE</postcode>
	  <country>GB</country>
	  <created>2015-09-28 10:31:31.843788</created>
	  <updated_date>2022-11-30 21:28:33</updated_date>
	  <contact_alias>725877_464357</contact_alias>
	 </r>
	</contacts>

Example 2

You can use the contact_id paramater to search for one contact in your account and to return its details. In this example, we will fetch details for "7962" (contact_id=7962)

Query

https://www.above.com/registrar/api/query.html?query=manage_contacts&contact_id=7962

Use Registrar API key in place of {BEARER_TOKEN}

Response

<results code="100">
	<contacts total="1" offset="0" limit="100" sort_by="id" order="ASC">
	 <r contact="7962">
	  <id>7962</id>
	  <contact_identifier>725877</contact_identifier>
	  <name>test name</name>
	  <company>test company</company>
	  <email>test@trillion.com</email>
	  <phone>61.123456789</phone>
	  <address>test address</address>
	  <city>city</city>
	  <state>state</state>
	  <postcode>3000</postcode>
	  <country>AU</country>
	  <created>2015-09-04 10:49:46.996666</created>
	  <updated_date>2025-06-26 15:13:46</updated_date>
	  <contact_alias>725877</contact_alias>
	  <registrant_name>TEST IP REGISTRANT LTD.</registrant_name>
	  <registrant_id_type/>
	  <registrant_id/>
	  <eligibility_type>Pending TM Owner</eligibility_type>
	  <eligibility_name>TRILLION</eligibility_name>
	  <eligibility_id_type>TM</eligibility_id_type>
	  <eligibility_id>123456</eligibility_id>
	  <approved>Y</approved>
	  <elig_status>ACTIVE</elig_status>
	  <elig_error_reason/>
	 </r>
	</contacts>

Example 3

Various sorting options are available for the manage_contacts API function. In the below example, we will sort contacts by created date in descending order. This will show the most recently registered contacts first. (sort_by=created&order=desc).

Note: The response has been truncated in this example.

Query

https://www.above.com/registrar/api/query.html?query=manage_contacts&sort_by=created&order=desc

Use Registrar API key in place of {BEARER_TOKEN}

Response

<results code="100">
	<contacts total="2" offset="0" limit="100" sort_by="id" order="ASC">
	 <r contact="7970">
	  <id>7970</id>
	  <contact_identifier>725877_464357</contact_identifier>
	  <name>Another test</name>
	  <company/>
	  <email>test@trillion.com</email>
	  <phone>44.987654321</phone>
	  <address>another test address</address>
	  <city>city</city>
	  <state>state</state>
	  <postcode>MK19 7BE</postcode>
	  <country>GB</country>
	  <created>2015-09-28 10:31:31.843788</created>
	  <updated_date>2022-11-30 21:28:33</updated_date>
	  <contact_alias>725877_464357</contact_alias>
	 </r>
	 <r contact="7962">
	  <id>7962</id>
	  <contact_identifier>725877</contact_identifier>
	  <name>test name</name>
	  <company>test company</company>
	  <email>test@trillion.com</email>
	  <phone>61.123456789</phone>
	  <address>test address</address>
	  <city>city</city>
	  <state>state</state>
	  <postcode>3000</postcode>
	  <country>AU</country>
	  <created>2015-09-04 10:49:46.996666</created>
	  <updated_date>2025-06-26 15:13:46</updated_date>
	  <contact_alias>725877</contact_alias>
	  <registrant_name>TEST IP REGISTRANT LTD.</registrant_name>
	  <registrant_id_type/>
	  <registrant_id/>
	  <eligibility_type>Pending TM Owner</eligibility_type>
	  <eligibility_name>TRILLION</eligibility_name>
	  <eligibility_id_type>TM</eligibility_id_type>
	  <eligibility_id>123456</eligibility_id>
	  <approved>Y</approved>
	  <elig_status>ACTIVE</elig_status>
	  <elig_error_reason/>
	 </r>
	</contacts>

Example 3

The limit and offset parameters work exactly the same way they do in common database SQL. The offset parameter is the record you want to start at (0 is the first record) and the limit parameter is used to control how many records are returned.

To return details for contacts 1-10 for example, you would use the following:
offset=0&limit=10

For the second page of contacts (11-20), you would use the following:
offset=10&limit=10

For the third page of contacts (21-30), you would use the following:
offset=20&limit=10

If you were showing 100 contacts per page and wanted the third page of contacts (201-300), you would use the following:
offset=200&limit=100

Note: The response has been truncated in this example.

Query

In this example, there are a total of 150 contacts in the account, however we are trying to fetch contacts 201-300. We will receive an error as no records will be found for this query.

https://www.above.com/registrar/api/query.html?query=manage_contacts&offset=200&limit=100

Use Registrar API key in place of {BEARER_TOKEN}

Response

<results code="3001">
             <msg>No contacts found</msg>
            </results>

Error Codes

Possible error responses for this function are:

For a complete list of error responses, see the Error Codes manual page.

Introduction

Interface

Portfolio Manager

My Domains

Monetization

Sell Domains

Offers Received

Registrar

Reports

Common Actions

Monetization API

Queries

Registrar API

Queries

My Account Manual

Column Descriptions

Domain Details Page

Supported Domains

Quick Start Guide

Support and Help

API Queries - Manage Contacts

Additional Parameters

Response Values

Example

Query

Response

Example 2

Query

Response

Example 3

Query

Response

Example 3

Query

Response

Error Codes