# Vault API — Custom Mappings

> Canonical URL: https://developers.apideck.com/apis/vault/reference#tag/Custom-Mappings

This document contains every operation on the `Custom Mappings` resource.

---

# Get custom mapping

> **Vault API** · `GET /vault/custom-mappings/{unified_api}/{service_id}/{target_field_id}`
> Canonical URL: https://developers.apideck.com/apis/vault/reference#tag/Custom-Mappings/operation/customMappingsOne

## Authentication

- Send `Authorization: Bearer $API_KEY` using your Apideck secret API key. Keep the key server-side; never put it in a URL or client-side code.

Use the application, consumer and connector headers listed in Parameters below for this operation.

Get a custom mapping

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `x-apideck-consumer-id` | header | `string` | Yes | ID of the consumer which you want to get or push data from |
| `x-apideck-app-id` | header | `string` | Yes | The ID of your Unify application |
| `unified_api` | path | `string` | Yes | Unified API |
| `service_id` | path | `string` | Yes | Service ID of the resource to return |
| `target_field_id` | path | `string` | Yes | ID of the target field to return as a custom mapping. |

### Responses

#### 200 — Custom mapping

- `status_code` `integer` **required** — HTTP Response Status Code — example: `200`
- `status` `string` **required** — HTTP Response Status — example: `OK`
- `data` `object` **required**
  - `id` `string` — Target Field ID — example: `hris+employees+first_aid_training`
  - `label` `string` — Target Field name to use as a label — example: `First Aid Training`
  - `description` `string` — Target Field description — example: `First Aid Training completed after 2019-01-01`
  - `value` `string` — Target Field Mapping value — example: `$.root.training.first_aid`
  - `key` `string` — Target Field Key — example: `first_aid_training`
  - `required` `boolean` — Target Field Mapping is required — example: `false`
  - `custom_field` `boolean` — This mapping represents a finder for a custom field — example: `true`
  - `consumer_id` `string` — Consumer ID — example: `test_user_id`
  - `example` `string` — Target Field Mapping example value from downstream — example: `Some value`
- `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=`
  - `total_count` `integer` — Number of records available in total for this resource — example: `1`
  - `warnings` `array of object` — Non-fatal warnings emitted when optional workflow steps failed. Present only when at least one step degraded; the response status remains 200.
    - `type` `string` — Discriminator for the warning kind. — example: `downstream_request_failed`
    - `status_code` `integer` — HTTP status code returned by the failed downstream request, when available. — example: `429`
    - `error` `string` — Short error description from the downstream provider, when available.
    - `operation` `string` — Identifier of the workflow step that failed. — example: `getManager`
    - `message` `string` — Detailed message from the downstream provider, when available.
- `_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 custom mapping

> **Vault API** · `POST /vault/custom-mappings/{unified_api}/{service_id}/{target_field_id}`
> Canonical URL: https://developers.apideck.com/apis/vault/reference#tag/Custom-Mappings/operation/customMappingsAdd

## Authentication

- Send `Authorization: Bearer $API_KEY` using your Apideck secret API key. Keep the key server-side; never put it in a URL or client-side code.

Use the application, consumer and connector headers listed in Parameters below for this operation.

Create a custom mapping

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `x-apideck-consumer-id` | header | `string` | Yes | ID of the consumer which you want to get or push data from |
| `x-apideck-app-id` | header | `string` | Yes | The ID of your Unify application |
| `unified_api` | path | `string` | Yes | Unified API |
| `service_id` | path | `string` | Yes | Service ID of the resource to return |
| `target_field_id` | path | `string` | Yes | ID of the target field to return as a custom mapping. |

### Request Body

Fields that need to be updated on the resource

_Required._

- `value` `string` **required** — Target Field Mapping value — example: `$.root.training.first_aid`

### Responses

#### 200 — Custom mapping created

- `status_code` `integer` **required** — HTTP Response Status Code — example: `200`
- `status` `string` **required** — HTTP Response Status — example: `OK`
- `data` `object` **required**
  - `id` `string` — Target Field ID — example: `hris+employees+first_aid_training`
  - `label` `string` — Target Field name to use as a label — example: `First Aid Training`
  - `description` `string` — Target Field description — example: `First Aid Training completed after 2019-01-01`
  - `value` `string` — Target Field Mapping value — example: `$.root.training.first_aid`
  - `key` `string` — Target Field Key — example: `first_aid_training`
  - `required` `boolean` — Target Field Mapping is required — example: `false`
  - `custom_field` `boolean` — This mapping represents a finder for a custom field — example: `true`
  - `consumer_id` `string` — Consumer ID — example: `test_user_id`
  - `example` `string` — Target Field Mapping example value from downstream — example: `Some value`
- `_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)

---

# Deletes a custom mapping

> **Vault API** · `DELETE /vault/custom-mappings/{unified_api}/{service_id}/{target_field_id}`
> Canonical URL: https://developers.apideck.com/apis/vault/reference#tag/Custom-Mappings/operation/customMappingsDelete

## Authentication

- Send `Authorization: Bearer $API_KEY` using your Apideck secret API key. Keep the key server-side; never put it in a URL or client-side code.

Use the application, consumer and connector headers listed in Parameters below for this operation.

Deletes a custom mapping

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `x-apideck-consumer-id` | header | `string` | Yes | ID of the consumer which you want to get or push data from |
| `x-apideck-app-id` | header | `string` | Yes | The ID of your Unify application |
| `unified_api` | path | `string` | Yes | Unified API |
| `service_id` | path | `string` | Yes | Service ID of the resource to return |
| `target_field_id` | path | `string` | Yes | ID of the target field to return as a custom mapping. |

### Responses

#### 204 — Resource deleted

#### 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 custom mapping

> **Vault API** · `PATCH /vault/custom-mappings/{unified_api}/{service_id}/{target_field_id}`
> Canonical URL: https://developers.apideck.com/apis/vault/reference#tag/Custom-Mappings/operation/customMappingsUpdate

## Authentication

- Send `Authorization: Bearer $API_KEY` using your Apideck secret API key. Keep the key server-side; never put it in a URL or client-side code.

Use the application, consumer and connector headers listed in Parameters below for this operation.

Update a custom mapping

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `x-apideck-consumer-id` | header | `string` | Yes | ID of the consumer which you want to get or push data from |
| `x-apideck-app-id` | header | `string` | Yes | The ID of your Unify application |
| `unified_api` | path | `string` | Yes | Unified API |
| `service_id` | path | `string` | Yes | Service ID of the resource to return |
| `target_field_id` | path | `string` | Yes | ID of the target field to return as a custom mapping. |

### Request Body

Fields that need to be updated on the resource

_Required._

- `value` `string` **required** — Target Field Mapping value — example: `$.root.training.first_aid`

### Responses

#### 200 — Custom mapping updated

- `status_code` `integer` **required** — HTTP Response Status Code — example: `200`
- `status` `string` **required** — HTTP Response Status — example: `OK`
- `data` `object` **required**
  - `id` `string` — Target Field ID — example: `hris+employees+first_aid_training`
  - `label` `string` — Target Field name to use as a label — example: `First Aid Training`
  - `description` `string` — Target Field description — example: `First Aid Training completed after 2019-01-01`
  - `value` `string` — Target Field Mapping value — example: `$.root.training.first_aid`
  - `key` `string` — Target Field Key — example: `first_aid_training`
  - `required` `boolean` — Target Field Mapping is required — example: `false`
  - `custom_field` `boolean` — This mapping represents a finder for a custom field — example: `true`
  - `consumer_id` `string` — Consumer ID — example: `test_user_id`
  - `example` `string` — Target Field Mapping example value from downstream — example: `Some value`
- `_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)

---

# List custom mappings

> **Vault API** · `GET /vault/custom-mappings/{unified_api}/{service_id}`
> Canonical URL: https://developers.apideck.com/apis/vault/reference#tag/Custom-Mappings/operation/customMappingsAll

## Authentication

- Send `Authorization: Bearer $API_KEY` using your Apideck secret API key. Keep the key server-side; never put it in a URL or client-side code.

Use the application, consumer and connector headers listed in Parameters below for this operation.

This endpoint returns a list of custom mappings.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `x-apideck-consumer-id` | header | `string` | Yes | ID of the consumer which you want to get or push data from |
| `x-apideck-app-id` | header | `string` | Yes | The ID of your Unify application |
| `unified_api` | path | `string` | Yes | Unified API |
| `service_id` | path | `string` | Yes | Service ID of the resource to return |

### Responses

#### 200 — Custom mapping

- `status_code` `integer` **required** — HTTP Response Status Code — example: `200`
- `status` `string` **required** — HTTP Response Status — example: `OK`
- `data` `array of object` **required**
  - `id` `string` — Target Field ID — example: `hris+employees+first_aid_training`
  - `label` `string` — Target Field name to use as a label — example: `First Aid Training`
  - `description` `string` — Target Field description — example: `First Aid Training completed after 2019-01-01`
  - `value` `string` — Target Field Mapping value — example: `$.root.training.first_aid`
  - `key` `string` — Target Field Key — example: `first_aid_training`
  - `required` `boolean` — Target Field Mapping is required — example: `false`
  - `custom_field` `boolean` — This mapping represents a finder for a custom field — example: `true`
  - `consumer_id` `string` — Consumer ID — example: `test_user_id`
  - `example` `string` — Target Field Mapping example value from downstream — example: `Some value`
- `_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)

---