Skip to main content
API docs by Redocly

Feathr API (0.0.0)

Download OpenAPI specification:Download

Standalone FastAPI public API on crane.

breadcrumbs

List Breadcrumbs

List breadcrumbs for the caller's account. Requires breadcrumbs:read.

Optional filters combine with AND: flavor, person_id, campaign_id, and a since/until activity-time range. Public filter names map to the internal Elasticsearch fields (flvr/per_id/cpn_id/d_c). Results are ordered newest activity first.

Authorizations:
HTTPBearer
query Parameters
BreadcrumbFlavors (string) or Flavor (null) (Flavor)

Filter by activity flavor.

Person Id (string) or Person Id (null) (Person Id)

Filter by person id.

Campaign Id (string) or Campaign Id (null) (Campaign Id)

Filter by campaign id.

Project Id (string) or Project Id (null) (Project Id)

Filter by project id.

Since (string) or Since (null) (Since)

Min activity time.

Until (string) or Until (null) (Until)

Max activity time.

page
integer (Page) >= 1
Default: 1

1-based page number.

size
integer (Size) [ 1 .. 100 ]
Default: 25

Items per page (max 100).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "size": 0,
  • "total": 0
}

Append Breadcrumb

Append a breadcrumb (activity record). Requires breadcrumbs:write.

The crumb's person is resolved-or-created inline from its identifiers, so no separate person-first step is needed. Breadcrumbs are append-only; supplying an Idempotency-Key makes the write deterministic (the key is hashed into the document's id), so re-delivery overwrites the same record rather than duplicating it.

Authorizations:
HTTPBearer
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
Request Body schema: application/json
required
Campaign Id (string) or Campaign Id (null) (Campaign Id)
Email (string) or Email (null) (Email)
External Id (string) or External Id (null) (External Id)
F Id (string) or F Id (null) (F Id)
flavor
required
string (BreadcrumbFlavors)
Enum: "ad_click" "ad_view" "blocked" "bot_partner_message_link_click" "bot_partner_message_unsubscribe" "bot_partner_message_view" "bot_pinpoint_tracked_email_click" "bot_pinpoint_tracked_email_open" "bot_pinpoint_tracked_email_unsubscribe" "contact_list_import" "conversation_response" "convert" "created_by_import" "custom" "dashboard_create" "dashboard_import" "dashboard_link_click" "dashboard_send_complete" "dashboard_send_request" "dashboard_submit" "dashboard_view" "deduplicated" "donation" "email_bot_detection_click" "email_link_click" "email_preferences_resubscribe" "email_preferences_update" "email_not_sent_via_opt_out" "email_send" "email_view" "form_submission" "form_view" "imis_create" "imis_update" "page_link_click" "page_view" "partner_message_complaint" "partner_message_delivered" "partner_message_hardbounce" "partner_message_link_click" "partner_message_rendering_failure" "partner_message_send" "partner_message_softbounce" "partner_message_suppression" "partner_message_unsubscribe" "partner_message_view" "pinpoint_tracked_email_click" "pinpoint_tracked_email_complaint" "pinpoint_tracked_email_delivered" "pinpoint_tracked_email_hardbounce" "pinpoint_tracked_email_open" "pinpoint_tracked_email_rendering_failure" "pinpoint_tracked_email_send" "pinpoint_tracked_email_softbounce" "pinpoint_tracked_email_suppression" "pinpoint_tracked_email_unsubscribe" "raisers_edge_constituent_created" "raisers_edge_constituent_updated" "raisers_edge_constituent_summary" "raisers_edge_gift_added" "report_link_click" "report_view" "shared_email_preferences_update" "update" "user_create" "user_update" "updated_by_import" "zapier_import" "zapier_update"
Occurred At (string) or Occurred At (null) (Occurred At)
Person Id (string) or Person Id (null) (Person Id)
Project Id (string) or Project Id (null) (Project Id)

Responses

Request samples

Content type
application/json
{
  • "campaign_id": "string",
  • "email": "string",
  • "external_id": "string",
  • "f_id": "string",
  • "flavor": "ad_click",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "person_id": "string",
  • "project_id": "string"
}

Response samples

Content type
application/json
{
  • "campaign_id": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "email": "string",
  • "flavor": "string",
  • "id": "string",
  • "person_id": "string",
  • "project_id": "string"
}

campaigns

List Campaigns

List the account's campaigns. Requires campaigns:read.

Authorizations:
HTTPBearer
query Parameters
page
integer (Page) >= 1
Default: 1

1-based page number.

size
integer (Size) [ 1 .. 100 ]
Default: 25

Items per page (max 100).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "size": 0,
  • "total": 0
}

Get Campaign

Fetch one campaign by id, own account only. Requires campaigns:read.

Authorizations:
HTTPBearer
path Parameters
campaign_id
required
string (Campaign Id)

Responses

Response samples

Content type
application/json
{
  • "date_created": "2019-08-24T14:15:22Z",
  • "date_end": "2019-08-24T14:15:22Z",
  • "date_start": "2019-08-24T14:15:22Z",
  • "description": "string",
  • "id": "string",
  • "is_enabled": true,
  • "kind": "string",
  • "name": "string",
  • "project_id": "string",
  • "state": "string"
}

custom-fields

List Custom Fields

List the account's custom fields. Requires custom_fields:read.

Authorizations:
HTTPBearer
query Parameters
Collection (string) or Collection (null) (Collection)

Filter to fields for one entity type.

page
integer (Page) >= 1
Default: 1

1-based page number.

size
integer (Size) [ 1 .. 100 ]
Default: 25

Items per page (max 100).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "size": 0,
  • "total": 0
}

Create Custom Field

Create a custom field for the caller's account. Requires custom_fields:write.

Allocates the storage key, creates the Elasticsearch mapping so values can be indexed, then persists the definition. The owning account comes from the API key; key+collection must be unique (409) and the account-wide field limit is enforced (422).

Authorizations:
HTTPBearer
Request Body schema: application/json
required
collection
required
string (Collection)
Enum: "Person" "Breadcrumb" "Partner"
data_type
required
string (Data Type)
Enum: "str" "int" "float" "bool" "list" "date" "money" "unicode"
Description (string) or Description (null) (Description)
form_type
string (Form Type)
Default: "text"
Enum: "text" "number" "textarea" "email" "url" "image"
key
required
string (Key) [ 1 .. 255 ] characters
Label (string) or Label (null) (Label)

Responses

Request samples

Content type
application/json
{
  • "collection": "Person",
  • "data_type": "str",
  • "description": "string",
  • "form_type": "text",
  • "key": "string",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "collection": "Person",
  • "data_type": "str",
  • "description": "string",
  • "form_type": "text",
  • "id": "string",
  • "is_default": true,
  • "is_read_only": true,
  • "key": "string",
  • "label": "string"
}

Delete Custom Field

Archive a custom field (soft delete). Requires custom_fields:write.

Soft delete preserves already-stored values and the Elasticsearch mapping (mappings are only reclaimed on reindex). Integration-managed (read-only) fields cannot be deleted via the API (403).

Authorizations:
HTTPBearer
path Parameters
field_id
required
string (Field Id)

Responses

Response samples

Content type
{
  • "detail": "string",
  • "status": 0,
  • "title": "string",
  • "type": "about:blank"
}

Get Custom Field

Fetch one custom field by id, own account only. Requires custom_fields:read.

Authorizations:
HTTPBearer
path Parameters
field_id
required
string (Field Id)

Responses

Response samples

Content type
application/json
{
  • "collection": "Person",
  • "data_type": "str",
  • "description": "string",
  • "form_type": "text",
  • "id": "string",
  • "is_default": true,
  • "is_read_only": true,
  • "key": "string",
  • "label": "string"
}

Update Custom Field

Update a custom field's display attributes. Requires custom_fields:write.

Integration-managed (read-only) fields cannot be edited via the API (403).

Authorizations:
HTTPBearer
path Parameters
field_id
required
string (Field Id)
Request Body schema: application/json
required
Description (string) or Description (null) (Description)
Form Type (string) or Form Type (null) (Form Type)
Label (string) or Label (null) (Label)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "form_type": "text",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "collection": "Person",
  • "data_type": "str",
  • "description": "string",
  • "form_type": "text",
  • "id": "string",
  • "is_default": true,
  • "is_read_only": true,
  • "key": "string",
  • "label": "string"
}

me

Whoami

Introspect the calling API key: its account, scopes, metadata, and limits.

Requires only a valid key (any scope) and does not count against the key's rate limit. Metadata is read fresh from storage by the key's id; rate-limit counters reflect the bucket as of this request.

Authorizations:
HTTPBearer

Responses

Response samples

Content type
application/json
{
  • "account_id": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "key_id": "string",
  • "last_four": "string",
  • "last_used_at": "2019-08-24T14:15:22Z",
  • "prefix": "string",
  • "rate_limit": {
    },
  • "revoked": false,
  • "scopes": [
    ],
  • "service_name": "string"
}

persons

List Persons

List persons last seen since updated_since, or look up a single person by email / external_id. Requires persons:read.

One of updated_since, email, or external_id is required, selecting one of two modes:

  • Window mode (updated_since given; capped at 30 days, last-seen ascending for stable paging): external_id and tag_ids filter the window; email is ignored.
  • Lookup mode (no updated_since): email or external_id resolves a single person by stable key (0- or 1-item page); tag_ids is ignored.

Inner breadcrumbs are excluded; custom-field values are translated to public keys. Set extended=true to include the full field set (see the extended param); it is omitted by default.

Authorizations:
HTTPBearer
query Parameters
Updated Since (string) or Updated Since (null) (Updated Since)

Return persons last seen at/after this time (max 30 days ago).

Email (string) or Email (null) (Email)

Look up the single person with this email (no time window). Ignored when updated_since is set.

External Id (string) or External Id (null) (External Id)

With updated_since, filter the window to this external id; without it, look up the single person with this external id.

Array of Tag Ids (strings) or Tag Ids (null) (Tag Ids)

Filter to persons holding ALL of these tag ids (AND). Requires updated_since; ignored without it.

extended
boolean (Extended)
Default: false

Include the full field set (name, language, pseudonym, occupation, companies, address, age, ethnicity, income, edu, tags, email_opt_out, is_archived, person_url). Off by default.

page
integer (Page) >= 1
Default: 1

1-based page number.

size
integer (Size) [ 1 .. 100 ]
Default: 25

Items per page (max 100).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "size": 0,
  • "total": 0
}

Upsert Person

Write a person from a flat attribute body, matched by stable key. Requires persons:write.

Matches an existing person by external_id to email to f_id, then applies the provided attributes: scalar fields, nested address_*, email_opt_out, custom_fields (by public key), and tags (by name — missing ones are created and added without removing existing tags). mode selects create-or-update behavior (see the param); the default upsert is idempotent given a stable external_id. The response is the full person with upsert_result set to created or updated.

Authorizations:
HTTPBearer
query Parameters
mode
string (WriteMode)
Default: "upsert"
Enum: "upsert" "create" "update"

upsert (default) matches-or-creates; create returns 409 if the person already exists; update returns 404 if it does not.

Request Body schema: application/json
required
Address Administrative Area Name (string) or Address Administrative Area Name (null) (Address Administrative Area Name)
Address Country Name (string) or Address Country Name (null) (Address Country Name)
Address Locality (string) or Address Locality (null) (Address Locality)
Address Postal Code (string) or Address Postal Code (null) (Address Postal Code)
Address Premise1 (string) or Address Premise1 (null) (Address Premise1)
Address Premise2 (string) or Address Premise2 (null) (Address Premise2)
Age (integer) or Age (null) (Age)
Array of Companies (strings) or Companies (null) (Companies)
Custom Fields (object) or Custom Fields (null) (Custom Fields)
Edu (string) or Edu (null) (Edu)
Email (string) or Email (null) (Email)
Email Opt Out (boolean) or Email Opt Out (null) (Email Opt Out)
Ethnicity (string) or Ethnicity (null) (Ethnicity)
External Id (string) or External Id (null) (External Id)
F Id (string) or F Id (null) (F Id)
First Name (string) or First Name (null) (First Name)
Income (integer) or Income (null) (Income)
Language (string) or Language (null) (Language)
Last Name (string) or Last Name (null) (Last Name)
Name (string) or Name (null) (Name)
Occupation (string) or Occupation (null) (Occupation)
Phone (string) or Phone (null) (Phone)
Pseudonym (string) or Pseudonym (null) (Pseudonym)
Array of Tags (strings) or Tags (null) (Tags)

Responses

Request samples

Content type
application/json
{
  • "address_administrative_area_name": "string",
  • "address_country_name": "string",
  • "address_locality": "string",
  • "address_postal_code": "string",
  • "address_premise1": "string",
  • "address_premise2": "string",
  • "age": 0,
  • "companies": [
    ],
  • "custom_fields": { },
  • "edu": "string",
  • "email": "string",
  • "email_opt_out": true,
  • "ethnicity": "string",
  • "external_id": "string",
  • "f_id": "string",
  • "first_name": "string",
  • "income": 0,
  • "language": "string",
  • "last_name": "string",
  • "name": "string",
  • "occupation": "string",
  • "phone": "string",
  • "pseudonym": "string",
  • "tags": [
    ]
}

Response samples

Content type
application/json
{
  • "0_person_url": "string",
  • "address": {
    },
  • "age": 0,
  • "companies": [
    ],
  • "custom_fields": { },
  • "date_created": "2019-08-24T14:15:22Z",
  • "date_last_seen": "2019-08-24T14:15:22Z",
  • "edu": "string",
  • "email": "string",
  • "email_opt_out": true,
  • "ethnicity": "string",
  • "external_id": "string",
  • "first_name": "string",
  • "id": "string",
  • "income": 0,
  • "is_archived": true,
  • "language": "string",
  • "last_name": "string",
  • "name": "string",
  • "occupation": "string",
  • "phone": "string",
  • "pseudonym": "string",
  • "tag_ids": [
    ],
  • "tags": [
    ],
  • "upsert_result": "created"
}

Get Person

Fetch a person by id, scoped to the caller's account. Requires persons:read.

Inner breadcrumbs are always excluded from the fetch (they are large and served by the breadcrumbs endpoint). Custom-field values are translated to public keys. Set extended=true to include the full field set.

Authorizations:
HTTPBearer
path Parameters
person_id
required
string (Person Id)
query Parameters
extended
boolean (Extended)
Default: false

Include the full field set (name, language, pseudonym, occupation, companies, address, age, ethnicity, income, edu, tags, email_opt_out, is_archived, person_url). Off by default.

Responses

Response samples

Content type
application/json
{
  • "0_person_url": "string",
  • "address": {
    },
  • "age": 0,
  • "companies": [
    ],
  • "custom_fields": { },
  • "date_created": "2019-08-24T14:15:22Z",
  • "date_last_seen": "2019-08-24T14:15:22Z",
  • "edu": "string",
  • "email": "string",
  • "email_opt_out": true,
  • "ethnicity": "string",
  • "external_id": "string",
  • "first_name": "string",
  • "id": "string",
  • "income": 0,
  • "is_archived": true,
  • "language": "string",
  • "last_name": "string",
  • "name": "string",
  • "occupation": "string",
  • "phone": "string",
  • "pseudonym": "string",
  • "tag_ids": [
    ],
  • "tags": [
    ],
  • "upsert_result": "created"
}

Update Person

Update a person's attributes (incl. custom_fields) by id, own account only. Requires persons:write.

Authorizations:
HTTPBearer
path Parameters
person_id
required
string (Person Id)
Request Body schema: application/json
required
Custom Fields (object) or Custom Fields (null) (Custom Fields)
Email (string) or Email (null) (Email)
First Name (string) or First Name (null) (First Name)
Last Name (string) or Last Name (null) (Last Name)
Phone (string) or Phone (null) (Phone)

Responses

Request samples

Content type
application/json
{
  • "custom_fields": { },
  • "email": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "phone": "string"
}

Response samples

Content type
application/json
{
  • "0_person_url": "string",
  • "address": {
    },
  • "age": 0,
  • "companies": [
    ],
  • "custom_fields": { },
  • "date_created": "2019-08-24T14:15:22Z",
  • "date_last_seen": "2019-08-24T14:15:22Z",
  • "edu": "string",
  • "email": "string",
  • "email_opt_out": true,
  • "ethnicity": "string",
  • "external_id": "string",
  • "first_name": "string",
  • "id": "string",
  • "income": 0,
  • "is_archived": true,
  • "language": "string",
  • "last_name": "string",
  • "name": "string",
  • "occupation": "string",
  • "phone": "string",
  • "pseudonym": "string",
  • "tag_ids": [
    ],
  • "tags": [
    ],
  • "upsert_result": "created"
}

Add Person Tags

Add tags to a person. Requires persons:write.

Every id must be a live tag owned by the caller's account; unknown, archived, or foreign-account ids are a 404. Idempotent — tags already on the person are left unchanged, no duplicates are created. View a person's tags via GET /persons/{id} (tag_ids) and filter by them on GET /persons.

Authorizations:
HTTPBearer
path Parameters
person_id
required
string (Person Id)
Request Body schema: application/json
required
tag_ids
required
Array of strings (Tag Ids) non-empty

Responses

Request samples

Content type
application/json
{
  • "tag_ids": [
    ]
}

Response samples

Content type
{
  • "detail": "string",
  • "status": 0,
  • "title": "string",
  • "type": "about:blank"
}

Remove Person Tag

Remove a tag from a person. Requires persons:write. A no-op if the person doesn't hold the tag.

Authorizations:
HTTPBearer
path Parameters
person_id
required
string (Person Id)
tag_id
required
string (Tag Id)

Responses

Response samples

Content type
{
  • "detail": "string",
  • "status": 0,
  • "title": "string",
  • "type": "about:blank"
}

projects

List Projects

List the account's projects. Requires projects:read.

Authorizations:
HTTPBearer
query Parameters
page
integer (Page) >= 1
Default: 1

1-based page number.

size
integer (Size) [ 1 .. 100 ]
Default: 25

Items per page (max 100).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "size": 0,
  • "total": 0
}

Get Project

Fetch one project by id, own account only. Requires projects:read.

Authorizations:
HTTPBearer
path Parameters
project_id
required
string (Project Id)

Responses

Response samples

Content type
application/json
{
  • "date_created": "2019-08-24T14:15:22Z",
  • "date_end": "2019-08-24T14:15:22Z",
  • "date_start": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "location": "string",
  • "name": "string",
  • "registration_url": "string",
  • "site_url": "string"
}

tags

List Tags

List the account's tags, optionally filtered by context. Requires tags:read.

Authorizations:
HTTPBearer
query Parameters
Context (string) or Context (null) (Context)
page
integer (Page) >= 1
Default: 1

1-based page number.

size
integer (Size) [ 1 .. 100 ]
Default: 25

Items per page (max 100).

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "page": 0,
  • "size": 0,
  • "total": 0
}

Create Tag

Create a tag for the caller's account. Requires tags:write.

The account (parent) is taken from the API key, never the request body. A duplicate (name, context) against a live tag is a 409; if it collides with a soft-deleted (archived) tag, that tag is revived and returned — matching the in-app get-or-create so a deleted name isn't locked out forever.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
context
required
string (Context)
Enum: "event" "account" "person_segment" "partner" "breadcrumb" "person"
name
required
string (Name) [ 1 .. 64 ] characters

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "context": "string",
  • "date_created": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "name": "string"
}

Delete Tag

Archive a tag (soft delete; preserves references). Requires tags:write.

Authorizations:
HTTPBearer
path Parameters
tag_id
required
string (Tag Id)

Responses

Response samples

Content type
{
  • "detail": "string",
  • "status": 0,
  • "title": "string",
  • "type": "about:blank"
}

Get Tag

Fetch one tag by id, own account only. Requires tags:read.

Authorizations:
HTTPBearer
path Parameters
tag_id
required
string (Tag Id)

Responses

Response samples

Content type
application/json
{
  • "context": "string",
  • "date_created": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "name": "string"
}

Update Tag

Update a tag's name and/or context, own account only. Requires tags:write.

Authorizations:
HTTPBearer
path Parameters
tag_id
required
string (Tag Id)
Request Body schema: application/json
required
Context (string) or Context (null) (Context)
Name (string) or Name (null) (Name)

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "context": "string",
  • "date_created": "2019-08-24T14:15:22Z",
  • "id": "string",
  • "name": "string"
}