> For the complete documentation index, see [llms.txt](https://docs.onum.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onum.com/listeners/listener-integrations/pull-data-from-http-endpoints/pull-data-from-the-box-api.md).

# Pull data from the Box API

## Overview

Use the **HTTP Pull** Listener to collect data from the [Box API](https://developer.box.com/reference/get-events). Currently, we support the events endpoint.

## HTTP Pull Listener configuration

In Falcon Onum, go to the **Listeners** area and click **New Listener > HTTP Pull**. Give a name to your new Listener and enter the following data:

### Parameters

N/A

### Secrets

You must define these credentials in Onum:

* `client_id` will reference your Box Client ID.
* `client_secret` will reference your Box Client Secret.

To do it, click **Add element** and enter a **Name** for the secret (in this case, `client_id`). Then, click the **Value** field and select **New secret** to create a new one:

* Give the secret a **Name**.
* Turn off the **Expiration date** option.
* Click **Add new value** and paste the secret corresponding to the value.
* Click **Save**.

You can now select the secret you just created in the **Value** field list. Repeat the process for the `client_secret`.

{% hint style="info" %}
Learn more about secrets in Onum in [this article](/settings/organization-settings/secrets-management.md).
{% endhint %}

### Setup

After entering the required parameters and secrets, you can choose to manually enter the rest of configuration fields, or simply paste the given YAML:

{% tabs %}
{% tab title="Config as YAML" %}
Toggle **ON** the **Config as YAML** option to enable a free text field where you can paste the following YAML:

```yaml
withTemporalWindow: true
temporalWindow:
  duration: 30s
  offset: 30s
  tz: UTC
  format: RFC3339
withAuthentication: true
authentication:
  type: token
  token:
    request:
      method: POST
      url: https://api.box.com/oauth2/token 
      headers:
        - name: Content-Type
          value: application/x-www-form-urlencoded
      bodyType: urlEncoded
      bodyParams:
        - name: grant_type
          value: client_credentials
        - name: client_id
          value: '${secrets.client_id}'
        - name: client_secret
          value: '${secrets.client_secret}'
        - name: box_subject_id
          value: 62685208
        - name: box_subject_type
          value: enterprise
    tokenPath: ".access_token"
    authInjection:
      in: header
      name: Authorization
      prefix: 'Bearer '
      suffix: ''
withEnumerationPhase: false
collectionPhase:
  paginationType: "cursor"
  cursorSelector: ".next_stream_position"
  initialRequest:
    responseType: json
    method: GET
    url: "https://api.box.com/2.0/events"
    headers:
      - name: Accept
        value: application/json
    queryParams:
      - name: stream_type
        value: admin_logs
      - name: created_after
        value: ${temporalWindow.from}
      - name: created_before
        value: ${temporalWindow.to}
      - name: limit
        value: '100'
      # REMOVED: event_type parameter - either remove entirely or use valid Box event types
      # Valid types: ACCESS_GRANTED, ADMIN_LOGIN, FILE_MARKED_MALICIOUS, etc.
  nextRequest:
    responseType: json
    method: GET
    url: "https://api.box.com/2.0/events"
    headers:
      - name: Accept
        value: application/json
    queryParams:
      - name: stream_type
        value: admin_logs
      - name: stream_position
        value: '${pagination.cursor}'
      - name: created_after
        value: ${temporalWindow.from}
      - name: created_before
        value: ${temporalWindow.to}
      - name: limit
        value: '100'
output:
    select: ".entries"
    map: "."
    outputMode: "element"
```

{% endtab %}

{% tab title="Manually configure" %}
**Temporal Window**

Toggle **ON** to add a temporal window for events. This repeatedly shifts the time window over which data is collected.

* **Duration**<mark style="color:$primary;">**\***</mark> - `30s`
* **Offset**<mark style="color:$primary;">**\***</mark> - `30s`
* **Format**<mark style="color:$primary;">**\***</mark> - `RFC3339`

**Authentication**

Toggle **ON** to configure the authentication phase.

* **Type**<mark style="color:red;">**\***</mark>**&#x20;-** `token`
* **Token Retrieve Baes Authentication**
  * **Request**&#x20;
    * **Method**<mark style="color:red;">**\***</mark> - `POST`
    * **URL**<mark style="color:red;">**\***</mark> - `https://api.box.com/oauth2/token`
  * **Headers**&#x20;
    * **Name** - `Content-Type`&#x20;
    * **Value** - `application/x-www-form-urlencodedapplication/x-www-form-urlencoded`
    * **Body Type**<mark style="color:$primary;">**\***</mark> - `urlEncoded`
    * **Body Params**
      * **Name** - `grant_type`
      * **Value** - `client_credentials`
      * **Name** - `Client ID`
      * **Value** - `${secrets.client_id}`
      * **Name** - `Client Secret`
      * **Value** - `${secrets.client_secret}`
      * **Name** - `box_subject_id`
      * **Value** - `62685208`
      * **Name** - `box_subject_type`
      * **Value** - `enterprise`
* **Token path** - `.access_token`
* **Auth injection**
  * **In**<mark style="color:$primary;">**\***</mark> - `header`
  * **Name**<mark style="color:$primary;">**\***</mark> - `Authorization`
  * **Prefix** - `'Bearer '`
  * **Suffix** - `''`

**Collection Phase**

Toggle **ON** to configure the collection phase. This API endpoint requires an initial request that will provide a list of alert ids. In order to get the details about that information, it will require an additional request for those details.

* **Pagination Type**<mark style="color:red;">**\***</mark> - `Cursor`
* **Cursor Selector**<mark style="color:red;">**\***</mark> - `.next_stream_position`
* **Initial request**&#x20;
  * **Response Type**<mark style="color:$primary;">\*</mark> - `JSON`
  * **Method**<mark style="color:red;">**\***</mark> - `GET`
  * **URL**<mark style="color:red;">**\***</mark> - `https://api.box.com/2.0/events`
  * **Headers**
    * **Name** - `Accept`
    * **Value** - `Application/JSON`
  * **Query Params**&#x20;
    * **Name** - `stream_type`&#x20;
    * **Value** - `admin_logs`
    * **Name** - `created_after`
    * **Value** - `${temporalWindow.from}`
    * **Name** - `created_before`
    * **Value** - `${temporalWindow.to}`
    * **Name** - `limit`
    * **Value** - `100`
* **Next request**&#x20;
  * **Response Type**<mark style="color:$primary;">**\***</mark> - `JSON`
  * **Method**<mark style="color:red;">**\***</mark> - `GET`
  * **URL**<mark style="color:red;">**\***</mark> - `https://api.box.com/2.0/events`
  * **Headers**
    * **Name** - `Accept`
    * **Value** - `Application/JSON`
  * **Query Params**&#x20;
    * **Name** - `stream_type`&#x20;
    * **Value** - `admin_logs`
    * **Name** - `stream_position`
    * **Value** - `${pagination.cursor}`
    * **Name** - `created_after`
    * **Value** - `${temporalWindow.from}`
    * **Name** - `created_before`
    * **Value** - `${temporalWindow.to}`
    * **Name** - `limit`
    * **Value** - `100`
* **Output**&#x20;
  * **Select**<mark style="color:$primary;">**\***</mark> - `.entries`
  * **Map** - `.`
  * **Output Mode**<mark style="color:$primary;">**\***</mark> - `element`
    {% endtab %}
    {% endtabs %}

When you're done, click **Create labels** to move on to the next step and define the required [Labels](/listeners/labels.md) if needed.