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 syncing from charthop querying the organization the best api call to make open ended queries to the organizational roster is the findjobs https //api charthop com/swagger#/job/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 live syncing via webhook 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 ) permissions 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 syncing to charthop importing data the best api call to use to update data in bulk in charthop is the importdatacsv https //api charthop com/swagger#/import/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 https //api charthop com/swagger#/user/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 checking on the status of the import 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 https //api charthop com/swagger#/process/getprocess call interacting with the charthop apps ui 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 https //api charthop com/swagger#/process/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 permissions your app will need primary editor permissions to sync data into charthop