Contact tools

Preview

Connected applications are currently available to selected accounts only.

Six tools manage your domain contacts, the people and organisations your domains name as owner and admin contact. For what contacts are and why they are separate from your account, see Domains.

The tools

Tool	What it does	Needs
handle_list	Lists your contacts and whether their email address and phone number are verified, 5 per call. Every detail only for your default contacts	handle:read
handle_create	Adds a person or an organisation and returns it without the details it was given	handle:write
handle_update	Changes a contact. Every field is sent, and you give the application the unchanged ones from the portal	handle:write
handle_verify_request	Sends a contact a code by email or SMS. Says where only for your default contacts	handle:write
handle_verify_confirm	Confirms the code you received and passed on	handle:write
handle_verify_status	Shows whether a contact is verified and whether it is due again	handle:read

There is no tool that deletes a contact. You delete contacts in the portal.

Organisation details are published in WHOIS (RDDS) under NIS2, so for an organisation the application is told to suggest a functional email address such as domains@ over a personal one.

What an application sees of a contact

An application gets every detail only for your default contacts, marked Account Handle in the portal: the person created with your account and, if your account has an organisation, that organisation. Any other contact can hold another person's data, and ITSH passes that to no application.

Detail	Default contact	Any other contact
ID, type, country and whether the email address and phone number are verified	Yes	Yes
An organisation's company name	Yes	Yes
Name, address, phone and fax numbers, email address	Yes	No

Another contact comes with details_withheld and a panel_link to the contacts page in the portal, where you see the missing details. The fields are then left out, not empty. That has consequences for the other tools:

• handle_create returns the new contact as handle_list lists it, so without the details it was created with.
• handle_update makes the contact what is sent, so it needs every field. The application gets the unchanged ones from you rather than from handle_list: you see them in the portal.
• handle_verify_request names the partly masked address or number the code went to only for your default contacts.

Verifying an email address or phone number

1. The application calls handle_verify_request with email or phone.
2. The code reaches you by email or SMS. You tell the application the code.
3. The application calls handle_verify_confirm with the six-digit code.

Rule	Value
Code valid by email	15 minutes
Code valid by SMS	10 minutes
Wrong entries before a code is used up	5
A new request	Replaces the previous code
SMS go to	Mobile numbers in the EEA, Switzerland, the United Kingdom or your account's own country
SMS per account	5 a day
Verified again	A year after the email address was verified

An address or number already verified elsewhere on your account is verified at once, and no code is sent. The same holds for an address that is your account's own. The code is never kept in the activity log, not even as a checksum.

A changed email address or phone number has to be verified again.

What cannot change here, and why

The owner or admin contact of a domain. Only its phone and fax numbers can change through these tools. Its name, organisation, postal address and email address are the domain holder's, and who holds a domain is your decision alone. An application that tries gets registrant_change_requires_panel and a link to the contacts page in the portal.

Your default contacts. They follow your account's own details and cannot be changed on their own, by an application or in the portal. The refusal, default_contact_follows_account, links to your account details.

More than 25 contacts. An account holds at most 25. Beyond that, contact_limit_reached links to the contacts page, where you delete one you no longer need.

Other refusals

Code	Message	What to do
invalid_postcode	The postcode does not have the country's postcode format.	Correct the postcode
postcode_state_mismatch	The postcode is not in the given state.	Check the state's ISO 3166-2 code
invalid_code	The code is wrong, has expired, or is used up after five wrong tries.	Check the code, or request a new one
contact_changed	The contact's address or number changed while it was being verified, or this default contact does not hold the account's phone number yet.	Request a new code. For a default contact, save your account details again in the portal
phone_already_in_use	This phone number is already verified on another ITSH account.	Use a different number
phone_not_mobile	The number cannot receive a verification SMS: only mobile numbers in the EEA, Switzerland, the United Kingdom or the account's own country can.	Verify the email address instead
too_many_requests	Too many codes were requested for this address or number in the last hour.	Wait an hour
too_many_failures	Too many wrong codes were entered for this contact, address or number today.	Wait a day
sms_daily_limit	This account's verification SMS for today are used up.	Verify by email, or wait until the next day (UTC)
sms_unavailable	Verification SMS cannot be sent for the rest of the day.	Verify by email, or try the next day (UTC)

Limits

Limit	Value
Listing, adding and changing	5 requests a minute per account
Adding and changing	20 an hour for all connected applications together, apart from your own changes in the portal
Codes	10 email codes and 5 SMS codes an hour per account, shared with the portal
Registrar calls	Listing 1 per contact not listed in the last 2 minutes, adding 2, changing 4, a code request or confirmation 1, from the account's 6 a minute
Time per call	45 seconds; 10 for handle_verify_status

A call to handle_create that runs out of time may still have added the contact, so the application should list the contacts before trying again.

What's next

• Domains for what contacts are for
• Managing connections for what each change recorded