Circle.us API

(Ver. 1.0.0)

Overview

Circle.us API enables developers to have seamless access to all Circle.us features, including validating addresses, using Circle.us universal carrier account, creating and rating shipment, purchasing labels at a discount rate, tracking packages, etc.

The workflow of using Circle.us API to create shipping labels

  • 1.Create address with Address request;
  • 2.Create shipments with Shipment request;
  • a.The addresses used in this process could be addresses retrieved with the address key generated in Address request, or address data uploaded by users;

  • b.When create the shipments, you have 2 options: create with the circle.us account, or with your own carrier accounts;

  • 3.Get shipping rate with the Rating API
  • a.If you are using circle.us account to create shipments, the Rating API is required in order to calculate the shipping rates before creating labels;
  • b.If you are using your own carrier accounts, the Rating API is not compulsory;
  • 4.Create shipping labels with Label request.
  • a.All label data are encoded with Base64
  • 5.Update package status with Tracking request.

This API doc is organized following the workflow of fulfilling a shipment. In addition, in order to make it easy for developers to understand and use Circle.us API, examples for each request are included.

More features are under developement and will be available soon. So, keep yourself tuned!

If you have any questions, please email support@circle.us.

API Endpoint


 https://api.circle.us

Authentication

Authenticate your account when using the API by including your API key in the request. You need to create a Circle.us account and you can find your API key in Setting - My Profile.

There is no test API key for Circle.us API but a “switch” in the label request for changing between test and production mode when creating labels. Therefore, it is highly recommended to make sure to keep your API key confidential, as the use of your API key may be considered as the behaviors of your Circle.us account. Do not share it in publicly accessible areas such as GitHub.

API KEY

All the request must be accompanied with a header. To use the API key, just include it in the header. In addition, content type should also be defined.


Authorization    : {apiKey}
Content-Type     : application/json

Errors

In the event of request fails, the respondent error codes and detailed messages will be returned to help you understand the reasons of the failure and debug your code.

Detailed list for error codes and messages in different types of requests will be provided in each request section.

Error Response(s)

The error codes and descriptions would be responsed when the requests are failed.

Error Response Example


Response:

    {
        "code": "ShipmentServer_00031",
        "message": "Shipment not found.",
        "additional": null,
        "otherErrors": []
    }

*List of error codes and descriptions would be attached in each corresponding section.

HTTP Status Code

The Common HTTP Status Code

Code Definition
200 The request was successful
400 The request was failed (reasons could be parameter error, server errors, etc,.
401 User Verification Failed

results matching ""

    No results matching ""