Create Subaccount And Provide Contact Information
A subaccount is a member of an NIR. Resources can be delegated to subaccounts and transferred between them, as well as deallocated from them.
This tutorial assumes that you have an access token. If you do not have an access token, see Authentication for details on how to get one.
Please refer to the OpenAPI document for field definitions with redoc openapi
Create a subaccount object
To create a new subaccount object:
# Configure the access token.
$ export TOKEN=$access_token
# Configure the API base URL.
$ export BASE_URL=https://registry-testbed.apnic.net/nir-api
# Create a new subaccount object.
$ curl -s \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-X POST $BASE_URL/subaccounts \
--data-binary @- << EOF | jq
{
"name": "SA1",
"legalName": "Subaccount 1 Legal Name",
"economy": "US",
"companyId": "12345",
"startDate": "2020-01-30",
"jcard": [
"vcard",
[
[ "version", {}, "text", "4.0" ],
[ "kind", {}, "text", "org" ],
[ "fn", {}, "text", "Subaccount 1 Legal Name" ],
[ "adr", { "cc": "US", "label": "123 Main Street\nAny Town\nCA 91921-1234" },
"text", [ "", "", "123 Main Street", "Any Town", "CA", "91921-1234", "" ] ],
[ "email", {}, "text", "subaccount1@test.com" ]
]
],
"industryType": "academic-educational-research"
}
EOF
This will produce a task response:
{
"_links": {
"api:tasks": {
"href": "https://registry-testbed.apnic.net/nir-api/tasks/2"
},
"curies": [
{
"href": "https://registry-testbed.apnic.net/nir-api/docs/overview#{rel}",
"name": "api",
"templated": true
}
]
}
}
To fetch the task object:
$ curl -s \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
$BASE_URL/tasks/2 | jq
{
"id": 2,
"taskStatus": "SUCCESSFUL",
"_links": {
"self": {
"href": "https://registry-testbed.apnic.net/nir-api/tasks/2"
},
"related": {
"href": "https://registry-testbed.apnic.net/nir-api/subaccounts/1"
}
}
}
To fetch the subaccount object itself:
$ curl -s \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
$BASE_URL/subaccounts/1 | jq
{
"id": 1,
"name": "SA1",
"legalName": "Subaccount 1 Legal Name",
"economy": "US",
"jcard": [
"vcard",
[
[
"version",
{},
"text",
"4.0"
],
[
"kind",
{},
"text",
"org"
],
[
"fn",
{},
"text",
"Subaccount 1 Legal Name"
],
[
"adr",
{
"cc": "US",
"label": "123 Main Street\nAny Town\nCA 91921-1234"
},
"text",
[
"",
"",
"123 Main Street",
"Any Town",
"CA",
"91921-1234",
""
]
],
[
"email",
{},
"text",
"subaccount1@test.com"
]
]
],
"companyId": "12345",
"startDate": "2020-01-30",
"industryType": "academic-educational-research",
"_links": {
"self": {
"href": "https://registry-testbed.apnic.net/nir-api/subaccounts/1"
},
"api:rename": {
"href": "https://registry-testbed.apnic.net/nir-api/subaccounts/1/rename"
},
"preview": [
{
"href": "https://registry-testbed.apnic.net/nir-api/direct-delegations/{resource_type}/whois-preview",
"templated": true
},
{
"href": "https://registry-testbed.apnic.net/nir-api/nir-delegations/{resource_type}/whois-preview",
"templated": true
}
],
"api:default-entities": {
"href": "https://registry-testbed.apnic.net/nir-api/subaccounts/1/default-entities"
},
"curies": [
{
"href": "https://registry-testbed.apnic.net/nir-api/docs/overview#{rel}",
"name": "api",
"templated": true
}
]
}
}
Set default entities and Whois maintainers for subaccount resource delegation
Before a resource delegation can be made, a subaccount will need to provide contact and maintainer details for delegations in Whois and RDAP. The recommended way to provide this information is via the subaccount’s default entities endpoint (See: https://registry-testbed.apnic.net/nir-api/redoc#operation/updateDefaultEntitiesSubaccount).
There are three types of roles (administrative, technical, and abuse) that an entity in the API can be assigned to. When an entity is initially assigned to a role, the entity’s jCard information will be used to create Whois and RDAP records. An entity that is assigned to an administrative/technical role will result in a Whois role/person object and RDAP entity record being created. An entity that is assigned to an abuse role will result in a Whois IRT object and RDAP entity record being created. During delegation to subaccounts, the role information will be used to set the contact details of the delegation records in Whois and RDAP.
There are three different types of Whois default maintainer (mnt-by, mnt-lower, and mnt-routes) to which a value can be assigned. During delegation to subaccounts, this data is used to set the corresponding attribute in the Whois object.
At the moment, Whois maintainer objects will need to be created via MyAPNIC resource manager or mail updates, as the API does not currently provide interfaces for managing them.
$ curl -s \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-X PUT $BASE_URL/subaccounts/1/default-entities \
--data-binary @- << EOF | jq
{
"abuse": [ { "id": 2 } ],
"administrative": [ { "id": 1 } ],
"technical": [ { "id": 1 } ],
"whois-default-maintainers": {
"mnt-by": [ { "name": "MAINT-NIR1" } ],
"mnt-routes": [ { "name": "MAINT-NIR1" } ],
"mnt-lower": [ { "name": "MAINT-NIR1" } ]
}
}
EOF
{
"_links": {
"api:tasks": {
"href": "https://registry-testbed.apnic.net/nir-api/tasks/3"
},
"curies": [
{
"href": "https://registry-testbed.apnic.net/nir-api/docs/overview#{rel}",
"name": "api",
"templated": true
}
]
}
}
To fetch the task object:
$ curl -s \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
$BASE_URL/tasks/3 | jq
{
"id": 3,
"taskStatus": "SUCCESSFUL",
"_links": {
"self": {
"href": "https://registry-testbed.apnic.net/nir-api/tasks/3"
},
"related": {
"href": "https://registry-testbed.apnic.net/nir-api/subaccounts/1/default-entities"
}
}
}
Fetching the default entities and Whois maintainer objects:
$ curl -s \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
$BASE_URL/subaccount/1/default-entities | jq
{
"abuse": {
"_embedded": {
"api:entities": [
{
"external_id": "IRT-SUBACCOUNT1-AU",
"_links": {
"self": {
"href": "https://registry-testbed.apnic.net/nir-api/entities/2"
}
}
}
]
},
"_links": {}
},
"administrative": {
"_embedded": {
"api:entities": [
{
"external_id": "EN1-AP",
"_links": {
"self": {
"href": "https://registry-testbed.apnic.net/nir-api/entities/1"
}
}
}
]
},
"_links": {}
},
"technical": {
"_embedded": {
"api:entities": [
{
"external_id": "EN1-AP",
"_links": {
"self": {
"href": "https://registry-testbed.apnic.net/nir-api/entities/1"
}
}
}
]
},
"_links": {}
},
"whois-default-maintainers": {
"mnt-by": [
{
"external_id": "MAINT-NIR1",
"_links": {
"api:external": [
{
"href": "https://rdap.apnic.net/entity/MAINT-NIR1"
},
{
"href": "https://wq.apnic.net/static/search.html?query=MAINT-NIR1"
}
]
}
}
],
"mnt-lower": [
{
"external_id": "MAINT-NIR1",
"_links": {
"api:external": [
{
"href": "https://rdap.apnic.net/entity/MAINT-NIR1"
},
{
"href": "https://wq.apnic.net/static/search.html?query=MAINT-NIR1"
}
]
}
}
],
"mnt-routes": [
{
"external_id": "MAINT-NIR1",
"_links": {
"api:external": [
{
"href": "https://rdap.apnic.net/entity/MAINT-NIR1"
},
{
"href": "https://wq.apnic.net/static/search.html?query=MAINT-NIR1"
}
]
}
}
]
},
"_links": {
"api:whois-preview": {
"href": "https://registry-testbed.apnic.net/nir-api/subaccounts/3/default-entities/whois-preview{?netname,status}",
"templated": true
},
"api:whois-template": {
"href": "https://registry-testbed.apnic.net/nir-api/subaccounts/3/default-entities/whois-template"
},
"self": {
"href": "https://registry-testbed.apnic.net/nir-api/subaccounts/3/default-entities"
},
"curies": [
{
"href": "https://registry-testbed.apnic.net/nir-api/docs/overview#{rel}",
"name": "api",
"templated": true
}
]
}
}
An alternate way to provide contact and maintainer details (via Whois template)
An alternate way to provide contact and maintainer details for delegation is via the use of Whois template which will override default entities and maintainers details when creating Whois and RDAP records during delegation.
An example of a Whois template to be used for delegation:
netname: Test Netname
descr: 1 Test Street Australia
admin-c: EN1-AP
tech-c: EN1-AP
country: AU
status: ALLOCATED PORTABLE
mnt-by: MAINT-NIR1
mnt-lower: MAINT-NIR1
mnt-routes: MAINT-NIR1
mnt-irt: IRT-subaccount1-AU
source: APNIC
$ curl -s \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-X PUT $BASE_URL/subaccounts/1/default-entities \
--data-binary @- << EOF | jq
{
"abuse": [],
"administrative": [],
"technical": [],
"whois-default-maintainers": {},
"whois-template": "netname:test\ndescr:1 Test Street, Australia\nadmin-c:EN1-AP\ntech-c: EN1-AP\ncountry:AU\nstatus: ALLOCATED PORTABLE\nmnt-lower:MAINT-NIR1\nmnt-routes:MAINT-NIR1\nsource:APNIC"
}
EOF
This will produce a task response:
{
"_links": {
"api:tasks": {
"href": "https://registry-testbed.apnic.net/nir-api/tasks/4"
},
"curies": [
{
"href": "https://registry-testbed.apnic.net/nir-api/docs/overview#{rel}",
"name": "api",
"templated": true
}
]
}
}
To fetch the task object:
$ curl -s \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
$BASE_URL/tasks/4 | jq
{
"id": 4,
"taskStatus": "SUCCESSFUL",
"_links": {
"self": {
"href": "https://registry-testbed.apnic.net/nir-api/tasks/4"
},
"related": {
"href": "https://registry-testbed.apnic.net/nir-api/subaccounts/1/default-entities"
}
}
}
To view the Whois template itself:
$ curl -s \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
$BASE_URL/subaccounts/1/default-entities/whois-template | jq
netname:test
descr:1 Test Street, Australia
admin-c:EN1-AP
tech-c: EN1-AP
country:AU
status: ALLOCATED PORTABLE
mnt-lower:MAINT-NIR1
mnt-routes:MAINT-NIR1
source:APNIC
Can't find what you're looking for? Please contact the Software team.