# Using database steps in Flow Builder

Database steps in [Flow Builder](https://dashboard.messagebird.com/en/flow-builder) allow you to store a piece of data in server-less [Databases](https://dashboard.messagebird.com/en/developers/databases) during one invocation and retrieve it during another, based on a shared key.  All stored values can be deleted, too.

### In this article: <a href="#id-01fy922v2q7ftms9cyd99a7byv" id="id-01fy922v2q7ftms9cyd99a7byv"></a>

* [Databases 101](#h_01FY91R1FXRQTH4N5DSPJZV0T5)
* [*Store value* step](#h_01FFM3VZZAPA1XWH52PD6KAMPN)
  * [A database](#01FYBNZWX2GD51MJ8478N9P30N)
  * [A key](#01FYBP00NNH3D55G4QNV8HW530)
  * [A value](#01FYBP04936WVZPVHM5VWR5AGG)
* [*Retrieve value from Database* step](#h_01FFM4PHAJ3R8V4HEGS1YMRQ5N)
  * [Read value as JSON](#01FYBM4SPKYRDNHX8ET202F6WK)
  * [Failure handling](#01FYBM4MT4E5QNC6WPZKDC06P7)
* [*Delete value from Database* step](#h_01FFM4DRKH28W19Y574CXC323P)
* [Public API ](#h_01FFM4PXJGSS1FV6CV4D7X6KE5)
  * [List all key/value pairs](#01FY922V2QFPKV3CYGHZ51ZKHY)
  * [List all Databases](#01FY922V2QGDX6XCQFS6E7JX3T)
  * [Get a key/value pair](#01FY922V2QGDX6XCQFS6E7JX3T)
  * [Set a key/value pair](#01FY922V2QMJNFA7YDVWGS2TWZ)
  * [Delete a key/pair value](#01FY922V2QTBA9M8HX8A8ZG06P)
  * [Delete multiple key/value pairs](#01FYBSQMR03A2YR9T2D54KZMV8)
  * [Delete all key/value pairs](#01FYBT61QXFH7MYAC4REJWDK8H)
  * [Update a key/value pair](#01FYBS03J3KHAKD209S0GSH8F1)
  * [Upload multiple key/value pairs](#01FYBSTEZH8TG5DK9VX3NE4DDG)
  * [Get the total count of all key/value pairs](#01FY922V2QR91KTYS00X9ABQCN)
  * [Export multiple key/value pairs](#01FYBT1WK1ECB0985B7FXA2B8X)

### &#x20; <a href="#id-01fybm4mt4wyq6g9r9hpf4cm26" id="id-01fybm4mt4wyq6g9r9hpf4cm26"></a>

### **Databases 101** <a href="#h_01fy91r1fxrqth4n5dspjzv0t5" id="h_01fy91r1fxrqth4n5dspjzv0t5"></a>

Learn all about Databases feature in the following article: [Using Databases](https://docs.bird.com/connectivity-platform/advanced-functionalities/using-databases).

### &#x20; <a href="#id-01fybm4mt4ajgc460hqj5v4wft" id="id-01fybm4mt4ajgc460hqj5v4wft"></a>

### ***Store value*****&#x20;step** <a href="#h_01ffm3vzzapa1xwh52pd6kampn" id="h_01ffm3vzzapa1xwh52pd6kampn"></a>

The **Store value** step allows you to temporarily store values in a database that's connected to your workspace. A single database has a limited capacity (**10 000** entries), so you are able to combine this step with the [Delete value from Database step](#h_01FFM4DRKH28W19Y574CXC323P) to clean up entries in a given database.

&#x20;

<figure><img src="https://675349995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUJNEE9TMK4fU91VKstBr%2Fuploads%2Fgit-blob-934cdde74a9e2f7de8c6f814d0559c02336ff144%2Fblobid1.png?alt=media" alt=""><figcaption></figcaption></figure>

&#x20;

The **Store value** step configuration requires a couple of things.

#### A database <a href="#id-01fybnzwx2gd51mj8478n9p30n" id="id-01fybnzwx2gd51mj8478n9p30n"></a>

Choose the **exact database** you want to store the value to, as you are able to have more than one. If you'd like to see all your databases, click on *View your databases* and it will open a separate tab with all of them listed:

<figure><img src="https://675349995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUJNEE9TMK4fU91VKstBr%2Fuploads%2Fgit-blob-88e42a049839104afbec42829d1ba3300601a56d%2Fmceclip3.png?alt=media" alt=""><figcaption></figcaption></figure>

If you'd like to make a database on the spot, click on *Create new database*. It will also open a separate tab, allowing you to do the creation:

<figure><img src="https://675349995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUJNEE9TMK4fU91VKstBr%2Fuploads%2Fgit-blob-2b2055fe8b79e083176cebfb8d65339e1b094ed3%2Fmceclip5.png?alt=media" alt=""><figcaption></figcaption></figure>

#### A key <a href="#id-01fybp00nnh3d55g4qnv8hw530" id="id-01fybp00nnh3d55g4qnv8hw530"></a>

You are required to input a **key**, which is the identifier for the value you’re going to store. This way you can locate it in your database.

#### A value <a href="#id-01fybp04936wvzpvhm5vwr5agg" id="id-01fybp04936wvzpvhm5vwr5agg"></a>

You are also required to input a **value**, which is the content you are going to store in the database. It can be stored:

* * as a string
  * or a JSON formatted object
    * example:

```
{
 "name":"Super",
 "surname":"Mario"
}
```

Both **key** and **value** fields accept variables. If a given key already exists, this step will overwrite the value for that key.

If you want to store data for a specific user, make sure that you include a unique reference in the key, such as a phone number or contact ID. This will allow you to retrieve the value for this same user later on.

&#x20;

### ***Retrieve value from Database*****&#x20;step** <a href="#h_01ffm4phaj3r8v4hegs1ymrq5n" id="h_01ffm4phaj3r8v4hegs1ymrq5n"></a>

The **Retrieve value from database** step allows you to retrieve values that you've stored in your database.

The step configuration requires a key and a variable name:

* The **key** must be the same key from the [Store value step](#h_01FFM3VZZAPA1XWH52PD6KAMPN).
* The **variable name** is what the value will be stored in.

<figure><img src="https://675349995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUJNEE9TMK4fU91VKstBr%2Fuploads%2Fgit-blob-5a3cbd4b02b4d7c408b5661a1c8205a7ecf4a250%2Fmceclip1.png?alt=media" alt=""><figcaption></figcaption></figure>

&#x20;

#### Read value as JSON <a href="#id-01fybm4spkyrdnhx8et202f6wk" id="id-01fybm4spkyrdnhx8et202f6wk"></a>

The step offers the option to read the value as JSON. If you've stored a JSON object, then enabling this option will allow you to read out properties on the output variable using the dot notation (e.g. *{{outputVariable.property}}*).

&#x20;

<figure><img src="https://675349995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUJNEE9TMK4fU91VKstBr%2Fuploads%2Fgit-blob-ec2251adcc7eb55473ee06301708586ab5f15db9%2Fblobid0.png?alt=media" alt=""><figcaption></figcaption></figure>

&#x20;

#### Failure handling <a href="#id-01fybm4mt4e5qnc6wpzkdc06p7" id="id-01fybm4mt4e5qnc6wpzkdc06p7"></a>

There is a possibility of a failed status when a record cannot be found or a JSON error occurs. To keep your Flow running smoothly, you can enable branches that will handle it:

<figure><img src="https://675349995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUJNEE9TMK4fU91VKstBr%2Fuploads%2Fgit-blob-c2d655ee2d76f2e17d27a7b6546ccb9cfb67f556%2Fezgif.com-gif-maker.gif?alt=media" alt=""><figcaption></figcaption></figure>

&#x20;

### ***Delete value from Database*****&#x20;step** <a href="#h_01ffm4drkh28w19y574cxc323p" id="h_01ffm4drkh28w19y574cxc323p"></a>

The **Delete value from database** step will remove the key/value pair.\
This step only requires a **key** to be configured. As the database where we store your values is limited, you'll want to use this step in your Flow to clean up entries that you no longer need and keep your flow working smoothly.

<figure><img src="https://675349995-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FUJNEE9TMK4fU91VKstBr%2Fuploads%2Fgit-blob-1eda6e455fb2b78e9ded963f58fac8286bb83bc8%2Fmceclip2.png?alt=media" alt=""><figcaption></figcaption></figure>

&#x20;

An additional way of keeping your Database clean is making use of the [data retention settings](https://docs.bird.com/connectivity-platform/advanced-settings/data-retention-settings) of your databases.

&#x20;

### **Public API** <a href="#h_01ffm4pxjgss1fv6cv4d7x6ke5" id="h_01ffm4pxjgss1fv6cv4d7x6ke5"></a>

In addition to the Flow Builder steps, we also offer a public API to interact with the database. This can be used to set/retrieve values from external systems as well as to list all key/value pairs. The API consists of the following endpoints:

#### &#x20;List all key/value pairs <a href="#id-01fy922v2qfpkv3cyghz51zkhy" id="id-01fy922v2qfpkv3cyghz51zkhy"></a>

**GET** <https://flows.messagebird.com/databases/database\\_id>

```
curl "https://flows.messagebird.com/databases/database_id/" \\
-H 'Authorization: AccessKey <MESSAGEBIRD_ACCESS_KEY>'
```

#### List all Databases <a href="#id-01fy922v2qgdx6xcqfs6e7jx3t" id="id-01fy922v2qgdx6xcqfs6e7jx3t"></a>

**GET** <https://flows.messagebird.com/database-browser/>

```
curl "https://flows.messagebird.com/database-browser/" \\
-H 'Authorization: AccessKey <MESSAGEBIRD_ACCESS_KEY>'
```

#### Get a key/value pair <a href="#id-01g15t59w2vnfbqp1ke3xy0b6n" id="id-01g15t59w2vnfbqp1ke3xy0b6n"></a>

**GET** <https://flows.messagebird.com/databases/database\\_id/\\><key>

```
curl "https://flows.messagebird.com/databases/database_id/<KEY>" \\
-H 'Authorization: AccessKey <MESSAGEBIRD_ACCESS_KEY>'
```

#### Set a key/value pair <a href="#id-01fy922v2qmjnfa7ydvwgs2twz" id="id-01fy922v2qmjnfa7ydvwgs2twz"></a>

**POST** <https://flows.messagebird.com/databases/database\\_id> (put key and value in the JSON body)

```
curl -X "POST" "https://flows.messagebird.com/databases/database_id/" \\
-H 'Authorization: AccessKey <MESSAGEBIRD_ACCESS_KEY>' \\
-H 'Content-Type: application/json; charset=utf-8' \\
-d $'{
"key": "<YOUR_KEY>",
"value": "<YOUR_VALUE>"
}'
```

#### Delete a key/pair value <a href="#id-01fy922v2qtba9m8hx8a8zg06p" id="id-01fy922v2qtba9m8hx8a8zg06p"></a>

**DELETE** <https://flows.messagebird.com/databases/database\\_id/\\><key>

```
curl -X "DELETE" "https://flows.messagebird.com/databases/database_id/<KEY>" \\
-H 'Authorization: AccessKey <MESSAGEBIRD_ACCESS_KEY>'
```

#### Delete multiple key/value pairs <a href="#id-01fybsqmr03a2yr9t2d54kzmv8" id="id-01fybsqmr03a2yr9t2d54kzmv8"></a>

**POST** <https://flows.messagebird.com/databases/\\>\<database\_id>/batch-delete

```

curl -X "POST" "https://flows.messagebird.com/databases/<database_id>/batch-delete" \\
-H 'Authorization: AccessKey <MESSAGEBIRD_ACCESS_KEY>' \\
-H 'Content-Type: application/json; charset=utf-8' \\
-d $'{
"documentIds": [<YOUR_KEY1>, <YOUR_KEY2>, <YOUR_KEY3>],
}'
```

#### Delete all key/value pairs <a href="#id-01fybt61qxfh7myac4rejwdk8h" id="id-01fybt61qxfh7myac4rejwdk8h"></a>

**DELETE** <https://flows.messagebird.com/database-browser/\\>\<database\_id>/delete-all

```
curl -X "DELETE" "https://flows.messagebird.com/database-browser/<DATABASE_ID>/delete-all" \\
-H 'Authorization: AccessKey <MESSAGEBIRD_ACCESS_KEY>' \\
```

#### Update a key/value pair <a href="#id-01fybs03j3khakd209s0gsh8f1" id="id-01fybs03j3khakd209s0gsh8f1"></a>

**PUT** <https://flows.messagebird.com/databases/\\>\<database\_id>/\<key>

```
curl -X "PUT" "https://flows.messagebird.com/databases/<DATABASE_ID>/<KEY>" \\
-H 'Authorization: AccessKey <MESSAGEBIRD_ACCESS_KEY>' \\
-H 'Content-Type: application/json; charset=utf-8' \\
-d $'{
"key": "<YOUR_KEY>",
"value": "<YOUR_VALUE>"
}'
```

#### Upload multiple key/value pairs <a href="#id-01fybstezh8tg5dk9vx3ne4ddg" id="id-01fybstezh8tg5dk9vx3ne4ddg"></a>

**POST** <https://flows.messagebird.com/databases/>\<database\_id>/upload<br>

```
curl -X "POST" "https://flows.messagebird.com/databases/<database_id>/upload" \\
-H 'Authorization: AccessKey <MESSAGEBIRD_ACCESS_KEY>' \\
-H 'Content-Type: text/csv; charset=utf-8' \\
-d @data.csv
```

#### Get the total count of all key/value pairs <a href="#id-01fy922v2qr91ktys00x9abqcn" id="id-01fy922v2qr91ktys00x9abqcn"></a>

**POST** <https://flows.messagebird.com/databases/database\\_id/count>

```
curl -X "POST" "https://flows.messagebird.com/databases/database_id/count" \\
-H 'Authorization: AccessKey <MESSAGEBIRD_ACCESS_KEY>'
```

#### Export multiple key/value pairs <a href="#id-01fybt1wk1ecb0985b7fxa2b8x" id="id-01fybt1wk1ecb0985b7fxa2b8x"></a>

**POST** <https://flows.messagebird.com/databases/>\<database\_id>/export<br>

```
curl -X "POST" "https://flows.messagebird.com/databases/<DATABASE_ID>/export" \\
-H 'Authorization: AccessKey <MESSAGEBIRD_ACCESS_KEY>' \\
-H 'Content-Type: text/csv; charset=utf-8' \\
```

As multiple databases are supported:

* if you are calling the default database, use ***key-values*** parameter to indicate the ID.
* if you are calling a specific database, use **database\_id** parameter.

&#x20;

📤 Feel free to [contact our Support](https://support.messagebird.com/hc/en-us/requests/new) in case you might need some help!