Quickstart: Your First API Call

Before you start#

You need an API key: a long secret string that identifies your account, like a password. Keys are issued by your AggKnowledge account team — if you don’t have one, ask whoever set up AggKnowledge at your company. Details are in API Keys.

Step 1 — send the request#

The command below calls Person Enrich: you give it a person’s professional social media URL, and it returns everything AggKnowledge knows about that person. Paste it into a terminal (macOS and Linux ship with the curl command preinstalled), replace the key, and press Enter:

curl --request POST \
  --url https://api.aggknowledgeai.com/v2/test/person/enrich \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{ "professionalSocialMediaUrl": "https://linkedin.com/in/danielentrup/" }'

What you just sent#

• POST — the HTTP method. You’re sending data to the API (the request body below), not just fetching a page.
• The URL — reading left to right: api.aggknowledgeai.com (the API server), /v2/ (the API version), /test/ (the environment — test returns realistic mock data for free; change it to live for real data once your integration works, see Environments), and /person/enrich (the endpoint you’re calling).
• x-api-key — the header that authenticates every request. If it’s missing or wrong, the API rejects the request (see the table at the end of this page). See Authentication.
• Content-Type: application/json — tells the server the body is JSON.
• --data — the request body: a JSON object holding the input. This endpoint needs just one field to work.

Step 2 — read the response#

You’ll get back a sizable JSON document: the person’s full work history, with a complete company record embedded in every role. Trimmed to the parts that matter on a first read, it looks like this (the full field list is on the Person Enrich reference page):

{
  "data": {
    "id": 590654273,
    "firstName": "dan",
    "lastName": "entrup",
    "locationCity": "new york",
    "locationCountry": "united states",
    "workExperience": [
      {
        "title": "co-founder",
        "startDate": "2023-11",
        "endDate": null,
        "company": {
          "id": 15017574,
          "displayName": "AggKnowledge",
          "website": "aggknowledge.ai"
        }
      }
    ]
  },
  "inputParameters": {
    "linkedinUsername": "danielentrup",
    "freshness": "FRESH"
  },
  "isRetryable": true,
  "isSuccess": true,
  "metadata": null,
  "problems": {
    "linkedinProfileNotFound": false,
    "transientScrapingVendorFailure": false
  }
}

The three things to look at first:

• isSuccess — whether the API found data. A 200 status alone doesn’t guarantee it did; always check this field. When it’s false, the problems object says why. See Handle Failed Enrichments.
• data.id — the person’s stable AggKnowledge ID (personId). Store it: future lookups by ID are the fastest and most reliable. See Identifiers.
• workExperience — the employment history. A role with “endDate”: null is a current job.

The same request from code#

In a real integration the key shouldn’t be typed into commands or hardcoded in source files — read it from an environment variable (a named value the operating system passes to your program). Set one in your terminal:

export AGGK_API_KEY="YOUR_API_KEY"      # macOS / Linux
$env:AGGK_API_KEY = "YOUR_API_KEY"      # Windows PowerShell

Then make the same request in Python (needs pip install requests first):

import os
import requests

response = requests.post(
    "https://api.aggknowledgeai.com/v2/test/person/enrich",
    headers={"x-api-key": os.environ["AGGK_API_KEY"]},
    json={"professionalSocialMediaUrl": "https://linkedin.com/in/danielentrup/"},
)
result = response.json()
print(result["isSuccess"], result["data"]["firstName"])

or in JavaScript (Node.js 18 or newer — save as quickstart.mjs and run node quickstart.mjs):

const response = await fetch(
  "https://api.aggknowledgeai.com/v2/test/person/enrich",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.AGGK_API_KEY,
    },
    body: JSON.stringify({
      professionalSocialMediaUrl: "https://linkedin.com/in/danielentrup/",
    }),
  },
);
const result = await response.json();
console.log(result.isSuccess, result.data.firstName);

If something went wrong#

Errors come back as a small JSON document whose title and detail name the problem. Running the request with the YOUR_API_KEY placeholder still in place, for example, returns:

{
  "detail": "Invalid API key",
  "instance": "/v2/test/person/enrich",
  "status": 400,
  "title": "Malformed API key",
  "correlationId": "65457402-8984-4b85-a720-4c666f6f4a98"
}

Every other status — including 402 and 429 — is covered in HTTP Status Codes. Every error carries a correlationId; include it when reporting a problem to your AggKnowledge account team and we can find your exact request.

What’s next#

That’s the whole loop: authenticate with a header, send a JSON body, branch on isSuccess. Every endpoint in the API follows this same pattern — from here it’s a matter of which endpoints answer your question.