Sites
Jump to:
This endpoint is used to obtain an Access Token using the Client Credentials Grant flow. This flow is typically used for machine-to-machine (M2M) communication where a specific user’s consent is not required, and the client application is acting on its own behalf.
Create site
This endpoint provisions a new Site resource within a specific namespace. It features automatic address standardization and geocoding: the system accepts a raw address string (inputAddress) and transforms it into a structured address object with precise geospatial coordinates.
| Feature | Details |
|---|---|
| Method | POST |
| Endpoint | /apis/v1alpha/namespaces/{namespace}/site |
Path parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| namespace | String | Yes | The unique identifier for the tenant or grouping. | 2135 |
Headers
| Header | Value | Description |
|---|---|---|
| Content-Type | application/json | Required. Indicates the payload format. |
| Authorization | Bearer <TOKEN> | Required. Standard OAuth 2.0 access token. |
Request body
The payload requires standard resource identifiers (kind, version) and a spec object containing the site details.
| Field | nested property | Type | Required | Description |
|---|---|---|---|---|
| kind | String | Yes | Resource type classifier. Must be “site”. | |
| version | String | Yes | API version. Must be “v1alpha“. | |
| namespace | String | Yes | Must match the namespace provided in the URL path. | |
| name | String | Yes | Unique user-defined identifier (slug) for this site. | |
| metadata | Object | No | Container for custom tags and labels. | |
| labels | Map | No | Key-value pairs for external tracking (e.g., Project IDs). | |
| spec | Object | Yes | The technical specifications of the site. | |
| inputAddress | String | Yes | Raw Address. A single string representing the physical location. The API will parse this to generate structured data. | |
| friendly | String | Yes | A human-readable display name for the site. |
Response body
The API returns the created resource with additional system-generated fields.
Note: The inputAddress is removed and replaced by a structured address object and geoLocation data.
| Field | nested property | Type | Description |
|---|---|---|---|
| metadata | Object | ||
| dateCreated | Long | Timestamp of creation (Unix Epoch). | |
| geoLocation | Object | Enrichment. Geospatial data derived from the input address. | |
| geoLocation.coordinates | Array | [Longitude, Latitude] pair. | |
| geoLocation.plusCode | String | The Google Open Location Code (Plus Code) for the site. | |
| spec | Object | The specification object contains detailed information | |
| address | Object | Enrichment. The parsed, structured version of the inputAddress. | |
| address.line1 | String | Street address line 1. | |
| address.city | String | City name. | |
| address.state | String | State or province code. | |
| address.zipcode | String | Postal code. | |
| address.latitude | Float | Precise latitude of the address. | |
| address.longitude | Float | Precise longitude of the address. |
Example request
The user sends a raw address string (2015 2nd ave…).
{
"kind": "site",
"version": "v1alpha",
"namespace": "2135",
"name": "intl-test-001",
"metadata": {
"labels": {
"project": "MR-PROJ-1000-A"
}
},
"spec": {
"inputAddress" : "2015 2nd ave seattle wa 98121",
"friendly": "Seattle Branch"
}
}Example response
The system validates the address and returns the structured data.
{
"kind": "site",
"version": "v1alpha",
"namespace": "2135",
"name": "intl-test-001",
"metadata": {
"dateCreated": 1764966214549,
"dateUpdated": 1764966215838,
"labels": {
"project-id": "MR-PROJ-1000-A"
},
"geoLocation": {
"type": "Point",
"coordinates": [ -122.3424101, 47.6117607 ],
"plusCode": "84VVJM65+P24"
}
},
"spec": {
"address": {
"line1": "2015 2nd Ave",
"line2": null,
"city": "Seattle",
"state": "WA",
"zipcode": "98121",
"country": "USA",
"latitude": 47.61176,
"longitude": -122.34241,
"streetNumber": "2015",
"routeShort": "2nd Ave"
},
"friendly": "Seattle Branch"
}
}Get site details
Retrieves the configuration, metadata, and geospatial data for a specific site.
| Feature | Details |
|---|---|
| Method | GET |
| Endpoint | /apis/v1alpha/namespaces/{namespaceId}/site/{name} |
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| namespaceId | string | Yes | The unique identifier for the customer or organizational namespace (e.g., 2135). |
| name | string | Yes | The name or ID of the specific site to retrieve (e.g., intl-test-001). |
Headers
| Header | Value | Required | Description |
|---|---|---|---|
| Authorization | Bearer <TOKEN> | Yes | Valid OAuth2 bearer token. |
Response schema
The response returns a Site object containing the resource’s identity, metadata, and specification.
| Field | NESTED PROPERTY | Type | Description |
|---|---|---|---|
| kind | String | The resource type (always site) | |
| version | String | The API version (e.g., v1alpha) | |
| namespace | String | The namespace ID linked to this site | |
| name | String | The unique name of the site | |
| metadata | Object | Contains system-generated timestamps and user-defined identifiers | |
| **dateCreated / dateUpdated** | Long | Epoch timestamps representing the site lifecycle | |
| labels | Object | Dictionary of key-value pairs used for internal tracking (e.g., project, att-id | |
| geoLocation | Object | Defines the physical delivery point using GeoJSON coordinates and Google Plus Codes | |
| type | Geometry type (typically Point) | ||
| coordinates | Array | Containing [longitude, latitude] | |
| plusCode | The Google Plus Code for high-accuracy location sharing | ||
| spec | Object | Technical requirements are defined | |
| line1 | Primary street address. | ||
| city / state / zipcode | Standard US address components. | ||
| country | ISO 3166-1 alpha-3 country code (e.g., USA). | ||
| streetNumber | Extracted building number. | ||
| routeLong / routeShort | Full and abbreviated street names (e.g., “2nd Avenue” vs “2nd Ave”). | ||
| uk* fields | Regional fields specific to UK addresses (e.g., ukExchangeCode). These are null for non-UK sites. | ||
| quotes | Object | An optional collection of quote references associated with this site | |
| offers | Array | A list of objects containing kind, version, namespace, and name pointing to specific quote resources |
Example response
{
"kind": "site",
"version": "v1alpha",
"namespace": "2135",
"name": "intl-test-001",
"metadata": {
"dateCreated": 1764966214549,
"dateUpdated": 1764966215838,
"labels": {
"att-id": "EXT-123456",
"project": "MR-PROJ-1000-A"
},
"geoLocation": {
"type": "Point",
"coordinates": [-122.3424101, 47.6117607],
"plusCode": "84VVJM65+P24"
}
},
"spec": {
"address": {
"line1": "2015 2nd Ave",
"city": "Seattle",
"state": "WA",
"zipcode": "98121",
"country": "USA",
"latitude": 47.61176,
"longitude": -122.34241,
"streetNumber": "2015",
"routeLong": "2nd Avenue",
"routeShort": "2nd Ave"
},
"friendly": "Seattle Branch",
"quotes": {
"offers": [
{
"kind": "quote",
"version": "v1alpha",
"namespace": "2135",
"name": "intl-test-001"
}
]
}
}
}