AxleHire API

Welcome to AxleHire's API documentation!

Authentication

Provided API tokens need to be passed as an Authorization header preceded by Bearer with all requests.

If the token is not valid the 401 authorization error response will be returned.

Example request

$ curl -XGET
       -H 'Authorization: Bearer API_TOKEN'
       -H "Content-type: application/json"
       {endpoint}

Example error response

{
  "status": 401,
  "message": "No client found with authentication token!"
}

Pagination

AxleHire allows for pagination on the shipments core resource. Pass either a page and/or limit query parameter in the GET /shipments requests to utilize resource pagination.

The default values are:

  • page : 1
  • limit : 50

The limit also has a hard limit of 1,000 to prevent overquerying the database.

Pagination Example

$ curl -XGET
       -H 'Authorization: Bearer API_TOKEN'
       -H "Content-type: application/json"
       'https://api.axlehire.com/shipments?page=1&limit=100'

Errors

AxleHire uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.), and codes in the 5xx range indicate an error with AxleHire's servers.

Messages that return the a more detailed description of the exact thing that went wrong are sometimes returned with 4xx and 5xx errors.

Handling errors

Our API raises exceptions for many reasons, such as a failed shipment address geocoding, invalid parameters, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions.

HTTP Status Code Summary

200 - OK             Everything worked as expected.
400 - Bad Request    The request was missing a required parameter.
401 - Unauthorized   No valid API key provided.
404 - Not Found      The requested resource doesn't exist.
429 - Too Many       Too many requests hit the API too quickly.
      Requests
422 - Field          An incorrect type within a field was used.
      Validation
500 - Server Error   Something went wrong on AxleHire's end.

Shipments

This is the shipments API. You can use this API to view, create, update, and delete your shipments.

The shipments to be delivered the next day are cloned and moved along with any other shipments to be delivered on that same day to our primary database at 5PM PST daily as a collective job. After this migration, the migrated shipment or shipments will be moved to our archived shipment collection and will not be allowed to be updated unless it is through your account at dashboard.axlehire.com where you may view or update the shipments in the job.

If the shipment is submitted but its delivery datetime is not the next day, then the shipment will remain in pending until the daily check is the day immediately before the shipment's delivery datetime. This means that you may continue to update this shipment's information up until that migration. There will be time restrictions in updating the shipment's dropoff time based on service time agreements.

Get Shipments

Get all shipments you have created.

Pass the following query params to grab just the pending or archived shipments.

Examples:

https://api.axlehire.com/shipments?pending=true
https://api.axlehire.com/shipments?archived=true

Passing no query parameters will retrieve both pending and archived shipments in separate pending and archived keys in the data section of the response.

Pagination default value is 50 items. This can be overwritten by passing the following a limit value. A page value can also be passed as a query parameter to grab a certain page.

Examples:

https://api.axlehire.com/shipments?limit=10
https://api.axlehire.com/shipments?page=2
https://api.axlehire.com/shipments?limit=10&page=2

Error Handling:

  • 500 Error Code - Database query error
GET
/shipments

Example request

$ curl -XGET \
       -H 'Authorization: Bearer API_TOKEN' \
       -H "Content-type: application/json" \
       'https://api.axlehire.com/shipments'

Example response

{
  "success": true,
  "data": {
    "pending": [
      {
        "_id": "57433e39862d37581d1a694a",
        "dropoff_longitude": -122.2697218,
        "dropoff_latitude": 37.8700762,
        "pickup_longitude": -122.268613,
        "pickup_latitude": 37.870019,
        "client_id": 1,
        "dropoff_latest_ts": "2016-05-24T18:42:37.000Z",
        "dropoff_buffer": 600,
        "dropoff_zipcode": "94704",
        "dropoff_state": "CA",
        "dropoff_city": "Berkeley",
        "dropoff_street2": "709",
        "dropoff_street": "2040 Center Street",
        "pickup_buffer": 300,
        "pickup_zipcode": "94704",
        "pickup_state": "CA",
        "pickup_city": "Berkeley",
        "pickup_street2": "PH",
        "pickup_street": "2150 Shattuck Ave",
        "customer_email": "long@axlehire.com",
        "customer_phone_number": "760-583-5579",
        "customer_name": "Long Tran",
        "client_internal_shipment_id": "2",
        "workload": 1
      }
    ],
    "archived": [
      {
        "_id": "57422c5d379f552615488f53",
        "job_id": 254,
        "shipment_id": 12772,
        "client_internal_shipment_id": "1",
        "customer_name": "James Smith",
        "customer_phone_number": "888-333-4444",
        "customer_email": "demo@axlehire.com",
        "pickup_street": "2150 Shattuck Ave",
        "pickup_street2": "PH",
        "pickup_city": "Berkeley",
        "pickup_state": "CA",
        "pickup_zipcode": "94704",
        "pickup_buffer": 300,
        "dropoff_street": "2540 College Ave",
        "dropoff_street2": "303",
        "dropoff_city": "Berkeley",
        "dropoff_state": "CA",
        "dropoff_zipcode": "94704",
        "dropoff_buffer": 600,
        "dropoff_latest_ts": "2016-05-23T18:42:37.000Z",
        "client_id": 1,
        "pickup_latitude": 37.870019,
        "pickup_longitude": -122.268613,
        "dropoff_latitude": 37.86408,
        "dropoff_longitude": -122.254124,
        "workload": 1
      }
    ]
  },
  "_meta": {
    "max_results": 50,
    "page": 1,
    "total": 2
  }
}

Get Shipment

Get a shipment from uploaded shipments.

Pass one of the following query paramters to look for it specifically in the pending or archived colletion.

Examples:

https://api.axlehire.com/shipments/{shipment_id}?pending=true
https://api.axlehire.com/shipments/{shipment_id}?archived=true

If no query parameters are passed, then both archived and pending collections will be searched for the shipment.

Error Handling:

  • 404 Error Code - Shipment not found
  • 500 Error Code - Database query failed
GET
/shipments/{shipment_id}

Example request

$ curl -XGET \
       -H 'Authorization: Bearer {API_TOKEN}' \
       -H 'Content-type: application/json' \
       'https://api.axlehire.com/shipments/{shipment_id}'

Example response

{
  "success": true,
  "data": {
    "_id": "57433e39862d37581d1a694a",
    "dropoff_longitude": -122.2697218,
    "dropoff_latitude": 37.8700762,
    "pickup_longitude": -122.268613,
    "pickup_latitude": 37.870019,
    "client_id": 1,
    "dropoff_latest_ts": "2016-05-24T18:42:37.000Z",
    "dropoff_buffer": 600,
    "dropoff_zipcode": "94704",
    "dropoff_state": "CA",
    "dropoff_city": "Berkeley",
    "dropoff_street2": "709",
    "dropoff_street": "2040 Center Street",
    "pickup_buffer": 300,
    "pickup_zipcode": "94704",
    "pickup_state": "CA",
    "pickup_city": "Berkeley",
    "pickup_street2": "PH",
    "pickup_street": "2150 Shattuck Ave",
    "customer_email": "long@axlehire.com",
    "customer_phone_number": "760-583-5579",
    "customer_name": "Long Tran",
    "client_internal_shipment_id": "2",
    "workload": 1
  }
}

Create Shipments

Creates one or multiple shipments. To create multiple shipments at once, pass multiple shipments in an array in the body of the request.

Shipments with addresses that fail to geocode, get the latitude and longitude of the address, will return a response with an error code of 400.

The 400 response will contain the following fields:

  • Succesfully geocoded shipments

  • Failed geocoded shipments

  • Failed geocoded addresses with suggestions

  • Failed geocoded addresses without suggestions

  • Successfully geocoded addresses will not be returned

If one address fails in a batch request, then all of the shipments in the request fail. Make sure to fix up the addresses that failed to geocode with the suggestions and resubmit the request.

The client_internal_shipment_id is highly recommended as a unique identifier on your end to match the failed geocoded addresses with the shipment they are a part of when fixing the addresses.

All times passed inside the request body needs to be passed with a timezone offset from UTC, otherwise it will be interpretted as UTC.

Property Description Type Optionality
client_internal_shipment_id Shipment ID for client's internal tracking String recommended
customer_name Customer's name String recommended
customer_phone_number Customer's phone number String recommended
customer_email Customer's email String optional
pickup_street Pickup's street address String required
pickup_street2 Pickup's address's apt or room String optional
pickup_city Pickup's city String required
pickup_state Pickup's state String required
pickup_zipcode Pickup's zipcode String required
pickup_buffer Pickup's service time Number optional
pickup_note Pickup notes String optional
pickup_earliest_ts Pickup's earliest time Date optional
pickup_latest_ts Pickup's latest time Date optional
dropoff_street Dropoff's street address String required
dropoff_street2 Dropoff's address's apt or room String optional
dropoff_city Dropoff's city String required
dropoff_state Dropoff's state String required
dropoff_zipcode Dropoff's zipcode String required
dropoff_buffer Dropoff's service time Number optional
dropoff_note Dropoff notes String optional
dropoff_earliest_ts Dropoff's earliest time Date optional
dropoff_latest_ts Dropoff's latest time Date required
workload Workload Number optional
delivery_photo_required Option to require photo at dropoff (Default: false) Boolean optional
delivery_signature_required Option to require signature at dropoff (Default: false) Boolean optional

Error Handling:

  • 400 Error Code

    • Returns a success: false along with failed geocoded shipment pickup or dropoff locations with or without suggestions, successful shipments (not saved), and failed shipments.
  • 412 Error Code

    • Required fields in body of request are missing or misformatted.
  • 500 Error Code

    • Geocoding server error
    • Database document insertion error
POST
/shipments

Example request

curl -XPOST \
     -H 'Authorization: Bearer {API_TOKEN}' \
     -H 'Content-type: application/json' \
     -d '{"client_internal_shipment_id": "11",
         "customer_name": "James Smith",
         "customer_phone_number": "888-555-4444",
         "customer_email": "demo@axlehire.com",
         "pickup_street": "2150 Shattuck Ave",
         "pickup_street2": "PH",
         "pickup_city": "Berkeley",
         "pickup_state": "CA",
         "pickup_zipcode": "94704",
         "pickup_buffer": 300,
         "dropoff_street": "3797 Stoneglen North",
         "dropoff_street2": "69",
         "dropoff_city": "Richmond",
         "dropoff_state": "CA",
         "dropoff_zipcode": "94806",
         "dropoff_buffer": 600,
         "dropoff_note": "Note for dropoff",
         "dropoff_earliest_ts": "2016-06-07T08:00:00-07:00",
         "dropoff_latest_ts": "2016-06-07T12:00:00-07:00"}' \
     'https://api.axlehire.com/shipments'

Example request body

{
    "client_internal_shipment_id": "1",
    "customer_name": "James Smith",
    "customer_phone_number": "888-444-3333",
    "customer_email": "demo@axlehire.com",
    "pickup_street": "2150 Shattuck Ave",
    "pickup_street2": "PH",
    "pickup_city": "Berkeley",
    "pickup_state": "CA",
    "pickup_zipcode": "94704",
    "pickup_buffer": 300,
    "dropoff_street": "2540 College Ave",
    "dropoff_street2": "303",
    "dropoff_city": "Berkeley",
    "dropoff_state": "CA",
    "dropoff_zipcode": "94720",
    "dropoff_buffer": 600,
    "dropoff_latest_ts": "2016-05-24T11:42:37-07:00"
}

Example success response

{
  "success": true,
  "data": {
    "shipments": [
      {
        "_id": "5744cd96e3f32d833a5ce98c",
        "dropoff_longitude": -122.254124,
        "dropoff_latitude": 37.86408,
        "pickup_longitude": -122.268613,
        "pickup_latitude": 37.870019,
        "client_id": 1,
        "dropoff_latest_ts": "2016-05-25T18:42:37.000Z",
        "dropoff_buffer": 600,
        "dropoff_zipcode": "94704",
        "dropoff_state": "CA",
        "dropoff_city": "Berkeley",
        "dropoff_street2": "303",
        "dropoff_street": "2540 College Ave",
        "pickup_buffer": 300,
        "pickup_zipcode": "94704",
        "pickup_state": "CA",
        "pickup_city": "Berkeley",
        "pickup_street2": "PH",
        "pickup_street": "2150 Shattuck Ave",
        "customer_email": "demo@axlehire.com",
        "customer_phone_number": "333-444-8888",
        "customer_name": "James Smith",
        "client_internal_shipment_id": "1",
        "workload": 1
      }
    ]
  }
}

Example error response

{
  "success": false,
  "code": 400,
  "message": "Some addresses failed to geocode properly."
  "data": {
    "shipments": [
      {
        "client_internal_shipment_id": "1",
        "customer_name": "James Smith",
        "customer_phone_number": "333-444-3333",
        "customer_email": "demo@axlehire.com",
        "pickup_street": "2150 Shattuck Ave",
        "pickup_street2": "PH",
        "pickup_city": "Berkeley",
        "pickup_state": "CA",
        "pickup_zipcode": "94704",
        "pickup_buffer": 300,
        "dropoff_street": "2540 College Ave",
        "dropoff_street2": "303",
        "dropoff_city": "Berkeley",
        "dropoff_state": "CA",
        "dropoff_zipcode": "94720",
        "dropoff_buffer": 600,
        "dropoff_latest_ts": "2016-05-24T11:42:37-07:00",
        "client_id": 1
      }
    ],
    "successfully_geocoded_shipments": [],
    "failed_geocoded_shipments": [
      {
        "client_internal_shipment_id": "1",
        "customer_name": "James Smith",
        "customer_phone_number": "555-444-6666",
        "customer_email": "demo@axlehire.com",
        "pickup_street": "2150 Shattuck Ave",
        "pickup_street2": "PH",
        "pickup_city": "Berkeley",
        "pickup_state": "CA",
        "pickup_zipcode": "94704",
        "pickup_buffer": 300,
        "dropoff_street": "2540 College Ave",
        "dropoff_street2": "303",
        "dropoff_city": "Berkeley",
        "dropoff_state": "CA",
        "dropoff_zipcode": "94720",
        "dropoff_buffer": 600,
        "dropoff_latest_ts": "2016-05-24T11:42:37-07:00",
        "client_id": 1
      }
    ],
    "failed_locations_with_suggestions": [
      {
        "street": "2540 College Ave",
        "city": "Berkeley",
        "state": "CA",
        "zipcode": "94720",
        "type": "dropoff",
        "client_internal_shipment_id": "1",
        "suggestions": [
          {
            "latitude": 37.86408,
            "longitude": -122.254124,
            "address": "2540 College Ave, Berkeley, CA 94704, USA",
            "street": "2540 College Avenue",
            "city": "Berkeley",
            "state": "CA",
            "zipcode": "94704"
          }
        ]
      }
    ],
    "failed_locations": []
  }
}
{
  "error": {
    "code": 422,
    "message": "Shipment/s field validation failed!"
  },
  "data": [
    {
      "dropoff_latest_ts": "Latest dropoff time missing!",
      "id": "1"
    }
  ]
}

Update Shipment

Updates the properties of a shipment. Archived shipments are not allowed to be updated.

These are the fields that can be updated after a shipment has been created. If another field of a pending shipment needs to be updated then delete the old pending shipment and create a new shipment.

All times passed inside the request body needs to be passed with a timezone offset from UTC, otherwise it will be interpretted as UTC.

The following fields can be editted after being created:

Property Description Type
client_internal_shipment_id Shipment ID for client's internal tracking String
customer_name Customer's name String
customer_phone_number Customer's phone number String
customer_email Customer's email String
pickup_street2 Pickup's address's apt or room String
pickup_buffer Pickup's service time Number
pickup_earliest_ts Pickup's earliest time Date
pickup_latest_ts Pickup's latest time Date
dropoff_street2 Dropoff's address's apt or room String
dropoff_buffer Dropoff's service time Number
dropoff_earliest_ts Dropoff's earliest time Date
dropoff_latest_ts Dropoff's latest time Date
delivery_photo_required Option to require photo at dropoff (Default: false) Boolean
delivery_signature_required Option to require signature at dropoff (Default: false) Boolean

The following fields can not be updated after creation:

Property Description Type
pickup_street Pickup's street address String
pickup_city Pickup's city String
pickup_state Pickup's state String
pickup_zipcode Pickup's zipcode String
dropoff_street Dropoff's street address String
dropoff_city Dropoff's city String
dropoff_state Dropoff's state String
dropoff_zipcode Dropoff's zipcode String

Error Handling:

  • 400 Error Code - Shipment not found.
  • 422 Error Code - Validation error with a field not being editable or valid.
  • 500 Error Code - Database update error
PATCH
/shipments/{shipment_id}

Example request

curl -XPATCH
     -H 'Authorization: Bearer {API_TOKEN}'
     -H 'Content-type: application/json;
     -d '{"customer_name": "Long Tran"}'
     'https://api.axlehire.com/shipments/{shipment_id}'

Example request body

{
    "customer_name": "Long Tran"
}

Example successful response

{
    "success": true,
    "message": "Shipment {shipment_id} updated.",
    "data": {
        "_id": "{shipment_id}",
        "dropoff_longitude": -122.2697218,
        "dropoff_latitude": 37.8700762,
        "pickup_longitude": -122.268613,
        "pickup_latitude": 37.870019,
        "client_id": 1,
        "dropoff_latest_ts": "2016-05-25T18:42:37.000Z",
        "dropoff_buffer": 300,
        "dropoff_zipcode": "94704",
        "dropoff_state": "CA",
        "dropoff_city": "Berkeley",
        "dropoff_street2": "709",
        "dropoff_street": "2040 Center Street",
        "pickup_buffer": 300,
        "pickup_zipcode": "94704",
        "pickup_state": "CA",
        "pickup_city": "Berkeley",
        "pickup_street2": "PH",
        "pickup_street": "2150 Shattuck Ave",
        "customer_email": "long@axlehire.com",
        "customer_phone_number": "760-583-5579",
        "customer_name": "Long Tran",
        "client_internal_shipment_id": "2",
        "workload": 1
    }
}

Example error response

{
    "message": "Validation error/s!",
    "error": {
        "status": 422,
        "fields": {
            "pickup_street": "pickup_street is not editable!"
        }
    }
}

Delete Shipment

Delete a pending shipment. Archived shipments are not allowed to be deleted.

Error Handling:

  • 500 Error Code - Database error
DELETE
/shipments/{shipment_id}

Example request

curl -XDELETE
     -H 'Authorization: Bearer {API_TOKEN}'
     -H 'Content-type: application/json'
     'https://api.axlehire.com/shipments/{shipment_id}'

Example response

{
  "success": true,
  "message": "Shipment {shipment_id} deleted."
}

Get Shipment Status

Get the status of a shipment that has been archived and put into a job. Status information includes the following:

  • status
  • pickup_predicted_departure_ts
  • pickup_actual_departure_ts
  • dropoff_predicted_departure_ts
  • dropoff_actual_departure_ts

To get all archived shipment statuses, pass all for {shipment_id} and an array of all shipment statuses will be returned.

Error Handling

  • 404 Error Code - Shipment not found in archived shipments collection
GET
/shipments/{shipment_id}/status

Example request

curl -XGET
     -H 'Authorization: Bearer API_TOKEN'
     -H "Content-type: application/json"
     'https://api.axlehire.com/shipments/{shipment_id}/status'

Example response

{
  "success": true,
  "data": [
    {
      "_id": "5759fd20e83a0a1a5e5dec2e",
      "client_internal_shipment_id": "11",
      "customer_name": "James Smith",
      "customer_phone_number": "555-444-7777",
      "customer_email": "demo@axlehire.com",
      "pickup_street": "2150 Shattuck Ave",
      "pickup_street2": "PH",
      "pickup_city": "Berkeley",
      "pickup_state": "CA",
      "pickup_zipcode": "94704",
      "pickup_buffer": 300,
      "dropoff_street": "3797 Stoneglen North",
      "dropoff_street2": "69",
      "dropoff_city": "Richmond",
      "dropoff_state": "CA",
      "dropoff_zipcode": "94820",
      "dropoff_buffer": 600,
      "dropoff_note": "Note for dropoff",
      "dropoff_earliest_ts": "2016-06-10T15:00:00.000Z",
      "dropoff_latest_ts": "2016-06-10T19:00:00.000Z",
      "client_id": 1,
      "dropoff_latitude": 37.98443,
      "dropoff_longitude": -122.33471,
      "pickup_latitude": 37.870019,
      "pickup_longitude": -122.268613,
      "job_id": 428,
      "shipment_id": 37454,
      "workload": 1,
      "pickup_predicted_departure_ts": "2016-06-10T07:54:52.000Z",
      "pickup_actual_departure_ts": "2016-06-11T19:07:41.126Z",
      "dropoff_predicted_departure_ts": "2016-06-10T08:26:34.000Z",
      "dropoff_actual_departure_ts": "2016-06-11T19:09:45.309Z",
      "status": "DELIVERY_FAILED"
    }
  ]
}

Crons

This is the crons API. An AxleHire API cron is a scheduled task that runs at scheduled times. The purpose of AxleHire's API cron is to allow for a stream of shipments to come in through our API and then batched at a certain scheduled time to create a job.

Feel free to read more about cron-type syntax here.

AxleHire's cron syntax also allows for seconds to be set as opposed to the traditional Linux cron syntax which is restricted to having minutes as the smallest time denominator.

View Crons

Get all created crons.

Error Handling:

  • 500 Error Code - Database query error
GET
/crons

Example request

$ curl -XGET \
       -H 'Authorization: Bearer {API_TOKEN}' \
       -H 'Content-type: application/json' \
       'https://api.axlehire.com/crons'

Example Response

{
  "success": true,
  "data": [
    {
      "_id": "57e173f78fd4d0004f4a2de0",
      "name": "cron_3pm",
      "_client": "57646f0d0383e84883a7d491",
      "client_id": 1,
      "__v": 0,
      "active": true,
      "interval": 24,
      "cron": "0 0 15 * * *"
    },
    {
      "_id": "57e174a5fc4edd164faf9a88",
      "name": "cron_5pm",
      "_client": "57646f0d0383e84883a7d491",
      "client_id": 1,
      "__v": 0,
      "active": true,
      "interval": 24,
      "cron": "00 00 17 * * *"
    }
  ]
}

View a Cron

Get selected cron's information.

Error Handling:

  • 500 Error Code - Database query error
GET
/crons/{cron_id}

Example request

$ curl -XGET \
       -H 'Authorization: Bearer {API_TOKEN}' \
       -H 'Content-type: application/json' \
       'https://api.axlehire.com/crons/{cron_id}'

Example Response

{
  "success": true,
  "data": {
    "_id": "57e173f78fd4d0004f4a2de0",
    "name": "skydeck_test_up",
    "_client": "57646f0d0383e84883a7d491",
    "client_id": 1,
    "__v": 0,
    "active": true,
    "interval": 24,
    "cron": "0 0 15 * * *"
  }
}

Create Cron

Creates a cron. The following fields can/need to be included inside the request body.

Property Description Type Optionality
cron Cron time string String required
interval Hours from cron trigger as window to batch shipments according to their dropoff times Number required
name Name for cron String recommended

Error Handling

  • 500 Error Code - Database error
  • 422 Error Code - Field validation error
POST
/crons

Example Request

curl -XPOST \
     -H 'Authorization: Bearer {API_TOKEN}'
     -H 'Content-type: application/json' \
     -d '{"cron": "00 00 15 1-5 * *",
         "interval": 24,
         "name": "new_cron_3pm_weekdays"}' \
     https://api.axlehire.com/crons

Example Request Body

{
  "cron": "00 00 15 1-5 * *",
  "interval": 24,
  "name": "new_cron_3pm_weekdays"
}

Example Response

{
  "success": true,
  "data": {
    "_id": "57e1a0c4675fae2e54aead1f",
    "_client": "57646f0d0383e84883a7d491",
    "client_id": 1,
    "active": true,
    "interval": 24,
    "name": "new_cron_3pm_weekdays",
    "cron": "00 00 15 1-5 * *"
  }
}

Update Cron

Updates the properties of a cron. The following fields can be editted:

Property Description Type
cron Cron time string String
interval Hours from cron trigger as window to batch shipments according to their dropoff times Number
name Name of cron String
active Cron is active or not Boolean

Error Handling

  • 500 Error Code - Database error
  • 422 Error Code - Field validation error
PATCH
/crons/{cron_id}

Example Request

curl -XPATCH \
     -H "Content-type: application/json" \
     -d '{"cron": "00 00 15 1-5 * *",
         "interval": 24,
         "name": "new_cron_3pm_weekdays"}' \
     https://api.axlehire.com/crons/{cron_id}

Example Request Body

{
  "interval": 18,
}

Example Response

{
  "success": true,
  "message": "Cron updated!",
  "data": {
    "_id": "57e1a0c4675fae2e54aead1f",
    "_client": "57646f0d0383e84883a7d491",
    "client_id": 1,
    "active": true,
    "interval": 18,
    "name": "new_cron_3pm_weekdays",
    "cron": "00 00 15 1-5 * *"
  }
}

Delete Cron

Delete a cron. If you want to stop the cron, but have it continue in the future, it might be better to change the active attribute of the cron to false and return it to true later on.

Error Handling:

  • 500 Error Code - Database error
DELETE
/crons/{cron_id}

Example request

curl -XDELETE
     -H 'Authorization: Bearer API_TOKEN'
     -H 'Content-type: application/json'
     'https://api.axlehire.com/crons/{cron_id}'

Example response

{
  "success": true,
  "message": "Cron {cron_id} deleted."
}

Buckets

A bucket is a grouping parent of shipments and is the premature state of a job before it is converted into a job.

Shipments can be inserted into a specific bucket, and the bucket will hold these shipments until the bucket's trigger time, which will then move all its contained shipments to the archived shipments collection.

View Buckets

Get all created buckets.

Error Handling:

  • 500 Error Code - Database query error
GET
/buckets

Example request

$ curl -XGET \
       -H 'Authorization: Bearer API_TOKEN' \
       -H "Content-type: application/json" \
       'https://api.axlehire.com/buckets'

Example Response

{
  "success": true,
  "data": [
    {
      "_id": "57e576baa6cbae201590880a",
      "name": "bucket-test1",
      "client_id": 1,
      "__v": 0,
      "active": true,
      "shipments_count": 0,
      "shipments": [],
      "trigger_time": "2016-09-23T18:40:00.000Z"
    },
    {
      "_id": "57e576c253296b2815179864",
      "name": "bucket-test2",
      "client_id": 1,
      "__v": 0,
      "active": true,
      "shipments_count": 0,
      "shipments": [],
      "trigger_time": "2016-09-23T18:40:00.000Z"
    }
  ]
}

View a Bucket

Get selected bucket's information.

Error Handling:

  • 500 Error Code - Database query error
GET
/buckets/{bucket_id}

Example request

$ curl -XGET \
       -H 'Authorization: Bearer API_TOKEN' \
       -H "Content-type: application/json" \
       'https://api.axlehire.com/buckets/{bucket_id}'

Example Response

{
  "success": true,
  "data": {
    "_id": "57e576baa6cbae201590880a",
    "name": "bucket-test1",
    "client_id": 1,
    "__v": 0,
    "active": true,
    "shipments_count": 0,
    "shipments": [],
    "trigger_time": "2016-09-23T18:40:00.000Z"
  }
}

Create Bucket

Creates a bucket. The following fields can/need to be included inside the request body.

Property Description Type Optionality
name Name for cron String recommended
trigger_time Datetime for bucket to convert to job Date required

Error Handling

  • 500 Error Code - Database error
  • 422 Error Code - Field validation error
POST
/crons

Example Request

curl -XPOST \
     -H "Content-type: application/json" \
     -d '{"trigger_time": "2016-09-23T18:40:00.000Z",
         "name": "bucket-test3"}' \
     'https://api.axlehire.com/buckets'

Example Request Body

{
    "trigger_time": "2016-09-23T18:40:00.000Z",
    "name": "bucket-test3"
}

Example Response

{
  "success": true,
  "data": {
    "__v": 0,
    "name": "bucket_2",
    "client_id": 1,
    "_id": "581a8af2ed46e62b5c05e0bd",
    "active": true,
    "shipments_count": 0,
    "shipments": [],
    "trigger_time": "2016-11-03T00:56:00.000Z"
  }
}

Update Bucket

Updates the properties of a buckets. Note that the bucket trigger time needs to be after the current datetime.

The following fields can be editted:

Property Description Type
trigger_time Datetime for bucket to be converted into a job Date
name Bucket name String
active Bucket is active or not Boolean

Error Handling

  • 500 Error Code - Database error
  • 422 Error Code - Field validation error
PATCH
/buckets/{bucket_id}

Example Request

curl -XPATCH \
     -H 'Content-type: application/json' \
     -d '{"name": "updated-bucket"}' \
     'https://api.axlehire.com/buckets/{bucket_id}'

Example Request Body

{
  "name": "updated-bucket"
}

Example Response

{
  "success": true,
  "message": "Bucket 57e576baa6cbae201590880a updated.",
  "data": {
    "_id": "57e576baa6cbae201590880a",
    "name": "updated-bucket",
    "client_id": 1,
    "__v": 0,
    "active": true,
    "shipments_count": 0,
    "shipments": [],
    "trigger_time": "2016-09-23T18:40:00.000Z"
  }
}

Delete Bucket

Deletes a bucket and all it's contained shipments.

DELETE
/buckets/{bucket_id}

Example request

curl -XDELETE
     -H 'Content-type: application/json'
     -H 'Authorization: Bearer API_TOKEN'
     'https://api.axlehire.com/buckets/{bucket_id}'

Example Response

{
  "success": true,
  "message": "Bucket 57e576baa6cbae201590880a deleted."
}

Get Bucket Shipments

Queries and returns the bucket's information with a list of the bucket's shipments with each of their information.

GET
/buckets/{bucket_id}/shipments

Example request

curl -XGET
     -H 'Content-type: application/json'
     -H 'Authorization: Bearer API_TOKEN'
     'https://api.axlehire.com/buckets/{bucket_id}/shipments'

Example Response

{
  "success": true,
  "data": {
    "_id": "57e588073bc33c8816866f6b",
    "name": "bucket-name",
    "client_id": 1,
    "__v": 0,
    "active": true,
    "shipments_count": 1,
    "shipments": [
      {
        "_id": "57e59976da7d695418909803",
        "client_internal_shipment_id": "1",
        "customer_name": "James Smith",
        "customer_phone_number": "888-777-6666",
        "customer_email": "demo@axlehire.com",
        "pickup_street": "2150 Shattuck Ave",
        "pickup_street2": "PH",
        "pickup_city": "Berkeley",
        "pickup_state": "CA",
        "pickup_zipcode": "94704",
        "pickup_buffer": 300,
        "dropoff_street": "2540 College Ave",
        "dropoff_street2": "303",
        "dropoff_city": "Berkeley",
        "dropoff_state": "CA",
        "dropoff_zipcode": "94704",
        "dropoff_buffer": 600,
        "dropoff_earliest_ts": "2016-09-24T15:00:00.000Z",
        "dropoff_latest_ts": "2016-09-24T23:00:00.000Z",
        "bucket_id": "57e588073bc33c8816866f6b",
        "client_id": 1,
        "dropoff_latitude": 37.86408,
        "dropoff_longitude": -122.254124,
        "pickup_latitude": 37.870019,
        "pickup_longitude": -122.268613,
        "delivery_proof_photo_required": false,
        "delivery_signature_required": false,
        "delivery_photo_required": false,
        "workload": 1
      }
    ],
    "trigger_time": "2016-09-23T19:55:00.000Z"
  }
}

Routing

With the routing endpoints, jobs can be turned into problems which are in turn solved, producing solutions. These solutions are be viewed and selected as the final solution for the generated problems.

Get Routing Configurations

Query all the routing configurations available to route a problem with.

GET
/jobs/configs

Example request

curl -XGET \
     -H 'Content-type: application/json' \
     -H 'Authorization: Bearer {API_TOKEN}' \
     'https://api.axlehire.com/jobs/configs'

Example success response

{
  "success": true,
  "data": [
    {
      "id": "57a240360c13c4bdda011697",
      "alias": "skydeck"
    },
    {
      "id": "57a387dd0c13c4172ca612f5",
      "alias": "skydeck2"
    },
    {
      "id": "5820dd390c13c45974c22793",
      "alias": "skydeck3"
    }
  ]
}

Example error response

{
  "status": 500,
  "message": "Failed to get routing configurations."
}

Create Routing Problem

Pass the job ID in the URL params to create a problem and automatically trigger solving the problem. The problem will be solved with a routing configuration provided as a configuration alias or id inside the request body payload.

The job ID can be acquired from one of the archived shipments as it's job_id field. If the job was created through a bucket, the deactivated bucket also contains the saved job_id.

POST
/jobs/{job_id}/route

Example request

curl -XPOST \
     -H "Content-type: application/json" \
     -H 'Authorization: Bearer {API_TOKEN}' \
     -d '{"alias": "skydeck"}' \
     'https://api.axlehire.com/jobs/{job_id}/route'

Example request body

{
  "alias": "skydeck"
}

Example success response

{
  "success": true,
  "data": {
    "problem_id": 221,
    "message": "Successfully started routing problem."
  }
}

Example error response

{
  "status": 500,
  "message": "Failed to create problem and start routing."
}

Get Problem Solution

Pass the job ID in the URL params to get the most recent solution for the problem in which the job is being routed.

GET
/jobs/{job_id}/solutions

Example request

curl -XGET \
     -H "Content-type: application/json" \
     -H 'Authorization: Bearer {API_TOKEN}' \
     'https://api.axlehire.com/jobs/{job_id}/solutions'

Example success response

{
  "success": true,
}

Example error response

{
  "status": 500,
  "message": "Failed to get the most recent solution for job's problem."
}

Get All Problem's Solution

Pass the job ID in the URL params to get all the solutions for the problems in which the job is being routed.

GET
/jobs/{job_id}/solutions

Example request

curl -XGET \
     -H "Content-type: application/json" \
     -H 'Authorization: Bearer API_TOKEN' \
     'https://api.axlehire.com/jobs/{job_id}/solutions'

Example success response

{
  "success": true,
}

Example error response

{
  "status": 500,
  "message": "Failed to get the solutions for job's problem."
}
Show examples in:
AxleHire API Documentation