Introduction

Welcome to the Snappr API! You can use our API to commission and manage photoshoots within the Snappr marketplace network. The API is available only to organizations using the Snappr enterprise Photography Portal. If you do not currently have a Photography Portal account and are interesting in setting one up, find out more here.

We have code examples in Shell. You can them in the panel on the right. We will have language bindings for JavaScript very soon.

Authentication

curl "/example-endpoint" \
  -H "Authorization: Bearer zkTvDUe5jJBJFcjc6ckwapEwax8Kbs7h3nv2SHXSgh5qGhHP22ggsu4fbdZgf25z"

Replace the example key above with your API key. This fake key is used in all of the following request examples.

Snappr uses API keys to allow access to the API. You can access or regenerate your API key from your Photography Portal GUI. Each user has a single unique active API key. Regenerating your API key will deactivate your previous key. Deleting a user will deactivate their API key.

An API key needs to be included in all API requests in a header of this format:

Authorization: Bearer api_key

You must replace api_key with your user API key.

Coverage

Get Coverage

Example request:

curl "https://api.snappr.co/coverage?latitude=34.0522&longitude=-118.2437&shoottype=event" \
  -H 'accept-version: 1.0.0' \
  -H "Authorization: Bearer zkTvDUe5jJBJFcjc6ckwapEwax8Kbs7h3nv2SHXSgh5qGhHP22ggsu4fbdZgf25z"

Example JSON response:

{
  "latitude": 34.0522,
  "longitude": -118.2437,
  "shoottype": "event",
  "coverage": false
}

This endpoint returns Snappr coverage status (boolean) for a given location and shoot type. Coverage status is independent of specific dates or times.

HTTP Request

GET https://api.snappr.co/coverage?latitude=:latitude&longitude=:longitude&shoottype=:shoottype

Query Parameters

Parameter	Type	Description	Required
`latitude`	Number	Latitude of the shoot location.	Yes
`longitude`	Number	Longitude of the shoot location.	Yes
`shoottype`	String	Name of the shoot type (see `Shoot types` endpoints), e.g. "event".	Yes

Availability

Get Availability

Example request:

curl "https://api.snappr.co/availability?latitude=34.0522&longitude=-118.2437&shoottype=event&duration=120&date=2018-12-01" \
  -H 'accept-version: 1.0.0' \
  -H "Authorization: Bearer zkTvDUe5jJBJFcjc6ckwapEwax8Kbs7h3nv2SHXSgh5qGhHP22ggsu4fbdZgf25z"

Example JSON response:

{
  "latitude": 34.0522,
  "longitude": -118.2437,
  "shoottype": "event",
  "duration": 120,
  "date": "2018-12-01",
  "timezone": "America/Los_Angeles",
  "available_times": [
    "2018-12-01T07:30:00Z",
    "2018-12-01T09:30:00Z",
    "2018-12-01T15:00:00Z",
    "2018-12-01T15:30:00Z"
  ]
}

This endpoint returns time availability (i.e. available shoot start times) for a combination of location, date, shoot type and duration.

HTTP Request

GET https://api.snappr.co/availability?latitude=:latitude&longitude=:longitude&shoottype=:shoottype&duration=:duration&date=:date

Query Parameters

Parameter	Type	Description	Required
`latitude`	Number	Latitude of the shoot location.	Yes
`longitude`	Number	Longitude of the shoot location.	Yes
`shoottype`	String	Name of the shoot type (see `Shoot types` endpoints), e.g. "event".	Yes
`duration`	Integer	Length of the shoot in minutes.	Yes
`date`	Date (ISO)	Date for which you want to check time availability.	Yes

Bookings

Create New Booking

Example request when start_at is provided:

curl "https://api.snappr.co/bookings" \
  -H "Authorization: Bearer zkTvDUe5jJBJFcjc6ckwapEwax8Kbs7h3nv2SHXSgh5qGhHP22ggsu4fbdZgf25z" \
  -H 'accept-version: 1.0.0' \
  -H "Content-Type: application/json" \
  --data-binary $'{
    "fields": {
      "latitude": 34.0522,
      "longitude": -118.2437,
      "shoottype": "event",
      "start_at": "2018-12-01T07:30:00Z",
      "duration": 120,
      "location_notes": "Location is Emerald Theatre - ring buzzer at main entrance on arrival",
      "style_notes": "Shots of as many members of crowd as possible; shallow depth of field where possible",
      "customer_firstname": "Mary",
      "customer_surname": "Smith",
      "customer_email": "test@snappr.co",
      "customer_mobilephone": "+14153339966",
      "customer_company": "Snappr Inc."
    }
  }'

Example JSON response:

{
  "uid": "0ccefa53-b346-4d3e-8dcb-79a914289928",
  "status": "paid",
  "credits": 249,
  "latitude": 34.0522,
  "longitude": -118.2437,
  "shoottype": "event",
  "start_at": "2018-12-01T07:30:00Z",
  "duration": 120,
  "location_notes": "Location is Emerald Theatre - ring buzzer at main entrance on arrival",
  "style_notes": "Shots of as many members of crowd as possible; shallow depth of field where possible",
  "customer_firstname": "Mary",
  "customer_surname": "Smith",
  "customer_email": "test@snappr.co",
  "customer_mobilephone": "+14153339966",
  "customer_company": "Snappr Inc.",
  "photographer_name": "Hollie B.",
  "created_at": "2018-09-01T09:12:00Z",
  "updated_at": "2018-09-01T09:12:00Z"
}

Example request when start_at is not provided (end-customer picked date and time):

curl "https://api.snappr.co/bookings" \
  -H "Authorization: Bearer zkTvDUe5jJBJFcjc6ckwapEwax8Kbs7h3nv2SHXSgh5qGhHP22ggsu4fbdZgf25z" \
  -H 'accept-version: 1.0.0' \
  -H "Content-Type: application/json" \
  --data-binary $'{
    "fields": {
      "latitude": 34.0522,
      "longitude": -118.2437,
      "shoottype": "event",
      "start_at": null,
      "duration": 120,
      "location_notes": "Location is Emerald Theatre - ring buzzer at main entrance on arrival",
      "style_notes": "Shots of as many members of crowd as possible; shallow depth of field where possible",
      "customer_firstname": "Mary",
      "customer_surname": "Smith",
      "customer_email": "test@snappr.co",
      "customer_mobilephone": "+14153339966",
      "customer_company": "Snappr Inc."
    }
  }'

Example JSON response:

{
  "uid": "0ccefa53-b346-4d3e-8dcb-79a914289928",
  "status": "paid_pending_schedule",
  "credits": 249,
  "latitude": 34.0522,
  "longitude": -118.2437,
  "shoottype": "event",
  "duration": 120,
  "location_notes": "Location is Emerald Theatre - ring buzzer at main entrance on arrival",
  "style_notes": "Shots of as many members of crowd as possible; shallow depth of field where possible",
  "customer_firstname": "Mary",
  "customer_surname": "Smith",
  "customer_email": "test@snappr.co",
  "customer_mobilephone": "+14153339966",
  "customer_company": "Snappr Inc.",
  "photographer_name": "Hollie B.",
  "created_at": "2018-09-01T09:12:00Z",
  "updated_at": "2018-09-01T09:12:00Z"
}

This endpoint creates a new photoshoot booking.

Broadly, there are two main ways to create a new photoshoot booking, and examples are provided for each:

Provide all shoot details including the start date and time for the shoot (start_at). With this option, Snappr will not seek any input on shoot details from your end-customer, they will simply be notified if the booking is placed successfully.
Provide all shoot details except the start date and time for the shoot (start_at set to null). This will trigger an automatic process to collect the start date and time from your end-customer using the contact details (email and/or mobile phone) provided. End-customers will be able to select from all available dates and times for the shoot location, using a Snappr UI.

HTTP Request

POST https://api.snappr.co/bookings

Request (Body) Parameters

Parameter	Type	Description	Required
`latitude`	Number	Latitude of the shoot location.	Yes
`longitude`	Number	Longitude of the shoot location.	Yes
`shoottype`	String	Name of the shoot type (see `Shoot types` endpoints), e.g. "event".	Yes
`start_at`	Datetime (ISO)	Start time of the shoot in UTC. If this is set to `null`, then Snappr will automatically seek this information from the end-customer.	Yes
`duration`	Integer	Length of the shoot in minutes.	Yes
`location_notes`	String	Details to help the photographer find the specific location and contact person at the time of the shoot.	No
`style_notes`	String	Instructions, stylistic preferences and other special requests.	No
`customer_firstname`	String	First name of your end-customer.	Yes
`customer_surname`	String	Last name of your end-customer.	No
`customer_email`	String (email)	Valid email address of your end-customer.	Yes
`customer_mobilephone`	String	Valid mobile phone number of your end-customer.	Yes
`customer_company`	String	Name of your end-customer's company.	No

If start_at is set to null the system assumes you want the end-customer to pick the start date and time.

Always check availability before trying to create a new booking with start_at defined. If you try to make a booking at for combination of location, date/time and shoot type for which there are no available photographers, you will receive a 400 error (see Errors section).

Get All Bookings

Example request:

curl "https://api.snappr.co/bookings" \
  -H "Authorization: Bearer zkTvDUe5jJBJFcjc6ckwapEwax8Kbs7h3nv2SHXSgh5qGhHP22ggsu4fbdZgf25z" \
  -H 'accept-version: 1.0.0'

Example JSON response:

{
  "results": [
    {
      "uid": "0ccefa53-b346-4d3e-8dcb-79a914289928",
      "status": "paid",
      "credits": 249,
      "latitude": 34.0522,
      "longitude": -118.2437,
      "shoottype": "event",
      "start_at": "2018-12-01T07:30:00Z",
      "duration": 120,
      "location_notes": "Location is Emerald Theatre - ring buzzer at main entrance on arrival",
      "style_notes": "Shots of as many members of crowd as possible; shallow depth of field where possible",
      "customer_firstname": "Mary",
      "customer_surname": "Smith",
      "customer_email": "test@snappr.co",
      "customer_mobilephone": "+14153339966",
      "customer_company": "Snappr Inc.",
      "photographer_name": "Hollie B.",
      "created_at": "2018-09-01T09:12:00Z",
      "updated_at": "2018-09-01T09:12:00Z"
    },
    {
      "uid": "48b095fd-7fc0-41dc-b632-9b032e0a65e6",
      "status": "paid",
      "credits": 349,
      "latitude": 34.1513,
      "longitude": -118.2439,
      "shoottype": "family",
      "start_at": "2018-12-01T07:30:00Z",
      "duration": 180,
      "location_notes": "Meet near the park entance",
      "style_notes": "Variety of group shots of the family with different backgrounds",
      "customer_firstname": "John",
      "customer_surname": "Smith",
      "customer_email": "testing@snappr.co",
      "customer_mobilephone": "+14153338822",
      "customer_company": null,
      "photographer_name": "Jamie C.",
      "created_at": "2018-09-01T08:34:00Z",
      "updated_at": "2018-09-01T08:34:00Z"
    }
  ],
  "count": 2,
  "limit": 100,
  "offset": 0,
  "total": 2
}

This endpoint retrieves all bookings.

HTTP Request

GET https://api.snappr.co/bookings?limit=:limit&offset=:offset

Query Parameters

Parameter	Type	Description	Required
`limit`	Integer	Maximum number of bookings to be returned (maximum of 100). Defaults to `100`.	No
`offset`	Integer	Offset used for pagination if there are more bookings than the limit (or more than 100 bookings if there is no limit). Defaults to `0`.	No

Get Single Booking

Example request:

curl "https://api.snappr.co/bookings/0ccefa53-b346-4d3e-8dcb-79a914289928" \
  -H "Authorization: Bearer zkTvDUe5jJBJFcjc6ckwapEwax8Kbs7h3nv2SHXSgh5qGhHP22ggsu4fbdZgf25z" \
  -H 'accept-version: 1.0.0'

Example JSON response:

{
  "uid": "0ccefa53-b346-4d3e-8dcb-79a914289928",
  "status": "paid",
  "credits": 249,
  "latitude": 34.0522,
  "longitude": -118.2437,
  "shoottype": "event",
  "start_at": "2018-12-01T07:30:00Z",
  "duration": 120,
  "location_notes": "Location is Emerald Theatre - ring buzzer at main entrance on arrival",
  "style_notes": "Shots of as many members of crowd as possible; shallow depth of field where possible",
  "customer_firstname": "Mary",
  "customer_surname": "Smith",
  "customer_email": "test@snappr.co",
  "customer_mobilephone": "+14153339966",
  "customer_company": "Snappr Inc.",
  "photographer_name": "Hollie B.",
  "created_at": "2018-09-01T09:12:00Z",
  "updated_at": "2018-09-01T09:12:00Z"
}

This endpoint retrieves a specific booking using the ID of the booking.

HTTP Request

GET https://api.snappr.co/bookings/:booking_uid

Request Parameters

Parameter	Type	Description	Required
`booking_uid`	String (UUID)	The identifier of the booking.	Yes

Images

Get All Images For a Booking

Example request:

curl "https://api.snappr.co/bookings/0ccefa53-b346-4d3e-8dcb-79a914289928/images" \
  -H "Authorization: Bearer zkTvDUe5jJBJFcjc6ckwapEwax8Kbs7h3nv2SHXSgh5qGhHP22ggsu4fbdZgf25z" \
  -H 'accept-version: 1.0.0'

Example JSON response:

{
  "results": [
    {
      "uid": "ed10cf86-97f9-4ce6-af6f-a01dfe891114",
      "file_name": "ZD 001.JPG",
      "url_original": "https://prod-us-media-snappr.s3.us-west-1.amazonaws.com/ed10cf86-97f9-4ce6-af6f-a01dfe891114?AWSAccessKeyId=AKIAIIR7FMZ7RANC45MA&Expires=1586478927&Signature=IqGcYjJZXM7%2FSX%2BoHQk4mccB3FA%3D",
      "url_thumb": "https://img.snappr.co/QlXCPwnEgV7P_RO4AJDLhOsq500=/fit-in/600x0/ed10cf86-97f9-4ce6-af6f-a01dfe891114"
    },
    {
      "uid": "ee9be5f8-84a8-4592-88a0-1781d0c39d0a",
      "file_name": "ZD 002.JPG",
      "url_original": "https://prod-us-media-snappr.s3.us-west-1.amazonaws.com/ee9be5f8-84a8-4592-88a0-1781d0c39d0a?AWSAccessKeyId=AKIAIIR7FMZ7RANC45MA&Expires=1586478927&Signature=E%2BPTBIqQOEgf0MctPRy6WXLIsBM%3D",
      "url_thumb": "https://img.snappr.co/rXtW9z6hGdDm3lebP9IPHGo9V5k=/fit-in/600x0/ee9be5f8-84a8-4592-88a0-1781d0c39d0a"
    },
    {
      "uid": "6b6eae3e-ebfb-4776-8a20-2b8087f76418",
      "file_name": "ZD 003.JPG",
      "url_original": "https://prod-us-media-snappr.s3.us-west-1.amazonaws.com/6b6eae3e-ebfb-4776-8a20-2b8087f76418?AWSAccessKeyId=AKIAIIR7FMZ7RANC45MA&Expires=1586478927&Signature=cqgRr6oJDYYMxkGm2M34MKDnArM%3D",
      "url_thumb": "https://img.snappr.co/gXk81aciTVokDvyi2NdWGNluhNg=/fit-in/600x0/6b6eae3e-ebfb-4776-8a20-2b8087f76418"
    }
  ],
  "count": 3,
  "limit": 1000,
  "offset": 0,
  "total": 3
}

This endpoint retrieves all the images of a specific booking.

HTTP Request

GET https://api.snappr.co/bookings/:booking_uid/images

Request Parameters

Parameter	Type	Description	Required
`booking_uid`	String (UUID)	The identifier of the booking.	Yes

Query Parameters

Parameter	Type	Description	Required
`limit`	Integer	Maximum number of images to be returned (maximum of 10000). Defaults to `1000`.	No
`offset`	Integer	Offset used for pagination if there are more images than the limit (or more than 1000 images if there is no limit). Defaults to `0`.	No

Shoot Types

Get All Shoot Types

Example request:

curl "https://api.snappr.co/shoottypes" \
  -H "Authorization: Bearer zkTvDUe5jJBJFcjc6ckwapEwax8Kbs7h3nv2SHXSgh5qGhHP22ggsu4fbdZgf25z" \
  -H 'accept-version: 1.0.0'

Example JSON response:

{
  "results": [
    {
      "name": "food",
      "display_name": "Food"
    },
    {
      "name": "real-estate",
      "display_name": "Real Estate"
    },
    ...
  ],
  "count": 10,
  "limit": 100,
  "offset": 0,
  "total": 10
}

This endpoint returns all available Snappr shoot types.

HTTP Request

GET https://api.snappr.co/shoottypes

Custom Webhooks

Example JSON payload sent to webhook URL as POST:

{
  "type": "update",
  "booking": {
    "uid": "0ccefa53-b346-4d3e-8dcb-79a914289928",
    "status": "paid",
    "credits": 249,
    "latitude": 34.0522,
    "longitude": -118.2437,
    "shoottype": "event",
    "start_at": "2018-12-01T07:30:00Z",
    "duration": 120,
    "location_notes": "Location is Emerald Theatre - ring buzzer at main entrance on arrival",
    "style_notes": "Shots of as many members of crowd as possible; shallow depth of field where possible",
    "customer_firstname": "Mary",
    "customer_surname": "Smith",
    "customer_email": "test@snappr.co",
    "customer_mobilephone": "+14153339966",
    "customer_company": "Snappr Inc.",
    "photographer_name": "Hollie B.",
    "created_at": "2018-09-01T09:12:00Z",
    "updated_at": "2018-09-01T09:12:00Z"
  }
}

You can set a custom webhook URL in the Snappr Photography Portal GUI. If the custom webhook URL is set, we will POST to that URL every time a booking is created or updated.

Setting URL

Click on the 'API' link in the top-right drop-down menu in your Photography Portal, or go to the following URL:

https://app.snappr.co/partner/your-slug/api

Replace your-slug with your company's custom Snappr slug.

Go to the 'Custom Webhook' section and click the 'Edit' button in the URL field. Type in the receiving URL of your choice, then click the 'Save' button. If you entered a valid URL, that endpoint will now start receiving all booking updates.

Errors

The Snappr API uses the following error codes:

Status	Name	Description
400	SyntaxError	Request body has incorrect formatting. Most likely invalid JSON.
400	InvalidAPIVersion	Requested an invalid API version.
400	UnsupportedVersion	Requested an API version that is unsupported by the requested route.
400	NotImplemented	Requested a feature that is not currently implemented.
400	ValidationError	Validation failure. See 'Problems' field in response.
400	Conflict	Request has a conflict with existing data.
400	NotAvailable	Requested resource is not available in your region or for the requested date/time.
400	NoCoverage	There is no coverage by Snappr on the requested `latitude`/`longitude` for the `shoottype`.
401	Unauthorized	Provided access token is invalid or does not have access to requested resource.
402	InsufficientCredits	The account does not have a sufficient credit balance to perform the request. Add more credits in the GUI.
404	NotFound	Requested resource not found.
429	RateLimit	The rate limit of the provided access_token has been reached. Please have your application respect the X-RateLimit-Remaining header that is included on API responses.
500	ServerError	There was an issue with our server. Try again later.
400	UnknownError	An error occurred that is not a server error and is not described here.