> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.hellotracks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a place

> Creates a place for the company. Workers only when the company allows workersCreatePlaces. Without teams the place goes to the creator's teams; without a location the address is geocoded in the background. Visits of the last 30 days that match the new place are labeled with it.



## OpenAPI

````yaml v1/openapi.json POST /places
openapi: 3.1.0
info:
  title: Hellotracks REST API
  version: '1'
  description: >-
    Plain REST resources over HTTPS, for tools, automations and services. The ht
    command line is built on it.
  contact:
    email: api@hellotracks.com
servers:
  - url: https://api.hellotracks.com/v1
security:
  - ApiKey: []
tags:
  - name: Sign-up and sign-in
    description: >-
      Create a company or get an API key by an emailed code, without a key; and
      check which account a key belongs to.
  - name: Company
    description: The company the API key belongs to, with its settings and teams.
  - name: Members
    description: 'The people in the company: admins, operators and workers.'
  - name: API keys
    description: 'The company''s API keys: list, create, revoke and delete.'
  - name: Jobs
    description: 'Jobs: work at a location on a date, assigned to a member.'
  - name: Places
    description: 'Places: customer sites and other saved locations with a check-in radius.'
  - name: Zones
    description: 'Zones: the company''s geofences.'
  - name: Routing
    description: Route optimization for one member's day.
  - name: ETA pages
    description: >-
      Live ETA pages (eta.page links) that show a job's recipient when the
      worker arrives.
  - name: Maps
    description: Rendered maps as GeoJSON, and public map share links.
  - name: Timesheets
    description: Clock-in and clock-out entries of members, with totals, and editing them.
  - name: Forms
    description: >-
      Form templates, submitted forms, attachments for file and image fields,
      and forms linked to places and jobs.
  - name: Alerts
    description: >-
      Alert rules (configs) that watch members, places and zones, and the alerts
      (instances) they raised.
  - name: Reports
    description: >-
      Reports: the newer reporting API (catalog, preview, run, saved) and the
      older one (types, generate, jobs, uploads, recurring).
  - name: Webhooks
    description: URLs Hellotracks calls when jobs, check-ins, clock-ins or alerts happen.
paths:
  /places:
    post:
      tags:
        - Places
      summary: Create a place
      description: >-
        Creates a place for the company. Workers only when the company allows
        workersCreatePlaces. Without teams the place goes to the creator's
        teams; without a location the address is geocoded in the background.
        Visits of the last 30 days that match the new place are labeled with it.
      operationId: createPlace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaceInput'
            example:
              name: Ferry Building
              address: 1 Ferry Building, San Francisco, CA 94111
              radius: 100
              location:
                lat: 37.7955
                lng: -122.3937
              teams:
                - 1
              extendedData:
                Gate code: '1234'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - error
                  - meta
                properties:
                  data:
                    type: object
                    required:
                      - place
                    properties:
                      place:
                        $ref: '#/components/schemas/Place'
                  error:
                    type: 'null'
                  meta:
                    $ref: '#/components/schemas/Meta'
              example:
                data:
                  place:
                    id: p1q2r3
                    type: place
                    name: Ferry Building
                    address: 1 Ferry Building
                    email: frontdesk@example.com
                    phone: '+14155550103'
                    city: San Francisco
                    postalCode: '94111'
                    state: CA
                    countryCode: US
                    color: '#3366CC'
                    radius: 100
                    location:
                      lat: 37.7955
                      lng: -122.3937
                    teams:
                      - 1
                      - 3
                    linkedForms: []
                    extendedData:
                      Gate code: '1234'
                      Customer no: C-88
                error: null
                meta:
                  path: /v1/places
                  method: POST
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    PlaceInput:
      type: object
      additionalProperties: false
      description: >-
        Place fields. Unknown fields are refused with 400. On update only the
        fields sent change.
      properties:
        name:
          type: string
        address:
          type: string
          description: Geocoded in the background on create when no location is given.
        email:
          type: string
        phone:
          type: string
        city:
          type: string
        postalCode:
          type: string
        state:
          type: string
        countryCode:
          type: string
        color:
          type: string
        teams:
          type: array
          items:
            type: integer
          description: >-
            Team numbers. On create, without teams the place goes to the
            creator's teams.
        radius:
          type: integer
          description: Check-in radius in meters.
        location:
          type: object
          required:
            - lat
            - lng
          properties:
            lat:
              type: number
              format: double
            lng:
              type: number
              format: double
        extendedData:
          type: object
          additionalProperties:
            type:
              - string
              - number
              - boolean
              - 'null'
          description: >-
            Custom fields. Merged into the place's current fields: names sent
            get the value (stored as text), names sent as null are removed,
            names not sent stay.
      example:
        name: Ferry Building
        address: 1 Ferry Building, San Francisco, CA 94111
        radius: 100
        location:
          lat: 37.7955
          lng: -122.3937
        teams:
          - 1
        extendedData:
          Gate code: '1234'
    Place:
      type: object
      required:
        - id
        - type
        - radius
        - location
        - teams
        - linkedForms
        - extendedData
      properties:
        id:
          type: string
        type:
          type: string
          const: place
        name:
          type: string
        address:
          type: string
        email:
          type: string
        phone:
          type: string
        city:
          type: string
        postalCode:
          type: string
        state:
          type: string
        countryCode:
          type: string
        color:
          type: string
        radius:
          type: integer
          description: Check-in radius in meters.
        location:
          type: object
          properties:
            lat:
              type: number
              format: double
            lng:
              type: number
              format: double
        teams:
          type: array
          items:
            type: integer
          description: Team numbers the place belongs to.
        linkedForms:
          type: array
          items:
            $ref: '#/components/schemas/JobLinkedForm'
        extendedData:
          type: object
          additionalProperties:
            type: string
          description: Custom fields of the place, name to value.
      example:
        id: p1q2r3
        type: place
        name: Ferry Building
        address: 1 Ferry Building
        email: frontdesk@example.com
        phone: '+14155550103'
        city: San Francisco
        postalCode: '94111'
        state: CA
        countryCode: US
        color: '#3366CC'
        radius: 100
        location:
          lat: 37.7955
          lng: -122.3937
        teams:
          - 1
          - 3
        linkedForms: []
        extendedData:
          Gate code: '1234'
          Customer no: C-88
    Meta:
      type: object
      properties:
        path:
          type: string
          description: The request path, without /v1.
          example: /jobs
        method:
          type: string
          example: GET
    JobLinkedForm:
      type: object
      properties:
        id:
          type: string
          description: Form template id.
        title:
          type: string
    ErrorEnvelope:
      type: object
      properties:
        data:
          type: 'null'
        error:
          $ref: '#/components/schemas/Error'
        meta:
          $ref: '#/components/schemas/Meta'
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Stable error code for programs.
          enum:
            - invalid_request
            - invalid_format
            - invalid_data
            - invalid_api_key
            - unknown_user
            - authentication_failed
            - forbidden
            - not_found
            - already_exists
            - throttled
            - not_ready
            - clock_invalid
            - force_logout
            - internal_error
            - unknown_error
        message:
          type: string
          description: Why it failed, for people.
  responses:
    BadRequest:
      description: The request is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            data: null
            error:
              code: invalid_request
              message: date must be YYYY-MM-DD
            meta:
              path: /jobs
              method: GET
    Unauthorized:
      description: The API key is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            data: null
            error:
              code: invalid_api_key
              message: Invalid Hellotracks API key.
            meta:
              path: /jobs
              method: GET
    Forbidden:
      description: The key may not do this.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            data: null
            error:
              code: forbidden
              message: No permission.
            meta:
              path: /jobs
              method: GET
    TooManyRequests:
      description: Too many requests; slow down.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            data: null
            error:
              code: throttled
              message: Too many requests.
            meta:
              path: /jobs
              method: GET
    ServerError:
      description: Hellotracks failed; retry later.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            data: null
            error:
              code: internal_error
              message: Hellotracks API is temporarily unavailable.
            meta:
              path: /jobs
              method: GET
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: API-Key
      description: >-
        Your API key, from More → API & Integrations in the dashboard, or from
        ht signup / ht auth login.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.