Record Matching - Campaign records

Campaign Record Matching Behavior

Campaign is a required field for Transactions and many other data types in Kindful. In order to prevent the creation of duplicate Campaign records when you import data into Kindful, Kindful's API offers great flexibility in how you want to specify a Campaign record in an import.

The match_by hash allows you to specify whether you want to refer to a Campaign's Kindful ID, your (External) ID, or Kindful's Campaign Name when importing records into Kindful.

When you import records into Kindful, you optionally specify:

  • campaign_id
  • campaign_name

Kindful interprets the meaning of these fields based upon the campaign match_by value you provide.

See detail below

Campaign match_by Type Description of Behavior When to use this match_by type Default campaign_id means campaign_name means
external_id Will attempt to associate the record to the correct Campaign in Kindful based upon the record's provided campaign_id field and your integration's (external) campaign ID which is stored in Kindful.

If an exact match is not found, a new Campaign will be created in Kindful.

Note: This does NOT match to Kindful's Campaign ID.		 You should only attempt to use this Match By Type if you are sending your Campaign ID to Kindful (via the campaign_id field).

Matching by external_id is useful because you can prevent duplicate campaigns being created (if a campaign has been renamed in either your third party system or in Kindful after it has been created).		 yes, this is the default match_by type for Campaigns. Your (External) Campaign ID Kindful's Campaign Name
id Will attempt to associate the record to an existing Campaign in Kindful based upon the record's provided campaign_id field and Kindful's campaign ID.

If an exact match is not found, a new Campaign will be created in Kindful.		 Use this match_by type if you have queried Kindful for existing Kindful Campaigns, and you "for sure" want to add records to update an existing Kindful Campaign no, you will need to specify if you want this behavior. Kindful's Campaign ID Kindful's Campaign Name
name Will attempt to associate the record to the correct Campaign in Kindful based upon the record's provided campaign_name field and the Campaign Name stored in Kindful.

If an exact match is not found, a new Campaign will be created in Kindful.		 Matching by name is useful because you can potentially reduce duplicate campaigns in Kindful of campaigns that have been created in Kindful or other systems integrated with Kindful via the API. no, you will need to specify if you want this behavior. Your (External) Campaign ID Kindful's Campaign Name

Example

In the examples below, we are appending to an existing campaign: Hogwarts Fundraiser 2015.

The match_by name request is using the name (Hogwarts Fundraiser 2015) of the campaign. The match_by ID request is using the ID for Hogwarts Fundraiser 2015 which is 85010.

Default Behavior

COPY 
{
  "data_format": "contact_with_transaction",
  "action_type": "create",
  "data_type": "json",

  "data": [
    {
      "id":"c123",
      "first_name": "Harry", 
      "last_name": "Potter", 
      "transaction_id": "t456",
      "amount_in_cents": "5000",
      "transaction_time": "2015-10-13 18:56:12 UTC",
      "campaign_id": "85010", //NOTE: 85010 is *your* application's External Campaign ID, NOT Kindful's Campaign ID.
      "campaign_name": "Hogwarts Fundraiser 2015"
    } 
  ]
}

In this case campaign match_by is not specified, so the default behavior of campaign match_by = external_id is assumed. If this integration has already passed in a Campaign with an (external) id "85010" to Kindful, the transaction t456 will be added to the Campaign with external id "85010".

However, if there is no Campaign with external id "85010" in Kindful yet, then a new campaign will be created with id 85010 and name "Hogwarts Fundraiser 2015"


Append to Exisiting Campaigns using name

COPY 
{
  "data_format": "contact_with_transaction",
  "action_type": "create",
  "data_type": "json",
  "match_by": {
    "campaign": "name"
  },
  "data": [
    {
      "id":"c123",
      "first_name": "Harry", 
      "last_name": "Potter", 
      "transaction_id": "t456",
      "amount_in_cents": "5000",
      "transaction_time": "2015-10-13 18:56:12 UTC",
      "campaign_name": "Hogwarts Fundraiser 2015"
    } 
  ]
}

In this case campaign match_by is name so if there is already a Campaign named "Hogwarts Fundraiser 2015" in Kindful, the transaction t456 will be added to the "Hogwarts Fundraiser 2015" Campaign.

However, if there is no Campaign named "Hogwarts Fundraiser 2015" in Kindful yet, then a new campaign will be created by that name.


Append to Exisiting Campaigns using ID

COPY 
{
  "data_format": "contact_with_transaction",
  "action_type": "create",
  "data_type": "json",
  "match_by": {
    "campaign": "id"
  },
  "data": [
    {
      "id":"c123",
      "first_name": "Harry", 
      "last_name": "Potter", 
      "transaction_id": "t456",
      "amount_in_cents": "5000",
      "transaction_time": "2015-10-13 18:56:12 UTC",
      "campaign_id": "85010", //NOTE: 85010 is Kindful's Campaign ID.
      "campaign_name": "Hogwarts Fundraiser 2015"
    } 
  ]
}

In this case campaign match_by is id, so if this integration has already passed in a Campaign with id "85010" to Kindful, the transaction t456 will be added to the Campaign with id "85010".

However, if there is no Campaign with id "85010" in Kindful yet, then a new campaign will be created with id 85010 and name "Hogwarts Fundraiser 2015"


For more information about Record Matching, please see Record Matching Overview