# Your First Upload

A batch upload is the entry point for all list-based verification. You create a batch by sending a TXT file to `POST /v1/batch`, which returns a `batch_uuid` you'll use for every subsequent operation.

<Note>
  You'll need a valid API key before uploading. If you haven't created one yet, see [Your First API Key](/quickstart/first-api-key).
</Note>

***

## Steps

<Steps>
  <Step title="Prepare your TXT file">
    Create a plain `.txt` file with **one email or phone number per line**, UTF-8 encoded. No headers, no commas, no extra formatting.

    <Tabs>
      <Tab title="Email list">
        ```
        alice@example.com
        bob@company.org
        carol@domain.net
        dave@webmail.io
        ```
      </Tab>

      <Tab title="Phone list (E.164)">
        ```
        +6591234567
        +447911123456
        +12125551234
        +33612345678
        ```
      </Tab>
    </Tabs>

    <Tip>
      Use E.164 format for phone numbers (`+[country code][number]`) to ensure accurate parsing. Numbers without a country code may be rejected or incorrectly routed.
    </Tip>
  </Step>

  <Step title="Choose a name and description">
    Every batch requires a **name** (1–255 characters). A description is optional (up to 2,048 characters) but helps you identify batches later.

    Good names: `Q2 Customer Import`, `Newsletter List April`, `Lead Gen Campaign - US`
  </Step>

  <Step title="Upload the file">
    Send a `multipart/form-data` POST request with your file and parameters:

    ```bash
    curl -X POST https://api.apexverify.com/v1/batch \
      -H "X-Api-Key: YOUR_API_KEY" \
      -F "file=@emails.txt" \
      -F "name=Q2 Customer Import" \
      -F "description=Quarterly CRM export for verification" \
      -F "type=email" \
      -F "target_country=US"
    ```

    **Required form fields:**

    | Field            | Type               | Description                          |
    | :--------------- | :----------------- | :----------------------------------- |
    | `file`           | binary             | Your `.txt` file                     |
    | `name`           | string             | Batch display name (max 255 chars)   |
    | `type`           | `email` \| `phone` | Verification type                    |
    | `target_country` | ISO2 string        | Country code (e.g. `US`, `SG`, `GB`) |

    **Optional fields:** `description`, `target_audience`, `target_market_industry`, `target_objective`, `use_account_cache`, `use_global_cache`. These can also be set or changed later via `PUT /v1/batch/{uuid}`.
  </Step>

  <Step title="Save your batch_uuid">
    On success, the API returns a `batch_uuid`. **Save this value** — it identifies your batch for all subsequent calls (parameters, parsing, launch, status, export, deletion).

    <Tabs>
      <Tab title="Success">
        ```json
        {
          "status": "ok",
          "batch_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "created_at": "2026-04-06T10:00:00Z"
        }
        ```
      </Tab>

      <Tab title="Parse error">
        ```json
        {
          "status": "parse_error"
        }
        ```

        The file was rejected during upload. Check that it is a valid UTF-8 `.txt` file with one entry per line.
      </Tab>

      <Tab title="Error">
        ```json
        {
          "status": "error"
        }
        ```

        An unexpected server error occurred. Retry the request or contact support if it persists.
      </Tab>
    </Tabs>
  </Step>
</Steps>

***

## What's Next?

With your `batch_uuid` in hand, the next step is to configure verification parameters, trigger parsing, and launch the job.

<CardGroup cols={2}>
  <Card title="Your First Verification" icon="fa-regular fa-square-check" href="/quickstart/first-verification">
    Walk through the complete lifecycle from upload to exported results.
  </Card>

  <Card title="API Verification Workflow" icon="fa-regular fa-arrows-spin" href="/tutorials/api-workflow">
    The full reference guide covering every API call in the batch verification lifecycle.
  </Card>
</CardGroup>