Syncing from ChartHop

ÔĽŅ

One of the most common usecases of the ChartHop API is to pull data, such as the current organizational roster, from ChartHop into another system.

ÔĽŅÔĽŅQuerying the organization

The best API call to make open-ended queries to the organizational roster is the queryJobs 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/v1/org/{orgId}/job/data?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/v1/org/{orgId}/job/data?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 CQL 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.