Inklings: a tumblelog

New EPP Parameters for the usTLD

For the benefit of anybody else integrating with the .us registry, this document outlines the values of the NexusCategory and AppPurpose fields to be specified in the <neulevel:unspec> extension element of a contact when registering a .us domain.

Keep in mind, however, that while the documentation documents the two fields mentioned above, it’s sorely out of date when it comes to their use. For this, you’ll need Neustar’s poorly documented ‘neulevel’ extension, which you can detect the presence of in the greeting with the extension namespace URI urn:ietf:params:xml:ns:neulevel (it’s actually urn:ietf:params:xml:ns:neulevel-1.0 because of implementation quirks in the Neustar EPP server). To use it, you put the following in the EPP <extension> element:

<neulevel:extension xmlns:neulevel="urn:ietf:params:xml:ns:neulevel-1.0">

Where DATA is actually a bunch of key/value pairs separated by spaces. Thus, if you were creating a contact with the application purpose code P3 (personal use) and the nexus category C12 (natural person), you would do the following:

<neulevel:extension xmlns:neulevel="urn:ietf:params:xml:ns:neulevel-1.0">
  <neulevel:unspec>AppPurpose=P3 NexusCategory=C12</neulevel:unspec>

For foreign entities (C31 and C32), the nexus category is followed by a slash and the country code of the country where the entity is based or has citizenship.

Application purpose field (AppPurpose) values:

Value Meaning
P1 Business use for profit
P2 Non-profit business, club, association, religious organisation
P3 Personal use
P4 Educational purpose
P5 Government purpose

Nexus category field (NexusCategory) values:

Value Meaning
C11 A natural person who is a US citizen
C12 A natural person who is a permanent resident
C21 An entity or organisation that is (i) incorporated within one of the fifty US states, the District of Columbia, or any of the US possessions or territories, or (ii) organised or otherwise constituted under the laws of a state of the US, the District of Columbia or any of its possessions and territories (including federal, state, or local government of the US, or a political subdivision thereof, and non-commercial organizations based in the US.)
C31/CC A foreign organization that regularly engages in lawful activities (sales of goods or services or other business, commercial, or non-commercial, including not for profit relations) in the United States. The CC equals to the two-letter country code of the organisation.
C32/CC An organisation has an office or other facility in the U.S., where CC equals to the two-letter country code of the organisation.

Only contacts used as registrants need to to have AppPurpose and NexusCategory assigned to them. Contacts used in other roles do not. If you attempt to use a contact without these set on them, you’ll get roughly the following response:

<?xml version="1.0" encoding="UTF-8"?>
<epp xmlns="urn:ietf:params:xml:ns:epp-1.0">
    <result code="2305">
      <msg lang="en-US">Object association prohibits operation</msg>
        <text>SRS Major Code: 5160</text>
        <text>SRS Minor Code: 51605</text>

The documentation on this is surprisingly awkward to find.