---
agentTools:
  projectIndex: https://docs.embercopilot.ai/llms.txt
---

# Submit EDI Files

Submit a batch of 835 and/or 837 EDI files for processing. Files are persisted
durably on receipt and processed asynchronously.

Organization ownership is determined by the API key. A single file may contain
claims for multiple providers.

Each file must include a `clientFileId` that is unique per API key. Resubmitting
a previously used `clientFileId` returns a 409 error, allowing safe retries from
daily batch jobs.

Note on rate limiting: Maximum of 3 concurrent requests allowed per API key.
Exceeding this limit will result in 429 Too Many Requests responses.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "EDI File Ingestion API",
    "description": "API for submitting EDI 835 (ERA/Remittance Advice) and 837 (Claims) files.\nCustomers submit raw X12 EDI files in batch; Ember persists the files and\nprocesses them asynchronously for denial management and claims analysis.\n",
    "version": "1.0.0",
    "contact": {
      "name": "API Support",
      "email": "support@embercopilot.ai"
    }
  },
  "servers": [
    {
      "url": "https://api.embercopilot.ai/v1",
      "description": "Production server"
    }
  ],
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/edi/files": {
      "post": {
        "summary": "Submit EDI Files",
        "description": "Submit a batch of 835 and/or 837 EDI files for processing. Files are persisted\ndurably on receipt and processed asynchronously.\n\nOrganization ownership is determined by the API key. A single file may contain\nclaims for multiple providers.\n\nEach file must include a `clientFileId` that is unique per API key. Resubmitting\na previously used `clientFileId` returns a 409 error, allowing safe retries from\ndaily batch jobs.\n\nNote on rate limiting: Maximum of 3 concurrent requests allowed per API key.\nExceeding this limit will result in 429 Too Many Requests responses.\n",
        "operationId": "submitEdiFiles",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EdiSubmissionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Files received and durably persisted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EdiSubmissionResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Successful batch submission",
                    "value": {
                      "submissionId": "sub_8fd9a734-b39c-4f44-9c5a-7e123456789",
                      "fileCount": 2,
                      "files": [
                        {
                          "clientFileId": "era-2026-04-13-001",
                          "fileId": "663f1a2b3c4d5e6f7a8b9c0d"
                        },
                        {
                          "clientFileId": "claims-2026-04-13-001",
                          "fileId": "663f1a2b3c4d5e6f7a8b9c0e"
                        }
                      ],
                      "requestId": "8fd9a734-b39c-4f44-9c5a-7e123456789",
                      "requestTimestamp": "2026-04-14T10:00:00Z"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request - missing required fields or invalid file type",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "missingField": {
                    "summary": "Missing required field",
                    "value": {
                      "error": {
                        "code": "MISSING_REQUIRED_FIELD",
                        "message": "files[0]: missing required field clientFileId",
                        "requestId": "8fd9a734-b39c-4f44-9c5a-7e123456789"
                      }
                    }
                  },
                  "invalidFileType": {
                    "summary": "Invalid file type",
                    "value": {
                      "error": {
                        "code": "INVALID_FILE_TYPE",
                        "message": "files[0]: fileType must be \"835\" or \"837\", got \"834\"",
                        "requestId": "8fd9a734-b39c-4f44-9c5a-7e123456789"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "409": {
            "description": "Duplicate file - clientFileId already submitted for this API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "duplicate": {
                    "summary": "Duplicate clientFileId",
                    "value": {
                      "error": {
                        "code": "DUPLICATE_FILE",
                        "message": "The following clientFileIds have already been submitted: era-2026-04-13-001",
                        "requestId": "8fd9a734-b39c-4f44-9c5a-7e123456789"
                      }
                    }
                  }
                }
              }
            }
          },
          "413": {
            "description": "Payload too large - total request body exceeds 25 MB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/UnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "authorization",
        "description": "API key for authentication"
      }
    },
    "schemas": {
      "EdiSubmissionRequest": {
        "type": "object",
        "required": [
          "files"
        ],
        "properties": {
          "files": {
            "type": "array",
            "description": "Array of EDI files to submit (1-100 files per request)",
            "minItems": 1,
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/EdiFileInput"
            }
          }
        }
      },
      "EdiFileInput": {
        "type": "object",
        "required": [
          "clientFileId",
          "fileType",
          "content"
        ],
        "properties": {
          "clientFileId": {
            "type": "string",
            "description": "Customer-supplied identifier for this file. Must be unique per API key.\nUsed for idempotent submission — resubmitting the same clientFileId returns 409.\n",
            "example": "era-2026-04-13-001"
          },
          "fileType": {
            "type": "string",
            "enum": [
              "835",
              "837"
            ],
            "description": "EDI transaction type",
            "example": "835"
          },
          "content": {
            "type": "string",
            "description": "Raw X12 EDI file content",
            "example": "ISA*00*          *00*          *ZZ*SENDER..."
          },
          "receivedAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the clearinghouse produced or delivered the file (optional)",
            "example": "2026-04-13T06:00:00Z"
          }
        }
      },
      "EdiSubmissionResponse": {
        "type": "object",
        "properties": {
          "submissionId": {
            "type": "string",
            "description": "Unique identifier grouping the files in this submission",
            "example": "sub_8fd9a734-b39c-4f44-9c5a-7e123456789"
          },
          "fileCount": {
            "type": "integer",
            "description": "Number of files accepted",
            "example": 2
          },
          "files": {
            "type": "array",
            "description": "Per-file confirmation with assigned IDs",
            "items": {
              "type": "object",
              "properties": {
                "clientFileId": {
                  "type": "string",
                  "description": "The customer-supplied identifier echoed back",
                  "example": "era-2026-04-13-001"
                },
                "fileId": {
                  "type": "string",
                  "description": "Ember-assigned file identifier",
                  "example": "663f1a2b3c4d5e6f7a8b9c0d"
                }
              }
            }
          },
          "requestId": {
            "type": "string",
            "description": "Unique identifier for this request",
            "example": "8fd9a734-b39c-4f44-9c5a-7e123456789"
          },
          "requestTimestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the request was processed",
            "example": "2026-04-14T10:00:00Z"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Error code",
                "example": "MISSING_REQUIRED_FIELD"
              },
              "message": {
                "type": "string",
                "description": "Human-readable error message",
                "example": "Missing required field: files"
              },
              "requestId": {
                "type": "string",
                "description": "Unique identifier for this request",
                "example": "8fd9a734-b39c-4f44-9c5a-7e123456789"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Unauthorized - Invalid API key",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "UnprocessableEntity": {
        "description": "Unprocessable Entity - Data validation failed",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Too Many Requests - Concurrency limit exceeded",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "InternalServerError": {
        "description": "Internal Server Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 105,
      "1": 231,
      "2": 23,
      "3": 208,
      "4": 22,
      "5": 13,
      "6": 17,
      "7": 40,
      "8": 107,
      "9": 235,
      "10": 68,
      "11": 166
    }
  }
}
```