# Interconnects API

Buying a route from Market View creates an interconnect between one of your accounts and the seller's route. Traffic sent with the route's tech prefix then terminates on it, billed per minute or per message from the account's balance. Purchasing is free; you pay only for traffic.

## Buy a route (create an interconnect)

`POST https://apiv2.telecomsxchange.com/buyers/interconnect`

Reference: https://help.telecomsxchange.com/reference/interconnects/#buy-a-route-create-an-interconnect

Buys a seller's route for one of your accounts, or for all of them, so you can send it traffic. Returns the tech prefix to put in front of the dialled number (voice) or to use for the route (SMS), the route type, and a link to a rate deck. Buying is free; you pay only for the traffic you send. The account must match the route: a voice account for a voice route, an SMPP account for an SMS route.

> Send all fields in the form body. `route_type` is sms for SMS routes and voice otherwise. Anonymous routes show the seller as Anonymous. To get the route's rate deck, call Download a route's rate deck with the route's `i_tariff` rather than following `rates_url`. If `i_account` is not one of your accounts of the route's type, the response is not JSON: check the account before buying.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `add` | integer | body | yes | Must be 1 to perform the purchase. Example `1`. |
| `id` | integer | body | yes | The route's `i_connection`, from Market View or List seller routes. Example `38`. |
| `i_account` | integer | body | yes | The buyer account to attach the route to. 0 attaches it to every one of your accounts of the matching type that does not already have it. Example `1022`. |
| `agree` | string | body | yes | Must be yes, confirming you accept the seller's terms and conditions. One of `yes`. Example `yes`. |

### Errors

| Message | When |
|---|---|
| `This API expects parameter add=1 for route purchase` | add is missing or 0 |
| `Error! You have to agree to seller terms and conditions to purchase the route (agree=yes).` | agree is not exactly yes |
| `Error! Choose another account or route, this route is already purchased for this account.` | the account already has this route |
| `Error! Seller has blocked one of your accounts on this route, you can not purchase it until it gets unblocked.` | the seller has blocked any of your accounts on this route |
| `Error! Private route.` | the route is private and the seller has not opened it to you |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/buyers/interconnect" \
  -d add=1 \
  -d id=38 \
  -d i_account=1022 \
  -d agree=yes
```

### Response: Example

```json
{
  "status": "success",
  "message": "Interconnection with NorthStarTel completed",
  "rates_url": "https://members.telecomsxchange.com/accounts.php?download=38",
  "tech_prefix": "33270#",
  "route_type": "voice"
}
```

## List interconnects

`POST https://apiv2.telecomsxchange.com/interconnections/list`

Reference: https://help.telecomsxchange.com/reference/interconnects/#list-interconnects

Lists the routes you have bought (your interconnects) across all your accounts, with the seller, route name, tech prefix, `i_tariff`, and whether you or the seller has blocked it. The same call can first block or unblock one interconnect: pass its `i_purchased_route` in `block` or `unblock`, and the list returned already reflects the change. A blocked interconnect carries none of your traffic. Free.

> Check `result`, not `status`, for success. `inactive_prs` counts all your interconnects blocked by you or by the seller. Anonymous routes show `vendor_login` Anonymous and have no `i_vendor`. A `block` or `unblock` value that is not one of your interconnects is ignored.

### Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `block` | integer | body | no | `i_purchased_route` of an interconnect to block. Example `3`. |
| `unblock` | integer | body | no | `i_purchased_route` of an interconnect to unblock. |
| `q` | string | body | no | Search text matched against route name, account name, tech prefix and seller login (or the word Anonymous for anonymous routes). Up to 100 characters. |
| `pager` | integer | body | no | Maximum number of interconnects to return. Default `50`. Example `50`. |
| `off` | integer | body | no | Number of interconnects to skip, for paging. Default `0`. Example `0`. |

### Request

```bash
curl --digest -u "$TCXC_USERNAME:$TCXC_API_KEY" -X POST \
  "https://apiv2.telecomsxchange.com/interconnections/list" \
  -d block=3 \
  -d pager=50 \
  -d off=0
```

### Response: Example

```json
{
  "result": "success",
  "purchased_routes": [
    {
      "i_purchased_route": "4",
      "vendor_login": "NorthStarTel",
      "connection_name": "Gold+",
      "i_tariff": "3",
      "tech_prefix": "36310#",
      "blocked": "0",
      "vendor_blocked": "0",
      "account_name": "Northwind",
      "i_vendor": "2",
      "smpp": "1",
      "anonymous": "0"
    },
    {
      "i_purchased_route": "9",
      "vendor_login": "Anonymous",
      "connection_name": "Premium CLI",
      "i_tariff": "41",
      "tech_prefix": "41822#",
      "blocked": "1",
      "vendor_blocked": "0",
      "account_name": "Northwind",
      "smpp": "0",
      "anonymous": "1"
    }
  ],
  "inactive_prs": 1
}
```