AggKnowledge API

Person Synchronous

Endpointhttps://api.aggknowledgeai.com

V2 synchronous APIs to fetch person information

Enrich

POST

https://api.aggknowledgeai.com

/v2/{environment}/person/enrich

Accepts a person enrichment request and returns enriched person data (Tier 1)

Enrich › path Parameters

environment

string · enum · required

Environment (live or test)

Enum values:

live

test

Enrich › Headers

x-api-key

string · required

API key for authentication

Enrich › Request Body

object

Optional metadata to associate with the request. Will be returned in the response.

pdlId

string

The person's PDL ID.

personId

integer · int64

The AggKnowledge person ID.

professionalSocialMediaUrl

string

LinkedIn URL of the person. Protocol and subdomain are optional, this value will be normalized server-side. Sales Nav and Recruiter URLs are allowed.

Enrich › Responses

Enriched person data

object

isRetryable

boolean

If the request failed, whether the request is retryable with the same input. Always true for successful requests.

isSuccess

boolean

Whether or not the request resulted in a successful enrichment.

object

Caller-supplied metadata associated with the request

object

POST/v2/{environment}/person/enrich

curl --request POST \
  --url https://api.aggknowledgeai.com/v2/:environment/person/enrich \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <string>' \
  --data '
{
  "metadata": {
    "key": "string"
  },
  "pdlId": "pdlId",
  "personId": 590654273,
  "professionalSocialMediaUrl": "https://www.linkedin.com/in/danielentrup/"
}
'

shell

Example Request Body

{
  "metadata": {
    "key": "string"
  },
  "pdlId": "pdlId",
  "personId": 590654273,
  "professionalSocialMediaUrl": "https://www.linkedin.com/in/danielentrup/"
}

json

Example Responses

{
  "data": {
    "bio": "bio",
    "dateLastUpdated": "2025-02",
    "firstName": "daniel",
    "id": 590654273,
    "lastName": "entrup",
    "linkedinUrl": "linkedin.com/in/danielentrup",
    "linkedinUsername": "danielentrup",
    "locationCity": "new york",
    "locationCountry": "united states",
    "locationMetro": "new york, new york",
    "locationPostalCode": "10001",
    "locationStateOrProvince": "new york",
    "middleName": "middleName",
    "primaryWorkExperienceId": 935242012,
    "tags": [
      {
        "confidenceLevel": 0,
        "description": "description",
        "name": "Java",
        "relatedWorkExperiences": [
          {
            "companyName": "Google",
            "jobRole": "operations",
            "jobSubRole": "executive",
            "jobTitle": "senior software engineer",
            "workExperienceId": 0
          }
        ],
        "type": 0
      }
    ],
    "workExperience": [
      {
        "company": {
          "addressLine1": "100 wall st",
          "addressLine2": "suite 100",
          "city": "melville",
          "companyType": "private",
          "competitors": [
            {
              "companyId": 44510632,
              "competitiveDescription": "Patterson Companies is a medical supplies company that operates in the business of veterinary and dental products, competing with Henry Schein in the dental and veterinary supply markets.",
              "competitorName": "patterson dental"
            }
          ],
          "country": "united states",
          "description": "Henry Schein is a leading distributor of dental and medical supplies, founded in 1839. They offer a wide range of products including dental equipment, orthodontic devices, medical instruments, and pharmaceuticals. Their services include practice management solutions, equipment financing, and repair services to support healthcare professionals in managing their practices efficiently.",
          "displayName": "Henry Schein",
          "employeeCountActual": 9800,
          "employeeCountRange": "1-10",
          "fundingRoundCount": 1,
          "fundingTotal": "750000000.00",
          "id": 65731533,
          "industry": "accounting",
          "isDescriptionReviewedByHuman": true,
          "isStructuredEntity": true,
          "latestFundingAmount": "1000000.00",
          "latestFundingDate": "2023-08-08",
          "latestFundingStage": "angel",
          "linkedinId": 93061732,
          "linkedinUrl": "linkedin.com/company/henry-schein",
          "name": "henry schein",
          "pdlCompanyId": "CBczqSDnKU3LGFyDe3JeoA9IhxYi",
          "postalCode": "11747",
          "primaryExchange": "xnas",
          "primaryTicker": "HSIC",
          "productsAndServices": [
            {
              "categories": [
                {
                  "categoryHierarchy": [
                    {
                      "categoryId": 137,
                      "level": 4,
                      "name": "Procurement"
                    }
                  ],
                  "id": 1785,
                  "name": "Accounts Payable (AP) and Spend Analysis"
                }
              ],
              "description": "Spend smarter with the leading spend management platform built for companies like you. Get the financial agility you need by transforming how your business spends.",
              "id": 60436221725246776,
              "name": "Coupa",
              "vendorAggkCompanyId": 42971468
            }
          ],
          "revenueRangeInferred": "$0-$1M",
          "stateOrProvince": "new york",
          "technographics": [
            {
              "description": "description",
              "indications": {
                "jobOpeningsCount": 0,
                "reviewsCount": 0,
                "webDetectionCount": 0
              },
              "lastObservation": "2024-08-25",
              "productId": 0,
              "productName": "productName",
              "vendorId": 0
            }
          ],
          "ultimateParent": {
            "addressLine1": "100 wall st",
            "addressLine2": "suite 100",
            "city": "melville",
            "companyType": "private",
            "country": "united states",
            "description": "Henry Schein is a leading distributor of dental and medical supplies, founded in 1839. They offer a wide range of products including dental equipment, orthodontic devices, medical instruments, and pharmaceuticals. Their services include practice management solutions, equipment financing, and repair services to support healthcare professionals in managing their practices efficiently.",
            "displayName": "Henry Schein",
            "employeeCountActual": 9800,
            "employeeCountRange": "1-10",
            "fundingRoundCount": 1,
            "fundingTotal": "750000000.00",
            "id": 65731533,
            "industry": "accounting",
            "isDescriptionReviewedByHuman": true,
            "isStructuredEntity": true,
            "latestFundingAmount": "1000000.00",
            "latestFundingDate": "2023-08-08",
            "latestFundingStage": "angel",
            "linkedinId": 93061732,
            "linkedinUrl": "linkedin.com/company/henry-schein",
            "name": "henry schein",
            "pdlCompanyId": "CBczqSDnKU3LGFyDe3JeoA9IhxYi",
            "postalCode": "11747",
            "primaryExchange": "xnas",
            "primaryTicker": "HSIC",
            "revenueRangeInferred": "$0-$1M",
            "stateOrProvince": "new york",
            "wasDescriptionRejected": false,
            "website": "henryschein.com",
            "willDescriptionBeGenerated": true
          },
          "wasDescriptionRejected": false,
          "website": "henryschein.com",
          "willDescriptionBeGenerated": true
        },
        "description": "description",
        "endDate": "2023-11",
        "id": 862384084,
        "jobClass": "general_and_administrative",
        "role": {
          "v1": "operations",
          "v2": "operations"
        },
        "seniority": "cxo",
        "startDate": "2023-02",
        "subrole": {
          "v1": "data",
          "v2": "executive"
        },
        "title": "chief executive officer",
        "titleRaw": "ceo"
      }
    ]
  },
  "inputParameters": {
    "pdlId": "pdlId",
    "personId": 590654273,
    "professionalSocialMediaUrl": "https://www.linkedin.com/in/danielentrup/"
  },
  "isRetryable": true,
  "isSuccess": true,
  "metadata": {
    "key": "string"
  },
  "problems": {
    "linkedinProfileNotFound": true,
    "transientScrapingVendorFailure": true
  }
}

json

application/json

Match

POST

https://api.aggknowledgeai.com

/v2/{environment}/person/match

Accepts a person match request with required full name and optional multiple companies, domains, and emails. Returns possible matches limited to 250 results. (Tier 3)

Match › path Parameters

environment

string · enum · required

Environment (live or test)

Enum values:

live

test

Match › Headers

x-api-key

string · required

API key for authentication

Match › Request Body

Person match request

companyDomains

string[]

Current or former employer domains of the person.

companyNames

string[]

Current or former employer names of the person.

emailAddresses

string[]

Current or former email addresses of the person.

fullName

string

The person's full name. Either fullName or linkedinUrl must be provided.

linkedinUrl

string

LinkedIn URL of the person. Either fullName or linkedinUrl must be provided.

locationCity

string

City where the person is located.

locationCountry

string

Country where the person is located.

locationStateOrProvince

string

State or province where the person is located.

Match › Responses

Match results

object[]

POST/v2/{environment}/person/match

curl --request POST \
  --url https://api.aggknowledgeai.com/v2/:environment/person/match \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <string>' \
  --data '
{
  "companyDomains": [
    "henryschein.com",
    "aggknowledge.ai"
  ],
  "companyNames": [
    "henry schein",
    "aggknowledge"
  ],
  "emailAddresses": [
    "[email protected]",
    "[email protected]"
  ],
  "fullName": "daniel entrup",
  "linkedinUrl": "https://www.linkedin.com/in/danielentrup",
  "locationCity": "san francisco",
  "locationCountry": "united states",
  "locationStateOrProvince": "california"
}
'

shell

Example Request Body

{
  "companyDomains": [
    "henryschein.com",
    "aggknowledge.ai"
  ],
  "companyNames": [
    "henry schein",
    "aggknowledge"
  ],
  "emailAddresses": [
    "[email protected]",
    "[email protected]"
  ],
  "fullName": "daniel entrup",
  "linkedinUrl": "https://www.linkedin.com/in/danielentrup",
  "locationCity": "san francisco",
  "locationCountry": "united states",
  "locationStateOrProvince": "california"
}

json

Example Responses

{
  "results": [
    {
      "fullName": "fullName",
      "hasEmail": true,
      "isEmailMatch": true,
      "linkedinUsername": "linkedinUsername",
      "locationCity": "locationCity",
      "locationCountry": "locationCountry",
      "locationStateOrProvince": "locationStateOrProvince",
      "personId": 0,
      "previousEmployerDomains": [
        "string"
      ],
      "previousEmployerNames": [
        "string"
      ]
    }
  ]
}

json

application/json

Search

POST

https://api.aggknowledgeai.com

/v2/{environment}/person/search

Accepts a person search request and returns possible matches (Tier 3)

Search › path Parameters

environment

string · enum · required

Environment (live or test)

Enum values:

live

test

Search › Headers

x-api-key

string · required

API key for authentication

Search › Request Body

Person search request

currentOrPastEmailAddress

string

A current or former email address of the person.

currentOrPastEmployerDomain

string

A current or former employer domain of the person.

currentOrPastEmployerName

string

A current or former employer name of the person.

fullName

string

The person's full name.

Search › Responses

Invalid input

correlationId

string

The correlation ID for this request. Provide this ID when contacting support.

detail

string

A human-readable explanation specific to this occurrence of the problem.

status

integer · int32

The HTTP status code generated by the origin server for this occurrence of the problem.

title

string

A brief title for the problem.

POST/v2/{environment}/person/search

curl --request POST \
  --url https://api.aggknowledgeai.com/v2/:environment/person/search \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <string>' \
  --data '
{
  "currentOrPastEmailAddress": "[email protected]",
  "currentOrPastEmployerDomain": "henryschein.com",
  "currentOrPastEmployerName": "henry schein",
  "fullName": "daniel entrup"
}
'

shell

Example Request Body

{
  "currentOrPastEmailAddress": "[email protected]",
  "currentOrPastEmployerDomain": "henryschein.com",
  "currentOrPastEmployerName": "henry schein",
  "fullName": "daniel entrup"
}

json

Example Responses

{
  "correlationId": "correlationId",
  "detail": "detail",
  "status": 0,
  "title": "title"
}

json

application/json

Validate enrichment request

POST

https://api.aggknowledgeai.com

/v2/{environment}/person/validate

Validates whether a person enrichment request has sufficient information and valid URLs (Tier 4)

Validate enrichment request › path Parameters

environment

string · enum · required

Environment (live or test)

Enum values:

live

test

Validate enrichment request › Headers

x-api-key

string · required

API key for authentication

Validate enrichment request › Request Body

object

Optional metadata to associate with the request. Will be returned in the response.

pdlId

string

The person's PDL ID.

personId

integer · int64

The AggKnowledge person ID.

professionalSocialMediaUrl

string

LinkedIn URL of the person. Protocol and subdomain are optional, this value will be normalized server-side. Sales Nav and Recruiter URLs are allowed.

Validate enrichment request › Responses

Validation result

hasSufficientIdentifiers

boolean

Whether the request has sufficient identifiers to proceed with enrichment

isLinkedinUrlValid

boolean

Whether any provided LinkedIn URL is valid

isValid

boolean

Whether the request is valid for enrichment

object

Metadata from the original request

validationMessage

string

Description of any validation issues found

POST/v2/{environment}/person/validate

curl --request POST \
  --url https://api.aggknowledgeai.com/v2/:environment/person/validate \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <string>' \
  --data '
{
  "metadata": {
    "key": "string"
  },
  "pdlId": "pdlId",
  "personId": 590654273,
  "professionalSocialMediaUrl": "https://www.linkedin.com/in/danielentrup/"
}
'

shell

Example Request Body

{
  "metadata": {
    "key": "string"
  },
  "pdlId": "pdlId",
  "personId": 590654273,
  "professionalSocialMediaUrl": "https://www.linkedin.com/in/danielentrup/"
}

json

Example Responses

{
  "hasSufficientIdentifiers": true,
  "isLinkedinUrlValid": true,
  "isValid": true,
  "metadata": {
    "key": "string"
  },
  "validationMessage": "validationMessage"
}

json

application/json

Bulk validate enrichment requests

POST

https://api.aggknowledgeai.com

/v2/{environment}/person/validate/bulk

Validates whether multiple person enrichment requests have sufficient information and valid URLs. Accepts up to 250 requests. (Tier 4)

Bulk validate enrichment requests › path Parameters

environment

string · enum · required

Environment (live or test)

Enum values:

live

test

Bulk validate enrichment requests › Headers

x-api-key

string · required

API key for authentication

Bulk validate enrichment requests › Request Body

object[]

Person enrichment requests to validate

object

Optional metadata to associate with the request. Will be returned in the response.

pdlId

string

The person's PDL ID.

personId

integer · int64

The AggKnowledge person ID.

professionalSocialMediaUrl

string

LinkedIn URL of the person. Protocol and subdomain are optional, this value will be normalized server-side. Sales Nav and Recruiter URLs are allowed.

Bulk validate enrichment requests › Responses

Validation results

object[]

hasSufficientIdentifiers

boolean

Whether the request has sufficient identifiers to proceed with enrichment

isLinkedinUrlValid

boolean

Whether any provided LinkedIn URL is valid

isValid

boolean

Whether the request is valid for enrichment

object

Metadata from the original request

validationMessage

string

Description of any validation issues found

POST/v2/{environment}/person/validate/bulk

curl --request POST \
  --url https://api.aggknowledgeai.com/v2/:environment/person/validate/bulk \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <string>' \
  --data '
[
  {
    "metadata": {
      "key": "string"
    },
    "pdlId": "pdlId",
    "personId": 590654273,
    "professionalSocialMediaUrl": "https://www.linkedin.com/in/danielentrup/"
  }
]
'

shell

Example Request Body

[
  {
    "metadata": {
      "key": "string"
    },
    "pdlId": "pdlId",
    "personId": 590654273,
    "professionalSocialMediaUrl": "https://www.linkedin.com/in/danielentrup/"
  }
]

json

Example Responses

[
  {
    "hasSufficientIdentifiers": true,
    "isLinkedinUrlValid": true,
    "isValid": true,
    "metadata": {
      "key": "string"
    },
    "validationMessage": "validationMessage"
  }
]

json

application/json

Person Asynchronous

Enrich

POST

https://api.aggknowledgeai.com

/v2/{environment}/person/enrich

Accepts a person enrichment request and returns enriched person data (Tier 1)

Enrich › path Parameters

environment

string · enum · required

Environment (live or test)

Enum values:

live

test

Enrich › Headers

x-api-key

string · required

API key for authentication

Enrich › Request Body

object

Optional metadata to associate with the request. Will be returned in the response.

pdlId

string

The person's PDL ID.

personId

integer · int64

The AggKnowledge person ID.

professionalSocialMediaUrl

string

LinkedIn URL of the person. Protocol and subdomain are optional, this value will be normalized server-side. Sales Nav and Recruiter URLs are allowed.

Enrich › Responses

Enriched person data

object

isRetryable

boolean

If the request failed, whether the request is retryable with the same input. Always true for successful requests.

isSuccess

boolean

Whether or not the request resulted in a successful enrichment.

object

Caller-supplied metadata associated with the request

object

Match

POST

https://api.aggknowledgeai.com

/v2/{environment}/person/match

Accepts a person match request with required full name and optional multiple companies, domains, and emails. Returns possible matches limited to 250 results. (Tier 3)

Match › path Parameters

environment

string · enum · required

Environment (live or test)

Enum values:

live

test

Match › Headers

x-api-key

string · required

API key for authentication

Match › Request Body

Person match request

companyDomains

string[]

Current or former employer domains of the person.

companyNames

string[]

Current or former employer names of the person.

emailAddresses

string[]

Current or former email addresses of the person.

fullName

string

The person's full name. Either fullName or linkedinUrl must be provided.

linkedinUrl

string

LinkedIn URL of the person. Either fullName or linkedinUrl must be provided.

locationCity

string

City where the person is located.

locationCountry

string

Country where the person is located.

locationStateOrProvince

string

State or province where the person is located.

Match › Responses

Match results

object[]

POST

https://api.aggknowledgeai.com

/v2/{environment}/person/search

Accepts a person search request and returns possible matches (Tier 3)

Search › path Parameters

environment

string · enum · required

Environment (live or test)

Enum values:

live

test

Search › Headers

x-api-key

string · required

API key for authentication

Search › Request Body

Person search request

currentOrPastEmailAddress

string

A current or former email address of the person.

currentOrPastEmployerDomain

string

A current or former employer domain of the person.

currentOrPastEmployerName

string

A current or former employer name of the person.

fullName

string

The person's full name.

Search › Responses

Invalid input

correlationId

string

The correlation ID for this request. Provide this ID when contacting support.

detail

string

A human-readable explanation specific to this occurrence of the problem.

status

integer · int32

The HTTP status code generated by the origin server for this occurrence of the problem.

title

string

A brief title for the problem.

Validate enrichment request

POST

https://api.aggknowledgeai.com

/v2/{environment}/person/validate

Validates whether a person enrichment request has sufficient information and valid URLs (Tier 4)

Validate enrichment request › path Parameters

environment

string · enum · required

Environment (live or test)

Enum values:

live

test

Validate enrichment request › Headers

x-api-key

string · required

API key for authentication

Validate enrichment request › Request Body

object

Optional metadata to associate with the request. Will be returned in the response.

pdlId

string

The person's PDL ID.

personId

integer · int64

The AggKnowledge person ID.

professionalSocialMediaUrl

string

LinkedIn URL of the person. Protocol and subdomain are optional, this value will be normalized server-side. Sales Nav and Recruiter URLs are allowed.

Validate enrichment request › Responses

Validation result

hasSufficientIdentifiers

boolean

Whether the request has sufficient identifiers to proceed with enrichment

isLinkedinUrlValid

boolean

Whether any provided LinkedIn URL is valid

isValid

boolean

Whether the request is valid for enrichment

object

Metadata from the original request

validationMessage

string

Description of any validation issues found

Bulk validate enrichment requests

POST

https://api.aggknowledgeai.com

/v2/{environment}/person/validate/bulk

Validates whether multiple person enrichment requests have sufficient information and valid URLs. Accepts up to 250 requests. (Tier 4)

Bulk validate enrichment requests › path Parameters

environment

string · enum · required

Environment (live or test)

Enum values:

live

test

Bulk validate enrichment requests › Headers

x-api-key

string · required

API key for authentication

Bulk validate enrichment requests › Request Body

object[]

Person enrichment requests to validate

object

Optional metadata to associate with the request. Will be returned in the response.

pdlId

string

The person's PDL ID.

personId

integer · int64

The AggKnowledge person ID.

professionalSocialMediaUrl

string

LinkedIn URL of the person. Protocol and subdomain are optional, this value will be normalized server-side. Sales Nav and Recruiter URLs are allowed.

Bulk validate enrichment requests › Responses

Validation results

object[]

hasSufficientIdentifiers

boolean

Whether the request has sufficient identifiers to proceed with enrichment

isLinkedinUrlValid

boolean

Whether any provided LinkedIn URL is valid

isValid

boolean

Whether the request is valid for enrichment

object

Metadata from the original request

validationMessage

string

Description of any validation issues found