Skip to main content
API docs by Redocly

Leadfox API (1.0.0)

Download OpenAPI specification:Download

URL: https://leadfox.co License: Proprietary

API Basics (Concise Version)

⚠️⚠️⚠️ PLEASE REFER TO THE API BASIC SECTION FIRST ⚠️⚠️⚠️

Most collection endpoints support query parameters for filtering, sorting, field selection, and pagination:

  • filters: Filter resources using conditions (see Filter Syntax below)
  • sort: Sort results by field(s)
  • fields: Select specific fields to return
  • skip: Number of records to skip (pagination)
  • limit: Maximum number of records to return (default: 100)

Filter Syntax

  • Use comma , between conditions to AND
  • Use pipe | between values to OR
  • Use dot . to access nested attributes
  • Operators: =, !=, >, >=, <, <=, exists

Example: filters=name = Test List,deleted = false

Sort Syntax

  • Use comma , to sort by multiple fields
  • Use minus - prefix for descending order

Example: sort=-name

Fields Syntax

  • Use comma , to select multiple fields
  • _id and _owner are always included

Example: fields=name,description

Authentication

⚠️⚠️⚠️ PLEASE REFER TO THE AUTHENTICATION SECTION FIRST ⚠️⚠️⚠️

  1. Generate an API key and secret from the API page
  2. Exchange them for a JWT token via POST /v1/auth
  3. Include the JWT token in the Authorization header as JWT <token>

Authenticate and obtain JWT token

Exchange your API key and secret for a JWT token.

The JWT token is used to authenticate subsequent API requests.

Request Body schema: application/json
required
apikey
required
string
secret
required
string

Responses

Request samples

Content type
application/json
{
  • "apikey": "string",
  • "secret": "string"
}

Response samples

Content type
application/json
{
  • "jwt": "string",
  • "mode": "string",
  • "client": "string",
  • "clientid": "string"
}

Campaigns - Collection

Manage a Client's Campaigns.

Note: The Campaign entity supports multiple types, but only EmailCampaign (type = 2) is documented.
Refrain from using other campaign types.

List all Campaigns

query Parameters
filters
string
sort
string
fields
string
skip
integer >= 0
Default: 0
limit
integer >= 1
Default: 100

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new Campaign

⚠️⚠️⚠️ PLEASE REFER TO THE EMAILING GUIDE BEFORE USING THE CAMPAIGN API ⚠️⚠️⚠️**
Create a new Campaign (currently only EmailCampaign type is supported).

Required before creating:

  • At least one Folder to organize campaigns
  • At least one Email design to use in the campaign

Required before sending:

  • At least one List containing the Contacts to send to
Request Body schema: application/json
required
One of
_id
required
string
_owner
required
string
name
required
string
description
string
folder
required
string
type
required
integer
Value: 2
status
string (EmailCampaignStatus)
Enum: "d" "a" "i"

d = draft, a = active, i = inactive

start
string <date-time>
None (object) or Fixed Count (object) or Fixed Size (object) (BatchConfiguration)
Array of objects (EmailVariant)
Array of All Contacts (object) or Include List (object) or Exclude List (object) (CampaignList)
object (CampaignMailingList)

Responses

Request samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "name": "string",
  • "description": "string",
  • "folder": "string",
  • "type": 2,
  • "status": "d",
  • "start": "2019-08-24T14:15:22Z",
  • "batchConfiguration": {
    },
  • "emails": [
    ],
  • "lists": [
    ],
  • "mailinglist": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "name": "string",
  • "description": "string",
  • "folder": "string",
  • "type": 2,
  • "status": "d",
  • "start": "2019-08-24T14:15:22Z",
  • "batchConfiguration": {
    },
  • "emails": [
    ],
  • "lists": [
    ],
  • "mailinglist": {
    }
}

Campaigns - Resource

Operations on individual Campaign resources

Get a Campaign by ID

path Parameters
id
required
string
query Parameters
fields
string

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "name": "string",
  • "description": "string",
  • "folder": "string",
  • "type": 2,
  • "status": "d",
  • "start": "2019-08-24T14:15:22Z",
  • "batchConfiguration": {
    },
  • "emails": [
    ],
  • "lists": [
    ],
  • "mailinglist": {
    }
}

Update a Campaign by ID

Partial update of a Campaign.

To schedule an EmailCampaign, set the start date to a future datetime. To send an EmailCampaign, update the status to "a" (active).

path Parameters
id
required
string
Request Body schema: application/json
required
name
string
description
string
status
string (EmailCampaignStatus)
Enum: "d" "a" "i"

d = draft, a = active, i = inactive

start
string <date-time>
None (object) or Fixed Count (object) or Fixed Size (object) (BatchConfiguration)
Array of objects (EmailVariant)
Array of All Contacts (object) or Include List (object) or Exclude List (object) (CampaignList)
object (CampaignMailingList)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "status": "d",
  • "start": "2019-08-24T14:15:22Z",
  • "batchConfiguration": {
    },
  • "emails": [
    ],
  • "lists": [
    ],
  • "mailinglist": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "name": "string",
  • "description": "string",
  • "folder": "string",
  • "type": 2,
  • "status": "d",
  • "start": "2019-08-24T14:15:22Z",
  • "batchConfiguration": {
    },
  • "emails": [
    ],
  • "lists": [
    ],
  • "mailinglist": {
    }
}

Delete a Campaign by ID

path Parameters
id
required
string

Responses

Contacts - Collection

Manage contacts in your marketing database.

Contacts represent people in your marketing database, identified by a unique email address. Each Contact can have custom Properties, belong to Lists, and have subscription preferences for MailingLists if GDPR is enabled.

List all Contacts

query Parameters
filters
string
sort
string
fields
string
skip
integer >= 0
Default: 0
limit
integer >= 1
Default: 100

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new Contact

Request Body schema: application/json
required
email
required
string
properties
object

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "properties": { }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "email": "string",
  • "name": "string",
  • "properties": { },
  • "subscribed": true,
  • "created": "2019-08-24T14:15:22Z",
  • "lifecycle": "string",
  • "lists": [
    ],
  • "mailinglists": [
    ],
  • "sessionTrackingConsent": {
    },
  • "emailTrackingConsent": {
    }
}

Upsert a Contact

Insert a new Contact if it doesn't exist, or update it if it does (based on email)

Request Body schema: application/json
required
email
required
string
properties
object

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "properties": { }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "email": "string",
  • "name": "string",
  • "properties": { },
  • "subscribed": true,
  • "created": "2019-08-24T14:15:22Z",
  • "lifecycle": "string",
  • "lists": [
    ],
  • "mailinglists": [
    ],
  • "sessionTrackingConsent": {
    },
  • "emailTrackingConsent": {
    }
}

Contacts - Resource

Operations on individual Contact resources

Get a Contact by ID

path Parameters
id
required
string
query Parameters
fields
string

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "email": "string",
  • "name": "string",
  • "properties": { },
  • "subscribed": true,
  • "created": "2019-08-24T14:15:22Z",
  • "lifecycle": "string",
  • "lists": [
    ],
  • "mailinglists": [
    ],
  • "sessionTrackingConsent": {
    },
  • "emailTrackingConsent": {
    }
}

Update a Contact by ID

Partial update of a Contact. Only properties can be updated via this endpoint.

Special behavior for properties: The properties object is merged with existing properties, not replaced. To update a single property, send only that property.

Example updating properties:

{
  "properties": {
    "company": "New Company Inc."
  }
}

This will update only the "company" property while keeping other properties intact.

To manage list membership, use the dedicated endpoints documented in the Lists section.

path Parameters
id
required
string
Request Body schema: application/json
required
properties
object

Responses

Request samples

Content type
application/json
{
  • "properties": { }
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "email": "string",
  • "name": "string",
  • "properties": { },
  • "subscribed": true,
  • "created": "2019-08-24T14:15:22Z",
  • "lifecycle": "string",
  • "lists": [
    ],
  • "mailinglists": [
    ],
  • "sessionTrackingConsent": {
    },
  • "emailTrackingConsent": {
    }
}

Delete a Contact by ID

path Parameters
id
required
string

Responses

Emails - Collection

Manage email designs.

Emails represent email designs used in EmailCampaigns. Each Email contains HTML content, subject line, sender information, and other email-specific settings.

List all Emails

query Parameters
filters
string
sort
string
fields
string
skip
integer >= 0
Default: 0
limit
integer >= 1
Default: 100

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new Email

Request Body schema: application/json
required
name
required
string
description
string
subject
string
preheader
string
fromemail
string
fromname
string
unsubscribetext
string
editor
string
Default: "bee"
Value: "bee"
body
string
json
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "subject": "string",
  • "preheader": "string",
  • "fromemail": "string",
  • "fromname": "string",
  • "unsubscribetext": "string",
  • "editor": "bee",
  • "body": "string",
  • "json": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "name": "string",
  • "description": "string",
  • "subject": "string",
  • "preheader": "string",
  • "fromemail": "string",
  • "fromname": "string",
  • "unsubscribetext": "string",
  • "editor": "bee",
  • "body": "string",
  • "json": "string"
}

Emails - Resource

Operations on individual Email resources

Get an Email by ID

path Parameters
id
required
string
query Parameters
fields
string

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "name": "string",
  • "description": "string",
  • "subject": "string",
  • "preheader": "string",
  • "fromemail": "string",
  • "fromname": "string",
  • "unsubscribetext": "string",
  • "editor": "bee",
  • "body": "string",
  • "json": "string"
}

Update an Email by ID

path Parameters
id
required
string
Request Body schema: application/json
required
name
string
description
string
subject
string
preheader
string
fromemail
string
fromname
string
unsubscribetext
string
editor
string
Default: "bee"
Value: "bee"
body
string
json
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "subject": "string",
  • "preheader": "string",
  • "fromemail": "string",
  • "fromname": "string",
  • "unsubscribetext": "string",
  • "editor": "bee",
  • "body": "string",
  • "json": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "name": "string",
  • "description": "string",
  • "subject": "string",
  • "preheader": "string",
  • "fromemail": "string",
  • "fromname": "string",
  • "unsubscribetext": "string",
  • "editor": "bee",
  • "body": "string",
  • "json": "string"
}

Delete an Email by ID

path Parameters
id
required
string

Responses

Folders - Collection

Organize campaigns and email designs.

Folders are used to organize and group campaigns and emails for better management and organization.

List all Folders

query Parameters
filters
string
sort
string
fields
string
skip
integer >= 0
Default: 0
limit
integer >= 1
Default: 100

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new Folder

Request Body schema: application/json
required
name
required
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "name": "string",
  • "description": "string"
}

Folders - Resource

Operations on individual Folder resources

Get a Folder by ID

path Parameters
id
required
string
query Parameters
fields
string

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "name": "string",
  • "description": "string"
}

Update a Folder by ID

path Parameters
id
required
string
Request Body schema: application/json
required
name
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "name": "string",
  • "description": "string"
}

Delete a Folder by ID

path Parameters
id
required
string

Responses

Lists - Collection

Manage contact lists for segmentation and targeting.

Lists are used to group contacts for sending EmailCampaigns or organizing them. Use lists to create segments like "Webinar Attendees" or "Black Friday Leads".

List all Lists

query Parameters
filters
string
sort
string
fields
string
skip
integer >= 0
Default: 0
limit
integer >= 1
Default: 100

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new List

Request Body schema: application/json
required
name
required
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "name": "string",
  • "description": "string"
}

Lists - Resource

Operations on individual List resources

Get a List by ID

path Parameters
id
required
string
query Parameters
fields
string

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "name": "string",
  • "description": "string"
}

Update a List by ID

path Parameters
id
required
string
Request Body schema: application/json
required
name
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "name": "string",
  • "description": "string"
}

Delete a List by ID

path Parameters
id
required
string

Responses

Lists - Contacts

Manage contact membership in lists

List Contacts in a List

path Parameters
list_id
required
string
query Parameters
filters
string
sort
string
fields
string
skip
integer >= 0
Default: 0
limit
integer >= 1
Default: 100

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Count Contacts in a List

path Parameters
list_id
required
string
query Parameters
filters
string

Responses

Response samples

Content type
application/json
{
  • "count": 0
}

Add a Contact to a List

path Parameters
list_id
required
string
contact_id
required
string

Responses

Remove a Contact from a List

path Parameters
list_id
required
string
contact_id
required
string

Responses

MailingLists - Collection

Manage GDPR-compliant email subscription categories.

MailingLists represent email categories that Contacts can opt-in or opt-out of, such as "General communication", "Newsletter", or "Promotions". They are used to ensure GDPR compliance by respecting Contact subscription preferences.

MailingLists work in combination with Lists: use Lists to target specific Contacts, while MailingLists ensure you only send to those who opted-in to that category.

List all MailingLists

query Parameters
filters
string
sort
string
fields
string
skip
integer >= 0
Default: 0
limit
integer >= 1
Default: 100

Responses

Response samples

Content type
application/json
[
  • {
    }
]

MailingLists - Resource

Operations on individual MailingList resources

Get a MailingList by ID

path Parameters
id
required
string
query Parameters
fields
string

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "name": "string",
  • "description": "string",
  • "default": true
}

Get email metrics

path Parameters
element_type
required
string
Enum: "campaign" "target"

campaign = metrics for an EmailCampaign (all variants) target = metrics for a specific Email variant

element_id
required
string
query Parameters
compile
boolean

Get aggregated totals

startdate
string <date-time>
enddate
string <date-time>

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Properties - Collection

Manage Contact custom Properties.

You can define custom Properties that store additional information in a Contact. Built-in system Properties like "email", "firstname", "lastname", "phone", and "gender" already exist, but you can create your own custom Properties for your specific needs like "company", "industry", or "jobtitle".

Each Property has a shortcode that serves as the key in a Contact's properties object. All property values are stored as strings.

Example Contact with properties:

{
  "_id": "000000000000000000000001",
  "properties": {
    "firstname": "John",
    "lastname": "Doe",
    "email": "[email protected]",
    "company": "Doe's Inc.",
    "jobtitle": "CEO"
  }
}

List all Properties

query Parameters
filters
string
sort
string
fields
string
skip
integer >= 0
Default: 0
limit
integer >= 1
Default: 100

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a new Property

Request Body schema: application/json
required
name
required
string
shortcode
required
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "shortcode": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "name": "string",
  • "description": "string",
  • "shortcode": "string"
}

Properties - Resource

Operations on individual Property resources

Get a Property by ID

path Parameters
id
required
string
query Parameters
fields
string

Responses

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "name": "string",
  • "description": "string",
  • "shortcode": "string"
}

Update a Property by ID

path Parameters
id
required
string
Request Body schema: application/json
required
name
string
shortcode
string
description
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "shortcode": "string",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_owner": "string",
  • "name": "string",
  • "description": "string",
  • "shortcode": "string"
}

Delete a Property by ID

path Parameters
id
required
string

Responses