openapi: 3.2.0
info:
  title: Local SEO REST Listing Profiles API
  version: '1.0'
  description: Using this api requires active Local SEO
servers:
- url: https://prod.apigateway.co/products/listings
  description: Production
- url: https://demo.apigateway.co/products/listings
  description: Demo
- url: '{local}/products/listings'
  description: Local
- url: http://localhost:11001/products/listings
  description: Localhost
tags:
- name: Listing Profiles
paths:
  /listingProfiles/{id}:
    parameters:
    - schema:
        type: string
      name: id
      in: path
      required: true
    patch:
      summary: Update Listing Profile
      operationId: patch-listingProfiles-id
      tags:
      - Listing Profiles
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`


        Update the existing listing profile.

        Only the root ID and type fields are required. All others are optional and will keep their original value if omitted.'
      x-lifecycle:
        status: proposed
      parameters:
      - schema:
          type: string
          example: Bearer <Access Token>
          pattern: ^Bearer\s\S+
        in: header
        name: Authorization
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        required: true
      - schema:
          type: string
          default: application/vnd.api+json
          enum:
          - application/vnd.api+json
        in: header
        name: Content-Type
        required: true
        description: Indicates the format of the request body being sent. In most cases you will want `application/vnd.api+json`
      security:
      - OAuth2Demo:
        - listing
      - OAuth2Prod:
        - listing
      responses:
        '200':
          description: Ok
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/listingProfiles'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
                        format: uri
                        description: The address of the updated listing profile
          headers: {}
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/listingProfiles'
    get:
      summary: Get Listing Profile
      tags:
      - Listing Profiles
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/listingProfiles'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
      operationId: get-listingProfiles-id
      x-lifecycle:
        status: trustedTester
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`


        Returns basic data about the listing profile.'
      parameters:
      - schema:
          type: string
          example: Bearer <Access Token>
          pattern: ^Bearer\s\S+
        in: header
        name: Authorization
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        required: true
      security:
      - OAuth2Demo:
        - listing
      - OAuth2Prod:
        - listing
components:
  schemas:
    hoursOfOperation:
      type: array
      x-examples:
        Example 1:
        - hoursTypeId: general
          regularHours:
          - openDay: wednesday
            closeDay: wednesday
            openTime: 09:45
            closeTime: 09:45
          specialHours:
          - status: closed
            startDate: '2019-08-24'
            endDate: '2019-08-24'
            openTime: 09:45
            closeTime: 09:45
      description: "The operating hours for the listing profile. \nEach entry in the array is a set of hours for a particular department or customer of the business. It is recommended to provide the `general` hours for all locations. Some locations may have additional definitions for "
      items:
        type: object
        properties:
          hoursTypeId:
            type: string
            description: "The category of hours that may apply to a specific department or service. Not all types are valid for all business categories.\n\nThe general hours for a location must be set before defining hours for other departments. \n\nCurrently only `general` is supported in the Vendasta platform."
            enum:
            - general
            - delivery
            - kitchen
            - pickup
            - driveThrough
            - takeout
          regularHours:
            type: array
            description: 'A collection of times that this location is open for business. Each period represents a range of hours when the location is open during the week.


              You may specify multiple entries for the same date if you are open for multiple periods (Example lunch and supper).'
            items:
              type: object
              properties:
                openDay:
                  allOf:
                  - type: string
                    x-stoplight:
                      id: 3u07tkjf0bxdg
                    description: Indicates the day of the week that this period starts on.
                  - $ref: '#/components/schemas/dayOfTheWeek'
                closeDay:
                  allOf:
                  - type: string
                    x-stoplight:
                      id: svnvxunjr767f
                    description: Indicates the day of the week that this period ends on. It should be the same as `openDay` except when the period goes over midnight. The total period may not be more than 24 hours
                  - $ref: '#/components/schemas/dayOfTheWeek'
                openTime:
                  $ref: '#/components/schemas/timeOfDay'
                closeTime:
                  $ref: '#/components/schemas/timeOfDay'
              required:
              - openDay
              - closeDay
              - openTime
              - closeTime
          specialHours:
            type: array
            description: SpecialHours represents a set of time periods when a location's operational hours differ from its regular business hours. This may be a holiday or special event. These hours replace the sets of hours that begin on the dates specified by the special hours entry. The `openTime` and `startDate` must predate the `closeTime` and `endDate` respectively. Currently only `open` and `closed` are supported in the Vendasta platform.
            items:
              type: object
              properties:
                status:
                  type: string
                  description: Describes the different modes that apply to special hour periods. Currently only `open` and `closed` are supported in the Vendasta platform. Overlapping `open` and `closed` periods are not allowed. When status is `open`, for the given business it will be open for the mentioned time period for the selected date. When status is `closed`, for the given business it will be closed for the selected date.
                  enum:
                  - open
                  - closed
                startDate:
                  type: string
                  format: date
                  description: The calendar date this special hour period starts on.
                endDate:
                  type: string
                  format: date
                  description: Optional:The calendar date this special hour period ends on. If `endDate` field is not set, default to the date specified in `startDate`. If set, this field must be equal to or at most 1 day after `startDate`.
                startTime:
                  $ref: '#/components/schemas/timeOfDay'
                endTime:
                  $ref: '#/components/schemas/timeOfDay'
              required:
              - status
              - startDate
              - startTime
              - endTime
        required:
        - hoursTypeId
    timeOfDay:
      title: a time of Day
      x-stoplight:
        id: lji3j2ahr2aiu
      type: string
      description: 'Valid values are 00:00-24:00, where 24:00 represents midnight at the end of the specified day field.

        If `specialHours` is set with status `closed`, the corresponding `startTime` and `endTime` value for the hours should be set to `00:00`'
      example: 09:45
      pattern: ^\d{2}:\d{2}$
    listingProfiles:
      type: object
      x-examples:
        Example 1:
          id: AG-1234567
          type: listingProfiles
          attributes:
            customerIdentifier: customer 123
            name: Fred's Fish
            address:
              line1: 109 8th Street E.
              line2: Suite 23
              city: string
              postalCode: S7M 1R3
              regionCode: CA-SK
              countryCode: CA
            phoneNumbers:
            - +1 (306) 555-1234
            serviceAreaBusiness: true
            geoCoordinate:
              latitude: -90
              longitude: -180
            hours:
            - hoursTypeId: general
              regularHours:
              - openDay: wednesday
                closeDay: wednesday
                openTime: 09:45
                closeTime: 09:45
              specialHours:
              - status: closed
                startDate: '2019-08-24'
                endDate: '2019-08-24'
                openTime: 09:45
                closeTime: 09:45
          relationships:
            businessPartner:
              data:
                type: partners
                id: ABC
            businessCategories:
              data:
              - type: businessCategories
                id: active:diving:freediving
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`


        A listing profile is the representation of a business location (or similar) used by the Local SEO product. It contains advanced fields used by listing sources. If the Local SEO product is active for the location the data will be shared to listing sources such as Google Maps.'
      properties:
        id:
          type: string
          example: AG-1231232
          description: An identifier for the record. Currently these will be the same as a platform/salesAccounts or platform/businessLocations id.
        type:
          type: string
          enum:
          - listingProfiles
          default: listingProfiles
          description: The data type of this record
        attributes:
          type: object
          properties:
            customerIdentifier:
              type: string
              description: A value assigned by the business partner to reference this business location. Customer ID is currently NOT enforced to be unique, and there may be negative side effects to having a duplicate and/or changing a customer ID, specifically around legacy SSO. Use caution when editing a customer ID.
              readOnly: true
            name:
              type: string
              description: 'The common name for this location.

                Note: The pipe character (`|`) is not allowed.'
            address:
              type: object
              properties:
                line1:
                  type: string
                  description: The primary information. Typically a street address
                line2:
                  type: string
                  description: An additional line of information to add after the street address.
                city:
                  type: string
                postalCode:
                  type: string
                  description: The zip code or postal code component of an address.
                regionCode:
                  type: string
                  example: CA-SK, US-FL, AG-08, AU-NSW
                  pattern: ^[A-Z]{2}-[\w]{1,3}$
                  minLength: 4
                  maxLength: 6
                  description: 'The code for the top level subdivision within the country (state/province). For more info see the [Addresses guide](https://developers.vendasta.com/platform/1ljuzmi2uboim-addresses)


                    Examples: CA-SK, US-FL, AG-08, AU-NSW'
                countryCode:
                  type: string
                  example: CA, US, AU
                  minLength: 2
                  maxLength: 2
                  pattern: ^[A-Z]{2}$
                  description: 'The two letter country code. For more info see the [Addresses guide](https://developers.vendasta.com/platform/1ljuzmi2uboim-addresses)


                    Examples: CA, US, AU'
            phoneNumbers:
              type: array
              description: 'The standard phone numbers for the location.

                Formatting characters may be included.


                **Extensions**


                It is recommended that extensions are included at the end of the number after an appropriate separator: Pause: `,` Wait: `;` Default: `ext.`


                You may test the parsibility of a number using https://phonenumbers.temba.io/ All phone numbers are assumed to be in the same country as this listing profile'
              items:
                type: string
            serviceAreaBusiness:
              type: boolean
              description: When true the address will be used as the center of the area that this location services instead of being displayed
            geoCoordinate:
              type: object
              description: 'The point where the map pin for the location should be displayed.


                The values will **not** be automatically updated when the address is updated. If not provided when creating the location they will be initialized based on the address.


                It is expressed as a pair of numbers to represent degrees latitude and degrees longitude in accordance with the [WGS84](https://en.wikipedia.org/wiki/World_Geodetic_System) standard (the one used by your GPS).'
              required:
              - latitude
              - longitude
              properties:
                latitude:
                  type: number
                longitude:
                  type: number
            hours:
              $ref: '#/components/schemas/hoursOfOperation'
            ico:
              type: number
              x-stoplight:
                id: ccum95lf9wwqb
              description: Identifier for a business in the Czech republic.  Can only be set for Czech businesses
        relationships:
          type: object
          properties:
            businessPartner:
              type: object
              description: A link to the organization that provides the platform to this listing profile
              required:
              - data
              properties:
                data:
                  type: object
                  required:
                  - type
                  - id
                  properties:
                    type:
                      type: string
                    id:
                      type: string
            businessCategories:
              type: object
              description: A list of the types of business this location should be compared against. The first item on the list will be considered as the primary category. If not set during creation it will default "other".
              properties:
                data:
                  type: array
                  items:
                    type: object
                    required:
                    - type
                    - id
                    properties:
                      type:
                        type: string
                      id:
                        type: string
    dayOfTheWeek:
      title: a day of the week
      x-stoplight:
        id: g2z8832hnj8hr
      type: string
      enum:
      - monday
      - tuesday
      - wednesday
      - thursday
      - friday
      - saturday
      - sunday
      example: wednesday
  securitySchemes:
    JWT:
      type: http
      scheme: bearer
    OAuth2Demo:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://sso-api-demo.apigateway.co/oauth2/auth
          tokenUrl: https://sso-api-demo.apigateway.co/oauth2/token
          refreshUrl: ''
          scopes:
            listing: Access to the Local SEO REST API
    OAuth2Prod:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://sso-api-prod.apigateway.co/oauth2/auth
          tokenUrl: https://sso-api-prod.apigateway.co/oauth2/token
          refreshUrl: ''
          scopes:
            listing: Access to the Local SEO REST API