Frequently Asked Questions - API (Automated Interface)

In order to trigger the automated status change for mark records in non-latin script in the OT&E interface, you can use the following number codes.

  • valid (1000)
  • invalid (2000)
  • incorrect (3000)

for Mark Records, POU, UDRP Cases and Labels.

The number codes can also be used for mark records in latin script, but the original triggers will also work. Please refer to the OT&E documentation, in the download section, for more detailed information.

Tags: 

Poll messages are not stored on in the poll queue indefinitely,  depending on the age and  type of messages they will be removed from the poll queue and sent via mail to  the e-mail address linked to your account. This is a safety mechanism to ensure our API users are kept informed  of changes to their mark records and notifications, should there be an issue with connecting to the API interface.

Poll messages for API users are converted to e-mails under these circumstances:

  • At 12PM UTC an automated job runs that will check if you have any poll message in your queue older than 12 hours . If so the old poll  messages will be removed and sent via e-mail.
  • Every hour an automated job runs that will check if you have poll messages related to prepayment watermark levels that are older than 12 hours. If so they will be removed from the poll queue and sent via e-mail.
  • Every 4 hours a job will check for Claims or Sunrise notifications (NORDNs) that are older than 1h. They will be removed from the poll queue and sent via e-mail, conform ICANN requirements.

Yes, the trademark clearinghouse accepts trademarks consisting out of multiple scripts. However, please check with the applicable registry first as not all registries will accept a domain name consisting out of mixed scripts.

If you previously connected to API v1, to connect to the API v2 only 2 modifications are needed, if you already have a working client for the API v1:

Port number:

In order to access the API v2 you will need to adjust the port number you connect to: "91.198.126.138:7701" using TCP/TLS. The IP address in the example is that of the OT&E environment.

Header

In order to successfully communicate with the API v2 you will need to change 1 section of the header. For API v1 the header mentions "tmch-1.0", to connect to the API v2 this text needs to be changed to "tmch-1.1" By making these small changes you will already be able to connect to the API v2 and make use of the enhancements. Please be aware that if you would like to submit Abused Domain Name Labels via the API v2 further modifications are necessary. For a detailed overview of the API v2 please refer to: TMCH API2 Documentation & XSD

Yes. You can submit Abused Domain Name Labels via the API v2.

 

After your account has been verified and you have received both your credentials, for the Production and OT&E environment, you need to whitelist your IP address in order to access the environments.

The procedure is the same for Production and OT&E but must be performed on both environments:

  • Sign in to the environment where you wish to add or update the IP address;
  • Select "Submit Mark";
  • Select "My Account";
  • Select "API settings";
  • Enter the IP address you wish to whitelist (IPv4);
  • Select "Update API Settings".

Please note that it may take up to 30 minutes before the IP address is whitelisted.

 

The detailed commands to execute the CREATE command can be found in the API documentation in the download section of our website.

Additionally if you want to add and IDN label you will need to convert this label to puny code and use the aLabel(s) in the CREATE command, uLabel is not permitted and will be automatically generated based on the aLabel.

The detailed commands to execute the CREATE command can be found in the API documentation in the download section of our website.

Additionally if you want to create a Trademark record with a one or multiple labels attached you will need to use the aLabel(s) in the CREATE command, uLabel is not permitted and will be automatically generated based on the aLabel.

Please be aware that changes to mark records (other than uploading a Proof of Use document or adding/removing labels) are only possible when the mark record has been assigned status incorrect.

To update the name of a mark you need to follow the next steps in the exact order, in separate commands:

  • Update the name of the Mark (and other fields if necessary)

After executing the command to change the name of the Mark the existing labels attached to the Mark record will be automatically removed. (Notice : this is not an action, it is done automatically)

  • Add the labels you want, if any, to the Mark record (if you do not perform this step no labels will be attached to the Mark record)

The number of labels you can attach to the Mark record is either the number of labels originally attached to the Mark record or 10 labels, whichever number is biggest. Keep in mind adding labels is not possible when a Mark Record is being verified or when it is expired.

In the API class 46 stands for "Not Applicable". If you have a registered trademark where a NICE class does not apply you can use class 46 to indicate this.

Yes you can add new documents of the same type to trademark records if the mark has status incorrect.

Please be aware that the SMD Inclusion flag can only be set when a Proof of Use document has been uploaded (this can be done at any time except if the Mark record is being verified or is expired).

When enabling or disabling the smdInclusion flag(s) you need to follow the next steps in the exact order, in separate commands:

 

  • Remove the label(s);
  • Add the label(s) again with the smdInclusion flags enabled or disabled.

More specifically, to do this please send an update command with a <rem> section to delete the specific label(s) followed by an update <add> command to add the label(s) again with the appropriate flags set.

 

This procedure is relevant for the API v1. For the API v2 a simple update command can be used.

There is currently a limit of 2 connections from the whitelisted IP address linked to your account, on the production and OT&E environment.

 

If a validator added a comment to your mark record, you will be able to retrieve it via the INFO command.

Yes. We request the e-mail address of the trademark holder as a precautionary step as stated in the Clearinghouse Guidelines. Deloitte preserves to right to check this e-mail address’.

On the test environment the ID should start with a unique ID formatted in 6 digits left padded with zeros, followed by a string of digits (up to 54 digits) and ending in “-1”. To retrieve this unique ID you will need to use the create command with a random ID and the subsequent error message will tell you the correct format.

 

On the production environment the ID should start with the provided User-id (without the "u" )formatted in 6 digits left padded with zeros, followed by a string of digits (up to 54 digits) and ending in “-1”.

 

A url to generate labels for registered trademarks can be found below:

For marks protected under statute or treaty and court validated marks can be found below:

For example: https://secure.trademark-clearinghouse.com/tmch/public/labels?name=test@test&country=US will generate:

  • testtest
  • test-test
  • testattest

If your trademark contains an IDN character you will have to enter the puny code version of the label in the API create commands. You can use the following url in order get a preview of the puny code versions labels that would be accepted for a trademark:

A url to generate labels for registered trademarks can be found below:

For marks protected under statute or treaty and court validated marks can be found below:

For example: https://secure.trademark-clearinghouse.com/tmch/public/labels?name=tést@test&country=US&enc=a will generate:

  • xn--tsttest-bya
  • xn--tst-test-b1a
  • xn--tstattest-b4a

 

*Fields <trademark name>, <jurisdiction> and <country> must be filled in by the users (omitting the “<” and “>”). For a list of jurisdictions and country codes please refer to the API documentation Annexes available on our websites download section.

The actual code for the polling commands can be found in the API documentation available in the download section of our website.

Polling will allow you to receive and acknowledge messages regarding the following events:

  • Notifications on changes;
  • Notifications on claims;
  • Notifications on SMD creation;
  • Additional: watermark messages.

Notifications contain the following elements:

  • A counter that shows how many poll messages are in your queue;
  • The ID of the current message (the message that is displayed);
  • The POLL messages, each preceded by the message type unique identifier:
    • 102 Proof of use (POU) is expired
    • 103 Proof of use (POU) has been verified and approved
    • 104 Proof of use (POU) has not been approved and invalidated
    • 105 Proof of use (POU) is not approved. Further attention needed
    • 107 Mark certificate expired
    • 123 Mark record has been verified and approved
    • 124 Mark record is not approved. Further attention needed
    • 126 Mark record has not been approved and invalidated
    • 127 Mark record has not been corrected within 20 days and invalidated.
    • 134 Exception : validator still needs more info to approve mark
    • 137 Mark record expired
    • 138 Mark record has been deactivated
    • 146 Correction period expired
    • 148 Mark record has been deactivated
    • 154 Exception : user request to re-edit after changes
    • 164 Exception : mark record can be re-edited
    • 181 TREx applications will expire soon ($d days notice)
    • 182 TREx applications expired 
    • 190 POU will expire soon ($d days notice)
    • 191 Mark certificate will expire soon ($d days notice)
    • 196 Warning : Mark record about to be invalidated due to INCORRECT status time-out
    • 197 Your mark record is about to expire ($d days notice)
    • 199 Mark record transferred out/SMD has been revoked
    • 210 The domain name [$dn] was registered during sunrise
    • 220 The domain name [$dn] was registered during claims period
    • 230 The domain name [$dn] has been activated
    • 240 The domain name [$dn] has been registered in the Qualified Launch Program
    • 310 SMD has been created
    • 320 SMD has been regenerated
    • 330 SMD has been revoked
    • 400 Account status has gone below watermark level ($level)
    • 500 UDRP/Court case status change
  • The ID of the Trademark Record the poll message is referring to;
  • The name of the Mark Record the poll message is referring to.

If the current poll message has been processed you will need to send an acknowledgement, in the acknowledgement command you will need to use the ID of the current message, in order to de-queue the message and receive the next message.

In addition to the above mentioned notifications, a poll request can also provide you with a “watermark” message, if your pre-paid amount has gone below $1000.

Watermark messages contain the following elements:

  • A counter that shows how many poll messages are in your queue;
  • The ID of the current message (the message that is displayed);
  • A message preceded by the message type unique identifier: “400 Account status has gone below watermark level”

You will also have to de-queue this message with an acknowledgement command in order receive the next message.

Polling is available on the production and OT&E environments.

In addition to this, the API v2 also automatically adds the number of poll messages pending in the responses the API sends out.

 

Access to the test (OT&E) environment for the API is possible once you are a registered Trademark Agent.

After your account has been verified you will receive an e-mail containing your OT&E credentials and the URL's necessary to access the OT&E web interface and OT&E API interface.

For a detailed manual on how to use the OT&E environment please refer to our downloads section.

The test environment for the API is available for registered Trademark Agents. Once your account has been verified you will receive an e-mail with your credentials and connection information for the test environment.

Please see the API documentation in our Download section for more information on how document needs to be sent through the API.

An automated interface, to create, view and update mark records is available to agents, the latest version of the Automated Interface XSD scheme is available in our Download section