---
name: icims-oauth-app
description: >-
  Establishes whether an iCIMS API credential can be obtained for a given
  platform and, if so, obtains it — Basic username and password, an HMAC key,
  or an OAuth 2.0 client-credentials client ID and secret, all issued by hand
  by iCIMS staff, never self-serve — with the paid Technology Partner Program,
  the per-customer Customer ID, the regional US/EU/Canada hosts, the
  Integration User group and Security Rules that silently return partial data,
  the 10,000-call daily limit, and a safe credential handoff. Use when asked
  to get iCIMS API or OAuth credentials, register an iCIMS app, become an
  iCIMS Technology Partner, obtain a sandbox, or fix an iCIMS error like
  `access_denied` on the token call, a 401 quoting Basic or
  `x-icims-v1-hmac-sha256`, "Invalid Username or Password credentials
  provided", an empty search, or fields that silently come back missing.
---

# iCIMS API Credentials

**Read this first, because it will probably change the plan: iCIMS has no self-serve developer portal, no "create
app" button, and — for the API that matters here — no OAuth consent screen at all.** Every iCIMS API credential is
configured by a human at iCIMS and handed over through a partner manager, an integration specialist or a support
consultant. iCIMS says so in its own Developer Acceptable Use Policy, in the one sentence that ends most of the
questions this skill gets asked:

> "ICIMS will be responsible for the configuration of both API credentials and user access. API credentials and user
> access shall be issued to the Partner and must not be shared with any third-party without ICIMS' express consent."

And on the customer side, an iCIMS staff answer on iCIMS' own public developer forum, to a customer who had a working
login and expected it to work against the API:

> "The response given is correct. You will need API credentials for your integration build. **That will require a
> customer purchase of an integration license.**"

So there are two honest routes to a working credential, and the choice is commercial before it is technical:

1. **Become an iCIMS Technology Partner** — apply, sign the Master Partner Agreement and the Technology Partner
   Addendum, and pay the annual program fee. As of the fee schedule effective **1 July 2026**, published openly by
   iCIMS: **Connect tier $7,500/yr, Premier tier $12,500/yr**. The unpaid "None" tier exists, and its *only* listed
   benefit is "Custom Integrations Built for Customer" — no partner designation, no persistent developer-site access,
   no sandbox, no integration verification, no Marketplace listing. In other words, **a repeatable integration that
   connects many customers' iCIMS instances is a paid tier; a one-off build for a single named customer is not**
   (§3).
2. **Build per customer, on that customer's own licence.** iCIMS calls this a "Customer Integration with ICIMS":
   built on one mutual customer's specification, "non-repeatable," and explicitly **no sandbox is provided**. Each
   such customer must have bought an integration licence, and each gets one integration account with its own
   10,000-requests-per-day allowance (§4, §7).

Do not start a registration that cannot complete. Establish which route applies (§1, §3) before anything technical.

Once you hold credentials, four things cost real time, and only one of them is authentication: the **Customer ID**,
which is part of every URL path and must be collected from each customer before the first call can be built (§5); the
**region**, because the token host and the API host both change between US, EU and Canada and there is no universal
front door (§5); the **Integration User group and Security Rules**, which decide whether a technically valid
credential returns the customer's data, a subset of it, or nothing at all — with no error (§6); and the **10,000
requests per day licence limit**, which is a contract term, not a throttle (§7).

## Inputs to collect before you start

Ask in one batch. Never invent.

| Input | Notes |
| --- | --- |
| **Which route** | Paid Technology Partner tier, or per-customer builds on each customer's licence? (§1, §3) |
| **Partner status** | Is there a signed Master Partner Agreement and Technology Partner Addendum? Which tier? (§3) |
| **Named mutual customer** | Required for the per-customer route; iCIMS states a mutual customer must be in place before development begins (§3) |
| **Which auth method iCIMS has agreed to** | Basic, HMAC, or OAuth 2.0 client credentials — iCIMS configures it; do not assume (§1) |
| **The customer's Customer ID** | Goes in the URL path of every call. Communicated "at the time of the live integration project" (§5) |
| **Region** | US, EU or Canada — different token host *and* different API host (§5) |
| **Environment** | Temporary Sandbox, Premium Site, or production. Separate credentials and separate hosts (§3, §5) |
| **Which profile types the customer has enabled** | iCIMS: "not all clients have all profile types enabled" (§6) |
| **The integration account's group and security profile** | Search needs the Integration User group; field visibility follows Security Rules (§6) |
| **Static egress IPs** | iCIMS allowlists partner IPs at sandbox setup for some integration types (§7) |
| **Expected daily call volume** | The licensed limit is per integration, per day, and overage is a purchase (§7) |
| **Whether the integration uses AI/ML** | Contractually must be disclosed to iCIMS and to each customer *before* deployment (§9) |

## Quick Start

1. Establish which **route** is legitimately available, and whether the paid partner tier is required for what is
   actually being built (§1, §3). Every wasted month starts here.
2. Confirm whether credentials already exist worth reusing; re-issuing is a human process with a real wait (§2).
3. If partner route: apply, sign the agreements, pay the tier fee, get the Temporary Sandbox (§3).
4. Ask iCIMS for the credentials **by exact name**, and for the auth method in writing (§4).
5. Collect the **Customer ID** and the **region** per customer before building a single URL (§5).
6. Stop looking for consent scopes. Pin down the **Integration User group** and the **Security Rules** on the
   integration account instead (§6).
7. Check the **daily call limit**, the search cache, the retry rule and the no-browser-calls rule before promising a
   launch date (§7).
8. Verify against a **second** customer instance, and against a deliberately under-privileged account (§8).
9. Hand the secret to a human, never to source control (§9).

## Platform state (verified 2026-09-20 — re-verify before trusting)

- **There is no self-serve developer portal.** `developer.icims.com` redirects to the iCIMS Developer Community, whose
  home page (last modified **Sep/17/2026**) says: "New users may request access to ICIMS Developer Community by
  submitting a New User Request form." Most of the technical reference sits behind that login.
- **The authoritative authentication page is login-walled.** `/platform/services/connecting-and-authentication`
  returns **HTTP 403** to an anonymous reader. The 2023-era deep link to the OAuth page
  (`developer.icims.com/authenticating-api-calls-0auth20`, still quoted in forum threads) now redirects to the
  community home page rather than to an OAuth page. **Nothing in this skill about token lifetimes, scope strings or the full OAuth contract should be taken as
  verified** — see "What could not be verified publicly".
- **Credentials are configured by iCIMS, not by you.** Developer Acceptable Use Policy, last modified **28 October
  2025**, quoted above.
- **The partner programme is paid and tiered, and the figures are public.** Fee Schedule and Technology Partner
  Benefits & Requirements, both effective **01 July 2026**: Connect **$7,500**/yr, Premier **$12,500**/yr, unpaid
  "None" tier limited to custom per-customer builds. Premier additionally requires "Turnkey or 2+ Verified
  Integrations" and can buy a Premium Site for **+$10,000**/yr.
- **The API is licensed per customer, per integration.** The Integration Terms page (last modified **Nov/06/2023**)
  describes what a customer's integration licence includes: "One integration account that can be secured with BASIC
  or HMAC authentication" and "Up to 10,000 web services requests per day." Note what that sentence does **not**
  mention: OAuth.
- **OAuth 2.0 nevertheless exists and is in use.** `login.icims.com` publishes a live OpenID configuration
  (fetched anonymously on 2026-09-20) with `token_endpoint: https://login.icims.com/oauth/token` and
  `client_credentials` among `grant_types_supported`; `login.icims.eu` and `login.icims.ca` publish their own. A
  public forum thread shows the exact request — form-encoded `audience=https://api.icims.com/v1/`,
  `grant_type=client_credentials`, `client_id`, `client_secret` — and an iCIMS staff reply: "Client Secret is the one
  provided to you by your engaged support consultant." **It is a machine-to-machine grant. There is no user consent
  screen and no authorization code.**
- **A live, unauthenticated API call advertises only two schemes.** On 2026-09-20, `GET
  https://api.icims.com/customers/1769/jobs/1707` returned **401** with
  `WWW-Authenticate: Basic realm="…", x-icims-v1-hmac-sha256 realm="…"` and the body
  `{"errors":[{"errorMessage":"You must provide authentication details in the Authorization Header using either Basic
  HTTP Authentication or x-icims-v1-hmac-sha256 HTTP Authentication.","errorCode":6}]}`. **Bearer is not advertised.**
  Whether a given customer's instance accepts a bearer token is a per-customer configuration question for iCIMS, not
  something to assume from this header or from anyone's working example.
- **Field and record visibility follows the platform, not the API.** Profiles API reference (public, last modified
  **Jun/28/2024**): "if a user does not have access to a field in the Platform, they will not be able to return that
  field via ICIMS Profiles API. These permissions are based on the credentials provided in the Authorization header."
- **Search requires a specific group.** Search API reference (public, last modified **Jul/24/2025**): "In order to
  utilize the Search API, a user must be part of the Integration User group." Same page: results are capped at 1,000
  per call, and search results are **cached for 15 minutes by default** unless you pass `staleness=0`.
- **Browser and desktop calls are contractually prohibited.** AUP: "ICIMS endpoints cannot be accessed from mobile
  applications, Developer workstations or web browsers. This is a design requirement that you must address in any
  solution being developed in the ICIMS Marketplace to avoid rejection."
- **The Developer Terms of Use were last modified 30 June 2026** and are materially heavier than most vendors':
  SOC 2 Type II or ISO 27001 (or equivalent) with the report produced on request, iCIMS-initiated security
  assessments and penetration testing, 24-hour breach notification to `generalcounsel@icims.com`, minimum-necessary
  data access, no onward disclosure of customer data, and **no training or fine-tuning any model on customer data
  without express prior written consent**.
- **Rate-limit *fees* are real.** The public FAQ: "Yes, ICIMS does institute limitations, and integration fees."

If the developer community, the partner legal page or the fee schedule do not look like this, stop and report what
you actually see.

## 1. Which credential, and who is allowed to hold it

A reader arriving here is usually holding the wrong thing, or expecting a flow that does not exist.

| Surface | Credential | Hosts | Who gets it |
| --- | --- | --- | --- |
| **REST API — HTTP Basic** | API username + password on an *integration account* configured by iCIMS | `api.icims.com` / `api-eu.icims.com` / `api-ca.icims.com`, always under `/customers/{customerId}/…` | Issued by iCIMS to the partner or to the customer's developer, on a purchased integration licence |
| **REST API — HMAC** | `x-icims-v1-hmac-sha256` signing key | Same | Same. Named in the Integration Terms alongside Basic as what an integration licence includes |
| **REST API — OAuth 2.0, client credentials** | `client_id` + `client_secret`, exchanged with an `audience` parameter for a bearer token | Token at `login.icims.com` / `login.icims.eu` / `login.icims.ca`; API on the matching `api*` host | Issued by an iCIMS support consultant / integration specialist. **No consent screen, no authorization code, no redirect** |
| **Prime / connector-framework endpoints** (background screening and similar "Prime" integrations) | Signed **JWT** with `sub`, `iss`, `iat`, `exp`, shared signing key, plus **IP allowlisting** | Per-integration endpoints, allocated with the sandbox | Partners on a Prime integration, from the ISV enablement team when the sandbox is allocated |
| **Developer Community site login** | Personal named account, requested through the New User Request form | `developer.icims.com` | Anyone iCIMS approves. **This is documentation access, not API access** |

Consequences worth saying out loud before anyone starts work:

- **"iCIMS credentials" is ambiguous and the ambiguity costs a week.** A customer contact will often send their own
  Talent Platform login. It will not work: the public forum contains this exact mistake repeatedly, with the 401
  `"Invalid Username or Password credentials provided."` and the staff answer that an integration licence is
  required. Ask by exact name for the **API username and password** (or the **OAuth client ID and client secret**)
  **and the Customer ID**, separately.
- **There is no authorization-code flow to build.** Do not design a "Connect with iCIMS" consent screen. The customer
  does not click through anything on iCIMS' side; they (or iCIMS) hand you a credential out of band, and you collect
  their Customer ID in your own UI.
- **The credential is bound to a platform *user account* and therefore to that account's permissions.** There is no
  app identity with its own permission set. See §6 — this is the single biggest source of "it works for us and
  returns nothing for them."
- **Sandbox and production are different instances with different hosts and different credentials.** A sandbox
  credential says nothing about production.
- **Do not build the browser-side version.** The AUP forbids calling iCIMS endpoints from browsers, mobile apps or
  developer workstations; it is a stated rejection criterion at validation.

> **Product fact — dated.** As of **2026-09-20**, this platform's iCIMS connector supports **two** authentication
> modes and ships **no shared credentials** — every workspace supplies its own, which in practice means its own
> relationship with iCIMS. The first mode collects **three** values from the customer, in this order — **API
> Username, API Password, Customer ID** — and sends the first two as **HTTP Basic** on every request. The second
> mode is labelled OAuth 2.0 but is a **two-legged client-credentials exchange**: it POSTs form-encoded
> `grant_type=client_credentials` with the workspace's client ID and client secret **as request parameters** (not an
> HTTP Basic header) plus the region's `audience` value to the region's token endpoint, and then sends the returned
> token as `Authorization: Bearer …`. It records **four** regional profiles: **United States** (`api.icims.com`,
> token `login.icims.com`, audience `https://api.icims.com/v1/`), **Europe** (`api-eu.icims.com`,
> `login.icims.eu`), **Canada** (`api-ca.icims.com`, `login.icims.ca`) and **Sandbox** (`api.dev.icims.com`,
> `login.dev.icims.com`). It records a per-object permission map using strings of the shape
> `irecruiter:<object>:<read|write>` over `people`, `jobs`, `applicantworkflows` and `onboardworkflows`, and its
> customer-facing note says the three values come from "your iCIMS integration specialist" and that API access must
> be requested from the customer's iCIMS rep beforehand. Its reads are built on the **Search API** — one search for
> IDs, then a fetch per ID — with a page size of 100. **Confirm all of this with the connector's owner before acting
> on it** — connector configuration changes independently of this skill.

## 2. Reuse the existing credentials, or request new ones

There is no console in which to rotate anything, so every change is a human request with a real wait. Reuse what
exists for: adding a customer, changing the permissions on an existing integration account, diagnosing a failure, or
raising the call limit — none of those need a new credential. Request a **new** credential only when the user
explicitly wants one: a new environment (sandbox and production are separate by design), a replacement for a
compromised secret, or a genuinely separate integration.

Two iCIMS-specific wrinkles pull in opposite directions and are worth stating before anyone decides:

- **Each customer's integration licence carries its own 10,000-call daily allowance** (§7). Volume does not pool
  across customers, and it does not pool across a partner's whole estate the way a single shared client ID would.
- **Fees and credentials are linked contractually.** Under the Technology Partner Addendum, invoices unpaid 30 days
  past due let iCIMS "terminate the Integration for any and all integrated Subscribers." A lapsed partner fee is not
  a billing footnote; it is an outage for every customer at once.

## 3. The gate: Technology Partner Program, tiers and sandboxes

This section applies when the **platform** wants a repeatable integration across many customers.

**Entry point:** apply through iCIMS (`https://community.icims.com/s/apply`, linked from the partner pages), then
sign the **Master Partner Agreement** plus the **Technology Partner Addendum**. Both, plus the Fee Schedule and the
tier table, are published on `https://www.icims.com/partner/gc/` — read them before quoting anything to the user.

**The tiers, effective 01 July 2026** (from iCIMS' published Benefits & Requirements table):

| | None | Connect | Premier |
| --- | --- | --- | --- |
| Annual program fee | n/a | **$7,500** | **$12,500** |
| Custom integrations built for one customer | yes | yes | yes |
| Partner designation, persistent developer-site access, enablement team | — | yes | yes |
| **Partner Integration Verification** | — | yes | yes |
| **Temporary Sandbox** | — | yes | yes |
| Marketplace listing with lead form | — | standard | prioritized |
| Eligible to build a Rapid Activation integration | — | — | yes |
| Eligible to purchase a Premium Site | — | — | **+$10,000/yr** |
| Requirements | — | apply online, sign agreements | + "Turnkey or 2+ Verified Integrations" |

**The build-and-approve sequence**, as iCIMS publishes it: review the developer resources and the existing
Marketplace integrations → design against the documented process and standard fields → **reach out to your iCIMS
Partner Manager to schedule a call with the iCIMS Developer Support Team**, who review the business use case →
**once approved**, iCIMS issues validation requirements and sets up a sandbox → build and test → submit for
validation.

**Validation** is a real review, not a form: an end-to-end **video** of the working integration recorded in the
iCIMS-provided sandbox, plus screenshots proving 400-with-a-user-friendly-message handling for a **duplicate request**
and for a **missing required field**, plus a written statement of every field read and written by profile type and
access level, plus the information a customer needs to enable the integration (authentication method, IPs to
allowlist, package IDs, optional features, partner credentials, Customer ID). iCIMS adds the rule that matters most
to a multi-tenant platform: **"values that will differ across client platforms shouldn't be hardcoded."**
**Revalidation** can be demanded later — within 90 days of notice, or 1 year for a newly mandatory feature — and
failing it can mean removal from the Marketplace and calls "suspended at ICIMS' sole discretion."

**Sandboxes**, from the Addendum and the AUP:

- **Temporary Sandbox** — free with Connect/Premier, **12 weeks**, extensions at iCIMS' discretion, up to **5 users**
  from your organisation, provisioned "generally within five (5) business days," no live data, **no iCIMS support**,
  and explicitly **not** for demos, workflow exploration or screenshots. iCIMS repeats the point on the public
  getting-started page: "The ICIMS Sandbox is prohibited for customer integration testing and customer demo usage,
  and is subject for partner removal."
- **Premium Site** — $10,000/yr, Premier only, 3 technical + 5 demo users, ~10 business days, dummy data only, no
  customisation, no system-administrator access, and only iCIMS-validated integrations may be demoed on it. Buying
  one **replaces** the Temporary Sandbox rather than adding to it.
- **Per-customer route: no sandbox at all.** iCIMS states that customer-specific integrations are built directly on
  each customer platform.

What this section deliberately does not tell you, because iCIMS does not publish it: how long approval takes, what
the security questionnaire contains, whether a unified-API layer is accepted as a Technology Partner, and whether any
given customer's instance will be configured for OAuth. **All four are questions for iCIMS, and three of them are
business decisions.** Do not fill in security, compliance or commercial claims on the user's behalf — collect the
questions and hand them back.

**If this session has no browser automation** (the usual case for a CLI or cloud run), do not pretend to click. Give
the user an ordered path with the literal values to paste, or a ready-to-send message to the partner manager or to
`developerhelp@icims.com`, then continue once they report back.

## 4. Asking iCIMS for the credentials

There is no form and no self-service. Who you ask depends on the route:

| Situation | Ask |
| --- | --- |
| Partner, integration already approved | Your **iCIMS Partner Manager** / the **Developer Support Team** |
| Partner, technical problem with a sandbox or credential | `developerhelp@icims.com` (the Technology Partner help desk named in the Addendum) |
| Building for one customer | The **iCIMS resource already engaged with that customer** — the partner application page tells developers without an iCIMS contact to get it from their customer contact |
| Documentation access only | The **New User Request form** on the developer community |

**Put all of this in the first message**, because each round trip is business days:

- That you are requesting **REST API credentials for an integration**, and for which **environment** (sandbox or
  production) — one request per environment.
- **Which authentication method** is being configured: Basic, HMAC or OAuth 2.0 client credentials. Ask iCIMS to
  state it in writing; do not infer it from a working example on a different customer.
- The **integration name and purpose**, and the named customer if this is a per-customer build.
- The **Customer ID(s)** the credential must be entitled to reach, and the **region** (§5).
- The **egress IP addresses** to allowlist, if the integration type requires it (§7).
- The **group and permissions** the integration account needs — say "Integration User group" explicitly, and name the
  profile types and fields the integration reads and writes (§6). This is the step everyone skips and everyone pays
  for later.

**What comes back.** iCIMS' public FAQ: "To make a call you must first establish your authentication method with
ICIMS. ICIMS should then communicate back user credentials to allow inbound access to make calls." Expect the values
by email or through a support case, expect no console to re-read them in, and store them immediately. Rotation is
another request to the same human.

## 5. The Customer ID, the region, and the redirect URI that does not exist

### There is no redirect URI to register with iCIMS

The documented iCIMS OAuth grant is **client credentials**. No browser leaves your platform, no consent screen is
shown, and **no callback URL is registered with iCIMS**. If someone asks which redirect URIs to send to iCIMS, the
answer is none — and if an iCIMS contact asks you for one, stop and find out which product they actually mean (the
Prime/JWT and webhook-style integrations have their own endpoint and IP-allowlist requirements, §7).

For completeness, and because they get asked for in the same conversation, this platform's own callback hosts — one
per data centre — are:

```
https://api.unified.to/oauth/code          # us (default)
https://api-eu.unified.to/oauth/code       # eu
https://api-au.unified.to/oauth/code       # au
https://api-dev.unified.to/oauth/code      # dev
```

> **Product fact — dated.** As of **2026-09-20**, the connector's "connect" step for iCIMS never sends the customer
> to an iCIMS page. It collects the **Customer ID** in the platform's own UI, immediately returns to the platform's
> own callback carrying that value where an authorization code would normally go, and then performs the
> client-credentials token call server-side. The token it stores is the access token, and its "refresh" simply
> re-runs the same client-credentials exchange — there is no refresh token in this flow. Consequently the four
> callback hosts above are internal to the platform and are **not** registered anywhere at iCIMS. **Confirm this
> with the connector's owner before acting on it.**

### The Customer ID

**Every iCIMS API path contains the customer's numeric Customer ID**, immediately after `/customers/`. iCIMS' own
public example: `https://api.icims.com/customers/1769/jobs/1707/?fields=bgcpackagetype`. You cannot build a single
URL without it, which is why it must be collected on the connect form rather than discovered from a token.

- **Where it comes from:** iCIMS' FAQ says "Client ID's will be communicated at the time of the live integration
  project. This information is also included in the payload of the outbound ICIMS messages." In practice the
  customer or the iCIMS implementation contact tells you; it is also visible in the customer's own platform URLs.
- **Never hardcode it, and never hardcode anything else that varies per customer.** iCIMS makes this an explicit
  validation requirement (§3).
- **A wrong Customer ID does not fail cleanly.** The unauthenticated probe in Platform state shows the API answering
  for an arbitrary customer number with a generic 401 rather than "no such customer", so a typo looks like an auth
  problem, not a routing one.

### The region

Three production regions, each with its **own token host and its own API host**, and a separate sandbox estate:

| Region | API host | Token host | `audience` |
| --- | --- | --- | --- |
| United States | `api.icims.com` | `login.icims.com` | `https://api.icims.com/v1/` |
| Europe | `api-eu.icims.com` | `login.icims.eu` | the EU equivalent — confirm with iCIMS |
| Canada | `api-ca.icims.com` | `login.icims.ca` | the CA equivalent — confirm with iCIMS |
| Sandbox | issued with the sandbox | issued with the sandbox | issued with the sandbox |

All three `login.*` hosts published a live OpenID configuration when probed anonymously on 2026-09-20. The API hosts
resolve and answer. **The `audience` values for EU and CA are not published on any public iCIMS page** — the only
one visible anywhere public is the US value, in a forum post. Get the others from iCIMS in writing rather than
pattern-matching, and treat a pattern-matched guess as the most likely cause of an `access_denied` you cannot explain
(§8).

Sandbox URLs are issued with the sandbox. A public forum exchange shows exactly this going wrong — a developer with a
valid sandbox, Customer ID, client ID and secret getting `access_denied` because they were pointing at the wrong
host, and iCIMS replying "You should have been provided a sandbox URL as well."

## 6. There are no consent scopes — groups, Security Rules and the silent failure

**This is the section to read twice.** iCIMS has no consent screen, no scope checklist a customer approves, and no
token response that tells you what you may do. What the integration can see and change is decided entirely inside the
customer's iCIMS configuration, by the permissions on the account behind your credential. iCIMS states the model
plainly in its public Profiles API reference:

> "The interaction of Profiles through the Profiles API will generally follow the same conventions as if a user were
> to access the information through the ICIMS Talent Platform. … if a user does not have access to a field in the
> Platform, they will not be able to return that field via ICIMS Profiles API. **These permissions are based on the
> credentials provided in the Authorization header.**"

**For a field to come back on a GET, iCIMS requires all five of these to be true:**

1. It **has a value**.
2. It is **not hidden by attribute configuration settings**.
3. It is **not hidden by Security Rules**.
4. It is **not hidden by Search Locks**.
5. It is **not hidden by Profile layout configuration** — the tab the field sits on must not be hidden.

**For a POST or PATCH**, the same list applies, plus the field must pass field-specific validation and must not be
**locked** by attribute configuration. iCIMS notes two consequences that look like bugs and are not: a profile locked
in attribute configuration can be **created but not updated**; and POST/PATCH validate *all* required fields for the
profile's folder and roles, so an update can fail because of a field you never touched.

**Why this is the classic ATS silent failure.** A missing permission does not produce a 403 with an explanation. It
produces a field that simply is not in the JSON, or a profile type that returns nothing, or a search that finds no
records. Any mapping that treats "absent" as "the customer has no data" will confidently report an empty ATS.

**Three specific traps:**

- **The Integration User group gates search entirely.** iCIMS: "In order to utilize the Search API, a user must be
  part of the Integration User group." A connector that lists records by searching first — most do — returns nothing
  at all for a customer whose integration account was created outside that group. Ask for it by name when the account
  is configured (§4).
- **Permission problems can surface as syntax errors.** One documented search error is "The following filter is
  either not valid **or hidden**: [filter]" — the same message for a typo and for a field the account may not see.
- **Not every customer has every profile type.** iCIMS: "Note that not all clients have all profile types enabled."
  The documented set is `people`, `jobs`, `companies`, `newhirecategories`, `talentpools`, `rooms`, `connectevents`.
  An integration that assumes a profile type exists will fail on a subset of customers for reasons no credential
  change can fix.

**Practical consequences.** Ask each customer's iCIMS administrator, in writing, for an integration account in the
Integration User group with visibility of the specific profile types and fields you need, and make that list part of
your onboarding documentation — it is the same list iCIMS makes you produce at validation anyway (§3). When a
customer reports missing data, your first question is about Security Rules, Search Locks and tab visibility, not
about the credential.

Because there are no scopes, **adding a feature never requires re-consent** — it requires the customer's
administrator to widen the integration account's permissions. Own that conversation.

## 7. Limits, caching, retries, and what the contract forbids

**The daily limit is a licence term.** From the Integration Terms page, for what an integration licence includes:

| Limit | Value |
| --- | --- |
| Web service requests per day ("Allowable Daily Limit") | **10,000**, per integration |
| Burst tolerance | Up to **5×** the daily limit on a given day without being denied |
| Enforcement | iCIMS averages your **previous 90 days**; exceed the average and you must buy an increase within 30 days or be hard-limited |
| Call Limit Increase | Purchased in blocks of **10,000** requests/day; iCIMS reserves the right to cap how many a single integration may buy |
| Search results per call | **1,000**, paged by filtering on the last returned ID |
| Search cache | **15 minutes by default**; `staleness=0` forces a live search, and the cache is shared across users running the same search |

And the parts that change the arithmetic:

- **Exceeding the limit halts the integration.** The AUP: "Exceeding the daily limit may halt functionality of that
  Integration until the next calculation period, resulting in a service interruption of the Integration." Not a
  throttle — a stop, until tomorrow.
- **The limit is per customer's integration, not per partner.** That is gentler than a shared per-client-ID budget,
  but it means capacity is a *customer-by-customer* conversation and an ID-then-fetch read pattern (one search plus
  one call per record) burns the allowance far faster than it looks. Count calls per sync before promising a
  frequency.
- **Retries must use exponential back-off.** The AUP permits retry logic "provided that Developer only uses retry
  logic that leverages an exponential back-off approach." A fixed-interval retry loop is a policy violation, not just
  bad manners.
- **Search is not a real-time API.** iCIMS: "At this time, ICIMS does not support real-time usage of the Search API.
  The Search API is currently optimized for synching data between two different systems in the background." If your
  product promises live search over iCIMS, that promise is at odds with the documentation.
- **Mind the 15-minute cache when polling for changes.** A sync that filters on an updated-date and does not set
  `staleness` can miss records written in the last quarter of an hour and then never revisit them, because the next
  poll's window has already moved past.
- **No browser, mobile or workstation calls** (AUP, §1).
- **iCIMS may change the API with ~30 days' notice**, and the Addendum makes adapting your problem, at your expense,
  with a 30-day remediation window before suspension. iCIMS may also **disable an integration immediately, without
  notice**, on suspicion of fraud, abuse or a security threat.
- **IP allowlisting exists for some integration types**, applied at sandbox setup from the list your partner contact
  supplies, with additions by request. If your egress is autoscaled or serverless with no stable addresses, surface
  that before launch — it is an infrastructure decision, not a support ticket.
- **Listing** on the iCIMS Marketplace requires an approved integration, the tier that includes listing, and iCIMS'
  sole-discretion approval. You may not describe the integration as complete, certified or validated — or hold
  yourself out as an iCIMS partner — before iCIMS says so in writing.

## 8. Verify end-to-end

Do not stop at "the token came back," and do not stop at "one customer works."

1. Confirm **which auth method** the customer's instance is actually configured for. If you are using a bearer token,
   confirm with iCIMS in writing that it is enabled for that Customer ID — the live 401 advertises only Basic and
   HMAC (Platform state).
2. Make one real read against a **second** customer instance, ideally in a **different region**, using hosts and the
   `audience` resolved from configuration rather than hardcoded.
3. Run a **search**, not just a fetch by ID. Search is the path that requires the Integration User group, so it is
   the test that catches the most common permission failure (§6).
4. Repeat step 3 with `staleness=0` and compare against the cached result. If your sync depends on freshness, prove
   it now rather than explaining a 15-minute data gap later.
5. Read a profile you know has values in fields you care about, and **diff the returned field set against what the
   customer sees in their platform**. Missing fields here mean Security Rules, Search Locks or a hidden tab — not a
   bug in your mapper.
6. Repeat step 5 as a **deliberately under-privileged** account and confirm your code reports a permission problem
   rather than reporting "no data."
7. Exercise a create and an update, and confirm you handle the two documented traps: a **locked profile** that
   accepts POST but refuses PATCH, and a PATCH that fails on required fields you did not send (§6).
8. Count the calls a full sync makes for a realistic customer and compare against **10,000/day** (§7).
9. Confirm your retry path backs off exponentially and has no fixed-interval loop.

| Symptom | Cause |
| --- | --- |
| `401` with `WWW-Authenticate: Basic …, x-icims-v1-hmac-sha256` | No credentials sent, or bearer sent to an instance not configured for OAuth (§1, Platform state) |
| `401 "Invalid Username or Password credentials provided." (errorCode 6)` | A Talent Platform user login used as an API credential; no integration licence / integration account (§1, §4) |
| `401 {"error":"access_denied","error_description":"Unauthorized"}` on the token call | Wrong client ID/secret, wrong `audience`, wrong regional token host, or credentials not yet activated by iCIMS (§5) |
| Token works in sandbox, `access_denied` in production (or vice versa) | Separate instances, separate credentials, separate hosts; the sandbox URL is issued with the sandbox (§3, §5) |
| Works for US customers, fails for EU/Canada | Hardcoded token host, API host or `audience` instead of per-customer configuration (§5) |
| 404s on paths that should exist | Wrong or missing Customer ID in the path (§5) |
| **Search returns nothing, no error** | Integration account is not in the **Integration User group** (§6) |
| **A field the customer can see is simply absent from the JSON** | Hidden by Security Rules, Search Locks, attribute configuration or a hidden profile tab — iCIMS returns absence, not an error (§6) |
| "The following filter is either not valid or hidden: [filter]" | Either a genuinely wrong filter name, or a field this account may not see (§6) |
| A whole profile type returns nothing for one customer | That customer does not have that profile type enabled (§6) |
| POST succeeds, PATCH refuses on the same profile | Profile is locked in attribute configuration — documented behaviour, mirrors the platform (§6) |
| PATCH fails complaining about fields you never sent | Required-field validation runs across the profile's folder and roles (§6) |
| Sync misses records written minutes ago | 15-minute default search cache; pass `staleness=0` or widen the window (§7) |
| Integration stops for the rest of the day | Allowable Daily Limit hit; functionality halts until the next calculation period (§7) |
| Calls fine for 90 days, then throttled or invoiced | Rolling 90-day average exceeded the Allowable Daily Limit (§7) |
| Requests rejected from a new region or new worker pool | Partner egress IPs allowlisted at sandbox/integration setup (§7) |
| Integration disabled with no warning | Emergency disabling on suspicion of fraud, abuse or security threat (§7) |
| Customer cannot get credentials at all | No integration licence purchased, or no engaged iCIMS resource (§1, §4) |

## 9. Hand off — never commit the secret

- **Do not** write an API password, client secret, HMAC key or JWT signing key into source control, a test, a
  fixture, a committed `.env`, a ticket, a PR body or a chat channel. iCIMS makes this contractual: under the
  Developer Terms of Use, credentials are Confidential Information, "Developer's account is personal to Developer and
  may not be shared with, transferred to, or used by any other person or entity," and under the AUP credentials
  "must not be shared with any third-party without ICIMS' express consent."
- **A Customer ID is not a secret, but it is customer-identifying.** Keep it out of public issues and marketing
  examples anyway.
- If a code change is needed (a regional host, the Customer ID plumbing, retry behaviour), keep it secret-free and
  say plainly what the human must set out of band.
- Report a secret once so it can be pasted into the secret store, say clearly that it is now in the transcript and
  can be rotated by asking iCIMS, then move on.
- **Say the compliance obligations out loud**, because they are easy to breach by accident and they are in the
  signed agreements: 24-hour breach notification to iCIMS; SOC 2 Type II or ISO 27001 evidence on request; iCIMS'
  right to run security assessments and penetration tests; minimum-necessary data access; no onward disclosure of
  customer data; advance written notice to each customer that their data leaves iCIMS; and **no model training or
  fine-tuning on customer data — even de-identified or aggregated — without that customer's express prior written
  permission, which iCIMS can demand evidence of.** If the platform exposes iCIMS data to an AI feature, the
  Technology Partner Addendum also requires disclosing that in writing to iCIMS and to each customer **before
  deployment**.
- Close with: which route you ended on and whether iCIMS has agreed in writing; the tier and its fee, if any; which
  auth method each customer is configured for; the Customer IDs and regions in play; where the secret was delivered;
  the permissions the customer's administrator must grant, in words they can act on (Integration User group, profile
  types, fields); the daily call budget against your expected volume; and whatever is still waiting on iCIMS.

## Stop and ask

Hand back to a human rather than guessing when: **the platform is a connector, middleware or unified-API layer with
no signed iCIMS partner agreement** and the ask is a repeatable multi-customer integration — say in the first reply
that the repeatable route is a paid tier and the free tier covers only custom per-customer builds; the partner
agreement, fee, security assessment or validation engagement needs business, security or compliance claims; a
customer cannot produce an integration licence; iCIMS has not confirmed **in writing** which authentication method a
customer's instance is configured for, or the `audience` value for a non-US region; a customer's data is missing and
the fix requires changing their Security Rules, Search Locks or account group (that is their administrator's call,
not yours); expected volume approaches 10,000 calls/day for any customer; the integration will expose iCIMS data to
an AI or ML feature, or train on it; egress IP allowlisting requires decisions about static addresses; or the
developer community, the partner legal page and the fee schedule no longer match the Platform state section above.

## What could not be verified publicly

iCIMS' technical reference is largely behind a login, and this skill was written without one. Everything above came
from iCIMS-owned pages that answer to an anonymous reader, from iCIMS' published partner legal documents, and from
direct anonymous probes of iCIMS hosts on 2026-09-20. The following are **not** publicly verifiable and are stated
here as gaps rather than filled in:

- **The authoritative authentication page.** `https://developer-community.icims.com/platform/services/connecting-and-authentication`
  returns **HTTP 403** to anonymous readers — *login-walled*. So does the Applications index
  (`/applications/icims-applicant-tracking`) and most of the product-specific documentation. The older OAuth deep
  link `https://developer.icims.com/authenticating-api-calls-0auth20`, quoted in a 2023 forum thread, now redirects
  to the community home page instead of to that content.
- **Access token lifetime and the exact token response shape.** Not on any public iCIMS page. Drive re-authentication
  off the response and the 401; do not hardcode a TTL from a blog post.
- **Whether OAuth is available to every customer, or only on certain products, contracts or newer instances.** The
  Integration Terms page names only BASIC and HMAC as what an integration licence includes, and the live 401
  advertises only those two — yet OAuth demonstrably exists. **Confirm per customer with iCIMS.**
- **The `audience` values for the EU and Canada regions**, and the sandbox token host's configuration
  (`login.dev.icims.com` returned 403 to an anonymous metadata request).
- **Whether iCIMS scopes an OAuth client to specific Customer IDs, and how a scope string is spelled.** The
  `irecruiter:<object>:<read|write>` shape appears in this platform's connector configuration; it is **not**
  documented on any publicly reachable iCIMS page. Treat it as unverified.
- **Any per-second or per-minute rate limit.** Only the 10,000/day licence limit is public.
- **How long partner approval, credential issuance or validation actually take**, and what the security questionnaire
  contains.
- **Whether a unified-API or middleware platform is accepted as an iCIMS Technology Partner at all.** iCIMS publishes
  no prohibition — unlike some ATS vendors — but it also reserves sole discretion to reject any integration,
  including one "competitive with and/or that offers overlapping capabilities with the ICIMS Subscription." That is a
  commercial conversation to have with iCIMS in writing, early.

Two iCIMS legal PDFs cited here (the Fee Schedule and the Technology Partner Benefits & Requirements) are published
openly on iCIMS' own partner legal page while carrying a "Confidential Business Information" footer. They are quoted
as published, and both should be re-fetched rather than trusted from this page — iCIMS may change the fees with 60
days' notice.

## References

Every URL below returned HTTP 200 to an anonymous reader on 2026-09-20.

- iCIMS Developer Resources home (access is by request; New User Request form) — https://developer.icims.com/
- iCIMS Developer Community — https://developer-community.icims.com/
- Getting Started: Integrating with ICIMS (partner vs customer integration, approval sequence, validation requirements, sandbox restrictions, "values that will differ across client platforms shouldn't be hardcoded") — https://developer-community.icims.com/getting-started/integrating-icims
- Partner Application Process (apply to be a partner; User Request Form for customer-behalf developers) — https://developer-community.icims.com/getting-started/partner-application-process
- Developer FAQ (rate limitations and integration fees; Customer IDs communicated at project time; the `/customers/{id}/…` example; `X-HTTP-Method-Override` for PATCH) — https://developer-community.icims.com/faq
- Integration Terms (BASIC or HMAC on one integration account; 10,000 requests/day; 5× burst; 90-day averaging; Call Limit Increases) — https://developer-community.icims.com/integration-licenses
- Developer Terms of Use, last modified 30 June 2026 (credentials as Confidential Information; no account sharing; SOC 2/ISO 27001; security assessments; 24-hour breach notice; minimum-necessary data; AI/ML training restrictions) — https://developer-community.icims.com/terms-use
- Developer Acceptable Use Policy, last modified 28 October 2025 ("ICIMS will be responsible for the configuration of both API credentials and user access"; exponential back-off; no browser/mobile/workstation calls; Temporary Sandbox and Premium Site limits) — https://developer-community.icims.com/acceptable-use-policy
- Profiles API reference (permission model, the five GET visibility conditions, POST/PATCH rules, profile types, locked profiles, role validation) — https://developer-community.icims.com/applications/applicant-tracking/profiles-api
- Search API reference (Integration User group requirement; 1,000 results per call; paging; `staleness` and the 15-minute default cache; not for real-time use; error messages) — https://developer-community.icims.com/applications/applicant-tracking/search-api
- Developer forum — https://developer-community.icims.com/forum
- Forum: "Authentication" (iCIMS staff: API credentials require a customer purchase of an integration license; Prime JWT; IP allowlisting at sandbox setup) — https://developer-community.icims.com/forum/authentication
- Forum: "OAuth JWT Not WOrking" (the exact `login.icims.com/oauth/token` client-credentials request with `audience`; iCIMS staff: the client secret comes from your engaged support consultant) — https://developer-community.icims.com/forum/oauth-jwt-not-working
- Forum: "Unable to authenticate with OAuth 2.0" (`access_denied` caused by the wrong sandbox URL) — https://developer-community.icims.com/forum/unable-authenticate-oauth-20
- Developer Community user request form — https://developer-community.icims.com/user-request-form
- Developer Community release notes — https://developer-community.icims.com/release-notes
- Developer Community contact (`developerhelp@icims.com`) — https://developer-community.icims.com/contact
- iCIMS partner legal documents (Master Partner Agreement, Technology Partner Addendum, Fee Schedule, tier tables) — https://www.icims.com/partner/gc/
- Fee Schedule, effective 01 July 2026 (annual program fee by tier; Demo Site $10,000/yr) — https://cdn31.icims.com/wp-content/uploads/2026/07/01133141/Fee_Schedule_01JULY2026.pdf
- Technology Partner Benefits & Requirements, effective 01 July 2026 (None / Connect $7,500 / Premier $12,500; what each tier includes) — https://cdn31.icims.com/wp-content/uploads/2026/07/10115540/ICIMS-Technology-Partner-Benefits-and-Requirements-01July2026.pdf
- Technology Partner Program Addendum, 01 July 2026 (integration approval, 12-week Temporary Sandbox, Premium Site, emergency disabling, security audits, AI/ML restrictions, fee non-payment terminating integrations) — https://cdn31.icims.com/wp-content/uploads/2026/07/03162830/Technology-Partner-Addendum-01JULY2026.pdf
- Master Partner Agreement, 01 July 2026 — https://cdn31.icims.com/wp-content/uploads/2026/07/01112408/Master-Partner-Agreement-01JULY2026.pdf
- iCIMS general legal documents (Subscriber Data Security Addendum, Support & Maintenance Policy) — https://www.icims.com/gc/
- iCIMS Partner Experience — https://www.icims.com/community/partner-experience/
- Become an iCIMS Partner (technology vs advisory partners) — https://www.icims.com/community/partner-experience/become-a-partner/
- iCIMS partner application — https://community.icims.com/s/apply
- iCIMS Customer Community — https://community.icims.com/s/
- iCIMS Marketplace — https://marketplace.icims.com/
- US OpenID configuration (token endpoint and supported grants, probed anonymously) — https://login.icims.com/.well-known/openid-configuration
- EU OpenID configuration — https://login.icims.eu/.well-known/openid-configuration
- Canada OpenID configuration — https://login.icims.ca/.well-known/openid-configuration