GoDaddy Corporate Domains.png
API docs by Redocly

Brandsight API (1.0.0)

Download OpenAPI specification:

Getting Started

The following section will walk you through the steps and endpoints necessary to get started with basic domain name management functions via the Brandsight Domain API. A full list of available endpoints is available in the Domain Endpoints section.

API Key and Secret

To request your Brandsight account API Key and Secret:

  • Contact your Client Success Manager to request a unique API Key and Secret for your Brandsight account. Access to the Brandsight Domain API will be authenticated using these credentials.

Domain Availability

To check the availability and price for specific domain names:

  • Check if a domain name is available using the single domain availability endpoint.
    Note: SPEED checks do not connect to registry and are local checks to determine the outcome of the availability calls whereas ACCURACY checks connects to the registry, are more reliable and are recommended.

  • Check if a list of domain names is available using the bulk domains availability endpoint.

Domain Registration

To register an available domain name:

  1. Different TLDs require different payloads to be able to register a schema. Retrieve the Registration Schema for a specific TLD using the register schema endpoint and passing the tld. For example, send com to get the schema required for a .com registration.

  2. Validate the registration payload using the validation endpoint.

  3. Once the payload is validated, request to register the domain name using the register endpoint.

  4. Check status of the registration request using the actions endpoint and passing the type value as REGISTER.

Domain Renewal

To renew a managed domain name for a specified period:

  1. Retrieve the price for your specified registration term using the single domain availability endpoint and passing the type to RENEWAL and specifying the period in years.

  2. Include the exact amounts retrieved previously to renew an active domain name using renew endpoint.

  3. Check status of the renewal request using the actions endpoint and passing the type value as RENEW.

Domain Transfer In

To raise a transfer in request for a specific domain name:

  1. Determine transfer in availability of a domain name with AuthCode using the transferAvailable endpoint.

  2. Purchase and start or restart transfer in request for a domain name using the transfer endpoint.

  3. Cancel a transfer in request for a domain name using the TransferInCancel endpoint.

Domain Info

To retrieve the list of managed domain names in your account with/without the given filters:

  • Retrieve a list all the domain names in the account using the get domain endpoint. There are multiple filters that can be applied to filter the list. This endpoint will return a maximum of 500 domain names at a time.

  • Retrieve additional details about a domain name using the get domain details endpoint such as DNSSEC, contacts and authcode.

Domain AuthCode Regeneration

To regenerate an AuthCode for a specific managed domain name:

  1. Regenerate an AuthCode for a domain name using the regenerate endpoint.

  2. Check status of the AuthCode update request using the actions endpoint and passing the type value as AUTH_CODE_REGENERATE.

Domain Trademark Claims

To check for trademark claim on a specific domain name:

  • Check for any trademark claim on a domain name using the trademark endpoint.

Legal Agreements

To retrieve a list of legal agreements for a specific TLD:

  • Retrieve the list of legal agreements for a specific TLD using the agreements endpoint.

General Domain Update

To update the registrar lock or auto-renew status of a specific managed domain name:

  1. Update the locked status or auto-renew status of a domain name using the update domain endpoint.

  2. Check status of the update request using the actions endpoint and passing the type value as DOMAIN_UPDATE.

  3. Cancel a specific action for a domain using the actions cancel endpoint.

Nameservers Update

To update the nameservers of a specific managed domain name:

  1. Request to update the nameservers using the update nameserver endpoint. note: To delete nameservers, pass the list of name servers as an empty list.
  2. Check status of the nameserver update request using the actions endpoint and passing the type value as DOMAIN_UPDATE_NAME_SERVERS.

Privacy Service Update

It is only possible to toggle between "Brandsight Privacy"(Enable Privacy) and "GDPR"(Disable Privacy). For setting it to "Full Whois" option, please use the UI. To enable Brandsight Privacy Service for a specific managed domain name

  1. Enable privacy service for a domain name using the privacy on endpoint and passing the agreement keys that can be discovered using the agreements endpoint.

  2. Check status of the privacy service update request using the actions endpoint and passing the type value as PRIVACY_PURCHASE.

To disable Brandsight Privacy Service for a specific managed domain name:

  1. Remove privacy service for a domain name using the privacy off endpoint.

  2. Check status of the privacy service update request using the actions endpoint and passing the type value as PRIVACY_DELETE.

Contact Update

To update the contact details of a specific managed domain name:

  1. Retrieve the TLD specific schema to be submitted when creating a contact using the contact schema endpoint.

  2. Update the contact info of a managed domain name using the update contact endpoint.

  3. Check status of the contact update request using the actions endpoint and passing the type value as CONTACT_UPDATE.

DNSSEC Update

To create or update a DNSSEC record of a specific managed domain name:

  1. Create or update the DNSSEC records of a domain name using the update dnssec endpoint.

  2. Check status of the DNSSEC create or update request using the actions endpoint and passing the type value as DNSSEC_CREATE.

To delete a DNSSEC record of a specific managed domain name:

  1. Delete the DNSSEC records of a domain name using the delete dnssec endpoint.

  2. Check status of the DNSSEC delete request using the actions endpoint and passing the type value as DNSSEC_DELETE.

Domains

Retrieve a list of domain names for the specified Brandsight customer

path Parameters
customerId
required
string

The Brandsight customer identifier

query Parameters
statuses
Array of strings
Items Enum: "ACTIVE" "CANCELLED" "DELETED_REDEEMABLE" "EXPIRED" "FAILED" "LOCKED_REGISTRAR" "PARKED" "HELD_REGISTRAR" "OWNERSHIP_CHANGED" "PENDING_TRANSFER" "PENDING_REGISTRATION" "REPOSSESSED" "SUSPENDED" "TRANSFERRED"

Only include results with status value in the specified set

  • ACTIVE - Domain name has been registered and is active.
  • CANCELLED - Domain name has been cancelled by the user or system and is not reclaimable.
  • DELETED_REDEEMABLE - Domain name is deleted but is redeemable.
  • EXPIRED - Domain name has expired.
  • FAILED - Domain name registration or transfer error.
  • LOCKED_REGISTRAR - Domain name is locked at the registrar; this is usually the result of a spam, abuse, etc.
  • PARKED - Domain name has been parked.
  • HELD_REGISTRAR - Domain name is held at the registrar and cannot be transferred or modified; this is usually the result of a dispute.
  • OWNERSHIP_CHANGED Domain name has been moved to another account.
  • PENDING_TRANSFER - Domain name transfer has been requested and is pending the transfer process.
  • PENDING_REGISTRATION - Domain name is pending registration at the registry.
  • REPOSSESSED - Domain name has been confiscated; this is usually the result of a chargeback, fraud, abuse, etc.
  • SUSPENDED - Domain name is in violation and has been suspended.
  • TRANSFERRED - Domain name has been transferred to another registrar.
statusGroups
Array of strings
Items Enum: "PENDING" "REGISTERED" "PENDING_TERMINAL" "TERMINAL"

Only include results with status value in any of the specified domain lifecycle groups

  • PENDING - Domain name is in the process of being registered or transferred in, including PENDING_TRANSFER, PENDING_REGISTRATION.
  • REGISTERED - Domain name is registered, including ACTIVE, LOCKED_REGISTRAR, PARKED, HELD_REGISTRAR, SUSPENDED.
  • PENDING_TERMINAL - Domain name is expired and will be removed soon, including EXPIRED, DELETED_REDEEMABLE.
  • TERMINAL - Domain name has been cancelled, and is not reclaimable, including CANCELLED, FAILED, TRANSFERRED, REPOSSESSED, OWNERSHIP_CHANGED.
modifiedAtAfter
string <iso-datetime>

Only include domains with modifiedAt after the supplied date

expiresAtBefore
string <iso-datetime>

Only include domains with expiresAt between now and the supplied date

limit
integer [ 1 .. 500 ]

Maximum number of domains to return

marker
string <domain>

Marker Domain to use as the offset in results

includes
Array of strings
Items Value: "actions"

Optional details to be included in the response

Responses

Request samples 

curl --request GET \
--url 'https://api.godaddy.com/v2/customers/<CUSTOMER_ID>/domains?limit=10&marker=abc.com' \
--header 'Authorization: sso-key <API_KEY>:<SECRET>'

Response samples

Content type
[
  • {
    }
]

Retrieve details for the specified domain name

path Parameters
customerId
required
string

The Brandsight Customer identifier

domain
required
string <domain>

Domain name whose details are to be retrieved

query Parameters
includes
Array of strings
Items Enum: "authCode" "contacts" "dnssecRecords" "registryStatusCodes" "verifications"

Optional details to be included in the response

Responses

Request samples 

curl --request GET \
  --url https://api.godaddy.com/v2/customers/<CUSTOMER_ID>/domains/thujun9.com \
  --header 'Authorization: sso-key <API_KEY>:<SECRET>'

Response samples

Content type
{
  • "authCode": "string",
  • "contacts": {
    },
  • "createdAt": "string",
  • "deletedAt": "string",
  • "dnssecRecords": [
    ],
  • "domain": "string",
  • "domainId": "string",
  • "expirationProtected": true,
  • "expiresAt": "string",
  • "holdClient": true,
  • "holdRegistrar": true,
  • "hostnames": [
    ],
  • "locked": true,
  • "modifiedAt": "string",
  • "nameServers": [
    ],
  • "privacy": true,
  • "registryStatusCodes": [
    ],
  • "renewAuto": true,
  • "renewDeadline": "string",
  • "renewal": {
    },
  • "status": "ACTIVE",
  • "transferAwayEligibleAt": "string",
  • "transferProtected": true,
  • "verifications": {
    }
}

Update general details for the specified domain name

path Parameters
customerId
required
string

The Customer identifier

domain
required
string

Domain name whose details are to be updated

header Parameters
X-Request-Id
string

A client provided identifier for tracking this request.

Request Body schema: application/json
required

Changes to apply to existing Domain name

locked
boolean

Whether or not the domain name should be locked to prevent transfers

renewAuto
boolean

Whether or not the domain name should be configured to automatically renew

Responses

Request samples

Content type
application/json
{
  • "locked": true,
  • "renewAuto": true
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Determine whether the specified domain name is available for registration

query Parameters
domain
required
string

Domain name whose availability is to be checked

period
integer <integer-positive> [ 1 .. 10 ] ^[0-9]+$
Default: 1

The number of years to include in the price

type
string
Default: "REGISTRATION"
Enum: "REGISTRATION" "RENEWAL" "TRANSFER"

Check availability for registration, renewal or transfer

optimizeFor
string
Default: "SPEED"
Enum: "SPEED" "ACCURACY"

Optimize for time ('SPEED') or accuracy ('ACCURACY'). 'ACCURACY' is recommended

Responses

Request samples 

curl --request GET \
--url 'https://api.godaddy.com/v2/domains/available?domain=thujun10.com&period=1&type=REGISTRATION&optimizeFor=ACCURACY' \
--header 'Authorization: sso-key <API_KEY>:<SECRET>'

Response samples

Content type
{
  • "available": true,
  • "currency": "USD",
  • "definitive": true,
  • "domain": "string",
  • "period": 0,
  • "price": 0,
  • "reason": "INVALID_AUTH_CODE",
  • "registryPremiumPricing": true,
  • "rightsDomain": "string"
}

Determine whether the specified domains are available for registration

query Parameters
optimizeFor
string
Default: "SPEED"
Enum: "SPEED" "ACCURACY"

Optimize for time ('SPEED') or accuracy ('ACCURACY'). 'ACCURACY' is recommended.

Request Body schema: application/json
required

Domain names for which to check availability

Array
string

Responses

Request samples

Content type
application/json
[
  • "string"
]

Response samples

Content type
{
  • "domains": [
    ]
}

Retrieve the TLD-specific schema to use when registering a domain name

path Parameters
customerId
required
string

The Brandsight Customer identifier

tld
required
string

The Top-Level Domain whose schema should be retrieved

Responses

Request samples 

curl --request GET \
--url https://api.godaddy.com/v2/customers/<CUSTOMER_ID>/domains/register/schema/com \
--header 'Authorization: sso-key <API_KEY>:<SECRET>'

Response samples

Content type
{
  • "id": "string",
  • "models": { },
  • "properties": { },
  • "required": [
    ]
}

Validate a domain name registration request when using the TLD-specific schema

path Parameters
customerId
required
string

The Customer identifier

Request Body schema: application/json
required

An instance document expected to match the JSON schema returned by ./schema/{tld}

required
object (ConsentV2)
object (DomainContactsCreateV2)
domain
required
string <domain> ^[^.]{1,63}.[^.]{2,}$

For internationalized domain names with non-ascii characters, the domain name is converted to punycode before format and pattern validation rules are checked

metadata
object

The domain eligibility data fields as specified by GET /v2/customers/{customerId}/domains/register/schema/{tld}

nameServers
Array of strings <host-name> <= 2 items [ items <host-name > ]
period
integer <integer-positive> [ 1 .. 10 ] ^[0-9]+$
Default: 1
privacy
boolean
Default: false
renewAuto
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "consent": {
    },
  • "contacts": {
    },
  • "domain": "string",
  • "metadata": { },
  • "nameServers": [
    ],
  • "period": 1,
  • "privacy": false,
  • "renewAuto": true
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Register the specified domain name

path Parameters
customerId
required
string

The Customer identifier

header Parameters
X-Request-Id
string

A client provided identifier for tracking this request.

Request Body schema: application/json
required

An instance document expected to match the JSON schema returned by ./schema/{tld}

required
object (ConsentV2)
object (DomainContactsCreateV2)
domain
required
string <domain> ^[^.]{1,63}.[^.]{2,}$

For internationalized domain names with non-ascii characters, the domain name is converted to punycode before format and pattern validation rules are checked

metadata
object

The domain eligibility data fields as specified by GET /v2/customers/{customerId}/domains/register/schema/{tld}

nameServers
Array of strings <host-name> <= 2 items [ items <host-name > ]
period
integer <integer-positive> [ 1 .. 10 ] ^[0-9]+$
Default: 1
privacy
boolean
Default: false
renewAuto
boolean
Default: true

Responses

Request samples

Content type
application/json
{
  • "consent": {
    },
  • "contacts": {
    },
  • "domain": "string",
  • "metadata": { },
  • "nameServers": [
    ],
  • "period": 1,
  • "privacy": false,
  • "renewAuto": true
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Retrieve the legal agreement(s) required to register the specified TLD and add-ons

query Parameters
tlds
Array of strings

List of TLDs whose legal agreements are to be retrieved

privacy
boolean

Whether privacy has been requested

forTransfer
boolean

Whether or not domain transfer has been requested

Responses

Request samples 

curl --request GET \
--url 'https://api.godaddy.com/v2/customers/<CUSTOMER_ID>/domains/agreements?privacy=false&tlds=com' \
--header 'Authorization: sso-key <API_KEY>:<SECRET>'

Response samples

Content type
[
  • {
    }
]

Determine whether the specified domain name has a trademark claim

query Parameters
domain
required
string

Domain name to check for trademark claim

Responses

Request samples 

curl --request GET \
  --url 'https://api.godaddy.com/v2/domains/claim?domain=thujun9.com' \
  --header 'Authorization: sso-key <API_KEY>:<SECRET>'

Response samples

Content type
{
  • "claimToken": "string",
  • "claimed": false,
  • "url": "string"
}

Renew the specified domain name

path Parameters
customerId
required
string

The Customer identifier

domain
required
string

Domain name to be renewed

header Parameters
X-Request-Id
string

A client provided identifier for tracking this request.

Request Body schema: application/json

Options for renewing existing domain name

required
object (ConsentRenew)
expires
required
string <iso-datetime>

Current date when this domain name will expire

period
integer <integer-positive> [ 1 .. 10 ] ^[0-9]+$

Number of years to extend the Domain name registration term. Must not exceed maximum for TLD. When omitted, defaults to period specified during original purchase

Responses

Request samples

Content type
application/json
{
  • "consent": {
    },
  • "expires": "string",
  • "period": 1
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Add Brandsight privacy for the specified domain name

path Parameters
customerId
required
string

The Customer identifier

domain
required
string

Domain name for which to add privacy

header Parameters
X-Request-Id
string

A client provided identifier for tracking this request.

Request Body schema: application/json
required

Options for purchasing privacy

required
object (Consent)

Responses

Request samples

Content type
application/json
{
  • "consent": {
    }
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Submit a Brandsight privacy service cancellation request for the specified domain name

path Parameters
customerId
required
string

The Customer identifier

domain
required
string

Domain name whose privacy is to be cancelled

header Parameters
X-Request-Id
string

A client provided identifier for tracking this request.

Responses

Request samples 

curl --request DELETE \
  --url https://api.godaddy.com/v2/customers/<CUSTOMER_ID>/domains/thujun9.com/privacy \
  --header 'Authorization: sso-key <API_KEY>:<SECRET>'

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Retrieve the TLD-specific schema to use when updating a domain name contact

Variations across TLDs will be restrictions on the fields, not adding/removing fields.

path Parameters
customerId
required
string

The Customer identifier

tld
required
string

The Top-Level Domain whose schema should be retrieved

Responses

Request samples 

curl --request GET \
--url https://api.godaddy.com/v2/customers/<CUSTOMER_ID>/domains/contacts/schema/com \
--header 'Authorization: sso-key <API_KEY>:<SECRET>'

Response samples

Content type
application/json
{
  • "contacts": {
    },
  • "identityDocumentId": "string"
}

Update the contacts of a specified domain name

path Parameters
customerId
required
string

The Customer identifier

domain
required
string

Domain whose Contacts are to be updated.

header Parameters
X-Request-Id
string

A client provided identifier for tracking this request.

Request Body schema: application/json
required

Changes to apply to existing Contacts

object (DomainContactsCreateV2)
identityDocumentId
string

Unique identifier of the document, which the user wishes to associate with the domain name, whose registrant contact is being updated. This is required only if user is trying to update registrant contact and the owning registry has a requirement for an approved identity document.

Responses

Request samples

Content type
application/json
{
  • "contacts": {
    },
  • "identityDocumentId": "string"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Replace the existing nameservers on the specified domain name.

path Parameters
customerId
required
string

The Customer identifier

domain
required
string

Domain name whose name servers are to be replaced

header Parameters
X-Request-Id
string

A client provided identifier for tracking this request.

Request Body schema: application/json
required

Nameserver records to replace on the domain name

nameServers
Array of strings

Fully qualified domain names of name servers to associate with the domain name

Responses

Request samples

Content type
application/json
{
  • "nameServers": [
    ]
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Retrieve details for the given hostname and domain

path Parameters
customerId
required
string

The Customer identifier

domain
required
string

Domain which owns the host

hostname
required
string

Hostname to retrieve

Responses

Request samples 

curl --request GET \
  --url https://api.godaddy.com/v2/customers/<CUSTOMER_ID>/domains/example.com/hosts/ns1.example.com \
  --header 'Authorization: sso-key <API_KEY>:<SECRET>'

Response samples

Content type
application/json
{
  • "hostname": "string",
  • "ipAddresses": [
    ],
  • "status": "ACTIVE"
}

Delete given hostname

path Parameters
customerId
required
string

The Customer identifier

domain
required
string

Domain which owns the host

hostname
required
string

Hostname to delete

query Parameters
deleteLinked
boolean
Default: false

Whether or not the host should be deleted if it is linked.

Responses

Request samples 

curl --request DELETE \
  --url https://api.godaddy.com/v2/customers/<CUSTOMER_ID>/domains/example.com/hosts/ns1.example.com \
  --header 'Authorization: sso-key <API_KEY>:<SECRET>'

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Add DNSSEC records to the specified domain name

path Parameters
customerId
required
string

The Customer identifier

domain
required
string

Domain name to which to add the DNSSEC record

header Parameters
X-Request-Id
string

A client provided identifier for tracking this request.

Request Body schema: application/json
required

DNSSEC records to add

Array
algorithm
required
string
Enum: "RSASHA1" "RSASHA1_NSEC3_SHA1" "RSASHA256" "RSASHA512" "ECDSAP256SHA256" "ECDSAP384SHA384" "ED25519" "ED448" "PRIVATEDNS" "PRIVATEOID"

This identifies the cryptographic algorithm used to generate the signature

  • RSASHA1 - [05] RSA/SHA-1
  • RSASHA1_NSEC3_SHA1 - [07] RSASHA1-NSEC3-SHA1
  • RSASHA256 - [08] RSA/SHA-256
  • RSASHA512 - [10] RSA/SHA-512
  • ECDSAP256SHA256 - [13] ECDSA Curve P-256 with SHA-256
  • ECDSAP384SHA384 - [14] ECDSA Curve P-384 with SHA-384
  • ED25519 - [15] Ed25519
  • ED448 - [16] Ed448
  • PRIVATEDNS - [253] PRIVATE ALGORITHM
  • PRIVATEOID - [254] PRIVATE ALGORITHM OID
digest
string

The digest is an alpha-numeric value

digestType
string
Enum: "SHA1" "SHA256" "SHA384"

This identifies the algorithm used to construct the digest

  • SHA1 - [01] SHA-1
  • SHA256 - [02] SHA-256
  • SHA384 - [04] SHA-384
flags
string
Enum: "ZSK" "KSK"

This identifies the key type; either a Zone-Signing Key or a Key-Signing Key

  • ZSK - [256] Zone-Signing Key
  • KSK - [257] Key-Signing Key
keyTag
integer <integer-positive> <= 65536

This is an integer value less than 65536 used to identify the DNSSEC record for the domain name.

publicKey
string

Registries use this value to encrypt DS records. Decryption requires a matching public key

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Remove DNSSEC records from the specified domain name

path Parameters
customerId
required
string

The Customer identifier

domain
required
string

Domain name to delete the DNSSEC record for

header Parameters
X-Request-Id
string

A client provided identifier for tracking this request.

Request Body schema: application/json
required

DNSSEC records to remove

Array
algorithm
required
string
Enum: "RSASHA1" "RSASHA1_NSEC3_SHA1" "RSASHA256" "RSASHA512" "ECDSAP256SHA256" "ECDSAP384SHA384" "ED25519" "ED448" "PRIVATEDNS" "PRIVATEOID"

This identifies the cryptographic algorithm used to generate the signature

  • RSASHA1 - [05] RSA/SHA-1
  • RSASHA1_NSEC3_SHA1 - [07] RSASHA1-NSEC3-SHA1
  • RSASHA256 - [08] RSA/SHA-256
  • RSASHA512 - [10] RSA/SHA-512
  • ECDSAP256SHA256 - [13] ECDSA Curve P-256 with SHA-256
  • ECDSAP384SHA384 - [14] ECDSA Curve P-384 with SHA-384
  • ED25519 - [15] Ed25519
  • ED448 - [16] Ed448
  • PRIVATEDNS - [253] PRIVATE ALGORITHM
  • PRIVATEOID - [254] PRIVATE ALGORITHM OID
digest
string

The digest is an alpha-numeric value

digestType
string
Enum: "SHA1" "SHA256" "SHA384"

This identifies the algorithm used to construct the digest

  • SHA1 - [01] SHA-1
  • SHA256 - [02] SHA-256
  • SHA384 - [04] SHA-384
flags
string
Enum: "ZSK" "KSK"

This identifies the key type; either a Zone-Signing Key or a Key-Signing Key

  • ZSK - [256] Zone-Signing Key
  • KSK - [257] Key-Signing Key
keyTag
integer <integer-positive> <= 65536

This is an integer value less than 65536 used to identify the DNSSEC record for the domain name.

publicKey
string

Registries use this value to encrypt DS records. Decryption requires a matching public key

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Retrieve a list of the most recent actions for the specified domain name

path Parameters
customerId
required
string

The Customer identifier

domain
required
string

Domain name whose actions are to be retrieved

Responses

Request samples 

curl --request GET \
  --url https://api.godaddy.com/v2/customers/<CUSTOMER_ID>/domains/thujun23.com/actions \
  --header 'Authorization: sso-key <API_KEY>:<SECRET>'

Response samples

Content type
[
  • {
    }
]

Retrieve the most recent action for the specified domain name

path Parameters
customerId
required
string

The Customer identifier

domain
required
string

Domain name whose action is to be retrieved

type
required
string
Enum: "AUTH_CODE_PURCHASE" "AUTH_CODE_REGENERATE" "AUTO_RENEWAL" "DNS_VERIFICATION" "DNSSEC_CREATE" "DNSSEC_DELETE" "DOMAIN_DELETE" "DOMAIN_UPDATE" "DOMAIN_UPDATE_CONTACTS" "DOMAIN_UPDATE_DATA_QUALITY" "DOMAIN_UPDATE_NAME_SERVERS" "DOMAIN_UPDATE_REGISTRY_STATUS" "EXPIRY" "ICANN_VERIFICATION" "MIGRATE" "MIGRATE_IN" "PREMIUM" "PRIVACY_PURCHASE" "PRIVACY_DELETE" "REDEEM" "REGISTER" "RENEW" "RENEW_UNDO" "TRADE" "TRADE_CANCEL" "TRADE_PURCHASE" "TRADE_PURCHASE_AUTH_TEXT_MESSAGE" "TRADE_RESEND_AUTH_EMAIL" "TRANSFER" "TRANSFER_IN" "TRANSFER_IN_CANCEL" "TRANSFER_OUT" "TRANSFER_OUT_ACCEPT" "TRANSFER_OUT_REJECT" "TRANSFER_OUT_REQUESTED" "TRANSIT"

The action type to retrieve

Responses

Request samples 

curl --request GET \
  --url https://api.godaddy.com/v2/customers/<CUSTOMER_ID>/domains/thujun23.com/actions/REGISTER \
  --header 'Authorization: sso-key <API_KEY>:<SECRET>'

Response samples

Content type
{
  • "completedAt": "string",
  • "createdAt": "string",
  • "modifiedAt": "string",
  • "origination": "USER",
  • "reason": {
    },
  • "requestId": "string",
  • "startedAt": "string",
  • "status": "ACCEPTED",
  • "type": "AUTH_CODE_PURCHASE"
}

Cancel the most recent action for the specified domain name

path Parameters
customerId
required
string

The Customer identifier

domain
required
string

Domain name whose action is to be retrieved

type
required
string
Enum: "AUTH_CODE_REGENERATE" "CONTACT_UPDATE" "DNSSEC_CREATE" "DNSSEC_DELETE" "DOMAIN_UPDATE" "DOMAIN_UPDATE_CONTACTS" "DOMAIN_UPDATE_NAME_SERVERS" "PRIVACY_PURCHASE" "PRIVACY_DELETE" "REDEEM" "REGISTER" "RENEW" "TRANSFER_IN"

The action type to retrieve

Responses

Request samples 

curl --request DELETE \
  --url https://api.godaddy.com/v2/customers/<CUSTOMER_ID>/domains/thujun23.com/actions/TRANSFER_IN \
  --header 'Authorization: sso-key <API_KEY>:<SECRET>'

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Determine whether the specified domain names are available for transfer in

Request Body schema: application/json
required

Details for domain name transfer availability check

Array
authCode
string

Auth-Code, required for some TLDs, for domain name holder to transfer a domain name from one registrar to another

domain
required
string <domain> <= 255 characters

Domain name for which to check transfer availability

period
integer <integer-positive> [ 1 .. 10 ] ^([1-9]|10)$
Default: 1

The number of years to extend the registration term at time of transfer

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
{
  • "domains": [
    ]
}

Start or restart a transfer in request

path Parameters
customerId
required
string

The Customer identifier

domain
required
string

Domain name to transfer in

header Parameters
X-Request-Id
string

A client provided identifier for tracking this request.

Request Body schema: application/json
required

Details for domain transfer purchase

authCode
required
string

Auth-Code, required for some TLDs, for domain name holder to transfer a domain name from one registrar to another

required
object (ConsentV2)
object (DomainContactsCreateV2)
metadata
object

The domain name eligibility data fields as specified by GET /v2/customers/{customerId}/domains/register/schema/{tld}

period
integer <integer-positive> [ 1 .. 10 ] ^[0-9]+$
Default: 1

Can be more than 1 but no more than 10 years total including current registration term

privacy
boolean
Default: false

Whether Brandsight privacy service has been requested

renewAuto
boolean
Default: true

Whether the domain name should be configured to automatically renew

Responses

Request samples

Content type
application/json
{
  • "authCode": "string",
  • "consent": {
    },
  • "contacts": {
    },
  • "metadata": { },
  • "period": 1,
  • "privacy": false,
  • "renewAuto": true
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Cancels a transfer in request

path Parameters
customerId
required
string

The Customer identifier

domain
required
string

Domain Name

header Parameters
X-Request-Id
string

A client provided identifier for tracking this request.

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Regenerate the auth code for the specified domain name

path Parameters
customerId
required
string

The Customer identifier

domain
required
string

Domain name for which to update the authCode

header Parameters
X-Request-Id
string

A client provided identifier for tracking this request.

Responses

Request samples 

curl --request POST \
  --url https://api.godaddy.com/v2/customers/<CUSTOMER-ID>/domains/<DOMAIN>/regenerateAuthCode \
  --header 'Authorization: sso-key <API_KEY>:<SECRET>'

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Certificates v1

Create a pending order for certificate

Creating a certificate order can be a long running asynchronous operation in the PKI workflow. The PKI API supports 2 options for getting the completion stateful actions for this asynchronous operations: 1) by polling operations -- see /v1/certificates/{certificateId}/actions 2) via WebHook style callback -- see '/v1/certificates/{certificateId}/callback'.

header Parameters
X-Market-Id
string
Default: Default locale for shopper account

Setting locale for communications such as emails and error messages

Request Body schema: application/json
required

The certificate order information

callbackUrl
string

Required if client would like to receive stateful actions via callback during certificate lifecyle

commonName
string

Name to be secured in certificate. If provided, CN field in CSR will be ignored.

required
object (CertificateContact)
csr
required
string

Certificate Signing Request

intelVPro
boolean
Default: false

Only used for OV

object (CertificateOrganizationCreate)
period
required
integer

Number of years for certificate validity period

productType
required
string
Enum: "DV_SSL" "DV_WILDCARD_SSL" "EV_SSL" "OV_CS" "OV_DS" "OV_SSL" "OV_WILDCARD_SSL" "UCC_DV_SSL" "UCC_EV_SSL" "UCC_OV_SSL"

Type of product requesting a certificate. Only required non-renewal

rootType
string
Default: "STARFIELD_SHA_2"
Enum: "GODADDY_SHA_1" "GODADDY_SHA_2" "STARFIELD_SHA_1" "STARFIELD_SHA_2"

Root Type. Depending on certificate expiration date, SHA_1 not be allowed. Will default to SHA_2 if expiration date exceeds sha1 allowed date

slotSize
string
Enum: "FIVE" "TEN" "FIFTEEN" "TWENTY" "THIRTY" "FOURTY" "FIFTY" "ONE_HUNDRED"

Number of subject alternative names(SAN) to be included in certificate

subjectAlternativeNames
Array of strings unique

Subject Alternative names. Collection of subjectAlternativeNames to be included in certificate.

Responses

Request samples

Content type
application/json
{
  • "callbackUrl": "string",
  • "commonName": "string",
  • "contact": {
    },
  • "csr": "string",
  • "intelVPro": false,
  • "organization": {
    },
  • "period": 0,
  • "productType": "DV_SSL",
  • "rootType": "GODADDY_SHA_1",
  • "slotSize": "FIVE",
  • "subjectAlternativeNames": [
    ]
}

Response samples

Content type
application/json
{
  • "certificateId": "string"
}

Validate a pending order for certificate

header Parameters
X-Market-Id
string
Default: Default locale for shopper account

Setting locale for communications such as emails and error messages

Request Body schema: application/json
required

The certificate order info

callbackUrl
string

Required if client would like to receive stateful actions via callback during certificate lifecyle

commonName
string

Name to be secured in certificate. If provided, CN field in CSR will be ignored.

required
object (CertificateContact)
csr
required
string

Certificate Signing Request

intelVPro
boolean
Default: false

Only used for OV

object (CertificateOrganizationCreate)
period
required
integer

Number of years for certificate validity period

productType
required
string
Enum: "DV_SSL" "DV_WILDCARD_SSL" "EV_SSL" "OV_CS" "OV_DS" "OV_SSL" "OV_WILDCARD_SSL" "UCC_DV_SSL" "UCC_EV_SSL" "UCC_OV_SSL"

Type of product requesting a certificate. Only required non-renewal

rootType
string
Default: "STARFIELD_SHA_2"
Enum: "GODADDY_SHA_1" "GODADDY_SHA_2" "STARFIELD_SHA_1" "STARFIELD_SHA_2"

Root Type. Depending on certificate expiration date, SHA_1 not be allowed. Will default to SHA_2 if expiration date exceeds sha1 allowed date

slotSize
string
Enum: "FIVE" "TEN" "FIFTEEN" "TWENTY" "THIRTY" "FOURTY" "FIFTY" "ONE_HUNDRED"

Number of subject alternative names(SAN) to be included in certificate

subjectAlternativeNames
Array of strings unique

Subject Alternative names. Collection of subjectAlternativeNames to be included in certificate.

Responses

Request samples

Content type
application/json
{
  • "callbackUrl": "string",
  • "commonName": "string",
  • "contact": {
    },
  • "csr": "string",
  • "intelVPro": false,
  • "organization": {
    },
  • "period": 0,
  • "productType": "DV_SSL",
  • "rootType": "GODADDY_SHA_1",
  • "slotSize": "FIVE",
  • "subjectAlternativeNames": [
    ]
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Retrieve certificate details

Once the certificate order has been created, this method can be used to check the status of the certificate. This method can also be used to retrieve details of the certificate.

path Parameters
certificateId
required
string

Certificate id to lookup

Responses

Response samples

Content type
application/json
{
  • "certificateId": "string",
  • "commonName": "string",
  • "contact": {
    },
  • "createdAt": "string",
  • "deniedReason": "string",
  • "organization": {
    },
  • "period": 0,
  • "productType": "DV_SSL",
  • "progress": 0,
  • "revokedAt": "string",
  • "rootType": "GODADDY_SHA_1",
  • "serialNumber": "string",
  • "serialNumberHex": "string",
  • "slotSize": "FIVE",
  • "status": "PENDING_ISSUANCE",
  • "subjectAlternativeNames": [
    ],
  • "validEnd": "string",
  • "validStart": "string"
}

Retrieve all certificate actions

This method is used to retrieve all stateful actions relating to a certificate lifecycle.

path Parameters
certificateId
required
string

Certificate id to register for callback

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Resend an email

This method can be used to resend emails by providing the certificate id and the email id

path Parameters
certificateId
required
string

Certificate id to resend email

emailId
required
string

Email id for email to resend

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Add alternate email address

This method adds an alternate email address to a certificate order and re-sends all existing request emails to that address.

path Parameters
certificateId
required
string

Certificate id to resend emails

emailAddress
required
string

Specific email address to resend email

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "accountId": 0,
  • "templateType": "string",
  • "fromType": "string",
  • "recipients": "string",
  • "body": "string",
  • "dateEntered": "string",
  • "subject": "string"
}

Resend email to email address

This method can be used to resend emails by providing the certificate id, the email id, and the recipient email address

path Parameters
certificateId
required
string

Certificate id to resend emails

emailId
required
string

Email id for email to resend

emailAddress
required
string

Specific email address to resend email

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Retrieve email history

This method can be used to retrieve all emails sent for a certificate.

path Parameters
certificateId
required
string

Certificate id to retrieve email history

Responses

Response samples

Content type
application/json
{
  • "id": 0,
  • "accountId": 0,
  • "templateType": "string",
  • "fromType": "string",
  • "recipients": "string",
  • "body": "string",
  • "dateEntered": "string",
  • "subject": "string"
}

Unregister system callback

Unregister the callback for a particular certificate.

path Parameters
certificateId
required
string

Certificate id to unregister callback

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Retrieve system stateful action callback url

This method is used to retrieve the registered callback url for a certificate.

path Parameters
certificateId
required
string

Certificate id to register for stateful action callback

Responses

Response samples

Content type
application/json
{
  • "callbackUrl": "string"
}

Register of certificate action callback

This method is used to register/replace url for callbacks for stateful actions relating to a certificate lifecycle. The callback url is a Webhook style pattern and will receive POST http requests with json body defined in the CertificateAction model definition for each certificate action. Only one callback URL is allowed to be registered for each certificateId, so it will replace a previous registration.

path Parameters
certificateId
required
string

Certificate id to register/replace for callback

query Parameters
callbackUrl
required
string

Callback url registered/replaced to receive stateful actions

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Cancel a pending certificate

Use the cancel call to cancel a pending certificate order.

path Parameters
certificateId
required
string

Certificate id to cancel

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Download certificate

path Parameters
certificateId
required
string

Certificate id to download

Responses

Response samples

Content type
application/json
{
  • "pems": {
    },
  • "serialNumber": "string"
}

Reissue active certificate

Rekeying is the process by which the private and public key is changed for a certificate. It is a simplified reissue,where only the CSR is changed. Reissuing is the process by which domain names are added or removed from a certificate.Once a request is validated and approved, the certificate will be reissued with the new common name and sans specified. Unlimited reissues are available during the lifetime of the certificate.New names added to a certificate that do not share the base domain of the common name may take additional time to validate. If this API call is made before a previous pending reissue has been validated and issued, the previous reissue request is automatically rejected and replaced with the current request.

path Parameters
certificateId
required
string

Certificate id to reissue

Request Body schema: application/json
required

The reissue request info

callbackUrl
string

Required if client would like to receive stateful action via callback during certificate lifecyle

commonName
string
Default: "Existing common name"

The common name of certificate to be secured

csr
string
Default: "Existing CSR"

Certificate Signing Request.

delayExistingRevoke
integer <= 168
Default: 72

In hours, time to delay revoking existing certificate after issuance of new certificate. If revokeExistingCertOnIssuance is enabled, this value will be ignored

rootType
string
Default: "GODADDY_SHA_1"
Enum: "GODADDY_SHA_1" "GODADDY_SHA_2" "STARFIELD_SHA_1" "STARFIELD_SHA_2"

Root Type. Depending on certificate expiration date, SHA_1 not be allowed. Will default to SHA_2 if expiration date exceeds sha1 allowed date

subjectAlternativeNames
Array of strings unique

Only used for UCC products. An array of subject alternative names to include in certificate.

forceDomainRevetting
Array of strings unique

Optional field. Domain verification will be required for each domain listed here. Specify a value of * to indicate that all domains associated with the request should have their domain information reverified.

Responses

Request samples

Content type
application/json
{
  • "callbackUrl": "string",
  • "commonName": "Existing common name",
  • "csr": "Existing CSR",
  • "delayExistingRevoke": 72,
  • "rootType": "GODADDY_SHA_1",
  • "subjectAlternativeNames": [
    ],
  • "forceDomainRevetting": [
    ]
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Renew active certificate

Renewal is the process by which the validity of a certificate is extended. Renewal is only available 60 days prior to expiration of the previous certificate and 30 days after the expiration of the previous certificate. The renewal supports modifying a set of the original certificate order information. Once a request is validated and approved, the certificate will be issued with extended validity. Since subject alternative names can be removed during a renewal, we require that you provide the subject alternative names you expect in the renewed certificate. New names added to a certificate that do not share the base domain of the common name may take additional time to validate.

path Parameters
certificateId
required
string

Certificate id to renew

Request Body schema: application/json
required

The renew request info

callbackUrl
string

Required if client would like to receive stateful actions via callback during certificate lifecyle

commonName
string
Default: "Existing common name"

The common name of certificate to be secured

csr
string
Default: "Existing CSR"

Certificate Signing Request.

period
integer
Default: 0

Number of years for certificate validity period, if different from previous certificate

rootType
string
Default: "GODADDY_SHA_1"
Enum: "GODADDY_SHA_1" "GODADDY_SHA_2" "STARFIELD_SHA_1" "STARFIELD_SHA_2"

Root Type. Depending on certificate expiration date, SHA_1 not be allowed. Will default to SHA_2 if expiration date exceeds sha1 allowed date

subjectAlternativeNames
Array of strings unique

Only used for UCC products. An array of subject alternative names to include in certificate. Not including a subject alternative name that was in the previous certificate will remove it from the renewed certificate.

Responses

Request samples

Content type
application/json
{
  • "callbackUrl": "string",
  • "commonName": "Existing common name",
  • "csr": "Existing CSR",
  • "period": 0,
  • "rootType": "GODADDY_SHA_1",
  • "subjectAlternativeNames": [
    ]
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Revoke active certificate

Use revoke call to revoke an active certificate, if the certificate has not been issued a 404 response will be returned.

path Parameters
certificateId
required
string

Certificate id to revoke

Request Body schema: application/json
required

The certificate revocation request

reason
required
string
Enum: "AFFILIATION_CHANGED" "CESSATION_OF_OPERATION" "KEY_COMPROMISE" "PRIVILEGE_WITHDRAWN" "SUPERSEDED"

Reason for revocation

Responses

Request samples

Content type
application/json
{
  • "reason": "AFFILIATION_CHANGED"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}

Get Site seal

This method is used to obtain the site seal information for an issued certificate. A site seal is a graphic that the certificate purchaser can embed on their web site to show their visitors information about their SSL certificate. If a web site visitor clicks on the site seal image, a pop-up page is displayed that contains detailed information about the SSL certificate. The site seal token is used to link the site seal graphic image to the appropriate certificate details pop-up page display when a user clicks on the site seal. The site seal images are expected to be static images and hosted on the reseller's website, to minimize delays for customer page load times.

path Parameters
certificateId
required
string

Certificate id

query Parameters
theme
string
Default: "LIGHT"
Enum: "DARK" "LIGHT"

This value represents the visual theme of the seal. If seal doesn't exist, default values are used if params not present. If seal does exist, default values will not be used to update unless params present.

locale
string
Default: "en"

Determine locale for text displayed in seal image and verification page. If seal doesn't exist, default values are used if params not present. If seal does exist, default values will not be used to update unless params present.

Responses

Response samples

Content type
application/json
{
  • "html": "string"
}

Check Domain Control

Domain control is a means for verifying the domain included in the certificate order. This resource is useful for resellers that control the domains for their customers, and can expedite the verification process. See https://www.godaddy.com/help/verifying-your-domain-ownership-for-ssl-certificate-requests-html-or-dns-7452

path Parameters
certificateId
required
string

Certificate id to lookup

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "fields": [
    ],
  • "message": "string"
}