Skip to main content

Set Up an Interconnect

Define the authorized EDI routing relationship between two ECGrid IDs so that EDI documents can flow between your mailbox and a trading partner's mailbox.

Overview​

An interconnect is the record in ECGrid that permits EDI routing between two ECGrid IDs. Without an active interconnect, parcels addressed between those IDs will be rejected. Interconnects are directional by configuration but typically set up bidirectionally — one interconnect record covers both inbound and outbound flows between the two IDs.

When your trading partner's ECGrid ID is already registered in the ECGrid network (e.g., they use a different VAN or are an existing ECGrid subscriber), you search for their ID first, then create the interconnect. If the partner is brand new to ECGrid, follow Onboard a Trading Partner instead, which covers creating the ECGrid ID as well.

Sequence:

  1. Search for the trading partner's ECGrid ID with GET /v2/ids/find.
  2. Create the interconnect with POST /v2/partners.

REST​

Auth: X-API-Key: <key> header

Step 1 — Find the trading partner's ECGrid ID​

Search by ISA qualifier and ISA ID to locate the partner's registered ECGrid ID.

GET https://rest.ecgrid.io/v2/ids/find?isaQualifier=01&isaId=PARTNERCO
X-API-Key: YOUR_API_KEY
Query ParameterTypeRequiredDescription
isaQualifierstringYesTwo-character ISA qualifier (e.g., "01", "ZZ").
isaIdstringYesThe ISA ID to search for. Partial matches may be supported.

Response:

{
  "success": true,
  "data": [
    {
      "ecGridId": 334455,
      "isaQualifier": "01",
      "isaId": "PARTNERCO     ",
      "companyName": "Partner Company Inc.",
      "status": "Active"
    }
  ]
}

If no results are returned, the partner may not yet have an ECGrid ID. In that case, create one first — see Onboard a Trading Partner.

Step 2 — Create the interconnect​

Use your ECGrid ID and the partner's ecGridId from Step 1 to create the interconnect.

POST https://rest.ecgrid.io/v2/partners
Content-Type: application/json
X-API-Key: YOUR_API_KEY
{
  "ecGridIdFrom": 111111,
  "ecGridIdTo": 334455,
  "status": "Active"
}
FieldTypeRequiredDescription
ecGridIdFromintegerYesYour ECGrid ID — the initiating side of the relationship.
ecGridIdTointegerYesThe trading partner's ECGrid ID from Step 1.
statusstringNoInitial status. Use "Active" to enable routing immediately. Defaults to "Active".

Response:

{
  "success": true,
  "data": {
    "interconnectId": 88200,
    "ecGridIdFrom": 111111,
    "ecGridIdTo": 334455,
    "status": "Active",
    "createdDate": "2026-05-07T11:00:00Z"
  }
}

Once status is "Active", ECGrid begins routing EDI parcels addressed between the two IDs in both directions.

:::tip Verify routing After creating the interconnect, use Send a Test File to confirm that EDI flows end-to-end between the two parties. :::

Code Examples​

// .NET 10 — find a partner's ECGrid ID and create an interconnect
// API key loaded from IConfiguration — never hardcoded

using System.Net.Http.Json;

public record ECGridIdSearchResult(
    int ECGridId,
    string IsaQualifier,
    string IsaId,
    string CompanyName,
    string Status);

public record SearchResponse(bool Success, List<ECGridIdSearchResult> Data);

public record CreatePartnerRequest(
    int ECGridIdFrom,
    int ECGridIdTo,
    string Status);

public record InterconnectInfo(
    int InterconnectId,
    int ECGridIdFrom,
    int ECGridIdTo,
    string Status,
    DateTimeOffset CreatedDate);

public record ApiResponse<T>(bool Success, T Data);

public class ECGridInterconnectService
{
    private readonly IHttpClientFactory _httpClientFactory;
    private readonly ILogger<ECGridInterconnectService> _logger;

    public ECGridInterconnectService(
        IHttpClientFactory httpClientFactory,
        ILogger<ECGridInterconnectService> logger)
    {
        _httpClientFactory = httpClientFactory;
        _logger = logger;
    }

    /// <summary>
    /// Finds a trading partner's ECGrid ID and creates an active interconnect.
    /// Throws InvalidOperationException if no matching ECGrid ID is found.
    /// </summary>
    /// <param name="myECGridId">Your ECGrid ID (the from side of the interconnect).</param>
    /// <param name="partnerIsaQualifier">Partner's ISA qualifier.</param>
    /// <param name="partnerIsaId">Partner's ISA ID.</param>
    public async Task<InterconnectInfo> SetupInterconnectAsync(
        int myECGridId,
        string partnerIsaQualifier,
        string partnerIsaId,
        CancellationToken cancellationToken = default)
    {
        var http = _httpClientFactory.CreateClient("ECGrid");

        // Step 1 — find the partner's ECGrid ID
        var searchUrl = $"/v2/ids/find?isaQualifier={Uri.EscapeDataString(partnerIsaQualifier)}" +
                        $"&isaId={Uri.EscapeDataString(partnerIsaId)}";

        var searchResponse = await http.GetFromJsonAsync<SearchResponse>(
            searchUrl, cancellationToken)
            ?? throw new InvalidOperationException("No response from ECGrid ID search.");

        if (searchResponse.Data.Count == 0)
            throw new InvalidOperationException(
                $"No ECGrid ID found for {partnerIsaQualifier}:{partnerIsaId}. " +
                "Use OnboardPartnerAsync to create one first.");

        // Take the first active match
        var partnerInfo = searchResponse.Data.FirstOrDefault(x => x.Status == "Active")
            ?? searchResponse.Data[0];

        _logger.LogInformation(
            "Found partner ECGrid ID: {ECGridId} ({Company})",
            partnerInfo.ECGridId, partnerInfo.CompanyName);

        // Step 2 — create the interconnect
        var partnerRequest = new CreatePartnerRequest(
            ECGridIdFrom: myECGridId,
            ECGridIdTo:   partnerInfo.ECGridId,
            Status:       "Active");

        var partnerResponse = await http.PostAsJsonAsync(
            "/v2/partners", partnerRequest, cancellationToken);
        partnerResponse.EnsureSuccessStatusCode();

        var result = await partnerResponse.Content
            .ReadFromJsonAsync<ApiResponse<InterconnectInfo>>(cancellationToken: cancellationToken)
            ?? throw new InvalidOperationException("Empty response from partner create.");

        _logger.LogInformation(
            "Interconnect created: ID={InterconnectId} From={From} To={To} Status={Status}",
            result.Data.InterconnectId,
            result.Data.ECGridIdFrom,
            result.Data.ECGridIdTo,
            result.Data.Status);

        return result.Data;
    }
}

Registration in Program.cs:

builder.Services.AddHttpClient("ECGrid", client =>
{
    client.BaseAddress = new Uri("https://rest.ecgrid.io");
    client.DefaultRequestHeaders.Add(
        "X-API-Key",
        builder.Configuration["ECGrid:ApiKey"]);
});

builder.Services.AddScoped<ECGridInterconnectService>();

SOAP​

:::caution Established API The SOAP API is in maintenance mode. For new integrations use REST above. :::

Methods:

  • TPSearch(SessionID, ISAQualifier, ISAID, ...) — find an existing ECGrid ID
  • InterconnectAdd(SessionID, ECGridIDFrom, ECGridIDTo, ...) — create the interconnect

Step 1 — Log in and get a session ID​

var loginResult = await client.LoginAsync(username, password);
string sessionId = loginResult.LoginResult;

Step 2 — Find the partner with TPSearch​

var searchResult = await client.TPSearchAsync(
    sessionId,
    isaQualifier: "01",
    isaId:        "PARTNERCO",
    pageNo:       1,
    recordsPerPage: 10);

var partner = searchResult.TPSearchResult?.FirstOrDefault()
    ?? throw new InvalidOperationException("Partner ECGrid ID not found.");

int partnerECGridId = partner.ECGridID;
Console.WriteLine($"Found partner: {partnerECGridId} — {partner.CompanyName}");

Step 3 — Create the interconnect with InterconnectAdd​

int myECGridId = int.Parse(Environment.GetEnvironmentVariable("MY_ECGRID_ID")!);

var interconnect = await client.InterconnectAddAsync(
    sessionId,
    ecgridIdFrom: myECGridId,
    ecgridIdTo:   partnerECGridId);

Console.WriteLine($"Interconnect created: {interconnect.InterconnectAddResult.InterconnectID}");

Code Examples​

// .NET 10 — dotnet-svcutil generated proxy
// Reference: https://os.ecgrid.io/v4.1/prod/ECGridOS.asmx?WSDL

using ECGridOS;

var binding  = new BasicHttpBinding(BasicHttpSecurityMode.Transport);
var endpoint = new EndpointAddress("https://os.ecgrid.io/v4.1/prod/ECGridOS.asmx");
var client   = new ECGridOSAPIClient(binding, endpoint);

string sessionId = string.Empty;

try
{
    var loginResult = await client.LoginAsync(
        Environment.GetEnvironmentVariable("ECGRID_USER")!,
        Environment.GetEnvironmentVariable("ECGRID_PASS")!);
    sessionId = loginResult.LoginResult;

    // Find the trading partner's ECGrid ID
    var searchResult = await client.TPSearchAsync(
        sessionId,
        isaQualifier:   "01",
        isaId:          "PARTNERCO",
        pageNo:         1,
        recordsPerPage: 10);

    var partner = searchResult.TPSearchResult?.FirstOrDefault()
        ?? throw new InvalidOperationException("No matching ECGrid ID found for this partner.");

    Console.WriteLine($"Partner found: ECGridID={partner.ECGridID}  Company={partner.CompanyName}");

    // Create the interconnect
    int myECGridId = int.Parse(Environment.GetEnvironmentVariable("MY_ECGRID_ID")!);

    var icResult = await client.InterconnectAddAsync(
        sessionId,
        ecgridIdFrom: myECGridId,
        ecgridIdTo:   partner.ECGridID);

    Console.WriteLine($"Interconnect created: ID={icResult.InterconnectAddResult.InterconnectID}");
}
finally
{
    if (!string.IsNullOrEmpty(sessionId))
        await client.LogoutAsync(sessionId);
}