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.

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.

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

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.

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

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

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

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

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

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.

GET ConnectionServices​

GET Locations​

GET PatchPanels​

GET PatchPanels {patchPanelId}​

GET Providers​

GET ConnectionServices

GET Locations

GET PatchPanels

GET PatchPanels {patchPanelId}

GET Providers