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.

diloa-create-workflow

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

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

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

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

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

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

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.

Step 1: Authenticate​

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

Step 3: Create Digital LOA​

Step 4: Authorize Digital LOA Use (conditional)​

Step 1: Authenticate

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

Step 3: Create Digital LOA

Step 4: Authorize Digital LOA Use (conditional)