Ingest a batch of camera-roll metadata

Send photo metadata only, never image bytes. FanFeed matches each item against venue and event data using its coordinates and capture time, and returns the matches inline in the response for that batch.

There is no webhook and nothing to poll: each batch’s response is the result for that batch. Drive your progress UI from batch completions.

Send 50–200 items per request. Items without coordinates or a capture time cannot be matched and are returned in rejected; filter them out client-side to save the round trip.

Re-sending a batch is safe. Photos that matched upsert on your asset id and never produce a second entry; photos that matched nothing are not retained, so re-sending one costs a re-evaluation rather than a duplicate. Either way the result is the same, so overlapping your scan window slightly is the right call.

FanFeed records the sync high-water mark per user; last_sync_at comes back on every response and is also available on the stats endpoint.

POST /users/{user_id}/media

Ingest a batch of camera-roll metadata

cURL

curl --request POST \
  --url https://api.fanfeed.ai/v1/users/{user_id}/media \
  --header 'Content-Type: application/json' \
  --header 'X-PARTNER-API-KEY: <api-key>' \
  --data '
{
  "media": [
    {
      "id": "B84E8479-475C-4727-A4A4-B77AA9980897/L0/001",
      "taken_at": "2026-06-14T02:31:07Z",
      "latitude": "<unknown>",
      "longitude": "<unknown>",
      "media_type": "photo",
      "filename": "IMG_4821.HEIC",
      "thumbnail_url": "<string>",
      "duration_seconds": "<unknown>",
      "device_make": "Apple",
      "device_model": "iPhone 15 Pro",
      "device_lens_model": "<string>"
    }
  ]
}
'

200

{
  "accepted": 96,
  "matched": 8,
  "rejected": [
    {
      "id": "B84E8479-475C-4727-A4A4-B77AA9980897/L0/002",
      "reason": "missing_coordinates"
    }
  ],
  "matches": [
    {
      "media_id": "B84E8479-475C-4727-A4A4-B77AA9980897/L0/001",
      "matched": true,
      "event_id": 18012359,
      "venue_id": 4412
    }
  ],
  "events": [
    {
      "id": 18012359,
      "name": "Zach Bryan",
      "starts_at_local": "2026-06-13T19:30:00",
      "venue": {
        "id": 4412,
        "name": "Madison Square Garden",
        "city": "New York",
        "region": "NY",
        "country": "US",
        "latitude": "<unknown>",
        "longitude": "<unknown>"
      },
      "performers": [
        {
          "id": 34421,
          "name": "Zach Bryan",
          "category": "Country",
          "image_url": "<string>",
          "is_headliner": true
        }
      ],
      "media_count": 12,
      "media": [
        {
          "media_id": "B84E8479-475C-4727-A4A4-B77AA9980897/L0/001",
          "taken_at": "2023-11-07T05:31:56Z",
          "media_type": "photo",
          "thumbnail_url": "<string>"
        }
      ]
    }
  ],
  "last_sync_at": "2026-08-25T18:44:12Z"
}

Authorizations

X-PARTNER-API-KEY · string · header · required

Your FanFeed partner API key, issued to your organization.

FanFeed trusts your authentication: the key identifies you, and the user_id in the path identifies which of your users the request is for. FanFeed performs no end-user authentication of its own.

Treat the key as a server-side secret. See the guide for what that implies for the camera-roll ingest path, which is the one call that naturally originates on-device.

Path Parameters

user_id · string<uuid> · required

The FanFeed user id returned by POST /users.

Example:

"8f14e45f-ceea-467a-9a1e-2b4d9c3f0a11"

Body

application/json

media · object[] · required

Aim for 50–200 items per request. 200 is a hard cap; anything larger returns 413.

Smaller batches are valid and expected: the last batch of a scan is normally short, and a user with only a handful of geotagged photos may never fill one.

Required array length: 1 - 200 elements

Show child attributes

Response

200

application/json

Batch processed. Matches are included.

accepted · integer · required

Items in this batch accepted for matching: everything you sent that was not rejected.

Example:

96

matched · integer · required

A subset of accepted: how many of those landed on an event (matched: true with an event_id). The remainder are perfectly good ingested photos that were not taken at a live event.

Example:

8

rejected · object[] · required

Always present. Empty when every item in the batch was accepted. Rejections are per-item and never fail the request.

Show child attributes

matches · object[] · required

One entry per accepted item, in no particular order. Resolve by media_id.

Show child attributes

events · object[] · required

The distinct events matched in this batch, fully expanded, so you can render newly-found events as the sync progresses without a second call.

Show child attributes

last_sync_at · string<date-time> · required

Server-side timestamp of the last time FanFeed received media or a sync-complete for this user, advanced by this batch. It never moves backwards, so the value on any response is the latest mark even when concurrent batches commit out of order.

Example:

"2026-08-25T18:44:12Z"