REST API – Domain Contacts

WEDOS REST API is still in development. Access and features may change without notice.

This article partially covers the Domains endpoint of WEDOS REST API. Domains and NSSETs have their own articles. For WEDOS API (WAPI) see WAPI – WEDOS Domain Contacts.

For basic information anbout WEDOS REST API, consult the WEDOS REST API Manual.

In this article, you will find the following information:

Contacts Endpoint Access

This API covers the management of domain contacts under the /v2/contacts URL prefix. You must always specify the TLD for contacts, because the format and validation of contact details differ by the registry the TLD belongs to.

Base URL and Authentication

The base URL for the contacts endpoints is: https://api.wedos.com/v2

All communication runs over HTTPS, and authentication uses only OAuth2: send the header Authorization: Bearer <TOKEN> with every request. The token must have the domains scope (one shared scope for domains, contacts and NSSETs). Without valid authentication the API returns an error.

Data requests (POST/PATCH) are sent as JSON (Content-Type: application/json).

You can add the parameter example=1 to any endpoint (e.g. ?example=1, or &example=1 if the URL already contains other query parameters). Instead of executing the request, the API then returns a sample curl command for that call. Valid authentication is required even in this mode.

Endpoint Overview

MethodEndpointDescription
GET/contacts/checkCheck availability/existence of a contact
GET/contacts/{cname}Contact information
POST/contacts/createCreate a new contact
POST/contacts/{cname}/transferTransfer a contact
POST/contacts/{cname}/auth-info/sendSend the contact’s authorization code
PATCH/contacts/{cname}Modify a contact

Response format

The API response is always a JSON object with the keys code (return code), msg (text description), request_id (request identifier) and, where applicable, data (returned data on success).

Besides the specific (business) return codes listed for each call below, all endpoints may also return these general REST-layer codes:

  • 1000 – the request was executed successfully
  • 2000 – authentication (OAuth2 Bearer token) missing or invalid
  • 2004 – maximum allowed request size exceeded (URL or request body)
  • 4000 – unknown/unsupported API method or action
  • 4001 – input data validation failed
  • 4005 – no example defined for the current URL form in example=1 mode
  • 6000 – internal error initializing request processing

GET /contacts/check

Checks whether a contact handle is free to use and what its status is at the registry.

Parameters:

  • tld – required, query, string – TLD for which the contact is checked
  • cname – required, query, string – contact handle (identifier)
  • reg_key – optional, query, string – identifier of a specific registry (if the TLD supports several registries/modes)

Return codes:

  • 1000 – the contact is free and usable
  • 2201 – invalid TLD
  • 2216 – invalid contact identifier format
  • 2218 – contacts are generated automatically at this registry (you cannot choose the handle)
  • 3228 – the registry does not support contacts
  • 3231 – the contact already exists
  • 3233 – the contact cannot be used
  • 3234 – the contact cannot be used – quarantine
  • 3235 – the contact cannot be used – reserved
  • 3236 – the contact cannot be used – blocked
  • 3237 – the contact is already registered with us
  • 4211 – contact check failed – connection error

Response data: None – the result is carried directly by the response’s code/msg.

Example:

curl -X GET -H 'Authorization: Bearer <TOKEN>' \
  'https://api.wedos.com/v2/contacts/check?tld=eu&cname=CONTACT'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3f1"
}

GET /contacts/{cname}

Returns detailed information about a contact.

Parameters:

  • cname – required, path – contact handle
  • tld – required, query, string – TLD under which the contact is looked up
  • auth_info – optional, query, string – the contact’s authorization code (if given, it must match the code set on the object, otherwise an error is returned)
  • reg_key – optional, query, string – identifier of a specific registry

Return codes:

  • 1000 – OK
  • 2201 – incorrectly specified TLD
  • 2216 – contact identifier syntax error
  • 3215 – invalid authorization code (given and does not match)
  • 3228 – the registry does not support contacts
  • 3229 – error loading the contact
  • 3236 – the contact is blocked
  • 4212 – connection error
  • 5001 – nobody is logged in

Response data:

  • contact – object with contact details:
    • contact_id, roid, status – identifier, ROID and status of the contact at the registry
    • name, fname, lname, company – name/first name/last name, or company name
    • addr_street, addr_city, addr_zip, addr_state, addr_country – address
    • phone, fax, email, email2 – contact details
    • ic, dic, taxpayer – company ID (IČ), tax ID (DIČ), VAT payer status
    • reg_owner, reg_creator, reg_update – registrar identifiers
    • created_date, updated_date, transfer_date – creation/update/transfer dates
    • disclose – data disclosure settings (per registry)
    • other – additional registry-specific data

Example:

curl -X GET -H 'Authorization: Bearer <TOKEN>' \
  'https://api.wedos.com/v2/contacts/CONTACT?tld=eu'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3f2",
  "data": {
    "contact": {
      "contact_id": "CONTACT",
      "status": "ok",
      "fname": "Esmeralda",
      "lname": "Excavadora",
      "company": null,
      "addr_street": "Street 123",
      "addr_city": "City",
      "addr_zip": "11000",
      "addr_country": "CZ",
      "phone": "+420.777123456",
      "email": "esmeralda@wedos.com",
      "created_date": "2024-01-10",
      "updated_date": null
    }
  }
}

POST /contacts/create

Creates a new domain contact for the given TLD.

Parameters:

  • tld – required, string – TLD for which the contact is created
  • reg_key – optional, string – identifier of a specific registry
  • contact – required, object – contact details; the available fields differ by registry, typically:
    • cname (optional) – requested contact handle; omit it for registries that generate handles automatically
    • fname, lname – first and last name (for a natural person)
    • company – company name (for a legal entity)
    • addr_street, addr_city, addr_zip, addr_state, addr_country – address
    • phone, fax, email, email2 – contact details
    • ic, dic, taxpayer – company ID (IČ), tax ID (DIČ), VAT payer status
    • other items depending on the specific registry

Return codes:

  • 1000 – contact created
  • 2100 – required parameter missing
  • 2101 – invalid input parameters
  • 2201 – invalid TLD
  • 2216 – invalid contact name
  • 2218 – contact names are created automatically at this registry (you cannot specify your own)
  • 2219–2242 – missing or invalid format of individual contact items (company, first name, last name, e-mail, phone, fax, company ID, tax ID, address, region, other data)
  • 3228 – the registry does not support contacts
  • 3230 – contact creation failed
  • 3231 – the contact name is already used
  • 3233 – the contact cannot be used
  • 3234 – the contact cannot be used – quarantine
  • 3236 – the contact cannot be used – blocked
  • 3237 – the contact is already registered with us
  • 4211 – check failed – communication error
  • 4213 – contact creation failed – communication error

Response data:

  • cname – handle of the created contact

Example:

curl -X POST -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  'https://api.wedos.com/v2/contacts/create' \
  --data '{
    "tld": "eu",
    "contact": {
      "fname": "Esmeralda",
      "lname": "Excavadora",
      "addr_street": "Street 123",
      "addr_city": "City",
      "addr_zip": "11000",
      "addr_country": "CZ",
      "email": "esmeralda@wedos.com",
      "phone": "+420.777123456"
    }
  }'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3f3",
  "data": {
    "cname": "CONTACT"
  }
}

POST /contacts/{cname}/transfer

Transfers a contact to us from another registrar (only at registries that support contact transfer, e.g. CZ.NIC).

Parameters:

  • cname – required, path – contact handle
  • tld – required, string – TLD
  • auth_info – required, string – the contact’s authorization code
  • reg_key – optional, string – identifier of a specific registry

Return codes:

  • 1000 – OK
  • 2100 – required parameter missing
  • 2101 – invalid input parameters
  • 2201 – invalid TLD
  • 2215 – parameter auth_info missing
  • 2216 – invalid contact identifier
  • 2244 – this domain/registry does not support contact transfer
  • 3229 – the contact is not available
  • 3237 – the contact is already registered with us
  • 3240 – authorization error
  • 3241 – transfer failed
  • 4216 – transfer failed – connection error

Response data: None – the result is carried directly by the response’s code/msg.

Example:

curl -X POST -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  'https://api.wedos.com/v2/contacts/CONTACT/transfer' \
  --data '{"tld": "cz", "auth_info": "AUTHCODE123"}'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3f4"
}

POST /contacts/{cname}/auth-info/send

Sends the contact’s authorization code to its contact e-mail.

Parameters:

  • cname – required, path – contact handle
  • tld – required, string – TLD
  • reg_key – optional, string – identifier of a specific registry

Return codes:

  • 1000 – OK
  • 2100 – required parameter missing
  • 2101 – invalid input parameters
  • 2201 – invalid TLD
  • 2216 – invalid contact name
  • 2243 – sending the authorization code is not allowed for this contact
  • 3213 – the contact is unavailable
  • 3215 – sending the code failed
  • 3228 – the registry does not support contacts
  • 4217 – sending failed – communication error
  • 5001 – authentication error

Response data: None – the result is carried directly by the response’s code/msg.

Example:

curl -X POST -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  'https://api.wedos.com/v2/contacts/CONTACT/auth-info/send' \
  --data '{"tld": "eu"}'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3f5"
}

PATCH /contacts/{cname}

Modifies the details of an existing contact. Cannot be used at registries where contacts are not editable (e.g. Ascio).

Parameters:

  • cname – required, path – contact handle
  • tld – required, string – TLD
  • auth_info – optional, string – the contact’s authorization code
  • contact – required, object – contact details to modify (same fields as in POST /contacts/create; only the given fields are changed)
  • reg_key – optional, string – identifier of a specific registry

Return codes:

  • 1000 – OK
  • 2100 – required parameter missing
  • 2101 – invalid input parameters
  • 2201 – invalid TLD
  • 2207 – syntax error
  • 2216 – invalid contact name
  • 2219–2241 – missing or invalid format of individual modified items (same range as for contact creation)
  • 3211 – failed to load the contact
  • 3238 – authorization error
  • 3239 – modification failed
  • 4202 – contact unavailable – connection error
  • 4215 – execution failed – connection error

Response data: None – the result is carried directly by the response’s code/msg.

Example:

curl -X PATCH -H 'Authorization: Bearer <TOKEN>' -H 'Content-Type: application/json' \
  'https://api.wedos.com/v2/contacts/CONTACT' \
  --data '{"tld": "eu", "contact": {"email": "esmeralda-new@wedos.com"}}'
{
  "code": 1000,
  "msg": "OK",
  "request_id": "a1b2c3f6"
}

Notes

  • The endpoints under /v2/domains, /v2/contacts and /v2/nssets are handled by one shared server class and all share one OAuth2 scope, domains. From the client’s point of view, they are three logically separate but administratively unified APIs.
  • For contacts, tld is always a required parameter, because the same handle (cname) may in theory exist at several registries, and the validation/format of the data differs by TLD/registry.

Was this helpful?

Thanks for your feedback!
Generic selectors
Exact matches only
Search in title
Search in content
Post Type Selectors
Article TOC
Browse Categories