# Vault API — Consumers

> Canonical URL: https://developers.apideck.com/apis/vault/reference#tag/Consumers

This document contains every operation on the `Consumers` resource.

---

# Get all consumers

> **Vault API** · `GET /vault/consumers`
> Canonical URL: https://developers.apideck.com/apis/vault/reference#tag/Consumers/operation/consumersAll

This endpoint includes all application consumers, along with an aggregated count of requests made.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `x-apideck-app-id` | header | `string` | Yes | The ID of your Unify application |
| `filter` | query | `object` | No | Filter results |
| `cursor` | query | `string` | No | Cursor to start from. You can find cursors for next/previous pages in the meta.cursors property of the response. |
| `limit` | query | `integer` | No | Number of results to return. Minimum 1, Maximum 200, Default 20 |

### Responses

#### 200 — Consumers

- `status_code` `integer` **required** — HTTP Response Status Code — example: `200`
- `status` `string` **required** — HTTP Response Status — example: `OK`
- `data` `array of object` **required**
  - `consumer_id` `string` — example: `test_consumer_id`
  - `application_id` `string` — example: `1111`
  - `metadata` `object` — The metadata of the consumer. This is used to display the consumer in the sidebar. This is optional, but recommended.
    - `account_name` `string` — The name of the account as shown in the sidebar. — example: `SpaceX`
    - `user_name` `string` — The name of the user as shown in the sidebar. — example: `Elon Musk`
    - `email` `string` — The email of the user as shown in the sidebar. — example: `elon@musk.com`
    - `image` `string` — The avatar of the user in the sidebar. Must be a valid URL — example: `https://www.spacex.com/static/images/share.jpg`
  - `aggregated_request_count` `number` — example: `101`
  - `request_counts` `object`
    - `unify` `number` — example: `100`
    - `proxy` `number` — example: `10`
    - `vault` `number` — example: `21`
  - `created` `string` — example: `2021-05-07T12:55:42.242Z`
  - `modified` `string` — example: `2021-05-07T12:55:42.242Z`
  - `request_count_updated` `string` — example: `2021-05-07T12:55:42.242Z`
  - `services` `array of string`
- `meta` `object` — Response metadata
  - `items_on_page` `integer` — Number of items returned in the data property of the response — example: `50`
  - `cursors` `object` — Cursors to navigate to previous or next pages through the API
    - `previous` `string` — Cursor to navigate to the previous page of results through the API — example: `em9oby1jcm06OnBhZ2U6OjE=`
    - `current` `string` — Cursor to navigate to the current page of results through the API — example: `em9oby1jcm06OnBhZ2U6OjI=`
    - `next` `string` — Cursor to navigate to the next page of results through the API — example: `em9oby1jcm06OnBhZ2U6OjM=`
- `links` `object` — Links to navigate to previous or next pages through the API
  - `previous` `string` — Link to navigate to the previous page through the API — example: `https://unify.apideck.com/crm/companies?cursor=em9oby1jcm06OnBhZ2U6OjE%3D`
  - `current` `string` — Link to navigate to the current page through the API — example: `https://unify.apideck.com/crm/companies`
  - `next` `string` — Link to navigate to the previous page through the API — example: `https://unify.apideck.com/crm/companies?cursor=em9oby1jcm06OnBhZ2U6OjM`
- `_raw` `object` — Raw response from the integration when raw=true query param is provided

#### 400 — Bad Request

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 401 — Unauthorized

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 402 — Payment Required

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 404 — The specified resource was not found

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 422 — Unprocessable

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### default — Unexpected error

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

---

# Create consumer

> **Vault API** · `POST /vault/consumers`
> Canonical URL: https://developers.apideck.com/apis/vault/reference#tag/Consumers/operation/consumersAdd

Create a consumer

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `x-apideck-app-id` | header | `string` | Yes | The ID of your Unify application |

### Request Body

_Required._

- `consumer_id` `string` **required** — Unique consumer identifier. You can freely choose a consumer ID yourself. Most of the time, this is an ID of your internal data model that represents a user or account in your system (for example account:12345). If the consumer doesn't exist yet, Vault will upsert a consumer based on your ID. — example: `test_consumer_id`
- `metadata` `object` — The metadata of the consumer. This is used to display the consumer in the sidebar. This is optional, but recommended.
  - `account_name` `string` — The name of the account as shown in the sidebar. — example: `SpaceX`
  - `user_name` `string` — The name of the user as shown in the sidebar. — example: `Elon Musk`
  - `email` `string` — The email of the user as shown in the sidebar. — example: `elon@musk.com`
  - `image` `string` — The avatar of the user in the sidebar. Must be a valid URL — example: `https://www.spacex.com/static/images/share.jpg`

### Responses

#### 200 — Consumer created

- `status_code` `integer` **required** — HTTP Response Status Code — example: `200`
- `status` `string` **required** — HTTP Response Status — example: `OK`
- `data` `object` **required**
  - `consumer_id` `string` **required** — Unique consumer identifier. You can freely choose a consumer ID yourself. Most of the time, this is an ID of your internal data model that represents a user or account in your system (for example account:12345). If the consumer doesn't exist yet, Vault will upsert a consumer based on your ID. — example: `test_consumer_id`
  - `application_id` `string` — ID of your Apideck Application — example: `dSBdXd2H6Mqwfg0atXHXYcysLJE9qyn1VwBtXHX`
  - `metadata` `object` — The metadata of the consumer. This is used to display the consumer in the sidebar. This is optional, but recommended.
    - `account_name` `string` — The name of the account as shown in the sidebar. — example: `SpaceX`
    - `user_name` `string` — The name of the user as shown in the sidebar. — example: `Elon Musk`
    - `email` `string` — The email of the user as shown in the sidebar. — example: `elon@musk.com`
    - `image` `string` — The avatar of the user in the sidebar. Must be a valid URL — example: `https://www.spacex.com/static/images/share.jpg`
  - `connections` `array of object`
    - `id` `string` — example: `1111+test_user_id`
    - `name` `string` — example: `Salesforce`
    - `icon` `string` — example: `https://res.cloudinary.com/apideck/image/upload/v1529456047/catalog/salesforce/icon128x128.png`
    - `logo` `string` — example: `https://c1.sfdcstatic.com/content/dam/web/en_us/www/images/home/logo-salesforce-m.svg`
    - `website` `string` — example: `https://www.salesforce.com`
    - `tag_line` `string` — example: `CRM software solutions and enterprise cloud computing from Salesforce, the leader in customer relationship management (CRM) and PaaS. Free 30 day trial.`
    - `service_id` `string` — example: `teamleader`
    - `unified_api` `string` — example: `crm`
    - `consumer_id` `string` — example: `test_user_id`
    - `auth_type` `string` — Type of authorization used by the connector — enum: `oauth2`, `apiKey`, `basic`, `custom`, `none` — example: `oauth2`
    - `enabled` `boolean` — example: `true`
    - `settings` `object` — Connection settings. Values will persist to `form_fields` with corresponding id
    - `metadata` `object` — Attach your own consumer specific metadata
    - `created_at` `string` — example: `2020-09-19T12:18:37.071Z`
    - `updated_at` `string` — example: `2020-09-19T12:18:37.071Z`
    - `state` `string` — [Connection state flow](#section/Connection-state) — enum: `available`, `callable`, `added`, `authorized`, `invalid` — example: `authorized`
    - `health` `string` — The operational health status of the connection — enum: `ok`, `pending_refresh`, `needs_auth`, `needs_consent`, `revoked`, `missing_settings` — example: `ok`
    - `credentials_expire_at` `string` — ISO 8601 timestamp indicating when credentials will be cleared if token refresh continues to fail. Only present when connection health is pending_refresh and a retention window is active.
    - `last_refresh_failed_at` `string` — ISO 8601 timestamp of the most recent token refresh failure. Only present when connection has experienced refresh failures.
  - `services` `array of string`
  - `aggregated_request_count` `number` — example: `101`
  - `request_counts` `object`
    - `unify` `number` — example: `100`
    - `proxy` `number` — example: `10`
    - `vault` `number` — example: `21`
  - `created` `string` — example: `2021-05-07T12:55:42.242Z`
  - `modified` `string` — example: `2021-05-07T12:55:42.242Z`
  - `request_count_updated` `string` — example: `2021-05-07T12:55:42.242Z`
- `_raw` `object` — Raw response from the integration when raw=true query param is provided

#### 400 — Bad Request

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 401 — Unauthorized

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 402 — Payment Required

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 404 — The specified resource was not found

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 422 — Unprocessable

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### default — Unexpected error

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

---

# Get consumer

> **Vault API** · `GET /vault/consumers/{consumer_id}`
> Canonical URL: https://developers.apideck.com/apis/vault/reference#tag/Consumers/operation/consumersOne

Consumer detail including their aggregated counts with the connections they have authorized.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `x-apideck-app-id` | header | `string` | Yes | The ID of your Unify application |
| `consumer_id` | path | `string` | Yes | ID of the consumer to return |

### Responses

#### 200 — Consumer

- `status_code` `integer` **required** — HTTP Response Status Code — example: `200`
- `status` `string` **required** — HTTP Response Status — example: `OK`
- `data` `object` **required**
  - `consumer_id` `string` **required** — Unique consumer identifier. You can freely choose a consumer ID yourself. Most of the time, this is an ID of your internal data model that represents a user or account in your system (for example account:12345). If the consumer doesn't exist yet, Vault will upsert a consumer based on your ID. — example: `test_consumer_id`
  - `application_id` `string` — ID of your Apideck Application — example: `dSBdXd2H6Mqwfg0atXHXYcysLJE9qyn1VwBtXHX`
  - `metadata` `object` — The metadata of the consumer. This is used to display the consumer in the sidebar. This is optional, but recommended.
    - `account_name` `string` — The name of the account as shown in the sidebar. — example: `SpaceX`
    - `user_name` `string` — The name of the user as shown in the sidebar. — example: `Elon Musk`
    - `email` `string` — The email of the user as shown in the sidebar. — example: `elon@musk.com`
    - `image` `string` — The avatar of the user in the sidebar. Must be a valid URL — example: `https://www.spacex.com/static/images/share.jpg`
  - `connections` `array of object`
    - `id` `string` — example: `1111+test_user_id`
    - `name` `string` — example: `Salesforce`
    - `icon` `string` — example: `https://res.cloudinary.com/apideck/image/upload/v1529456047/catalog/salesforce/icon128x128.png`
    - `logo` `string` — example: `https://c1.sfdcstatic.com/content/dam/web/en_us/www/images/home/logo-salesforce-m.svg`
    - `website` `string` — example: `https://www.salesforce.com`
    - `tag_line` `string` — example: `CRM software solutions and enterprise cloud computing from Salesforce, the leader in customer relationship management (CRM) and PaaS. Free 30 day trial.`
    - `service_id` `string` — example: `teamleader`
    - `unified_api` `string` — example: `crm`
    - `consumer_id` `string` — example: `test_user_id`
    - `auth_type` `string` — Type of authorization used by the connector — enum: `oauth2`, `apiKey`, `basic`, `custom`, `none` — example: `oauth2`
    - `enabled` `boolean` — example: `true`
    - `settings` `object` — Connection settings. Values will persist to `form_fields` with corresponding id
    - `metadata` `object` — Attach your own consumer specific metadata
    - `created_at` `string` — example: `2020-09-19T12:18:37.071Z`
    - `updated_at` `string` — example: `2020-09-19T12:18:37.071Z`
    - `state` `string` — [Connection state flow](#section/Connection-state) — enum: `available`, `callable`, `added`, `authorized`, `invalid` — example: `authorized`
    - `health` `string` — The operational health status of the connection — enum: `ok`, `pending_refresh`, `needs_auth`, `needs_consent`, `revoked`, `missing_settings` — example: `ok`
    - `credentials_expire_at` `string` — ISO 8601 timestamp indicating when credentials will be cleared if token refresh continues to fail. Only present when connection health is pending_refresh and a retention window is active.
    - `last_refresh_failed_at` `string` — ISO 8601 timestamp of the most recent token refresh failure. Only present when connection has experienced refresh failures.
  - `services` `array of string`
  - `aggregated_request_count` `number` — example: `101`
  - `request_counts` `object`
    - `unify` `number` — example: `100`
    - `proxy` `number` — example: `10`
    - `vault` `number` — example: `21`
  - `created` `string` — example: `2021-05-07T12:55:42.242Z`
  - `modified` `string` — example: `2021-05-07T12:55:42.242Z`
  - `request_count_updated` `string` — example: `2021-05-07T12:55:42.242Z`
- `_raw` `object` — Raw response from the integration when raw=true query param is provided

#### 400 — Bad Request

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 401 — Unauthorized

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 402 — Payment Required

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 404 — The specified resource was not found

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 422 — Unprocessable

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### default — Unexpected error

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

---

# Delete consumer

> **Vault API** · `DELETE /vault/consumers/{consumer_id}`
> Canonical URL: https://developers.apideck.com/apis/vault/reference#tag/Consumers/operation/consumersDelete

Delete consumer and all their connections, including credentials.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `x-apideck-app-id` | header | `string` | Yes | The ID of your Unify application |
| `consumer_id` | path | `string` | Yes | ID of the consumer to return |

### Responses

#### 200 — Consumer deleted

- `status_code` `integer` **required** — HTTP Response Status Code — example: `200`
- `status` `string` **required** — HTTP Response Status — example: `OK`
- `data` `any` **required**
- `_raw` `object` — Raw response from the integration when raw=true query param is provided

#### 400 — Bad Request

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 401 — Unauthorized

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 402 — Payment Required

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 404 — The specified resource was not found

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 422 — Unprocessable

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### default — Unexpected error

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

---

# Update consumer

> **Vault API** · `PATCH /vault/consumers/{consumer_id}`
> Canonical URL: https://developers.apideck.com/apis/vault/reference#tag/Consumers/operation/consumersUpdate

Update consumer metadata such as name and email.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `x-apideck-app-id` | header | `string` | Yes | The ID of your Unify application |
| `consumer_id` | path | `string` | Yes | ID of the consumer to return |

### Request Body

_Required._

- `metadata` `object` — The metadata of the consumer. This is used to display the consumer in the sidebar. This is optional, but recommended.
  - `account_name` `string` — The name of the account as shown in the sidebar. — example: `SpaceX`
  - `user_name` `string` — The name of the user as shown in the sidebar. — example: `Elon Musk`
  - `email` `string` — The email of the user as shown in the sidebar. — example: `elon@musk.com`
  - `image` `string` — The avatar of the user in the sidebar. Must be a valid URL — example: `https://www.spacex.com/static/images/share.jpg`

### Responses

#### 200 — Consumer updated

- `status_code` `integer` **required** — HTTP Response Status Code — example: `200`
- `status` `string` **required** — HTTP Response Status — example: `OK`
- `data` `object` **required**
  - `consumer_id` `string` **required** — Unique consumer identifier. You can freely choose a consumer ID yourself. Most of the time, this is an ID of your internal data model that represents a user or account in your system (for example account:12345). If the consumer doesn't exist yet, Vault will upsert a consumer based on your ID. — example: `test_consumer_id`
  - `application_id` `string` — ID of your Apideck Application — example: `dSBdXd2H6Mqwfg0atXHXYcysLJE9qyn1VwBtXHX`
  - `metadata` `object` — The metadata of the consumer. This is used to display the consumer in the sidebar. This is optional, but recommended.
    - `account_name` `string` — The name of the account as shown in the sidebar. — example: `SpaceX`
    - `user_name` `string` — The name of the user as shown in the sidebar. — example: `Elon Musk`
    - `email` `string` — The email of the user as shown in the sidebar. — example: `elon@musk.com`
    - `image` `string` — The avatar of the user in the sidebar. Must be a valid URL — example: `https://www.spacex.com/static/images/share.jpg`
  - `connections` `array of object`
    - `id` `string` — example: `1111+test_user_id`
    - `name` `string` — example: `Salesforce`
    - `icon` `string` — example: `https://res.cloudinary.com/apideck/image/upload/v1529456047/catalog/salesforce/icon128x128.png`
    - `logo` `string` — example: `https://c1.sfdcstatic.com/content/dam/web/en_us/www/images/home/logo-salesforce-m.svg`
    - `website` `string` — example: `https://www.salesforce.com`
    - `tag_line` `string` — example: `CRM software solutions and enterprise cloud computing from Salesforce, the leader in customer relationship management (CRM) and PaaS. Free 30 day trial.`
    - `service_id` `string` — example: `teamleader`
    - `unified_api` `string` — example: `crm`
    - `consumer_id` `string` — example: `test_user_id`
    - `auth_type` `string` — Type of authorization used by the connector — enum: `oauth2`, `apiKey`, `basic`, `custom`, `none` — example: `oauth2`
    - `enabled` `boolean` — example: `true`
    - `settings` `object` — Connection settings. Values will persist to `form_fields` with corresponding id
    - `metadata` `object` — Attach your own consumer specific metadata
    - `created_at` `string` — example: `2020-09-19T12:18:37.071Z`
    - `updated_at` `string` — example: `2020-09-19T12:18:37.071Z`
    - `state` `string` — [Connection state flow](#section/Connection-state) — enum: `available`, `callable`, `added`, `authorized`, `invalid` — example: `authorized`
    - `health` `string` — The operational health status of the connection — enum: `ok`, `pending_refresh`, `needs_auth`, `needs_consent`, `revoked`, `missing_settings` — example: `ok`
    - `credentials_expire_at` `string` — ISO 8601 timestamp indicating when credentials will be cleared if token refresh continues to fail. Only present when connection health is pending_refresh and a retention window is active.
    - `last_refresh_failed_at` `string` — ISO 8601 timestamp of the most recent token refresh failure. Only present when connection has experienced refresh failures.
  - `services` `array of string`
  - `aggregated_request_count` `number` — example: `101`
  - `request_counts` `object`
    - `unify` `number` — example: `100`
    - `proxy` `number` — example: `10`
    - `vault` `number` — example: `21`
  - `created` `string` — example: `2021-05-07T12:55:42.242Z`
  - `modified` `string` — example: `2021-05-07T12:55:42.242Z`
  - `request_count_updated` `string` — example: `2021-05-07T12:55:42.242Z`
- `_raw` `object` — Raw response from the integration when raw=true query param is provided

#### 400 — Bad Request

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 401 — Unauthorized

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 402 — Payment Required

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 404 — The specified resource was not found

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 422 — Unprocessable

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### default — Unexpected error

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

---

# Consumer request counts

> **Vault API** · `GET /vault/consumers/{consumer_id}/stats`
> Canonical URL: https://developers.apideck.com/apis/vault/reference#tag/Consumers/operation/consumerRequestCountsAll

Get consumer request counts within a given datetime range.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `x-apideck-app-id` | header | `string` | Yes | The ID of your Unify application |
| `consumer_id` | path | `string` | Yes | ID of the consumer to return |
| `start_datetime` | query | `string` | Yes | Scopes results to requests that happened after datetime |
| `end_datetime` | query | `string` | Yes | Scopes results to requests that happened before datetime |

### Responses

#### 200 — Consumers Request Counts within Date Range

- `status_code` `integer` **required** — HTTP Response Status Code — example: `200`
- `status` `string` **required** — HTTP Response Status — example: `OK`
- `data` `object` **required**
  - `application_id` `string` — example: `1111`
  - `consumer_id` `string` — example: `test_user_id`
  - `start_datetime` `string` — example: `2021-05-01T12:00:00.000Z`
  - `end_datetime` `string` — example: `2021-05-10T12:00:00.000Z`
  - `aggregated_request_count` `number` — example: `40`
  - `request_counts` `object`
    - `unify` `number` — example: `100`
    - `proxy` `number` — example: `10`
    - `vault` `number` — example: `21`
- `_raw` `object` — Raw response from the integration when raw=true query param is provided

#### 400 — Bad Request

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 401 — Unauthorized

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 402 — Payment Required

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 404 — The specified resource was not found

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 422 — Unprocessable

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### default — Unexpected error

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

---