Skip to main content

API Basics

Querying a Resource Collection​

Most resource collection endpoints (GET /v1/<resource_type>) support the query parameters filters, sort, fields and paging via skip & limit. We always respond with JSON (Content-Type: application/json).

Examples (Contact)
https://rest.leadfox.co/v1/contact?filters=email = [email protected]
https://rest.leadfox.co/v1/contact?sort=email
https://rest.leadfox.co/v1/contact?fields=_id,email
https://rest.leadfox.co/v1/contact?skip=0&limit=10
warning

Make sure your URLs are always properly encoded, for simplicity and readability they aren't in the examples :

filters=properties.firstname = John|john,properties.lastname = Doe|doe
                            ^ ^                             ^ ^
filters=properties.firstname%20=%20John|john,properties.lastname%20=%20Doe|doe
                            ^^^ ^^^                             ^^^ ^^^

General Schema Rules​

  • IDs are hexadecimal strings like abcdef123456789000000000 (MongoDB ObjectIds).
  • Resources have an
    • _id attribute which is the unique identifier of the resource.
    • _owner attribute which is the unique identifier of the Client owning the resource.
  • Most dates (datetimes) are in ISO 8601 format like 2025-01-01T00:00:00.000Z.
    • Always converted and stored as UTC.
    • In some rare cases, we might use a timestamp in milliseconds.

Filter Syntax​

Use a comma , between conditions to AND.
Use a pipe | between values to OR.
Use a dot . to access a nested object's attributes like properties.firstname.
Use a dot . to access a nested object's attributes inside an array like lists.list.
Operators are case sensitive meaning a = John and a = john won't match the same resources.

Condition's operators
attribute = <value>
attribute != <value>
attribute > <value>
attribute >= <value>
attribute < <value>
attribute <= <value>
attribute exists <true|false>
Examples (Contact)
filters=properties.firstname = John|john,properties.lastname = Doe|doe
                  ^                                ^
[
    { "properties": { "firstname": "John", "lastname": "Doe" } },
    // ...
]

DOs & DON'Ts​

DODON'T
MUST use spaces on each side of the operatora = <value>a=<value>
Only use pipe | (OR) between valuesa = <value>|<value>a = <value>,<value>
Only use comma , (AND) between conditionsa = <value>,b = <value>a = <value>|b = <value>
MUST NOT use spaces on each side of a pipe | or a comma ,a = <value>|<value>
a = <value>,b = <value>		a = <value> | <value>
a = <value> , b = <value>
Referencing an attribute on the right-hand side won't work, only static values are allowedobj.a = <value>obj.a = obj.b
Referencing an attribute multiple times won't work, only one condition per attribute is allowed (last one wins)obj.a >= 0,obj.a < 100
Examples (Contact)
filters=properties.firstname = John|john,properties.lastname = Doe|doe
                  ^         ^^^    ^    ^
info

This syntax is fairly limited in the filtering you can do. For example, you can only AND the conditions together, you cannot OR them or do some advance conditions with parentheses (), they are not allowed. It's generally enough to cover the basic use cases like filtering your contacts by email address or your lists by name.

warning

Careful when filtering an array of nested objects, it may not work as you expect it to :

filters=lists.list = 67f427c5328bb26a393d64ca,lists.time >= 2025-01-01
             ^                                     ^

Will result in at least one item matching the first condition lists.list = 67f427c5328bb26a393d64ca AND at least one (potentially different) item matching the second condition lists.time >= 2025-01-01. Filtering items matching both conditions at the same time is currently not supported.

Sort Syntax​

Use commas , to sort multiple fields at the same time.
Use minus - in front of a field to sort in decreasing order.

Examples (Contact)
sort=email
sort=-email
sort=_id,email

Fields Syntax​

Since we are using JSON with arrays and nested objects, it can be useful to only take what you need to reduce the response size.

Use commas , to retrieve only specific fields that you want.
Use a dot . to retrieve a nested object's attributes like properties.firstname.
Use a dot . to retrieve a nested object's attributes inside an array like lists.list.

Examples (Contact)
fields=email,properties.firstname,properties.lastname

[
    {
        "_id": "000000000000000000000000",
        "_owner": "000000000000000000000000",
        "email": "...",
        "properties": {
            "firstname": "...",
            "lastname": "..."
        }
    },
    // ...
]
info

_id & _owner are always returned even when not requested.

There's currently no syntax to ask for the default and include or exclude a subset of fields, to achieve this you need to send the whole list down manually.

Paging Syntax​

Use skip & limit to page through large result sets.

Examples (Contact)
skip=0&limit=10
skip=10&limit=10
skip=20&limit=10
...
info

The current default limit is 100 but may change in the future.

PUT not PATCH​

We do not support the PATCH method, we've simply made our PUT behave like a PATCH request. Thus when updating an entity, you can send partial data and only the provided fields will be updated.

Be careful when updating a nested object in an entity. By default, the whole nested object will be replaced. If you want to update only a subset of the nested object's attributes, you need to use the dot . notation to specify the attribute you want to update.

PUT /v1/<entity_type>/<id> HTTP/1.1
Host: rest.leadfox.co
Authorization: JWT <jwt>
Content-Type: application/json

{ "foo": { "bar": "new value" } }
warning

Contact.properties nested object is a special case where the whole object is merged instead of replaced. The dot notation is currently not supported for this one.