Bento

Subscribers

Manage your subscribers. When you are a new customer with an existing list you might use the import subscribers endpoint. Find and Search subscribers with convenient look up methods.

Available Endpoints

MethodEndpointName
POST/batch/subscribersImport Subscribers
GET/fetch/searchSearch Subscribers
GET/fetch/subscribersFind Subscriber
POST/fetch/subscribersCreate Subscriber
POST/fetch/commandsRun Command

The Subscriber Model

The Subscriber model contains all the identify information about your subscribers, such as their email address, first name, last name, and tags. You can add other key / value fields to hold other information about the subscriber, such as notes or other important details.

Properties

  • Name
    email
    Type
    string
    Description

    The Email Address for the subscriber.

POST/v1/batch/subscribers

Import Subscribers

This endpoint emulates our background processes for imports, serving as the go-to method for subscriber additions and updates. When you send your data to Bento, it's processed through our import queues. Although updates are typically swift, they can take up to 5 minutes to reflect. This endpoint is ideal for both bulk and single subscriber updates.

Request supports 1 to 1000 subscribers per post.
Does not trigger Flows or Automations.

Required Attributes

  • Name
    email
    Type
    string
    Description

    The Email Address for the subscriber.

Optional Attributes

  • Name
    first_name
    Type
    string
    Description

    The first name for the subscriber

  • Name
    last_name
    Type
    string
    Description

    The last name for the subscriber

  • Name
    tags
    Type
    string
    Description

    Comma seperated list of tags, if a tag doesn't exist it is created.

  • Name
    remove_tags
    Type
    string
    Description

    Comma seperated list of tags to remove from the subscriber.

  • Name
    some_other_field
    Type
    string
    Description

    key / value pair for storing other fields for the subscriber.

Request

Post
/v1/batch/subscribers
  curl -u publishableKey:secretKey -X POST "https://app.bentonow.com/api/v1/batch/subscribers?site_uuid=ExampleID1234" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d '{
      "subscribers": [
        {
          "email": "[email protected]",
          "first_name": "John",
          "last_name": "Doe",
          "tags": "lead,mql",
          "remove_tags": "customers",
          "some_other_field": "some value"
        }
      ]
    }'


Response

The response will contain the result count of subscribers.

JSON Response

      {
        "result": 1
      },
GET/v1/fetch/search

Search Subscribers

This endpoint delivers a report of the most recent 100 subscribers who accessed a page resource, complete with options for date-based searching and filtering.

This endpoint is limited to Bento Enterprise customers only. Please contact us for early access.

Required Attributes

  • Name
    page
    Type
    integer
    Description

    Page number for the search

Optional Attributes

  • Name
    created_at
    Type
    object
    Description

    The Creation date of the subscriber.
    gt date string - greater than date
    lt date string - less than date

  • Name
    updated_at
    Type
    object
    Description

    The update date of the subscriber
    gt date string - greater than date
    lt date string - less than date

  • Name
    last_event_at
    Type
    object
    Description

    The last event date of the subscriber.
    gt date string - greater than date
    lt date string - less than date

  • Name
    unsubscribed_at
    Type
    object
    Description

    The unsubscription date of the subscriber.
    gt date string - greater than date
    lt date string - less than date

Request

GET
/v1/fetch/search
  curl -L -u publishableKey:secretKey -X GET "https://app.bentonow.com/api/v1/fetch/search?site_uuid=ExampleID1234" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    --data-raw '{
        "page": 1,
        "created_at": {
          "gt": "string",
          "lt": "string"
        },
        "updated_at": {
          "gt": "string",
          "lt": "string"
        },
        "last_event_at": {
          "gt": "string",
          "lt": "string"
        },
        "unsubscribed_at": {
          "gt": "string",
          "lt": "string"
        }
    }'


Response

Returns a report of users that match the request.

JSON Response

"data": [
    {
      "id": "string",
      "type": "string",
      "attributes": {
        "uuid": "string",
        "email": "string",
        "fields": {},
        "cached_tag_ids": [
          "string"
        ],
        "unsubscribed_at": "string",
        "navigation_url": "string"
      }
    }
    ],
    "meta": {
      "page": 0,
      "query": {
        "email": {
          "not": "string"
        }
      }
    }
GET/v1/fetch/subscribers

Find Subscriber

Fetch a matched subscriber in your account.

Required Attributes

  • Name
    email
    Type
    string
    Description

    Email address to search for a match in your account

Optional Attributes

  • Name
    uuid
    Type
    string
    Description

    This returns the subscriber with the given identifier, though it is rarely needed. Can be used in place of email address.

Request

GET
/v1/fetch/subscribers
curl -L -u publishableKey:secretKey -X GET "https://app.bentonow.com/api/v1/fetch/subscribers?site_uuid=ExampleID1234&[email protected]" \
  -H "Accept: application/json"


Response

Returns the subscriber details.

JSON Response

"data": {
    "id": "string",
    "type": "string",
    "attributes": {
      "uuid": "string",
      "email": "string",
      "fields": {},
      "cached_tag_ids": [
        "string"
      ]
    }
}
POST/v1/fetch/subscribers

Create Subscriber

Creates a subscriber in your account and queues them for indexing.

Required Attributes

  • Name
    subscriber
    Type
    object
    Description

    An Array of subscriber emails to create.
    email string - subscriber email address

Request

POST
/v1/fetch/subscribers
      curl -L -u publishableKey:secretKey -X POST "https://app.bentonow.com/api/v1/fetch/subscribers?site_uuid=ExampleID1234" \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        --data-raw '{
          "subscriber": {
          "email": "[email protected]"
          }
        }'


Response

Returns the created subscribers details.

JSON Response

"data": {
  "id": "12345",
  "type": "visitors",
  "attributes": {
    "uuid": "123-123-123-123-123",
    "email": "[email protected]",
    "fields": {},
    "cached_tag_ids": [
      "123"
    ]
  }
}
POST/v1/fetch/commands

Run Command

Endpoint to execute a command and change a subscriber's data.

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

  • Name
    command
    Type
    object
    Description

    An Array of subscriber and details to change.
    command string - add_tag, add_tag_via_event, remove_tag, add_field, remove_field, subscribe, unsubscribe, change_email

    email string - subscriber email address

    query string/object - data for the requested change

Request

POST
/v1/fetch/commands
  curl -L -u publishableKey:secretKey -X POST "https://app.bentonow.com/api/v1/fetch/commands?site_uuid=ExampleID1234" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    --data-raw '{
        "command": [
          {
            "command": "add_tag",
            "email": "[email protected]",
            "query": "test"
          },
          {
            "command": "add_tag_via_event",
            "email": "[email protected]",
            "query": "test"
          },
          {
            "command": "remove_tag",
            "email": "[email protected]",
            "query": "test"
          },
          {
            "command": "add_field",
            "email": "[email protected]",
            "query": {
              "key": "test",
              "value": "test"
            }
          },
          {
            "command": "remove_field",
            "email": "[email protected]",
            "query": "test"
          },
          {
            "command": "subscribe",
            "email": "[email protected]"
          },
          {
            "command": "unsubscribe",
            "email": "[email protected]"
          },
          {
            "command": "change_email",
            "email": "[email protected]",
            "query": "[email protected]"
          }
        ]
    }'


Response

Returns the updated subscriber details.

JSON Response

"data": {
  "id": "12345",
  "type": "visitors",
  "attributes": {
    "uuid": "123-123-123-123-123",
    "email": "[email protected]",
    "fields": {},
    "cached_tag_ids": [
      "123"
    ]
  }
}

Was this page helpful?