Get the most out of your API

This recorded session is aimed at system administrators and IT teams, and shows you how to use the Ciphr HR API to share data securely between Ciphr and your other systems.

Discover how the Ciphr HR API lets your systems share data securely, see live demos of real queries and updates, and learn how to set up and control API access yourself.

Use the video controls to view captions, chapters, fullscreen and speed settings

Key takeaways

• Having an API key doesn’t give access to everything. Each request is checked against the key, its expiry date, the IP allow list, and the endpoint and field permissions
• Access is set at three levels: the overall key, each endpoint, and each field. A field won’t return data unless read access is turned on for it
• Start with read-only (GET) requests so you can see what comes back before you allow any updates.
• Use one API key per connection, for example separate keys for your LMS integration and for Power BI.
• Only expose the fields you need. Think carefully about sensitive data such as bank details or absence reasons
• You can only copy the API key once, when you create it. Store it in a secure password manager. Regenerating the key stops the old one from working straight away

Postman quick start

Add these three headers to every request:

Common status codes

• 200 OK: the request worked
• 401 Unauthorised: the key is invalid or wrongly formatted, the IP address isn’t on the allow list, or the key doesn’t have access to that endpoint or field

Questions

• Where do I set up the API? 
  Go to System Configuration > API. Any HR system admin can create keys and change settings. Some customers also give their IT team a role that can open this page.
• Where’s the technical documentation? 
  Add /api/help to the end of your Ciphr URL. It lists the endpoints your key can access, example requests and expected responses.
• Can a connected system update data in Ciphr? 
  Yes, if the key has update access on the endpoint and the field. For example, some customers update absence records from their time and attendance system.
• Can I connect Ciphr to Power BI directly? 
  Yes. Several customers query the API from Power BI without going through Excel, and the data is live each time it refreshes.
• I’ve added an endpoint but still get no data. Why? 
  Check that read access is turned on for the fields within that endpoint, not just the endpoint itself.
• Is there an endpoint for everything? 
  Almost all HR data has one. At the time of the session, talent management was the exception.
• Can I limit which employees are included? 
  Yes. Filter by record group or payroll code, and choose whether to include leavers (for example, the last 12 months) and future starters.
• Do I need Ciphr’s help to build an integration? 
  No. You can build it yourself using the guidance, or ask for a Ciphr-supported integration, which includes scoping and validation.

Related articles

• API and Integrations