Syncing data to/from ChartHop
One of the most common use-cases of the ChartHop API is to pull and push data, such as the current organizational roster or perhaps you have your own payroll system and want to write your own payroll sync to automatically update the ChartHop roster from the payroll system.
The best API call to make open-ended queries to the organizational roster is the findJobs call. This API call lets you retrieve both open jobs as well as people, and lets you retrieve whichever fields you choose (using the fields parameter) or apply filters (using the q parameter).
For example, if you wanted to retrieve the entire roster's first name, last name, title, work email, and work country:
https://api.charthop.com/v2/org/{orgId}/job?fields=name.first,name.last,title,contact.workEmail,workAddress.country
You can filter with the q parameter, using Carrot filtering. For example, if you only wanted people who have been at the company at least 12 months (tenure >= 12), you could query:
https://api.charthop.com/v2/org/{orgId}/job?fields=name.first,name.last,contact.workEmail&q=tenure>=12
- If you want to filter only for people, not open positions, you can use q=open:filled
- For a list of fields that you can query, see Built In Fields. You can also query for any custom fields.
- For more about Carrot filtering, review Filtering.
- To try out filtering in the application, use the Data Sheet and type the filters in the search bar.
Often, it is sufficient to query on a regular interval. However, you may want to automatically update your system as soon as something happens on ChartHop.
If so, your app can use a Webhook to subscribe to event notifications. You will want to set up an endpoint URL to receive the webhook, and subscribe to change.* events.
When you receive a notification that a change has occurred, the change payload should contain a jobId. You can query for that job using the queryJobs endpoint. (You can filter for a single person or job via q=jobId:jobId)
Like everything else on ChartHop, the data that you fetch via API will be filtered according to the app's specific permissions. If you don't receive data that you're expecting, be sure to check the app's permission.
The best API call to use to update data in bulk in ChartHop is the importDataCsv API call https://api.charthop.com/v1/org/{orgId}/import/csv/data
This call lets you post a multipart/form-upload of the CSV file to push a large amount of data into ChartHop.
This call has lots of optional parameters. For most purposes we'd recommend using:
- upsert - set this to true if you expect to add new people or jobs that aren't in ChartHop already. Don't use it if you're just updating existing people in the roster.
- createGroups - set this to true if you want to create departments and locations on the fly if they are in the source system. If you are not creating departments and locations, no need to use it.
- notifyUserIds - set this to a list of user-ids (you can retrieve these ids via the findUsers API call) to send an email following the completion of the API call.
- notifyAppName - set this to the name of the app that you want to show up in the notify email
The importDataCsv call runs asynchronously. Depending on the size of the import, it can take anywhere from a few seconds to an hour. It returns a Process object. You can check on the status of the process by calling the getProcess call.
If your sync is for your own private use, then run the above API call whenever you please, on your own schedule. It's your world!
But, if you are building a sync that is intended for distribution for other ChartHop users, those users will expect the sync to run when they press the "Sync Now" button from the app configuration page in ChartHop.
When the user presses "Sync Now", this starts an asynchronous "sync process" for your app that you, the app developer, are expected to manage the state of. We'll ping your webhook URL to tell you that the user has hit sync, and you ping us back when you're done syncing.
To implement this, you will want to use the following flow:
- Set up an Event Notification Webhook on your own URL, matching on the process.create.{appname} event.
- When your Webhook URL receives this event, the entityId will contain the sync process id.
- Run your sync, implementing calls to importDataCsv or whatever else you need to complete the sync.
- When your sync is complete (or errors out), call the updateProcess API call to mark the sync process as complete.
- For bonus points and a nicer user experience, call updateProcess periodically during your sync, passing a progress value from 0 to 1 and a message with the last status message. This will control the state of the progress bar the user will see as your sync runs.
Your app will need Primary Editor permissions to sync data into ChartHop.
