REST API: Add Locations

Last Updated: February 12, 2019

Description

Add one or more locations to 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 POST
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 (Only one of the following properties is required to create a location.)

addr1:
String. The first line of the street for the address.
addr2:
String. The second line of the street for the address.
city:
String. The city of the address.
state:
String. The state of the address.
zip:
String. The postal code for the address.
county:
String. The country of the address.

Optional Location properties

For a full list of the properties that may be set on a location, see the Location object.

Status Codes

Each location that is created will come back with a _status_code and _status_message that will indicate whether the location was created successfully. If there was a problem creating 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 created 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

Create two new locations. One of them linked to an existing jobcode.

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

## contents of the tsjobcode_create.json file are:
{
 "data":
  [
    {
     "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 front door",
     "linked_objects": {
        "jobcodes": [
           3656485
        ]
     }
    },
    {
     "addr1": "7 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": "Created",
                "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": 0,
                "longitude": 0,
                "place_id": "",
                "place_id_hash": "",
                "label": "TSheets HQ",
                "notes": "Please use the front door",
                "geocoding_status": "none",
                "created": "2018-12-18T18:01:01+00:00",
                "last_modified": "2018-12-18T18:01:01+00:00",
                "linked_objects": {
                    "jobcodes": [
                        3656485
                    ]
                },
                "geofence_config_id": null
            },
            "2": {
                "_status_code": 200,
                "_status_message": "Created",
                "id": 742415,
                "addr1": "7 Any Street",
                "addr2": "",
                "city": "Meridian",
                "state": "ID",
                "zip": "83646",
                "formatted_address": "7 Any Street, Meridian, ID 83646",
                "country": "US",
                "active": true,
                "latitude": 0,
                "longitude": 0,
                "place_id": "",
                "place_id_hash": "",
                "label": "Any House on Any Street",
                "notes": "Beware the dog!",
                "geocoding_status": "none",
                "created": "2018-12-18T18:01:01+00:00",
                "last_modified": "2018-12-18T18:01:01+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": "Gutter Cleaning",
                "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": [
                    742413
                ]
            }
        }
    }
}