Notification Management
Manage your organizations' portal notifications with the following use cases.
Retrieve IBX Notifications
Equinix Customer Portal users may be able to search for IBX notifications based on their Notification permissions.
Step 1: Authenticate
Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication.
Refer to Generating Client ID and Client Secret under Getting Access Token section for instructions on how to create client ID and client secret and refer to Requesting Access and Refresh tokens for instructions on how to call Oauth API to validate and authenticate your credentials.
If you are unaware of your user credentials for Equinix Customer Portal, contact your local Equinix Service Desk.
Step 2: Search for IBX Notifications
| POST /notifications/ibx/search | |
|---|---|
| Method | POST |
| URL or End Point | /v1/notifications/ibx/search |
| Headers | Authorization, Content-Type |
| Query Parameters | offset, limit, sorts |
| Body | {filter {ibxs [...], types [...], statuses [...], dateRange {fromDate, toDate}}} |
This method returns a filtered list of IBX notifications received by a user. The user receives these notifications based on their permissions and permissions-related order notification preferences. 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 API. The request indicates that the response should return all types of IBX notifications of completed status within the dates 2020/01/28 to 2021/03/28 for IBXs with locations codes SV1 and SV5. The results should be sorted by notification number (starting from the smallest number), and only 1 result should be displayed per page starting from offset '0'. The response returned a total of 18 notifications, with 1 displayed in the response.
curl -X
POST "https://api.equinix.com/v1/notifications/ibx/search?offset=0&limit=1&sorts=notificationNumber"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
"filter": {
"ibxs": [
"SV1",
"SV5"
],
"types": [
"IBX_MAINTENANCE"
"IBX_INCIDENT",
"IBX_SECURITY_INCIDENT",
"IBX_ADVISORY"
],
"statuses": [
"COMPLETED"
],
"dateRange": {
"fromDate": "2020-01-28T03:46:36.720Z",
"toDate": "2021-03-28T03:46:36.720Z"
}
}
}'
The description of the query parameters is as follows:
| Query Parameter Name | Mandatory | Type | Example | Applicable Values | Description |
|---|---|---|---|---|---|
| offset | No | integer | 0 | Any integer value within the total number of results. | The index of the first item you want results for. If a start value is not provided, the default value is 0. |
| limit | No | integer | 1 | Any integer value from 1 to 100. | The maximum number of search results to be shown per page. If a limit is not provided, the default value is 10. |
| sorts | No | array[string] | notificationNumber | notificationNumber, status, startDate, endDate, type, priority -notificationNumber, -status, -startDate, -endDate, -type -priority | Notifications searched can be sorted by id, status, startDate, endDate, or type, in ascending or descending order. To sort by descending order, the applicable value must start with a '-'. Default value: -startDate. |
The description of the body parameters is as follows:
| Body Parameter Name | Mandatory | Type | Example | Applicable Values | Description |
|---|---|---|---|---|---|
| filter | No | object | Filter of notifications by IBX location code(s), notification type(s), notification status(es), and date range of notification for a scheduled activity. | ||
| ibxs | No | array[strings] | SV1, SV5 | The IBX location code(s). By specifying single or multiple sources (ex: SV5 or SV1, SV5), the constraint is placed on specific IBXs. By default, search will be performed in all IBXs. | |
| types | No | array[strings] | IBX_MAINTENANCE | IBX_ADVISORY, IBX_INCIDENT, IBX_MAINTENANCE, IBX_SECURITY_INCIDENT | The notification types that are sent by Equinix. |
| statuses | No | array[strings] | COMPLETED | NEW, IN_PROGRESS, UPDATED, RESCHEDULED, EXTENDED, RESOLVED, COMPLETED, CANCELLED | The statuses of the notifications. |
| dateRange | No | object[strings] | Date range that defines the time period to search for notifications. | ||
| fromDate | No | string | 2020-01-28T03:46:36.720Z | The date and time from which to start the search or notifications. Provide a date and time (UTC timezone) in one of the following ISO 8601 formats: yyyy-MM-dd'T'HH:mm:ssZ, Default value: The date 1 year prior to the date this request is made. If there is no value for 'fromDate', instead of leaving the value empty, do not include the entire dateRange body parameter. | |
| toDate | No | string | 2021-03-28T03:46:36.720Z | The date and time at which to end the search for notifications. Provide a date and time (UTC timezone) in one of the following ISO 8601 formats: yyyy-MM-dd'T'HH:mm:ssZ, Default value: The date this request is made. If there is no value for 'toDate', instead of leaving the value empty, do not include the entire dateRange body parameter. |
{
"data": [
{
"notificationNumber": "5-195822495668",
"id": "GBL000006121231",
"type": "IBX_MAINTENANCE",
"startTimestamp": "2020-03-19T06:00:00Z",
"endTimestamp": "2020-03-20T18:00:00Z",
"ibxs": [
"SV5"
],
"globalNotification": false,
"status": "COMPLETED",
"priority": "LOW",
"summary": "Equinix and service vendor will be performing annual preventive maintenance on UPS / ASTS system B-2. Loads from the B-2 system will be transferred to the “Reserve” UPS system during this maintenance. Redundancy will be reduced."
}
],
"page": {
"limit": 1,
"offset": 0,
"total": 18,
"sorts": [
"notificationNumber"
]
},
"_links": {
"next": {
"href": "/notifications/ibx/search?limit=1&offset=1&sorts=notificationNumber"
},
"previous": {
"href": "/notifications/ibx/search?limit=1&offset=0&sorts=notificationNumber"
},
"self": {
"href": "/notifications/ibx/search?limit=1&offset=0&sorts=notificationNumber"
}
}
}
The description of the response payload is as follows:
| Field name | Type | Example | Description |
| data | array[objects] | Returned search results based on query parameters. | |
| notificationNumber | string | 5-195822495668 | The unique number of the notification. One 'notificationNumber' can have various types of statuses. |
| id | string | GBL000006121231 | An unique ID number of the IBX that relates to the specific notificationNumber. This is mandatory to include when retrieving a specific notification. |
| type | string | IBX_MAINTENANCE | The notification type. Refer to the body parameter description of 'types' for a full set of IBX notification types. |
| startTimestamp | string | 2020-03-19T06:00:00Z | The starting date and time of the notification. |
| endTimestamp | string | 2020-03-20T18:00:00Z | The ending date and time of the notification. If no 'endTimestamp' is specified, the value 'null' is returned. |
| ibxs | array[string] | SV5 | The IBX location code(s) associated with this notification. |
| globalNotification | boolean | false | Indicates if the IBX notification is global. Default value: false |
| status | string | COMPLETED | The status of the notification. Refer to the body parameter description of 'statuses' for a full set of IBX notification statuses. |
| priority | string | LOW | The priority level of the notification. All notification types are handled based on priority. Priority refers to events and incidents and specifies the order in which incidents should be addressed. |
| summary | string | Equinix and service vendor will be performing annual preventive maintenance on UPS / ASTS system B-2. Loads from the B2 system will be transferred to the “Reserve” UPS system during this maintenance. Redundancy will be reduced. | A summary description of the notification at the time it was first created. The summary description of these notifications remains unchanged througout the various changes of notification status. |
| page | object | The page information of the returned results. | |
| limit | integer | 1 | The maximum number of results shown per page. |
| offset | integer | 0 | The start index from which the search results list is created. |
| total | integer | 18 | Total total number of results that match the search criteria. |
| sorts | array[string] | notificationNumber | Selected sorting order. If the value begins with a '-', it is in descending order. This value should match the sorts field in the query parameter. |
| _links | object | Links that show the previous page, current page, and next page of search results. | |
| next | object | Next search results page. | |
| href | string | /notifications/ibx/search?limit=1&offset=1& sorts=notificationNumber | Link to the next page of search results. |
| previous | object | Previous search results page. | |
| href | string | /notifications/ibx/search?limit=1&offset=0& sorts=notificationNumber | Link to the previous page of search results. |
| self | object | Current search results page. This is a self-reference. | |
| href | string | /notifications/ibx/search?limit=1&offset=0& sorts=notificationNumber | Link to the current page of search results. |
If you would like to know more detailed information about the specific IBX notification, refer to GET Notifications IBX {id} under the API Reference section.
If you get “Insufficient permissions” error, contact your Master Administrator.
Retrieve Network Notifications
Equinix Customer Portal users may be able to search for network notifications based on their Notification permissions.
Step 1: Authenticate
Submit your user credentials, Client ID, and Client Secret for OAuth2 authentication.
Refer to Generating Client ID and Client Secret under Getting Access Token section for instructions on how to create client ID and client secret and refer to Requesting Access and Refresh tokens for instructions on how to call Oauth API to validate and authenticate your credentials.
If you are unaware of your user credentials for Equinix Customer Portal, contact your local Equinix Service Desk.
Step 2: Search for Network Notifications
| POST /notifications/network/search | |
|---|---|
| Method | POST |
| URL or End Point | /v1/notifications/network/search |
| Headers | Authorization, Content-Type |
| Query Parameters | offset, limit, sorts |
| Body | {filter {ibxs [...], types [...], productTypes [...], statuses [...], dateRange {fromDate, toDate}}} |
This method returns a filtered list of network notifications received by a user. The user receives these notifications based on their permissions and permissions-related order notification preferences. 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 API. The request indicates that the response should return all network maintenance notifications pertaining to metro connects with status 'Completed' from 2020/01/28 to 2021/03/28 , for IBXs with locations codes, SV1 and SV5. The response should be sorted by chronological order (starting from the latest date), and only 1 result should be displayed per page starting from offset '0'. The response returned a total of 6 notifications, with 1 displayed in the response.
curl -X
POST "https://api.equinix.com/v1/notifications/network/search?offset=0&limit=1&sorts=-startDate"
-H "content-type: application/json"
-H "authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
"filter": {
"ibxs": [
"SV1",
"SV5"
],
"types": [
"NETWORK_MAINTENANCE"
],
"productTypes": [
"METRO_CONNECT"
],
"statuses": [
"COMPLETED"
],
"dateRange": {
"fromDate": "2020-01-28T03:46:36.720Z",
"toDate": "2021-03-28T03:46:36.720Z"
}
}
}'
The description of the query parameters is as follows:
| Query Parameter Name | Mandatory | Type | Example | Applicable Values | Description |
|---|---|---|---|---|---|
| offset | No | integer | 0 | Any integer value within the total number of results. | The index of the first item you want results for. If a start value is not provided, the default value is 0. |
| limit | No | integer | 1 | Any integer value from 1 to 100. | The maximum number of search results to be shown per page. If a limit is not provided, the default value is 10. |
| sorts | No | array[string] | -startDate | notificationNumber, status, startDate, endDate, type, priority -notificationNumber, -status, -startDate, -endDate, -type -priority | Notifications searched can be sorted by notificationNumber, status, startDate, endDate, type, or priority in ascending or descending order. To sort by descending order, the applicable value must start with a '-'. Default value: -startDate. |
The description of the body parameters is as follows:
| Body Parameter Name | Mandatory | Type | Example | Applicable Values | Description |
|---|---|---|---|---|---|
| filter | No | object | Filter of notifications by IBX location code(s), notification type(s), notification status(es), and date range of notification for scheduled activity. | ||
| ibxs | No | array[strings] | SV1, SV5 | The IBX location code(s) that represent the IBX(s) that the notifications relate to. By specifying single or multiple sources (For example, SV5 or SV1, SV5), the constraint is placed on specific IBXs. By default, search will be performed in all IBXs. | |
| types | No | array[strings] | NETWORK_MAINTENANCE | NETWORK_INCIDENT, NETWORK_MAINTENANCE | The notification types that are sent by Equinix. |
| productTypes | No | array[strings] | METRO_CONNECT | MANAGEMENT_ACCESS, INTERNET_EXCHANGE, EQUINIX_CONNECT, MOBILITY_EXCHANGE, VOIP, BI_VLAN, METRO_CONNECT, VMMR_SDH, INTER_METRO_CONNECT, ETHERNET_EXCHANGE, CLOUD_EXCHANGE_FABRIC, BI_CLOUD, EXPEDITE, CLOUD_IX, CROSS_CONNECT, NETWORK_TIMING | The product types that the notifications relate to. |
| statuses | No | array[strings] | COMPLETED | NEW, IN_PROGRESS, UPDATED, RESCHEDULED, EXTENDED, RESOLVED, COMPLETED, CANCELLED | The statuses of the notifications. |
| dateRange | No | object[strings] | Date range that defines the time period to search for notifications. | ||
| fromDate | No | string | 2020-01-28T03:46:36.720Z | The date and time from which to start the search or notifications. Provide a date and time (UTC timezone) in one of the following ISO 8601 formats: yyyy-MM-dd'T'HH:mm:ssZ, Default value: The date 1 year prior to the date this request is made. If there is no value for 'fromDate', instead of leaving the value empty, do not include the entire dateRange body parameter. | |
| toDate | No | string | 2021-03-28T03:46:36.720Z | The date and time at which to end the search for notifications. Provide a date and time (UTC timezone) in one of the following ISO 8601 formats: yyyy-MM-dd'T'HH:mm:ssZ, Default value: The date this request is made. If there is no value for 'toDate', instead of leaving the value empty, do not include the entire dateRange body parameter. |
{
"data": [
{
"notificationNumber": "EQ-GL-20200904-00144",
"id": "GBL000007463303",
"type": "NETWORK_MAINTENANCE",
"startTimestamp": "2020-09-14T00:01:00Z",
"endTimestamp": "2020-09-14T05:00:00Z",
"ibxs": [
"SV1"
],
"status": "COMPLETED",
"priority": "HIGH",
"productTypes": [
"METRO_CONNECT"
],
"summary": "Equinix dark fiber provider will be performing hot cut to roll off leased fibers onto their owned fibers.\n\nCustomers may experience a brief disruption of services during the maintenance window when the line side fiber switches to the protect path."
}
],
"page": {
"limit": 1,
"offset": 0,
"total": 6,
"sorts": [
"-startDate"
]
},
"_links": {
"next": {
"href": "/notifications/network/search?limit=1&offset=1&sorts=-startDate"
},
"previous": {
"href": "/notifications/network/search?limit=1&offset=0&sorts=-startDate"
},
"self": {
"href": "/notifications/network/search?limit=1&offset=0&sorts=-startDate"
}
}
}
The description of the response payload is as follows:
| Field name | Type | Example | Description |
| data | array[objects] | Returned search results based on query parameters. | |
| notificationNumber | string | 5-195822495668 | The unique number of the notification. One 'notificationNumber' can have various types of statuses. |
| id | string | GBL000006121231 | An unique ID number of the Network that relates to the specific notificationNumber. This is mandatory to include when retrieving a specific notification. |
| type | string | NETWORK_MAINTENANCE | The notification type. Refer to the body parameter description of 'types' for a full set of network notification types. |
| startTimestamp | string | 2020-09-14T00:01:00Z | The starting date and time of the notification. |
| endTimestamp | string | 2020-09-14T05:00:00Z | The ending date and time of the notification. If no 'endTimestamp' is specified, the value 'null' is returned. |
ibxs | array[string] | SV1 | The IBX location code(s) associated with this notification. |
| status | string | COMPLETED | The status of the notification. Refer to the body parameter description of 'statuses' for a full set of network notification statuses. |
| priority | string | LOW | The priority level of the notification. All notification types are handled based on priority. Priority refers to events and incidents and specifies the order in which incidents should be addressed. |
| productType | array[strings] | METRO_CONNECT | The product type(s) associated with the notification. If no match found was found, UNKNOWN will be sent. Refer to the body parameter description of 'productTypes' for the full set of product types. |
| summary | string | Equinix dark fiber provider will be performing hot cut to roll off leased fibers onto their owned fibers.\n\nCustomers may experience a brief disruption of services during the maintenance window when the line side fiber switches to the protect path. | A summary description of the notification at the time it was first created. The summary description of these notifications remains unchanged througout the various changes of notification status. |
| page | object | The page information of the returned results. | |
| limit | integer | 1 | The maximum number of results shown per page. |
| offset | integer | 0 | The start index from which the search results list is created. |
| total | integer | 18 | Total total number of results that match the search criteria. |
| sorts | array[string] | notificationNumber | Selected sorting order. If the value begins with a '-', it is in descending order. This value should match the sorts field in the query parameter. |
| _links | object | Links that show the previous page, current page, and next page of search results. | |
| next | object | Next search results page. | |
| href | string | /notifications/network/search?limit=1& offset=1&sorts=-startDate | Link to the next page of search results. |
| previous | object | Previous search results page. | |
| href | string | /notifications/network/search?limit=1& offset=0&sorts=-startDate | Link to the previous page of search results. |
| self | object | Current search results page. This is a self-reference. | |
| href | string | /notifications/network/search?limit=1& offset=0&sorts=-startDate | Link to the current page of search results. |
If you would like to know more detailed information about the specific network notification, refer to GET Notifications Network {id} under the API Reference section.
If you get “Insufficient permissions” error, contact your Master Administrator.