Skip to main content

Onboard a Trading Partner

Register a new trading partner in ECGrid by creating their ECGrid ID and establishing the interconnect that authorizes EDI exchange between your mailbox and theirs.

Overview​

A trading partner in ECGrid is represented by an ECGrid ID — a record that binds an ISA qualifier and ISA ID pair to a specific mailbox. Once the ECGrid ID exists, you create an interconnect (partnership) to enable routing between your ID and theirs. Both steps are required before EDI files can flow between the two parties.

Sequence:

  1. Create the trading partner's ECGrid ID with POST /v2/ids.
  2. Create the interconnect (partnership) with POST /v2/partners.

REST​

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

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

An ECGrid ID represents an ISA sender/receiver identity. Each ID belongs to a mailbox and carries an ISA qualifier + ISA ID pair that appears in the EDI envelope.

POST https://rest.ecgrid.io/v2/ids
Content-Type: application/json
X-API-Key: YOUR_API_KEY
{
  "networkId": 0,
  "mailboxId": 54321,
  "isaQualifier": "01",
  "isaId": "ACMECORP      ",
  "description": "Acme Corporation Production ID",
  "useType": "Production"
}
FieldTypeRequiredDescription
networkIdintegerNoNetwork ID. Pass 0 to use the network for the API key.
mailboxIdintegerYesThe mailbox this ECGrid ID belongs to.
isaQualifierstringYesTwo-character ISA qualifier (e.g., "01" for DUNS, "ZZ" for mutually defined).
isaIdstringYesUp to 15-character ISA ID, padded with trailing spaces to 15 characters.
descriptionstringNoHuman-readable label for this ID.
useTypestringNo"Test", "Production", or "TestAndProduction".

Response:

{
  "success": true,
  "data": {
    "ecGridId": 678900,
    "mailboxId": 54321,
    "isaQualifier": "01",
    "isaId": "ACMECORP      ",
    "description": "Acme Corporation Production ID",
    "status": "Active"
  }
}

Record the ecGridId — you need it to create the interconnect.

Step 2 — Create the interconnect​

An interconnect authorizes and routes EDI traffic between two ECGrid IDs. You supply your ECGrid ID and the trading partner's ECGrid ID.

POST https://rest.ecgrid.io/v2/partners
Content-Type: application/json
X-API-Key: YOUR_API_KEY
{
  "ecGridIdFrom": 111111,
  "ecGridIdTo": 678900,
  "status": "Active"
}
FieldTypeRequiredDescription
ecGridIdFromintegerYesYour ECGrid ID (the initiating party).
ecGridIdTointegerYesThe trading partner's ECGrid ID created in Step 1.
statusstringNoInitial status. Use "Active" to enable routing immediately.

Response:

{
  "success": true,
  "data": {
    "interconnectId": 99001,
    "ecGridIdFrom": 111111,
    "ecGridIdTo": 678900,
    "status": "Active",
    "createdDate": "2026-05-07T10:15:00Z"
  }
}

Once the interconnect is "Active", EDI files addressed to either ECGrid ID will route between the two parties.

Code Examples​

// .NET 10 — create ECGrid ID and interconnect using IHttpClientFactory (registered as "ECGrid")
// API key loaded from IConfiguration — never hardcoded

using System.Net.Http.Json;

public record CreateECGridIdRequest(
    int NetworkId,
    int MailboxId,
    string IsaQualifier,
    string IsaId,
    string Description,
    string UseType);

public record ECGridIdInfo(
    int ECGridId,
    int MailboxId,
    string IsaQualifier,
    string IsaId,
    string Status);

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

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

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

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

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

    /// <summary>
    /// Creates an ECGrid ID for a new trading partner and establishes an active interconnect.
    /// </summary>
    /// <param name="mailboxId">Mailbox to attach the new ECGrid ID to.</param>
    /// <param name="isaQualifier">ISA-06 qualifier (e.g., "01", "ZZ").</param>
    /// <param name="isaId">ISA-06 sender/receiver ID, padded to 15 chars.</param>
    /// <param name="myECGridId">Your existing ECGrid ID — the other side of the interconnect.</param>
    /// <param name="description">Optional human-readable label for the new ID.</param>
    public async Task<(ECGridIdInfo Id, InterconnectInfo Interconnect)> OnboardPartnerAsync(
        int mailboxId,
        string isaQualifier,
        string isaId,
        int myECGridId,
        string description = "",
        CancellationToken cancellationToken = default)
    {
        var http = _httpClientFactory.CreateClient("ECGrid");

        // Step 1 — create the trading partner ECGrid ID
        var idRequest = new CreateECGridIdRequest(
            NetworkId:    0,
            MailboxId:    mailboxId,
            IsaQualifier: isaQualifier,
            IsaId:        isaId.PadRight(15),
            Description:  description,
            UseType:      "Production");

        var idResponse = await http.PostAsJsonAsync(
            "/v2/ids", idRequest, cancellationToken);
        idResponse.EnsureSuccessStatusCode();

        var idResult = await idResponse.Content
            .ReadFromJsonAsync<ApiResponse<ECGridIdInfo>>(cancellationToken: cancellationToken)
            ?? throw new InvalidOperationException("Empty response from ECGrid ID create.");

        _logger.LogInformation(
            "ECGrid ID created: {ECGridId} ({IsaQualifier}:{IsaId})",
            idResult.Data.ECGridId, idResult.Data.IsaQualifier, idResult.Data.IsaId.Trim());

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

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

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

        _logger.LogInformation(
            "Interconnect created: ID={InterconnectId} Status={Status}",
            partnerResult.Data.InterconnectId, partnerResult.Data.Status);

        return (idResult.Data, partnerResult.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<ECGridOnboardingService>();

SOAP​

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

Methods:

  • TPAdd(SessionID, NetworkID, MailboxID, ISAQualifier, ISAID, ...) — creates the ECGrid ID
  • InterconnectAdd(SessionID, ECGridIDFrom, ECGridIDTo, ...) — creates the interconnect

Step 1 — Log in and get a session ID​

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

Step 2 — Create the ECGrid ID with TPAdd​

var tpResult = await client.TPAddAsync(
    sessionId,
    networkId:    0,
    mailboxId:    54321,
    isaQualifier: "01",
    isaId:        "ACMECORP      ",
    description:  "Acme Corporation Production ID");

int newECGridId = tpResult.TPAddResult.ECGridID;
Console.WriteLine($"ECGrid ID created: {newECGridId}");

Step 3 — Create the interconnect with InterconnectAdd​

var interconnect = await client.InterconnectAddAsync(
    sessionId,
    ecgridIdFrom: 111111,    // your ECGrid ID
    ecgridIdTo:   newECGridId);

Console.WriteLine($"Interconnect ID: {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;

    // Create trading partner ECGrid ID
    var tpResult = await client.TPAddAsync(
        sessionId,
        networkId:    0,
        mailboxId:    54321,
        isaQualifier: "01",
        isaId:        "ACMECORP      ",
        description:  "Acme Corporation Production ID");

    int partnerECGridId = tpResult.TPAddResult.ECGridID;
    Console.WriteLine($"ECGrid ID created: {partnerECGridId}");

    // Create the interconnect between your ID and the partner's ID
    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}");
}
finally
{
    if (!string.IsNullOrEmpty(sessionId))
        await client.LogoutAsync(sessionId);
}