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

# REST File API

> Submit spreadsheet files to CSVbox programmatically with the REST File API.

The File API lets you accept spreadsheet files programmatically, as an alternative to users uploading files manually through the CSVbox importer. Files submitted through the REST File API are pushed to the data destination set up in the CSVbox dashboard.

## Simple File API request

```javascript theme={null}
curl --location --request POST 'https://api.csvbox.io/1.1/file' \
--header 'x-csvbox-api-key: CSBxRLHgIZv3bqMlrJiVKXhKwtcHSv' \
--header 'Content-Type: application/json' \
--data-raw '{
    "import": {
        "public_file_url": "https://some-domain.com/file/3434as.csv",
        "sheet_license_key": "jhkjsahjkhkjhkjhkjasdasd",
        "user": {
            "user_id": "1a2b3c4d5e6f"           
        },
         "options": {           
            "has_header": 1
        }    
    }
}'
```

After the data is pushed to the destination, the [import complete webhook](/getting-started/3-receive-data#import-complete-webhook) can be triggered as configured in the sheet settings.

<Warning>
  Spreadsheet data submitted through the File API is not [validated](/dashboard-settings/validations) against the rules configured in the sheet settings. The importer attempts to push the data directly to the destination in raw form.
</Warning>

## Authentication

All REST File API queries require a valid API key. You can find the API key on the **Accounts** page in the CSVbox dashboard.

Include your API key as an `x-csvbox-api-key` header on all API queries.

## Endpoint

Submits a spreadsheet file.

```text theme={null}
POST https://api.csvbox.io/1.1/file
```

### Headers

| Name | Type | Required | Description |
| - | - | - | - |
| `x-csvbox-api-key` | String | Yes | API Key |
| `content-type` | String | Yes | `application/json` |

### Request body

| Name | Type | Required | Description |
| - | - | - | - |
| `import.public_file_url` | String | Yes | The public URL of the spreadsheet that is to be submitted. |
| `import.file_sheet_name` | String | No | Worksheet name in case of a file having multiple tabs. |
| `import.sheet_license_key` | String | Yes | Sheet license key |
| `import` | Object | Yes | Import file data |
| `import.user` | Object | No | Object [referencing the user](/getting-started/2-install-code#referencing-the-user) |
| `import.options` | Object | No | Object [referencing the import options](/advanced-installation/rest-file-api#options) |
| `import.dynamic_columns` | Object | No | Object [referencing dynamic columns](/advanced-installation/dynamic-columns) |

<Warning>
  The columns in the file must be in the same order as configured in the sheet template, and the column names must match exactly. To have the importer auto-map the columns, set `options.auto_map` to `true`.
</Warning>

### Response

**200 OK**: File submitted.

```javascript 200 OK theme={null}
HTTP/1.1 200 OK
{
  "import_id": 79418895,
  "license_key":"jhkjsahjkhkjhkjhkjasdasd",
  "sheet_id": 575,
  "sheet_name": "Products Import",
  "destination_type": "webhook",
  "import_starttime": 87987897897,
  "custom_fields": {
    "user_id": "1a2b3c4d5e6f",
    "team_id": "sales2",
    "permissionLevel": "admin"
  },
  "options": {
    "max_rows": 150,
    "has_header": 1,
    "auto_map": true
  },
  "dynamic_columns": [
     {
      "column_name": "qualification",
      "display_label": "Highest Qualification",
      "info_hint": "What is your highest educational degree",
      "matching_keywords": "degree, education",
      "type": "text",
      "validators": {
        "min_length": 2,
        "max_length": 50
      },
      "required": true
    },
    {
      "column_name": "experience",
      "display_label": "Work Experience",
      "info_hint": "Years of work experience",
      "matching_keywords": "",
      "type": "number",
      "validators": {
        "min_value": 0,
        "max_value": 100
      },
      "required": false
    }
  ]
}
```

### Example request

<CodeGroup>
  ```javascript cURL theme={null}
  curl --location --request POST 'https://api.csvbox.io/1.1/file' \
  --header 'x-csvbox-api-key: CSBxRLHgIZv3bqMlrJiVKXhKwtcHSv' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "import": {
          "public_file_url": "https://some-domain.com/admin/download-csv/UXOR2MphpEu2sSAIISpY7AKmOIzAKygLNy8eviEr",
          "sheet_license_key": "jhkjsahjkhkjhkjhkjasdasd",
          "user": {
              "user_id": "1a2b3c4d5e6f",
              "team_id": "sales2",
              "permissionLevel": "admin"
          },
          "options": {
              "max_rows": 150,
              "has_header": 1,
              "auto_map": true
          },
          "dynamic_columns": [
              {
                  "column_name": "qualification",
                  "display_label": "HighestQualification",
                  "info_hint": "Whatisyourhighesteducationaldegree",
                  "matching_keywords": "degree,   education",
                  "type": "text",
                  "validators": {
                      "min_length": 2,
                      "max_length": 50
                  },
                  "required": true
              },
              {
                  "column_name": "experience",
                  "display_label": "WorkExperience",
                  "info_hint": "Yearsofworkexperience",
                  "matching_keywords": "",
                  "type": "number",
                  "validators": {
                      "min_value": 0,
                      "max_value": 100
                  },
                  "required": false
              }
          ]
      }
  }'
  ```

  ```javascript jQuery theme={null}
  var settings = {
    "url": "https://api.csvbox.io/1.1/file",
    "method": "POST",
    "timeout": 0,
    "headers": {
      "x-csvbox-api-key": "CSBxRLHgIZv3bqMlrJiVKXhKwtcHSv",
      "Content-Type": "application/json"
    },
    "data": "{\r\n    \"import\": {\r\n        \"public_file_url\": \"https://some-domain.com/admin/download-csv/UXOR2MphpEu2sSAIISpY7AKmOIzAKygLNy8eviEr\",\r\n        \"sheet_license_key\": \"jhkjsahjkhkjhkjhkjasdasd\",\r\n        \"user\": {\r\n            \"user_id\": \"1a2b3c4d5e6f\",\r\n            \"team_id\": \"sales2\",\r\n            \"permissionLevel\": \"admin\"\r\n        },\r\n        \"options\": {\r\n            \"max_rows\": 150,\r\n            \"has_header\": \"1\"\r\n        },\r\n        \"dynamic_columns\": [\r\n            {\r\n                \"column_name\": \"qualification\",\r\n                \"display_label\": \"HighestQualification\",\r\n                \"info_hint\": \"Whatisyourhighesteducationaldegree\",\r\n                \"matching_keywords\": \"degree,   education\",\r\n                \"type\": \"text\",\r\n                \"validators\": {\r\n                    \"min_length\": 2,\r\n                    \"max_length\": 50\r\n                },\r\n                \"required\": true\r\n            },\r\n            {\r\n                \"column_name\": \"experience\",\r\n                \"display_label\": \"WorkExperience\",\r\n                \"info_hint\": \"Yearsofworkexperience\",\r\n                \"matching_keywords\": \"\",\r\n                \"type\": \"number\",\r\n                \"validators\": {\r\n                    \"min_value\": 0,\r\n                    \"max_value\": 100\r\n                },\r\n                \"required\": false\r\n            }\r\n        ]\r\n    }\r\n}",
  };

  $.ajax(settings).done(function (response) {
    console.log(response);
  });
  ```

  ```php PHP theme={null}
  <?php

  $curl = curl_init();

  curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://api.csvbox.io/1.1/file',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS =>'{
      "import": {
          "public_file_url": "https://some-domain.com/admin/download-csv/UXOR2MphpEu2sSAIISpY7AKmOIzAKygLNy8eviEr",
          "sheet_license_key": "jhkjsahjkhkjhkjhkjasdasd",
          "user": {
              "user_id": "1a2b3c4d5e6f",
              "team_id": "sales2",
              "permissionLevel": "admin"
          },
          "options": {
              "max_rows": 150,
              "has_header": 1
          },
          "dynamic_columns": [
              {
                  "column_name": "qualification",
                  "display_label": "HighestQualification",
                  "info_hint": "Whatisyourhighesteducationaldegree",
                  "matching_keywords": "degree,   education",
                  "type": "text",
                  "validators": {
                      "min_length": 2,
                      "max_length": 50
                  },
                  "required": true
              },
              {
                  "column_name": "experience",
                  "display_label": "WorkExperience",
                  "info_hint": "Yearsofworkexperience",
                  "matching_keywords": "",
                  "type": "number",
                  "validators": {
                      "min_value": 0,
                      "max_value": 100
                  },
                  "required": false
              }
          ]
      }
  }',
    CURLOPT_HTTPHEADER => array(
      'x-csvbox-api-key: CSBxRLHgIZv3bqMlrJiVKXhKwtcHSv',
      'Content-Type: application/json'
    ),
  ));

  $response = curl_exec($curl);

  curl_close($curl);
  echo $response;
  ```

  ```javascript NodeJS theme={null}
  var axios = require('axios');
  var data = '{\r\n    "import": {\r\n        "public_file_url": "https://some-domain.com/admin/download-csv/UXOR2MphpEu2sSAIISpY7AKmOIzAKygLNy8eviEr",\r\n        "sheet_license_key": "jhkjsahjkhkjhkjhkjasdasd",\r\n        "user": {\r\n            "user_id": "1a2b3c4d5e6f",\r\n            "team_id": "sales2",\r\n            "permissionLevel": "admin"\r\n        },\r\n        "options": {\r\n            "max_rows": 150,\r\n            "has_header": "1"\r\n        },\r\n        "dynamic_columns": [\r\n            {\r\n                "column_name": "qualification",\r\n                "display_label": "HighestQualification",\r\n                "info_hint": "Whatisyourhighesteducationaldegree",\r\n                "matching_keywords": "degree,   education",\r\n                "type": "text",\r\n                "validators": {\r\n                    "min_length": 2,\r\n                    "max_length": 50\r\n                },\r\n                "required": true\r\n            },\r\n            {\r\n                "column_name": "experience",\r\n                "display_label": "WorkExperience",\r\n                "info_hint": "Yearsofworkexperience",\r\n                "matching_keywords": "",\r\n                "type": "number",\r\n                "validators": {\r\n                    "min_value": 0,\r\n                    "max_value": 100\r\n                },\r\n                "required": false\r\n            }\r\n        ]\r\n    }\r\n}';

  var config = {
    method: 'post',
    url: 'https://api.csvbox.io/1.1/file',
    headers: { 
      'x-csvbox-api-key': 'CSBxRLHgIZv3bqMlrJiVKXhKwtcHSv', 
      'Content-Type': 'application/json'
    },
    data : data
  };

  axios(config)
  .then(function (response) {
    console.log(JSON.stringify(response.data));
  })
  .catch(function (error) {
    console.log(error);
  });
  ```
</CodeGroup>

## Direct file upload

As an alternative to providing a public file URL, you can upload the file contents directly. Instead of `import.public_file_url`, use the following body parameter.

### Request body

| Name | Type | Required | Description |
| - | - | - | - |
| `import.file` | String | Yes | The contents of the file to be imported. |

<Note>
  Send the file with the `multipart/form-data` content type.
</Note>

### Example request

```javascript cURL theme={null}
curl --location --request POST 'https://api.csvbox.io/1.1/file' \
--header 'x-csvbox-api-key: CSBxRLHgIZv3bqMlrJiVKXhKwtcHSv' \
--header 'Content-Type: multipart/form-data' \
-F 'import={
        "sheet_license_key": "jhkjsahjkhkjhkjhkjasdasd",
        "user": {
            "user_id": "1a2b3c4d5e6f"           
        },
         "options": {           
             "max_rows": 150,
             "has_header": 1
        }
    }' \
-F 'file=@/path/to/your/file.csv'
```

## Rate limits

The REST File API supports a limit of 30 requests per minute. This allotment replenishes at a rate of 2 requests per second.

Past the limit, the API returns a `429 Too Many Requests` error.

All REST API responses include the `x-csvbox-file-api-call-limit` header, which shows how many requests the client has made and the total number allowed per minute.

A `429` response also includes a `retry-after` header with the number of seconds to wait before retrying your query.

## Status and error codes

All API queries return HTTP status codes that tell you more about the response.

### 401 Unauthorized

The client doesn't have the correct authentication credentials.

```
HTTP/1.1 401 Unauthorized
{
    "errors": "[API] Invalid API key or access token."
}
```

### 402 Import Limit Reached

The monthly import limit for the account plan is reached. Upgrade the plan to increase the import limit.

```
HTTP/1.1 402 Import Limit Reached
{
    "errors": "The account has exceeded the import limit."
}
```

### 403 Forbidden

The server is refusing to respond. This is typically caused by the File API being disabled.

```
HTTP/1.1 403 Access Denied
{
    "errors": "User does not have access."
}
```

### 404 Not Found

The referenced sheet was not found.

```
HTTP/1.1 404 Not Found
{
    "errors": "Sheet not found."
}
```

### 422 Unprocessable File

The request body contains file errors. Typical causes are an incorrect file path, invalid file permissions, an incorrect file format, a corrupt file, or a file size that's too large.

```
HTTP/1.1 422 Unprocessable File
{
    "errors": "Invalid file format."
}
```

### 429 Too Many Requests

The client has exceeded the [rate limit](/advanced-installation/rest-file-api#rate-limits).

```
HTTP/1.1 429 Too Many Requests
{
    "errors": "API Rate limit reached. Reduce request rates to resume uninterrupted service."
}
```

### 5xx errors

An internal error occurred in CSVbox. Report such errors to our team.

```
HTTP/1.1 500 Internal Server Error
{
    "errors": "An unexpected error occurred."
}
```

## Options

The following additional configuration options are available with the File API.

### max\_rows

* **Type**: Integer
* **Default**: Null
* **Description**: The maximum number of rows to import.

### has\_header

* **Type**: Boolean
* **Default**: `0`
* **Description**: Specify whether the file contains a header row. Acceptable values are `0` (no header) and `1` (has a header row).

### auto\_map

* **Type**: Boolean
* **Default**: `false`
* **Description**: Enable automatic column mapping in cases where an exact match is not found.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.