Skip to main content
Index

Lookup (V2 Beta)

Lookup (V2 Beta) 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 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 Started section.

 

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

 

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,

WORK_VISIT

Filters user's locations according to the user's permissions. Only one permission code can be passed at a time.

ibxs No string    

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.

 

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 the cross connect permission code, and should not be used to search for A-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 not be used to search for A-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.

 

{
  "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. 

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 Started 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

 

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

 

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 in searches for both A-side and Z-side when the A-side account is in a shared cabinet.

 

[
  {
    "patchPanelId": "CP:0112:13468516",
    "availablePortCount": 2,
    "patchPanelReferenceId": "AB:C46 (Equinix provided)",
    "preWired": true,
    "ifcEnabled": true
  },
  {
    "patchPanelId": "PP:0112:1142910",
    "availablePortCount": 16,
    "patchPanelReferenceId": "",
    "preWired": false,
    "ifcEnabled": false
  }
]

 

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. 

preWired

boolean

true

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

 

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 Started 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
 

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

 

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 mandatory when the search is for Z-side.

 

{
  "patchPanelId": "CP:0112:13468516",
  "ibx": "AM1",
  "cageId": "AM1:0G:00EQ11",
  "cabinetId": "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
  ],
  "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"
    },
    {
      "portNumber": "3",
      "serialNumber": "20619401",
      "connectionServicesName": "MULTI_MODE_FIBER",
      "zSideProviderName": "Acme Network Services"
    },
    {
      "portNumber": "1",
      "serialNumber": "20619399",
      "connectionServicesName": "MULTI_MODE_FIBER",
      "zSideProviderName": "Acme Network Services"
    }
  ]
}

 

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 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.
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
[numbers]
  Available circuit count for the IFC enabled patch panel.

usedPortsDetails

array

[objects]

 

List of used ports on this patch panel.

Each used port object comprises the following parameters: portNumber, serialNumber, connectionServicesName, zSideProviderName.

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.

 

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 Started section.

 

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

 

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. 

 

[
  {
    "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.