OrgChart API

Audience: Administrators

 

Overview

The OrgChart REST API is designed to send your chart data to OrgChart. For most integrations, OrgChart will pull data from your HRIS or ATS system. However, certain integrations may push data to OrgChart. The following article details the REST API method for pushing data to OrgChart.  Typically, your organization would need to do some development work to interface with this custom integration. 

Note

SFTP integrations are also available to push data to OrgChart. For more information on SFTP connections, please contact OrgChart Support.

The OrgChart REST API provides a RESTful interface for integrating external employee data into your org chart. This API supports real-time data ingestion with flexible JSON schemas and automatic chart refresh capabilities.

Base URL: https://{mydomain}.theorgchart.com/api/v1

Setup instructions

The following sections provide information on how to set up the OrgChart API.

Important

You need to have a base chart setup in order to push data to OrgChart. Reference the Creating a base chart article for more information.

Enable API Access

1. Click on Settings > Chart Settings. The Data sources tab is opened by default.
   
    
    
2. Click on the Change data source button under the Main data source section, and then select OrgChart API as your data source.
    
    
3. A Load field mapping heading alert is displayed. Click on Not now.
    
4. Click on the Generate API Key button to create your authentication credentials
    
    

5. The API key is generated. Click on the eye button to reveal the API key, and then copy (highlight text and right-click to copy) and securely store the generated API key. Click on Save to close the panel.

   
    

6. Click on Save on the Chart Settings: Data sources page.
   
   

7. Proceed with the Authentication and Data ingestion sections below to send employee data to OrgChart. Then, return to the screen above and choose the Configure field mapping button.
    
8. Load your field mapping, click on Save, and then Refresh.

Authentication: Get authentication token

Before you begin the authentication flow, you will need the following information:

• OrgChart username: Email associated with an OrgChart user that is used to sign in to the OrgChart application. This forms the username for basic authentication.
   
• OrgChart password: Password associated with the username selected above that is used to sign in to the OrgChart application. This forms the password for basic authentication.
   
• OrgChart API Key: Generated in the OrgChart application while enabling API access.

The OrgChart API uses a two-step authentication process:

1. Get Authentication Token using Basic Auth + API Key

2. Use Token for subsequent data ingestion requests

Endpoint: POST /auth

Headers:

Authorization: Basic {base64_encoded_username:password}
Content-Type: application/json

Request body:

{
   "api_key": "your_generated_api_key"
}

Response:

{
   "success": true,
   "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
   "expires_in": 300,
   "message": "Authentication successful"
}

Important

Tokens expire after 5 minutes (300 seconds). Request a new token if you receive authentication errors.

Data ingestion: Send employee data

Before you begin data ingestion, you'll need the following information:

• OrgChart API Key: Generated in the OrgChart application while enabling API access.
   
• OrgChart Authentication Token: Generated during the authentication flow.
   
• Org ID: Your OrgChart Org ID, which can be found in Settings: Account details under the OrgID heading:
  
  
   
• Chart ID: The automatically generated number that is associated with the base chart to which you are sending employee data. The highlighted number (1) in the screenshot below is the Chart ID, which can be found in the OrgChart URL while in the Chart settings menu:
  
  
   

Endpoint: POST /{org_id}/{chart_id}/employees/

Headers:

Content-Type: application/json

Query Parameters:

• clear=true (optional) - Clears all existing data for this source before inserting new data

  Typically, you’ll want to include this option the first time you push a fresh batch of employee data to OrgChart. OrgChart will keep the previous data you pushed in a temporary collection so that you can combine multiple data sources together or send multiple payloads of data.

• refresh=true (optional) - triggers immediate refresh

  OrgChart will use the latest data you’ve sent via the API when a scheduled refresh job occurs. If you would like OrgChart to reflect the data more immediately, you can queue up a refresh job as part of your last batch of data you push to OrgChart, or even independently of pushing additional data. 

Request body:

{
   "token": "your_authentication_token",
   "api_key": "your_api_key",
   "batchID": "batch_2024_001",
   "data": [
       {
           "PersonID": "EMP001",
           "SupervisorID": "MGR001", 
           "Name": "John Doe",
           "Title": "Software Engineer",
           "Email": "[e-mail]",
           "Department": "Engineering",
           "Location": "New York",
           "HireDate": "2023-01-15",
           "Salary": "75000"
       },
       {
           "PersonID": "MGR001",
           "SupervisorID": null,
           "Name": "Jane Smith",
           "Title": "Engineering Manager", 
           "Email": "[e-mail]",
           "Department": "Engineering",
           "Location": "New York",
           "HireDate": "2021-03-20",
           "Salary": "95000"
       }
   ]
}

Response:

{
   "success": true,
   "message": "Employee data ingested successfully",
   "batch_id": "batch_2024_001",
   "record_count": 2,
   "refresh_triggered": true,
   "refresh_result": {
       "success": true,
       "message": "Chart flagged for refresh - processing will begin shortly",
       "code": "0000",
       "async": true
   }
}

Data schema requirements

The API accepts flexible JSON schemas, but your data must include fields that can be mapped to these core org chart elements:

• Record ID / Person ID: Unique identifier for each employee

• Parent Record ID / Supervisor ID: ID of the employee's manager

• Employee Name: Full name of the employee

• Employee Title: Job title or position

In addition to the require fields listed above, you may choose to include any additional fields relevant to your organization (department, location, email, phone, etc.). All fields will be available for mapping in the chart configuration mapping interface. 

Advanced features

The following section provides information on advanced feature available for the OrgChart API.

Data clearing

Use the clear=true query parameter to replace all existing data for your source:

POST /{org_id}/{chart_id}/employees/?clear=true

Clear with new data response:

{
   "success": true,
   "message": "Employee data ingested successfully",
   "batch_id": "new_batch_123",
   "record_count": 50,
   "clear_triggered": true,
   "clear_result": {
       "success": true,
       "records_cleared": 45,
       "batches_cleared": 3,
       "source_id": "main"
   }
}

Clear only (no new data) response:

{
   "token": "your_token",
   "api_key": "your_api_key", 
   "username": "your_username",
   "data": []
}

Automatic chart refresh

The API integrates with the org chart refresh scheduler:

• Immediate Refresh: Add refresh: true header to trigger immediate processing

• Scheduled Refresh: Data will be processed according to your chart's refresh schedule

• Manual Refresh: Use the refresh button in Chart Settings

Rate limits

Recommended limits (enforce these in your client):

• Authentication requests: 10 per minute per API key

• Data ingestion requests: 5 per minute per API key

• Maximum records per request: 1,000 employees

Error responses

Authentication Errors

Invalid Basic Auth:

{ 
"success": false, 
"message": "Basic Auth required"
 }

Status Code: 401

Invalid API Key:

{ 
"success": false, 
"message": "Invalid API key"
 }

Status Code: 401

Expired Token

{ 
"success": false, 
"message": "Invalid or expired token"
 }

Status Code: 401

Data Ingestion Errors

Missing Required Fields:

{
 "success": false,
 "message": "Missing authentication fields"
 }

Status Code: 400

Invalid Data Format:

{ 
"success": false, 
"message": "Data must be a list"
 }

Status Code: 400

Clear Operation Failed:

{ 
"success": false, 
"message": "Failed to clear existing data: Database connection error",
"clear_requested": true
 }

Status Code: 500

Storage Failed After Clear:

{ 
"success": false,
"message": "Failed to store data: Invalid batch format (Note: Existing data was cleared but new data failed to store)",
"clear_triggered": true,
"clear_result": { 
       "success": true,
       "records_cleared": 25,
       "batches_cleared": 3,
       "source_id": "main"
        }        
}

Troubleshooting

Common Issues

1. "Invalid or expired token" - Tokens expire after 5 minutes. Request a new token.

2. "Invalid API key" - Verify your API key is correctly copied from the Chart Settings interface.

3. "Missing authentication fields" - Ensure your request includes token, api_key, and username fields.

4. "Data must be a list" - The data field must be an array of employee objects, not a single object.

5. Rate limiting - If you encounter frequent errors, implement delays between requests.

Best Practices

• Cache tokens for up to 4 minutes to avoid unnecessary authentication requests

• Implement retry logic for network failures and rate limiting

• Use batch uploads instead of individual employee uploads for efficiency

• Monitor refresh status to ensure data processing completes successfully

• Test with small datasets before implementing full data synchronization

Support

For technical support or questions about the OrgChart API or the Employees Endpoint:

1. Check Chart Settings: Data sources for detailed error messages. Integration errors will appear in the top banner.

2. Verify your API key is active in the OrgChart API configuration modal.

3. Ensure your data includes the required mapping fields (Person ID, Supervisor ID, Name, Title).

4. Contact your system administrator for additional assistance.