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

# Create Geofence Monitor

> Create a geofence monitor for one vehicle, watched from its origin to its destination.

<Info>Identify the vehicle with `vehicle_id` if you have it, otherwise `vin` or the full license plate. Creating a monitor requires an active share agreement granting you `vehicle_location` access to that vehicle's fleet.</Info>


## OpenAPI

````yaml https://api.catenatelematics.com/v2/notifications/openapi.json post /v2/notifications/geofence-monitors
openapi: 3.1.0
info:
  title: Notifications Service - REST API
  description: Notifications Service REST API.
  version: 0.1.0
servers:
  - url: https://api.catenatelematics.com
    description: Catena Telematics API
security: []
tags:
  - name: Webhook Subscriptions
    description: >-
      Create and manage webhooks to subscribe to events and receive
      notifications when they occur.
  - name: Webhook Event Schemas
    description: Get the OpenAPI 3.0 schema for our versioned webhook events.
  - name: Webhook Events
    description: View available webhook events.
  - name: Geofence Monitors
    description: >-
      Watch one vehicle along a planned journey and receive an event as it
      departs and arrives at each stop. The monitor stops watching once it
      leaves its destination, is cancelled, or expires.
paths:
  /v2/notifications/geofence-monitors:
    post:
      tags:
        - Geofence Monitors
      summary: Create Geofence Monitor
      description: >-
        Create a geofence monitor for one vehicle, watched from its origin to
        its destination.
      operationId: create_geofence_monitor
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeofenceMonitorCreate'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeofenceMonitorRead'
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequest'
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Forbidden'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
          description: Not Found
        '405':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowed'
          description: Method Not Allowed
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conflict'
          description: Conflict
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnprocessableEntity'
          description: Unprocessable Entity
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequests'
          description: Too Many Requests
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
          description: Internal Server Error
      security:
        - Bearer:
            - geofence_monitor:create
components:
  schemas:
    GeofenceMonitorCreate:
      properties:
        webhook_group_id:
          type: string
          format: uuid
          title: Webhook Group ID
          description: >-
            The geofence_monitor.* subscription to deliver this monitor's events
            to. Returned when you create the subscription.
        name:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Name
          description: >-
            Your own label for this journey, for example a load or BOL number.
            Echoed on every event.
        vehicle_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Vehicle ID
          description: The Catena vehicle identifier.
        vin:
          anyOf:
            - type: string
            - type: 'null'
          title: VIN
          description: >-
            Vehicle Identification Number. 17 characters, A-Z excluding I, O and
            Q, and 0-9.
        license_plate_number:
          anyOf:
            - type: string
            - type: 'null'
          title: License Plate Number
          description: Must be sent together with the region and country.
        license_plate_region:
          anyOf:
            - type: string
            - type: 'null'
          title: License Plate Region
          description: Two letter state or province abbreviation, e.g. 'OH' or 'ON'.
        license_plate_country:
          anyOf:
            - type: string
            - type: 'null'
          title: License Plate Country
          description: Plate country code (ISO-3166-1 alpha-3, e.g., 'USA', 'CAN')
        origin:
          $ref: '#/components/schemas/GeofenceMonitorStopCreate'
          title: Origin
          description: >-
            Where the journey starts. Departure is detected on leaving this
            circle.
        destination:
          $ref: '#/components/schemas/GeofenceMonitorStopCreate'
          title: Destination
          description: >-
            Where the journey ends. Arriving here is the delivery; the monitor
            completes once the vehicle leaves destination, so the dwell can be
            measured.
        stops:
          items:
            $ref: '#/components/schemas/GeofenceMonitorStopCreate'
          type: array
          title: Intermediate Stops
          description: >-
            Planned stops between origin and destination, in travel order. Each
            one gets its own arrival and departure events.
        starts_at:
          type: string
          format: date-time
          title: Start Time
          description: >-
            When the journey is expected to start. Pings before this are
            ignored, so set it close to dispatch -- a monitor watching a truck
            still parked in the origin yard will record that as the origin
            arrival. Must include a UTC offset.
        expires_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Expires At
          description: >-
            When to stop watching. Must include a UTC offset. Both the default
            and the maximum are measured from starts_at, not from now, so
            booking a monitor early does not eat into the journey's window.
            Defaults to 3 days after starts_at, up to a maximum of 14 days.
      type: object
      required:
        - webhook_group_id
        - origin
        - destination
        - starts_at
      title: GeofenceMonitorCreate
      description: Geofence monitor create model.
      example:
        destination:
          latitude: 39.9612
          longitude: -82.9988
          radius_meters: 800
        expires_at: '2026-08-16T12:00:00Z'
        license_plate_country: USA
        license_plate_number: HMT-3570
        license_plate_region: OH
        origin:
          latitude: 40.7484
          longitude: -73.9857
          radius_meters: 200
        starts_at: '2026-08-14T12:00:00Z'
        stops:
          - latitude: 40.6084
            longitude: -75.4902
            radius_meters: 500
        vin: 1FUJGLDR7CSBF1234
        webhook_group_id: 0198c1f2-3a4b-7c5d-8e6f-0a1b2c3d4e5f
    GeofenceMonitorRead:
      properties:
        id:
          type: string
          format: uuid
          title: Geofence Monitor ID
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        webhook_group_id:
          type: string
          format: uuid
          title: Webhook Group ID
          description: >-
            The geofence_monitor.* subscription this monitor's events are
            delivered to
        fleet_id:
          type: string
          format: uuid
          title: Fleet ID
          description: The Catena fleet whose vehicle is being watched
        fleet_ref:
          anyOf:
            - type: string
            - type: 'null'
          title: Fleet Ref
          description: Your own reference for the fleet
        vehicle_id:
          type: string
          format: uuid
          title: Vehicle ID
          description: The Catena vehicle being watched
        vin:
          anyOf:
            - type: string
            - type: 'null'
          title: VIN
        license_plate_number:
          anyOf:
            - type: string
            - type: 'null'
          title: License Plate Number
        license_plate_region:
          anyOf:
            - type: string
            - type: 'null'
          title: License Plate Region
        license_plate_country:
          anyOf:
            - type: string
            - type: 'null'
          title: License Plate Country
        status:
          $ref: '#/components/schemas/GeofenceMonitorStatusEnum'
          title: Status
          description: >-
            The monitor's lifecycle status. Non-terminal means still being
            watched.
        current_stop_sequence:
          type: integer
          title: Current Stop Sequence
          description: Which stop is currently being watched
        stops:
          items:
            $ref: '#/components/schemas/GeofenceMonitorStopRead'
          type: array
          title: Stops
          description: The journey, in travel order
        starts_at:
          type: string
          format: date-time
          title: Start Time
          description: Pings before this are ignored.
        expires_at:
          type: string
          format: date-time
          title: Expires At
          description: >-
            When the watch ends. A monitor still ACTIVE past this is marked
            EXPIRED.
        cancelled_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Cancelled At
          description: When the partner cancelled the monitor
        completed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completed At
          description: When the vehicle departed the final stop, ending the watch
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the monitor was created
        updated_at:
          type: string
          format: date-time
          title: Updated At
          description: When the monitor last changed, including each stop transition
      type: object
      required:
        - id
        - webhook_group_id
        - fleet_id
        - vehicle_id
        - status
        - current_stop_sequence
        - starts_at
        - expires_at
        - created_at
        - updated_at
      title: GeofenceMonitorRead
      description: Geofence monitor read model
    BadRequest:
      properties:
        code:
          type: integer
          title: Code
          default: 400
        message:
          type: string
          title: Message
          default: Bad Request
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: BadRequest
    Unauthorized:
      properties:
        code:
          type: integer
          title: Code
          default: 401
        message:
          type: string
          title: Message
          default: Unauthorized
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: Unauthorized
    Forbidden:
      properties:
        code:
          type: integer
          title: Code
          default: 403
        message:
          type: string
          title: Message
          default: Forbidden
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: Forbidden
    NotFound:
      properties:
        code:
          type: integer
          title: Code
          default: 404
        message:
          type: string
          title: Message
          default: Not Found
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: NotFound
    MethodNotAllowed:
      properties:
        code:
          type: integer
          title: Code
          default: 405
        message:
          type: string
          title: Message
          default: Method Not Allowed
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: MethodNotAllowed
    Conflict:
      properties:
        code:
          type: integer
          title: Code
          default: 409
        message:
          type: string
          title: Message
          default: Conflict
        detail:
          anyOf:
            - type: string
            - type: 'null'
          title: Detail
      type: object
      title: Conflict
    UnprocessableEntity:
      properties:
        code:
          type: integer
          title: Code
          default: 422
        message:
          type: string
          title: Message
          default: Invalid Request Body
        detail:
          anyOf:
            - items:
                $ref: '#/components/schemas/ValidationErrorDetail'
              type: array
            - type: 'null'
          title: Detail
      type: object
      title: UnprocessableEntity
    TooManyRequests:
      properties:
        code:
          type: integer
          title: Code
          default: 429
        message:
          type: string
          title: Message
          default: Too Many Requests
        detail:
          anyOf:
            - $ref: '#/components/schemas/RetryAfterDetail'
            - type: 'null'
      type: object
      title: TooManyRequests
    InternalServerError:
      properties:
        message:
          type: string
          title: Message
          default: Internal Server Error
      type: object
      title: InternalServerError
    GeofenceMonitorStopCreate:
      properties:
        name:
          anyOf:
            - type: string
              maxLength: 255
            - type: 'null'
          title: Name
          description: >-
            Your own label for this stop, for example the facility name. Echoed
            on every event.
        latitude:
          type: number
          maximum: 90
          minimum: -90
          title: Latitude
          description: Latitude of the fence centre, in decimal degrees
        longitude:
          type: number
          maximum: 180
          minimum: -180
          title: Longitude
          description: Longitude of the fence centre, in decimal degrees
        radius_meters:
          type: number
          maximum: 1000
          minimum: 100
          title: Radius (meters)
          description: >-
            How close to the point counts as being at this stop, in metres. Size
            it to cover wherever trucks come to rest: the yard and the queue,
            not just the building.
          default: 100
      type: object
      required:
        - latitude
        - longitude
      title: GeofenceMonitorStopCreate
      description: A single fence as supplied by the partner.
      example:
        latitude: 39.9612
        longitude: -82.9988
        radius_meters: 200
    GeofenceMonitorStatusEnum:
      type: string
      enum:
        - active
        - completed
        - expired
        - cancelled
      title: GeofenceMonitorStatusEnum
      description: >-
        Enum for geofence monitor status.


        ``ACTIVE`` is the only non-terminal status: the tracker queries
        non-terminal monitors, so

        reaching any of the others is what ends the watch. There is no
        unsubscribe.


        Departure and arrival are per-stop, not per-journey.``COMPLETED`` means
        the last stop was reached.
    GeofenceMonitorStopRead:
      properties:
        id:
          type: string
          format: uuid
          title: Stop ID
        sequence:
          type: integer
          title: Sequence
          description: >-
            Position in the journey. 0 is the origin, the highest is the
            destination.
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        point:
          $ref: '#/components/schemas/Point'
          description: The centre of the fence, as a GeoJSON Point
        radius_meters:
          type: number
          title: Radius (meters)
        arrived_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Arrived At
          description: When the vehicle entered this stop's circle
        departed_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Departed At
          description: When the vehicle left this stop's circle
      type: object
      required:
        - id
        - sequence
        - point
        - radius_meters
      title: GeofenceMonitorStopRead
      description: Geofence monitor stop read model
    ValidationErrorDetail:
      properties:
        path:
          type: string
          title: Path
        input:
          type: string
          title: Input
        message:
          type: string
          title: Message
        error_type:
          type: string
          title: Error Type
      type: object
      required:
        - path
        - input
        - message
        - error_type
      title: ValidationErrorDetail
    RetryAfterDetail:
      properties:
        retry_after_seconds:
          type: integer
          title: Retry After Seconds
        message:
          type: string
          title: Message
      type: object
      required:
        - retry_after_seconds
        - message
      title: RetryAfterDetail
    Point:
      properties:
        bbox:
          anyOf:
            - prefixItems:
                - type: number
                - type: number
                - type: number
                - type: number
              type: array
              maxItems: 4
              minItems: 4
            - prefixItems:
                - type: number
                - type: number
                - type: number
                - type: number
                - type: number
                - type: number
              type: array
              maxItems: 6
              minItems: 6
            - type: 'null'
          title: Bbox
        type:
          type: string
          const: Point
          title: Type
        coordinates:
          anyOf:
            - $ref: '#/components/schemas/Position2D'
            - $ref: '#/components/schemas/Position3D'
          title: Coordinates
      type: object
      required:
        - type
        - coordinates
      title: Point
      description: Point Model
    Position2D:
      prefixItems:
        - type: number
          title: Longitude
        - type: number
          title: Latitude
      type: array
      maxItems: 2
      minItems: 2
    Position3D:
      prefixItems:
        - type: number
          title: Longitude
        - type: number
          title: Latitude
        - type: number
          title: Altitude
      type: array
      maxItems: 3
      minItems: 3
  securitySchemes:
    Bearer:
      type: oauth2
      flows:
        clientCredentials:
          refreshUrl: >-
            https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token
          scopes: {}
          tokenUrl: >-
            https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token
        authorizationCode:
          refreshUrl: >-
            https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token
          scopes: {}
          authorizationUrl: >-
            https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/auth
          tokenUrl: >-
            https://auth.catenatelematics.com/realms/catena/protocol/openid-connect/token

````

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