API for agencies and sites

Updated

Finishot sends photos to any API as multipart/form-data. The format below works without changes to the app. The photographer sets the address, authentication and field names in Finishot: Agencies → the agency → Delivery → API (HTTP).

Request

POST https://your-site.example/api/photos
Authorization: Bearer <token>
Content-Type: multipart/form-data
Field Type Content
file JPEG file Full-resolution photo with IPTC and XMP metadata written in
metadata text (JSON) The same data in a convenient form, described below
title text Title
caption text Caption
keywords text Comma-separated keywords

Field names can be changed and extra fields added, e.g. gallery=15 or event={event}. Instead of a Bearer token you can use your own header, e.g. X-API-Key.

The metadata field

{
  "app": "Finishot 1.0.0",
  "agency": "Your site (API)",
  "fileName": "IMG_4812.jpg",
  "capturedAt": "2026-01-28T21:02:12-05:00",
  "width": 6000,
  "height": 4000,
  "event": { "name": "NBA", "date": "2026-01-28", "sport": "basketball", "venue": "Rocket Arena", "city": "Cleveland", "country": "USA", "countryCode": "USA" },
  "people": [
    { "name": "Luka Dončić", "first": "Luka", "last": "Dončić", "number": "77", "team": "Los Angeles Lakers" }
  ],
  "iptc": {
    "title": "…", "description": "…", "keywords": ["NBA", "basketball"],
    "personInImage": ["Luka Dončić"], "creator": ["First Last"], "credit": "First Last/Your site",
    "dateCreated": "2026-01-28T21:02:12-05:00"
  }
}

Response

  • Success: a 2xx code, ideally 201 with JSON { "id": "2687", "url": "https://your-site.example/photo/2687" }. Finishot stores the url or id in the delivery log.
  • Error: a 4xx or 5xx code with a short message, e.g. 401 {"error":"invalid token"}. Finishot shows it next to the photo and lets the photographer retry.

Server notes

  • Request size: at least 50 MB (PHP: upload_max_filesize, post_max_size; nginx: client_max_body_size).
  • Connection test in the app sends a GET to the same address with the token:
    • 200 or 405 means the server answers;
    • 401 or 403 means a wrong token;
    • 404 means a wrong address.
  • Re-sending the same file after a caption fix should update the photo, not create a duplicate. Match it by fileName and capturedAt.
  • Encoding: all fields are UTF-8.

Questions about integration? Get in touch.