EasyRoutes API - Getting Started Guide

This guide walks you through getting API access, authenticating, and making your first API call. By the end, you'll have retrieved your routes via the API.

What you'll need:

• An active EasyRoutes account (Shopify or Web)
• Admin access to EasyRoutes settings
• A way to make HTTP requests (terminal, Postman, etc.)

Set up API client ID and secret key

Before using the API, you may need to complete a quick verification process:

1. From your EasyRoutes Settings, access the API tab. You may see the following banner:

2. Click on Request access, enter your contact information, and submit the request form.

3. Our team will review your submission and notify you once verified.

Once we have verified your account, you'll be able to generate an API key.

Generating an API client ID and secret key

To enable API access, go to Settings > API, then click Generate API Key:

You'll receive two values:

Note: the Secret key is only available immediately after it is generated. The secret key should be copied and stored in a secure location. If you lose your secret key, you'll need to rotate it (see Rotating Secrets below).

Authenticating and making requests

To get started, exchange your client ID and secret key for a short-lived access token using the /authenticate         endpoint.

curl -X POST \                                                                                                   
-H "Content-Type: application/json; charset=utf-8" \
-d '{
        "clientId":"...",
        "clientSecret":"..."
    }' \
https://easyroutes.roundtrip.ai/api/2024-07/authenticate

You can then use the access token to retrieve routes like so:

curl \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://easyroutes.roundtrip.ai/api/2024-07/routes

Refer to Authenticate API for details.

Rotating Secrets

Forgot your secret key? If you have forgotten your secret key, you can initiate a key rotation to generate a new one. During the rotation, both the old key and the newly generated one will be valid for API authentication.

Once again, the new secret key is only viewable immediately after you generate it. Please copy and store it in a secure location before completing the rotation! Once you have migrated clients to the new key, click the Finish rotation button to disable the old key. You can also cancel the rotation at any time to disable the new key instead.

Make Your First API Call

Use your access token to retrieve a list of recent routes:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
 https://easyroutes.roundtrip.ai/api/2024-07/routes?query.sortKey=UPDATED_AT&query.limit=10

What's Next?

Now that you're authenticated, here's what you can do:

Documentation

Now that you have setup your initial API access, learn more about our API below and view our docs:

• Developer Overview - this guide provides a high-level overview to help you get started building integrations with EasyRoutes as a developer.
• API Reference Guide - read our guide to learn how to add stops into EasyRoutes for route planning, and access route and stop data
• Webhooks Guide - learn how to use our webhooks to react to real-time changes in routes and stops for integrations or connect with Zapier to integrate with no-code workflows

Zapier Integrations

You can use our API with Zapier to unlock seamless no-code workflows with your favorite apps and services, triggered by route updates in EasyRoutes or to import stops from your own data sources

• Import Stops Action - You can Import stops into EasyRoutes for planning with our Import Stop action on Zapier.
• Integrate with route- and stop-level updates with our Route Updated & Stop Status Updated Zapier triggers.
• Design custom workflows to suit your specific needs - see our Common Zapier Integrations support article for some specific examples and workflows.