# Custom Field mapping

Expose a provider-specific value under a consistent response key with custom mappings. For example, your accounting product might need a customer's internal cost-center code alongside an invoice. The source field can differ between connectors and between customers using the same connector.

Start with the [Accounting data model](/guides/accounting-data-model): use a unified field when it already expresses the value you need. Use a custom mapping for additional response data, and check availability for the chosen connector and resource.

## Understanding API Fields

### Response fields

These are properties returned by the provider's API, such as an invoice number or a provider-specific classification. [Raw mode](/guides/using-raw-mode) helps you inspect the original response when the operation supports it.

### Custom fields

Customers can define additional fields in some providers. Their IDs, names, and values can vary by customer. A field called “Cost center” in one account may not exist in another. The customer administrator must identify the appropriate field for their connection.

### Unified models

Apideck normalizes supported fields into a shared model. A shared schema does not mean every connector supports every field or operation. Check [connector coverage](/apis/accounting/coverage), the operation reference, and a sample response from the customer's connection.

## Mapping fields

The response follows this path:

```text
Provider response or customer-defined field
  → mapping configured for the integration / connection
  → custom_mappings.<your_key>
  → your application's business logic
```

Define a stable key in your app, configure its source, and verify the returned value before making the workflow depend on it.

## Field mapping feature

### Developer setup

1. Open **Configuration → Custom Mapping** in the [Apideck dashboard](https://platform.apideck.com).
2. Select the Unified API and create a mapping with a stable key, a recognizable name, and a description of the value your application expects.
3. Configure the source for each integration you support. Decide whether it is a provider response property or a customer-defined field.
4. If your workflow cannot proceed without the value, configure the mapping as required and explain that requirement before asking the customer to connect.

For an accounting workflow, `cost_center` is an illustrative key. Do not assume a field with that name exists in a provider or that all accounting resources expose it.

### Customer administrator setup

For customer-defined fields, the administrator selects the source field in Vault's custom-mapping view. Keep that setup step available in your [Vault integration](/guides/vault). Tell the administrator what the value is used for and which records should contain it.

Link customers to the maintained connector instructions for prerequisites and permissions. Avoid duplicating provider screenshots in your own onboarding flow.

### Verify the response

Read a record known to contain the source value using the same consumer and connector that were configured. Check `custom_mappings` in the response. This simplified example illustrates the output shape; the ID and value are sample data:

```json
{
  "data": {
    "id": "invoice-123",
    "custom_mappings": {
      "cost_center": "Operations"
    }
  }
}
```

A mapping is returned only when a value is available from its source. Your application must handle a missing mapping rather than assuming an empty string, a default value, or a successful setup.

>
> A response mapping does not establish write support. Before sending custom data, check the selected operation's writable fields and connector behavior. Do not assume posting `custom_mappings` writes the provider field.

## Field mapping types

### Property mapping

Choose property mapping when the desired value is a regular property of the downstream response. The developer configures the source for the integration. Inspect a real sample response rather than guessing the path from a display label.

### Custom field mapping

Choose custom field mapping when the source is defined by the customer in their provider account. The customer selects that field for their connection in Vault. Keep mappings scoped to the correct consumer; one customer's field configuration is not a template for every other account.

## Troubleshooting

| Symptom | What to check |
| --- | --- |
| The mapping is absent | Confirm the source field has a value on this record and is available in the provider response. |
| It works for one customer only | Verify each consumer's connection and custom-field selection independently. |
| The value is unexpected | Compare the original response, selected source field, and mapping key in [Logs](/logs). |
| The field cannot be selected | Check connector/resource support, permissions, and the customer's field configuration. |
| A write rejects the mapping | Use the operation's documented writable fields; response mapping alone does not add write capabilities. |

See the [maintained custom-mapping setup guide](https://help.apideck.com/en/articles/4231554) for dashboard configuration, or the [Vault Custom Mappings reference](/apis/vault/reference/custom-mappings) for programmatic management.