Create Digital LOA

Digital Letter of Authorization (LOA) enables convenient ordering of services that require third-party authorization. It minimizes the engagement from both A-side and Z-side when processing orders for interconnection services such as Cross Connect.

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 createclient ID and client secret and refer to Requesting Access and Refresh tokens for instructions on how to call Oauth API to validate and authenticate yourcredentials.

If you are unaware of your user credentials for Equinix Customer Portal, contact your local Equinix Service Desk.


Step 2: Get Possible A-side Partners (optional)

Use the Get Possible Connections API request to retrieve the list of A-side partners that are present in a specified IBX data center.

GET /diloa/v1/organizations
Method GET
Endpoint /diloa/v1/organizations
Headers Authorization
Path Parameters Not applicable
Query Parameters location.ibx, product.type
Body Parameters Not applicable

Sample curl request

Copy 
curl -X
GET "https://api.equinix.com/diloa/v1/organizations?ibx=AM3"
-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"

Query parameters

Parameter
Description
location.ibx string
REQUIRED		 IBX data center identifier.
Example: AT1
product.type array[string]
OPTIONAL		 A-side IBX data center identifier.
Applicable values: CROSS_CONNECT

Sample response

Copy 
[
    {
        "orgIds": [
            "81918"
        ],
        "name": "3W INFRA B.V."
    },
    {
        "orgIds": [
            "9769",
            "10947",
            "11070",
            "69273",
            "78488"
        ],
        "name": "A1 Telekom Austria Group"
    },
    {
        "orgIds": [
            "24254"
        ],
        "name": "A2B Internet - Fast and Reliable Connectivity"
    }
]

Step 3: Create Digital LOA

Use the Create Digital LOA Document API request to create a Digital LOA document.

POST /diloa/v1/digitalLoas
Method POST
Endpoint /diloa/v1/digitalLoas
Headers Authorization, Content-Type
Path Parameters Not applicable
Query Parameters Not applicable
Body Parameters type, crossConnect, serviceTypeName, mediaTypeName, aSide, connectorTypeName, circuitId, patchPanel, number, portA, PortB, zSide, requestor, provider, contacts, registeredUser, firstName, lastName, timezone, availability, details, note, value, notes, expiryDateTime

If the A-side customer you want to issue this Digital LOA document to was listed in the response in Step 5, set the requestor.type parameter to CUSTOMER_ORGANIZATION. In the requestor.ids parameter, specify customer organizations entitled to use this Digital LOA document. If the A-side customer wasn't available in the response, set the requestor.type parameter to NEW_RELATIONSHIP.


Sample curl request - an existing A-side customer relationship

Copy 
curl -X
POST "https://api.equinix.com/diloa/v1/digitalLoas"
-H "content-type: application/json"
-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
    "products": [
        {
            "type": "CROSS_CONNECT",
            "crossConnect": {
                "connectionService": "UTP",
                "mediaType": "CAT6",
                "protocolType": "ETHERNET",
                "zSide": {
                    "connectorType": "RJ45",
                    "patchPanelId": "PP:0000:6256843",
                    "circuitId": "34234535",
                    "portA": 4
                }
            }
        }
    ],
    "requestor": {
        "type": "CUSTOMER_ORGANIZATION",
        "contacts": [
            {
                "type": "NOTIFICATION",
                "details": [
                    {
                        "value": "jane@xyz.com",
                        "type": "EMAIL"
                    }
                ]
            }
        ],
        "orgIds": [
            "123412",
            "223124"
        ],
        "name": "XYZ Company"
    },
    "provider": {
        "contacts": [
            {
                "type": "NOTIFICATION",
                "firstName": "John",
                "lastName": "Smith",
                "timezone": "America/Los_Angeles",
                "details": [
                    {
                        "value": "john@smith.com",
                        "type": "EMAIL"
                    }
                ]
            }
        ]
    },
    "notes": "",
    "expiryDateTime": "2022-07-31T21:59:59.999Z"
}'

Sample curl request - a new A-side customer relationship

Copy 
curl -X
POST "https://api.equinix.com/diloa/v1/digitalLoas"
-H "content-type: application/json"
-H "Authorization: Bearer {Access Token}"
-d '{
    "products": [
        {
            "type": "CROSS_CONNECT",
            "crossConnect": {
                "connectionService": "UTP",
                "mediaType": "CAT6",
                "protocolType": "ETHERNET",
                "zSide": {
                    "connectorType": "RJ45",
                    "patchPanelId": "PP:0000:6256843",
                    "circuitId": "34234535",
                    "portA": 4
                }
            }
        }
    ],
    "requestor": {
        "type": "NEW_RELATIONSHIP",
        "email": "jane@xyz.com",
        "name": "XYZ Company"
    },
    "provider": {
        "contacts": [
            {
                "type": "NOTIFICATION",
                "firstName": "John",
                "lastName": "Smith",
                "timezone": "America/Los_Angeles",
                "details": [
                    {
                        "value": "john@smith.com",
                        "type": "EMAIL"
                    }
                ]
            }
        ]
    },
    "notes": "",
    "expiryDateTime": "2022-07-31T21:59:59.999Z"
}'

Body parameters

Parameter
Description
products array[object]
REQUIRED		 Specification of services that the given LOA document is valid for.
type string
REQUIRED
 Service instance type.
Applicable values: CROSS_CONNECT
crossConnect object
REQUIRED
 Cross Connect connection specification.
connectionService string
REQUIRED
 Connection service type.
Example: Single-Mode Fiber
mediaType string
REQUIRED
 Media type.
Example: Single-Mode Fiber
protocolType string
REQUIRED
 Protocol type.
Example: 100 GIG ETHERNET
zSide object
REQUIRED
 Z-side connection details.
circuitId string
OPTIONAL
 User-defined Cross Connect circuit identifier.
Example: 34234535
connectorType string
REQUIRED
 Patch panel connector type.
Example: ST
patchPanelId string
REQUIRED
 Patch panel identifier.
Example: CP:0218:0102:13008148
portA integer
REQUIRED
 Port A number.
Example: 12
portB integer
OPTIONAL
 Port B number.

Example: 13
requestor object
REQUIRED		 LOA document requestor information.
type string
REQUIRED
 Party type that specifies if the requestor is a known organization or a new one without previous engagements.
Applicable values:
  • CUSTOMER_ORGANIZATION - A customer organization with known organization identifiers.
  • NEW_RELATIONSHIP - A new customer relationship, where the organization identifier is unknown.
email string
CONDITIONAL
 Customer organization representative's email address. Required if the requestor.type parameter is set to NEW_RELATIONSHIP.
Example: mike@mspc.us
orgIds array[string]
CONDITIONAL
 Customer organization identifiers. Required if the requestor.type parameter is set to CUSTOMER_ORGANIZATION.
Example: 123345
name string
REQUIRED
 Customer organization name.
Example: Solid Snake Inc.
contacts array[object]
REQUIRED
 Service provider contact information.
type string
 Notification messages category relevant to a given contact person.
Possible values:
  • NOTIFICATION - Notifications related to Digital LOA document's lifecycle.
  • TECHNICAL - Contact information for technical inquiries.
registeredUser string
OPTIONAL
 contactId, userId or userKey of a registered user.
firstName string
CONDITIONAL
 Contact person's first name. Required if registeredUser hasn't been provided.
Example: Jane
lastName string
CONDITIONAL
 Contact person's last name. Required if registeredUser hasn't been provided.
Example: Smith
timezone string
OPTIONAL
 Contact person's timezone.
Example: Australia/Perth
availability string
OPTIONAL
 Contact person's availability.
Applicable values:
  • WORK_HOURS - Contact person be reached during working hours.
  • ANYTIME - Contact person can be reached anytime throughout the day.
details array[object]
REQUIRED
 Means of contact.
note string
OPTIONAL
 Additional note applicable to the given contact option.
Example: Not suitable for emergencies.
value string
REQUIRED
 Value specific to the given contact type.
Example: jane@smith.com
type string
REQUIRED
 Means of contact.
Applicable values:
  • EMAIL - Email address.
  • PHONE - Landline phone number.
  • MOBILE - Mobile phone number.
  • SECONDARY_EMAIL - Alternative email address.
provider object Provider details.
contacts array[object]
REQUIRED
 Service provider contact information.
type string
 Notification messages category relevant to a given contact person.
Possible values:
  • NOTIFICATION - Notifications related to Digital LOA document's lifecycle.
  • TECHNICAL - Contact information for technical inquiries.
registeredUser string
OPTIONAL
 contactId, userId or userKey of a registered user.
firstName string
CONDITIONAL
 Contact person's first name. Required if registeredUser hasn't been provided.
Example: Jane
lastName string
CONDITIONAL
 Contact person's last name. Required if registeredUser hasn't been provided.
Example: Smith
timezone string
OPTIONAL
 Contact person's timezone.
Example: Australia/Perth
availability string
OPTIONAL
 Contact person's availability.
Applicable values:
  • WORK_HOURS - Contact person be reached during working hours.
  • ANYTIME - Contact person can be reached anytime throughout the day.
details array[object]
REQUIRED
 Means of contact.
note string
OPTIONAL
 Additional note applicable to the given contact option.
Example: Not suitable for emergencies.
value string
REQUIRED
 Value specific to the given contact type.
Example: jane@smith.com
type string
REQUIRED
 Means of contact.
Applicable values:
  • EMAIL - Email address.
  • PHONE - Landline phone number.
  • MOBILE - Mobile phone number.
  • SECONDARY_EMAIL - Alternative email address.
notes string
REQUIRED		 Additional information, added to the Digital LOA document, that should be taken under consideration.
Example: Rack access: weekdays - 18:00 to 22:00 CET; Saturday - 10:00 to 14:00 CET.
expiryDateTime string
REQUIRED		 Digital LOA document expiration date.
Example: 2022-11-17T22:59:59.999Z
For more information refer to Internet Date/Time Format.

Sample response

Copy 
{
    "token": "REDF-4R56",
    "uuid": "079dc798-05e8-11ed-b939-0242ac120002",
    "state": "READY_FOR_USE",
    "draft": false,
    "changeLog": {
        "createdDateTime": 2018-05-24T18:19:59.999Z
    },
    "link": {
        "rel": "info",
        "href": "https://ic-core-prod-ingress-usw1.clouda.equinix.com:80/diloa/v2/digitalLoas/402cbf99-97d7-440f-8291-1a4b9639154a",
        "method": "GET",
        "contentType": "application/json",
        "authenticate": true
    },
    "expiryDateTime": 2018-06-24T18:19:59.999Z,
    "href": "diloa/v1/digitalLoas/079dc798-05e8-11ed-b939-0242ac120002"
}

Use the Get Specified Digital LOA Document API request to monitor LOA document's status.


Step 4: Authorize Digital LOA Use (conditional)

This step is applicable to new A-side customer relationships.

After the Digital LOA document is created, the A-side party receives an email notification with authorization link. Once the A-side party verifies and approves the Digital LOA document, use the Perform Action on Digital LOA API request to authorize the use of the Digital LOA document.

POST /diloa/v1/digitalLoas/{uuid}/actions
Method POST
Endpoint /diloa/v1/digitalLoas/{uuid}/actions
Headers Authorization, Content-Type
Path Parameters uuid
Query Parameters Not applicable
Body Parameters type

Sample curl request

Copy 
curl -X
POST "https://api.equinix.com/diloa/v1/digitalLoas/079dc798-05e8-11ed-b939-0242ac120002/actions"
-H "Authorization: Bearer qwErtY8zyW1abcdefGHI"
-d '{
    "type": "AUTHORIZE"
}'

Path parameters

Parameter
Description
uuid string
REQUIRED		 Digital LOA document identifier.
Example: 079dc798-05e8-11ed-b939-0242ac120002

Body parameters

Parameter
Description
type string
REQUIRED		 Action type performed on a Digital LOA document.
Applicable values:
  • ACCEPT - Accepts LOA Requestor as a valid Equinix customer.
  • AUTHORIZE - Authorizes Requestor as a party of LOA by its Provider.
  • UNAUTHORIZE - Unauthorizes Requestor as a party of LOA by its Provider.
  • SEND_LOA - Send email with Digital LOA document details.