You are here: Home > Get Support > Documentation > Developer Documentation > Resource Request API

Resource Request API

The Resource Request API allows you to submit requests for Internet number resources to the RIPE NCC.

Currently we support the following resource requests through the API:

The Request Resource API accepts HTTP POST messages with JSON in the payload specifying the resource request type and the information required by the RIPE NCC to process and accept the request.

Creating an API Access Key

To use this API, you must create an application specific API access key. In order to this, please follow these steps:

  • Log into the LIR Portal with a user account that has administrator credentials
  • Click the API Access Keys link in the Tools section
  • Create a key for the Resource Request API

Please note that you are responsible for maintaining your keys. You can create as many keys as you like and revoke unused keys as needed.

Usage

The Resource Request JSON payload for all requests share the same structure. The first part is generic and only the requestType is different per request type.

{
"requestType": "REQUEST_TYPE",
"contactPreferred": true,
"contactPersonName": "Tom Smith",
"contactPersonEmail": "tom.smith _at_ example _dot_ org",
"contactPhoneNumber": "+31634567890",
"additionalEmailDetail": "additional-1 _at_ example _dot_ com, additional-2 _at_ example _dot_ com",
"requestContent": {
Request Type specific JSON
}
}

The requestType, contactPreferred, contactPersonName and contactPersonEmail are required. As is the requestContent which is different for each request type. You specify that you would like to be contacted by specifying:

"contactPreferred": true

If you don't want to be contacted you can omit this property. The additionalEmailDetail property is also optional, if specified it contains the additional email addresses - comma separated - that will also receive a notification containing a summary of the request.

Using an ASN request as an example, a minimum generic part of the JSON could be:

{
"requestType": "AsnAssignment",
"contactPreferred": false,
"contactPersonName": "Tom Smith",
"contactPersonEmail": "tom.smith _at_ example _dot_ org",
"requestContent": {
Request Type specific JSON
}
}

In the following sections we will explain the specific requestContent parts of the JSON, depending on the request type.

Autonomous System (AS) Number Assignment

For requesting an AS Number assignment, the following endpoint is available:

https://my.ripe.net/api/external/v1/request/asn/assignment?key=YOUR_RESOURCE_REQUEST_API_KEY

The payload of the HTTP POST message for AS Number assignments:

{
"requestType": "AsnAssignment",
"contactPreferred": false,
"contactPersonName": "Tom Smith",
"contactPersonEmail": "tom.smith _at_ example _dot_ org",
"requestContent": {
"requires16BitAsn": true,
"requires16BitAsnRationale": "We have old-school equipment",
"asnName": "RIPE-NCC-AS",
"adminc": "my-admin-c",
"techc": "my-tech-c",
"mntBy": "my-mnt-by",
"mntRoutes": "my-mnt-routes",
"country": "NL",
"currentAsns": ["AS111", "AS222"],
"peeringPartners": [
{"asn": "AS333", "email": "partner-1 _at_ domain _dot_ com", "import": "from AS333 accept ANY", "export": "to AS333 announce ASNEW"},
{"asn": "AS444", "email": "partner-2 _at_ domain _dot_ com", "advancedRoutingPolicy": "from AS444 accept ANY"}
],
"addressPrefix": "22",
"onBehalfOfCustomer": true,
"customer": {
"organisation": "ORG-customer-RIPE",
"organisationName": "customer-org-name",
"adminc": "customer-admin-c",
"techc": "customer-tech-c",
"mntBy": "customer-mnt-by",
"mntRoutes": "customer-mnt-routes",
"website": "http://www.name.org"
},
"attachments": [
{
"fileName": "contract.pdf",
"content": "ZHVtbXkgY29udHJhY3Q="
},
{
"fileName": "agreement.pdf",
"content": "ZHVtbXkgY29udHJhY3Q="
}
]
}
}

Required fields are requires16BitAsn, requires16BitAsn, asnName, adminc, techc, mntBy, mntRoutes, country, currentAsns (may be an empty array), peeringPartners, addressPrefix and onBehalfOfCustomer.

If you specify that you would like a 16-bit ASN then the requires16BitAsnRationale is required, otherwise it can be omitted. If you don't have current AS Numbers then the currentAsns can be an empty array (e.g. []).

It is required to have a minimum of two peering partners and both ASN and email must be specified. You can either specify the import and export rules, or you can omit them and specify a advancedRoutingPolicy. Lastly, each peering partner must have a unique ASN.

If you make the request on behalf of a customer then the "customer" section is required. If you make the request for your own infrastructure the customer element can be omitted. Within the customer element the organisation, organisationName and website are required. The RIPE Database fields adminc, techc, mntBy and mntRoutes are optional within the customer element.

If you do make the request on behalf of a customer then you are required to submit at least one attachement with both fileName and content required. The content field is the actual contents of the file Base64 encoded.

If you don't make the request on behalf of a customer then this is an example of the minimum JSON required:

{
"requestType": "AsnAssignment",
"contactPreferred": false,
"contactPersonName": "Tom Smith",
"contactPersonEmail": "tom.smith _at_ example _dot_ org",
"requestContent": {
"requires16BitAsn": false,
"asnName": "RIPE-NCC-AS",
"adminc": "my-admin-c",
"techc": "my-tech-c",
"mntBy": "my-mnt-by",
"mntRoutes": "my-mnt-routes",
"country": "NL",
"currentAsns": [],
"peeringPartners": [
{"asn": "AS333", "email": "partner-1 _at_ domain _dot_ com", "import": "from AS333 accept ANY", "export": "to AS333 announce ASNEW"},
{"asn": "AS444", "email": "partner-2 _at_ domain _dot_ com", "import": "from AS444 accept ANY", "export": "to AS444 announce ASNEW"}
],
"addressPrefix": "22",
"onBehalfOfCustomer": false,
"attachments":[]
}
}

IPv4 First Allocation

For requesting an IPv4 First Allocation, the following endpoint is available:

https://my.ripe.net/api/external/v1/request/ipv4/allocation?key=YOUR_RESOURCE_REQUEST_API_KEY

The payload of the HTTP POST message for IPv4 First Allocations is:

{
"requestType": "Ipv4FirstAllocation",
"contactPreferred": false,
"contactPersonName": "Tom Smith",
"contactPersonEmail": "tom.smith _at_ example _dot_ org",
"requestContent": {
"prefixLength": 22,
"adminc": "my-admin-c",
"techc": "my-tech-c",
"mntRoutes": "my-mnt-routes",
"mntLower": "my-mnt-lower",
"country": "NL"
}
}

All of the fields in the payload are required and validated against the RIPE Database. The prefixLength is /22 for the first allocation and the request is not valid if the LIR has already received their last /22 allocation.

IPv6 First Allocation

For requesting an IPv6 First Allocation, the following endpoint is available:

https://my.ripe.net/api/external/v1/request/ipv6/allocation?key=YOUR_RESOURCE_REQUEST_API_KEY

The payload of the HTTP POST message for IPv6 First Allocations is:

{
"requestType": "Ipv6FirstAllocation",
"contactPreferred": false,
"contactPersonName": "Tom Smith",
"contactPersonEmail": "tom.smith _at_ example _dot_ org",
"requestContent": {
"prefixLength": 32,
"adminc": "my-admin-c",
"techc": "my-tech-c",
"mntRoutes": "my-mnt-routes",
"mntLower": "my-mnt-lower",
"country": "NL"
}
}

All of the fields in the payload are required and validated against the RIPE Database. The recommended prefixLength for an IPv6 First Allocation is /32. For allocations larger than a /29, it is required to provide documentation that justifies the request, such as the number of existing users or the extent of the organisation's infrastructure. The RIPE NCC will contact the requesting LIR as soon as possible to discuss the details.

IPv6 Provider Independent (PI) Assignment

For requesting IPv6 PI Assignments, the following endpoint is available:

https://my.ripe.net/api/external/v1/request/ipv6/pi-assignment?key=YOUR_RESOURCE_REQUEST_API_KEY

The payload of the HTTP POST message for IPv6 PI Assignments is:

{
"requestType": "Ipv6PIAssignment",
"contactPreferred": false,
"contactPersonName": "Tom Smith",
"contactPersonEmail": tom.smith _at_ example _dot_ org",
"requestContent": {
"prefixLength": 32,
"adminc": "my-admin-c",
"techc": "my-tech-c",
"mntBy": "my-mnt-by",
"country": "NL",
"providerIndependentRationale": ["I have routing reasons"],
"additionalProviderIndependentRationale": "Really urgent routing reasons",
"addressingPlans": [
{
"prefixLength": 39,
"period": "3 Months",
"purpose": "purpose1"
},
{
"prefixLength": 39,
"period": "1 Year",
"purpose": "purpose2"
},
{
"prefixLength": 39,
"period": "2 Years",
"purpose": "purpose3"
}
],
"onBehalfOfCustomer": true,
"customerOrganisation": "ORG-customer-RIPE",
"customerOrganisationName": "customer-org-name",
"customerWebsite": "http://www.name.org",
"customerMntBy": "customer-mnt-by",
"customerAdminc": "customer-admin-c",
"customerTechc": "customer-tech-c",
"attachments": [
{
"fileName": "contract.pdf",
"content": "ZHVtbXkgY29udHJhY3Q="
},
{
"fileName": "customer",
"content": "ZHVtbXkgY29udHJhY3Q="
}
]
}
}

Required fields are requestType (with the value Ipv6PIAssignment), contactPersonName, contactPersonEmail and contactPreferred in the main section. In the requestContent section, the fields prefixLength, adminc, techc, mntBy, country, onBehalfOfCustomer are required. In addition, the LIR is required to add at least addressingPlan to the addressingPlans array. If the request is made on behalf of a customer then the following fields are required: customerOrganisation (the ORG-ID of the customers organisation), customerOrganisationName and customerWebsite and at least one attachment. If the request is made on behalf of a customer then customerMntBy, customerAdminc and customerTechc are optional.

If you do make the request on behalf of a customer then you are required to submit at least one attachment (e.g. the End User Assignment Agreement and preferably the customer's company registration papers) with both fileName and content required. The content field is the actual contents of the file Base64 encoded. We provide a model agreement that you can use for this purpose.

Optional fields are additionalProviderIndependentRationale. The providerIndependentRationale is an array of rationale that will be reviewed by the RIPE NCC.

If you don't make the request on behalf of the customer, then this is an example of the minimum JSON required for an IPv6 PI Assignment:

{
"requestType": "Ipv6PIAssignment",
"contactPreferred": false,
"contactPersonName": "Tom Smith",
"contactPersonEmail": "Tom.Smith _at_ example _dot_ org",
"requestContent": {
"prefixLength": 32,
"adminc": "my-admin-c",
"techc": "my-tech-c",
"mntBy": "my-mnt-by",
"country": "NL",
"providerIndependentRationale": ["I want to be provider independant"],
"addressingPlans": [
{
"prefixLength": 32,
"period": "1 Year",
"purpose": "IP range to migrate away from Provider"
}
],
"onBehalfOfCustomer": false
}
}

Validation in General

All of the fields are validated both on presence (if mandatory) or on correctness (are they present in the RIPE Database, for example). If there are omissions in the JSON and/or invalid content then the response will have a status of 400 (Bad Request) and list all the errors in the request payload. The following response indicates that in the main 'obj' (e.g. the root of the JSON) the required regId was not provided.

{
"errors": [
{
"path": "obj",
"msg": "The regId is required"
}
]
}

If all of the required fields are present then the error message will report on invalid content. If, for example, the adminc, mntBy are not known and a asnName 'as-123-!' is provided, the response would be:

{
"errors": [
{
"path": "obj",
"msg": "invalid-role: admin-c object does not exist in the RIPE database"
},
{
"path": "obj",
"msg": "invalid-mnt: mnt-by object does not exist in the RIPE database"
},
{
"path": "obj",
"msg": "'as-123-!' is an invalid as-name"
}
]
}