# What are KV Pairs?

Source: https://dev.arcxp.com/audience-insights/developer-docs/what-are-audience-insights-kv-pairs/

Learn about Audience Insights Key Value Pairs

KV Pairs is a feature of Audience Insights that enables a publisher to configure a list of data points for which it wishes to collect data about its users. Each data point (key) must be configured in Settings Admin before the Audience Insights APIs will accept data for them. Configuration items for a KV pair include its time to live (TTL) in the Audience Insights database, input validation of the value(s) that will be accepted, and whether the value will be piped through an IFX Integration prior to being stored in Audience Insights.

Suggested uses for KV Pairs include tracking individual newsletters that the user may have signed up for, survey responses and other items that may enable personalized experiences for the individual user while consuming content.

> **Note:**
> 
> Audience Insights also has a variation of KV Pairs referred to as [IAB pairs](https://dev.arcxp.com/audience-insights/developer-docs/what-are-audience-insights-kv-pairs/how-to-use-the-iab-audience-taxonomy). Here a list of common keys and input validations have already been defined by the Interactive Advertising Bureau. Please consider using IAB pairs before defining common keys using KV Pairs.

## APIs For Working With KV Pairs

The KV Pair feature has two sets of APIs: 1) Public APIs that can be called by readers who are signed in; and 2) Developer APIs that can be called by the publisher’s servers to store values for individual users. These are the available APIs:

### Public APIs

| HTTP Method | Path                                   | Description                                                 |
| ----------- | -------------------------------------- | ----------------------------------------------------------- |
| GET         | /identity/public/v2/extprofile/kv/:key | Get the value of a single key for a signed-in user          |
| GET         | /identity/public/v2/extprofile/kv      | Get all key-value pairs for a signed-in user                |
| POST        | /identity/public/v2/extprofile/kv      | Store a key-value pair in the account of the signed-in user |

### Developer APIs

| HTTP Method | Path                                      | Description                                            |
| ----------- | ----------------------------------------- | ------------------------------------------------------ |
| DELETE      | /identity/api/v2/extprofile/kv/i/:id/:key | Delete a key-value pair for the indicated user account |
| GET         | /identity/api/v2/extprofile/kv/i/:id/:key | Get the value of a key for the indicated user account  |
| GET         | /identity/api/v2/extprofile/kv/i/:id      | Get all key-value pairs for the indicated user account |
| POST        | /identity/api/v2/extprofile/kv/i/:id      | Store a key-value pair in the indicated user account   |

> **Note:**
> 
> The detailed descriptions of all the APIs are available [here](https://dev.arcxp.com/api/audience-insights/)

## KV Pairs and IFX

[IFX](https://dev.arcxp.com/integrations/introduction/) is Arc XP’s platform for a publisher to upload its own custom code to for the purpose of extending the platform. When configuring a KV Pair, using Settings Admin, it is possible to indicate that, rather than storing the value, the submission of a new KV Pair (using the public API) should result in an IFX integration being invoked.

> **Note:**
> 
> The name of the IFX integration is commerce:kvp\_event

As an example, if the KV Pair indicates that the user is signed up for a newsletter, then the publisher’s logic, in the IFX integration, can call out to the publisher’s email service provider(ESP) to manage the registration. Upon positive confirmation from the ESP the IFX integration can use the Audience Insights developer API to store the response in the user’s account.

## Arc XP Audience Insights KV Pairs SDK Methods

Before utilizing these methods, see [Audience Insights: Getting Started](https://dev.arcxp.com/audience-insights/developer-docs/getting-started) for more information on setting up the SDK.

Our SDK methods serve as wrappers, making it easier for developers to interact with our APIs. The following table lists the SDK methods and the corresponding APIs they wrap.

| SDK Method              | API                                         |
| ----------------------- | ------------------------------------------- |
| submitValue(key, value) | POST /identity/public/v2/extprofile/kv      |
| listKVPairs()           | GET /identity/public/v2/extprofile/kv       |
| getKeyValue(key)        | GET /identity/public/v2/extprofile/kv/{key} |