Match agents to members

PUT 
/app_installs/:id/agents

Updates agents the app has already reported, matched by external_id (none is ever inserted), and stores each choice how: manual; user_id: null is "No KudosCRM user". Agents not listed are left alone. fallback_owner_user_id sets who owns calls no agent claims (null = the app itself); leave it out to keep it. Any refusal saves nothing: 422 unknown_agent (an id the app has not reported, at /data/attributes/mappings/N/external_id), unknown_user (not an active member), invalid, not_installed. At most 1,000 mappings. integrations.manage. Throttle: app_installs/agents/minute, 120 a minute (outside the write bucket).

A signed-in session or the person's own personal access token; an app's OAuth token is refused (403 resource_not_grantable).

Request

Responses

200

The agents, the first 1,000 by name.

401

No session or token, or one that is no longer valid. A request that presented a token gets WWW-Authenticate: Bearer realm="KudosCRM", error="invalid_token" (refresh it); one with no credentials and no session cookie gets the bare challenge.

Response Headers

WWW-Authenticate
Example: Bearer realm="KudosCRM", error="invalid_token"

403

Not allowed: the permission this route needs is missing, the Integrations module is off (code: module_disabled, meta.module_key, meta.blocked_at_layer), or the caller is an app's own OAuth token (code: resource_not_grantable).

404

Not found in this workspace — or not something the caller may know exists.

422

unknown_agent, unknown_user, invalid (with a pointer), or not_installed.

429

A throttle refused the request. Wait Retry-After seconds — the time left in the refusing window plus 0–3 s of jitter. The X-RateLimit-* headers describe the bucket that refused it.

Response Headers

Retry-After
X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

Seconds until the window rolls.