Skip to content
SynupAPI
Get an API key
POSTapi.synup.com/api/v4/locations

Create a new business location

A Location represents a physical business entity within your account and serves as the foundation for managing and interacting with the API’s features. Each Location acts as a centralized hub for managing and accessing data related to that specific business, including:

  • Listings Management: Maintain accurate and consistent business details across multiple publishers.
  • Review Monitoring: Track and respond to customer feedback associated with the location.
  • Performance Insights: Analyze key metrics related to visibility, engagement, and growth.
  • SEO Optimization: Enhance local search presence and improve rankings.

See the Request Section for a detailed data schema of Supported Fields. Here’s a key detail to keep in mind:

Requires an API key. Send it as Authorization: API <your-key> — see Getting started.

Parameters

Body

NameTypeRequiredDescription
inputobjectoptional
input.tenurestringoptionalRequired when an account has multiple subscriptions. Specifies the tenure (e.g., Monthly).

For accounts with multiple subscriptions, specify the tenure of the corresponding subscription. Refer to Subscriptions for details.
input.storeIdstringoptionalUnique store identifier. Must be unique across all locations.
input.subCategoryIdintegerrequiredID of the subcategory the business belongs to
input.namestringrequiredName of the business
input.streetstringrequiredStreet address of the business
input.street1stringoptionalAdditional street address information
input.citystringrequiredCity where the business is located
input.postalCodestringrequiredPostal code of the business location
input.phonestringrequired
  • Must follow the international E.164 format. Ref here.
  • Do not include the + sign or country code.
  • Remove parentheses and special characters.
  • Example:
  • Incorrect: (123)-456-7890, +1-123-456-7890
  • Correct: 1234567890
input.stateIsostringrequiredState ISO code. Refer to the Places API for valid ISOs.
input.countryIsostringrequiredCountry ISO code. Refer to the Places API for valid ISOs.
input.descriptionstringrequiredDetailed description of the business
input.ownerEmailstringoptionalEmail of the business owner
input.ownerNamestringoptionalName of the business owner
input.bizUrlstringoptionalURL of the business website
input.facebookUrlstringoptionalURL of the business's Facebook page
input.twitterUrlstringoptionalURL of the business's Twitter page
input.linkedinUrlstringoptionalURL of the business's LinkedIn page
input.instagramUrlstringoptionalURL of the business's Instagram page
input.youtubeUrlstringoptionalURL of the business's YouTube page
input.tiktokUrlstringoptionalURL of the business's TikTok page
input.pinterestUrlstringoptionalURL of the business's Pinterest page
input.taglinestringoptionalTagline of the business
input.paymentMethodsarray of stringoptionalAccepted payment methods ("VISA", "MASTERCARD", "AMEX", "CASH", "CHEQUE", "CRYPTO", "DINERS_CLUB", "DISCOVER", "FINANCING", "INVOICE", "TRAVELERS_CHECK", "APPLE_PAY", "SAMSUNG_PAY", "PAYPAL", "ANDROID_PAY" )
input.yearOfIncorporationintegeroptionalYear the business was established
input.hideAddressbooleanoptionalSet to true if location is a Service Area Business
input.businessHoursarray of objectoptionalBusiness hours for each day of the week
input.businessHours[].daystringrequiredDay of the week
MONDAYTUESDAYWEDNESDAYTHURSDAYFRIDAYSATURDAYSUNDAY
input.businessHours[].slotsarray of objectrequiredArray of time slots (minimum 1, maximum 2). Required only if type is OPEN.
input.businessHours[].slots[].startstringoptionalOpening time. Valid formats: <HH>:<MM>am OR <HH>:<MM>pm
input.businessHours[].slots[].endstringoptionalClosing time. Valid formats: <HH>:<MM>am OR <HH>:<MM>pm
input.businessHours[].typestringrequiredType of business hours (e.g., OPEN, CLOSED, OPEN_24x7)
OPENOPEN_24x7CLOSED
input.additionalCategoryIdsarray of integeroptionalAdditional category IDs for the business
input.videosarray of stringoptionalList of valid video URLs
input.enabledSiteIdsarray of integeroptionalList of site IDs where the business details should be published
input.submissionDisabledSiteIdsarray of integeroptionalList of site IDs where the business details should not be published
input.temporarilyClosedbooleanoptionalSet to true if the location's business hours should be marked as closed
input.additionalPhonesarray of stringoptionalAdditional contact phone numbers
input.googleAdsPhonestringoptionalGoogle Ads-specific phone number
input.bookingUrlstringoptionalURL for booking appointments. Applicable only for Food industry businesses
input.offeringsUrlstringoptionalURL for listing business offerings. Applicable only for food industry businesses
input.reservationUrlstringoptionalURL for making reservations. Applicable only for restaurant only businesses.
input.placeActionLinksarray of objectoptionalManage a location's Place Action Links
input.placeActionLinks[].placeActionTypestringrequiredOne of the valid types.
APPOINTMENTONLINE_APPOINTMENTDINING_RESERVATIONFOOD_ORDERINGFOOD_DELIVERYFOOD_TAKEOUTSHOP_ONLINE
input.placeActionLinks[].isPreferredbooleanoptionalMarks this link preferred for its type. At most one preferred per type.
input.placeActionLinks[].uristringrequiredDestination URL.

Request

Request
curl -X POST 'https://api.synup.com/api/v4/locations' \
  -H 'Authorization: API YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "input": {
    "tenure": "Monthly",
    "name": "Whisk & Bloom Bakery",
    "street": "123 Maple Avenue",
    "street1": "Suite 202",
    "city": "San Francisco",
    "postalCode": "94107",
    "phone": "(415) 555-1239",
    "stateIso": "CA",
    "countryIso": "US",
    "ownerEmail": "lana@whiskbloom.com",
    "ownerName": "Lana Thompson",
    "subCategoryId": 10,
    "description": "Whisk & Bloom Bakery offers a delightful selection of organic and gluten-free baked goods. Our mission is to provide fresh, handmade pastries and cakes crafted with love and the finest ingredients. Visit us for a cozy experience and enjoy our special seasonal treats!",
    "bizUrl": "https://www.whisknbloombakery.com/",
    "facebookUrl": "https://www.facebook.com/whisknbloomBakery/",
    "linkedinUrl": "https://www.linkedin.com/company/whisknbloombakery",
    "twitterUrl": "https://twitter.com/whisknbloomBakery",
    "instagramUrl": "https://www.instagram.com/whisknbloombakery/",
    "youtubeUrl": null,
    "tiktokUrl": null,
    "pinterestUrl": "https://www.pinterest.com/whisknbloombakery/",
    "tagline": "Fresh. Organic. Delicious.",
    "paymentMethods": [
      "VISA",
      "CASH"
    ],
    "yearOfIncorporation": 2015,
    "hideAddress": false,
    "businessHours": [
      {
        "day": "MONDAY",
        "slots": [
          {
            "start": "08:00am",
            "end": "12:00pm"
          },
          {
            "start": "01:00pm",
            "end": "06:00pm"
          }
        ],
        "type": "OPEN"
      },
      {
        "day": "TUESDAY",
        "slots": [
          {
            "start": "08:00am",
            "end": "06:00pm"
          }
        ],
        "type": "OPEN"
      },
      {
        "day": "WEDNESDAY",
        "slots": [
          {
            "start": "08:00am",
            "end": "06:00pm"
          }
        ],
        "type": "OPEN"
      },
      {
        "day": "THURSDAY",
        "slots": [
          {
            "start": "08:00am",
            "end": "06:00pm"
          }
        ],
        "type": "OPEN"
      },
      {
        "day": "FRIDAY",
        "slots": [
          {
            "start": "08:00am",
            "end": "06:00pm"
          }
        ],
        "type": "OPEN"
      },
      {
        "day": "SATURDAY",
        "slots": [
          {
            "start": "08:00am",
            "end": "04:00pm"
          }
        ],
        "type": "OPEN"
      },
      {
        "day": "SUNDAY",
        "slots": [],
        "type": "CLOSED"
      }
    ],
    "additionalCategoryIds": [],
    "videos": [],
    "enabledSiteIds": [],
    "submissionDisabledSiteIds": [],
    "temporarilyClosed": false,
    "additionalPhones": [
      "(415) 555-5678",
      "(415) 555-9012"
    ],
    "googleAdsPhone": "(415) 555-3456",
    "bookingUrl": "https://www.whisknbloombakery.com/reservations",
    "offeringsUrl": "https://www.whisknbloombakery.com/menu",
    "reservationUrl": "https://www.whisknbloombakery.com/book",
    "storeId": null,
    "placeActionLinks": [
      {
        "placeActionType": "FOOD_ORDERING",
        "uri": "https://order.example.com",
        "isPreferred": true
      },
      {
        "placeActionType": "FOOD_DELIVERY",
        "uri": "https://deliver.example.com"
      }
    ]
  }
}'

Responses

StatusDescription
200Location created successfully
400Bad request, invalid input
Example response (generated from the schema)
{
  "data": {
    "createLocation": {
      "errors": null,
      "location": {
        "accountId": 0,
        "additionalCategoryIds": [
          "string"
        ],
        "additionalInfo": null,
        "additionalPhones": [
          "string"
        ],
        "archived": true,
        "archivedAt": null,
        "billingPeriod": null,
        "bizUrl": "string",
        "bookingUrl": "string",
        "categoryId": 0,
        "businessHours": [
          {
            "day": "MONDAY",
            "slots": [
              null
            ],
            "type": "OPEN",
            "specialDate": "string"
          }
        ],
        "city": "string",
        "countryIso": "string",
        "customAttributes": [
          {
            "archived": true,
            "enumValues": [
              null
            ],
            "name": "string",
            "slug": "string",
            "type": "string",
            "value": [
              null
            ]
          }
        ],
        "databaseId": 0,
        "description": "string",
        "facebookUrl": "string",
        "folderId": "string",
        "folderName": "string",
        "googleAdsPhone": "string",
        "googleplusUrl": null,
        "hideAddress": true,
        "id": "string",
        "instagramUrl": "string",
        "isRestaurant": true,
        "latitude": 0,
        "linkedinUrl": "string",
        "locationPhotos": [
          "string"
        ],
        "longitude": 0,
        "moreHours": [
          "string"
        ],
        "name": "string",
        "offeringsUrl": "string",
        "ownerEmail": "string",
        "ownerName": "string",
        "package": "string",
        "paymentMethods": [
          "string"
        ],
        "phone": "string",
        "pinterestUrl": "string",
        "planId": 0,
        "planName": "string",
        "postalCode": "string",
        "publisherAttributes": [
          "string"
        ],
        "reservationUrl": "string",
        "serviceItems": [
          "string"
        ],
        "stateIso": "string",
        "storeId": null,
        "street": "string",
        "street1": "string",
        "subCategory": {
          "databaseId": 0,
          "id": "string",
          "name": "string",
          "primary": true
        },
        "subCategoryId": 0,
        "subCategoryName": "string",
        "tagline": "string",
        "tags": [
          "string"
        ],
        "temporarilyClosed": true,
        "tiktokUrl": null,
        "toplineMessage": null,
        "toplineMessageText": null,
        "twitterUrl": "string",
        "videos": [
          "string"
        ],
        "yearOfIncorporation": 0,
        "youtubeUrl": null,
        "placeActionLinks": [
          {
            "placeActionType": "FOOD_ORDERING FOOD_ORDERING",
            "uri": "string",
            "isPreferred": true,
            "name": "string",
            "submissionStatus": "string",
            "submissionMessage": "string",
            "lastSubmittedAt": "string",
            "isEditable": "string"
          }
        ],
        "discoveredPlaceActionLinks": [
          {
            "placeActionType": "string",
            "uri": "string",
            "isPreferred": true,
            "name": "string",
            "providerType": "string",
            "isEditable": true
          }
        ]
      },
      "success": true,
      "warnings": [
        "string"
      ]
    }
  },
  "message": "Location created successfully"
}

Response body

NameTypeRequiredDescription
dataobjectoptionalContains the response data for the create location request.
data.createLocationobjectoptionalEncapsulates details about the created location.
data.createLocation.errorsnulloptionalErrors encountered during the location creation process, if any. Null if no errors.
data.createLocation.locationobjectoptionalDetails of the created location.
data.createLocation.location.accountIdintegerrequired
data.createLocation.location.additionalCategoryIdsarray of stringrequired
data.createLocation.location.additionalInfonullrequired
data.createLocation.location.additionalPhonesarray of stringrequired
data.createLocation.location.archivedbooleanrequired
data.createLocation.location.archivedAtnullrequired
data.createLocation.location.billingPeriodnullrequired
data.createLocation.location.bizUrlstringoptional
data.createLocation.location.bookingUrlstringoptional
data.createLocation.location.categoryIdintegerrequired
data.createLocation.location.businessHoursarray of objectoptionalBusiness hours for each day of the week
data.createLocation.location.businessHours[].daystringrequiredDay of the week | Special
MONDAYTUESDAYWEDNESDAYTHURSDAYFRIDAYSATURDAYSUNDAYSPECIAL
data.createLocation.location.businessHours[].slotsarray of objectrequiredArray of time slots (minimum 1, maximum 2). Required only if type is OPEN.
data.createLocation.location.businessHours[].slots[].startstringoptionalOpening time. Valid formats: <HH>:<MM>am OR <HH>:<MM>pm
data.createLocation.location.businessHours[].slots[].endstringoptionalClosing time. Valid formats: <HH>:<MM>am OR <HH>:<MM>pm
data.createLocation.location.businessHours[].typestringrequiredType of business hours (e.g., OPEN, CLOSED, OPEN_24x7)
OPENOPEN_24x7CLOSED
data.createLocation.location.businessHours[].specialDatestringoptionalDay should be SPECIAL. Regular hours is mandatory. Regular hours is mandatory for special hours to be allowed
data.createLocation.location.citystringrequired
data.createLocation.location.countryIsostringrequired
data.createLocation.location.customAttributesarray of objectrequired
data.createLocation.location.customAttributes[].archivedbooleanoptional
data.createLocation.location.customAttributes[].enumValuesarray of stringoptional
data.createLocation.location.customAttributes[].namestringoptional
data.createLocation.location.customAttributes[].slugstringoptional
data.createLocation.location.customAttributes[].typestringoptional
data.createLocation.location.customAttributes[].valuearray of stringoptional
data.createLocation.location.databaseIdintegerrequired
data.createLocation.location.descriptionstringrequired
data.createLocation.location.facebookUrlstringoptional
data.createLocation.location.folderIdstringrequired
data.createLocation.location.folderNamestringrequired
data.createLocation.location.googleAdsPhonestringrequired
data.createLocation.location.googleplusUrlnullrequired
data.createLocation.location.hideAddressbooleanrequired
data.createLocation.location.idstringrequired
data.createLocation.location.instagramUrlstringoptional
data.createLocation.location.isRestaurantbooleanoptional
data.createLocation.location.latitudenumberrequired
data.createLocation.location.linkedinUrlstringoptional
data.createLocation.location.locationPhotosarray of stringrequired
data.createLocation.location.longitudenumberrequired
data.createLocation.location.moreHoursarray of stringrequired
data.createLocation.location.namestringrequired
data.createLocation.location.offeringsUrlstringoptional
data.createLocation.location.ownerEmailstringrequired
data.createLocation.location.ownerNamestringrequired
data.createLocation.location.packagestringrequired
data.createLocation.location.paymentMethodsarray of stringrequired
data.createLocation.location.phonestringrequired
data.createLocation.location.pinterestUrlstringrequired
data.createLocation.location.planIdintegerrequired
data.createLocation.location.planNamestringrequired
data.createLocation.location.postalCodestringrequired
data.createLocation.location.publisherAttributesarray of stringrequired
data.createLocation.location.reservationUrlstringrequired
data.createLocation.location.serviceItemsarray of stringrequired
data.createLocation.location.stateIsostringrequired
data.createLocation.location.storeIdnullrequired
data.createLocation.location.streetstringrequired
data.createLocation.location.street1stringrequired
data.createLocation.location.subCategoryobjectrequired
data.createLocation.location.subCategory.databaseIdintegerrequired
data.createLocation.location.subCategory.idstringrequired
data.createLocation.location.subCategory.namestringrequired
data.createLocation.location.subCategory.primarybooleanrequired
data.createLocation.location.subCategoryIdintegerrequired
data.createLocation.location.subCategoryNamestringrequired
data.createLocation.location.taglinestringrequired
data.createLocation.location.tagsarray of stringrequired
data.createLocation.location.temporarilyClosedbooleanrequired
data.createLocation.location.tiktokUrlnullrequired
data.createLocation.location.toplineMessagenullrequired
data.createLocation.location.toplineMessageTextnullrequired
data.createLocation.location.twitterUrlstringrequired
data.createLocation.location.videosarray of stringrequired
data.createLocation.location.yearOfIncorporationintegerrequired
data.createLocation.location.youtubeUrlnullrequired
data.createLocation.location.placeActionLinksarray of objectoptional
data.createLocation.location.placeActionLinks[].placeActionTypestringrequired
FOOD_ORDERING FOOD_ORDERINGONLINE_APPOINTMENTAPPOINTMENTDINING_RESERVATIONFOOD_DELIVERYFOOD_TAKEOUTSHOP_ONLINE
data.createLocation.location.placeActionLinks[].uristringrequired
data.createLocation.location.placeActionLinks[].isPreferredbooleanoptional
data.createLocation.location.placeActionLinks[].namestringoptional
data.createLocation.location.placeActionLinks[].submissionStatusstringoptional
data.createLocation.location.placeActionLinks[].submissionMessagestringoptional
data.createLocation.location.placeActionLinks[].lastSubmittedAtstringoptional
data.createLocation.location.placeActionLinks[].isEditablestringoptional
data.createLocation.location.discoveredPlaceActionLinksarray of objectoptional
data.createLocation.location.discoveredPlaceActionLinks[].placeActionTypestringrequired
data.createLocation.location.discoveredPlaceActionLinks[].uristringrequired
data.createLocation.location.discoveredPlaceActionLinks[].isPreferredbooleanrequired
data.createLocation.location.discoveredPlaceActionLinks[].namestringrequired
data.createLocation.location.discoveredPlaceActionLinks[].providerTypestringrequired
data.createLocation.location.discoveredPlaceActionLinks[].isEditablebooleanrequired
data.createLocation.successbooleanoptionalIndicates whether the location creation was successful.
data.createLocation.warningsarray of stringoptionalList of warnings generated during the request processing, if any.
messagestringoptionalResponse message indicating the result of the operation.