Org chart

Count a company's people by department and seniority

How one company's people distribute across departments and seniorities.

This is a matrix, not a tree. The corpus holds no reporting lines — no person document carries a manager — so there is no hierarchy here to walk and no direct_reports coming later. What you get is every person we hold for the company, grouped by two closed vocabularies: the 23-function department taxonomy across one axis and the seven-level seniority ladder across the other.

Read total as the headcount and cells as the classified part of it. The two do not match, and the gap is not a bug: someone whose title we hold but whose function we could not infer is counted in total, in neither axis total, and in no cell. Send include_others: true to see those people as a row and a column of their own rather than only in the difference.

Order is fixed rather than reported: departments descend by headcount with the leftover buckets last, and seniorities always run C-Suite to In Training. Two companies' charts therefore read the same way, and a column that is missing is a column with nobody in it.

Narrow with any of the filters and the counts change rather than the display — country: ["Netherlands"] returns the Dutch org chart, not the global one with cells hidden. POST /v1/org-chart/locations is where the place names come from.

To see the people behind a cell, search for them: POST /v1/search with category: "person", include_domains: ["<domain>"] and department / seniority filters set to that cell's labels. The one exception is a cell labelled Others, which is not a value the search filters accept — it names the absence of a value, and there is nothing to filter on.

Scope: dsp.search.read

Use it when you want the shape of a company rather than a list of its people: where the headcount sits, which functions are large, how senior each one is. Outcome: a department × seniority grid with totals on both axes, and two drill-downs:

• Sub-departments: sub-functions within a department
• Locations: where the people are

All three routes are metered under one action, dsp.org_chart, at 1 credit flat per call that returns data. A call that returns nothing — no cells, no departments, no locations — is free and reports credits_charged: 0. A failed call is not charged.

Request#

Give a domain or a linkedin_url, exactly one. Both are refused, as is neither: the two can name different companies, and picking a winner would answer a question you did not ask.

• A pasted URL is reduced to its host on either field, so https://www.adyen.com/about and adyen.com are the same request. The response echoes the normalized form.
• A company name is a 422. Find the company with search (category: "company") first.

Filters narrow the population before the grouping, so they change the counts rather than hiding rows: country: ["Netherlands"] returns the Dutch org chart, not the global one with cells blanked.

Response#

total is not the sum of the cells

total is everyone at the company under the filters, and the sum of the cells can be lower or higher than it. Lower, because a person whose title we hold but whose function we could not infer is counted in total, in neither axis total, and in no cell. Higher, because a person with several departments or seniorities is counted once in total and once in each of their cells.

Send include_others: true to see those people as a row and a column of their own rather than only in the difference.

Order is fixed, not reported

• Departments descend by headcount, with the leftover buckets last however large they are.
• Seniorities always run C-Suite, VP, Director / Head, Manager, IC, Entry, In Training, then Others.

Two companies' charts therefore read the same way, and a column that is missing is a column with nobody in it. Cells are sparse: a pair with no people is absent, not a zero.

Getting the people behind a cell

There is no people list on this route. A cell's two labels are search filters, so send them to POST /v1/search:

{
  "category": "person",
  "include_domains": ["adyen.com"],
  "filters": {
    "department": { "include": ["Engineering / Software"] },
    "seniority": { "include": ["VP"] }
  },
  "limit": 10
}

For a company reached by linkedin_url, scope the search with the company filter instead, since include_domains cannot narrow a company that has no domain:

{
  "category": "person",
  "filters": {
    "company": {
      "include": [{ "value": "linkedin.com/company/procentia", "by": "li" }]
    },
    "department": { "include": ["Sales"] },
    "seniority": { "include": ["VP"] }
  },
  "limit": 10
}

Either way it is a separate, separately-billed call.

Sub-departments#

curl -X POST "https://api.sproutsdata.ai/v1/org-chart/departments" \
  -H "X-API-Key: $SPROUTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "domain": "adyen.com"
     }'

The same population and filters as the grid, grouped one level finer. Two differences will look like inconsistencies if you expect otherwise:

• Labels are the corpus's raw values rather than the grid's relabelled taxonomy, so a department name here can be absent from the grid's departments.
• People with no sub-function are named Uncategorized where the grid says Others. Two routes aggregating two fields; their vocabularies are deliberately not merged, because renaming an upstream's labels is how two systems start disagreeing about counts.

Locations#

curl -X POST "https://api.sproutsdata.ai/v1/org-chart/locations" \
  -H "X-API-Key: $SPROUTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "domain": "adyen.com",
       "search": "amst"
     }'

Two uses:

• On its own, it is the geographic shape of the company.
• Beside the grid, it is that route's vocabulary: these are the exact strings its country, state and city filters accept, so there is no need to guess at place names.

A parent's count is not the sum of its children: someone with a country and no city is counted at the country and in no city beneath it. Each level answers "how many people do we place at least this precisely".

search filters people rather than labels. Matching a city keeps that city's country and state in the tree, with counts reduced to the matching people, so the branch stays navigable instead of returning a city with no parent.

A level with no value recorded is labelled __unknown__, and that string is accepted back as a filter value on the grid.

Errors#

Two worth handling distinctly:

• An unknown company is a 422 request.invalid, not a 404. The detail names the identifier you sent, because correcting it is your fix. On the linkedin_url path this is raised before any charge, since resolution happens first.
• 501 not_implemented means org charts are not enabled in this deployment. It is never charged, and retrying will not change it.