Listings APIListings API
Get API keySign in
POST/api/v4/locations/photos

Upload photos to a location

Attaches media to a location, either by public image URL or by referencing files already in your media library.

Requires an API key. See Authentication for header format and key rotation.

Parameters

Body

NameTypeRequiredDescription
input.locationIdstringrequiredThe location's Base64-encoded Relay ID to attach media to.
input.photosarray of objectsrequiredImages to attach. Each item is `{ "photo": "<public image URL>" }`, a publicly accessible JPEG or PNG URL that Listings API fetches and stores.

Sample request

Ready-to-paste body. Replace placeholder IDs and values with yours.

{
  "input": {
    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",
    "photos": [
      { "photo": "https://cdn.example.com/jenny-home/logo.png" },
      { "photo": "https://cdn.example.com/jenny-home/storefront.jpg" }
    ]
  }
}

Responses

200Photos attached. Returns the created photo records; `errors` is null on success.
{
  "data": {
    "addLocationPhotos": {
      "clientMutationId": null,
      "photos": [
        {
          "id": "TWVkaWFGaWxlOjU4Nzg5MzE=",
          "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/f47d62a6.png",
          "caption": null,
          "starred": false
        },
        {
          "id": "TWVkaWFGaWxlOjU4Nzg5MzI=",
          "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/ef4ffb12.jpg",
          "caption": null,
          "starred": false
        }
      ],
      "errors": null
    }
  }
}
401Unauthenticated, missing or invalid API key.

Attaches one or more images to a location. Supply a photos array where each item is { "photo": "<public image URL>" }; Listings API fetches each URL and stores the image. locationId and a non-empty photos array are always required.

Use case: seed a new location's imagery. Right after creating a location such as "Jenny Home", POST its logo and storefront photos by URL in a single call. The response returns each new photo's id, which you pass to the star and remove endpoints later.

Use case: reuse an approved asset across locations. Point multiple locations at the same hosted image URL in their photos arrays so every location shares the same source asset.

Gotchas.

  • Images must be JPEG or PNG. Publisher size rules apply per category (a typical floor is ~10 KB and ceiling of a few MB).
  • Large batches are processed asynchronously. Poll GET /locations/photos/requests/{requestId} to track completion when a request is queued rather than applied inline.
  • A location keeps a single logo and single cover; re-uploading either category replaces the existing image.
curl -X POST 'https://listingsapi.com/api/v4/locations/photos' \
  -H "Authorization: API $LISTINGSAPI_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "input": {
      "locationId": "TG9jYXRpb246MTgwMDI4OQ==",
      "photos": [
        {
          "photo": "https://cdn.example.com/jenny-home/logo.png"
        },
        {
          "photo": "https://cdn.example.com/jenny-home/storefront.jpg"
        }
      ]
    }
  }'
Run in playground