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

# Automated Import API Reference

> Technical specifications and examples for the Automated Import API

This page provides technical specifications for implementing automated data imports via the Broadstripes API.

## API Endpoints

| Environment    | URL                                                     |
| -------------- | ------------------------------------------------------- |
| **Production** | `https://crm.broadstripes.com/api/automated_imports`    |
| **Staging**    | `https://groton.broadstripes.com/api/automated_imports` |

## HTTP Specifications

### Request Method

**POST** - All automated import requests must use the POST method

### Authentication

Include your authentication token in the HTTP header:

```
x-broadstripes-authentication-token: your-authentication-token-here
```

### Content Types

#### For CSV Data

* **Content-Type**: `multipart/form-data`
* **Content-Disposition**: `form-data; name="automated_import[source_document]"; filename="your-file.csv"`

#### For JSON Data

* **Content-Type**: `application/json`
* **Content-Disposition**: Not required (or use `application/json`)

## Request Examples

### CSV Import with curl

```bash theme={null}
curl https://crm.broadstripes.com/api/automated_imports \
  -F 'automated_import[source_document]=@/path/to/your-file.csv' \
  -H "x-broadstripes-authentication-token: your-authentication-token" \
  -X POST
```

### JSON Import with curl

```bash theme={null}
curl https://crm.broadstripes.com/api/automated_imports \
  --json '[{"first_name": "John", "last_name": "Smith", "employer": "Acme Inc"}]' \
  -H "x-broadstripes-authentication-token: your-authentication-token" \
  -X POST
```

## Response Format

### Success Response

**Status Code**: `200`

**Response Structure**:

```json theme={null}
{
  "automated_import": {
    "id": "unique-import-id",
    "status": "scheduled",
    "filename": "your-file.csv" // or NULL for JSON imports
  }
}
```

### Error Responses

The API will return appropriate HTTP status codes and error messages for:

* Invalid authentication tokens
* Malformed data
* Configuration issues
* Server errors

## Code Examples

### Ruby CSV Import

```ruby theme={null}
require 'uri'
require 'net/http'

file_path = '/path/to/your-file.csv'
uri = URI.parse('https://crm.broadstripes.com/api/automated_imports')
boundary = "AaB03x"

post_body = []
post_body << "--#{boundary}\r\n"
post_body << "Content-Disposition: form-data; name=\"automated_import[source_document]\"; "
post_body << "filename=\"#{File.basename(file_path)}\"\r\n"
post_body << "Content-Type: text/csv\r\n"
post_body << "Content-Transfer-Encoding: binary\r\n"
post_body << "\r\n"
post_body << File.read(file_path, :mode => 'rb')
post_body << "\r\n--#{boundary}--\r\n"

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.read_timeout = 600

request = Net::HTTP::Post.new(uri.request_uri)
request.body = post_body.join
request['Content-Type'] = "multipart/form-data, boundary=#{boundary}"
request['x-broadstripes-authentication-token'] = "your-authentication-token"

response = http.request(request)
```

### Ruby JSON Import

```ruby theme={null}
require 'uri'
require 'net/http'
require 'json'

# Array of records to import
post_json = [
  {
    "first_name" => "John",
    "last_name" => "Smith",
    "employer" => "Acme Inc",
    "department" => "Assembly"
  }
].to_json

uri = URI.parse('https://crm.broadstripes.com/api/automated_imports')

json_headers = {
  "Content-Type" => "application/json",
  "x-broadstripes-authentication-token" => "your-authentication-token"
}

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.read_timeout = 600

response = http.post(uri.path, post_json, json_headers)
```

## Data Format Requirements

### CSV Format

* **Headers Required**: First row must contain field names
* **Field Names**: Must match Broadstripes field names exactly
* **Encoding**: UTF-8 recommended
* **File Size**: No explicit limit, but consider timeout settings

### JSON Format

* **Structure**: Array of objects, where each object represents one record
* **Field Names**: Must match Broadstripes field names exactly
* **Data Types**: Use appropriate JSON data types (strings, numbers, booleans)

### Field Name Examples

Common field names that map to Broadstripes:

* `first_name`, `last_name`
* `employer`, `department`
* `address1`, `address2`, `city`, `state`, `zip`
* `phone`, `email`
* Custom field names (must match exactly as configured in your project)

## ZIP File Support (CSV Only)

For CSV imports, you can send a ZIP file containing multiple CSV files with specific names:

1. `people_modifications.csv`
2. `address_modifications.csv`
3. `phone_modifications.csv`
4. `employment_modifications.csv`

Files are processed in the order listed above.

## Best Practices

### Performance

* **Batch Size**: Consider breaking large datasets into smaller batches
* **Timeout**: Set appropriate timeout values (example shows 600 seconds)
* **Retry Logic**: Implement retry mechanisms for failed requests

### Security

* **HTTPS Only**: Always use HTTPS endpoints
* **Token Security**: Keep authentication tokens secure and rotate them regularly
* **Data Validation**: Validate data before sending to reduce errors

### Error Handling

* **Check Response Codes**: Always verify the HTTP response status
* **Parse Error Messages**: Handle and log API error responses appropriately
* **Monitor Import Status**: Use the web interface to monitor import progress and results

## Rate Limits

While not explicitly documented, consider implementing reasonable delays between requests to avoid overwhelming the API. Monitor your import success rates and adjust timing as needed.

## Testing

Always test your integration against the staging environment before using production:

* Use the staging URL for initial development
* Test with small datasets first
* Verify data appears correctly in the Broadstripes interface
* Confirm your authentication tokens work properly