FleetRunnr API
1.0

Copyright © FleetRunnr, Inc.

This is the documentation for version 1.0 of the API. Last update on Jul 20, 2022.

Base URL
https://{workspace}.fleetrunnr.com/api/v1

Authentication

Send a bearer token in the Authorization HTTP header to authenticate with the API.

To generate an access token, please go to the Settings page in the FleetRunnr portal, click on Access Tokens, and create a new one from there (https://app.fleetrunnr.com/settings/access-tokens).

Error Responses

All API requests return HTTP status codes that can tell you more about the response.

401 Unauthorized

The client doesn't have proper authentication headers.

{
  "message": "Unauthorized."
}

402 Payment Required

The account doesn't have a valid subscription or has overdue payments.

{
  "message": "Payment Required."
}

403 Forbidden

The requested resource is not accessible.

{
  "message": "Forbidden."
}

404 Not Found

The requested resource was not found.

{
  "message": "Not found."
}

422 Unprocessable Entity

The request body contains semantic errors. This is typically caused by incorrect formatting, omitting required fields, or logical errors.

{
  "message": "The given data was invalid."
  "errors": {
    ...
  }
}

429 Too Many Requests

The client has exceeded the API rate limit.

{
  "message": "Too many requests."
}

5xx Errors

An internal error occurred in FleetRunnr. Contact support for more information.

{
  "message": "Internal server error."
}

Retrieve Carriers

GET /carriers

Retrieve your connected carriers

Responses

GET /carriers
curl \
 -X GET https://{workspace}.fleetrunnr.com/api/v1/carriers \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "message": "string",
  "data": {
    "carriers": [
      {
        "uuid": "a66def5d-c2bc-4cbc-9ed6-a8815d08114c",
        "name": "ABC Logistics",
        "avatar": "https://example.com/logo.png",
        "shipping_methods": [
          {
            "uuid": "2beb8038-c028-480a-9d53-2eb1feea9252",
            "name": "On-Demand",
            "currency": "USD",
            "base_fee": 20,
            "weight_threshold": 5,
            "weight_surcharge": 0.25,
            "weight_unit": "kg",
            "distance_threshold": 10,
            "distance_surcharge": 7.5,
            "distance_unit": "km"
          },
          {
            "uuid": "b990bed5-f4d9-4fca-be74-7e990a4cd450",
            "name": "3-Day Shipping",
            "currency": "USD",
            "base_fee": 15,
            "weight_threshold": 10,
            "weight_surcharge": 2.25,
            "weight_unit": "kg",
            "distance_threshold": 30,
            "distance_surcharge": 5,
            "distance_unit": "km"
          }
        ]
      }
    ]
  }
}

Calculate Rates

POST /carriers/rates

Provide an order's information and retreive all carriers along with each of their assigned shipping methods with its calculated rate

Body

  • The source location coordinates

    • lat number

      Minimum value is -90, maximum value is 90.

    • lng number

      Minimum value is -180, maximum value is 180.

  • The destination location coordinates

    • lat number

      Minimum value is -90, maximum value is 90.

    • lng number

      Minimum value is -180, maximum value is 180.

  • departure_time string(date-time)

    Format should match the following pattern: YYYY-MM-DD HH:MM.

  • Minimum value is 0.

  • Values are kg or oz.

Responses

POST /carriers/rates
curl \
 -X POST https://{workspace}.fleetrunnr.com/api/v1/carriers/rates \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"source_location":{"lat":46.371826,"lng":-118.496391},"destination_location":{"lat":47.58213,"lng":-122.38324},"departure_time":"2022-01-20 13:30","total_weight":23.45,"weight_unit":"kg"}'
Request example
{
  "source_location": {
    "lat": 46.371826,
    "lng": -118.496391
  },
  "destination_location": {
    "lat": 47.58213,
    "lng": -122.38324
  },
  "departure_time": "2022-01-20 13:30",
  "total_weight": 23.45,
  "weight_unit": "kg"
}
Response example (200)
{
  "message": "success",
  "data": {
    "carriers": [
      {
        "uuid": "a66def5d-c2bc-4cbc-9ed6-a8815d08114c",
        "name": "ABC Logistics",
        "avatar": "https://example.com/logo.png",
        "workspace": "abc-logistics",
        "shipping_methods": [
          {
            "id": 1,
            "name": "Standard Shipping",
            "rate": 50,
            "currency": "USD"
          },
          {
            "id": 2,
            "name": "Return Shipping",
            "rate": 150,
            "currency": "USD"
          }
        ]
      }
    ]
  }
}

Get Customer

GET /customers

Retrieve a single customer by phone or email.

Set locations=true to include the customer's locations.

Query parameters

  • phone string(phone) Required

    Phone number in E.164 international format

  • email string(email) Required

    Valid email address (only required if phone is not specified)

  • locations boolean

    Include the customer’s locations

Responses

GET /customers
curl \
 -X GET https://{workspace}.fleetrunnr.com/api/v1/customers?phone=string&email=hello%40example.com \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "message": "string",
  "data": {
    "customer": {
      "uuid": "69e93118-a581-4a13-afea-b6d4a2d2c40c",
      "external_id": "ABCDE12345",
      "first_name": "John",
      "last_name": "Ondricka",
      "email": "john.ondricka@example.com",
      "phone": "+12163547758",
      "notes": "Some notes here...",
      "locations": [
        {
          "uuid": "84e249df-8d50-4212-8329-6059fc002563",
          "name": null,
          "line_1": "4840 Sun Valley Road",
          "line_2": "Flat 302",
          "city": "Prescott",
          "region": "Washington",
          "country": "US",
          "zip_code": "99348",
          "coordinates": {
            "lat": 46.371826,
            "lng": -118.496391
          }
        }
      ]
    }
  }
}

Create Customer

POST /customers

Create a new customer

Body

  • Customer's ID generated from a third-party system such as a CRM, POS, or accounting software

  • first_name string Required
  • last_name string Required
  • email string(email) Required

    Required if phone is not provided

  • phone string(phone) Required

    Phone number in E.164 international format.
    Required if email is not provided.

  • notes string

Responses

POST /customers
curl \
 -X POST https://{workspace}.fleetrunnr.com/api/v1/customers \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"external_id":"ABCD1234","first_name":"string","last_name":"string","email":"user@example.com","phone":"+12163547758","notes":"string"}'
Request example
{
  "external_id": "ABCD1234",
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "phone": "+12163547758",
  "notes": "string"
}
Response example (200)
{
  "message": "string",
  "data": {
    "customer_uuid": "string"
  }
}

Update Customer

PUT /customers/{customer_uuid}

Update the information of an existing customer

Body

  • Customer's ID generated from a third-party system such as a CRM, POS, or accounting software

  • first_name string Required
  • last_name string Required
  • email string(email) Required

    Required if phone is not provided

  • phone string(phone) Required

    Phone number in E.164 international format.
    Required if email is not provided.

  • notes string
PUT /customers/{customer_uuid}
curl \
 -X PUT https://{workspace}.fleetrunnr.com/api/v1/customers/{customer_uuid} \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"external_id":"ABCD1234","first_name":"string","last_name":"string","email":"user@example.com","phone":"+12163547758","notes":"string"}'
Request example
{
  "external_id": "ABCD1234",
  "first_name": "string",
  "last_name": "string",
  "email": "user@example.com",
  "phone": "+12163547758",
  "notes": "string"
}
Response example (200)
{
  "message": "success"
}

Retrieve Locations

GET /locations

Retrieve your account locations

Responses

GET /locations
curl \
 -X GET https://{workspace}.fleetrunnr.com/api/v1/locations \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "message": "string",
  "data": {
    "locations": [
      {
        "uuid": "27df9695-5565-4091-b888-ca321b8566ff",
        "name": "Main Warehouse",
        "line_1": "2313 Retreat Avenue",
        "line_2": "Ste 300",
        "city": "Birmingham",
        "region": "Alabama",
        "country": "US",
        "zip_code": "35203",
        "coordinates": {
          "lat": 33.527805,
          "lng": -86.768112
        }
      }
    ]
  }
}

Get Order

GET /orders

Retrieve a single order by order_number or external_id

Query parameters

  • external_id string Required

    The ID generated by your system (required if order_number is not specified)

  • order_number string Required

    The unique order number generated by FleetRunnr (required if external_id is not specified)

Responses

GET /orders
curl \
 -X GET https://{workspace}.fleetrunnr.com/api/v1/orders?external_id=string&order_number=string \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "message": "string",
  "data": {
    "order": {
      "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
      "order_number": "382968892483436544",
      "external_id": "XYZ987",
      "tracking_url": "https://track.fleetrunnr.com/382968892483436544?s=7fc3b54b8a4b02ffd",
      "status": "NEW",
      "customer": {
        "first_name": "John",
        "last_name": "Ondricka",
        "external_id": "ABCDE12345",
        "email": "john.ondricka@example.com",
        "phone": "+12163547758",
        "notes": "Some notes here..."
      },
      "source_location": {
        "uuid": "27df9695-5565-4091-b888-ca321b8566ff",
        "name": "Main Warehouse",
        "line_1": "2313 Retreat Avenue",
        "line_2": "Ste 300",
        "city": "Birmingham",
        "region": "Alabama",
        "country": "US",
        "zip_code": "35203",
        "coordinates": {
          "lat": 33.527805,
          "lng": -86.768112
        }
      },
      "source_contact": {
        "name": "Amanda Murrin",
        "email": "amanda.murrin@example.com",
        "phone": "+12025550159"
      },
      "destination_location": {
        "uuid": "84e249df-8d50-4212-8329-6059fc002563",
        "name": null,
        "line_1": "4840 Sun Valley Road",
        "line_2": "Flat 302",
        "city": "Prescott",
        "region": "Washington",
        "country": "US",
        "zip_code": "99348",
        "coordinates": {
          "lat": 46.371826,
          "lng": -118.496391
        }
      },
      "destination_contact": {
        "name": "John Ondricka",
        "email": "john.ondricka@example.com",
        "phone": "+12163547758"
      },
      "collections": [
        {
          "amount": 120.75,
          "currency": "USD",
          "type": "CASH"
        }
      ],
      "packages": [
        {
          "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
          "barcode": "383176549899173888",
          "type": "BAG",
          "length": 20,
          "width": 30,
          "height": 1,
          "weight": 0.25,
          "length_unit": "cm",
          "weight_unit": "kg"
        }
      ],
      "proof_of_delivery": {
        "signature": true,
        "image": false
      },
      "pickup_schedule": {
        "from": "2022-01-20 13:30",
        "to": "2022-01-20 15:00"
      },
      "delivery_schedule": {
        "from": "2022-01-23 09:00",
        "to": "2022-01-23 11:30"
      },
      "is_return": false,
      "notes": "These notes are used internally and not visible to customers..."
    }
  }
}

Create Order

POST /orders

Create a new order

Body

If the order uses the standard workflow (is_return is false), then the source_location should include the uuid of one of your account's locations.

If the order uses the return workflow (is_return is true), then the destination_location should include the uuid of one of your account's locations.

For packages, please check your account preferences for the measurement system your account is using (https://app.fleetrunnr.dev/settings/account)

Responses

POST /orders
curl \
 -X POST https://{workspace}.fleetrunnr.com/api/v1/orders \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"external_id":"XYZ987","customer":{"external_id":"ABCDE12345","first_name":"John","last_name":"Ondricka","email":"john.ondricka@example.com","phone":"+12163547758","notes":"Some notes here..."},"source_location":{"uuid":"27df9695-5565-4091-b888-ca321b8566ff"},"source_contact":{"name":"Amanda Murrin","email":"amanda.murrin@example.com","phone":"+12025550159"},"destination_location":{"name":null,"line_1":"4840 Sun Valley Road","line_2":"Flat 302","city":"Prescott","region":"Washington","country":"US","zip_code":"99348","coordinates":{"lat":46.371826,"lng":-118.496391}},"destination_contact":{"name":"John Ondricka","email":"john.ondricka@example.com","phone":"+12163547758"},"collections":[{"amount":120.75,"currency":"USD","type":"CASH"}],"packages":[{"type":"BAG","length":20,"width":30,"height":1,"weight":0.25}],"proof_of_delivery":{"signature":true,"image":false},"pickup_schedule":{"from":"2022-01-20 13:30","to":"2022-01-20 15:00"},"delivery_schedule":{"from":"2022-01-23 09:00","to":"2022-01-23 11:30"},"is_return":false,"notes":"These notes are internal and not visible to customers..."}'
{
  "external_id": "XYZ987",
  "customer": {
    "external_id": "ABCDE12345",
    "first_name": "John",
    "last_name": "Ondricka",
    "email": "john.ondricka@example.com",
    "phone": "+12163547758",
    "notes": "Some notes here..."
  },
  "source_location": {
    "uuid": "27df9695-5565-4091-b888-ca321b8566ff"
  },
  "source_contact": {
    "name": "Amanda Murrin",
    "email": "amanda.murrin@example.com",
    "phone": "+12025550159"
  },
  "destination_location": {
    "name": null,
    "line_1": "4840 Sun Valley Road",
    "line_2": "Flat 302",
    "city": "Prescott",
    "region": "Washington",
    "country": "US",
    "zip_code": "99348",
    "coordinates": {
      "lat": 46.371826,
      "lng": -118.496391
    }
  },
  "destination_contact": {
    "name": "John Ondricka",
    "email": "john.ondricka@example.com",
    "phone": "+12163547758"
  },
  "collections": [
    {
      "amount": 120.75,
      "currency": "USD",
      "type": "CASH"
    }
  ],
  "packages": [
    {
      "type": "BAG",
      "length": 20,
      "width": 30,
      "height": 1,
      "weight": 0.25
    }
  ],
  "proof_of_delivery": {
    "signature": true,
    "image": false
  },
  "pickup_schedule": {
    "from": "2022-01-20 13:30",
    "to": "2022-01-20 15:00"
  },
  "delivery_schedule": {
    "from": "2022-01-23 09:00",
    "to": "2022-01-23 11:30"
  },
  "is_return": false,
  "notes": "These notes are internal and not visible to customers..."
}
{
  "external_id": "XYZ987",
  "customer": {
    "uuid": "69e93118-a581-4a13-afea-b6d4a2d2c40c"
  },
  "source_location": {
    "uuid": "27df9695-5565-4091-b888-ca321b8566ff"
  },
  "source_contact": {
    "name": "Amanda Murrin",
    "email": "amanda.murrin@example.com",
    "phone": "+12025550159"
  },
  "destination_location": {
    "uuid": "84e249df-8d50-4212-8329-6059fc002563"
  },
  "destination_contact": {
    "name": "John Ondricka",
    "email": "john.ondricka@example.com",
    "phone": "+12163547758"
  },
  "collections": [
    {
      "amount": 120.75,
      "currency": "USD",
      "type": "CASH"
    }
  ],
  "packages": [
    {
      "type": "BAG",
      "length": 20,
      "width": 30,
      "height": 1,
      "weight": 0.25
    }
  ],
  "proof_of_delivery": {
    "signature": true,
    "image": false
  },
  "pickup_schedule": {
    "from": "2022-01-20 13:30",
    "to": "2022-01-20 15:00"
  },
  "delivery_schedule": {
    "from": "2022-01-23 09:00",
    "to": "2022-01-23 11:30"
  },
  "is_return": false,
  "notes": "These notes are internal and not visible to customers..."
}
Response example (200)
{
  "message": "success",
  "data": {
    "order_uuid": "20c48af2-cb48-40e7-9d1f-372f9ec5bfbc"
  }
}

Update Order

PATCH /orders/{order_uuid}

Update the information of an existing order

Body

  • The order ID generated from a third-party system such as a CRM, POS, or accounting software

    • signature boolean

      Indicate whether to require a signature upon delivery

    • image boolean

      Indicate whether to require a picture to be taken upon delivery

    • from string(date-time)

      Should be in UTC timezone

      Format should match the following pattern: YYYY-MM-DD HH:MM.

    • to string(date-time)

      Should be in UTC timezone

      Format should match the following pattern: YYYY-MM-DD HH:MM.

    • from string(date-time)

      Should be in UTC timezone

      Format should match the following pattern: YYYY-MM-DD HH:MM.

    • to string(date-time)

      Should be in UTC timezone

      Format should match the following pattern: YYYY-MM-DD HH:MM.

  • notes string
PATCH /orders/{order_uuid}
curl \
 -X PATCH https://{workspace}.fleetrunnr.com/api/v1/orders/{order_uuid} \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"external_id":"DEF456","proof_of_delivery":{"signature":true,"image":true},"pickup_schedule":{"from":"2022-01-20 13:30","to":"2022-01-20 15:00"},"delivery_schedule":{"from":"2022-01-23 09:00","to":"2022-01-23 11:30"},"notes":"string"}'
Request example
{
  "external_id": "DEF456",
  "proof_of_delivery": {
    "signature": true,
    "image": true
  },
  "pickup_schedule": {
    "from": "2022-01-20 13:30",
    "to": "2022-01-20 15:00"
  },
  "delivery_schedule": {
    "from": "2022-01-23 09:00",
    "to": "2022-01-23 11:30"
  },
  "notes": "string"
}
Response example (200)
{
  "message": "success"
}

Assign Carrier

POST /orders/{order_uuid}/assign

Assign an order to one of your connected carriers

Body

You may retrieve the carrier_uuid and the shipping_method_uuid from the Get Carriers endpoint.

  • carrier_uuid string(uuid) Required

    The carrier's uuid.

  • shipping_method_uuid string(uuid) Required

    The shipping method uuid

    This shipping method must be assigned to you by the specified carrier.

POST /orders/{order_uuid}/assign
curl \
 -X POST https://{workspace}.fleetrunnr.com/api/v1/orders/{order_uuid}/assign \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"carrier_uuid":"fd5bcc10-1feb-40c1-9ce7-a3001c6dbed3","shipping_method_uuid":"8a316441-72e9-44sa-b31e-60aff566c8a0"}'
Request example
{
  "carrier_uuid": "fd5bcc10-1feb-40c1-9ce7-a3001c6dbed3",
  "shipping_method_uuid": "8a316441-72e9-44sa-b31e-60aff566c8a0"
}
Response example (200)
{
  "message": "success"
}

Cancel Order

POST /orders/{order_uuid}/cancel

Cancel an existing order

POST /orders/{order_uuid}/cancel
curl \
 -X POST https://{workspace}.fleetrunnr.com/api/v1/orders/{order_uuid}/cancel \
 -H "Authorization: Bearer $ACCESS_TOKEN"
Response example (200)
{
  "message": "success"
}

Generate Labels

POST /orders/generate-labels

Generate labels for a list of orders

Body

  • orders array Required

    The array of order UUIDs

  • size string Required

    The shipping label size.

    Values are A4, A5, A6, PAPER_ROLL, or TAG.

Responses

POST /orders/generate-labels
curl \
 -X POST https://{workspace}.fleetrunnr.com/api/v1/orders/generate-labels \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"orders":["8eb8168d-07e3-4bf9-a678-636689d1a876"],"size":"A6"}'
Request example
{
  "orders": [
    "8eb8168d-07e3-4bf9-a678-636689d1a876"
  ],
  "size": "A6"
}
Response example (200)
{
  "message": "success",
  "data": {
    "url": "https://s3.eu-west-1.amazonaws.com/media.fleetrunnr/6e92736d-7f41-46de-9c72-6c8b74990722.pdf?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA3GLSPZCROCOCUP7S%2F20220401%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20220401T094455Z&X-Amz-SignedHeaders=host&X-Amz-Expires=300&X-Amz-Signature=51eda1ef262f8a0e21786814735a6144e6e157b867250892182fcbf0f04ca414"
  }
}