Version: v0.2b

Create unassigned stop with custom properties

Prerequisites

You must first create up to 3 custom stop properties in your Circuit for Teams account settings.

Here we will be using the List custom stop properties endpoint to fetch the custom stop properties defined in your team. Afterwards, we will use the Create a new unassigned stop endpoint to create an unassigned stop with a custom stop property.

Note that custom stop properties can be added to Stops and Unassigned Stops when using Create, Batch import, or Update endpoints. They are also included in the response of List and Retrieve endpoints.

JS Web
Node
Python
curl

// Set the API key
const apiKey = '<your-api-key>'

// Headers for GET requests
const getHeaders = new Headers()
getHeaders.append('Authorization', `Basic ${btoa(`${apiKey}:`)}`)

// Headers for POST requests
const postHeaders = new Headers(getHeaders)
postHeaders.append('Content-Type', 'application/json')

async function createStopWithCustomProperties() {
  // Perform the request with GET method
  const response = await fetch(
    'https://api.getcircuit.com/public/v0.2b/team/customStopProperties',
    {
      method: 'GET',
      headers: getHeaders,
    },
  )

  // The response will be similar to the following:
  // {
  //   "customStopProperties": [
  //     {
  //       "id": "aed6447b-00f9-445d-8f3d-8ec5ef4d3d05", // a random id
  //       "name": "Invoice Number" // the name of your custom stop property
  //       ...
  //     },
  //     ...
  //   ]
  // }
  const customStopProperty = (await response.json()).customStopProperties[0]
  console.log(customStopProperty)

  const customStopPropertyId = customStopProperty.id

  // custom stop properties are added as key-value pairs 
  // in the 'customProperties' field referenced by their 'id'
  const unassignedStopData = {
    address: {
      addressLineOne: "221B Baker Street, London"
    },
    customProperties: {
      [customStopPropertyId]: "INV-123"
    }
  }
  
  // The custom stop property can be used in the 'customProperties' field
  // when creating a new unassigned stop.
  const createStopResponse = await fetch(
    `https://api.getcircuit.com/public/v0.2b/unassignedStops`,
    {
      method: 'POST',
      headers: postHeaders,
      body: JSON.stringify(unassignedStopData)
    },
  )

  // The response will return information about the created unassigned stop
  // including the custom stop property.
  const createStopData = await createStopResponse.json()
  console.log(createStopData)
}

// We are using the axios library here to make requests from Node
const axios = require('axios')

const apiKey = '<your-api-key>'

async function createStopWithCustomProperties() {
  // First, get the custom stop properties from your team
  const customPropertiesResponse = await axios.get(
    'https://api.getcircuit.com/public/v0.2b/team/customStopProperties',
    {
      auth: { username: apiKey }
    }
  )

  // The response will be similar to the following:
  // {
  //   "customStopProperties": [
  //     {
  //       "id": "aed6447b-00f9-445d-8f3d-8ec5ef4d3d05", // a random id
  //       "name": "Invoice Number" // the name of your custom stop property
  //       ...
  //     },
  //     ...
  //   ]
  // }
  const customStopProperty = customPropertiesResponse.data.customStopProperties[0]
  console.log(customStopProperty)

  const customStopPropertyId = customStopProperty.id

  // custom stop properties are added as key-value pairs 
  // in the 'customProperties' field referenced by their 'id'
  const unassignedStopData = {
    address: {
      addressLineOne: "221B Baker Street, London"
    },
    customProperties: {
      [customStopPropertyId]: "INV-123"
    }
  }

  // The custom stop property can be used in the 'customProperties' field
  // when creating a new unassigned stop.
  const createStopResponse = await axios.post(
    'https://api.getcircuit.com/public/v0.2b/unassignedStops',
    unassignedStopData,
    {
      auth: { username: apiKey }
    }
  )

  // The response will return information about the created unassigned stop
  // including the custom stop property.
  const createStopData = createStopResponse.data
  console.log(createStopData)
}

# We are using the requests library here to make requests from Python
import requests
from requests.auth import HTTPBasicAuth

# Set the API key
api_key = "<your-api-key>"

def create_stop_with_custom_properties():
    # First, get the custom stop properties from your team
    custom_properties_response = requests.get(
        "https://api.getcircuit.com/public/v0.2b/team/customStopProperties",
        auth=HTTPBasicAuth(api_key, ""),
    )

    # The response will be similar to the following:
    # {
    #   "customStopProperties": [
    #     {
    #       "id": "aed6447b-00f9-445d-8f3d-8ec5ef4d3d05", # a random uuid
    #       "name": "Invoice Number" # the name of your custom stop property
    #       ...
    #     },
    #     ...
    #   ]
    # }
    custom_stop_property = custom_properties_response.json()["customStopProperties"][0]
    print(custom_stop_property)

    custom_stop_property_id = custom_stop_property["id"]

    # custom stop properties are added as key-value pairs 
    # in the 'customProperties' field referenced by their 'id'.
    unassigned_stop_data = {
        "address": {
            "addressLineOne": "221B Baker Street, London"
        },
        "customProperties": {
            custom_stop_property_id: "INV-123"
        }
    }

    # The custom stop property can be used in the 'customProperties' field
    # when creating a new unassigned stop.
    create_stop_response = requests.post(
        "https://api.getcircuit.com/public/v0.2b/unassignedStops",
        auth=HTTPBasicAuth(api_key, ""),
        json=unassigned_stop_data,
    )

    # The response will return information about the created unassigned stop
    # including the custom stop property.
    create_stop_data = create_stop_response.json()
    print(create_stop_data)

# First, get the custom stop properties from your team
curl https://api.getcircuit.com/public/v0.2b/team/customStopProperties \
   -u <your-api-key>:

# The response will be similar to the following:
# {
#   "customStopProperties": [
#     {
#       "id": "aed6447b-00f9-445d-8f3d-8ec5ef4d3d05", // a random id
#       "name": "Invoice Number" // the name of your custom stop property
#       ...
#     },
#     ...
#   ]
# }

# Replace <custom-stop-property-id> with a custom stop property 'id'
# from the previous request.
unassigned_stop_data='{
  "address": {
    "addressLineOne": "221B Baker Street, London"
  },
  "customProperties": {
    "<custom-stop-property-id>": "INV-123"
  }
}'

# Create a new unassigned stop with custom properties
# The response contains information about the created unassigned stop 
# including the custom stop property.
curl -X POST https://api.getcircuit.com/public/v0.2b/unassignedStops \
   -d "$unassigned_stop_data" \
   -H 'Content-Type: application/json' \
   -u <your-api-key>:

Prerequisites​

Prerequisites