Skip to main content

Overview

Introduction​

Dripcel exposes various REST API endpoints for you to interact with the system programmatically.

The base route of the API is https://api.dripcel.com.

Most concepts in Dripcel have a corresponding API endpoint. Read more about each endpoint in it's documentation.

tip

You can use the Dripcel API Request Collection to interact with the API using the REST client of your choice.

Authentication​

All API endpoints require authentication.

You can authenticate using an API key for your Dripcel organisation. You can generate a key by logging into your account and going to the API keys page. Click the Generate Key button to generate a new key.

caution

Keep this key safe - it is as important as your Dripcel password.

You can authenticate to the API by passing the key as a Bearer Token in the Authorization header of your requests:

{ "Authorization": "Bearer <key>" }

Permissions​

Just like org members, API keys have roles/permissions that determine what they can/can't do. You can set these permissions when you generate a key, and click the "Modify Permissions" button to change them from the API keys page.

danger

By default, API keys have the same permissions as the user who created them, which may often be more than necessary. Always create keys with the fewest permissions needed to achieve its goal.

Some permissions are nested under others. For example, the contact.update.tag_ids permission is nested under the contact.update permission. This means that if you have the contact.update permission, you also have the contact.update.tag_ids permission, but not the other way around.

Response Format​

All responses are returned in JSON format.

Responses can either be successful or unsuccessful. Every response has an ok: boolean field that indicates whether the request was successful or not.

Successful responses have a data field that contains the response data.

{
  ok: true,
  data: unknown // Not necessarily an object
}

Unsuccessful responses have an error field that contains the error message.

{
  ok: false,
  error: unknown // Not necessarily a string
}

You can use this to check if a request was successful:

const response = await fetch("https://api.dripcel.com/balance", {
  headers: {
    Authorization: "Bearer <key>",
  },
});

const body = await response.json();

if (body.ok) {
  console.log("Your credit balance is", body.data);
} else {
  console.error("Error:", body.error);
}

Rate Limiting​

The API is rate limited to ~50 requests per minute per organisation.

If you exceed this limit, you will receive a 429 Too Many Requests response.

type RateLimitError = {
  ok: false;
  error: {
    resetsAt: number; // Unix timestamp
    remaining: number; // Number of requests remaining in the current window
  };
};

_id​

You'll notice that many endpoints require some _id field. This is the unique identifier of the resource. You can find the _id of a resource by:

  1. Navigating to the resource in the Dripcel app, and hover over the ID icon. Click to copy.
  2. Using the corresponding GET endpoint to retrieve a list of resources, and find the _id in the response.