Getting Started

Step 1: Get Access

To use the API you will need an authentication token. To obtain an authentication token, you will need client credentials.

You can request authorized access here. We typically review and respond to access requests within two business days or less.

Conceptually, you will only need one set of credentials. Then you will reuse the credentials to generate and regenerate authentication tokens regularly because they expire on a frequent basis.

For experimentation, you can manually generate a token with your credentials using the Postman collection offer. When integrating with the API, you will want to automate this process because authentication tokens expire frequently.

Keep in mind that your credentials are secrets just like passwords, so you will want to store them securely.

Authentication is via Auth0’s Machine to Machine (M2M) Authorization and OAuth 2.0 provides the client credentials grant flow. More information at https://auth0.com/blog/using-m2m-authorization/

Step 2: Create a Delivery

Creating a delivery is easy: simply make a POST request to the Create Delivery endpoint.

For experimentation, you can do this by constructing your own JSON and POSTing with any HTTP client, or by using the Postman collection which includes sample data.

Don’t forget that you must include the authentication token you generated above as a header in all requests.

Step 3: Get Delivery Status

After creating a delivery, you may want to know its status. There are two ways to find out the status of a delivery.

You can poll the Get Delivery Info endpoint which is a simple HTTP GET request that will return information about the delivery including the status.

And, you can configure a webhook that will post the same delivery information including the status.

To setup a webhook in the Dolly Platform currently requires manual configuration (i.e. you send us the webhook URL and we configure it).

However, prior to the endpoint being configured you can view the webhooks called for a given order by visiting https://webhooks.sandbox.dolly.com/webhook/{:delivery_id}.

In order to trigger a webhook, you will use the Courier Actions commands in the Postman Collection to simulate a delivery process. Each step in the process, such as ARRIVED_AT_PICKUP or EN_ROUTE_TO_DROPOFF, will call your webhook.