# Namely SureCloud connects to Namely to retrieve employee records, employment status changes, and HR profile data. This enables SureCloud to monitor joiner, mover, and leaver events — confirming that access provisioning and deprovisioning controls are triggered at the right points in the employee lifecycle, and that HR records remain consistent with identity and access data collected from connected systems. ## Authentication and setup Namely supports OAuth 2.0 for API access. SureCloud uses the OAuth flow to obtain a scoped access token tied to your Namely subdomain. {% hint style="info" %} SureCloud uses OAuth 2.0 for this integration. No credentials are stored — access is maintained via a refresh token that SureCloud rotates automatically. {% endhint %} {% stepper %} {% step %} **Identify your Namely subdomain** Your Namely instance is accessed at `https://.namely.com`. You will need this subdomain during the connection setup in SureCloud. {% endstep %} {% step %} **Initiate the OAuth connection in SureCloud** Navigate to **SureCloud → Integrations → Namely → Connect**. Enter your Namely subdomain when prompted, then click **Authorise**. SureCloud will redirect you to your Namely login page. {% endstep %} {% step %} **Approve access in Namely** Log in to Namely with an account that has API access permissions (typically an HR Admin). Review the requested scopes and click **Allow** to grant SureCloud access. {% endstep %} {% step %} **Return to SureCloud** After authorisation, you will be redirected back to SureCloud. The integration status will update to **Connected**. Click **Test Connection** to confirm SureCloud can retrieve data from your Namely instance. {% endstep %} {% endstepper %} ## Endpoints | API Call | Use Case | | ---------------------------------------------- | ------------------------------------------------------------------------------- | | `GET /api/v1/profiles` | Enumerate all employee profiles including employment status and start/end dates | | `GET /api/v1/profiles/{id}` | Retrieve individual employee detail including department, title, and manager | | `GET /api/v1/profiles?filter[status]=inactive` | Identify terminated or deactivated employees for offboarding evidence | | `GET /api/v1/events` | Retrieve HR event feed for joiner, mover, and leaver lifecycle events | | `GET /api/v1/groups` | Enumerate department and team groupings for access scope mapping | | `GET /api/v1/fields` | Retrieve custom field definitions to interpret profile metadata | ## Pagination `GET /api/v1/profiles` returns up to 50 records per page. SureCloud uses the `next` link from the response's `links` object to traverse pages until no `next` link is returned. ``` GET /api/v1/profiles?page=2&per_page=50 ``` `GET /api/v1/events` uses the same link-based pagination. `GET /api/v1/fields` and `GET /api/v1/groups` typically return all records in a single response for accounts with standard configurations. ## Required permissions / scopes SureCloud requests the following OAuth scopes from Namely: | Scope | Purpose | | --------------- | ---------------------------------------------------------------- | | `read:profiles` | Access employee records, employment status, and profile metadata | | `read:events` | Access HR lifecycle event feed for joiner/mover/leaver tracking | | `read:groups` | Access department and team structures | No write permissions are requested or required. ## Polling frequency | Data Type | Interval | | ---------------------------------------------- | -------------- | | Employee profiles and employment status | Every 24 hours | | HR lifecycle events (joiners, movers, leavers) | Every 12 hours | | Department and group structure | Every 24 hours | ## Troubleshooting
OAuth authorisation fails or redirects back with an error This usually occurs when the Namely account used for authorisation does not have API permissions enabled. Ask your Namely administrator to verify that the account has the **API Access** permission under **Roles & Permissions** in the Namely admin panel. Then retry the OAuth flow from **SureCloud → Integrations → Namely → Connect**.
Terminated employees are not appearing in SureCloud Inactive profiles are only returned when SureCloud explicitly queries `?filter[status]=inactive`. If this data is missing, check the integration logs in SureCloud for any 403 errors on that endpoint — some Namely account configurations restrict access to inactive profiles based on HR role. Confirm the authorising account has permission to view terminated employee records in Namely.
Employee count in SureCloud does not match Namely Pagination errors can cause SureCloud to miss records if the Namely API returns an unexpected response mid-traversal. Navigate to **SureCloud → Integrations → Namely** and trigger a manual data refresh. If the count discrepancy persists, check whether your Namely instance has multiple legal entities — SureCloud collects profiles from the entity associated with the authorised account only.
Refresh token expires and connection drops Namely refresh tokens can expire if not used for an extended period. If the integration status shows **Disconnected** or **Token Expired**, reconnect via **SureCloud → Integrations → Namely → Reconnect** and complete the OAuth flow again with an HR Admin account.
--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/namely.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.