Frequently Asked Questions - API (Automated Interface)

In order to trigger the automated status change for mark records in non-latin script on the OT&E interface, you can use the following number codes for trademark records, POU, UDRP Cases and Labels:

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

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 Downloads section, for more detailed information.

Poll messages are not stored 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 trademark 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:

To connect to the API v2, only 2 modifications are needed once 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 using TCP/TLS to: "api.trademark-clearinghouse.com:7701" for the PRODUCTION environment and "ote-api.trademark-clearinghouse.com:7701" for the OT&E environment respectively

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.

After your Trademark Agent account has been verified and you have received your credentials for the production environment, you need to request your credentials for the OT&E environment. You can do this by creating a ticket in our dedicated Customer Support System, either by clicking on "GET SUPPORT" on the TMCH interface or by sending an email to support[at]trademark-clearinghouse[dot]com. After receiving your credentials for the OT&E environment, you need to whitelist your IP address in order to access both environments.

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

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 Downloads section of our website.

Additionally, if you want to add an 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 our documentation on the API commands, available in the Downloads section.

Additionally if you want to create a trademark record with 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 trademark records (other than uploading a Proof of Use document or adding/removing labels) are only possible when the trademark record has been assigned the "incorrect" status.

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

Please refer to our documentation on the API commands for more detailed information, available in the Downloads section.

In the API, class 46 stands for "Not Applicable" or "N/A". If you have a registered trademark that does not follow the Nice classification, you can indicate this by using class 46.

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.

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

You will be able to retrieve comments added by a validator to your trademark record, via the INFO command. Please refer to our documentation on the API commands for more detailed information, available in the Downloads section.

On the OT&E, the trademark record 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 trademark record 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”.

Please refer to our documentation on the API commands for more detailed information, available in the Downloads section.

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

• secure.trademark-clearinghouse.com/tmch/public/labels?name=<trademark name*>&jurisdiction=<jurisdiction*> 

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

• secure.trademark-clearinghouse.com/tmch/public/labels?name=<trademark name*>&country=<country*> 

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:

• secure.trademark-clearinghouse.com/tmch/public/labels?name=<trademark name*>&jurisdiction=<jurisdiction*>&enc=a 

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

• secure.trademark-clearinghouse.com/tmch/public/labels?name=<trademark name*>&country=<country code*>&enc=a 

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 website's download section.

Please refer to our documentation on the API commands for detailed information, available in the Downloads section.

You can retrieve SMD files with the special INFO command as described in the API Documentation available on our website.

The actual code for the polling commands can be found in the API documentation available in the Downloads 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
  • 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
  • 251 The variant name [$dn] has been activated
  • 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 abovementioned 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 to receive the next message.

Polling is available on both the production and OT&E environment.

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

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

After your account has been verified, you can request your OT&E credentials by raising a Support ticket on our dedicated Customer Support System. To do this, click on "GET SUPPORT" on the TMCH interface or send an email to support[at]trademark-clearinghouse[dot]com. You will receive your OT&E credentials and the necessary URLs to access both the OT&E web interface and the OT&E API interface.

Please refer to our detailed manual on how to use the OT&E environment.

Please see the API documentation in our Downloads section for more information on how documents need to be sent through the API.