AddLocation

This method allows you to create a new location.

You can create an associated LocationAdmin user for this location by specifying both UserName and Password on the location record.

Return Value: LocRslt

Notes:

  • In lieu of providing the Client Id and Api Key, a call may be made to AuthenticateClient in the Lead web service with those credentials, and the resultant security token added to the Request Header under the key "ClientToken".
  • Location Name is required.
  • Active flag cannot be null and should be set to true in most cases.
  • Internet location cannot be null and should be set to false in most cases.
  • Country ID is required. (The country ID for US is 1; Canada is 2. For other countries, see the GetAllCountries() call.)
  • State ID is required for US and Canada. For convenience, you can specify StateAbbr (e.g. “NJ”) instead of the StateId (which is our numeric ID.)
  • ClientId, if specified in the location, will be overwritten with the id of the currently-authenticated client.
  • A “Services” array can be passed in, and must contain one record for each service that applies to this location. The only field that needs to be set on the LocationService record is the ServiceID. The two existing services are Lead Manager (Service ID 1) and Store Locator (Service ID 2).
  • An “Attributes” array can be passed in. AttributeId must be specified, and must correspond to a valid attribute ID for this client. Use GetAttributes() to retrieve a list of valid attributes. One of TextValue, NumericValue, MemoValue, BoolValue, or OptionID must be specified, corresponding to the data type for the specified attribute.
  • A “Categories” array can be passed in. The CategoryId must be set on each record, to a valid category ID for this client. (Specifying third-party category ID’s is not supported.)
  • If you do not use sub-categories, this is straightforward. Just specify the categories you want assigned to this location.
  • If you do use sub-categories, please note that, if you select a sub-category, then all ancestor categories will also be selected automatically when the location is saved. For instance, if you have a category “Meat” with sub-categories “Bacon” and “Turkey”, selecting bacon will automatically select meat. Selecting meat, on the other hand, will not automatically select bacon and turkey.
  • You can retrieve a list of valid categories via the GetCategories() method, and you can retrieve your category tree via the GetCategoryTree() method.
  • A “Territories” array can be passed in. The TerritoryId field must be set on each record, to a valid territory ID for this client. You can retrieve a list of valid territories via the GetTerritories() method.
  • A “BusinessHours” object can be passed in. You should specify a valid time zone ID. You can get a list of time zones via the GetTimeZones() method. For each of the Open and Closed fields, you need to pass in a valid DateTime value, but the date portion is ignored. If a location is closed on a given day, pass in NULL for both Open and Close values.
  • A “RestLocationSocialMedia” object can be passed in. This can be used to identify social media ID's for services such as Facebook, Yelp, Twitter, Google Plus, Pinterest and Yelp.
  • A "RestLocationSEO" object can be passed in, which allows an SEO title and meta description to be provided for the location.
  • A "RestLocationImage" object can be passed in, which is an array of image URL's that will be used on the landing page for the location.

Exception conditions:
This call, and other POST calls, will set the location ID in the LocRslt structure to a negative number on failure. Here are the values related to this method:

-1: invalid credentials (API key and/or client ID)
-2: validation failure (see errorMsg for details)
-3: client has reached maximum # of allowable locations for license type
-5: exception while creating user (see errorMsg for details)

Note that, if an error occurs while deserializing the JSON location object, the system is not capable of passing back a well-formatted error. In this case, you will get a 400 error code and a detailed “request error” from the .Net JSON deserializer.

Language
Click Try It! to start a request and see the response here!