Zayo API Developer Portal logo

API Developer Portal

Open Search

Maintenance Cases

Monitor upcoming outages with Maintenance Cases API. The Zayo Maintenance Cases API is composed of a series of API calls that are intended to be leveraged sequentially with each request/response cycle providing the required inputs for the next step in the Maintenance Case flow.

Get all maintenance cases

⚠️If no date filters are provided in the payload, results will be filtered server side for the Last 30 Days.

Retrieve all Maintenance Cases based on filter, search, order by, and pagination options. Maintenance Cases include maintenance event information like urgency, level of impact, status, primary date, second primary date, third primary date, time, time zone, reason for maintenance, location, latitude, and longitude.

The recommended flow is to get your Maintenance Case, then use the caseNumber or caseId as a filter option to receive the impacted circuits for that maintenance event.

To get related services impacted by this event data from the Maintenance Case, pass in the caseId or caseNumber value as a filter option in the Maintenance Impacts route.

SecurityBearerToken or OAuthClientCredentials
Request
Request Body schema: application/json

Optional body to apply filters, search values, and pagination as well as order by defined attributes to return a specific list of Maintenance Cases.

object

Object to define filter options.

orderBy
Array of strings unique

Array to specify results ordering.

Items Enum: "caseId" "caseId asc" "caseId desc" "caseNumber" "caseNumber asc" "caseNumber desc" "levelOfImpact" "levelofImpact asc" "levelOfImpact desc" "fromTime" "fromTime asc" "fromTime desc" "location" "location asc" "location desc" "latitude" "latitude asc" "latitude desc" "longitude" "longitude asc" "longitude desc" "primaryDate" "primaryDate asc" "primaryDate desc" "status" "status asc" "status desc" "timeZone" "timeZone asc" "timeZone desc" "toTime" "toTime asc" "toTime desc" "x2ndPrimaryDate" "x2ndPrimaryDate asc" "x2ndPrimaryDate desc" "x3rdPrimaryDate" "x3rdPrimaryDate asc" "x3rdPrimaryDate desc" "urgency" "urgency asc" "urgency desc"
search
string non-empty
object

Object to define pagination for the number of records per page, and how many records to skip. Follows odata pagination standards.

Responses
200

Success

400

Bad Request

post/services/service-management/v1/maintenance-cases
Request samples
application/json
{
  • "filter": {
    • "primaryDate": {
      • "le": "2022-06-29"
      }
    },
  • "orderBy": [
    • "primaryDate desc"
    ],
  • "paging": {
    • "top": 10,
    • "skip": 0
    }
}
Response samples
application/json
{
  • "apiVersion": "v1",
  • "data": {
    • "records": [
      • {
        • "caseId": "5004z00001dIOHFAA4",
        • "caseNumber": "TTN-0005809480",
        • "urgency": "Planned",
        • "levelOfImpact": "Service Affecting",
        • "status": "Closed",
        • "primaryDate": "2022-06-05",
        • "x2dPrimaryDate": null,
        • "x3rdPrimaryDate": null,
        • "fromTime": "06:00",
        • "toTime": "12:00",
        • "timeZone": "GMT",
        • "reasonForMaintenance": "Zayo is performing a mandatory vendor recommended software upgrade",
        • "location": "303 9 Ave Se, Calgary, AB, T2G 0R7",
        • "latitude": 51.044168,
        • "longitude": -114.057667
        },
      • {
        • "caseId": "5004z00001cTR37AAG",
        • "caseNumber": "TTN-0005782528",
        • "urgency": "Planned",
        • "levelOfImpact": "Service Affecting",
        • "status": "Closed",
        • "primaryDate": "2022-05-15",
        • "x2dPrimaryDate": null,
        • "x3rdPrimaryDate": null,
        • "fromTime": "07:00",
        • "toTime": "13:00",
        • "timeZone": "GMT",
        • "reasonForMaintenance": "Zayo is performing a mandatory vendor recommended software upgrade",
        • "location": "175 W Cordova St, Vancouver, BC, V6B 1E1",
        • "latitude": 49.28354,
        • "longitude": -123.10871
        },
      • {
        • "caseId": "5004z00001a47cdAAA",
        • "caseNumber": "TTN-0005504936",
        • "urgency": "Planned",
        • "levelOfImpact": "Service Affecting",
        • "status": "Closed",
        • "primaryDate": "2022-02-06",
        • "x2dPrimaryDate": null,
        • "x3rdPrimaryDate": null,
        • "fromTime": "00:01",
        • "toTime": "05:00",
        • "timeZone": "Eastern",
        • "reasonForMaintenance": "Zayo will be performing Repair on Fibers on Tube 3 must be re-installed/spliced as there are short/kinked to prevent imminent failure.",
        • "location": "45.39801 N , 75.74815 W",
        • "latitude": null,
        • "longitude": null
        }
      ]
    }
}

Get all maintenance impacts

Retrieve all Maintenance Impacts based on filter, search, order by, and pagination options. Maintenance Impacts contain service-based attributes like Service Name, CircuitId, A Location Clli, Z Location Clli, and Legacy Circuit Id.

The recommended flow is to get your Maintenance Case, then use the caseNumber or caseId as a filter option to receive the impacted circuits for that maintenance event.

SecurityBearerToken or OAuthClientCredentials
Request
Request Body schema: application/json

Optional body to apply filters, search values, and pagination as well as order by defined attributes to return a specific list of Maintenance Impacts.

object unique

Object to define filter options.

search
string non-empty
orderBy
Array of strings unique

Array to specify results ordering.

Items Enum: "circuitId" "circuitId asc" "circuitId desc" "expectedImpact" "expectedImpact asc" "expectedImpact desc" "aLocationClli" "aLocationClli asc" "aLocationClli desc" "zLocationClli" "zLocationClli asc" "zLocationClli desc" "legacyCircuitId" "legacyCircuitId asc" "legacyCircuitId desc" "serviceId" "serviceId asc" "serviceId desc" "serviceName" "serviceName asc" "serviceName desc"
object

Object to define pagination for the number of records per page, and how many records to skip. Follows odata pagination standards.

Responses
200

Success

400

Bad Request

post/services/service-management/v1/maintenance-impacts
Request samples
application/json
{
  • "paging": {
    • "top": 10,
    • "skip": 0
    }
}
Response samples
application/json
{
  • "apiVersion": "v1",
  • "data": {
    • "records": [
      • {
        • "caseNumber": "TTN-0005809480",
        • "serviceId": "a0M6000000MnLy8EAF",
        • "serviceName": 345313,
        • "circuitId": "CV2PVC00008",
        • "expectedImpact": "Hard Down",
        • "aLocationClli": "CLGRABCD",
        • "zLocationClli": "TOROONXNSP1",
        • "legacyCircuitId": "07/LOXX/000455/UCN/001"
        }
      ],
    • "metadata": {
      • "top": 5,
      • "skip": 0,
      • "currentPage": 1,
      • "totalPages": 1,
      • "totalRecordCount": 1
      }
    }
}

Get maintenance notifications

Returns all available Maintenance Notifications based on the caseNumber. These notifications are also available via email to enabled users. Reach out to your account rep to get subscribed for Maintenance Notifications emails.

SecurityBearerToken or OAuthClientCredentials
Request
path Parameters
caseNumber
required
string

Case Number returned from the Maintenance Cases or Maintenance Impacts route.

Example: TTN-0003590895
Responses
200

Success

400

Bad Request

get/services/service-management/v1/maintenance-cases/{caseNumber}/notifications
Request samples
curl -i -X GET \
  'https://api.zayo.com/services/service-management/v1/maintenance-cases/{caseNumber}/notifications' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
application/json
{
  • "apiVersion": "v1",
  • "data": [
    • {
      • "name": "MNN-00482176",
      • "notificationType": "Maintenance Completed",
      • "lastModifiedDate": "2019-10-15T08:07:48.000Z",
      • "subject": "COMPLETED MAINTENANCE NOTIFICATION***Z-FAANG US***ZAYO TTN-0003590895 Planned***",
      • "toEmailList": "ipeng@zayo.com; ip-tac@zayo.com; iparch@zayo.com; ethernet.arch@zayo.com; net-eng@zayo.com; telemetry@zayo.com"
      },
    • {
      • "name": "MNN-00482146",
      • "notificationType": "Maintenance Started",
      • "lastModifiedDate": "2019-10-15T07:45:05.000Z",
      • "subject": "START MAINTENANCE NOTIFICATION***Z-FAANG US***ZAYO TTN-0003590895 Planned***",
      • "toEmailList": "ipeng@zayo.com; ip-tac@zayo.com; iparch@zayo.com; ethernet.arch@zayo.com; net-eng@zayo.com; telemetry@zayo.com"
      },
    • {
      • "name": "MNN-00457342",
      • "notificationType": "Scheduled",
      • "lastModifiedDate": "2019-09-26T20:07:24.000Z",
      • "subject": "***Z-FAANG US***ZAYO TTN-0003590895 Planned MAINTENANCE NOTIFICATION***",
      • "toEmailList": "ipeng@zayo.com; ip-tac@zayo.com; iparch@zayo.com; ethernet.arch@zayo.com; net-eng@zayo.com; telemetry@zayo.com"
      }
    ]
}

Get maintenance notification details

Returns maintenance notification details by Maintenance Notification Name. Maintenance Notification details include the email body in HTML.

SecurityBearerToken or OAuthClientCredentials
Request
path Parameters
maintenanceNotificationName
required
string

name attribute returned from the get Maintenance Notifications route.

Example: MNN-00002814
Responses
200

Success

400

Bad Request

get/services/service-management/v1/maintenance-cases/notifications/{maintenanceNotificationName}
Request samples
curl -i -X GET \
  'https://api.zayo.com/services/service-management/v1/maintenance-cases/notifications/{maintenanceNotificationName}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
Response samples
application/json
{
  • "apiVersion": "v1",
  • "data": {
    • "name": "MNN-00482176",
    • "notificationType": "Maintenance Completed",
    • "lastModifiedDate": "2019-10-15T08:07:48.000Z",
    • "subject": "COMPLETED MAINTENANCE NOTIFICATION***Z-FAANG US***ZAYO TTN-0003590895 Planned***",
    • "emailBody": "Dear Zayo Customer,\\r\\n\\r\\n<br><br>Please be advised that the scheduled maintenance window has been completed in its entirety for this event.\\r\\n<br><br><font color=\\\"FF0000\\\">If your services are still being impacted please take a moment to review the service and bounce any interfaces that may have been impacted. In the event that this does not fully restore your service please contact the Zayo NCC at 866-236-2824 or at <u>zayoncc@zayo.com</u>.</font>\\r\\n\\r\\n<br><br><b>Maintenance Ticket #: </b> TTN-0003590895\\r\\n\\r\\n<br><br> <b>Maintenance Window: </b> 00:01 - 05:00 Pacific\\r\\n\\r\\n<br><br><b>1<sup>st</sup> Activity Date: </b> 15-Oct-2019\\n\\r\\n\\r\\n<br><br><b>Location of Maintenance: </b> 2001 6th Ave, Seattle, WA\\r\\n\\r\\n<br><br><b>Reason for Maintenance: </b> Zayo will perform groom for network optimization.\\r\\n\\r\\n<br><br><b>Circuit(s) Affected: </b><br>\\r\\n<table border=3D\\\"1\\\"><tr>\\n<tr>\\n<th>Circuit Id</th>\\n<th>Expected Impact</th>\\n<th>A Location CLLI</th>\\n\\n<th>Z Location CLLI</th>\\n<th>Legacy Circuit Id</th>\\n</tr>\\n<tr>\\n<td>/IPYX/106744/ /ZYO /</td>\\n<td>Hard Down - Duration of maintenance window</td>\\n<td>STTLWACC000</td>\\n<td>STTLWAWB012</td>\\n<td></td>\\n</tr>\\n</table>\\n\\r\\n\\r\\n<br><br>If you have any questions or need any additional information related to this maintenance event, please contact the MR group at mr@zayo.com or call 866-236-2824.\\r\\n\\r\\n<br><br>Regards,<br><p><b>\\r\\n<font color=\\\"808080\\\" size=\\\"3\\\" face=\\\"Times New Roman\\\">Zay</font><font color=\\\"FF9900\\\" size=\\\"3\\\" face=\\\"Times New Roman\\\">o </font>\\r\\n<font color=\\\"808080\\\" size=\\\"3\\\" face=\\\"Times New Roman\\\">Global Change Management Team/<i>Équipe de Gestion du Changement Global Zay</font><font color=\\\"FF9900\\\" size=\\\"3\\\" face=\\\"Times New Roman\\\">o</font></i><br>\\r\\n<font color=\\\"808080\\\" size=\\\"3\\\" face=\\\"Times New Roman\\\">Zay</font><font color=\\\"FF9900\\\" size=\\\"3\\\" face=\\\"Times New Roman\\\"><b>o </b></font>\\r\\n<font color=\\\"808080\\\" size=\\\"3\\\" face=\\\"Times New Roman\\\">Group/<i>Le Groupe Zay</font><font color=\\\"FF9900\\\" size=\\\"3\\\" face=\\\"Times New Roman\\\">o</font></i></b>\\r\\n<font size=\\\"2\\\" face=\\\"Times New Roman\\\">\\r\\n<br>Toll free/<i>N° sans frais</i>: <a href=\\\"tel:1-866-236-2824\\\">1.866.236.2824 </a>\\r\\n<br>United Kingdom Toll Free/<i>N° sans frais Royaume-Uni</i>: <a href=\\\"tel:0800-169-1646\\\">0800.169.1646</a>\\r\\n<br>Email/<i>Courriel</i>: <a href=\\\"mailto:mr@zayo.com\\\">mr@zayo.com</a>\\r\\n<br>Website/<i>Site Web</i>: <a href=\\\"https://www.zayo.com\\\">https://www.zayo.com</a>\\r\\n\\r\\n<p class=MsoNormal style='margin-bottom:0cm;margin-bottom:.0001pt;line-height:\\r\\nnormal'><a href=\\\"http://www.zayo.com/company/about-zayo/\\\" target=\\\"_blank\\\"><b><span\\r\\nlang=EN-US style='font-family:\\\"Helvetica\\\",sans-serif;color:#ED7D31;background:\\r\\nwhite;mso-ansi-language:EN-US'>About Zayo</span></b></a><span lang=EN-US\\r\\nstyle='font-family:\\\"Helvetica\\\",sans-serif;color:#ED7D31;background:white;\\r\\nmso-ansi-language:EN-US'>&nbsp;|&nbsp;</span><a\\r\\nhref=\\\"http://www.zayo.com/solutions/global-network/\\\" target=\\\"_blank\\\"><b><span\\r\\nlang=EN-US style='font-family:\\\"Helvetica\\\",sans-serif;color:#ED7D31;background:\\r\\nwhite;mso-ansi-language:EN-US'>Network</span></b></a><strong><span lang=EN-US\\r\\nstyle='font-family:\\\"Helvetica\\\",sans-serif;color:#ED7D31;background:white;\\r\\nmso-ansi-language:EN-US'>&nbsp;</span></strong><span lang=EN-US\\r\\nstyle='font-family:\\\"Helvetica\\\",sans-serif;color:#ED7D31;background:white;\\r\\nmso-ansi-language:EN-US'>|&nbsp;</span><a\\r\\nhref=\\\"https://tranzact.zayo.com/#!/escalation-lists\\\" target=\\\"_blank\\\"><b><span\\r\\nlang=EN-US style='font-family:\\\"Helvetica\\\",sans-serif;color:#ED7D31;background:\\r\\nwhite;mso-ansi-language:EN-US'>Escalation List</span></b></a><b><span\\r\\nlang=EN-US style='font-family:\\\"Helvetica\\\",sans-serif;color:#ED7D31;background:\\r\\nwhite;mso-ansi-language:EN-US'>&nbsp;</span></b><span lang=EN-US\\r\\nstyle='font-family:\\\"Helvetica\\\",sans-serif;color:#ED7D31;background:white;\\r\\nmso-ansi-language:EN-US'>|&nbsp;</span><a\\r\\nhref=\\\"https://www.linkedin.com/company/530962/\\\" target=\\\"_blank\\\"><b><span\\r\\nlang=EN-US style='font-family:\\\"Helvetica\\\",sans-serif;color:#ED7D31;background:\\r\\nwhite;mso-ansi-language:EN-US'>LinkedIn</span></b></a><b><span lang=EN-US\\r\\nstyle='font-family:\\\"Helvetica\\\",sans-serif;color:#ED7D31;background:white;\\r\\nmso-ansi-language:EN-US'>&nbsp;</span></b><span lang=EN-US style='font-family:\\r\\n\\\"Helvetica\\\",sans-serif;color:#ED7D31;background:white;mso-ansi-language:EN-US'>|&nbsp;</span><a\\r\\nhref=\\\"https://twitter.com/zayogroup\\\" target=\\\"_blank\\\"><b><span lang=EN-US\\r\\nstyle='font-family:\\\"Helvetica\\\",sans-serif;color:#ED7D31;background:white;\\r\\nmso-ansi-language:EN-US'>Twitter</span></b></a><b><span lang=EN-US\\r\\nstyle='font-family:\\\"Helvetica\\\",sans-serif;color:#ED7D31;background:white;\\r\\nmso-ansi-language:EN-US'>&nbsp;</span></b><span lang=EN-US style='font-family:\\r\\n\\\"Helvetica\\\",sans-serif;color:#ED7D31;background:white;mso-ansi-language:EN-US'>|&nbsp;<a\\r\\nhref=\\\"https://tranzact.zayo.com/#!/login\\\" target=\\\"_blank\\\"><b><span\\r\\nstyle='color:#ED7D31'>Tranzact</span></b><span style='color:#ED7D31'>&nbsp;</span></a><o:p></o:p></span></p>\\r\\n\\r\\n\\r\\n<br><br><font color=\\\"008080\\\" size=\\\"1.5\\\" face=\\\"Times New Roman\\\">\\r\\nSTRICTLY PERSONAL AND CONFIDENTIAL. This email may contain confidential and proprietary material for the sole use of the intended recipient. Any review or distribution by others is strictly prohibited. If you are not the intended recipient please contact the sender and delete all copies.\\r\\n</font>\\r\\n</p>",
    • "toEmailList": "ipeng@zayo.com; ip-tac@zayo.com; iparch@zayo.com; ethernet.arch@zayo.com; net-eng@zayo.com; telemetry@zayo.com"
    }
}

Generate auth token

Generating the auth token only needs to be done once, since this auth token will be good for receiving all push notifications associated with your current API token. However, this endpoint may be called as many times as necessary to reset the auth token for additional security. The active auth token is always the most recently generated auth token.

Workflow to set up push notifications services:

  1. Generate auth token | Generate the auth token to be used in the HTTP header to authenticate invocations to your callback endpoint.

  2. Implement a callback URL endpoint on your infrastructure. The callback URL endpoint must meet the following requirements:

    ● Implemented on HTTPS

    ● Accessible from any IP address

    ● Requires an Authorization header with the auth token generated in Step 1

    ● Rejects (via HTTP 401) a request that does not have an Authorization header or has the wrong Authorization header

    ● Accepts a HTTP POST request with a JSON body

  3. Register callback URL | Register your endpoint to recieve Maintenance Notifications.

  4. Send test notification | Test out your endpoint.

SecurityBearerToken or OAuthClientCredentials
Request
Request Body schema: application/x-www-form-urlencode

Required request body containing your grant type, client id and client secret. If you do not have API credentials, please reach out to zayoapi@zayo.com to obtain these.

grant_type
required
string

This value will always be client_credentials

client_id
required
string
client_secret
required
string
scope
string
Responses
200

Success

400

Bad Request

post/services/notifications/v1/generate-auth-token
Request samples
curl -i -X POST \
  https://api.zayo.com/services/notifications/v1/generate-auth-token \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/x-www-form-urlencode' \
  -d '[object Object]'
Response samples
application/json
{
  • "apiVersion": "string",
  • "data": {
    • "authToken": "007431a5-f913-4a19-8dd6-9350bb7229f6"
    }
}

Register callback URL

Once you've implemented a callback URL endpoint in your infrastructure register it with Zayo.

SecurityBearerToken or OAuthClientCredentials
Request
Request Body schema: application/json

Required request body to register your endpoint and subscribe to Maintenance Notifications.

notificationType
required
string
callbackUrl
required
string <url>
accounts
Array of strings
Responses
200

Success

400

Bad Request

post/services/notifications/v1/register-callback-url
Request samples
application/json
{}
Response samples
application/json
{
  • "apiVersion": "v1",
  • "data": {
    • "id": "58bfe26e-38a7-4c67-868a-65f536c3ae51",
    • "target": "https://4381968a-143c-4195-87db-986c11fb54ce.mock.pstmn.io/sampleCallback",
    • "notification_type": "Maintenance Notifications",
    • "account_id": "0016000000unFcJAAU",
    • "target_account_ids": [
      • "0016000000umyBWAAY, 0010z00001XVx7hAAD, 0010z00001XVxgNAAT, 0010z00001XWdh2AAD, 0014z00001b1FMPAA2, 0014z00001d89HqAAI"
      ],
    • "conditions": null,
    • "enabled": true,
    • "created_at": "2022-06-28T03:44:45.394Z",
    • "updated_at": "2022-06-28T03:44:45.394Z",
    • "created_by_username": "tranzactquote.api@zayo.com",
    • "created_by_user_id": "44a5d370-18a9-11eb-883f-e1dcd53ef907",
    • "target_type": "CALLBACK_URL",
    • "target_header": null,
    • "oauth_access_token_header": null
    }
}

Send test notification

Once the callback URL is registered, you can send test notifications to your registered callback URLs for a particular notification type.

SecurityBearerToken or OAuthClientCredentials
Request
Request Body schema: application/json

Requireed request body to register your endpoint and subscribe to Maintenance Notifications.

notificationType
string
Responses
200

Success

400

Bad Request

post/services/notifications/v1/send-test-notification
Request samples
application/json
{
  • "notificationType": "Maintenance Notifications"
}
Response samples
application/json
{
  • "apiVersion": "v1",
  • "data": {
    • "name": "MNN-12345678",
    • "type": "Calendar",
    • "case": "TTN-0123456789",
    • "timestamp": "2021-01-01T12:00:00",
    • "urgency": "Planned",
    • "levelOfImpact": "Potential Service Affecting",
    • "circuitId": "/xxx/xxxxxx/ /xxx /",
    • "primaryDate": "2021-01-03",
    • "x2ndPrimaryDate": null,
    • "x3rdPrimaryDate": null,
    • "fromTime": "00:01",
    • "toTime": "05:00",
    • "timeZone": "Mountain",
    • "reasonForMaintenance": "reason for maintenance",
    • "location": "Boulder, CO",
    • "accountIds": [
      • "0016000000unFcJAAU"
      ]
    }
}