Import Boat

POST/import/boat

Import a new boat listing in a single API call. Handles creating the boat, storing image URLs, linking amenities, and auto-matching to a marina location.

Authentication

Requires API key in the X-API-Key header.

Owner API key (cb_live_*): Boat is created under your company automatically. No need to specify owner fields.
Admin API key: Requires owner_id or owner_email in the request body to identify who the boat belongs to.

X-API-Key: cb_live_your_api_key_here

Request Body

Required Fields

Field	Type	Description
`title`	string	Boat name/title
`boat_type`	string	One of: `yacht`, `catamaran`, `sailboat`, `motorboat`, `rib`, `other`
`capacity`	integer	Maximum guests (must be at least 1)

Optional Fields

Field	Type	Default	Description
`description`	string		Full description (supports markdown)
`price_per_day`	number		Daily rate
`length_ft`	number		Length overall (LOA) in feet. Values outside the plausible hull range (~6.5–350 ft) are stored as no length rather than as sent — only boats priced from a connected platform take their length from the model catalogue.
`year`	integer		Year built
`cabins`	integer		Number of cabins
`berths`	integer		Number of berths
`toilets`	integer		Number of toilets
`model`	string		Boat model name
`manufacturer_name`	string		Manufacturer name (looked up or auto-created)
`rental_type`	string	`bareboat`	`bareboat`, `skippered`, or `no_licence_needed`
`fuel_included`	boolean	false	Whether fuel is included
`security_deposit`	number		Security deposit amount
`instant_book`	boolean	false	Allow instant booking
`is_published`	boolean	false	Whether the listing is visible to guests

Location Fields

The endpoint auto-matches to an existing marina by coordinates (within ~1km) or by location name. If coordinates are provided but no match is found, a new location is created.

Field	Type	Description
`location_city`	string	City where boat is based
`location_state`	string	State/country, stored as the location's country when a new marina is created
`location_address`	string	Full address or marina name (used for location name matching)
`latitude`	number	GPS latitude
`longitude`	number	GPS longitude

Deduplication Fields

When both fields are provided, the endpoint checks for existing imports to prevent duplicates.

Field	Type	Description
`import_source`	string	Platform name (e.g. `boataround`)
`import_source_id`	string	Unique ID on that platform

Owner Identification (admin API key only)

Field	Type	Description
`owner_id`	string	User UUID
`owner_email`	string	Owner's email (creates user + company if not found)
`owner_name`	string	Owner's display name (used when creating new user)
`company_id`	string	Assign to a specific company (overrides auto-detection)

Images

Array of image URLs or image objects. The first image is set as primary unless specified otherwise.

{
  "images": [
    "https://example.com/image1.jpg",
    { "url": "https://example.com/image2.jpg", "is_primary": true }
  ],
  "download_images": true
}

Field	Type	Default	Description
`images`	array		Image URLs (strings) or objects with `url` and optional `is_primary`
`download_images`	boolean	false	Download images to server storage instead of keeping source URLs

Amenities

Array of amenity names (strings). Matched case-insensitively against standard amenities. Unmatched names are saved as custom amenities.

{
  "amenities": ["WiFi", "Air Conditioning", "Snorkeling Equipment"]
}

Request

curl -X POST https://charter.boats/api/import/boat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cb_live_your_api_key" \
  -d '{
    "title": "BALI Catspace - Luxury Catamaran",
    "description": "Beautiful 40ft catamaran with 4 cabins.",
    "boat_type": "catamaran",
    "capacity": 8,
    "price_per_day": 850,
    "length_ft": 40,
    "year": 2023,
    "location_city": "Lefkada",
    "location_state": "Greece",
    "latitude": 38.8336,
    "longitude": 20.7066,
    "manufacturer_name": "Bali Catamarans",
    "rental_type": "bareboat",
    "images": [
      { "url": "https://example.com/exterior.jpg", "is_primary": true },
      "https://example.com/interior.jpg"
    ],
    "amenities": ["WiFi", "Air Conditioning", "GPS/Navigation"]
  }'

Response

The boat object is the full boat record (every column on the boats row) plus company, manufacturer, images, and flattened amenities. Only the most relevant fields are shown below.

{
  "success": true,
  "duplicate": false,
  "boat": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "bali-catspace-luxury-catamaran",
    "title": "BALI Catspace - Luxury Catamaran",
    "boat_type": "catamaran",
    "capacity": 8,
    "length_ft": 40,
    "year": 2023,
    "price_per_day": 850,
    "instant_book": false,
    "rental_type": "bareboat",
    "is_active": true,
    "is_published": false,
    "company": {
      "id": "company-uuid",
      "name": "Sail Greece",
      "slug": "sail-greece"
    },
    "manufacturer": {
      "id": "mfr-uuid",
      "name": "Bali Catamarans",
      "slug": "bali-catamarans"
    },
    "images": [
      {
        "id": "img-uuid",
        "boat_id": "550e8400-e29b-41d4-a716-446655440000",
        "url": "https://example.com/exterior.jpg",
        "storage_path": null,
        "is_primary": true,
        "sort_order": 0
      }
    ],
    "amenities": [
      { "id": "amenity-uuid", "name": "WiFi", "category": "entertainment" }
    ]
  },
  "images_uploaded": 2,
  "images_downloaded": 0,
  "amenities_added": 3,
  "view_url": "https://charter.boats/boats/bali-catspace-luxury-catamaran"
}

Response Fields

Field	Type	Description
`success`	boolean	Whether the import succeeded
`duplicate`	boolean	`true` if an existing boat was returned (same `import_source` + `import_source_id` under the same company)
`boat`	object	Created (or existing) boat with company, manufacturer, images, and amenities
`images_uploaded`	integer	Number of image records created
`images_downloaded`	integer	Number of images downloaded to storage (when `download_images: true`)
`amenities_added`	integer	Number of standard amenities matched and linked (unmatched names are ignored)
`view_url`	string	Public URL to view the listing

Deduplication Behavior

When import_source and import_source_id are both provided:

Same company: Returns the existing boat with duplicate: true
Different company: Returns 409 Conflict

Errors

Status	Message
`400`	title is required
`400`	boat_type is required
`400`	boat_type must be one of: yacht, catamaran, sailboat, motorboat, rib, other
`400`	capacity is required and must be >= 1
`400`	rental_type must be one of: bareboat, skippered, no_licence_needed
`400`	Owner identification required: provide owner_id or owner_email
`401`	API key required. Include X-API-Key header.
`401`	Invalid API key
`409`	This boat has already been imported by another company

Import Boat

On this page