---
title: "Create a photoshoot booking"
method: POST
path: "/bookings"
tags: ["Bookings"]
---

# Create a photoshoot booking

`POST /bookings`

## Request

- Base URL: `https://api.snappr.com`
- URL: `https://api.snappr.com/bookings`
- Auth: HTTP bearer

Creates a photoshoot booking. There are two ways to create one:

1. Provide all details including `start_at`. The end-customer is notified once the booking is placed.
2. Set `start_at` to `null`. Snappr contacts the end-customer (email and/or mobile phone) to pick a
   date and time, and the response includes a `scheduling_url` they can use. `start_at` cannot be
   `null` when `creator_id` is set.

Provide either `latitude` and `longitude`, or `address`. If both are provided, only `latitude` and
`longitude` are used. Booking a time with no available photographer returns a `400` with code
`NotAvailable`; an account without enough credits gets `402` `InsufficientCredits`.

## Headers

- `accept-version` string

## Request body

- BookingCreate
  - `title` string: Custom shoot title.
  - `latitude` number: Latitude of the shoot location. Required together with `longitude` when `address` is not provided.
  - `longitude` number: Longitude of the shoot location. Required together with `latitude` when `address` is not provided.
  - `address` string: Google Maps–valid address of the shoot location. Required when `latitude` and `longitude` are not provided.
  - `shoottype` string, required: Shoot type `name` (see `listShootTypes`), e.g. `event`.
  - `start_at` string, date-time, nullable, required: Shoot start time in UTC. Must be present; set to `null` to have the end-customer pick the date and time.
  - `duration` integer, required: Shoot length in minutes.
  - `location_notes` string, nullable: Details to help the photographer find the location and contact person.
  - `style_notes` string, nullable: Instructions, stylistic preferences and special requests.
  - `customer_firstname` string, required
  - `customer_surname` string, nullable
  - `customer_email` string, email, required
  - `customer_mobilephone` string, required: End-customer's mobile phone number, e.g. `+14153339966`.
  - `customer_company` string, nullable
  - `internal_id` string, nullable: Your own identifier, for matching the booking with your data.
  - `creator_id` string, uuid, nullable: Assign the booking to this specific creator.
  - `tags` string[], nullable: Tags for finding and reporting on bookings in the Snappr portal. Each tag is lowercased, trimmed and truncated to 255 characters.

## Response `201`

Booking created.

- BookingCreated
  - `uid` string, uuid, required
  - `package_id` string, uuid, nullable: The Snappr package (product) the booking was placed on.
  - `title` string, nullable
  - `status` string, required: Booking status, e.g. `paid`, `paid_pending_schedule`, `completed`, `cancelled`.
  - `credits` integer, required: Credits charged for the booking.
  - `latitude` number, nullable
  - `longitude` number, nullable
  - `shoottype` string, nullable
  - `start_at` string, date-time, nullable
  - `duration` integer, nullable: Shoot length in minutes.
  - `location_notes` string, nullable
  - `style_notes` string, nullable
  - `customer_firstname` string, nullable
  - `customer_surname` string, nullable
  - `customer_email` string, nullable
  - `customer_mobilephone` string, nullable
  - `customer_company` string, nullable
  - `internal_id` string, nullable
  - `creator_name` string, nullable: Assigned photographer's first name and last initial.
  - `creator_id` string, uuid, nullable
  - `creator_profile_image_url` string, uri, nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `update_at` string, date-time: Misspelled alias of `updated_at`, kept for backwards compatibility.
  - `photographer_name` string, nullable: Old name for `creator_name`.
  - `scheduling_url` string, uri: Present when `start_at` was `null`. Link the end-customer uses to pick a date and time.
  - `bookingTags` string[]: The tags stored on the booking (normalised from the request's `tags`).

## Other responses

- `400`: The request was invalid, or could not be fulfilled (validation failure, no coverage, no availability, location outside your region).
- `401`: The API key is missing or invalid, or its user is not an admin of the account.
- `402`: The account does not have enough credits. Add credits in the Snappr portal.
- `429`: Rate limit exceeded (1,000 requests per minute per API key).
- `500`: Unexpected server error. Try again later.

---

[API](https://skmtc.dev/snappr/apis/snappr-api.md) - [All operations](https://skmtc.dev/snappr/apis/snappr-api/llms.txt) - [OpenAPI document](https://skmtc.dev/snappr/apis/snappr-api/revisions/dd0648363a82?raw)