Contacts

Download schema

Endpoints for managing contacts.

List contacts

GET

https://domain.chief.app/api/v1

/contacts

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

List all contacts for the authenticated team.

List contacts › query Parameters

expand[]

string[]

Expand related resources.

Enum values:

parent

query

string · minLength: 1

Search query.

parent_handle

string

Filter contacts to only those that are sub-contacts of the given parent contact handle.

sort

string[] · maxItems: 5 · style: form

Sort by up to five fields, separated by commas. Prefix a field with - for descending order.

Enum values:

handle

-handle

is_default

-is_default

-id

Default: ["id"]

page

integer · min: 1

Default: 1

per_page

integer · min: 1 · max: 100

Default: 50

object

Search metadata key-value pairs. Only exact matches are supported.

List contacts › Responses

Paginated set of Contact

Contact[] · required

object · required

GET/contacts

curl https://domain.chief.app/api/v1/contacts \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": [
    {
      "handle": "handle",
      "parent": "string",
      "entity_type": "entity_type",
      "company_name": "company_name",
      "first_name": "first_name",
      "last_name": "last_name",
      "company_registration_number": "company_registration_number",
      "company_trading_name": "company_trading_name",
      "company_url": "company_url",
      "vat_registration": "vat_registration",
      "address_street": "address_street",
      "address_house_number": "address_house_number",
      "address_postal_code": "address_postal_code",
      "address_city": "address_city",
      "address_state": "address_state",
      "address_state_name": "address_state_name",
      "address_country_code": "NL",
      "email": "email",
      "phone": "+31 20 1234567",
      "extension_data": {
        "us_nexus_category": "us_nexus_category",
        "us_applicant_purpose": "us_applicant_purpose",
        "social_security_number": "social_security_number",
        "passport_number": "passport_number",
        "birth_date": "birth_date",
        "ficora_identity_code": "ficora_identity_code",
        "ficora_company_type": 0,
        "ie_contact_type": "ie_contact_type",
        "ie_cro_number": "ie_cro_number",
        "ie_supporting_number": "ie_supporting_number"
      },
      "is_default": true,
      "metadata": {
        "key": "string"
      }
    }
  ],
  "links": {
    "first": "first",
    "last": "last",
    "prev": "prev",
    "next": "next"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": "url",
        "label": "label",
        "active": true
      }
    ],
    "path": "path",
    "per_page": 0,
    "to": 1,
    "total": 0
  }
}

json

application/json

Create a new contact

POST

https://domain.chief.app/api/v1

/contacts

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Create a new contact for the authenticated team.

If a contact with identical details already exists for the team, the existing contact will be returned instead of creating a duplicate (HTTP 200 instead of 201). Use allow_duplicate: true to force creation of a new contact.

Create a new contact › query Parameters

expand[]

string[]

Expand related resources.

Enum values:

parent

Create a new contact › Request Body

first_name

string · maxLength: 255 · required

last_name

string · maxLength: 255 · required

address_street

string · maxLength: 255 · required

address_house_number

string · maxLength: 255 · required

address_postal_code

string · maxLength: 255 · required

Postal code in the format of the address country. Stored in the canonical format of that country, for example "1234 AB" for the Netherlands.

address_city

string · maxLength: 255 · required

address_country_code

string · minLength: 2 · maxLength: 2 · required

Country code in ISO 3166-1 alpha-2 format.

Example: NL

email

string · email · maxLength: 255 · required

E-mail address of the contact. The domain of the address must be able to receive e-mail.

phone

string · maxLength: 255 · required

Phone numbers need to be provided in international format.

Example: +31 20 1234567

entity_type

string · enum

General legal classification of the contact. When omitted, it is inferred from company_name.

Enum values:

individual

unincorporated_organization

organization

company_name

string | null · maxLength: 255

Company name. Required for organization and unincorporated organization contacts.

company_registration_number

string | null · maxLength: 255

If the contact is a company, this field could be required for some TLDs.

company_trading_name

string | null · maxLength: 255

Trading name for the company. Some registries require this as additional information.

company_url

string | null · uri · maxLength: 255

Company website URL. Some registries require this as additional information.

vat_registration

string | null · maxLength: 255

If the contact is a company, this field could be required for some TLDs.

address_state

string | null · maxLength: 255

State or province. Accepts either an abbreviation (e.g. "NY") or full name (e.g. "New York"). Stored as abbreviation.

object

TLD-specific extension data.

parent_handle

string | null

Handle of the parent contact. When provided, this contact will be grouped under the parent contact. This is purely for organizational purposes and has no effect on the use of the contact when registering or transferring domains.

Invalid handles will be ignored.

is_default

boolean

Indicates if the contact should be the default contact for the team.

allow_duplicate

boolean

When true, forces creation of a new contact even if one with identical details exists.

object

Optional metadata to attach to the contact. Metadata keys must be strings and cannot exceed 40 characters or contain [ or ] characters. Metadata values must be strings and cannot exceed 500 characters. A contact cannot have more than 50 metadata keys.

Example: {"key1":"value1","key2":"value2"}

Create a new contact › Responses

Contact

Contact · required

POST/contacts

curl https://domain.chief.app/api/v1/contacts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "entity_type": "individual",
  "company_name": "company_name",
  "company_registration_number": "company_registration_number",
  "company_trading_name": "company_trading_name",
  "company_url": "https://www.example.com/path/to/resource",
  "vat_registration": "vat_registration",
  "first_name": "first_name",
  "last_name": "last_name",
  "address_street": "address_street",
  "address_house_number": "address_house_number",
  "address_postal_code": "address_postal_code",
  "address_city": "address_city",
  "address_state": "address_state",
  "address_country_code": "NL",
  "email": "test@example.com",
  "phone": "+31 20 1234567",
  "extension_data": {
    "us_nexus_category": "C11",
    "us_applicant_purpose": "P1",
    "social_security_number": "social_security_number",
    "passport_number": "passport_number",
    "birth_date": "2024-08-25",
    "ficora_identity_code": "ficora_identity_code",
    "ficora_company_type": "1",
    "ie_contact_type": "CHA",
    "ie_cro_number": "ie_cro_number",
    "ie_supporting_number": "ie_supporting_number"
  },
  "parent_handle": "parent_handle",
  "is_default": true,
  "allow_duplicate": true,
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}'

Example Request Body

{
  "entity_type": "individual",
  "company_name": "company_name",
  "company_registration_number": "company_registration_number",
  "company_trading_name": "company_trading_name",
  "company_url": "https://www.example.com/path/to/resource",
  "vat_registration": "vat_registration",
  "first_name": "first_name",
  "last_name": "last_name",
  "address_street": "address_street",
  "address_house_number": "address_house_number",
  "address_postal_code": "address_postal_code",
  "address_city": "address_city",
  "address_state": "address_state",
  "address_country_code": "NL",
  "email": "test@example.com",
  "phone": "+31 20 1234567",
  "extension_data": {
    "us_nexus_category": "C11",
    "us_applicant_purpose": "P1",
    "social_security_number": "social_security_number",
    "passport_number": "passport_number",
    "birth_date": "2024-08-25",
    "ficora_identity_code": "ficora_identity_code",
    "ficora_company_type": "1",
    "ie_contact_type": "CHA",
    "ie_cro_number": "ie_cro_number",
    "ie_supporting_number": "ie_supporting_number"
  },
  "parent_handle": "parent_handle",
  "is_default": true,
  "allow_duplicate": true,
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}

json

Example Responses

{
  "data": {
    "handle": "handle",
    "parent": "string",
    "entity_type": "entity_type",
    "company_name": "company_name",
    "first_name": "first_name",
    "last_name": "last_name",
    "company_registration_number": "company_registration_number",
    "company_trading_name": "company_trading_name",
    "company_url": "company_url",
    "vat_registration": "vat_registration",
    "address_street": "address_street",
    "address_house_number": "address_house_number",
    "address_postal_code": "address_postal_code",
    "address_city": "address_city",
    "address_state": "address_state",
    "address_state_name": "address_state_name",
    "address_country_code": "NL",
    "email": "email",
    "phone": "+31 20 1234567",
    "extension_data": {
      "us_nexus_category": "us_nexus_category",
      "us_applicant_purpose": "us_applicant_purpose",
      "social_security_number": "social_security_number",
      "passport_number": "passport_number",
      "birth_date": "birth_date",
      "ficora_identity_code": "ficora_identity_code",
      "ficora_company_type": 0,
      "ie_contact_type": "ie_contact_type",
      "ie_cro_number": "ie_cro_number",
      "ie_supporting_number": "ie_supporting_number"
    },
    "is_default": true,
    "metadata": {
      "key": "string"
    }
  }
}

json

application/json

List specific contacts

POST

https://domain.chief.app/api/v1

/contacts/list

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Retrieve up to 100 contacts by handle. Results preserve the requested order, but contacts that do not exist or are not accessible to the authenticated team are omitted.

List specific contacts › Request Body

contacts

string[] · minItems: 1 · maxItems: 100 · required

List of contact handles to retrieve.

expand

string[]

Expand related resources.

Enum values:

parent

List specific contacts › Responses

Array of Contact

Contact[] · required

POST/contacts/list

curl https://domain.chief.app/api/v1/contacts/list \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "expand": [
    "parent"
  ],
  "contacts": [
    "string"
  ]
}'

Example Request Body

{
  "expand": [
    "parent"
  ],
  "contacts": [
    "string"
  ]
}

json

Example Responses

{
  "data": [
    {
      "handle": "handle",
      "parent": "string",
      "entity_type": "entity_type",
      "company_name": "company_name",
      "first_name": "first_name",
      "last_name": "last_name",
      "company_registration_number": "company_registration_number",
      "company_trading_name": "company_trading_name",
      "company_url": "company_url",
      "vat_registration": "vat_registration",
      "address_street": "address_street",
      "address_house_number": "address_house_number",
      "address_postal_code": "address_postal_code",
      "address_city": "address_city",
      "address_state": "address_state",
      "address_state_name": "address_state_name",
      "address_country_code": "NL",
      "email": "email",
      "phone": "+31 20 1234567",
      "extension_data": {
        "us_nexus_category": "us_nexus_category",
        "us_applicant_purpose": "us_applicant_purpose",
        "social_security_number": "social_security_number",
        "passport_number": "passport_number",
        "birth_date": "birth_date",
        "ficora_identity_code": "ficora_identity_code",
        "ficora_company_type": 0,
        "ie_contact_type": "ie_contact_type",
        "ie_cro_number": "ie_cro_number",
        "ie_supporting_number": "ie_supporting_number"
      },
      "is_default": true,
      "metadata": {
        "key": "string"
      }
    }
  ]
}

json

application/json

Show contact

GET

https://domain.chief.app/api/v1

/contacts/{contactHandle}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Show a single contact for the authenticated team.

Show contact › path Parameters

contactHandle

string · required

Show contact › query Parameters

expand[]

string[]

Expand related resources.

Enum values:

parent

Show contact › Responses

Contact

Contact · required

GET/contacts/{contactHandle}

curl https://domain.chief.app/api/v1/contacts/:contactHandle \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "data": {
    "handle": "handle",
    "parent": "string",
    "entity_type": "entity_type",
    "company_name": "company_name",
    "first_name": "first_name",
    "last_name": "last_name",
    "company_registration_number": "company_registration_number",
    "company_trading_name": "company_trading_name",
    "company_url": "company_url",
    "vat_registration": "vat_registration",
    "address_street": "address_street",
    "address_house_number": "address_house_number",
    "address_postal_code": "address_postal_code",
    "address_city": "address_city",
    "address_state": "address_state",
    "address_state_name": "address_state_name",
    "address_country_code": "NL",
    "email": "email",
    "phone": "+31 20 1234567",
    "extension_data": {
      "us_nexus_category": "us_nexus_category",
      "us_applicant_purpose": "us_applicant_purpose",
      "social_security_number": "social_security_number",
      "passport_number": "passport_number",
      "birth_date": "birth_date",
      "ficora_identity_code": "ficora_identity_code",
      "ficora_company_type": 0,
      "ie_contact_type": "ie_contact_type",
      "ie_cro_number": "ie_cro_number",
      "ie_supporting_number": "ie_supporting_number"
    },
    "is_default": true,
    "metadata": {
      "key": "string"
    }
  }
}

json

application/json

Update a contact

PATCH

https://domain.chief.app/api/v1

/contacts/{contactHandle}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Update properties of a single contact for the authenticated team.

You cannot update the name or company name of a contact. If you need to update these properties, you need to create a new contact.

Only the properties that are provided will be updated. If you omit a property it will not be changed.

Update a contact › path Parameters

contactHandle

string · required

Update a contact › query Parameters

expand[]

string[]

Expand related resources.

Enum values:

parent

Update a contact › Request Body

entity_type

string · enum

General legal classification of the contact. Personal contacts cannot be changed into business contacts or vice versa.

Enum values:

individual

unincorporated_organization

organization

company_registration_number

string | null · maxLength: 255

If the contact is a company, this field could be required for some TLDs.

company_trading_name

string | null · maxLength: 255

Trading name for the company. Some registries require this as additional information.

company_url

string | null · uri · maxLength: 255

Company website URL. Some registries require this as additional information.

vat_registration

string | null · maxLength: 255

If the contact is a company, this field could be required for some TLDs.

address_street

string · maxLength: 255

address_house_number

string · maxLength: 255

address_postal_code

string · maxLength: 255

Postal code in the format of the address country. Stored in the canonical format of that country, for example "1234 AB" for the Netherlands.

address_city

string · maxLength: 255

address_state

string | null · maxLength: 255

State or province. Accepts either an abbreviation (e.g. "NY") or full name (e.g. "New York"). Stored as abbreviation.

email

string · email · maxLength: 255

When updating the e-mail address of a contact that is in use. Please take care to verify the e-mail address if needed. Otherwise connected domains might be suspended. The domain of the address must be able to receive e-mail.

phone

string · maxLength: 255

Phone numbers need to be provided in international format.

Example: +31 20 1234567

object

TLD-specific extension data.

parent_handle

string | null

Invalid handles will be interpreted as removing the parent contact.

is_default

boolean

Indicates if the contact is the default contact for the team. Can only be true or unset.

object

To remove a metadata key, set its value to an empty string. To remove all metadata, set the metadata field to an empty object: {}.

Example: {"key1":"value1","key2":"value2"}

Update a contact › Responses

Contact

Contact · required

PATCH/contacts/{contactHandle}

curl https://domain.chief.app/api/v1/contacts/:contactHandle \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "entity_type": "individual",
  "company_registration_number": "company_registration_number",
  "company_trading_name": "company_trading_name",
  "company_url": "https://www.example.com/path/to/resource",
  "vat_registration": "vat_registration",
  "address_street": "address_street",
  "address_house_number": "address_house_number",
  "address_postal_code": "address_postal_code",
  "address_city": "address_city",
  "address_state": "address_state",
  "email": "test@example.com",
  "phone": "+31 20 1234567",
  "extension_data": {
    "us_nexus_category": "C11",
    "us_applicant_purpose": "P1",
    "social_security_number": "social_security_number",
    "passport_number": "passport_number",
    "birth_date": "2024-08-25",
    "ficora_identity_code": "ficora_identity_code",
    "ficora_company_type": "1",
    "ie_contact_type": "CHA",
    "ie_cro_number": "ie_cro_number",
    "ie_supporting_number": "ie_supporting_number"
  },
  "parent_handle": "parent_handle",
  "is_default": true,
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}'

Example Request Body

{
  "entity_type": "individual",
  "company_registration_number": "company_registration_number",
  "company_trading_name": "company_trading_name",
  "company_url": "https://www.example.com/path/to/resource",
  "vat_registration": "vat_registration",
  "address_street": "address_street",
  "address_house_number": "address_house_number",
  "address_postal_code": "address_postal_code",
  "address_city": "address_city",
  "address_state": "address_state",
  "email": "test@example.com",
  "phone": "+31 20 1234567",
  "extension_data": {
    "us_nexus_category": "C11",
    "us_applicant_purpose": "P1",
    "social_security_number": "social_security_number",
    "passport_number": "passport_number",
    "birth_date": "2024-08-25",
    "ficora_identity_code": "ficora_identity_code",
    "ficora_company_type": "1",
    "ie_contact_type": "CHA",
    "ie_cro_number": "ie_cro_number",
    "ie_supporting_number": "ie_supporting_number"
  },
  "parent_handle": "parent_handle",
  "is_default": true,
  "metadata": {
    "key1": "value1",
    "key2": "value2"
  }
}

json

Example Responses

{
  "data": {
    "handle": "handle",
    "parent": "string",
    "entity_type": "entity_type",
    "company_name": "company_name",
    "first_name": "first_name",
    "last_name": "last_name",
    "company_registration_number": "company_registration_number",
    "company_trading_name": "company_trading_name",
    "company_url": "company_url",
    "vat_registration": "vat_registration",
    "address_street": "address_street",
    "address_house_number": "address_house_number",
    "address_postal_code": "address_postal_code",
    "address_city": "address_city",
    "address_state": "address_state",
    "address_state_name": "address_state_name",
    "address_country_code": "NL",
    "email": "email",
    "phone": "+31 20 1234567",
    "extension_data": {
      "us_nexus_category": "us_nexus_category",
      "us_applicant_purpose": "us_applicant_purpose",
      "social_security_number": "social_security_number",
      "passport_number": "passport_number",
      "birth_date": "birth_date",
      "ficora_identity_code": "ficora_identity_code",
      "ficora_company_type": 0,
      "ie_contact_type": "ie_contact_type",
      "ie_cro_number": "ie_cro_number",
      "ie_supporting_number": "ie_supporting_number"
    },
    "is_default": true,
    "metadata": {
      "key": "string"
    }
  }
}

json

application/json

Delete a contact

DELETE

https://domain.chief.app/api/v1

/contacts/{contactHandle}

OpenID Connect

Bearer (ctp_*)

Bearer (ctt_*)

Delete a single contact for the authenticated team.

A contact can only be deleted if there is at least one contact left in the team and it's not used as a contact for any domain.

Delete a contact › path Parameters

contactHandle

string · required

Delete a contact › Responses

No content

No data returned

Mail Forwarding Team