API Reference

Umbel utilizes APIs to allow you to import and add data to Umbel and export data out of Umbel. A list of all the APIs is provided below.

Import APIs

API Name Action API Endpoint Description
Import Profile Data (Internal) POST /{property_id}/import-data Upload and insert one or more profiles and associate attributes.
Import Job (Internal) POST /{property_id}/imports/{import_id}/jobs Import process used to create grouping of import batches associated with a single import job.
Import POST /{property_id}/imports Create a new import mapping definition for a tabular data set.
Import Definition GET /{property_id}/imports/{import_id} Retrieve details about an import definition.
Import Job ID GET /{property_id}/imports/{import_id}/jobs Retrieve a collection of references to and dates of recent executions of the defined import definition.
Import Job Status GET /{property_id}/imports/{import_id}/jobs/{job_id} Retrieve status of an import job and information about date and time of execution of the import job.
Import Job Errors GET /{property_id}/imports/{import_id}/jobs/{job_id}/errors Retrieve details of failed rows from an import input data set.

How to Set Up an Import in Umbel

One of the more common uses of the Umbel APIs is importing data into the Umbel platform. In order to do this, the steps you would take are as follows:

  1. Create an Import Definition
  2. Create an Import Job associated to the Import Definition
  3. Import one or more batches of profile data for the Import Job.

NOTE: Steps (2),(3) can be repeated for another Import of the same format (and therefore leverage the same Import Definition).

The imports endpoint provides a mechanism to define processing rules for the ingestion of bulk, tabular data.
You’ll then be able to upload your data in files via SFTP and use this API to check on the status of the processing of each individual file.

When you create an Import, a corresponding directory for that import on Umbel’s SFTP server definition will be created automatically for you. You will use the directory to upload files, and an import process will automatically be kicked off. The import processor supports comma, tab, and pipe-delimited files. The default is comma separated, and you must specify in your definition if you are using one of the others.

When performing an import, you will have the ability to provide the attribute_source, which can be either stated or third_party. Umbel utilizes a hierarchy of trusted data sources when surfacing data in the product. The full data hierarchy is as follows: (1) Stated Data, (2) LinkedIn, (3) Facebook, (4) Third-Party, (5) Rapleaf, (6) Acxiom, (7) Gigya, so please note that stated data source supersede third-party data sources.

How to Create an Import Definition

The sample below shows you how to create an import definition for a CSV file.

curl --request POST \
     --url 'https://api.umbel.com/v1/<property>/imports' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json' \
     --data '{"name":"basic-import-def","mapping_fields":{"required_fields":["email"],"field_maps":[{"sources":[{"type":"source_field","name":"Email"}],"transformations":[{"name":"strip"},{"name":"lower"}],"target_field":"email"},{"sources":[{"type":"source_field","name":"First Name"}],"transformations":[{"name":"strip"}],"target_field":"first_name"},{"sources":[{"type":"source_field","name":"Last Name"}],"transformations":[{"name":"strip"}],"target_field":"last_name"},{"sources":[{"type":"source_field","name":"Id"}],"target_field":"unique_id"}]}}'
{
  "id":1,
  "name": "basic-import-def",
  "mapping_fields": {
    "required_fields": ["email"],
    "field_maps": [
      {
        "sources": [{"type": "source_field", "name": "Email"}],
        "transformations": [{"name": "strip"}, {"name": "lower"}],
        "target_field": "email"
      },
      {
        "sources":[{"type": "source_field", "name": "First Name"}],
        "transformations": [{"name":"strip"}],
        "target_field": "first_name"
      },
      {
        "sources": [{"type": "source_field", "name": "Last Name"}],
        "transformations": [{"name": "strip"}],
        "target_field": "last_name"
      },
      {
        "sources": [{"type": "source_field", "name": "Full Name"}],
        "transformations": [{"name": "strip"}],
        "target_field": "full_name"
      },
      {
        "sources":[{"type": "source_field", "name": "Id"}],
        "target_field": "unique_id"}]
      },
  "action": "import_csv_generic",
  "created": "2016-06-01T20:03:11.763108Z",
  "test_mode": false,
  "file_match_rule": null,
  "property": 2
 }

How to Create an Import Job Record

Once the import definition is created, we can send batches of data associated to this Import Job. The sample below shows you how to set up an import job.

NOTE: When we use the Umbel data pipeline code base, it automatically creates the Import Job record. When an Import is being generated outside of the Umbel code base, an Import Job record is required.

curl --request POST \
     --url 'https://api.umbel.com/v1/<property>/imports/1/jobs' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json' \
     --data '{"name":"import-job-05"}'
{
  "id": 5,
  "name": "import-job-05",
  "property": 2,
  "created": "2016-06-01T22:53:15.093926Z",
  "file_path": null,
  "counts": {
    "status": "unknown",
    "unserializable": 0,
    "serialized": 0,
    "completed": 0,
    "processing": 0,
    "failed": 0,
    "ingested": 0
  },
  "import_definition": 1
}

How to Send Multiple Records for an Import Job

Following the example provided in the How to Create an Import Job Record section, the sample below shows you how to import multiple records (or a batch) in a single request. Note the skip_appends value can be either true or false. Setting this value to true will skip over inputs considered to be a part of your append count. Setting this value to false will append those attributes. If you have a third_party data source that contains values that would otherwise be appended by Acxiom or other, you may want to set this value to false, since third_party data is higher than Acxiom in the hierarchy of trusted data sources.

curl --request POST \
     --url 'http://local.umbel.com:8001/api/v1/2/import-data' \
     --header 'Authorization: Bearer 7e523904dba9ba9b667d80acbeb856fa0ab11deb' \
     --header 'Content-Type: application/json' \
     --data @import-data-05-01.json

{
  "name": "import-job-05-batch-01",
  "import_job": 5,
  "skip_appends": true,
  "records": [
    {
      "first_name": "Jane",
      "last_name": "Smith",
      "full_name": "Jane Smith",
      "birthday": "1975-01-07",
      "gender": "male",
      "email": "jane-smith@example.com",
      "unique_id": "CUST-2001",
      "has_children": "Yes",
      "tags": [
        {"datetime": "2016-06-02 11:45:00", "tag": ["Cycling"]},
        {"datetime": "2016-06-02 11:45:00", "tag": ["Chess"]}]},
      ],
      "source": "Source 1,Source 2,Source 3"
    },
    {
      "first_name": "Jane",
      "last_name": "Smith",
      "full_name": "Jane Smith",
      "birthday": "1982-09-13",
      "gender": "female",
      "email": "jane@smith.com",
      "unique_id": "CUST-2002",
      "has_children": "No",
      "tags": [
        {"datetime": "2016-06-01 18:12:00", "tag": ["Reading"]},
        {"datetime": "2016-06-01 18:12:00", "tag": ["Archery"]}
      ],
      "source": "Source 1,Source 2,Source 3"
    }
  ]
}
{
  "batch_job_uuid":"a09cab88-28dd-11e6-8f8e-0242ac11000d",
  "import_job":
  {
    "id":5,
    "name":"import-job-05",
    "property":2,
    "created":"2016-06-02T15:57:11Z",
    "file_path":null,
    "counts":
    {
      "status":"ingestion-complete",
      "unserializable":0,
      "serialized":2,
      "completed":0,
      "processing":2,
      "failed":0,
      "ingested":2
    },
    "import_definition":1
  },
  "name":"import-job-01-batch-01",
  "skip_appends":true
}

How to Check the Status of Your Import Job

The sample below shows you how to check the status of an import job.

curl --request GET \
     --url 'https://api.umbel.com/v1/<property>/imports/1/jobs/5' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json'

{
  "id":5,
  "name":"import-job-05",
  "property":2,
  "created":"2016-06-02T17:01:21Z",
  "file_path":null,
  "counts":
  {
    "status":"ingestion-complete",
    "unserializable":0,
    "serialized":2,
    "completed":0,
    "processing":2,
    "failed":0,
    "ingested":2
  },
  "import_definition":1
}

How to Import “Extra” Profile Data

The Import API allows you to import additional data against a profile in the form of simple name-value pairs without requiring Umbel to create new columns in the platform. This “extra” profile data can be phone numbers, household ID’s, account numbers, etc., which is data that is not previously defined in Umbel.

The sample below shows you how to import “extra” profile data with the Import API:

curl --request POST \
     --url 'https://api.umbel.com/v1/<property>/profiles' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json' \
     --data '{"extra_data": {"household_email": "jane-smith@example.com", "customer_id": 1234567890}}
{
  "profile_uuid": "d8d5d608-2786-11e6-80bb-0242ac11000d"
}

Adding the key extra_data to the profile json will save the extra data to the profile. If you update a profile with new extra data it will be merged with the existing extra data.

Exporting Profile Extra Data.

Extra data does not appear in the Umbel application as a filter option. Profile extra data (stored and treated as attributes) is available when profiles are exported with all profile information. Emails that are imported as profile extra data are not included in the “Email Only” exports.

How to Import Facebook Brand Affinities (Facebook Likes)

The Import API allows you to directly import Facebook Brand Affinities (Facebook Likes) for a specific Facebook object. For every Facebook object (Facebook page), there is a unique Facebook ID assigned. By providing the Facebook ID, Facebook category, and Facebook page Name, you can import Facebook likes into Umbel.

The sample below shows you how to import Facebook Likes:

curl --request POST \
     --url 'https://api.umbel.com/v1/<property>/profiles' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json' \
     --data '"facebook_likes": [{"id": "123456789", "category": "sports","name": "Chicago White Sox"}]}
{
  "profile_uuid": "d8d5d608-2786-11e6-80bb-0242ac11000d"
}

Export APIs

An Export in Umbel is a .csv file that gets generated when the user exports our profile and attribute information. Exports are generated in the Umbel App when a user manually walks through the export steps in order to kick off an export job. The .csv file that gets generated is then available from the Downloads page in the Umbel App.

We use the Export API in order to support asynchronous downloads. The Export upon completion is configured to call a webhook or send an email indicating the location of the export file. This file is typically stored on S3 and available to be downloaded. The GET Export API is not going to return profiles, but rather a status and (upon success) a location of the final export file. There is also the concept of an “Export Definition”, but it’s really just the Export object where the query to be run/exported is stored.

API Name Action API Endpoint Description
Export Definition POST /{property_id}/exports Create a new export definition.
Export ID GET /{property_id}/exports/{export_id} Retrieve the export definition based on the export ID.
Export Job Status GET /{property_id}/exports/{export_id}/jobs Retrieve the status of executions of export jobs based on the export definition.
Export Job Details GET /{property_id}/exports/{export_id}/jobs/{job_id} Retrieve details of a specific export job.

Common API Actions

There are several ways to interact with your Umbel data via the APIs, including searching for data based on specific criteria or creating new profiles directly. The samples provided below will show you how to retrieve and create data based on various inputs.

How to Create a New Profile

The sample below shows you how to create a new profile in Umbel:

curl --request POST \
     --url 'https://api.umbel.com/v1/<property>/profiles' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json' \
     --data '{"first_name": "Jane", "last_name": "Smith", "full_name": "Jane Smith", "unique_id": "CUST-1234", "age": 35, "birthday": "1980-11-27", "gender": "male", "email": "jane-smith@example.com", "address": { "street": "1234 River Rd", "city": "Bonville", "state": "TX", "postal_code": "76543", "country": "USA" }}'
{
  "profile_uuid": "d8d5d608-2786-11e6-80bb-0242ac11000d"
}

How to Search for a Profile by Email

The sample below shows you how to search for a profile based on their email address.

curl --request GET \
     --url 'https://api.umbel.com/v1/<property>/profile?email=jane-smith@example.com' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json'
{
  "profile": {
    "last_name":"Smith",
    "linkedin_id":null,
    "street":"1234 River Rd",
    "education_level":null,
    "home_owner_status":null,
    "ethnicity":null,
    "city":"Bonville",
    "first_name":"Jane",
    "full_name":"Jane Smith",
    "zipcode":"76543",
    "state":"TX",
    "facebook_id":null,
    "home_value":null,
    "has_children":null,
    "phone_number":null,
    "street2":null,
    "birthday":"1980-11-27",
    "gender":"male",
    "marital_status":null,
    "email":"jane-smith@example.com",
    "household_income":null,
    "profile_uuid":"d8d5d608-2786-11e6-80bb-0242ac11000d",
    "unique_id":"CUST-1234",
  }
}

How to Search for Profile Segments by Email

The sample below shows you how to search for profile segments based on their email address.

curl --request GET \
     --url 'https://api.umbel.com/v1/<property>/profile_segments?email=jane-smith@example.com' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json'
{
    "Brand": {
        "count": 3,
        "segments": [
            "Wasabi peas"
        ],
        "subcategories": {
            "Lifestyle": {
                "count": 2,
                "segments": [],
                "subcategories": {
                    "Causes": {
                        "count": 2,
                        "segments": [
                            "Developers Doing Development"
                        ],
                        "subcategories": {
                            "Non-Profit Organization": {
                                "count": 1,
                                "segments": [
                                    "WUOG 90.5 FM"
                                ],
                                "subcategories": {}
                            }
                        }
                    }
                }
            }
        }
    }
}

How to Get All Profiles for a Segment

The sample below shows you how to get all the profile information for a profile within a segment.

curl --request GET \
     --url 'https://api.umbel.com/v2/properties/<property>/segments/1342/profiles' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json'
{
  "paging":
  {
    "next_page": "https://api.umbel.com/v2/properties/<property>/segments/1342/profiles?page=2",
    "previous_page":null
  },
  "profiles":
  [
    {
      "last_name":"Smith",
      "linkedin_id":null,
      "street":"789 River Rd",
      "education_level":null,
      "home_owner_status":null,
      "ethnicity":null,
      "city":"Bonteville",
      "first_name":"Jane",
      "full_name":"Jane Smith",
      "zipcode":"76543",
      "state":"TX",
      "facebook_id":null,
      "home_value":null,
      "has_children":null,
      "phone_number":null,
      "street2":null,
      "birthday":"1980-11-27",
      "gender":"male",
      "marital_status":null,
      "email":"jane-smith@example.com",
      "household_income":null,
      "profile_uuid":"17065028-280f-11e6-8f8e-0242ac11000d",
      "unique_id":"CUST-1234"
    }
  ]
}

How to Track Added and Removed Profiles in a Segment Using Timelines and Moments

A “moment” is a segment containing all profiles that existed in a given segment at a given time. A “timeline” is a sequence of such moments over time for the same segment. You can create multiple timelines for the same segment by providing different timeline names, but timeline names must be unique within a property.

Start by creating a timeline for the tile you want to track, which will automatically create the first moment in the timeline. A sample on how to do this is shown below:

curl --request POST \
     --url 'https://api.umbel.com/v2/properties/<property>/timelines' \
     --data '{"reference_tile": 1, "comments": "blah blah blah", "name": "mailchimp"}' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json'
201 Created
{
  "created_by": {
    "email": "jane-smith@example.com",
    "first_name": "Jane",
    "id": 843,
    "last_name": "Smith"
  },
  "id": 1,
  "name": "mailchimp",
  "created_date": "2016-08-31 14:29:13.747393",
  "reference_tile": 1,
  "moments": [
    {
      "comments": "None",
      "id": 1,
      "links": [
        "profiles": "https://api.umbel.com/v2/properties/<property>/segments/57897090/profiles",
       	"profiles_added": null,
        "profiles_removed": null
      ]
      "name": "mailchimp - 2016-08-31 14:29:13.747393",
    }
  ]
}

The “links” section in the moment object here contains up to three links, each of which points to a URL in the Segments API: “profiles”, which will return all profiles in the segment at this moment, “profiles_added”, which will return all profiles that have been added to the segment since the last moment in the timeline, and “profiles_removed”, which will return all profiles that have been removed from the segment since the last moment in the timeline. Since this is the first moment in the timeline, “profiles_added” and “profiles_removed” are null.

To create a second moment in this timeline, you can POST to the nested ‘moments’ resource within the timeline resource.

Notice that the “profiles_added” and “profiles_removed” links are now returned. Attempting to create another moment within one hour will return a 429 response (rate limited). A sample of how to create the second moment is shown below.

curl --request POST \
     --url 'https://api.umbel.com/v2/properties/<property>/timelines/1/moments' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json'
201 Created
{
  "comments": "",
  "created_by": {
    "email": "jane-smith@example.com",
    "first_name": "Jane",
    "id": 843,
    "last_name": "Smith"
  },
  "created_date": "2016-08-31 14:40:13.747393",

  "id": 2,
  "links": {
    "profiles": "https://api.umbel.com/v2/properties/<property>/57897099/profiles",
    "profiles_added": "https://api.umbel.com/v2/properties/<property>/57897099/profiles?not=57897090",
    "profiles_removed": "https://api.umbel.com/v2/properties/<property>/57897090/profiles?not=57897099"
  }
}

The final action you can do is check your created timelines by following the sample below:

curl --request GET \
     --url 'https://api.umbel.com/v2/properties/<property>/timelines' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'Content-Type: application/json'

200 OK
[
  {
    "created_by": {
    "email": "jane-smith@example.com",
    "first_name": "Jane",
    "id": 843,
    "last_name": "Smith"
  },
  "created_date": "2016-09-21T15:58:19.015140Z",
  "id": 1,
  "moments": [
    {
      "comments": "second moment",
      "created_by": {
        "email": "jane-smith@example.com",
        "first_name": "Jane",
        "id": 843,
        "last_name": "Smith"
      },
      "created_date": "2016-09-21T15:58:45.753147Z",
      "id": 15,
      "links": {
        "profiles": "https://api.umbel.com/v2/properties/<property>/57897099/profiles",
        "profiles_added": "https://api.umbel.com/v2/properties/<property>/57897099/profiles?not=57897090",
        "profiles_removed": "https://api.umbel.com/v2/properties/<property>/57897090/profiles?not=57897099"
      },
      "name": "Test Activator Moment - 2016-09-21 15:58:45"
    },
    {
      "comments": "testing",
      "created_by": {
        "email": "jane-smith@example.com",
        "first_name": "Jane",
        "id": 843,
        "last_name": "Smith"
      },
      "created_date": "2016-09-21T13:58:45.579470Z",
      "id": 14,
      "links": {
      "profiles": "https://api.umbel.com/v2/properties/<property>/57897090/profiles",
      "profiles_added": null,
      "profiles_removed": null
    },
    "name": "Test Activator Moment - 2016-09-21 13:58:45"
  }
],
"name": "Test Activator Moment",

How to Create an Export Job

The following describes how to set up an export job. The export job allows you to pull profile information for a specific segment within a property and can be set to run once or on a recurring-basis.

The definitions of the input parameters are as follows:

Field Name Field Type Description
id (string, optional) This is the unique ID for this export definition assigned and returned by the platform once it’s created.
segment (Array integer, optional) An array of segment ID’s to be included in this export. All profiles in each segment will be included in the data set returned.
collection (Array integer, optional) An array of collection ID’s to included in this export. All profiles in each segment contained in this collection will be included in the data set returned.
field_set (string, optional) Allowed values are ‘all’, ‘email’, or, ‘custom’. If ‘all’ is selected every profile attribute will be returned. For ‘email’, only the email address will be included. For ‘custom’ you must include a custom_result_format where you can select which properties to include and what they should be named in the exported dataset. = ‘email’, ‘all’, ‘custom’.
data_format (string, optional) Specify whether your exported dataset should be in a comma separated or tab delimited format. = ‘csv’, ‘txt’.
scope (string, optional)
schedule (object, optional) See below.
notification_email (string, optional)
webhook_url (string, optional)
start_date (string, optional) Start of date range to export. Format YYYY-MM-DD, e.g. “2015-09-08”.
end_date (string, optional) Start of date range to export. Format YYYY-MM-DD, e.g. “2015-09-09”.
custom_result_format (Array object, optional) An array describing a custom set of profile data to be exported. ‘umbel_field_name’ specifies the Umbel profile attribute to include in the export. ‘destination_field_name’ specifies the name of the column in the result data set.
pgp_public_key (string, optional) ASCII-encoded PGP public key used to encrypt the file before sending it to its destination. When included, the export’s filename will end in .pgp.
tile_types (Array string, optional) A list of ‘tile type’ segments to export. All segments of the given types (at the time of export creation) will be added to the export’s list of segments automatically.
destination_credentials (object, optional) The credentials used for sending the export to an SFTP destination. It will include the public key that will need to be added to the SFTP server’s authorized keys file.

Sample Input:

{
  "id": "string",
  "segment": [
    0
  ],
  "collection": [
    0
  ],
  "field_set": "email",
  "data_format": "csv",
  "scope": "full",
  "schedule": {
    "minute": "string",
    "hour": "string",
    "day_of_month": "string",
    "month": "string",
    "day_of_week": "string"
  },
  "notification_email": "string",
  "webhook_url": "string",
  "start_date": "string",
  "end_date": "string",
  "custom_result_format": [
    {
      "umbel_field_name": "string",
      "destination_field_name": "string"
    }
  ],
  "pgp_public_key": "string",
  "tile_types": [
    "CATEGORY"
  ],
  "destination_credentials": {
    "public_key": "string",
    "domain": "string",
    "client_id": "string"
  }
}