API overview

The Droplet API lets you create forms, move submissions through workflows, manage datasets and accounts, and pull your data into your own systems, all over a clean REST interface. This page covers everything you need before your first call: the base URL, how to authenticate, the shape of every request and response, and a few conventions that make the rest of the reference click into place.

Base URL

Every endpoint lives under one base URL, with versioned paths:

https://api.droplet.io

So a call to /v1/forms/ids is really https://api.droplet.io/v1/forms/ids. The /v1 prefix is the API version, and we will give you plenty of notice before anything about it changes.

Authentication

Authenticating is a two-step exchange. You hold a long-lived API token (Droplet calls it your identityToken), trade it for a short-lived access token, then send that access token on every other request.

First, exchange your API token for an access token by calling the Identity endpoint with your API token in the Authorization header:

curl -X POST https://api.droplet.io/v1/identity/client-access \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

The response carries an accessToken (along with your organization and permission map). Send that access token as the bearer on every subsequent call:

Authorization: Bearer YOUR_ACCESS_TOKEN

Both tokens are secrets, scoped to your organization and your permissions, so they can only do what your account is allowed to do. Treat them like a password: never commit them to source control, and never expose them in client-side code. Anyone with your token can act as you, so if one is ever exposed, rotate it right away and let us know so we can help.

Need an API token? Contact your Droplet administrator or support@droplet.io to get set up. To confirm a token is working and see exactly what it can do, call the Identity API (POST /v1/identity/client-access), which returns your organization and the permissions the token carries.

Your first request

Once you have an access token (see Authentication above), here is a complete, working example that lists the form IDs in your organization:

curl https://api.droplet.io/v1/forms/ids \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

A successful call returns something like this:

{
  "requestId": "req_8f2c1a",
  "success": true,
  "data": {
    "count": 3,
    "ids": ["frm_a1", "frm_b2", "frm_c3"]
  }
}

Response format

Every response comes back in the same envelope, so you always know where to look:

Errors

When something goes wrong, success is false and an error object takes the place of data. Always check success before you read data.

{
  "requestId": "req_9a1d04",
  "success": false,
  "error": {
    "code": "forbidden",
    "message": "You do not have access to this form."
  }
}

The usual causes are a missing or expired token, a token without the right permission, or an ID that does not exist. A 401 on an otherwise-correct request almost always means your 5-minute access token has expired, so request a fresh one from POST /v1/identity/client-access and retry. The requestId is your friend here: send it to us and we can see the exact failure on our side.

The IDs, then entities pattern

Across Droplet, listing and fetching are split into two steps, and once you spot it you will see it everywhere. First you ask for the IDs that match your filters, then you fetch the full records for the ones you care about.

Why two steps? It keeps list calls fast and lets you page through large sets of IDs cheaply, then pull full detail only for the records you actually need. Every major resource (forms, submissions, datasets, accounts, and packets) follows this pattern.

Pagination

List endpoints that can return a lot of results accept a page query parameter. Pages are zero-based, so the first page is page=0:

curl 'https://api.droplet.io/v1/forms/ids?page=0&search=intake' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

The count in the response is the total number of matches. The reliable recipe: request page=0, then keep incrementing page and collecting the returned IDs until you have gathered count of them, hydrating each page of IDs with the matching entities endpoint as you go.

Conventions

• Path placeholders. A colon in a path, like /v1/forms/:id, marks a value you replace. /v1/forms/frm_a1 fetches the form with that ID.
• IDs are strings. Pass and store them as strings, even when they look numeric.
• JSON in, JSON out. Send Content-Type: application/json on any request that has a body.
• Timestamps come back in ISO 8601, in UTC.

Fair use

To keep the API fast and reliable for everyone, automated traffic may be rate limited. Batch your work where you can (the IDs, then entities pattern helps), avoid tight polling loops, and if you are planning a high-volume integration, get in touch at support@droplet.io so we can make sure it goes smoothly.

Explore the resources

Ready to build? Each resource has its own reference, with every endpoint documented and examples you can copy:

• Forms create, edit, publish, and organize forms.
• Submissions read, create, move, export, and act on submissions.
• Packets build templates and send and track bundles of forms.
• Datasets manage the reference data that powers your forms.
• Accounts manage the people and roles in your organization.
• Identity verify a token and see its permissions.