REST API: Edit Locations

Last Updated: January 24, 2019

Description

Edit one or more locations in your company. We will handle batches of up to 50 locations at a time. More than 50 locations will result in a 413 - Request entity too large error.

Resource Information

HTTP Method PUT
Endpoint https://rest.tsheets.com/api/v1/locations
Authentication Token header required. See authentication section
Request format json object. Pass an array of location objects as the value to a 'data' property (see example below).
Response format json
Response object Location

Location properties

When editing a location, you must uniquely identify the location by passing in its id property. Other properties defined on a location object may be passed in to the request with a new value in order to change it. If the value passed in is the same as it was previously, or if a particular property is not passed in at all, it will be ignored. Certain properties (created, last_modified, etc.) are set automatically by the system and may not be modified.

NOTE: You cannot edit a location that is archived. You must restore the location first. It is permissible to make an edit to a location and restore it in one edit request (i.e. change active to 1 and change the locations country in one step).

Status Codes

Each location that is edited will come back with a _status_code and _status_message that will indicate whether the location was edited successfully. If there was a problem editing a location, there may also be an additional field, _status_extra, which will contain more details about the failure.

_status_code Meaning
200 OK. Location was edited successfully.
417 Expectation Failed. Something was wrong or missing with the properties supplied for this location. See the _status_extra value for more detail.

Examples

Change some information for each of these locations as well as unlink one of the location from a jobcode.
Note: When attempting to run the example code below you will need to substitute the name and id listed and instead use locations associated with your TSheets account.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -H "Content-Type: application/json" -X PUT -i "https://rest.tsheets.com/api/v1/locations"

## contents of the locations_edit.json file are:
{
 "data":
  [
    {
     "id": 742413,
     "addr1": "235 E Colchester Dr",
     "addr2": "101",
     "city": "Eagle",
     "state": "ID",
     "zip": "83616",
     "country": "US",
     "formatted_address": "235 E Colchester Dr, Meridian, ID 83646",
     "active": true,
     "label": "TSheets HQ",
     "notes": "Please use the front door",
     "linked_objects": {
        "jobcodes": [
           
        ]
     }
    },
    {
     "id": 742415,
     "addr1": "8 Any Street",
     "addr2": "",
     "city": "Meridian",
     "state": "ID",
     "zip": "83646",
     "country": "US",
     "formatted_address": "7 Any Street, Meridian, ID 83646",
     "active": true,
     "label": "Any House on Any Street",
     "notes": "Beware the dog!"
    }
  ]
}



## RESPONSE
HTTP/1.1 200 OK
Content-Type: application/json

{
    "results": {
        "locations": {
            "1": {
                "_status_code": 200,
                "_status_message": "Updated",
                "id": 742413,
                "addr1": "235 E Colchester Dr",
                "addr2": "101",
                "city": "Eagle",
                "state": "ID",
                "zip": "83616",
                "formatted_address": "235 E Colchester Dr 101, Eagle, ID 83616",
                "country": "US",
                "active": true,
                "latitude": 43.6698951,
                "longitude": -116.3522866,
                "place_id": "",
                "place_id_hash": "c2ed7ff7a2abadf503d2ffd4f1736ca4",
                "label": "TSheets HQ",
                "notes": "Please use the front door",
                "geocoding_status": "complete",
                "created": "2018-12-18T18:01:01+00:00",
                "last_modified": "2018-12-18T18:24:56+00:00",
                "linked_objects": {},
                "geofence_config_id": null
            },
            "2": {
                "_status_code": 200,
                "_status_message": "Updated",
                "id": 742415,
                "addr1": "8 Any Street",
                "addr2": "",
                "city": "Meridian",
                "state": "ID",
                "zip": "83646",
                "formatted_address": "8 Any Street, Meridian, ID 83646",
                "country": "US",
                "active": true,
                "latitude": 43.6141813,
                "longitude": -116.4029894,
                "place_id": "",
                "place_id_hash": "c261737fbcc29174cdbc8fa2f62da13d",
                "label": "Any House on Any Street",
                "notes": "Beware the dog!",
                "geocoding_status": "complete",
                "created": "2018-12-18T18:01:01+00:00",
                "last_modified": "2018-12-18T18:25:51+00:00",
                "linked_objects": {},
                "geofence_config_id": null
            }
        }
    },
    "supplemental_data": {
        "jobcodes": {
            "3656485": {
                "id": 3656485,
                "active": true,
                "parent_id": 0,
                "assigned_to_all": true,
                "type": "regular",
                "billable": true,
                "billable_rate": 0,
                "short_code": "",
                "name": "A_Test_Of_Add_0",
                "created": "2018-10-31T15:15:25+0000",
                "last_modified": "2018-12-13T15:11:57+0000",
                "has_children": false,
                "required_customfields": [
                    326759
                ],
                "filtered_customfielditems": {
                    "326759": [
                        2207167
                    ]
                },
                "locations": []
            }
        }
    }
}