listingsAPIlistingsAPI
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.photoUrlsarray of stringsoptionalPublicly accessible image URLs (JPEG or PNG) to fetch and attach.
input.mediaIdsarray of stringsoptionalIDs of files already in the account media library to attach to this location.

Sample request

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

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

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 photoUrls to have listingsAPI fetch images from public URLs, and/or mediaIds to attach files that already exist in your account's media library. At least one of the two arrays must be non-empty; locationId is 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. When a brand image is already in your media library, pass its media ID in mediaIds instead of re-uploading, so every location shares the same underlying file.

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": "<input.locationId>",
    "input.photoUrls": "<input.photoUrls>",
    "input.mediaIds": "<input.mediaIds>"
  }'
Run in playground