Skip to main content

Upload a File

Send an EDI file from your application into ECGrid for routing and delivery to a trading partner.

Overview​

Uploading places an outbound EDI file into the ECGrid network. ECGrid examines the EDI interchange headers (ISA/GS segments) to determine the sender and recipient, routes the file to the appropriate trading partner's mailbox, and returns a parcelId you can use to track delivery status.

You may also explicitly provide fromECGridId and toECGridId in the request body to override header-based routing — useful when the ISA IDs are not unique within your network or when you are sending test files.

Sequence:

  1. Read the EDI file from disk (or build it in memory).
  2. Base64-encode the bytes.
  3. POST to the upload endpoint with filename, encoded content, and optional routing IDs.
  4. Store the returned parcelId for status tracking.

REST​

Endpoint: POST /v2/parcels/upload

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

Step 1 — Prepare the request body​

POST https://rest.ecgrid.io/v2/parcels/upload
Content-Type: application/json
X-API-Key: YOUR_API_KEY
{
  "fileName": "850_order_20260507.edi",
  "content": "SVNBKDE...",
  "fromECGridId": 123456,
  "toECGridId": 789012
}
FieldTypeRequiredDescription
fileNamestringYesOriginal filename including extension. Preserved in the parcel record.
contentstringYesBase64-encoded EDI file bytes.
fromECGridIdintegerNoSender's ECGrid ID. If omitted, ECGrid derives from the ISA06 segment.
toECGridIdintegerNoRecipient's ECGrid ID. If omitted, ECGrid derives from the ISA08 segment.

Step 2 — Inspect the response​

{
  "success": true,
  "data": {
    "parcelId": 112233,
    "fileName": "850_order_20260507.edi",
    "status": "OutBoxQueued",
    "size": 8192
  }
}

Store parcelId. Use GET /v2/parcels/{id} to poll delivery status if needed.

Code Examples​

// .NET 10 — read a file from disk and upload it using IHttpClientFactory
// "ECGrid" named client is registered with base address and X-API-Key header

using System.Net.Http.Json;

public record UploadRequest(
    string FileName,
    string Content,          // Base64-encoded bytes
    int FromECGridId,
    int ToECGridId);

public record UploadData(long ParcelId, string FileName, string Status, long Size);

public record UploadResponse(bool Success, UploadData Data);

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

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

    /// <summary>
    /// Reads a file from disk, Base64-encodes it, and uploads it to ECGrid.
    /// Returns the assigned parcelId on success.
    /// </summary>
    public async Task<long> UploadFileAsync(
        string filePath,
        int fromECGridId,
        int toECGridId,
        CancellationToken cancellationToken = default)
    {
        if (!File.Exists(filePath))
            throw new FileNotFoundException("EDI file not found.", filePath);

        byte[] fileBytes = await File.ReadAllBytesAsync(filePath, cancellationToken);
        string base64Content = Convert.ToBase64String(fileBytes);
        string fileName = Path.GetFileName(filePath);

        var request = new UploadRequest(fileName, base64Content, fromECGridId, toECGridId);

        var http = _httpClientFactory.CreateClient("ECGrid");
        var response = await http.PostAsJsonAsync(
            "/v2/parcels/upload", request, cancellationToken);

        response.EnsureSuccessStatusCode();

        var result = await response.Content
            .ReadFromJsonAsync<UploadResponse>(cancellationToken: cancellationToken)
            ?? throw new InvalidOperationException("Empty response from upload endpoint.");

        if (!result.Success)
            throw new InvalidOperationException($"Upload failed for file '{fileName}'.");

        _logger.LogInformation(
            "Uploaded '{FileName}' → parcelId={ParcelId}  status={Status}",
            fileName, result.Data.ParcelId, result.Data.Status);

        return result.Data.ParcelId;
    }
}

Usage:

long parcelId = await uploader.UploadFileAsync(
    filePath:     "/data/edi/outbound/850_order_20260507.edi",
    fromECGridId: 123456,
    toECGridId:   789012,
    cancellationToken: ct);

Console.WriteLine($"Uploaded as parcelId={parcelId}");

:::tip Header-Based Routing If your EDI files contain valid ISA/GS segments with the correct sender and receiver IDs that are already registered in ECGrid, you can omit fromECGridId and toECGridId and let ECGrid route automatically. Explicit IDs are recommended when the same ISA ID is used in multiple mailboxes or networks. :::

SOAP​

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

Method: ParcelUpload(SessionID, FileName, Bytes, Content) → long (ParcelID)

ParameterTypeDescription
SessionIDstringActive session token.
FileNamestringOriginal filename including extension.
Bytesbyte[]Raw file bytes — not Base64 encoded; the SOAP stack handles encoding.
ContentstringMIME content type, e.g. "application/edi-x12".

Step 1 — Call ParcelUpload​

byte[] fileBytes = await File.ReadAllBytesAsync(filePath);
string fileName  = Path.GetFileName(filePath);

var result = await client.ParcelUploadAsync(
    sessionId,
    fileName,
    fileBytes,
    content: "application/edi-x12");

long parcelId = result.ParcelUploadResult;
Console.WriteLine($"Uploaded parcelId={parcelId}");

Code Examples​

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

using ECGridOS;

public static async Task<long> UploadEdiFileAsync(
    ECGridOSAPIClient client,
    string sessionId,
    string filePath)
{
    if (!File.Exists(filePath))
        throw new FileNotFoundException("EDI file not found.", filePath);

    byte[] fileBytes = await File.ReadAllBytesAsync(filePath);
    string fileName  = Path.GetFileName(filePath);

    // ParcelUpload handles Base64 encoding internally via the SOAP stack
    var result = await client.ParcelUploadAsync(
        sessionId,
        fileName,
        fileBytes,
        content: "application/edi-x12");

    long parcelId = result.ParcelUploadResult;
    Console.WriteLine($"Uploaded '{fileName}' → parcelId={parcelId}");
    return parcelId;
}

Routing Logic​

ECGrid determines delivery routing in the following priority order:

  1. Explicit IDs — if fromECGridId / toECGridId are provided (REST) or set on the comm configuration, they take precedence.
  2. ISA header — ECGrid reads ISA06 (sender) and ISA08 (recipient) qualifier/ID pairs from the EDI interchange envelope.
  3. GS header — used as a fallback or for sub-routing within an interchange.

If routing cannot be resolved, the parcel is placed in a suspense state and an error is returned.