# Subscribers Use this API to create, import, find, and update subscribers. The batch import endpoint handles bulk additions and existing lists. The fetch endpoints look up or change individual subscribers. ## Available Endpoints --- ## The Subscriber Model The Subscriber model contains identity, profile fields, tag membership, and subscription state. Batch imports can create or update the same subscriber shape without triggering automations. ### Properties - **email** (`string`): The email address for the subscriber. Bento uses this as the primary lookup key for most subscriber operations. - **uuid** (`string`): Bento's stable identifier for the subscriber. - **first_name** (`string`): The subscriber's first name when supplied. - **last_name** (`string`): The subscriber's last name when supplied. - **fields** (`object`): Custom profile fields stored on the subscriber. Use flat keys for predictable segmentation and Liquid access. - **cached_tag_ids** (`array`): Internal tag ids currently associated with the subscriber. Use tag names when writing data unless an endpoint says otherwise. - **tags** (`array`): Human-readable tag names currently associated with the subscriber. - **unsubscribed_at** (`datetime|null`): Timestamp for the subscriber's unsubscribe status. `null` means the subscriber is currently subscribed. - **unsubscribed_reason** (`string|null`): Reason Bento recorded for the unsubscribe, when available. - **attribution** (`object`): First-touch attribution details for the subscriber. Contains `first_referral`, `first_page`, and `campaign_data`. `campaign_data` returns `{}` when no campaign data has been captured. - **navigation_url** (`string`): Dashboard URL for reviewing the subscriber in Bento when returned by search endpoints. --- ## Import Subscribers {{ tag: 'POST', label: '/v1/batch/subscribers' }} This is the recommended way to add or update subscribers. Data is processed through Bento's import queues, so updates are usually fast but can take up to 5 minutes to appear. It works for bulk imports and single subscriber updates. > Request supports 1 to 1000 subscribers per post. > ⚠️ **Warning** > Does not trigger Flows or Automations. ### Required Attributes - **email** (`string`): The Email Address for the subscriber. ### Optional Attributes - **first_name** (`string`): The first name for the subscriber - **last_name** (`string`): The last name for the subscriber - **tags** (`string`): Comma separated list of tags, if a tag doesn't exist it is created. - **remove_tags** (`string`): Comma separated list of tags to remove from the subscriber. - **utm_source** (`string`): Attribution source for imported subscribers, such as `newsletter` or `google`. - **utm_medium** (`string`): Attribution medium for imported subscribers, such as `email` or `cpc`. - **utm_campaign** (`string`): Attribution campaign name for imported subscribers. - **utm_content** (`string`): Optional attribution content value for imported subscribers. - **utm_term** (`string`): Optional attribution term value for imported subscribers. - **created_at** (`datetime`): ISO 8601 timestamp to backfill when the subscriber was originally created or joined. - **lifetime_value_currency** (`string`): Three-letter currency code for the subscriber's lifetime value, such as `USD`. - **lifetime_value_amount** (`integer`): Lifetime value amount in cents. For example, USD $10 should be `1000`. - **some_other_field** (`string`): `key` / `value` pair for storing other fields for the subscriber. CSV import example: ```csv email,lifetime_value_currency,lifetime_value_amount jane@example.com,USD,1000 ``` ### Response The response contains how many subscriber records were queued for import. - **results** (`integer`): Number of subscriber records accepted for import. - **failed** (`integer`): Number of subscriber records rejected from the request. --- ## Search Subscribers {{ tag: 'GET', label: '/v1/fetch/search' }} Searches subscribers in your account and returns up to 100 results per page. Filter by tags or by date ranges on creation, update, last event, and unsubscribe times. > This endpoint is limited to Bento Enterprise customers only. See [Plans and API access](/docs/api/access) or contact support for access. > Use tag names in `tags`, not internal tag IDs. You can send an array or a comma-separated string like `customer,lead,enterprise`. > **Recommended** > `tag_names` is also accepted as an alias. `tag_ids` still works for older integrations, but `tags` is the recommended param. ### Required Attributes - **page** (`integer`): Page number for the search ### Optional Attributes - **tags** (`array|string`): Preferred filter. Accepts an array of tag names or a comma separated string. - **tag_names** (`array|string`): Alias for `tags`. Accepts an array of tag names or a comma separated string. - **tag_ids** (`array|string`): Legacy compatibility filter. Accepts internal tag ids as an array or comma separated string. - **created_at** (`object`): The Creation date of the subscriber. `gt` `` - greater than date `lt` `` - less than date - **updated_at** (`object`): The update date of the subscriber `gt` `` - greater than date `lt` `` - less than date - **last_event_at** (`object`): The last event date of the subscriber. `gt` `` - greater than date `lt` `` - less than date - **unsubscribed_at** (`object`): The unsubscription date of the subscriber. `gt` `` - greater than date `lt` `` - less than date ### Response Returns a report of users that match the request. > When you search with `tags` or `tag_names`, the response metadata includes both the requested tag names and the resolved `cached_tag_ids` used internally for search. - **data** (`array`): JSON:API-style subscriber records. Each item contains `id`, `type`, and `attributes`. - **data[].attributes.uuid** (`string`): Bento UUID for the matched subscriber. - **data[].attributes.email** (`string`): Subscriber email address. - **data[].attributes.fields** (`object`): Custom subscriber fields. - **data[].attributes.cached_tag_ids** (`array`): Internal tag ids matched or attached to the subscriber. - **meta.page** (`integer`): Current result page. - **meta.query** (`object`): Search filters applied by Bento, including resolved tag names and ids when tag filters are used. --- ## Find Subscriber {{ tag: 'GET', label: '/v1/fetch/subscribers' }} Fetch a matched subscriber in your account. ### Required Attributes - **email** (`string`): Email address to search for a match in your account ### Optional Attributes - **uuid** (`string`): This returns the subscriber with the given identifier, though it is rarely needed. Can be used in place of email address. ### Response Returns the subscriber details. - **data.id** (`string`): Internal record id. - **data.type** (`string`): Resource type, typically `visitors`. - **data.attributes.uuid** (`string`): Bento UUID for the subscriber. - **data.attributes.email** (`string`): Subscriber email address. - **data.attributes.fields** (`object`): Custom fields stored on the subscriber. - **data.attributes.cached_tag_ids** (`array`): Internal tag ids attached to the subscriber. - **data.attributes.tags** (`array`): Human-readable tag names attached to the subscriber. - **data.attributes.unsubscribed_at** (`datetime|null`): Timestamp for the subscriber's unsubscribe status. `null` means the subscriber is currently subscribed. - **data.attributes.unsubscribed_reason** (`string|null`): Reason Bento recorded for the unsubscribe, when available. - **data.attributes.attribution.first_referral** (`string`): First referral source captured for the subscriber. Returns an empty string when unavailable. - **data.attributes.attribution.first_page** (`string`): First page captured for the subscriber. Returns an empty string when unavailable. - **data.attributes.attribution.campaign_data** (`object`): First-touch UTM campaign data. Returns `{}` when no campaign data has been captured. --- ## Create Subscriber {{ tag: 'POST', label: '/v1/fetch/subscribers' }} Creates a subscriber in your account and queues them for indexing. ### Required Attributes - **subscriber** (`object`): An object describing the subscriber to create. `email` `` - subscriber email address ### Response Returns the created subscriber's details. - **data.id** (`string`): Internal record id for the created subscriber. - **data.type** (`string`): Resource type, typically `visitors`. - **data.attributes.uuid** (`string`): Bento UUID for the subscriber. - **data.attributes.email** (`string`): Subscriber email address. - **data.attributes.fields** (`object`): Custom fields stored on the subscriber. - **data.attributes.cached_tag_ids** (`array`): Internal tag ids attached to the subscriber. - **data.attributes.tags** (`array`): Human-readable tag names attached to the subscriber. - **data.attributes.unsubscribed_at** (`datetime|null`): Timestamp for the subscriber's unsubscribe status. `null` means the subscriber is currently subscribed. - **data.attributes.unsubscribed_reason** (`string|null`): Reason Bento recorded for the unsubscribe, when available. - **data.attributes.attribution** (`object`): First-touch attribution details for the subscriber. Contains `first_referral`, `first_page`, and `campaign_data`. --- ## Run Command {{ tag: 'POST', label: '/v1/fetch/commands' }} Endpoint to execute a command and change a subscriber's data. > ⚠️ **Warning** > This endpoint is not recommended for most use cases as it has a delayed response. It is recommended to use if the batch endpoints are not working for your use case. ### Required Attributes - **command** (`object`): An array of command objects, each targeting one subscriber. `command` `` - `add_tag`, `add_tag_via_event`, `remove_tag`, `add_field`, `remove_field`, `subscribe`, `unsubscribe`, `change_email` `email` `` - subscriber email address `query` `` - data for the requested change ### Response Returns how many commands were queued. Commands run asynchronously in the background. - **results** (`integer`): Number of commands accepted for processing.