Core objects
The Feathr API exposes a small set of resources that model your account. This page explains what each object represents and how they relate. The API Reference has the exact fields, endpoints, and request/response schemas.
How they relate
- Person is the central entity — an individual in your account.
- A Breadcrumb records an activity a person performed, optionally tied to a campaign or project.
- A Campaign belongs to a Project.
- Tags and Custom fields describe persons — labels and account-defined attributes.
Person
A person is an individual in your account (a contact). Persons accumulate activity (breadcrumbs), carry tags, and hold values for your account's custom fields.
Key fields: id, external_id, email, first_name, last_name, phone,
custom_fields (an object mapping your custom-field keys to values), tag_ids
(the tags applied to them), date_created, date_last_seen.
You create or update a person by upserting on an identifier you own —
external_id, email, or f_id (the Feathr tracking cookie id). Sending the same
identifier again updates the existing person instead of creating a duplicate.
See the API Reference for the person endpoints and schema.
Breadcrumb
A breadcrumb is an append-only record of something a person did — a page view, a form submission, or a custom activity you define. Breadcrumbs are how you report first-party activity into Feathr.
Key fields: id, flavor (the activity type — see below), person_id,
campaign_id, project_id, email, created_at.
When you create a breadcrumb, Feathr resolves or creates the person inline from
any one of person_id, external_id, email, or f_id (at least one is
required) — there is no separate person-creation step. Breadcrumbs are
append-only: send an Idempotency-Key header so a retried request overwrites
the same record instead of creating a duplicate. You may also set occurred_at
(when the activity happened) and associate the breadcrumb with a campaign_id
and/or project_id.
Flavor types
A breadcrumb's flavor is the kind of activity it records. When creating a
breadcrumb you may use these five flavors:
| Flavor | Meaning |
|---|---|
custom | A first-party activity you define yourself. |
page_view | A person viewed a page. |
page_link_click | A person clicked a link on a page. |
form_view | A person viewed a form. |
form_submission | A person submitted a form. |
Creating a breadcrumb is limited to these five on purpose. System- and Feathr-generated flavors — ad impressions and clicks, conversions, donations, email and partner-message delivery metrics, and importer or CRM-sync events — are billable or trust-sensitive, so they cannot be reported through the public API.
Reading is not restricted. When you list breadcrumbs you can filter by any
flavor (GET /breadcrumbs?flavor=...), including the system-generated ones, so
you can query all of a person's activity regardless of how it was recorded. The
API Reference lists every flavor, grouped by category, under
Breadcrumb flavors.
See the API Reference for the breadcrumb endpoints and schema.
Campaign
A campaign is a marketing effort in your account. Every campaign belongs to a project.
Key fields: id, name, project_id, state, kind, description,
date_created, date_start, date_end, is_enabled.
See the API Reference for the campaign endpoints and schema.
Project
A project is a container for campaigns and activity (internally a Feathr
"event"). Campaigns belong to a project, and breadcrumbs can reference one via
project_id.
Key fields: id, name, location, site_url, registration_url,
date_created, date_start, date_end.
See the API Reference for the project endpoints and schema.
Tag
A tag is a label you apply to persons to group or segment them. A tag's
context indicates what kind of tag it is.
Key fields: id, name, context, date_created.
See the API Reference for the tag endpoints and schema.
Custom field
A custom field is an attribute you define on your account and set per person. A
person's values for your custom fields appear in their custom_fields object.
Key fields: id, key (the stable identifier used in a person's
custom_fields), label, description, is_default, is_read_only.
See the API Reference for the custom-field endpoints and schema.