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
2xxcode, ideally201with JSON{ "id": "2687", "url": "https://your-site.example/photo/2687" }. Finishot stores theurloridin the delivery log. - Error: a
4xxor5xxcode 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
GETto the same address with the token:200or405means the server answers;401or403means a wrong token;404means a wrong address.
- Re-sending the same file after a caption fix should update the photo, not create a duplicate. Match it by
fileNameandcapturedAt. - Encoding: all fields are UTF-8.
Questions about integration? Get in touch.