> ## Documentation Index
> Fetch the complete documentation index at: https://withforerunner.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Submit File

> Upload a new file to Forerunner

<ParamField path="POST" type="endpoint">
  /api/v1/files
</ParamField>

Upload a new file to Forerunner and optionally associate it with a property.

<Warning>
  This endpoint accepts **`multipart/form-data`**, not JSON. All parameters,
  including metadata like `fileType` and `address`, must be sent as form fields
  alongside the file. Do not send a JSON body. See the [cURL
  example](#request-example) below and the [Content-Type](/developers/api/overview#content-type)
  section in the API overview for more details.
</Warning>

## Form Fields

<ParamField body="fileUpload" type="file" required>
  The file to upload. The allowed MIME types depend on the selected `fileType` for your account.
</ParamField>

<ParamField body="fileType" type="string" required>
  Type of file being uploaded. Common examples include: `Elevation Certificate`, `Building Permit`, `Property Image`, or other document type names configured for your account.

  The value must match an existing document type name in your Forerunner account. See [File types](/files/file-types) for how document types are configured.
</ParamField>

<ParamField body="address" type="string">
  Street address to associate with the file (e.g., "123 Main St, Springfield,
  IL")
</ParamField>

<ParamField body="parcelId" type="string">
  Parcel ID to associate with the file
</ParamField>

<ParamField body="coordinates" type="array">
  Two-element array `[latitude, longitude]` in `EPSG:4326` format

  ```json theme={null}
  [39.78, -89.65]
  ```
</ParamField>

<ParamField body="externalSystemId" type="string">
  Unique identifier within your system for duplicate detection. If a file with the same `externalSystemId` already exists, the API returns a `409` HTTP status code.
</ParamField>

<Note>
  At least one of `address`, `parcelId`, or `coordinates` is required for non-Elevation Certificate files. If multiple are provided, they will be used to find or create the appropriate property record. Only single documents are accepted per request.
</Note>

## Response

<ResponseField name="file" type="object">
  <Expandable title="properties">
    <ResponseField name="id" type="string">
      UUID uniquely identifying the file
    </ResponseField>

    <ResponseField name="url" type="string">
      Authenticated access link to the document
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="errors" type="array">
  Array of error objects. See [Errors](/developers/api/overview#errors).
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://app.withforerunner.com/api/v1/files \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -F "fileUpload=@elevation_cert.pdf" \
    -F "fileType=Elevation Certificate" \
    -F "address=123 Main St, Springfield, IL"
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "file": {
      "id": "f8a3b2c1-d4e5-6789-abcd-ef0123456789",
      "url": "https://app.withforerunner.com/files/f8a3b2c1-d4e5-6789-abcd-ef0123456789"
    },
    "errors": []
  }
  ```

  ```json With Validation Warnings theme={null}
  {
    "file": {
      "id": "f8a3b2c1-d4e5-6789-abcd-ef0123456789",
      "url": "https://app.withforerunner.com/files/f8a3b2c1-d4e5-6789-abcd-ef0123456789"
    },
    "errors": [
      {
        "message": "Could not find property with the provided address",
        "field": "address"
      }
    ]
  }
  ```
</ResponseExample>