# Location Attributes

Source: https://developer.synup.com/locations/attributes

## Overview

A Location represents a physical business location in your account. It is the starting point for accessing and harnessing the various endpoints the API has to offer.

### Location Object
The following table details all available fields for Location objects. Fields marked as mandatory are required when creating or updating locations.

####   Core Attributes

|  Attribute  |  Type  |  Description  |  Read Only  |  Required for <br>Create  |  Required for <br>Update  |
| --- | --- | --- | --- | --- | --- |
|  `id`  |  String  |  Unique identifier in Base64<br>encoded format.<br> Eg: `Location:<Location ID>` <br> `TG9jYXRpb246MTIzNDU=`  |  -  |  ✗  |  ✓  |
|  `name`  |  String  |  Business name  |  -  |  ✓  |  -  |
|  `storeId`  |  String  |  Custom store identifier  |  -  |  -  |  -  |
|  `subCategoryId`  |  Integer  |  Business primary category identifier.<br> Refer to [Categories Endpoint](/api/locations/get-sub-categories-and-additional-categories)<br>for valid primary categories.<br> |  -  |  ✓  |  -  |
|  `subCategoryName`  |  String  |  Name of business subcategory<br>( Primary)  |  ✓  |  -  |  -  |
|  `additionalCategoryIds`  |  Integer  |  Additional category classifications.<br> Refer to [Categories Endpoint](/api/locations/get-sub-categories-and-additional-categories).<br> Supports up to 9 categories.<br> Categories with primary flag<br>as true or false can be used.<br> |  -  |  -  |  -  |

####   Address Information

|  Attribute  |  Type  |  Description  |  Read Only  |  Required for<br>Create  |  Required for<br>Update  |
|:------------------|:---------|:---------------------------------|:---------:|:------------------:|:------------------:|
|  `street`  |  String  |  Street address  |  -  |  ✓  |  -  |
|  `street1`  |  String  |  Specify additional address information<br> |  -  |  -  |  -  |
|  `city`  |  String  |  City name  |  -  |  ✓  |  -  |
|  `postalCode`  |  String  |  Postal/ZIP code  |  -  |  ✓  |  -  |
|  `stateIso`  |  String  |  State/Province ISO code [**¹**](#notes)  |  -  |  ✓  |  -  |
|  `countryIso`  |  String  |  Country ISO code [**¹**](#notes).<br>Cannot be updated  |  -  |  ✓  |  ✗  |
| `countryCode`  |  String  |  Country code [**¹**](#notes).<br>Cannot be updated  |  ✓  |  ✗  |  ✗  |
|  `latitude`  |  String  |  Geographic latitude  |  ✓  |  ✗  |  ✗  |
|  `longitude`  |  String  |  Geographic longitude  |  ✓  |  ✗  |  ✗  |
|  `hideAddress`  |  Boolean  |  `true` indicates a Service Area<br>Business  |  -  |  -  |  -  |

####  Contact Information

|  Attribute  |  Type  |  Description  |  Read Only  |  Required for <br>Create  |  Required for <br>Update  |
|:------------------|:---------|:---------------------------------|:---------:|:------------------:|:------------------:|
|  `phone`  |  String  |  Business phone number. [**Ref here**](#phone-number-formats)  |  -  |  ✓  |  -  |
|  `ownerEmail`  |  String  |  Business owner's email  |  -  |  -  |  -  |
|  `ownerName`  |  String  |  Business owner's name  |  -  |  -  |  -  |
|  `googleAdsPhone`  |  String  |  Phone number used exclusively<br>for Google Ads <br>[**Ref here**](#phone-number-formats)<br> |  -  |  -  |  -  |
|  `additionalPhones`  |  Array of Strings  |  Additional phone numbers (Supported<br>only for Google) <br>[**Ref here**](#phone-number-formats)<br> |  -  |  -  |  -  |

####   Business Details
|  Attribute  |  Type  |  Description  |  Read Only  |  Required for<br>Create  |  Required for<br>Update  |
|:---------------------|:----------|:------------------------------|:---------:|:------------------:|:------------------:|
|  `businessHours`  |  Object  |  Business Hours. Refer to the<br>[**schema**](#business-hours-schema)<br>for details. <br> Regular hours required to add<br>special hours.  |  -  |  -  |  -  |
|  `temporarilyClosed`  |  Boolean  |  Set `true` to mark the location<br>as temporarily  <br>closed and hide business hours<br> |  -  |  -  |  -  |
|  `description`  |  String  |  Business description. Min 200<br>char - 1500 char  |  -  |  ✓  |  -  |
|  `tagline`  |  String  |  Business tagline  |  -  |  -  |  -  |
|  `yearOfIncorporation`  |  Integer  |  Business establishment year  |  -  |  -  |  -  |
|  `paymentMethods`  |  String[]  |  Accepted payment methods. [**Ref here**](#supported-payment-methods)<br> |  -  |  -  |  -  |

####  Online Presence

|  Attribute  |  Type  |  Description  |  Read Only  |  Required for<br>Create  |  Required for<br>Update  |
|:------------------|:---------|:---------------------------------|:---------:|:------------------:|:------------------:|
|  `bizUrl`  |  String  |  Business website URL  |  -  |  -  |  -  |
|  `facebookUrl`  |  String  |  Facebook page URL  |  -  |  -  |  -  |
|  `twitterUrl`  |  String  |  Twitter profile URL  |  -  |  -  |  -  |
|  `linkedinUrl`  |  String  |  LinkedIn page URL  |  -  |  -  |  -  |
|  `youtubeUrl`  |  String  |  YouTube page URL  |  -  |  -  |  -  |
|  `instagramUrl`  |  String  |  Instagram page URL  |  -  |  -  |  -  |
|  `tiktokUrl`  |  String  |  TikTok page URL  |  -  |  -  |  -  |
|  `pinterestUrl`  |  String  |  Pinterest page URL  |  -  |  -  |  -  |
|  `videos`  |  String[]  |  List of video URLs  |  -  |  -  |  -  |
|  `locationPhotos`  |  Object  |  Returns `LOGO` and `COVER` photos<br>of the location.  |  -  |  -  |  -  |

####  Publishing Configuration

| Attribute | Type | Description | Read Only | Required for<br>Create | Required for<br>Update |
|:---------------------------|:----------|:------------------------------|:---------:|:------------------:|:------------------:|
| `enabledSiteIds` | Integer[] | Specify site IDs where business<br>details should be published.<br><br>Choose from sites in the location<br>plan. [**Refer to Plan Sites**](/api/locations/get-site-details-for-your-plan) | - | - | - |
| `submissionDisabledSiteIds` | Integer[] | Sites where publishing is disabled.<br>[**Refer to Plan Sites**](/api/locations/get-site-details-for-your-plan) | - | - | - |

####  System Fields

| Attribute | Type | Description | Read Only | Required for<br>Create | Required for<br>Update |
|:---------------------|:----------|:------------------------------|:---------:|:------------------:|:------------------:|
| `databaseId` | Integer | Internal reference ID | ✓ | - | - |
| `archivalScheduledAt` | Timestamp | Timestamp set when an archival<br>request is initiated<br>for the location | ✓ | - | - |
| `archivedAt` | Timestamp | Timestamp marking the actual<br>archival of the location,<br>typically at the end of the billing<br>cycle | ✓ | - | - |
| `tenure` | String | For multi-subscription accounts,<br>specify the subscription<br>tenure. Example: Monthly. [**Refer to Subscriptions**](/api/locations/list-active-subscriptions) | - | ⚑ | - |

####  Restaurant and Food Business-Specific Fields

|  **Attribute**  |  **Type**  |  **Description**  |  **Read Only**  |  **Required for<br>Create**  |  **Required for<br>Update**  |
|:---------------------------------------------------|:------------|:---------------------------------------------------------|:-----------:|:------------------:|:------------------:|
|  `bookingUrl`  |  String  |  URL for booking services related<br>to the location (Applicable for<br>restaurant or food businesses)<br> |  -  |  -  |  -  |
|  `offeringsUrl`  |  String  |  URL showcasing menus (Applicable<br>for restaurant or food businesses)<br> |  -  |  -  |  -  |
|  `reservationUrl`  |  String  |  URL for reservations (Applicable<br>for restaurant or food businesses)<br> |  -  |  -  |  -  |

####  Categorization & Organization

| Attribute             | Type      | Description                   | Read Only | Required for<br>Create | Required for<br>Update |
|:---------------------|:----------|:------------------------------|:---------:|:------------------:|:------------------:|
| `tags`         | Array of Strings   | Keywords associated with the<br>location for categorization or<br>search purposes         | -         | -                  | -                  |
| `folderId`| String `<UUID>` |  Identifier for organizing locations<br>into folders (Retrieve folders<br>via query)     | -         | -                  | -                  |

####  Place Action Links

 Google place action links are the action buttons shown on the Business Profile (order, book, reserve, and more). See [**Managing Place Action Links**](#managing-place-action-links) for the write model and how to add a discovered link.

|  Attribute  |  Type  |  Description  |  Read Only  |  Required for<br>Create  |  Required for<br>Update  |
|:------------------|:---------|:---------------------------------|:---------:|:------------------:|:------------------:|
|  `placeActionLinks`  |  Array of Objects  |  Google action links you manage.<br> See [**Managing Place Action Links**](#managing-place-action-links).<br> |  -  |  -  |  -  |
|  `discoveredPlaceActionLinks`  |  Array of Objects  |  Links Google discovered on<br> the profile. Read-only;<br> [**add them**](#add-a-discovered-link)<br>to manage.  |  ✓  |  -  |  -  |

#### Notes

¹ Refer to the [Places API](/api/locations/get-a-list-of-supported-countries-and-their-states) for valid ISO codes
² Refer to [Plan Sites](/api/locations/get-site-details-for-your-plan) for available site IDs
³ Only required for accounts with multiple subscriptions. Find about subscription
⁴ Get Primary Categories and Additional Categories [here](/api/locations/get-sub-categories-and-additional-categories)
⚑ Conditionally required

##### Business hours schema

##### **Phone Number Formats**
[Back to Contact info](#contact-information)
- Must follow the international **E.164 format**. [Ref here.](https://www.twilio.com/docs/glossary/what-e164)
- Do not include the `+` sign or country code.
- Remove parentheses and special characters.
- Example:
  - **Incorrect**: `(123)-456-7890`, `+1-123-456-7890`
  - **Correct**: `1234567890`

##### **Supported Payment Methods**

#### Subcategories and Additional Categories

##### SubCategory
- A **Subcategory** can be considered as the **primary category** for the location.
- Only categories where `PRIMARY` is set to `true` are considered **SubCategories**.

##### AdditionalCategory
- An **Additional Category** can be considered as the **secondary category** for the location.
- Categories where `PRIMARY` is either `true` or `false` are considered **AdditionalCategories**.

#### Managing Place Action Links

Place action links are the action buttons Google shows on a Business Profile (order online, book, reserve, and so on). Manage them through the `placeActionLinks` array on the **Create a new business location** and **Update business location** endpoints.

##### Link object

|  Field  |  Type  |  Description  |
| --- | --- | --- |
|  `placeActionType`  |  Enum  |  One of `APPOINTMENT`, `ONLINE_APPOINTMENT`, `DINING_RESERVATION`,<br> `FOOD_ORDERING`, `FOOD_DELIVERY`, `FOOD_TAKEOUT`, `SHOP_ONLINE`.  |
|  `uri`  |  String  |  Destination URL for the action.  |
|  `isPreferred`  |  Boolean  |  Marks the preferred link for that type. At most one per type.  |
|  `action`  |  Enum  |  `add` (default) to add or update, or `delete` to remove.  |
|  `name`  |  String  |  Identifier returned by the read endpoints once synced to Google. `null` until synced.  |
|  `submissionStatus`  |  String  |  Sync status with Google. `null` until synced.  |

>  **Write model — append / upsert.** Only the links you include are affected; links you leave out stay unchanged. A link is matched by `name` when present, otherwise by `placeActionType` + `uri`.

#####  Add a link

Send a `placeActionLinks` entry with `action` set to `add` (the default), plus `placeActionType` and `uri`. Set `isPreferred` to `true` to make it the preferred link for its type.

```json
{
  "input": {
    "placeActionLinks": [
      {
        "placeActionType": "FOOD_ORDERING",
        "uri": "https://order.example.com",
        "isPreferred": true,
        "action": "add"
      }
    ]
  }
}
```

#####  Edit a link

There is no in-place update. In the same **Update business location** call, send the current link with `action` set to `delete`, then the new link with `action` set to `add`. The delete is matched by `name` when you have it, otherwise by `placeActionType` + `uri`.

```json
{
  "input": {
    "placeActionLinks": [
      {
        "placeActionType": "FOOD_ORDERING",
        "uri": "https://old-order.example.com",
        "action": "delete"
      },
      {
        "placeActionType": "FOOD_ORDERING",
        "uri": "https://new-order.example.com",
        "isPreferred": true,
        "action": "add"
      }
    ]
  }
}
```

#####  Add a discovered link

Links Google finds on its own are returned read-only under `discoveredPlaceActionLinks`. To take ownership of one, re-add it through `placeActionLinks` using the same `placeActionType` and `uri` with `action` set to `add`. After the write it moves under `placeActionLinks`; its `name` and `submissionStatus` stay `null` until it syncs to Google.

```json
{
  "input": {
    "placeActionLinks": [
      {
        "placeActionType": "FOOD_ORDERING",
        "uri": "https://discovered-order.example.com",
        "action": "add"
      }
    ]
  }
}
```

#### Common Errors while creating a location

|  **Error**  |  **Description**  |
| --- | --- |
|  **Insufficient Permissions**  |  The API key or user account does not have the required permissions to perform this action.  |
|  **Minimum 200 Characters for Business Description**  |  The business description must be at least 200 characters long.  |
|  **Must Be a Supported Country**  |  The specified country is not supported. Refer to the list of allowed countries.  |
|  **Not a Valid State**  |  The provided state is invalid or does not exist for the selected country.  |
|  **Invalid Postal Code**  |  The postal code format is incorrect or does not match the country’s requirements.  |
|  **Invalid Phone Number**  |  The phone number format is invalid or does not meet country-specific guidelines.  |
|  **Must Be a Valid Year (for Year of Incorporation)**  |  The year of incorporation must be a valid four-digit year.  |
|  **storeId Has Already Been Taken**  |  The provided `storeId` is already in use. Please use a unique identifier.  |