Create Location

The Create Location API allows you to create and update a location within Zenput.

Below is a sample call and a full description of input format, input parameters, and success and error output formats.

POST: /api/v3/locations/

$ curl -X POST \
  https://www.zenput.com/api/v3/locations/ \
    -H 'content-type: application/json' \
  -H 'X-API-TOKEN: your-api-token-goes-here' \
  -d '{
  "name": "Location name",
  "address": "5394 Banding Parkway",
  "city": "Richmond",
  "state": "VA",
  "zipcode": "23289",
  "country": "US",
  "email": "[email protected]",
  "phone": "703-233-1234",
  "external_key": "1234",
  "owners": [
    {
      "username": "[email protected]"
    }
  ],
  "teams": [
    {
      "name": "Team name"
    }
  ]
}'

Input format:

{
  "name": name,
  "address": address,
  "city": city,
  "state": state,
  "zipcode": zipcode,
  "country": country,
  "email": email,
  "phone": phone,
  "external_key": external_key,
  "lat": lat,
  "lon": lon,
  "time_zone": time_zone,
  "tags": [
    {
      "id": tag_id
    }
  ],
  "owners": [
    {
      "id": owner_id
    }
  ],
  "teams": [
    {
      "id": team_id
    }
  ]
}

Input parameters

Name

Required

Type

Description

name

Required

Text

Location's name

address

Required

Text

Location's address

city

Required

Text

Location's city

state

Required

State code or Text

Location's state. If country is United States (US), then state must be an ANSI state code https://en.wikipedia.org/wiki/List_of_U.S._state_and_territory_abbreviations

zipcode

No

Text

Location's zip code

country

No

Country code

Country code. Any ISO 3166-1 alpha-2 code (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)

Defaults to 'US'

email

No

Text

Location's email address

phone

No

Text

Phone number. It must be a valid phone number for the given country. Country code prefix is not required.

external_key

No

Text

A value to uniquely identify this location, E.g. it can be the company's location ID. If provided, it needs to be unique.

lat

No

Integer

The latitude of the location, if not provided, it will automatically be set based on the available location information.

lon

No

Integer

The longitude of the location, if not provided, it will automatically be set based on the available location information.

time_zone

No

Timezone

Time zone of the location, if not provided, it will automatically be set based on the available location information. Value must be one of TZ column of https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List

tag_id

No

Integer

Id from an existing tag to assign to this location

owner_id

No

Integer

Id from an existing user, to assign as owner of this location.

team_id

No

Integer

Id from an existing team to set this location to be part of.

🚧

IDs must be from an existing resource

*_id parameters must be from already existing resources.

Output format, success

{
  "meta": {
    "status_code": 201
  },
  "data": {
    "id": 1,
    "name": "Location name",
    "address": "5394 Banding Parkway",
    "city": "richmond",
    "state": "VA",
    "zipcode": "23289",
    "country": "US",
    "email": "[email protected]",
    "phone": null,
    "external_key": "703-233-1234",
    "lat": 37.4315734,
    "lon": -78.6568942,
    "date_modified": "2020-11-05T20:50:38+00:00",
    "date_created": "2020-11-05T20:50:37+00:00",
    "time_zone": "America/New_York",
    "company": {
      "id": 1,
      "name": "Zenput",
      "features": []
    },
    "tags": [
      {
        "id": 1,
        "name": "Location tag",
        "is_editable": false
      }
    ],
    "owners": [],
    "teams": []
  }
}

Output format, failure

{
  "meta": {
    "status_code": 400
  },
  "errors": [
    {
      "field": "state",
      "message": "Please enter region or state.",
      "code": "invalid"
    }
  ]
}