Lookup (V2)

Lookup (V2) APIs allow an authenticated user to do the following: retrieve their permitted locations, retrieve their available patch panels list, retrieve their patch panel details, and retrieve their available service providers.

GET ConnectionServices

GET /connectionServices
Method GET
URL or End Point /colocations/v2/connectionServices
Headers Authorization, Content-Type
Query Parameters ibx
Body Not applicable

This method returns all available connections services within the specified IBX where the user has Cross Connect & Intra-Facility Cables ordering permission. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Access Token section.

The following screenshots show a sample curl request and JSON response for this method.

Copy 
curl -X
GET "https://api.equinix.com/colocations/v2/connectionServices?ibx=AT1"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

The description of the query parameter is as follows:

Query Parameter Name Mandatory Type Example Applicable Values Description
ibx Yes string AT1

IBX location code that represents the IBX data center where the user permissions.

For example, AT1 represents a data centre in Atlanta, USA.
Copy 
[
    {
        "name": "COAX",
        "mediaTypes": [
        {
            "name": "COAX",
            "protocolTypes": [
            {
                "name": "DS-3",
                "connectorTypes": [
                "BNC",
                "LC"
                ]
            } 
            ],
            "circuitCounts": []
        }
        ]
    },
    {
        "name": "Multi-Mode Fiber",
        "mediaTypes": [
            {
                "name": "62.5_MICRON_MULTI-MODE_FIBER_OM1",
                "protocolTypes": [
                    {
                        "name": "10_GIG_ETHERNET",
                        "connectorTypes": [
                            "SC",
                            "LC",
                            "ST",
                            "FC"
                        ]
                    }
                ],
                "circuitCounts": []
            },
            {
                "name": "62.5_MICRON_MULTI-MODE_FIBER",
                "protocolTypes": [
                   {
                        "name": "GIGABIT_ETHERNET",
                        "connectorTypes": [
                            "LC",
                            "SC",
                            "FC",
                            "ST"
                        ]
                   },
                  {
                        "name": "FAST_ETHERNET",
                        "connectorTypes": [
                        "SC",
                        "LC",
                        "ST",
                        "FC"
                        ]
                  },
                  {
                        "name": "FIBRE_CHANNEL",
                        "connectorTypes": [
                        "SC",
                        "LC",
                        "FC",
                        "ST"
                        ]
                  }
                ],
                "circuitCounts": []
            }
        ]
    }
]

The description of the response payload is as follows:

Field name Type Example Description
name string COAX

Name of the available connection service.

For a full list of connection services, media types, protocol types, and connector types, see List of Connection Services in the Appendix.

mediaTypes array [objects]

List of media types, protocol types, and connector types associated with the connection service. An object represents a media type and its corresponding protocol and connector types.

Each object comprises the following parameters: name, protocolTypes.
name string COAX Name of the media type associated with the connection service.
protocolTypes array [objects] List of protocol types and connector types associated with the media type. An object represents a protocol type and its corresponding connector types. Each object comprises the following parameters: name, connectorTypes.
name string DS-3 Name of the protocol type associated with the media type.
connectorTypes array [strings] BNC,
LC		 List of connector types associated with the connection service.
circuitCounts array [integers]

Intra-Faciltiy Cable (IFC) circuit count options available for the respective connection service.

When the 'circuitCounts' is empty, it means there are no available IFC circuits. If '3,6' appears in the circuit count, it means that the IFC circuits options available are 3 circuits and 6 circuits. The circuit count varies with the connection service.

The circuitCounts refers to the ifcCircuitCounts in the Cross Connects Order and indicates the accepted values of IFC circuits.

If you get “Insufficient permissions” error, contact your Master Administrator.

GET Locations

GET /locations
Method GET
URL or End Point /colocations/v2/locations
Headers Authorization, Content-Type
Query Parameters permissionCode, ibxs, providerAccountNumber, aSideIbx, details
Body Not applicable

The method returns all IBX locations, accounts, cages and cabinets information based on the authenticated user's permissions. For a user with cross connect ordering permissions, this method also returns their permitted locations for a given A-side or Z-side criteria. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Access Token section.

The following screenshot shows a sample curl request and JSON response.

Copy 
curl -X
GET "https://api.equinix.com/colocations/v2/locations?permissionCode=CROSS_CONNECT&providerAccountNumber=123&aSideIbx=AT1&details=true"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

The description of the query parameters is as follows:

When 'Conditional' is indicated for a Query Parameter, refer to Description for further details.

Query Parameter Name Mandatory Type Example Applicable values Description
permissionCode Yes string CROSS_CONNECT CROSS_CONNECT,
SHIPMENTS,
WORK_VISIT		 Filters user's locations according to the user's permissions. Only one permission code can be passed at a time.
ibxs No array [strings]

Filters the user's permitted IBX data centers (IBXs) associated with the 'permissionCode'. IBXs are represented by their IBX location code.

By specifying single or multiple IBXs (AT1 or AT1,AT3), the constraint is placed on specific IBXs.

This can be used with any permission code. When used with permission code 'CROSS_CONNECT', this is used to search for the A-side location information. To search for Z-side location information, see the following parameters: providerAccountNumber; aSideIbx, connectionService.

When an IBX is not specified, all the IBXs where the user has the specified permission will be returned.
providerAccountNumber Conditional string 123

Z-side provider's account number. This is mandatory when searching for Z-side location information.

This should only be used with cross connect permission code, and should only be used for searching Z-side location.
aSideIbx Conditional string AT1

A-side IBX location code. This is mandatory when searching for Z-side location information.

This should only be used with cross connect permission code, and should only be used for searching Z-side location.
details No boolean true true,
false

Determines if the locations information returned is detailed.

Default value : false

If 'true', locations information returned will include IBX locations and their corresponding cage, account, and cabinet details, and any other cross connect type-specific details.

If 'false', only the IBX location codes will be returned.

This can be used with any permission code.
connectionService Conditional string COAX COAX,
MP4_CABLE,
MULTI_MODE_FIBER,
POTS,
SINGLE_MODE_FIBER,
UTP

Name of the available connection service. This is mandatory when searching for Z-side location information. The IBXs are returned based on the supported connection service.

This should only be used with cross connect permission code, and should only be used for searching Z-side location.
Copy 
{
    "crossConnects": [
        {
            "ibx": "AT1",
            "accessRestricted": false,
            "specialPrivilege": false,
            "accounts": [
                {
                    "accountNumber": "123",
                    "accountName": "ACME Corp.",
                    "allowOrder": false
                }
            ],
            "cages": [
                {
                    "id": "AT1:01:020304",
                    "type": "SHARED",
                    "accountNumber": "123",
                    "cabinetId": "AT1:01:020304:0101",
                    "cabinetType": "PRIVATE"
                }
            ]
        }
    ]
}

The description of the response payload is as follows:

Field name Type Example Description
{permission} array [objects] crossConnects

List of the user's permitted locations specific to this permission. An object represents information for one IBX location.

Each object comprises the following parameters: ibx, accessRestricted, specialPrivilege, accounts, cages.
ibx string AT1 Permitted IBX.
accessRestricted boolean false

Indicates if the access to this IBX is restricted due to unforeseen circumstances.

If 'true', access to this IBX is limited and its services may be affected. Special privileges may also be required to access this IBX. Contact your local Global Service Desk for more information.

If 'false', there are no restrictions and no services are affected.

Default: false
specialPrivilege boolean false

Indicates if special privileges are required when access to the IBX is restricted. This is only applicable to telecommunications partners.

If 'true', special privileges are necessary to access an IBX with restricted access. Contact your local Global Service Desk for more information.

If 'false', special privileges are not required.

Default: false
accounts array [objects]

List of the user's permitted accounts that have a presence in this IBX. An object represents information for one permitted account.

When searching for Z-side location information, only one object is returned.

Each object comprises the following parameters: accountNumber, accountName, allowOrder.
accountNumber string 123

Account number.

When searching for Z-side location information, this is the provider account number.
accountName string ACME Corp.

Account name.

When searching for Z-side location information, this is the provider account name.
allowOrder string false

Indicates if orders are allowed for this account.

If 'true', orders can be placed from this account. If 'false', otherwise.

Default: true
cages array [objects]

List of cages that belong to the aforementioned accounts. An object represents information for one cage/cabinet combination.

Each object comprises the following parameters: id, type, accountNumber, cabinetId, cabinetType.
id string AT1:01:020304 Cage ID.
type string SHARED

Type of cage.

Cage type - Description
PRIVATE - Cage is exclusive to this account. No other accounts have a presence in this cage.
SHARED - Cage is shared by multiple accounts. When calling a POST method where including the 'accountNumber' is optional, it is recommended to include it when your cage is shared.
accountNumber string 123

Account number that has a presence in this cage.

This number is important to pass in your order requests, especially when there are multiple accounts related to the same cage.

cabinetId string AT1:01:020304:0101 Cabinet ID that belongs to this cage and account number.
cabinetType string PRIVATE

Type of cabinet.

Cabinet type - Description
PRIVATE - Cabinet is exclusive to this account. No other accounts have a presence in this cabinet.
DEMARCATION - Equinix-approved demarcation point.

If you get “Insufficient permissions” error, contact your Master Administrator.

GET PatchPanels

GET /patchPanels
Method GET
URL or End Point /colocations/v2/patchPanels
Headers Authorization, Content-Type
Query Parameters cabinetId, providerAccountNumber, aSideIbx, accountNumber
Body Not applicable

This method returns a list of all the available patch panels for an A-side or Z-side criteria to an authenticated user with Cross Connect & Intra-Facility Cables ordering permission. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Access Token section.

The following screenshots show sample curl requests for a patch panel search based on two scenarios, and the JSON response.

Searching for your available A-side patch panels

Copy 
curl -X
GET "https://api.equinix.com/colocations/v2/patchPanels?cabinetId=AM1:01:00EQ00:0001&accountNumber=901011"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

Searching for your available Z-side patch panels

Copy 
curl -X
GET "https://api.equinix.com/colocations/v2/patchPanels?cabinetId=AM5:01:00EQ00:0001&providerAccountNumber=100006&aSideIbx=AM1&accountNumber=901011"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

The description of the query parameters is as follows:

When 'Conditional' is indicated for a Query Parameter, refer to Description for further details.

Query Parameter name Mandatory Type Example Applicable values Description
cabinetId Yes string AM1:01:00EQ00:0001

Cabinet ID of your A-side or Z-side.

When searching for your A-side patch panels, pass an A-side cabinet ID.
When searching for your Z-side patch panels, pass a Z-side cabinet ID.
providerAccountNumber Conditional string 100006 Account number of your Z-side provider. This is mandatory when the search is for Z-side.
aSideIbx Conditional string AM1 IBX location code of your A-side. This is mandatory when the search is for Z-side.
accountNumber Conditional string 901011 Account number of your A-side. This is applicable when the search is for A-side, and the A-side account is in a shared cabinet.
Copy 
[
    {
        "patchPanelId": "CP:0112:13468516",
        "availablePortCount": 2,
        "patchPanelReferenceId": "AB:C46 (Equinix provided)",
        "ifcEnabled": true,
        "provisioningType": "REGULAR"
    },
    {
        "patchPanelId": "PP:0112:1142910",
        "availablePortCount": 16,
        "patchPanelReferenceId": "",
        "ifcEnabled": false,
        "provisioningType": "FAST_PROVISIONING"
    }
]

The description of the response payload is as follows:

Field name Type Example Description
patchPanelId string CP:0112:13468516 Patch panel ID.
availablePortCount number 2 Total number of available ports on this patch panel.
patchPanelReferenceId string AB:C46 (Equinix provided) Customer patch panel reference number.

DEPRECATION

preWired 		boolean true

DEPRECATION: Equinix will deprecate the prewired flag from the patch panel API by 1st July 2023.
Therefore, we strongly recommend reducing your dependency on this field. Instead, use the GET PatchPanels {patchPanelId} API to obtain the prewired flag.

Indicates if patch panel is prewired.

If 'true', patch panel is prewired. If 'false', otherwise.

Default: false
ifcEnabled boolean true

Indicates if this patch panel is an Intra-Facility Cable (IFC) panel type.

If 'true', this is an IFC panel type. If 'false', otherwise.

Default: false
provisioningType string REGULAR

Type of the provision of orders the patch panel supports.

Provisioning type - Description
REGULAR - order will be provisioned as per standard lead time.
FAST_PROVISIONING - order is typically provisioned in 30min through the support of fast provisioning scheduling. However, service may be delayed due to system maintenance.

If you get “Insufficient permissions” error, contact your Master Administrator.

GET PatchPanels {patchPanelId}

GET /patchPanels/{patchPanelId}
Method GET
URL or End Point /colocations/v2/patchPanels/{patchPanelId}
Headers Authorization, Content-Type
Query Parameters providerAccountNumber, aSideIbx, accountNumber
Body Not applicable

This method returns the details of an A-side or Z-side patch panel by its ID to an authenticated user with Cross Connect & Intra-Facility Cables ordering permission. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Access Token section.

The following screenshots show sample curl requests for a patch panel search based on two scenarios, and the JSON response.

Retrieving details for your A-side patch panel

Copy 
curl -X
GET "https://api.equinix.com/colocations/v2/patchPanels/CP:0112:13468516"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

Retrieving details for your Z-side patch panel

Copy 
curl -X
GET "https://api.equinix.com/colocations/v2/patchPanels/PP:0501:1093542?providerAccountNumber=100006&aSideIbx=AM1&accountNumber=901011"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

The description of the URL parameters is as follows:

URL Parameter name Mandatory Type Example Description
patchPanelId Yes string CP:0112:13468516

Patch panel ID for your A-side or Z-side.

When searching for your A-side patch panel, pass an A-side patch panel ID.
When searching for your Z-side patch panel, pass a Z-side patch panel ID.

The description of the query parameters is as follows:

When 'Conditional' is indicated for a Query Parameter, refer to Description for further details.

Query Parameter name Mandatory Type Example Applicable values Description
providerAccountNumber Conditional string 100006 Account number of your Z-side provider. This is mandatory when the search is for Z-side.
aSideIbx Conditional string AM1 IBX location code of your A-side. This is mandatory when the search is for Z-side.
accountNumber Conditional string 901011 Account number of your A-side. This is applicable when the search is for A-side, and the A-side account is in a shared cabinet.
Copy 
{
    "patchPanelId": "CP:0112:13468516",
    "ibx": "AM1",
    "cageId": "AM1:0G:00EQ11",
    "cabinetId": "AM1:0G:00EQ11:0001",
    "accountNumber": "901011",
    "accountName": "John Doe Corp",
    "dedicatedMediaType": "Fiber",
    "preWired": false,
    "type": "EQUINIX_PROVIDED",
    "ifcEnabled": false,
    "rackLocations": "Back",
    "installLocations": "STANDARD",
    "installationRequired": true,
    "circuitAvailable": true,
    "availablePorts": [
        4,
        5
    ],
    
    "provisioningType": "REGULAR",
    "connectionServices": [
        {
          "name": "MULTI_MODE_FIBER",
          "mediaTypes": [
            {
              "name": "50_MICRON_MULTI_MODE_FIBER_OM3",
              "protocolTypes": [
                {
                 "name": "100_GIG_ETHERNET",
                 "connectorTypes": [
                    "LC",
                    "SC",
                    "ST"
                ]
                }
              ],
              "circuitCounts": []
            },
            {
              "name": "62.5_MICRON_MULTI_MODE_FIBER",
              "protocolTypes": [
                {
                  "name": "FAST_ETHERNET",
                  "connectorTypes": [
                    "LC",
                    "SC",
                    "ST"
                ]
                },
                {
                  "name": "FIBRE_CHANNEL",
                  "connectorTypes": [
                    "LC",
                    "SC",
                    "ST"
                ]
                }
            ],
            "circuitCounts": []
            }
        ]
        }
    ],
    "usedPortsDetails": [
        {
            "portNumber": "2",
            "serialNumber": "20619401",
            "connectionServicesName": "MULTI_MODE_FIBER",
            "zSideProviderName": "Acme Network Services",
            "circuitId": "1-12312312"
        },
        {
            "portNumber": "3",
            "serialNumber": "20619401",
            "connectionServicesName": "MULTI_MODE_FIBER",
            "zSideProviderName": "Acme Network Services",
            "circuitId": "-"
        },
        {
            "portNumber": "1",
            "serialNumber": "20619399",
            "connectionServicesName": "MULTI_MODE_FIBER",
            "zSideProviderName": "Acme Network Services",
            "circuitId": "-"
        }
    ]
}

The description of the response payload is as follows:

Field name Type Example Description
patchPanelId string PP:0501:1093542 Patch panel ID.
ibx string AM1 IBX location code associated with the patch panel.
cageId string AM1:0G:00EQ1 ID of cage associated with the patch panel.
cabinetId string AM1:0G:00EQ11:0001 ID of cabinet associated with the patch panel.
accountNumber string 901011 Customer account number associated with this patch panel.
accountName string John Doe Corp Customer account name associated with this patch panel.
dedicatedMediaType string Fiber Type of media dedicated to this patch panel.
preWired boolean false

Indicates if patch panel is prewired.

If 'true', patch panel is prewired. If 'false', otherwise.
type string EQUINIX_PROVIDED

Provision type of patch panel.

Type - Description
CUSTOMER_PROVIDED - Patch panel was provided by the customer.
EQUINIX_PROVIDED - Patch panel was provided by Equinix.
ifcEnabled boolean false

Indicates if this patch panel is an Intra-Facility Cable (IFC) panel type.

If 'true', this is an IFC panel type. If 'false', otherwise.
rackLocations string Back Location of the patch panel on the rack or cabinet.
installLocations string STANDARD

Location of the patch panel installation in the cabinet.

Install Locations - Description
STANDARD -
installationRequired boolean true

Indicates if patch panel required installation from Equinix.

If "true', patch panel was installed by Equinix. If 'false', patch panel was installed by customer.
circuitAvailable boolean true

Indicates if there are available circuits.

If 'true', circuits are available. If 'false', otherwise.
availablePorts array [numbers] 4, 5 List of available ports on this patch panel.
provisioningType string REGULAR

Type of the provision of orders the patch panel supports.

Provisioning type - Description
REGULAR - order will be provisioned as per standard lead time.
FAST_PROVISIONING - order is typically provisioned in 30min through the support of fast provisioning scheduling. However, service may be delayed due to system maintenance.
connectionServices array [objects]

List of available connection services for this patch panel.

Each connection service object comprises the following parameters: name, mediaTypes, circuitCounts.

For a full list of connection services, media types, protocol types, and connector types, see List of Connection Services in the Appendix.

name string MULTI_MODE_FIBER Name of the connection service.
mediaTypes array [objects]

List of available media types associated with the connection service.

Each media type object comprises the following parameters: name, protocolTypes.
name string 50_MICRON_MULTI_ MODE_FIBER_OM3

Name of media type associated with the connection service.

For a full list of media types, see description of 'connectionServices'.
protocolTypes array [objects]

List of available protocol types associated with the media type.

Each protocol type object comprises the following parameters: name, connectorTypes.
name string 100_GIG_ETHERNET

Name of protocol type associated with the media type.

For a full list of protocol types, see description of 'connectionServices'.
connectorTypes array [strings] LC, SC, ST

List of available connector types associated with the protocol type.

For a full list of connectory types, see description of 'connectionServices'.
circuitCounts array [integers]

Available circuit count for the IFC enabled patch panel.

The circuitCounts refers to the ifcCircuitCounts in the Cross Connects Order and indicates the accepted values of IFC circuits.

usedPortsDetails array [objects]

List of used ports on this patch panel.

Each used port object comprises the following parameters: portNumber, serialNumber, connectionServicesName, zSideProviderName, circuitId.
portNumber string 2 Port number that is already in use.
serialNumber string 20619401 Serial number or ID of the cable occupying the port, if applicable.
connectionServicesName string MULTI_MODE_FIBER

Indicates if this patch panel is an Intra-Facility Cable (IFC) panel type.

If 'true', this is an IFC panel type. If 'false', otherwise.

Default: false
zSideProviderName string Acme Network Services Z-side provider's account name associated with this occupied port.
circuitId string 1-12312312

Z-side circuit ID cable reference number for verification purposes.
This is the same circuit ID as used when you create Cross Connects Order.

Default: '-'

If you get “Insufficient permissions” error, contact your Master Administrator.

GET Providers

GET /providers
Method GET
URL or End Point /colocations/v2/providers/
Headers Authorization, Content-Type
Query Parameters cageId, accountNumber
Body Not applicable

This method returns all available Z-side providers to an authenticated user with Cross Connect & Intra-Facility Cables ordering permission. The authorization token and content-type are the only headers that are passed to this API and a response is received based on the values passed.

If you are unaware of how to obtain an authorization token, refer to Requesting Access and Refresh tokens under the Getting Access Token section.

The following screenshot shows a sample curl request and the JSON response.

Copy 
curl -X
GET "https://api.equinix.com/colocations/v2/providers?cageId=AM1:01:00EQ00&accountNumber=101010"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"

The description of the query parameters is as follows:

Query Parameter name Mandatory Type Example Applicable values Description
cageId Yes string AM1:01:00EQ00 A-side cage ID.
accountNumber Yes string 101010 A-side account number.
Copy 
[
    {
        "providerAccountName": "Acme Network Services",
        "providerAccountNumber": "123456"
    },
    {
        "providerAccountName": "EQUINIX",
        "providerAccountNumber": "789012"
    }
]

The description of the response payload is as follows:

Field name Type Example Description
providerAccountName string Acme Network Services Z-side provider name.
providerAccountNumber string 123456

Z-side provider account number.

You will need this when looking for Z-side details.

If you get “Insufficient permissions” error, contact your Master Administrator.