Skip to Content

Flat file delivery

In addition to the REST API, The Org can deliver org chart snapshots as flat files for bulk ingest, offline analysis, and historical backfills.

Flat files are a good fit when you need the full corpus (or large subsets) on a schedule, rather than pulling companies one-by-one over HTTP.

Request access

Flat file delivery is available on request. Contact us to enable access for your organization:

When you reach out, mention that you need flat file / SFTP access to org chart dumps. You can request:

  1. Ongoing monthly dumps — a complete snapshot published at the start of each month
  2. Historical dumps — prior monthly folders (subject to availability and your agreement)

Once approved, you will receive SFTP credentials (username and password) and connection details.

Flat file access is separate from API keys and credits. Having an API key does not automatically grant SFTP access.

What’s in a dump

Each monthly snapshot is a folder of gzipped LDJSON (newline-delimited JSON) part files — one or more parts per company — plus a completion marker.

global/
  YYYY-MM-01/
    <company-uuid>.1.json.gz
    <company-uuid>.2.json.gz   # only if the company has more than 50,000 nodes
    ...
    _SUCCESS
DetailBehavior
Folder dateAlways the first of the month (e.g. July → global/2026-07-01/)
Part sizeAt most 50,000 lines per .json.gz part
Part numbering1-based; every company with data has at least .1.json.gz
CompletenessA month is ready only when _SUCCESS is present

Historical months use the same layout under earlier YYYY-MM-01 folders when available for your account.

Download

Connect with the provided username and password:

sftp <USERNAME>@<SFTP_HOST>
# enter the provided password when prompted

Check that the month is complete, then download the folder:

ls global/2026-07-01/_SUCCESS
get -r global/2026-07-01 ./2026-07-01

GUI clients (Cyberduck, FileZilla, Transmit, etc.) work the same way: SFTP + username/password, then sync the month folder after _SUCCESS appears.

File format

Rows use the same Org Chart / Chart Node shapes as the API, with these flat-file specifics:

  • Every line includes companyId (company UUID)
  • One line = one chart node (position, job, coManager, or empty)
  • Positions include workEmail and linkedInUrl when available (unlike org-chart API v1.2, which omits them)
  • Job posts include jobPostUrl (https://theorg.com/org/<company-slug>?j=<job-slug>)

Peek at a file:

gunzip -c 2026-07-01/<company-uuid>.1.json.gz | head -n 5

Example lines

Position (nodeType: "position"):

{
  "companyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "nodeType": "position",
  "id": "p-4449",
  "positionId": 4449,
  "fullName": "Jane Doe",
  "title": "VP Engineering",
  "workEmail": "jane.doe@acme.com",
  "linkedInUrl": "https://www.linkedin.com/in/janedoe",
  "managerId": "p-4440",
  "section": "orgChart"
}

Job post (nodeType: "job"):

{
  "companyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "nodeType": "job",
  "id": "p-555001",
  "jobId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "jobTitle": "Senior Backend Engineer",
  "jobPostUrl": "https://theorg.com/org/acme?j=senior-backend-engineer",
  "managerId": "p-4449",
  "section": "orgChart"
}

Co-manager group (nodeType: "coManager"):

{
  "companyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "nodeType": "coManager",
  "id": "g-12403",
  "name": "Co-CEOs",
  "members": ["p-4449", "p-4448"],
  "managerId": null,
  "section": "orgChart"
}

Empty node (nodeType: "empty"):

{
  "companyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "nodeType": "empty",
  "id": "p-9001",
  "managerId": "p-4449",
  "section": "orgChart"
}

Tips

Last updated on
Change LogIntroduction