Documentation

Acumen API

Background

When you use the Acumen product you can view a list your most recent leads on the Site Visitor Report page and even download a comma separated value (CSV) file of all of your available leads for the current month.

For a visitor to meet our definition for a lead, FullContact must have at least the lead's name and employment to make it available to the customer within the Acumen lead report.

For use cases where a more automated lead enrichment flow is needed you may use our Acumen lead enrichment API. This Acumen API is available for all of the Acumen plans, but note that only our Essentials plan is available for self serve to test as a part of a 14 day trial. If you want to test on a different plan you will need to reach out to our solutions team.

Instructions

At it's simplest, to use Acumen via API, you will call the Person.Enrich API endpoint with a PersonID provided for each website visitor:

curl -X POST \
  https://api.fullcontact.com/v3/person.enrich \
  -H 'Authorization: Bearer {Your API Key}' \
  -H 'Content-Type: application/json' \
  -d '{
"personId": "eYxWc0B-dKRxerTw_uQpxCssM_GyPaLErj0Eu3y2FrU6py1J",
"dataFilter": ["acumen_essentials_api"]
			}'

{
    "fullName": "Joe Tester",
    "ageRange": null,
    "gender": "Male",
    "location": null,
    "title": "Chief Testing Officer",
    "organization": "Acumen, Co.",
    "twitter": null,
    "linkedin": null,
    "bio": null,
    "avatar": null,
    "website": null,
    "details": {
        "name": {
            "given": "Joe",
            "family": "Tester"
        },
        "age": null,
        "gender": "Male",
        "demographics": {
            "gender": "Male"
        },
        "emails": [
            {
                "label": "work",
                "value": "[email protected]"
            }
        ],
        "phones": [
        {
        "label": "work",
        "value": "+11234567890"
        }
        ],
        "profiles": {},
        "locations": [
            {
                "country": "United States"
            }
        ],
        "employment": [
            {
                "name": "Acumen, Co.",
                "current": true,
                "title": "Chief Testing Officer"
            }
        ],
        "photos": [],
        "education": [],
        "urls": [],
        "interests": []
    },
    "updated": "2024-01-16"
}

📘

Note: dataFilter line

The "dataFilter": ["acumen_essentials_api"] line of the cURL request is only necessary if you have other Person.Enrich bundles enabled, other than Acumen. "dataFilter": ["acumen_core_api"] is the other valid option, if you have upgraded to the Core package of Acumen.

Detailed Instructions

The first step of using the API is to obtain a FullContact PersonID to send to the API in exchange for lead information.

When you place the tag on your page Javascript will run to identify leads on your site and will assign a PersonID for users recognized in the FullContact graph. The PersonID is provided in the form of a Javascript function callback and in setting a 1st party cookie called fc_pid.

While the Javascript tag executes and returns a PersonID "client side" (in the client's browser), you will want to call the Enrich API on your Server Side (from code executing on your server like: Java, Python, PHP, .NET, etc).

Example retrieving PersonID in Javascript callback

📘

Change the URL below

Change the string https://YOURSERVERSIDE.URL.COM/sendPersonId below to be the URL to your server side endpoint you have created to receive personId.

(function (w, d, s, o, f, js, fjs) {
    w['FCObject'] = o; w[o] = w[o] || function () { (w[o].q = w[o].q || []).push(arguments) };
    js = d.createElement(s), fjs = d.getElementsByTagName(s)[0];
    js.id = o; js.src = f; js.async = 1; fjs.parentNode.insertBefore(js, fjs);
}(window, document, 'script', 'fc', 'https://tags.fullcontact.com/anon/fullcontact.js'));

var config = {
 callback: function(personId){
   fetch("https://YOURSERVERSIDE.URL.COM/sendPersonId", {
     method: 'POST',
     body: JSON.stringify({"personId": personId})
   });
 }
}

fc('init',"abcdefghpDQwBqH7PrNSjT12345679", config);
</script>

Example retrieving PersonID server side from a json POST

import json
def my_view(request):
  if request.method == 'POST':
    # Assuming the request contains JSON data
    json_data = json.loads(request.body.decode('utf-8'))

    # Extract values from the JSON data
    fc_pid = json_data.get('personId')
    if fc_pid and fc_pid != 'nopid':
      get_lead_data(fc_pid)

Example retrieving PersonID server side from browser submitted cookie

The following example shows extracting the fc_pid cookie in a Python Django view.

def my_view(request):
  if request.method == 'POST':
    fc_pid = request.COOKIES.get('fc_pid')
    
    if fc_pid and fc_pid != 'nopid':
       get_lead_data(fc_pid)

Calling Enrich Endpoint on your server side.

The below example uses the FullContact Python API. If you are not using Python you can checkout our official Java SDK or Golang SDK, or refer to the FullContact API Docs on how to make a raw HTTP request.

📘

Important pieces to note:

The code below requires two things:

  1. You have an environment variable FC_API_KEY set to an API key you generated on the Platform API Keys page

  2. You are signed up for a valid Acumen plan. Line 16 below shows an example of the argument you need to pass that will check if you are on a valid plan using the dataFilter parameter.

    If you are on the 14 day trial trial or the paid Essentials plan you would use acumen_essentials_api, and if on the Core plan you would useacumen_core_api.

from fullcontact import FullContactClient
import os

client = FullContactClient(os.environ.get("FC_API_KEY"))

def get_raw_value(ar):
  work_val = list(filter(lambda e: "value" in e, ar))
  if len(work_val) > 0:
    work_val = work_val[0]["value"]
  else:
    work_val = None

  return work_val

def get_lead_data(fc_pid):
  result = client.person.enrich(personId=fc_pid, dataFilter=["acumen_core_api"])

  if 200 == result.response.status_code:
     name = result.get_name()
     print(f"name: {name['given']} {name['family']}")

     work_email = get_raw_value(result.get_emails())
     work_phone = get_raw_value(result.get_phones())
     employment = result.get_employment()[0]['name']

     print(f"employment: {employment}")
     print(f"email: {work_email}")
     print(f"phone: {work_phone}")


# a PID that has lead data attached
get_lead_data('NnWJ447TWLW7V6ydsIasJ6RVn4CQ3uLWtoz2nMwbL744S123')

# a PID that does not have lead data attached
get_lead_data('niLHgfxgTtHixKA7CjCzuQpg_eiNObD9M-tmDeFbK6RHc456')

Assuming the first PID on line 33 above had lead data and the second one did not meet the criteria of a lead the data printed to stdout would be:

name: Joe Tester
employment: Acumen Tests R Us, Inc
email: [email protected]
phone: +11234567890

Updated 7 months ago

What’s Next

Want to limit "successful" API calls to just instances where we have more than 1 or 2 fields of data? Try using our "minFields" property to the API call - details below: