## File Upload Using GraphQL and `curl`

### Overview

This guide explains how to upload a file using a GraphQL mutation via `curl`. You will need to structure your `curl` request to include the GraphQL query, the file mapping, and the file itself in the form-data.

### Steps to Perform a File Upload

1. **Set Up the GraphQL Mutation**  
   Your GraphQL mutation should look like this:
   
   ```graphql
   mutation singleUpload($file: Upload!) {
        singleUpload(
          file: $file,
          entity_id: "your_entity_id", // or representative_id
          file_enum: front_drivers_license
        ) {
          filename
        }
   }
   ```

2. **Prepare the `operations` Parameter**  
   The `operations` parameter includes the GraphQL query and the variables. It should be a JSON string. Here’s an example:
   
   ```json
   {
        "query": "
          mutation singleUpload($file: Upload!) {
            singleUpload(
              file: $file,
              entity_id: \"your_entity_id\", // or representative_id
              file_enum: front_drivers_license
            ) {
              filename
            }
          }
        ",
        "variables": {
          "file": null
        }
   }
   ```

3. **Prepare the `map` Parameter**  
   The `map` parameter maps the file in the form data to the GraphQL variable. It should be a JSON string. Here’s an example:
   
   ```json
   {
        "0": ["variables.file"]
   }
   ```

4. **Include the File in the Form-Data**  
   The file should be included in the form-data with a key that matches the mapping in the `map` parameter. Here’s how you can reference the file in the form-data:
   
   ```plaintext
   0=@/path/to/your/file.txt
   ```

5. **Construct the `curl` Command**  
   Combine all the above elements into a single `curl` command. Replace placeholders with actual values:
   
   ```shell
   curl -X POST https://your-graphql-endpoint.com/graphql \
        -H "apollo-require-preflight: true" \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
        -F 'operations={
          "query": "
            mutation singleUpload($file: Upload!) {
              singleUpload(
                file: $file,
                entity_id: \"your_entity_id\", // or representative_id
                file_enum: front_drivers_license
              ) {
                filename
              }
            }
          ",
          "variables": {
            "file": null
          }
        }' \
        -F 'map={
          "0": ["variables.file"]
        }' \
        -F "0=@/path/to/your/file.txt"
   ```

### Example Explanation

- **Endpoint URL**: Replace `https://your-graphql-endpoint.com/graphql` with your actual GraphQL endpoint.
- **Authorization Header**: Replace `YOUR_ACCESS_TOKEN` with your actual token.
- **File Path**: Replace `/path/to/your/file.txt` with the path to the file you want to upload.
- **Entity ID**: Replace `your_entity_id` with the actual entity or representative ID required by your mutation.

### Example Command

Here's an example `curl` command with placeholders replaced:

```shell
curl -X POST https://api.example.com/graphql \
  -H "apollo-require-preflight: true" \
  -H "Authorization: Bearer your-access-token" \
  -F 'operations={
    "query": "
      mutation singleUpload($file: Upload!) {
        singleUpload(
          file: $file,
          entity_id: \"12345\", // or representative_id
          file_enum: front_drivers_license
        ) {
          filename
        }
      }
    ",
    "variables": {
      "file": null
    }
  }' \
  -F 'map={
    "0": ["variables.file"]
  }' \
  -F "0=@/path/to/your/file.txt"
```

### Notes

- Ensure the file path is correct and accessible.
- The `Authorization` header must contain a valid token.
- The `operations` and `map` parameters must be properly formatted JSON strings.

By following these steps, you can successfully upload a file using a GraphQL mutation with `curl`. If you encounter any issues, check the structure of your `operations` and `map` parameters, and ensure your file path is correct.