Upload a logo, cover and photos

Attach a logo, a cover image, and gallery photos to a location by URL, list what is attached, star the hero image, and remove what is stale.

Photos are attached to a location by public URL: you host the image, the API fetches and stores it, and publishers pick it up from there. A location keeps one logo, one cover, and any number of additional photos, and up to four of the additional photos can be starred for priority placement.

1. Upload by URL

POST /locations/photos takes input.locationId and an input.photos array. Each item's URL goes in a field named photo, not url. Set type to LOGO, COVER, or ADDITIONAL explicitly; an item without a type lands as an additional photo.

Upload

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", "type": "LOGO" },      { "photo": "https://cdn.example.com/jenny-home/cover.jpg", "type": "COVER" },      { "photo": "https://cdn.example.com/jenny-home/storefront.jpg", "type": "ADDITIONAL" }    ]  }}'

JSON

{  "data": {    "addLocationPhotos": {      "success": true,      "request": {},      "photos": [        { "id": "TWVkaWFGaWxlOjU4Nzg5MzE=", "databaseId": 5878931, "type": "LOGO", "starred": false,          "url": "https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/f47d62a6.png" },        { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "databaseId": 5878932, "type": "ADDITIONAL", "starred": false }      ],      "errors": null    }  }}

Keep each photo's id: it is what the star and remove endpoints take. Re-uploading a LOGO or COVER replaces the existing one. A small batch is stored inline like this. A large batch is queued instead: photos comes back empty and request.requestId is set. Branch on whether requestId is present, then poll GET /locations/photos/requests/{requestId}.

Poll a queued batch

curl https://listingsapi.com/api/v4/locations/photos/requests/e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a \-H "Authorization: API $LISTINGSAPI_KEY"

Job `status`	Meaning
`PROCESSING`	Still working. Poll again after a few seconds.
`SUCCESS`	Processing finished. Individual photos can still have failed, so read `photos[].status` and `photos[].errorMessage`.
`ERROR`	The job itself failed. Inspect `photos[].errorMessage`.

2. List what is attached

GET /locations/{locationId}/photos returns every media file on the location as a plain array. Use it to check for a missing logo or cover before you upload, and to collect ids for the next two steps. The path accepts the base64 id or the raw number.

List photos

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/photos \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "mediaFilesOfLocation": [      { "id": "TWVkaWFGaWxlOjU4Nzg5MzE=", "categoryName": "Logo", "categoryId": "4", "starred": false, "viewsCount": 0 },      { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "categoryName": "Additional", "categoryId": "12", "starred": true, "viewsCount": 143 }    ]  }}

categoryName is Logo, Cover, or Additional. A location with no media returns an empty array, not an error.

3. Star the hero image

POST /locations/photos/star marks additional photos for priority placement on publishers that support featured imagery. Only ADDITIONAL photos can be starred, at most 4 per location; a fifth fails the whole call with SY15012. You can also pass starred: true on an item at upload time.

Star

curl -X POST https://listingsapi.com/api/v4/locations/photos/star \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photoIds": ["TWVkaWFGaWxlOjU4Nzg5MzI="],    "starred": true  }}'

JSON

{  "data": {    "starUnstarLocationPhotos": {      "success": true,      "photos": [        { "id": "TWVkaWFGaWxlOjU4Nzg5MzI=", "type": "ADDITIONAL", "starred": true }      ],      "error": null    }  }}

The response key is starUnstarLocationPhotos and it carries a singular error, not an errors array. The starred flag in the body decides what happens: send false to unstar. The SDK methods take the same boolean.

4. Remove a photo

POST /locations/photos/remove detaches additional photos by id. removedCount reports how many were detached, so 0 with errors: null means none of those ids were attached to this location.

Remove

curl -X POST https://listingsapi.com/api/v4/locations/photos/remove \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "photoIds": ["TWVkaWFGaWxlOjU4Nzg5MzI="]  }}'

JSON

{  "data": {    "removeLocationPhotos": {      "removedCount": 1,      "errors": null    }  }}

Only ADDITIONAL photos can be removed here. To change the logo or cover, upload a new image with that type and it replaces the old one. Removal detaches the file from the location; it does not necessarily purge it from your media library.

5. What publishers do with each slot

Slot	How many	What publishers do with it
`LOGO`	One per location	Shown as the profile or brand image. Re-uploading replaces it. Cannot be starred or removed through the API.
`COVER`	One per location	Shown as the header image on listings that have one. Same replace-only rules as the logo.
`ADDITIONAL`	Any number	The gallery. Default `type` when none is given. Removable.
Starred `ADDITIONAL`	Up to 4	Given priority placement on publishers that support featured imagery, so lead with your best exterior and interior shots.

Next steps

Update a location: hours, closures, and Google categories on the same record.
Check listing status and live links: see when publishers have picked the new imagery up.
Upload photos, Get photos, Star photos, Remove photos, and Bulk upload status: the reference pages.
SDK references: Python photos and Node photos.