Flodesk API provides programmatic access to Flodesk data and functionality, allowing developers to integrate and build custom features with your own system.
The REST API communicates exclusively in JSON over SSL (HTTPS). All endpoint URLs begin with https://api.flodesk.com/v1.
Parameters must be serialized in JSON and passed in the request body (not in the query string or form parameters).
You should use the media type designation of application/json
.
Flodesk API supports two types of integrations that use different forms of authentication:
Private integrations: Where you (a Flodesk member) or a developer on your behalf, integrate with the API yourself to access and update data for your own Flodesk account. For this type of integration, you’ll authenticate with your personal API key. Learn more about creating and managing API keys here.
Partner integrations: You represent an app that would like to build a direct integration which allows customers within your application to authorize direct access to their Flodesk accounts. In this case, you’re acting as an integration partner and must use OAuth2 based authentication with a Client ID and Secret. To apply to build a partner integration, please submit a request using this form.
Enter the API key as the username and set the password to an empty string. You can create and manage your API keys from the API Key page.
curl "api_endpoint_here" \
-H "User-Agent: Your App Name (www.yourapp.com)" \
-H "Authorization: Basic $(echo YOUR_API_KEY: | base64)"
basic
OAuth2 authentication provides developers with a secure way to access Flodesk API data on behalf of other Flodesk users. OAuth2 authentication is used for setting up partner integrations between third-party applications and Flodesk.
curl "api_endpoint_here" \
-H "User-Agent: Your App Name (www.yourapp.com)" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
authorizationCode
https://api.flodesk.com/oauth2/authorize
https://api.flodesk.com/oauth2/token
all
- full access to all API resources
Here's a quick overview of how to get started with OAuth2 based authentication.
https://api.flodesk.com/oauth2/authorize?client_id=<your_client_id>&redirect_uri=<your_redirect_uri>
&response_type=code&state=<a_random_string>
The user will then be redirected back to your app with a verification code that will expire in 30 minutes.
Your app will then need to make a request to exchange that verification code for an access_token and a refresh_token:
curl -X POST "https://api.flodesk.com/oauth2/token" \
-H "User-Agent: Your App Name (www.yourapp.com)" \
-H "Authorization: Basic $(echo <your_client_id>:<your_client_secret> | base64)" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "code=<verification_code>&redirect_uri=<redirect_uri>&grant_type=authorization_code"
{
"access_token": "eyJraWQiOiJuUWdsaD...",
"token_type": "Bearer",
"expires_in": 86400,
"scopes": "all",
"refresh_token": "fd_rt_aef123..."
}
You can now use that access_token in the header of your API requests as follows:
Authorization: Bearer <access_token>
This endpoint can be used to retrieve basic information about the user.
GET https://api.flodesk.com/oauth2/userinfo
Header: "Authorization: Bearer <access_token>"
Example call with curl:
curl https://api.flodesk.com/oauth2/userinfo \
-H "Authorization: Bearer <access_token>"
Response sample:
{
"id":"a9c3f01e-6cc4-47c5-8710-e6d3c319888e",
"email":"foo@baz.com",
"full_name":"Foo Baz",
"created_at":"2020-12-24T10:11:42.222Z"
}
The refresh_token is used to obtain a new access_token when the current one expires without the user's involvement. See the below example of how to perform token refresh:
curl -X POST "https://api.flodesk.com/oauth2/token" \
-H "User-Agent: Your App Name (www.yourapp.com)" \
-H "Authorization: Basic $(echo <your_client_id>:<your_client_secret> | base64)" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "refresh_token=<your_refresh_token>&grant_type=refresh_token"
The refresh_token is a long-lived token and single-use
only. Every time a client performs a token refresh, a new refresh_token is issued along with a new access_token, and the previous refresh_token is invalidated.
Make sure you store the new refresh_token for the next refresh.
You can make up to 100 requests per minute. If you exceed your rate limit, the API will return a 429 error.
All API requests subject to rate limiting contain information regarding your current rate limit status in the response headers:
HTTP/1.1 200 OK
Status: 200 OK
X-Fd-RateLimit-Limit: 100
X-Fd-RateLimit-Remaining: 68
page | integer <int64> The page number. Defaults to 1. |
per_page | integer <int64> The number of records to be returned on each page. Defaults to 20. Maximum 100. |
status | string Enum: "active" "unsubscribed" "unconfirmed" "bounced" "complained" "cleaned" Optional. The subscriber's status.
|
segment_id | string Optional. The segment's id. When included, returns only subscribers who were added to the given segment. |
object (PaginationRes) | |
Array of objects (SubscriberRes) |
{- "meta": {
- "page": 0,
- "total_pages": 0,
- "per_page": 0,
- "total_items": 0
}, - "data": [
- {
- "id": "string",
- "status": "active",
- "email": "string",
- "source": "manual",
- "first_name": "string",
- "last_name": "string",
- "segments": [
- {
- "id": "string",
- "name": "string"
}
], - "custom_fields": {
- "property1": "string",
- "property2": "string"
}, - "optin_ip": "string",
- "optin_timestamp": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z"
}
]
}
id | string The subscriber's |
string The subscriber's | |
first_name | string The subscriber's first name. |
last_name | string The subscriber's last name. |
object An object containing custom field data.
E.g. | |
segment_ids | Array of strings The segments this subscriber will be added to. Cap at |
double_optin | boolean Whether or not to require the subscriber to confirm subscription via email. This option is only available to set with new subscriber creation. Default to |
optin_ip | string IP address from which the subscriber confirmed their opt-in. |
optin_timestamp | string The date and time the subscribers confirmed their opt-in in ISO 8601 format.
E.g. |
id | string A read-only generated unique id used to identify each subscriber record. |
status | string Enum: "active" "unsubscribed" "unconfirmed" "bounced" "complained" "cleaned" The subscriber's status.
|
string The subscriber's email address. | |
source | string Enum: "manual" "csv" "form_optin" "integration" "checkout" The source from which the subscriber was added to your list.
|
first_name | string The subscriber's first name. |
last_name | string The subscriber's last name. |
Array of objects (SegmentMini) Segments that the subscriber was added to. Cap at | |
object An object containing custom field data.
E.g. | |
optin_ip | string IP address from which the subscriber confirmed their opt-in. |
optin_timestamp | string <date-time> The date and time the subscribers confirmed their opt-in in ISO 8601 format.
E.g. |
created_at | string <date-time> The date and time the subscriber was added to your list in ISO 8601 format. |
{- "id": "string",
- "status": "active",
- "email": "string",
- "source": "manual",
- "first_name": "string",
- "last_name": "string",
- "segments": [
- {
- "id": "string",
- "name": "string"
}
], - "custom_fields": {
- "property1": "string",
- "property2": "string"
}, - "optin_ip": "string",
- "optin_timestamp": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z"
}
id_or_email required | string |
id | string A read-only generated unique id used to identify each subscriber record. |
status | string Enum: "active" "unsubscribed" "unconfirmed" "bounced" "complained" "cleaned" The subscriber's status.
|
string The subscriber's email address. | |
source | string Enum: "manual" "csv" "form_optin" "integration" "checkout" The source from which the subscriber was added to your list.
|
first_name | string The subscriber's first name. |
last_name | string The subscriber's last name. |
Array of objects (SegmentMini) Segments that the subscriber was added to. Cap at | |
object An object containing custom field data.
E.g. | |
optin_ip | string IP address from which the subscriber confirmed their opt-in. |
optin_timestamp | string <date-time> The date and time the subscribers confirmed their opt-in in ISO 8601 format.
E.g. |
created_at | string <date-time> The date and time the subscriber was added to your list in ISO 8601 format. |
{- "id": "string",
- "status": "active",
- "email": "string",
- "source": "manual",
- "first_name": "string",
- "last_name": "string",
- "segments": [
- {
- "id": "string",
- "name": "string"
}
], - "custom_fields": {
- "property1": "string",
- "property2": "string"
}, - "optin_ip": "string",
- "optin_timestamp": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z"
}
id_or_email required | string |
segment_ids required | Array of strings An array of identifiers of the segments. |
id | string A read-only generated unique id used to identify each subscriber record. |
status | string Enum: "active" "unsubscribed" "unconfirmed" "bounced" "complained" "cleaned" The subscriber's status.
|
string The subscriber's email address. | |
source | string Enum: "manual" "csv" "form_optin" "integration" "checkout" The source from which the subscriber was added to your list.
|
first_name | string The subscriber's first name. |
last_name | string The subscriber's last name. |
Array of objects (SegmentMini) Segments that the subscriber was added to. Cap at | |
object An object containing custom field data.
E.g. | |
optin_ip | string IP address from which the subscriber confirmed their opt-in. |
optin_timestamp | string <date-time> The date and time the subscribers confirmed their opt-in in ISO 8601 format.
E.g. |
created_at | string <date-time> The date and time the subscriber was added to your list in ISO 8601 format. |
{- "id": "string",
- "status": "active",
- "email": "string",
- "source": "manual",
- "first_name": "string",
- "last_name": "string",
- "segments": [
- {
- "id": "string",
- "name": "string"
}
], - "custom_fields": {
- "property1": "string",
- "property2": "string"
}, - "optin_ip": "string",
- "optin_timestamp": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z"
}
id_or_email required | string |
segment_ids required | Array of strings An array of identifiers of the segments. |
id | string A read-only generated unique id used to identify each subscriber record. |
status | string Enum: "active" "unsubscribed" "unconfirmed" "bounced" "complained" "cleaned" The subscriber's status.
|
string The subscriber's email address. | |
source | string Enum: "manual" "csv" "form_optin" "integration" "checkout" The source from which the subscriber was added to your list.
|
first_name | string The subscriber's first name. |
last_name | string The subscriber's last name. |
Array of objects (SegmentMini) Segments that the subscriber was added to. Cap at | |
object An object containing custom field data.
E.g. | |
optin_ip | string IP address from which the subscriber confirmed their opt-in. |
optin_timestamp | string <date-time> The date and time the subscribers confirmed their opt-in in ISO 8601 format.
E.g. |
created_at | string <date-time> The date and time the subscriber was added to your list in ISO 8601 format. |
{- "id": "string",
- "status": "active",
- "email": "string",
- "source": "manual",
- "first_name": "string",
- "last_name": "string",
- "segments": [
- {
- "id": "string",
- "name": "string"
}
], - "custom_fields": {
- "property1": "string",
- "property2": "string"
}, - "optin_ip": "string",
- "optin_timestamp": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z"
}
id_or_email required | string |
id | string A read-only generated unique id used to identify each subscriber record. |
status | string Enum: "active" "unsubscribed" "unconfirmed" "bounced" "complained" "cleaned" The subscriber's status.
|
string The subscriber's email address. | |
source | string Enum: "manual" "csv" "form_optin" "integration" "checkout" The source from which the subscriber was added to your list.
|
first_name | string The subscriber's first name. |
last_name | string The subscriber's last name. |
Array of objects (SegmentMini) Segments that the subscriber was added to. Cap at | |
object An object containing custom field data.
E.g. | |
optin_ip | string IP address from which the subscriber confirmed their opt-in. |
optin_timestamp | string <date-time> The date and time the subscribers confirmed their opt-in in ISO 8601 format.
E.g. |
created_at | string <date-time> The date and time the subscriber was added to your list in ISO 8601 format. |
{- "id": "string",
- "status": "active",
- "email": "string",
- "source": "manual",
- "first_name": "string",
- "last_name": "string",
- "segments": [
- {
- "id": "string",
- "name": "string"
}
], - "custom_fields": {
- "property1": "string",
- "property2": "string"
}, - "optin_ip": "string",
- "optin_timestamp": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z"
}
page | integer <int64> The page number. Defaults to 1. |
per_page | integer <int64> The number of records to be returned on each page. Defaults to 20. Maximum 100. |
object (PaginationRes) | |
Array of objects (SegmentRes) |
{- "meta": {
- "page": 0,
- "total_pages": 0,
- "per_page": 0,
- "total_items": 0
}, - "data": [
- {
- "id": "string",
- "name": "string",
- "total_active_subscribers": 0,
- "created_at": "2019-08-24T14:15:22Z",
- "color": "string"
}
]
}
color | string The color of the segment using a hex code. |
name | string |
{- "id": "string",
- "name": "string",
- "total_active_subscribers": 0,
- "created_at": "2019-08-24T14:15:22Z",
- "color": "string"
}
id required | string |
id | string A read-only generated unique id used to identify each segment record. |
name | string Name of the segment. |
total_active_subscribers | integer <int64> The number of active subscribers within the segment. |
created_at | string <date-time> The date and time the segment was created in ISO 8601 format. |
color | string The color of the segment using a hex code. |
{- "id": "string",
- "name": "string",
- "total_active_subscribers": 0,
- "created_at": "2019-08-24T14:15:22Z",
- "color": "string"
}
statuses | Array of strings Items Enum: "active" "paused" "draft" filter by workflow statuses e.g. statuses=active,paused. Default is all statuses |
page | integer <int64> Default = 1 |
perPage | integer <int64> Default = 10 |
Array of objects (WorkflowRes) | |
object (PaginationRes) |
{- "data": [
- {
- "id": "string",
- "name": "string"
}
], - "meta": {
- "page": 0,
- "total_pages": 0,
- "per_page": 0,
- "total_items": 0
}
}
Only available for Workflow V2. See upgrade guide.
Note: In order for a subscriber to be added to a workflow subsequent times, (1) the subscriber has to have already completed the workflow, i.e. they cannot currently be active in the workflow, and (2) the "Allow repeat subscribers" setting for the workflow must be toggled on.
workflow_id required | string |
string
| |
id | string
|
Only available for Workflow V2. See upgrade guide.
workflow_id required | string |
id_or_email required | string |
page | integer <int64> The page number. Defaults to 1. |
per_page | integer <int64> The number of records to be returned on each page. Defaults to 20. Maximum 100. |
object (PaginationRes) | |
Array of objects (CustomFieldRes) |
{- "meta": {
- "page": 0,
- "total_pages": 0,
- "per_page": 0,
- "total_items": 0
}, - "data": [
- {
- "key": "string",
- "label": "string"
}
]
}
page | integer <int64> The page number. Defaults to 1. |
per_page | integer <int64> The number of records to be returned on each page. Defaults to 20. Maximum 100. |
object (PaginationRes) | |
Array of objects (WebhookRes) |
{- "meta": {
- "page": 0,
- "total_pages": 0,
- "per_page": 0,
- "total_items": 0
}, - "data": [
- {
- "id": "string",
- "post_url": "string",
- "events": [
- "string"
], - "created_at": "2019-08-24T14:15:22Z"
}
]
}
name required | string The webhook name. |
post_url required | string The url that the webhook will post to. |
events required | Array of strings An array specifying which events are enabled for webhook notifications. |
{- "id": "string",
- "post_url": "string",
- "events": [
- "string"
], - "created_at": "2019-08-24T14:15:22Z"
}
id required | string |
id | string A read-only generated unique id used to identify each webhook record. |
post_url | string The url that the webhook will post to. |
events | Array of strings An array specifying which events are enabled for webhook notifications. |
created_at | string <date-time> The date and time the webhook was created in ISO 8601 format. |
{- "id": "string",
- "post_url": "string",
- "events": [
- "string"
], - "created_at": "2019-08-24T14:15:22Z"
}
id required | string |
events | Array of strings An array specifying which events are enabled for webhook notifications. |
name | string The webhook name. |
post_url | string The url that the webhook will post to. |
id | string A read-only generated unique id used to identify each webhook record. |
post_url | string The url that the webhook will post to. |
events | Array of strings An array specifying which events are enabled for webhook notifications. |
created_at | string <date-time> The date and time the webhook was created in ISO 8601 format. |
{- "id": "string",
- "post_url": "string",
- "events": [
- "string"
], - "created_at": "2019-08-24T14:15:22Z"
}
This event is triggered when a subscriber is added to a segment in your Flodesk account.
event_name | string The webhook notification's event name. E.g. |
event_time | string <date-time> The timestamp indicates when the event occurred. |
object (SubscriberRes) | |
object (SegmentMini) | |
webhook_id | string The webhook's identifier. |
{- "event_name": "string",
- "event_time": "2019-08-24T14:15:22Z",
- "subscriber": {
- "id": "string",
- "status": "active",
- "email": "string",
- "source": "manual",
- "first_name": "string",
- "last_name": "string",
- "segments": [
- {
- "id": "string",
- "name": "string"
}
], - "custom_fields": {
- "property1": "string",
- "property2": "string"
}, - "optin_ip": "string",
- "optin_timestamp": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z"
}, - "segment": {
- "id": "string",
- "name": "string"
}, - "webhook_id": "string"
}
This event is triggered when a subscriber is created in your Flodesk account.
event_name | string The webhook notification's event name. E.g. |
event_time | string <date-time> The timestamp indicates when the event occurred. |
object (SubscriberRes) | |
webhook_id | string The webhook's identifier. |
{- "event_name": "string",
- "event_time": "2019-08-24T14:15:22Z",
- "subscriber": {
- "id": "string",
- "status": "active",
- "email": "string",
- "source": "manual",
- "first_name": "string",
- "last_name": "string",
- "segments": [
- {
- "id": "string",
- "name": "string"
}
], - "custom_fields": {
- "property1": "string",
- "property2": "string"
}, - "optin_ip": "string",
- "optin_timestamp": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z"
}, - "webhook_id": "string"
}
This event is triggered when a subscriber is unsubscribed from all mailings.
event_name | string The webhook notification's event name. E.g. |
event_time | string <date-time> The timestamp indicates when the event occurred. |
object (SubscriberRes) | |
webhook_id | string The webhook's identifier. |
{- "event_name": "string",
- "event_time": "2019-08-24T14:15:22Z",
- "subscriber": {
- "id": "string",
- "status": "active",
- "email": "string",
- "source": "manual",
- "first_name": "string",
- "last_name": "string",
- "segments": [
- {
- "id": "string",
- "name": "string"
}
], - "custom_fields": {
- "property1": "string",
- "property2": "string"
}, - "optin_ip": "string",
- "optin_timestamp": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z"
}, - "webhook_id": "string"
}