Samsara Addresses API
The Addresses API from Samsara — 2 operation(s) for addresses.
OpenAPI Specification
openapi: 3.0.1
info:
description: Gain greater visibility by connecting your fleets, equipment, sites, and people.
title: Samsara Addresses API
version: '2024-11-18'
servers:
- url: https://api.samsara.com/
- url: https://api.eu.samsara.com/
security:
- AccessTokenHeader: []
tags:
- name: Addresses
paths:
/addresses:
get:
description: "Returns a list of all addresses in an organization. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Read Addresses** under the Addresses category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
operationId: listAddresses
parameters:
- description: The limit for how many objects will be in the response. Default and max for this value is 512 objects.
in: query
name: limit
schema:
format: int64
maximum: 512
minimum: 1
type: integer
- description: If specified, this should be the endCursor value from the previous page of results. When present, this request will return the next page of results that occur immediately after the previous page of results.
in: query
name: after
schema:
type: string
- description: 'A filter on the data based on this comma-separated list of parent tag IDs, for use by orgs with tag hierarchies. Specifying a parent tag will implicitly include all descendent tags of the parent tag. Example: `parentTagIds=345,678`'
explode: false
in: query
name: parentTagIds
schema:
items:
type: string
type: array
style: form
- description: 'A filter on the data based on this comma-separated list of tag IDs. Example: `tagIds=1234,5678`'
explode: false
in: query
name: tagIds
schema:
items:
type: string
type: array
style: form
- description: 'A filter on data to have a created at time after or equal to this specified time in RFC 3339 format. Millisecond precision and timezones are supported. (Examples: 2019-06-13T19:08:25Z, 2019-06-13T19:08:25.455Z, OR 2015-09-15T14:00:12-04:00).'
in: query
name: createdAfterTime
schema:
type: string
responses:
'200':
content:
application/json:
example:
data:
- addressTypes:
- yard
contacts:
- firstName: Jane
id: '22408'
lastName: Jones
createdAtTime: '2019-05-18T20:27:35Z'
externalIds:
maintenanceId: '250020'
payrollId: ABFS18600
formattedAddress: 350 Rhode Island St, San Francisco, CA
geofence:
circle:
latitude: 37.765363
longitude: -122.4029238
radiusMeters: 25
polygon:
vertices:
- latitude: 37.765363
longitude: -122.403098
- latitude: 38.765363
longitude: -122.403098
- latitude: 37.765363
longitude: -123.403098
id: '22408'
latitude: 37.765363
longitude: -122.4029238
name: Samsara HQ
notes: 'Hours of operation: 8am - 6pm; Truck entrance on the Rhode Island street side.'
tags:
- id: '3914'
name: East Coast
parentTagId: '4815'
pagination:
endCursor: MjkY
hasNextPage: true
schema:
$ref: '#/components/schemas/ListAddressesResponse'
description: List of all addresses in the organization
default:
content:
application/json:
schema:
$ref: '#/components/schemas/standardErrorResponse'
description: Error response
summary: List All Addresses
tags:
- Addresses
post:
description: "Creates a new address in the organization. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Write Addresses** under the Addresses category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
operationId: createAddress
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAddressRequest'
description: The address to create.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AddressResponse'
description: Newly created address object with ID.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/standardErrorResponse'
description: Error response
summary: Create an Address
tags:
- Addresses
x-codegen-request-body-name: address
/addresses/{id}:
delete:
description: "Delete a specific address. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Write Addresses** under the Addresses category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
operationId: deleteAddress
parameters:
- description: 'ID of the Address. This can either be the Samsara-provided ID or an external ID. External IDs are customer-specified key-value pairs created in the POST or PATCH requests of this resource. To specify an external ID as part of a path parameter, use the following format: `key:value`. For example, `crmId:abc123`'
in: path
name: id
required: true
schema:
type: string
responses:
'204':
content:
application/json:
schema:
$ref: '#/components/schemas/standardDeleteResponse'
description: A successful DELETE response is a 204 with no content.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/standardErrorResponse'
description: Unexpected error.
summary: Delete an Address
tags:
- Addresses
get:
description: "Returns a specific address. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Read Addresses** under the Addresses category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
operationId: getAddress
parameters:
- description: 'ID of the Address. This can either be the Samsara-provided ID or an external ID. External IDs are customer-specified key-value pairs created in the POST or PATCH requests of this resource. To specify an external ID as part of a path parameter, use the following format: `key:value`. For example, `crmId:abc123`'
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AddressResponse'
description: An Address.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/standardErrorResponse'
description: Error response
summary: Retrieve an Address
tags:
- Addresses
patch:
description: "Update a specific address. \n\n **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href=\"https://forms.gle/zkD4NCH7HjKb7mm69\" target=\"_blank\">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href=\"https://www.samsara.com/help\" target=\"_blank\">submit a case</a> to our support team.\n\nTo use this endpoint, select **Write Addresses** under the Addresses category when creating or editing an API token. <a href=\"https://developers.samsara.com/docs/authentication#scopes-for-api-tokens\" target=\"_blank\">Learn More.</a>"
operationId: updateAddress
parameters:
- description: 'ID of the Address. This can either be the Samsara-provided ID or an external ID. External IDs are customer-specified key-value pairs created in the POST or PATCH requests of this resource. To specify an external ID as part of a path parameter, use the following format: `key:value`. For example, `crmId:abc123`'
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAddressRequest'
description: The address fields to update.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/AddressResponse'
description: Updated address object with ID.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/standardErrorResponse'
description: Error response
summary: Update an Address
tags:
- Addresses
x-codegen-request-body-name: address
components:
schemas:
Address:
description: An Address object.
properties:
addressTypes:
description: 'Reporting location type associated with the address (used for ELD reporting purposes). Valid values: `yard`, `shortHaul`, `workforceSite`, `riskZone`, `industrialSite`, `alertsOnly`.'
items:
enum:
- yard
- shortHaul
- workforceSite
- riskZone
- industrialSite
- alertsOnly
example: yard
type: string
type: array
contacts:
description: An array Contact mini-objects that are associated the Address.
items:
$ref: '#/components/schemas/contactTinyResponse'
type: array
createdAtTime:
description: The date and time this address was created in RFC 3339 format.
example: '2019-05-18T20:27:35Z'
format: date-time
type: string
externalIds:
description: The [external IDs](https://developers.samsara.com/docs/external-ids) for the given object.
example:
maintenanceId: '250020'
payrollId: ABFS18600
properties: {}
type: object
formattedAddress:
description: The full street address for this address/geofence, as it might be recognized by Google Maps.
example: 350 Rhode Island St, San Francisco, CA
maxLength: 1024
type: string
geofence:
$ref: '#/components/schemas/AddressGeofence'
id:
description: ID of the Address.
example: '22408'
type: string
latitude:
description: Latitude of the address. Will be geocoded from `formattedAddress` if not provided.
example: 37.765363
format: double
type: number
longitude:
description: Longitude of the address. Will be geocoded from `formattedAddress` if not provided.
example: -122.4029238
format: double
type: number
name:
description: Name of the address.
example: Samsara HQ
maxLength: 255
type: string
notes:
description: Notes about the address.
example: 'Hours of operation: 8am - 6pm; Truck entrance on the Rhode Island street side.'
maxLength: 280
type: string
tags:
description: An array of all tag mini-objects that are associated with the given address entry.
items:
$ref: '#/components/schemas/tagTinyResponse'
type: array
required:
- formattedAddress
- geofence
- id
- name
type: object
AddressGeofence:
description: The geofence that defines this address and its bounds. This can either be a circle or a polygon, but not both.
properties:
circle:
$ref: '#/components/schemas/AddressGeofence_circle'
polygon:
$ref: '#/components/schemas/AddressGeofence_polygon'
settings:
$ref: '#/components/schemas/AddressGeofence_settings'
type: object
AddressGeofence_polygon_vertices:
properties:
latitude:
description: The latitude of a geofence vertex in decimal degrees.
format: double
type: number
longitude:
description: The longitude of a geofence vertex in decimal degrees.
format: double
type: number
required:
- latitude
- longitude
type: object
tagTinyResponse:
description: A minified tag object
properties:
id:
description: ID of the tag.
example: '3914'
type: string
name:
description: Name of the tag.
example: East Coast
type: string
parentTagId:
description: If this tag is part a hierarchical tag tree, this is the ID of the parent tag, otherwise this will be omitted.
example: '4815'
type: string
type: object
CreateAddressRequest:
description: A request body to create an Address.
properties:
addressTypes:
description: 'Reporting location type associated with the address (used for ELD reporting purposes). Valid values: `yard`, `shortHaul`, `workforceSite`, `riskZone`, `industrialSite`, `alertsOnly`.'
items:
enum:
- yard
- shortHaul
- workforceSite
- riskZone
- industrialSite
- alertsOnly
example: yard
type: string
type: array
contactIds:
description: An array of Contact IDs associated with this Address.
items:
example: '22408'
type: string
type: array
externalIds:
additionalProperties:
type: string
description: The [external IDs](https://developers.samsara.com/docs/external-ids) for the given object.
example:
maintenanceId: '250020'
payrollId: ABFS18600
type: object
formattedAddress:
description: The full street address for this address/geofence, as it might be recognized by Google Maps.
example: 350 Rhode Island St, San Francisco, CA
maxLength: 1024
type: string
geofence:
$ref: '#/components/schemas/CreateAddressRequest_geofence'
latitude:
description: Latitude of the address. Will be geocoded from `formattedAddress` if not provided.
example: 37.765363
format: double
type: number
longitude:
description: Longitude of the address. Will be geocoded from `formattedAddress` if not provided.
example: -122.4029238
format: double
type: number
name:
description: Name of the address.
example: Samsara HQ
maxLength: 255
type: string
notes:
description: Notes about the address.
example: 'Hours of operation: 8am - 6pm; Truck entrance on the Rhode Island street side.'
maxLength: 280
type: string
tagIds:
description: An array of IDs of tags to associate with this address.
items:
example: '3914'
type: string
type: array
required:
- formattedAddress
- geofence
- name
type: object
CreateAddressRequest_geofence_settings:
description: Information about a geofence's settings.
properties:
showAddresses:
description: If this property is set to true, then underlying geofence addresses will be shown in reports instead of a geofence's name.
example: true
type: boolean
type: object
CreateAddressRequest_geofence:
description: The geofence that defines this address and its bounds. This can either be a circle or a polygon, but not both.
properties:
circle:
$ref: '#/components/schemas/AddressGeofence_circle'
polygon:
$ref: '#/components/schemas/AddressGeofence_polygon'
settings:
$ref: '#/components/schemas/CreateAddressRequest_geofence_settings'
type: object
AddressResponse:
description: An Address response body.
properties:
data:
$ref: '#/components/schemas/Address'
required:
- data
type: object
UpdateAddressRequest:
description: A request body to update an Address.
properties:
addressTypes:
description: 'Reporting location type associated with the address (used for ELD reporting purposes). Valid values: `yard`, `shortHaul`, `workforceSite`, `riskZone`, `industrialSite`, `alertsOnly`.'
items:
enum:
- yard
- shortHaul
- workforceSite
- riskZone
- industrialSite
- alertsOnly
example: yard
type: string
type: array
contactIds:
description: An array of Contact IDs associated with this Address.
items:
example: '22408'
type: string
type: array
externalIds:
additionalProperties:
type: string
description: The [external IDs](https://developers.samsara.com/docs/external-ids) for the given object.
example:
maintenanceId: '250020'
payrollId: ABFS18600
type: object
formattedAddress:
description: The full street address for this address/geofence, as it might be recognized by Google Maps.
example: 350 Rhode Island St, San Francisco, CA
maxLength: 1024
type: string
geofence:
$ref: '#/components/schemas/UpdateAddressRequest_geofence'
latitude:
description: Latitude of the address. Will be geocoded from `formattedAddress` if not provided.
example: 37.765363
format: double
type: number
longitude:
description: Longitude of the address. Will be geocoded from `formattedAddress` if not provided.
example: -122.4029238
format: double
type: number
name:
description: Name of the address.
example: Samsara HQ
maxLength: 255
type: string
notes:
description: Notes about the address.
example: 'Hours of operation: 8am - 6pm; Truck entrance on the Rhode Island street side.'
maxLength: 280
type: string
tagIds:
description: An array of IDs of tags to associate with this address.
items:
example: '3914'
type: string
type: array
type: object
UpdateAddressRequest_geofence:
description: The geofence that defines this address and its bounds. This can either be a circle or a polygon, but not both.
properties:
circle:
$ref: '#/components/schemas/AddressGeofence_circle'
polygon:
$ref: '#/components/schemas/AddressGeofence_polygon'
settings:
$ref: '#/components/schemas/AddressGeofence_settings'
type: object
ListAddressesResponse:
description: A list of Addresses and pagination information.
properties:
data:
description: A list of Addresses.
items:
$ref: '#/components/schemas/Address'
type: array
pagination:
$ref: '#/components/schemas/paginationResponse'
required:
- data
- pagination
type: object
AddressGeofence_settings:
description: Information about a geofence's settings.
properties:
showAddresses:
description: If this property is set to true, then underlying geofence addresses will be shown in reports instead of a geofence's name.
example: false
type: boolean
type: object
AddressGeofence_circle:
description: Information about a circular geofence. This field is only needed if the geofence is a circle.
properties:
latitude:
description: Latitude of the address. Will be geocoded from `formattedAddress` if not provided.
example: 37.765363
format: double
type: number
longitude:
description: Longitude of the address. Will be geocoded from `formattedAddress` if not provided.
example: -122.4029238
format: double
type: number
radiusMeters:
description: The radius of the circular geofence in meters.
example: 25
format: int64
type: integer
required:
- radiusMeters
type: object
contactTinyResponse:
description: A minified contact object
properties:
firstName:
description: First name of the contact.
example: Jane
type: string
id:
description: ID of the contact.
example: '22408'
type: string
lastName:
description: Last name of the contact.
example: Jones
type: string
type: object
standardDeleteResponse:
description: A successful DELETE response is a 204 with no content.
example: <empty content>
type: string
standardErrorResponse:
description: Error response
properties:
message:
description: The message of the error.
example: An error has occurred.
type: string
requestId:
description: The ID of the request.
example: 8916e1c1
type: string
type: object
paginationResponse:
description: Pagination parameters.
properties:
endCursor:
description: Cursor identifier representing the last element in the response. This value should be used in conjunction with a subsequent request's 'after' query parameter. This may be an empty string if there are no more pages left to view.
example: MjkY
format: string
type: string
hasNextPage:
description: True if there are more pages of results immediately available after this endCursor.
example: true
type: boolean
required:
- endCursor
- hasNextPage
type: object
AddressGeofence_polygon:
description: Information about a polygon geofence. This field is only needed if the geofence is a polygon.
properties:
vertices:
description: The vertices of the polygon geofence. These geofence vertices describe the perimeter of the polygon, and must consist of at least 3 vertices and less than 40.
example:
- latitude: 37.765363
longitude: -122.403098
- latitude: 38.765363
longitude: -122.403098
- latitude: 37.765363
longitude: -123.403098
items:
$ref: '#/components/schemas/AddressGeofence_polygon_vertices'
maxItems: 40
minItems: 3
type: array
required:
- vertices
type: object
securitySchemes:
AccessTokenHeader:
type: http
scheme: bearer
x-original-swagger-version: '2.0'
x-readme:
explorer-enabled: true
proxy-enabled: true