openapi: 3.2.0
info:
  title: Listings Locations API
  version: 2026-08-27
  description: 'REST API for managing business locations: sync listings across Google, Facebook, Bing and other publishers, respond to reviews, publish posts, and pull local search analytics. Authenticate with an API key from the developer dashboard.'
  contact:
    name: Listings API support
    email: support@listingsapi.com
    url: https://www.listingsapi.com/contact
  termsOfService: https://www.listingsapi.com/terms
  license:
    name: Proprietary (Listings API Terms of Service)
    url: https://www.listingsapi.com/terms
  x-logo:
    url: https://www.listingsapi.com/favicon.svg
servers:
- url: https://listingsapi.com
  description: Production
security:
- apiKey: []
- rapidApiKey: []
  rapidApiHost: []
tags:
- name: Locations
  description: Create, update, archive, and inspect business locations.
paths:
  /api/v4/locations-by-store-codes:
    get:
      operationId: getLocationsByStoreCodes
      summary: Get locations by the Store Codes
      tags:
      - Locations
      parameters:
      - name: storeCodes
        in: query
        required: true
        schema:
          type: string
          description: JSON-encoded filter object
        description: JSON-encoded array of store code strings, e.g. `["ACME01","jio678"]`. URL-encode the value.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LocationSummaryType'
              example:
                data:
                  getLocationsByStoreCodes:
                  - id: TG9jYXRpb246MTgwMDI4OQ==
                    databaseId: 1800289
                    accountId: 62670
                    storeId: ACME01
                    name: Jenny Home
                    archived: false
                    street: 600 Congress Ave, Suite 200
                    city: Austin
                    stateIso: TX
                    postalCode: '78701'
                    countryIso: US
                    phone: '5125550142'
                    categoryId: 15
                    subCategoryId: 1432
                    subCategoryName: Restaurants
                    package: PREMIUM
                    planId: 3797
                    planName: Launch
                    placeActionLinks:
                    - placeActionType: FOOD_ORDERING
                      uri: https://order.example.com
                      isPreferred: true
                      name: locations/1944.../placeActionLinks/54ada85bc246058a
                      submissionStatus: success
                    discoveredPlaceActionLinks: []
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: Returns full location details for one or more locations identified by their store codes.
  /api/v4/locations:
    get:
      operationId: allLocations
      summary: All locations that belong to an account
      tags:
      - Locations
      parameters:
      - name: first
        in: query
        required: false
        schema:
          type: integer
          format: int32
        description: Number of records to return, counting forward from the start of the result set.
      - name: after
        in: query
        required: false
        schema:
          type: string
        description: Cursor to page forward from. Pass `pageInfo.endCursor`, or equivalently the `cursor` of the last edge in the previous page. Stop paging when `pageInfo.hasNextPage` is false, or when a page returns an empty `edges` array.
      - name: last
        in: query
        required: false
        schema:
          type: integer
          format: int32
        description: Number of records to return, counting backward from the end of the result set.
      - name: before
        in: query
        required: false
        schema:
          type: string
        description: Cursor to page backward from, used with `last`. Pass the `cursor` of the first edge of the page you are moving back from — the gateway's shared `PageInfo` type exposes no `startCursor` field.
      - name: filter
        in: query
        required: false
        schema:
          type: string
          description: JSON-encoded filter object
        description: JSON-encoded filter object to narrow the result set (e.g. by approval status or sync state).
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                required:
                - edges
                - pageInfo
                properties:
                  edges:
                    type: array
                    items:
                      type: object
                      required:
                      - node
                      - cursor
                      properties:
                        node:
                          $ref: '#/components/schemas/LocationSummaryConnectionType'
                        cursor:
                          type: string
                  pageInfo:
                    type: object
                    required:
                    - hasNextPage
                    - hasPreviousPage
                    properties:
                      hasNextPage:
                        type: boolean
                      hasPreviousPage:
                        type: boolean
                      endCursor:
                        type:
                        - string
                        - 'null'
                      total:
                        type:
                        - integer
                        - 'null'
                  totalCount:
                    type: integer
              example:
                data:
                  allLocations:
                    edges:
                    - cursor: TG9jYXRpb246MTgwMDI4OQ==
                      node:
                        id: TG9jYXRpb246MTgwMDI4OQ==
                        databaseId: 1800289
                        accountId: 62670
                        accountName: owner@brightsmile-dental.com
                        name: Jenny Home
                        approved: APPROVED
                        archived: false
                        archivalScheduledAt: null
                        archivedAt: null
                        street: 600 Congress Ave, Suite 200
                        city: Austin
                        stateIso: TX
                        stateName: Texas
                        postalCode: '78701'
                        countryIso: US
                        countryCode: '1'
                        latitude: '30.2711286'
                        longitude: '-97.7436995'
                        phone: '5125550142'
                        additionalPhones: []
                        bizUrl: null
                        hideAddress: false
                        storeId: null
                        categoryId: 15
                        subCategoryId: 1432
                        subCategoryName: Restaurants
                        additionalCategoryIds: []
                        additionalCategoryNames: []
                        description: This is a standalone duplex house. A comfortable, private residence located in the Bouldin Creek neighborhood of Austin, offering spacious duplex living with easy access to the surrounding South Congress area and downtown Austin.
                        businessHours: []
                        package: PREMIUM
                        planId: 3797
                        planName: Launch
                        temporarilyClosed: false
                        ownerEmail: null
                        ownerName: null
                        googleVerificationStatus:
                          status: NOT_CONNECTED
                          message: null
                        voiceStatus: 3
                        uid: 3c92283c-6145-4a43-8a62-0c15fd712021
                        createdDate: July 06, 2026
                        lastUpdatedDate: July 06, 2026
                        updatedAt: 2026-07-06 18:33:29.664000+00:00
                        placeActionLinks:
                        - placeActionType: FOOD_ORDERING
                          uri: https://order.example.com
                          isPreferred: true
                          name: locations/1944.../placeActionLinks/54ada85bc246058a
                          submissionStatus: success
                          submissionMessage: Already up to date on Google.
                          lastSubmittedAt: 2026-07-08 12:14:36+00:00
                        discoveredPlaceActionLinks:
                        - placeActionType: APPOINTMENT
                          uri: https://book.example.com
                          isPreferred: false
                          name: locations/1944.../placeActionLinks/abc123
                          providerType: MERCHANT
                          isEditable: true
                    pageInfo:
                      hasNextPage: false
                      hasPreviousPage: false
                      endCursor: TG9jYXRpb246MTgwMDI4OQ==
                      total: 1
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: Returns a cursor-paginated list of locations in your account.
    post:
      operationId: createLocation
      summary: Create a new location
      tags:
      - Locations
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateLocationPayload'
              example:
                data:
                  createLocation:
                    clientMutationId: null
                    success: true
                    errors: null
                    location:
                      id: TG9jYXRpb246MTgwMDI5MA==
                      databaseId: 1800290
                      storeId: ACME01
                      name: Acme Dental
                      street: 123 Jump Street
                      city: New York
                      stateIso: NY
                      postalCode: '10013'
                      countryIso: US
                      phone: '6443859313'
                      status: PENDING
                      primaryGbpSiteCategoryId: null
                      placeActionLinks:
                      - placeActionType: APPOINTMENT
                        uri: https://book.acmedental.example.com
                        isPreferred: true
                        name: null
                        submissionStatus: null
                      - placeActionType: ONLINE_APPOINTMENT
                        uri: https://virtual.acmedental.example.com
                        isPreferred: false
                        name: null
                        submissionStatus: null
                      discoveredPlaceActionLinks: []
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                input:
                  $ref: '#/components/schemas/CreateLocationInput'
              required:
              - input
            example:
              input:
                name: Acme Dental
                description: Acme Dental is a family-owned dental practice in downtown New York offering preventive care, cosmetic dentistry, orthodontics, and emergency appointments. Our board-certified team combines modern equipment with a gentle, patient-first approach, and same-week appointments are available for new patients.
                storeId: ACME01
                street: 123 Jump Street
                city: New York
                stateIso: NY
                postalCode: '10013'
                countryIso: US
                phone: '6443859313'
                subCategoryId: 1432
                businessHours:
                - day: MONDAY
                  type: OPEN
                  slots:
                  - start: 09:00am
                    end: 05:00pm
                - day: TUESDAY
                  type: OPEN
                  slots:
                  - start: 09:00am
                    end: 05:00pm
                - day: WEDNESDAY
                  type: OPEN
                  slots:
                  - start: 09:00am
                    end: 05:00pm
                - day: THURSDAY
                  type: OPEN
                  slots:
                  - start: 09:00am
                    end: 05:00pm
                - day: FRIDAY
                  type: OPEN
                  slots:
                  - start: 09:00am
                    end: 05:00pm
                - day: SATURDAY
                  type: OPEN
                  slots:
                  - start: 10:00am
                    end: 02:00pm
                - day: SUNDAY
                  type: CLOSED
                  slots: []
                placeActionLinks:
                - placeActionType: APPOINTMENT
                  uri: https://book.acmedental.example.com
                  isPreferred: true
                - placeActionType: ONLINE_APPOINTMENT
                  uri: https://virtual.acmedental.example.com
      description: Creates a new business location in your account and queues it for listing submission.
  /api/v4/locations/search:
    get:
      operationId: searchLocations
      summary: Search for locations
      tags:
      - Locations
      parameters:
      - name: query
        in: query
        required: false
        schema:
          type: string
        description: Search keyword matched against location name, street address, city, and store ID. Omit to page through every location.
      - name: filter
        in: query
        required: false
        schema:
          type: string
          description: JSON-encoded filter object
        description: JSON-encoded filter object to narrow results (for example by approval status).
      - name: first
        in: query
        required: false
        schema:
          type: integer
          format: int32
        description: Number of records to return, counting forward from the start of the result set.
      - name: after
        in: query
        required: false
        schema:
          type: string
        description: Cursor to page forward from. Pass `pageInfo.endCursor`, or equivalently the `cursor` of the last edge in the previous page. Stop paging when `pageInfo.hasNextPage` is false, or when a page returns an empty `edges` array.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                required:
                - edges
                - pageInfo
                properties:
                  edges:
                    type: array
                    items:
                      type: object
                      required:
                      - node
                      - cursor
                      properties:
                        node:
                          $ref: '#/components/schemas/LocationSummaryConnectionType'
                        cursor:
                          type: string
                  pageInfo:
                    type: object
                    required:
                    - hasNextPage
                    - hasPreviousPage
                    properties:
                      hasNextPage:
                        type: boolean
                      hasPreviousPage:
                        type: boolean
                      endCursor:
                        type:
                        - string
                        - 'null'
                      total:
                        type:
                        - integer
                        - 'null'
                  totalCount:
                    type: integer
              example:
                data:
                  searchLocations:
                    edges:
                    - cursor: TG9jYXRpb246MTgwMDI4OQ==
                      node:
                        accountId: 62670
                        accountName: owner@brightsmile-dental.com
                        addOns: []
                        additionalCategoryIds: []
                        additionalCategoryNames: []
                        additionalGbpSiteCategoryIds: []
                        additionalGbpSiteCategoryNames: []
                        additionalInfo: null
                        additionalPhones: []
                        aiAnalyticsEnabled: false
                        approved: APPROVED
                        archivalScheduledAt: null
                        archived: false
                        archivedAt: null
                        bizUrl: null
                        bizUrlUtm: false
                        bookingUrl: null
                        businessHours: []
                        cancellationScheduledAt: null
                        categoryId: 15
                        city: Austin
                        clientName: owner@brightsmile-dental.com
                        contentPreferredLanguage: ENGLISH
                        countryCode: '1'
                        countryIso: US
                        createErrors: []
                        createdDate: July 06, 2026
                        customAttributes: []
                        databaseId: 1800289
                        defaultAgencyTag: ownerbrightsmiledentalcom
                        description: This is a standalone duplex house. A comfortable, private residence located in the Bouldin Creek neighborhood of Austin.
                        discoveredPlaceActionLinks: []
                        enabledSiteIds: []
                        facebookUrl: null
                        franchise: false
                        googleAdsPhone: null
                        googleVerificationStatus:
                          message: null
                          status: NOT_CONNECTED
                        googleplusUrl: null
                        hideAddress: false
                        id: TG9jYXRpb246MTgwMDI4OQ==
                        instagramUrl: null
                        isRestaurant: true
                        lastUpdatedDate: July 06, 2026
                        latitude: '30.2711286'
                        linkedinUrl: null
                        locationPhotos: []
                        longitude: '-97.7436995'
                        managedServiceSiteBuckets: []
                        managedServiceSites: []
                        moreHours: []
                        name: Jenny Home
                        offeringsUrl: null
                        ownerEmail: null
                        ownerName: null
                        package: PREMIUM
                        paymentMethods: []
                        phone: '5125550142'
                        pinterestUrl: null
                        placeActionLinks: []
                        planId: 3797
                        planName: Launch
                        postalCode: '78701'
                        primaryGbpSiteCategoryId: null
                        primaryGbpSiteCategoryName: null
                        publisherAttributes: []
                        reservationUrl: null
                        serviceArea: null
                        serviceItems: []
                        stateIso: TX
                        stateName: Texas
                        storeId: null
                        street: 600 Congress Ave, Suite 200
                        street1: null
                        subCategoryId: 1432
                        subCategoryName: Restaurants
                        tagline: null
                        temporarilyClosed: false
                        tiktokUrl: null
                        toplineMessage: null
                        twitterUrl: null
                        uid: 3c92283c-6145-4a43-8a62-0c15fd712021
                        updatedAt: 2026-07-06 18:33:29.664000+00:00
                        videos: []
                        voiceStatus: 3
                        yearOfIncorporation: null
                        youtubeUrl: null
                    pageInfo:
                      endCursor: TG9jYXRpb246MTgwMDI4OQ==
                      hasNextPage: false
                      hasPreviousPage: false
                      total: 1
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: Returns a cursor-paginated list of locations matching a keyword, searchable by name, address, or store ID.
  /api/v4/locations-by-ids:
    get:
      operationId: getLocationsByIds
      summary: Fetch location info via cursor ids
      tags:
      - Locations
      parameters:
      - name: locationIds
        in: query
        required: true
        schema:
          type: string
          description: JSON-encoded filter object
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LocationSummaryType'
              example:
                data:
                  getLocationsByIds:
                  - id: TG9jYXRpb246MTgwMDI4OQ==
                    databaseId: 1800289
                    accountId: 62670
                    storeId: null
                    name: Jenny Home
                    archived: false
                    archivedAt: null
                    street: 600 Congress Ave, Suite 200
                    city: Austin
                    stateIso: TX
                    postalCode: '78701'
                    countryIso: US
                    countryCode: '1'
                    latitude: '30.2711286'
                    longitude: '-97.7436995'
                    phone: '5125550142'
                    additionalPhones: []
                    bizUrl: null
                    hideAddress: false
                    categoryId: 15
                    subCategoryId: 1432
                    subCategoryName: Restaurants
                    additionalCategoryIds: []
                    description: This is a standalone duplex house. A comfortable, private residence located in the Bouldin Creek neighborhood of Austin, offering spacious duplex living with easy access to the surrounding South Congress area and downtown Austin.
                    contentPreferredLanguage: ENGLISH
                    businessHours: []
                    moreHours: []
                    package: PREMIUM
                    planId: 3797
                    planName: Launch
                    temporarilyClosed: false
                    ownerName: null
                    ownerEmail: null
                    paymentMethods: []
                    locationPhotos: []
                    isRestaurant: true
                    voiceStatus: 3
                    yearOfIncorporation: null
                    placeActionLinks:
                    - placeActionType: FOOD_ORDERING
                      uri: https://order.example.com
                      isPreferred: true
                      name: locations/1944.../placeActionLinks/54ada85bc246058a
                      submissionStatus: success
                      submissionMessage: Already up to date on Google.
                      lastSubmittedAt: 2026-07-08 12:14:36+00:00
                    discoveredPlaceActionLinks:
                    - placeActionType: APPOINTMENT
                      uri: https://book.example.com
                      isPreferred: false
                      name: locations/1944.../placeActionLinks/abc123
                      providerType: MERCHANT
                      isEditable: true
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: Returns full location information for a specified set of location IDs in one request.
  /api/v4/locations/update:
    post:
      operationId: updateLocation
      summary: Update information on a location
      tags:
      - Locations
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateLocationPayload'
              example:
                data:
                  updateLocation:
                    clientMutationId: null
                    success: true
                    errors: null
                    location:
                      id: TG9jYXRpb246MTgwMDI4OQ==
                      databaseId: 1800289
                      name: Jenny Home
                      street: 600 Congress Ave, Suite 200
                      city: Austin
                      stateIso: TX
                      countryIso: US
                      postalCode: '78701'
                      phone: '5125550199'
                      storeId: null
                      status: APPROVED
                      placeActionLinks:
                      - placeActionType: FOOD_ORDERING
                        uri: https://order.example.com
                        isPreferred: true
                        name: null
                        submissionStatus: null
                      discoveredPlaceActionLinks: []
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                input:
                  $ref: '#/components/schemas/UpdateLocationInput'
              required:
              - input
            example:
              input:
                id: TG9jYXRpb246MTgwMDI4OQ==
                phone: '5125550199'
                businessHours:
                - day: MONDAY
                  type: OPEN
                  slots:
                  - start: 09:00am
                    end: 05:00pm
                - day: TUESDAY
                  type: OPEN
                  slots:
                  - start: 09:00am
                    end: 05:00pm
                - day: WEDNESDAY
                  type: OPEN
                  slots:
                  - start: 09:00am
                    end: 05:00pm
                - day: THURSDAY
                  type: OPEN
                  slots:
                  - start: 09:00am
                    end: 05:00pm
                - day: FRIDAY
                  type: OPEN
                  slots:
                  - start: 09:00am
                    end: 05:00pm
                - day: SATURDAY
                  type: OPEN
                  slots:
                  - start: 10:00am
                    end: 02:00pm
                - day: SUNDAY
                  type: CLOSED
                  slots: []
      description: Updates writable fields on an existing location. Only the fields you send are changed.
  /api/v4/locations/photos:
    post:
      operationId: addLocationPhotos
      summary: Add photos for a location
      tags:
      - Locations
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddLocationPhotosPayload'
              example:
                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
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                input:
                  $ref: '#/components/schemas/AddLocationPhotosInput'
              required:
              - input
            example:
              input:
                locationId: TG9jYXRpb246MTgwMDI4OQ==
                photos:
                - photo: https://cdn.example.com/jenny-home/logo.png
                - photo: https://cdn.example.com/jenny-home/storefront.jpg
      description: Attaches media to a location, either by public image URL or by referencing files already in your media library.
  /api/v4/locations/photos/remove:
    post:
      operationId: removeLocationPhotos
      summary: Remove photos from a location
      tags:
      - Locations
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoveLocationPhotosPayload'
              example:
                data:
                  removeLocationPhotos:
                    clientMutationId: null
                    removedCount: 1
                    errors: null
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                input:
                  $ref: '#/components/schemas/RemoveLocationPhotosInput'
              required:
              - input
            example:
              input:
                locationId: TG9jYXRpb246MTgwMDI4OQ==
                photoIds:
                - TWVkaWFGaWxlOjU4Nzg5MzI=
      description: Detaches one or more media files from a location by their media IDs.
  /api/v4/locations/photos/star:
    post:
      operationId: starLocationPhotos
      summary: Mark photos as favourite
      tags:
      - Locations
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StarLocationPhotosPayload'
              example:
                data:
                  starLocationPhotos:
                    clientMutationId: null
                    photos:
                    - id: TWVkaWFGaWxlOjU4Nzg5MzI=
                      url: https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/ef4ffb12.jpg
                      caption: null
                      starred: true
                    errors: null
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                input:
                  $ref: '#/components/schemas/StarLocationPhotosInput'
              required:
              - input
            example:
              input:
                locationId: TG9jYXRpb246MTgwMDI4OQ==
                photoIds:
                - TWVkaWFGaWxlOjU4Nzg5MzI=
                starred: true
      description: Marks one or more of a location's additional photos as favourites for priority placement on supported publishers.
  /api/v4/locations/archive:
    post:
      operationId: archiveLocations
      summary: Archive locations
      tags:
      - Locations
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArchiveLocationsPayload'
              example:
                data:
                  archiveLocations:
                    clientMutationId: null
                    bulkEditTaskId: null
                    errors: null
                    success: null
                    result:
                    - locationId: TG9jYXRpb246MTgwMDI4OQ==
                      status: ARCHIVE_SCHEDULED
                      success: true
                      errors: null
                    - locationId: TG9jYXRpb246MTgwMDI5MA==
                      status: ARCHIVE_SCHEDULED
                      success: true
                      errors: null
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                input:
                  $ref: '#/components/schemas/ArchiveLocationsInput'
              required:
              - input
            example:
              input:
                locationIds:
                - TG9jYXRpb246MTgwMDI4OQ==
                - TG9jYXRpb246MTgwMDI5MA==
      description: Schedules one or more locations for archival at the end of the current billing cycle.
  /api/v4/locations/cancel_archive:
    post:
      operationId: cancelLocationsArchive
      summary: Cancel archival of locations
      tags:
      - Locations
      parameters: []
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelLocationsArchivePayload'
              example:
                data:
                  cancelLocationsArchive:
                    clientMutationId: null
                    bulkEditTaskId: null
                    errors: null
                    success: null
                    result:
                    - locationId: TG9jYXRpb246MTgwMDI4OQ==
                      status: ACTIVE
                      success: true
                      errors: null
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                input:
                  $ref: '#/components/schemas/CancelLocationsArchiveInput'
              required:
              - input
            example:
              input:
                locationIds:
                - TG9jYXRpb246MTgwMDI4OQ==
      description: Cancels a pending archival for locations in ARCHIVE_SCHEDULED status, restoring them to active.
  /api/v4/locations/{locationId}/photos:
    get:
      operationId: mediaFilesOfLocation
      summary: List media files attached to a single location (starred + unstarred)
      tags:
      - Locations
      parameters:
      - name: locationId
        in: path
        required: true
        schema:
          oneOf:
          - type: integer
            description: Raw numeric ID
          - type: string
            description: Base64-encoded Relay ID
          format: base64-or-int
        description: 'The location''s raw Base64-encoded Relay ID (for example `TG9jYXRpb246MTgwMDI4OQ==`). Send it un-encoded, a numeric database ID or a URL-encoded value returns `SY90002: Invalid Id`.'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MediaFileOfLocationType'
              example:
                data:
                  mediaFilesOfLocation:
                  - id: TWVkaWFGaWxlOjU4Nzg5MzE=
                    url: https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/f47d62a6.jpg
                    thumbnailUrl: https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/thumbnail_f47d62a6.jpg
                    categoryName: Logo
                    categoryId: '4'
                    fileType: image
                    starred: false
                    viewsCount: 0
                  - id: TWVkaWFGaWxlOjU4Nzg5MzI=
                    url: https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/ef4ffb12.jpg
                    thumbnailUrl: https://sy-media-store.s3-us-west-2.amazonaws.com/f868bb3f/59c670a3/thumbnail_ef4ffb12.jpg
                    categoryName: Additional
                    categoryId: '12'
                    fileType: image
                    starred: true
                    viewsCount: 143
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: Returns all media files attached to a single location, including starred and unstarred photos.
  /api/v4/locations/photos/requests/{requestId}:
    get:
      operationId: getLocationPhotosUploadStatus
      summary: Return the status of a bulk add-media-to-location request
      tags:
      - Locations
      parameters:
      - name: requestId
        in: path
        required: true
        schema:
          type: string
        description: UUID request ID returned in the `request` object by the add-photos endpoint when a batch exceeds 30 photos.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationPhotosUploadStatusType'
              example:
                data:
                  getLocationPhotosUploadStatus:
                    requestId: e6c2d9d9-9a18-4015-88cf-9a4e19a6f49a
                    status: SUCCESS
                    photos:
                    - mediaId: TWVkaWFGaWxlOjkxODI3
                      locationId: TG9jYXRpb246MTgwMDI4OQ==
                      status: SUCCESS
                      errorMessage: null
                    - mediaId: null
                      locationId: TG9jYXRpb246MTgwMDI4OQ==
                      status: ERROR
                      errorMessage: Image dimensions below the minimum 250x250.
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      description: Returns the current processing status for a bulk photo upload request.
components:
  schemas:
    LocationPhotosUploadStatusType:
      type: object
      properties:
        requestId:
          type: string
        status:
          type: string
        photos:
          type: array
          items:
            $ref: '#/components/schemas/LocationPhotoUploadItem'
    CancelLocationsArchivePayload:
      type: object
      properties:
        clientMutationId:
          type: string
        cancelledCount:
          type: integer
          format: int32
        errors:
          type: array
          items:
            $ref: '#/components/schemas/MutationErrorType'
    LocationPhotoUploadItem:
      type: object
      properties:
        mediaId:
          type: string
        locationId:
          type: string
        status:
          type: string
        errorMessage:
          type: string
    CustomAttributeInputTypeEnum:
      type: string
      enum:
      - STRING
      - NUMBER
      - BOOLEAN
      - DATE
      - ENUM
      - URL
    PlaceInfoType:
      type: object
      properties:
        placeId:
          type: string
        placeName:
          type: string
      required:
      - placeId
    CreateLocationPayload:
      type: object
      properties:
        clientMutationId:
          type: string
        location:
          $ref: '#/components/schemas/LocationSummaryType'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/MutationErrorType'
        success:
          type: boolean
    PlaceActionTypeEnum:
      type: string
      enum:
      - APPOINTMENT
      - ONLINE_APPOINTMENT
      - DINING_RESERVATION
      - FOOD_ORDERING
      - FOOD_DELIVERY
      - FOOD_TAKEOUT
      - SHOP_ONLINE
      description: Google place action types.
    StarLocationPhotosInput:
      type: object
      properties:
        clientMutationId:
          type: string
        locationId:
          type: string
        photoIds:
          type: array
          items:
            type: string
        starred:
          type: boolean
      required:
      - locationId
      - photoIds
      - starred
    PlaceActionLinkType:
      type: object
      description: A Google place action link (ordering, delivery, takeout, reservation, appointment, etc.).
      properties:
        placeActionType:
          type: string
        uri:
          type: string
        isPreferred:
          type: boolean
        name:
          type: string
        providerType:
          type: string
        isEditable:
          type: boolean
        submissionStatus:
          type: string
        submissionMessage:
          type: string
        submissionCode:
          type: string
        lastSubmittedAt:
          type: string
      required:
      - placeActionType
      - uri
    ServiceAreaType:
      type: object
      properties:
        businessType:
          type: string
        regionCode:
          type: string
        placeInfos:
          type: array
          items:
            $ref: '#/components/schemas/PlaceInfoType'
    BusinessHours:
      type: string
      enum:
      - OPEN
      - CLOSED
    ArchiveLocationsPayload:
      type: object
      properties:
        clientMutationId:
          type: string
        archivedCount:
          type: integer
          format: int32
        locations:
          type: array
          items:
            $ref: '#/components/schemas/LocationSummaryType'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/MutationErrorType'
      required:
      - archivedCount
    AddLocationPhotosPayload:
      type: object
      description: (also defined by media-manager)
      properties:
        clientMutationId:
          type: string
        photos:
          type: array
          items:
            $ref: '#/components/schemas/PhotoType'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/MutationErrorType'
    LocationStatusType:
      type: string
      enum:
      - ACTIVE
      - ARCHIVED
      - PENDING
      - TEMPORARILY_CLOSED
      - SCHEDULED_FOR_ARCHIVE
      description: Lifecycle states of a location.
    CancelLocationsArchiveInput:
      type: object
      properties:
        clientMutationId:
          type: string
        locationIds:
          type: array
          items:
            type: string
      required:
      - locationIds
    PhotoType:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
        caption:
          type: string
        starred:
          type: boolean
      required:
      - id
      - url
    DayOfTheWeekType:
      type: string
      enum:
      - MONDAY
      - TUESDAY
      - WEDNESDAY
      - THURSDAY
      - FRIDAY
      - SATURDAY
      - SUNDAY
    BusinessHoursDayInput:
      type: object
      properties:
        day:
          $ref: '#/components/schemas/DayOfTheWeekType'
        slots:
          type: array
          items:
            $ref: '#/components/schemas/BusinessHoursSlotInput'
        type:
          $ref: '#/components/schemas/BusinessHours'
      required:
      - day
      - type
    MutationErrorType:
      type: object
      description: (also defined by notifications) (also defined by reviewfunnel) (also defined by crawler)
      properties:
        code:
          type: string
        message:
          type: string
        path:
          type: array
          items:
            type: string
      required:
      - message
    LocationSummaryType:
      type: object
      description: Summary view of a business location.
      properties:
        id:
          type: string
        databaseId:
          type: integer
          format: int32
        storeId:
          type: string
        name:
          type: string
        street:
          type: string
        city:
          type: string
        stateIso:
          type: string
        countryIso:
          type: string
        postalCode:
          type: string
        latitude:
          type: number
          format: float
        longitude:
          type: number
          format: float
        phone:
          type: string
        website:
          type: string
        status:
          $ref: '#/components/schemas/LocationStatusType'
        primaryGbpSiteCategoryId:
          type: string
        additionalGbpSiteCategoryIds:
          type: array
          items:
            type: string
        serviceArea:
          type: array
          items:
            $ref: '#/components/schemas/ServiceAreaType'
        placeActionLinks:
          type: array
          items:
            $ref: '#/components/schemas/PlaceActionLinkType'
        discoveredPlaceActionLinks:
          type: array
          items:
            $ref: '#/components/schemas/PlaceActionLinkType'
      required:
      - id
      - name
    LocationSummaryConnectionType:
      type: object
      description: A Relay connection over LocationSummary.
      properties:
        edges:
          type: array
          items:
            $ref: '#/components/schemas/LocationSummaryEdgeType'
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/LocationSummaryType'
        pageInfo:
          $ref: '#/components/schemas/PageInfoType'
        totalCount:
          type: integer
          format: int32
      required:
      - pageInfo
    RemoveLocationPhotosInput:
      type: object
      properties:
        clientMutationId:
          type: string
        locationId:
          type: string
        photoIds:
          type: array
          items:
            type: string
      required:
      - locationId
      - photoIds
    LocationSummaryEdgeType:
      type: object
      properties:
        cursor:
          type: string
        node:
          $ref: '#/components/schemas/LocationSummaryType'
      required:
      - cursor
    PlaceInfoInput:
      type: object
      properties:
        placeId:
          type: string
        placeName:
          type: string
      required:
      - placeId
    BusinessHoursSlotInput:
      type: object
      properties:
        start:
          type: string
        end:
          type: string
      required:
      - start
      - end
    CustomAttributeLevelTypeEnum:
      type: string
      enum:
      - ACCOUNT
      - LOCATION
    CreateLocationInput:
      type: object
      properties:
        clientMutationId:
          type: string
        name:
          type: string
        description:
          type: string
        storeId:
          type: string
        street:
          type: string
        city:
          type: string
        stateIso:
          type: string
        postalCode:
          type: string
        countryIso:
          type: string
        subCategoryId:
          type: integer
          format: int32
        phone:
          type: string
        businessHours:
          type: array
          items:
            $ref: '#/components/schemas/BusinessHoursDayInput'
        serviceArea:
          $ref: '#/components/schemas/ServiceAreaInput'
        enabledSiteIds:
          type: array
          items:
            type: integer
            format: int32
        placeActionLinks:
          type: array
          items:
            $ref: '#/components/schemas/PlaceActionLinkInputType'
      required:
      - name
      - description
      - countryIso
      - subCategoryId
    PlaceActionLinkInputType:
      type: object
      description: Write payload for a Google place action link (append/upsert model).
      properties:
        placeActionType:
          $ref: '#/components/schemas/PlaceActionTypeEnum'
        uri:
          type: string
        isPreferred:
          type: boolean
        name:
          type: string
        providerType:
          type: string
        isEditable:
          type: boolean
        action:
          type: string
      required:
      - placeActionType
      - uri
    PageInfoType:
      type: object
      description: (also defined by notifications) (also defined by reviewfunnel) (also defined by contests) (also defined by social-media)
      properties:
        hasNextPage:
          type: boolean
        hasPreviousPage:
          type: boolean
        startCursor:
          type: string
        endCursor:
          type: string
      required:
      - hasNextPage
      - hasPreviousPage
    StarLocationPhotosPayload:
      type: object
      properties:
        clientMutationId:
          type: string
        photos:
          type: array
          items:
            $ref: '#/components/schemas/PhotoType'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/MutationErrorType'
    MoreHourInput:
      type: object
      properties:
        type:
          type: string
        days:
          type: array
          items:
            $ref: '#/components/schemas/MoreHourDayInput'
      required:
      - type
    MediaFileOfLocationType:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
        thumbnailUrl:
          type: string
        categoryName:
          type: string
        categoryId:
          type: string
        fileType:
          type: string
        starred:
          type: boolean
        viewsCount:
          type: integer
          format: int32
      required:
      - id
    UpdateLocationPayload:
      type: object
      properties:
        clientMutationId:
          type: string
        location:
          $ref: '#/components/schemas/LocationSummaryType'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/MutationErrorType'
        success:
          type: boolean
    AddLocationPhotosInput:
      type: object
      properties:
        clientMutationId:
          type: string
        locationId:
          type: string
        photos:
          type: array
          items:
            $ref: '#/components/schemas/LocationPhotoInput'
      required:
      - locationId
      - photos
    CustomAttributeInputType:
      type: object
      properties:
        name:
          type: string
        value:
          type: string
        type:
          $ref: '#/components/schemas/CustomAttributeInputTypeEnum'
        levelType:
          $ref: '#/components/schemas/CustomAttributeLevelTypeEnum'
      required:
      - name
    Error:
      type: object
      description: Listings API error envelope returned from mutations.
      properties:
        code:
          type: string
        message:
          type: string
        field:
          type: string
    ArchiveLocationsInput:
      type: object
      properties:
        clientMutationId:
          type: string
        locationIds:
          type: array
          items:
            type: string
      required:
      - locationIds
    RemoveLocationPhotosPayload:
      type: object
      description: (also defined by media-manager)
      properties:
        clientMutationId:
          type: string
        removedCount:
          type: integer
          format: int32
        errors:
          type: array
          items:
            $ref: '#/components/schemas/MutationErrorType'
    UpdateLocationInput:
      type: object
      properties:
        clientMutationId:
          type: string
        id:
          type: string
        name:
          type: string
        street:
          type: string
        city:
          type: string
        stateIso:
          type: string
        postalCode:
          type: string
        countryIso:
          type: string
        phone:
          type: string
        businessHours:
          type: array
          items:
            $ref: '#/components/schemas/BusinessHoursDayInput'
        moreHours:
          type: array
          items:
            $ref: '#/components/schemas/MoreHourInput'
        serviceArea:
          $ref: '#/components/schemas/ServiceAreaInput'
        customAttributes:
          type: array
          items:
            $ref: '#/components/schemas/CustomAttributeInputType'
        placeActionLinks:
          type: array
          items:
            $ref: '#/components/schemas/PlaceActionLinkInputType'
      required:
      - id
    MoreHourDayInput:
      type: object
      properties:
        day:
          $ref: '#/components/schemas/DayOfTheWeekType'
        openTime:
          type: string
        closeTime:
          type: string
      required:
      - day
    ServiceAreaInput:
      type: object
      properties:
        businessType:
          type: string
        regionCode:
          type: string
        placeInfos:
          type: array
          items:
            $ref: '#/components/schemas/PlaceInfoInput'
    LocationPhotoInput:
      type: object
      properties:
        url:
          type: string
        caption:
          type: string
        type:
          type: string
      required:
      - url
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'Authenticate with `Authorization: API <your-key>`.'
    rapidApiKey:
      type: apiKey
      in: header
      name: X-RapidAPI-Key
      description: RapidAPI marketplace key. Sent with `X-RapidAPI-Host` when calling via the RapidAPI proxy.
    rapidApiHost:
      type: apiKey
      in: header
      name: X-RapidAPI-Host
      description: RapidAPI marketplace host header. Sent with `X-RapidAPI-Key` when calling via the RapidAPI proxy.
externalDocs:
  description: Developer documentation
  url: https://docs.listingsapi.com