> ## Documentation Index
> Fetch the complete documentation index at: https://docs.megaport.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Joining an IX with the API

> This help topic describes how to use the Megaport API to join an Internet Exchange (IX).

This topic describes the API procedure to join an Internet Exchange (IX) from a Port.

Before you begin, obtain a valid access token. For more information, see [Creating an API Key](/api/api-key).

## Use cases

Using the API to join an IX allows you to:

* Automate IX provisioning as part of your network deployment workflows.
* Integrate IX ordering into your infrastructure-as-code processes.
* Programmatically manage peering infrastructure across multiple locations.

## Prerequisites

Before joining an IX, ensure that:

* You have an active Port in a location where an IX is available.
* You can meet the [IX requirements](/ix/ix-requirements).

## Steps to join an IX

To join an IX using the API:

1. Get the `productUid` for your Port
2. Find available IX locations
3. Validate the IX order
4. Order the IX

## Getting your Port product ID

To join an IX, you need the `productUid` for the Port.

**Endpoint**

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
GET {baseUrl}/v2/products/
```

From the returned product details, locate the `productUid` value for the Port you want to connect from.

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "productName": "My API Port",
    "productUid": "7f5f9574-315e-4527-af44-122605a411de"
}
```

## Finding available IX locations

To find IX locations where you can connect, query the partner megaports endpoint with the IX connect type.

**Endpoint**

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
GET {baseUrl}/v2/dropdowns/partner/megaports
```

**Query Parameters**

| Parameter    | Required | Description                                                |
| :----------- | :------- | :--------------------------------------------------------- |
| connectType  | No       | Filter by connection type. Use `IX` for Internet Exchange. |
| vxcPermitted | No       | Filter to locations accepting new connections. Use `true`. |

**Example Request**

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
GET {baseUrl}/v2/dropdowns/partner/megaports?connectType=IX&vxcPermitted=true
```

**Response**

The response includes available IX locations with their `productUid` and `locationId` values.

```json {3,7} theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "connectType": "IX",
    "productUid": "f274bd09-1796-43af-8837-28fa4fa2a1ab",
    "vxcPermitted": true,
    "companyName": "MegaIX Sydney",
    "title": "MegaIX Sydney",
    "locationId": 3
}
```

## Validating the IX order

Before ordering, validate the IX configuration to review pricing details and confirm the settings are correct.

**Endpoint**

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
POST {baseUrl}/v3/networkdesign/validate
```

**Request Body Parameters**

| Parameter     | Required | Description                                   |
| :------------ | :------- | :-------------------------------------------- |
| productUid    | Yes      | The `productUid` of the Port to connect from. |
| associatedIxs | Yes      | An array containing the IX configuration.     |

**IX Configuration Parameters**

| Parameter      | Required | Description                                                                                                              |
| :------------- | :------- | :----------------------------------------------------------------------------------------------------------------------- |
| productName    | Yes      | The name of the IX connection.                                                                                           |
| rateLimit      | Yes      | The speed of the connection in Mbps.<br />Cannot exceed the port speed for metro connections.                            |
| term           | No       | Contract term in months.<br />Valid values: 1 (month-to-month), 12, 24, 36, 48, or 60. Default: 12.                      |
| shutdown       | No       | Initial state of the connection.<br />`true` shuts down the IX (no traffic flows); `false` enables it. Default: `false`. |
| vlan           | No       | Preferred VLAN ID (2-4093).<br />If not specified or in use, Megaport assigns one.                                       |
| asn            | Yes      | Your autonomous system number (ASN).<br />Must be a public 16-bit or 32-bit ASN.                                         |
| macAddress     | Yes      | The MAC address of the Layer 3 device establishing the BGP session. Format: `XX:XX:XX:XX:XX:XX`.                         |
| password       | No       | BGP password (1-25 characters).<br />Allowed characters: a-z, A-Z, 0-9, ! @ # . \$ % ^ & \* + = - \_                     |
| publicGraph    | No       | Whether your traffic graphs are visible to other IX participants. `true` for public; `false` for private.                |
| asSet          | No       | The peer AS-SET (AS macro) for route filtering.<br />If not specified, your ASN is used.                                 |
| bEndProductUid | Yes      | The `productUid` of the IX destination from the partner megaports lookup.                                                |

**Example Request**

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
POST {baseUrl}/v3/networkdesign/validate
```

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
[
  {
    "productUid": "7f5f9574-315e-4527-af44-122605a411de",
    "associatedIxs": [
      {
        "productName": "My API IX",
        "rateLimit": 1000,
        "term": 12,
        "shutdown": false,
        "vlan": 100,
        "asn": 136999,
        "macAddress": "01:02:0f:04:58:20",
        "password": "mybgppassword",
        "publicGraph": false,
        "asSet": "AS-EXAMPLE",
        "bEndProductUid": "f274bd09-1796-43af-8837-28fa4fa2a1ab"
      }
    ]
  }
]
```

**Response**

A successful validation returns pricing details and confirms the configuration is valid.

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "message": "Validation passed",
    "data": [
        {
            "productUid": "7f5f9574-315e-4527-af44-122605a411de",
            "associatedIxs": [
                {
                    "productName": "My API IX",
                    "rateLimit": 1000,
                    "term": 12,
                    "monthlyRate": 250.00,
                    "currency": "USD"
                }
            ]
        }
    ]
}
```

## Ordering the IX

After validation, use the same Request body to order the IX.

**Endpoint**

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
POST {baseUrl}/v3/networkdesign/buy
```

**Example Request**

Copy the validated body and send it to the buy endpoint.

```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
POST {baseUrl}/v3/networkdesign/buy
```

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
[
  {
    "productUid": "7f5f9574-315e-4527-af44-122605a411de",
    "associatedIxs": [
      {
        "productName": "My API IX",
        "rateLimit": 1000,
        "term": 12,
        "shutdown": false,
        "vlan": 100,
        "asn": 136999,
        "macAddress": "01:02:0f:04:58:20",
        "password": "mybgppassword",
        "publicGraph": false,
        "asSet": "AS-EXAMPLE",
        "bEndProductUid": "f274bd09-1796-43af-8837-28fa4fa2a1ab"
      }
    ]
  }
]
```

**Response**

A successful order returns details about the ordered IX, including its `productUid`.

```json {5} theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "message": "IX ordered successfully",
    "data": [
        {
            "productUid": "9e8ad9d7-85ab-46f9-ab13-c0966891341b",
            "productName": "My API IX",
            "provisioningStatus": "DEPLOYABLE"
        }
    ]
}
```

After deployment, Megaport sends an email to your registered email address with additional information on how to finish the BGP configuration.

## Helpful references

* [Changing an IX Configuration with the API](/api/api-ix-change)
* [IX Requirements](/ix/ix-requirements)
* [Joining an IX](/ix/joining-an-ix)
* [Moving a VXC and IX with the API](/api/api-vxc-move)
* [Shutting Down a VXC and IX with the API](/api/api-vxc-shut-down)