Custom Field mapping

Understanding API Fields

API integrations present data in diverse formats, and Apideck plays an important role in standardizing this data into a unified format. This standardization allows for the seamless creation of integrations across various SaaS products.

The premise of a Unified API is that it allows you to make a single request to an Apideck endpoint and receive a response that is ‘consistent’ across all of the downstream APIs.

This is achieved by mapping the properties of the downstream responses to a common set of properties in the Unify Model. This means the Unify response will consistently return the same set of properties, regardless of the specific downstream API.

On one hand, this makes it easy to consume the Unify response as you can expect the properties to be present. On the other hand, it means that the Unify response will only contain the available properties common across all downstream APIs.

There are times when the properties of the downstream response do not map directly to the properties of a Unify Model. There are also times when the data you need is defined by your customers as a ‘custom field’, and only they know the name of that property.

This is where the “field mapping” concept comes in.

Field Mapping is the process of defining how a property from an integration response should be mapped to the Unify response.

In the chapters below we will explain how this works in more detail.

Response fields

Integrations have specific field names/keys in their responses, each using unique naming conventions, structures, and casing. They even have different data formats JSON, XML, CSV, ...

For instance, when we compare a CRM lead across a couple of CRM SaaS tools, the following response values are all the same, but have different field names, structures and even different date formats.

A SalesForce example response:


{
  "Id": "123",
  "LastName": "Doe",
  "FirstName": "Jane",
  "T_shirt_Size__c": "Medium",
  "LastReferencedDate": "2024-01-12T10:46:34.000+0000",
  "LeadSource": "Trade Show",
  "CreatedDate": "2019-07-09T19:35:03.000+0000"
}

A Hubspot example response:


{
  "id": "123",
  "properties": {
    "lastname": "Doe",
    "firstname": "Jane",
    "t_shirt_size": "Small",
    "lifecyclestage": "lead",
    "hs_analytics_first_timestamp": "1601666897728",
    "hs_analytics_first_visit_timestamp": "1601666897728",
  },
  "createdAt": "2019-07-09T19:35:03.000+0000"
}

A Pipedrive example response:


{
  "data": {
    "id": "d2b4f0b0-6219-11eb-84bd-4b223d902a50",
    "first_name": "First",
    "last_name": "Last",
    "c692e0f0cc9f675d5b6219c3e16": "Small",
    "won_deals_count": 0,
    "related_won_deals_count": 0,
    "add_time": "2020-10-04 09:58:26"
  }
}

Looking at the above responses, we can detect 3 types of fields:

Standard fields: Fields that are available in all integrations, although with different names, casing, data formats, ... , like
```
id
```
,
```
first_name
```
,
```
last_name
```
,
```
created_at
```
, ...
Integration fields: Fields that are specific per integrations and part of their data model, like
```
hs_analytics_first_timestamp
```
,
```
LastReferencedDate
```
, ...
Custom fields: Fields that are created by the user in the integration, like
```
T_shirt_Size__c
```
,
```
t_shirt_size
```
,
```
c692e0f0cc9f675d5b6219c3e16
```
, ...

Custom fields

The term "custom fields" is used to describe fields that are created by the user in the integration. Giving the users the ability to add custom fields next to the standard fields and store additional information within the integration.

These custom fields are returned as part of the response. Depending on the integration these custom fields can be nested in a custom object or be part of the root object.

An example for SalesForce, where custom fields are part of the root object, typically ending with

__c


{
  "Id": "123",
  "LastName": "Doe",
  "FirstName": "Jane",
  "T_shirt_Size__c": "Medium",
  "Assigned_CSM__c": "Tom S.",
  "Lifecycle_Stage__c": "Lead",
  "CreatedDate": "2019-07-09T19:35:03.000+0000"
}

An example from Hubspot, where custom fields are nested in the

properties

object, as any other field:


{
  "id": "123",
  "properties": {
    "lastname": "Doe",
    "firstname": "Jane",
    "t_shirt_size": "Small",
    "assigned_csm": "Kristof W.",
    "lifecyclestage": "lead"
  },
  "createdAt": "2019-07-09T19:35:03.000+0000"
}

An example from Pipedrive, where custom fields are nested in the

data

object and have a unique key:


{
  "data": {
    "id": "d2b4f0b0-6219-11eb-84bd-4b223d902a50",
    "first_name": "First",
    "last_name": "Last",
    "add_time": "2020-10-04 09:58:26",
    "c692e0f0cc9f675d5b6219c3e16": "Lead",
    "c692e0f58789dfebb3adba15721": "Small",
    "e24805787eef64b08aafb6fa3d8": "Kristof W."
  }
}

An example from a CRM integration that has custom fields listed under

CustomFields

as an array of key/value pairs:


{
   "Id": "8750",
   "FirstName": "First",
   "LastName": "Last",
   "CustomFields": [
      {
         "key": "TShirtSize",
         "value": "Small"
      },
      {
         "key": "AssignedCSM",
         "value": "Tom S."
      }
   ]
}

Looking at the above responses, it is clear that the custom fields are not standardized across integrations.

Unified models

Looking at the above responses, each SaaS API has a different set of fields, with different names, casing, data formats, ... so when building an integration, you need to know the specific fields for each integration.

This is where Apideck comes in, Apideck applies the concept of the Unified Model.

This is a standardized set of fields that is consistently available across all integrations within a certain category (e.g. CRM, Accounting, HRIS, ...). The model is an abstraction of the available fields per resource (e.g. lead, contact, employee, folders, files, ...), into a set of standard fields.

The model provides a consistent way to interact with the data across all integrations, when it comes to naming, casing, data formats, ...

The Apideck model is designed to be consistent and support a wide variety of use cases like registering a new lead, updating a contact, creating a new employee, ...

Mapping fields

To be able to return the data in the unified model, the fields from the integration response need to be mapped to the unified model.

The Unify API handles the mapping of the available fields for each integration to the unified model.

After a request is made to the Unify API, the request is validated and then transformed into a request with the necessary parameters for the specific integration. The response from the integration is then transformed into a common format and returned to the client.

The returned response contains a harmonized result with a common format, simplifying the integration process.

Field mapping feature

As shown above, not all SaaS APIs are created equal. There are times when the properties of the integration response do not map directly to the properties of a Unify Model. There are also times when the data you need is defined by your customers as a ‘custom field’, and only they know the name of that property.

The “field mapping” feature within Unify API allows to extend Apideck Unify models with additional custom fields/properties from integrations that will be included in the Unify response

Let's take the Hubspot

lifecyclestage

property, which is Hubspot specific property and not part of the Unify model.

By mapping the field within Apideck, the

lifecyclestage

property will be included in the Unify response for all consumers that connect.

Field mapping types

There are 2 types of field mapping:

Property mapping: will search for the source field in the raw response of the integration
Custom field mapping: will search for the source field in the Unify response, in the list of
```
custom_fields
```
.

Property mapping

Property mapping is used to map a field from the integration response to a field in the Unify response. This property is typically not part of the Unify model, but is available in the integration response.

Hubspot response with all Hubspot properties:


{
    "id": "551",
    "properties": {
        "assigned_csm": "Kristof W.",
        "associatedcompanyid": "4562962674",
        "createdate": "2020-10-02T14:48:17.728Z",
        "custom_field": "",
        "email": "e.earhart@noemail.com",
        "firstname": "Emilia",
        "hs_object_id": "551",
        "hubspot_owner_id": null,
        "jobtitle": "Pilot",
        "known_via": "Apideck",
        "lastmodifieddate": "2024-01-12T10:42:21.467Z",
        "lastname": "Earhart",
        "lifecyclestage": "lead",
        "phone": "+32470123323",
        "website": "https://lead.com"
    },
    "createdAt": "2020-10-02T14:48:17.728Z",
    "updatedAt": "2024-01-12T10:42:21.467Z",
    "archived": false
}

We are interested in the

lifecyclestage

property, which is not part of the Unify model, but is available in the Hubspot response.

Let's start by defining a new field "lifecycle_stage" on the Unify model.

Provide a unique "Key" and a descriptive "Name." Optionally, add a brief "Description." The "key" will be utilized in the API response.

The next step, is to configure the mapping for the "lifecycle_stage" field for the Hubspot integration.

Custom Field mapping - Select integration

Since "lifecycle_stage" is a property of the Hubspot response, we need to configure a "property mapping".

Custom Field mapping - Select mapping type

Browse through the available Hubspot fields and select the "lifecyclestage" property.

Custom Field mapping - Select matching response key from the integration

Press Save to store the mapping for Hubspot.

Custom Field mapping - Save the configured mapping

The mapping is now configured for the Hubspot integration, and will be included in the Unify response.

Result: Unify response with

custom_mappings

property, containing the field mapping for the "lifecycle_stage" property.


{
    "status_code": 200,
    "status": "OK",
    "service": "hubspot",
    "resource": "contacts",
    "operation": "one",
    "data": {
        "id": "551",
        "name": "Emilia Earhart",
        "first_name": "Emilia",
        "last_name": "Earhart",
        "title": "Pilot",
        "updated_at": "2024-01-12T10:42:21.467Z",
        "created_at": "2020-10-02T14:48:17.728Z",
        "custom_mappings": {
            "lifecycle_stage": "lead"
        }
    }
}

For more details on how to configure a Property mapping, check out the Field Mapping guide.

Custom field mapping

In the Unify response, there is a list of

custom_fields

, which is a list of key/value pairs, where the key is the

id

of the custom field, and the value is the value of the custom field.

Let's take the example of the Unify response for Hubspot. Apideck has already mapped all the custom fields for Hubspot in the

custom_fields

property. The key/values pairs for the

custom_fields

are unique per consumer, since each consumer can configure their custom fields in their SaaS tool. Resulting in unique

id

values for the custom fields.

Unify response with mapped

custom_fields


{
    "status_code": 200,
    "status": "OK",
    "service": "hubspot",
    "resource": "contacts",
    "operation": "one",
    "data": {
        "id": "551",
        "name": "Emilia Earhart",
        "first_name": "Emilia",
        "last_name": "Earhart",
        "title": "Pilot",
        "custom_fields": [
            {
                "id": "assigned_csm",
                "value": "Kristof W."
            },
            {
                "id": "t_shirt_size",
                "value": "Small"
            }
        ],
        "updated_at": "2024-01-12T10:42:21.467Z",
        "created_at": "2020-10-02T14:48:17.728Z"
    }
}

By defining a new field "T-shirt Size" you are extending the Unify model.

Custom Field mapping - Add a new field to Unify

It will allow you to ask the consumer to configure the mapping for the correct custom field for their "T-shirt Size" field in Vault.

Custom Field mapping - Map custom field in Vault

This will result in the value of the "T-shirt Size" custom field that will be included in the Unify response.

Unify response with

custom_mappings

property, containing the field mapping for "T-shirt Size".


{
    "status_code": 200,
    "status": "OK",
    "service": "hubspot",
    "resource": "contacts",
    "operation": "one",
    "data": {
        "id": "551",
        "name": "Emilia Earhart",
        "first_name": "Emilia",
        "last_name": "Earhart",
        "title": "Pilot",
        "custom_fields": [
            {
                "id": "assigned_csm",
                "value": "Kristof W."
            },
            {
                "id": "t_shirt_size",
                "value": "Small"
            }
        ],
        "updated_at": "2024-01-12T10:42:21.467Z",
        "created_at": "2020-10-02T14:48:17.728Z",
        "custom_mappings": {
            "lifecycle_stage": "lead",
            "tshirt_size": "Small"
        }
    }
}

You can repeat the mapping process for all integrations, resulting in having the "T-shirt Size" field available in the Unify response for all integrations.

For more details on how to configure a Custom field mappings, check out the Custom Mapping guide.