Skip to content
RolePark
EN
About the product ↗

API, webhooks, SCIM and SAML single sign-on

RolePark connects to your other systems in four ways: a REST API with narrowly scoped keys, signed webhooks, SCIM 2.0 for creating and deactivating user accounts, and SAML 2.0 single sign-on. A company administrator sets them up.

Updated:

Reviewed by the RolePark team

In short

  • REST API with 7 scopes: read people, employments, public vacancies and applications, and add candidates; 120 requests per minute per key.
  • Webhooks for 8 events, signed with HMAC-SHA256: 6 delivery attempts in total (5 retries).
  • SCIM 2.0 for user accounts and SAML 2.0 single sign-on, with an option to switch off password sign-in.
  • Available on every plan, Free included; only a company administrator issues keys and configures SSO.

REST API

The API lives at https://rolepark.com/api/v1. Every request carries a key in the Authorization header as a bearer token. A company administrator creates keys on the Integrations page and gives each one only the scopes it needs.

Scopes

people.read, employments.read, vacancies.read, applications.read, candidates.write, webhooks.manage, scim.manage. A key gives an outside system access to company data regardless of user roles, which is why only the administrator issues it and why the scopes are narrow.

What the API can read and write

  • Read people and employments, with an updated-since filter for incremental sync.
  • Read public vacancies and applications, filtered by status or vacancy.
  • Add candidates. First name, last name, a source and an email, phone or LinkedIn address are required. If the candidate already exists, RolePark fills only the empty fields and does not overwrite the rest.
  • Reading candidate records through a key is deliberately not available.

Limits, keys and documentation

  • 120 requests per minute per key; above that the API answers 429 with Retry-After.
  • Page-based pagination: 25 records by default, up to 100.
  • The key is shown once. RolePark keeps only its SHA-256 hash, so it cannot be shown again; a revoked key stops working immediately.
  • The OpenAPI 3 description is at /api/v1/openapi.json and opens with the same key.

Webhooks

RolePark sends a POST request to your HTTPS endpoint when one of these events happens: employment.created, employment.updated, employment.ended, application.stage_changed, document.signed, interview.scheduled, interview.cancelled, scorecard.submitted.

  • Each request is signed: sha256=HMAC(secret, timestamp + "." + body). Verify the signature over the raw request body. The secret is shown once and can be rotated.
  • Only HTTPS addresses on public hosts are accepted. The receiver must answer 2xx within 10 seconds; redirects are not followed.
  • Failed deliveries are retried after 30 seconds, 2 minutes, 10 minutes, 1 hour and 6 hours. After the last attempt the endpoint is switched off and the Integrations page shows it.
  • The delivery log shows the last 50 deliveries with their status and error, and a delivery can be sent again by hand.

SCIM 2.0 user provisioning

SCIM is the IETF standard for creating, updating and removing user accounts from an identity provider (RFC 7643 and RFC 7644). RolePark’s SCIM endpoint is https://rolepark.com/api/scim/v2; it uses an API key with the scim.manage scope.

  • Supported: the Users resource (list, create, read, replace, update and delete) and ServiceProviderConfig.
  • Filtering by userName eq, paging with startIndex and count, up to 200 per page.
  • Deleting a user or setting active to false deactivates the account. Nothing is erased: history, signatures and scorecards stay. The last active administrator cannot be deactivated.
  • New SCIM users get the Employee role; an administrator assigns other roles in RolePark. Groups are not supported.

SAML 2.0 single sign-on

A company administrator sets up single sign-on in Settings → Company. RolePark shows its own details for your identity provider — the service provider Entity ID, the assertion consumer service (ACS) URL and metadata — and you enter the IdP Entity ID, its HTTPS sign-in URL and its signing certificate.

  • Your identity provider must sign its assertions. After saving, RolePark shows only the certificate fingerprint.
  • RolePark reads the email and name from the attribute names Okta and Microsoft Entra ID (Azure AD) use by default.
  • Accounts are not created on first sign-in: invite people or provision them through SCIM first.
  • After SSO works, the administrator can disallow password sign-in for the company. One identity provider per company.

Analytics keys for Power BI and Excel

With ATS access, an administrator can issue separate keys for JSON and CSV feeds of vacancy and people statistics. Power BI and Excel read them as a web data source. The vacancy feed carries numbers only — applications by stage, hires and time to hire — and no candidate personal data.

Other connections

AI assistants such as Claude and ChatGPT connect through MCP with the person’s own permissions, and Djinni connects with an API key from your Djinni account. Both have their own setup guides.

Frequently asked questions

Is the API available on the Free plan?

Yes. The API, webhooks, SCIM and SAML single sign-on are available on every plan. Analytics keys for Power BI need ATS access.

Can I read candidates through the API?

No, by design. A key can add candidates (candidates.write) and read people, employments, public vacancies and applications.

Does RolePark support SCIM groups?

No. RolePark supports the SCIM Users resource. Roles are assigned in RolePark; new SCIM users start as employees.

Does SAML sign-in create accounts automatically?

No. A person must already have an account, created by invitation or through SCIM. Unknown email addresses are refused.

How do I verify a webhook?

Compute HMAC-SHA256 with your webhook secret over the timestamp, a dot and the raw request body, and compare it with the signature in the request.

Sources

Create a workspaceAsk the RolePark team