Getting Set Up - API

Testing

Trellus maintains a sandbox environment for testing purposes. If you would like to create a separate account in our sandbox, please contact us at support@bytrellus.com for instructions.

When using the sandbox, API requests must be sent to https://testapi.bytrellus.com/v1

Authentication

All requests must be authenticated using your organization’s API key.

Your API key is generated on successful creation of your Trellus account and can be viewed through the menu in the dashboard by going into the Account Integrations section.

A valid key must be provided with every request via HTTP header, where the key string is Authorization.

Postman Collection

Postman is a GUI tool for making API requests - we think it's very useful for learning the Trellus API, or testing requests as you're building an implementation.

You can find our Postman Collection here. Simply download, import it into Postman, and set your APIKey to get started. Remember to adjust the baseURL parameter if you are in the sandbox environment.

Checking your API key

You can use the /validate endpoint via HTTP POST to check that you are formatting your request correctly and that your API key is valid. This endpoint will also return your account’s subscriptionStatus, deliveryRate per mile over 5 miles and deliveryFee per package.

Data Types, Validation and Response Formats

• The API attempts to respond with a 200 status code whenever possible, whether the request was successful or there was a known error. Unknown errors will respond with a 500 status code. All responses will contain a success boolean parameter. 
• Monetary Amounts - All API requests consume and produce monetary amounts in USD and follow the currency’s smallest unit. 
• For example, a deliveryRate of $10.00, will be represented as a value of 1000 (i.e., 1000 cents).
• Timestamps  - consumed and produced in Unix epoch time format, with millisecond precision.
• Phone Numbers - consumed in either 10 digit number, 10 digit string, or string “(XXX) XXX-XXX” format, and produced in string “(XXX) XXX-XXX” format. Any leading “+” or “1” characters will be removed. Consumed phone numbers will be validated using Google's phone validation library.
• Addresses - consumed addresses will be validated by attempting to use Google Maps Javascript API to geocode the address.
• Street Addresses - consumed street addresses will have special characters removed in accordance with USPS Standards. This removal takes place prior to geocoding and directly before the following validation:
• The first part of the street address may only contain numbers, slashes (/), periods (.) and hyphens (-).
• Remaining parts may only contain letters or numbers
• Zip Codes - consumed in either 5 digit integer or string format, or 10 digit hyphenated string format. Produced in 5 or 10 digit string format.

Service Area

As of now, Trellus chiefly services Queens and Long Island, New York. Exact Service Area is determined by zip code. Any Addresses consumed by the API that are outside of the service area will return an appropriate error. 

Errors

Failed API responses will always contain the success boolean parameter set to false and have the most descriptive error or error(s) we can discern. 

For Delivery related requests, errors will be represented in the deliveryErrors array parameter. Delivery Errors will contain a code, name and descriptive message.

An Invalid Request

Here's an example response to a request with an invalid API key.

{ 
    "success":false,
    "deliveryErrors": [
        { 
            "code":4001,
            "name":"notAuthenticated",
            "message":"Not Authenticated" 
         } 
    ]
}

Error List

(Will be added soon)