Olark User Management API Guide

Auth method: API Key (passed as query parameter or HTTP Basic with API key as username)

Setup steps

1. Log in to the Olark dashboard.
2. Navigate to Settings > Integrations > API.
3. Copy the API key displayed for your account.
4. Include the key as the 'apikey' query parameter on all requests, or use HTTP Basic Auth with the API key as the username and an empty password.

List operators

• Method: GET
• URL: https://www.olark.com/api/v1/operators
• Watch out for: Returns only operators under the authenticated account; sub-accounts are not included.

Request example

GET /api/v1/operators?apikey=YOUR_API_KEY HTTP/1.1
Host: www.olark.com

Response example

{
  "data": [
    {"id":"abc123","email":"agent@example.com","nickname":"Agent"}
  ],
  "meta": {"page":1}
}

Get operator

• Method: GET
• URL: https://www.olark.com/api/v1/operators/{id}
• Watch out for: Returns 404 if the operator ID does not belong to the authenticated account.

Request example

GET /api/v1/operators/abc123?apikey=YOUR_API_KEY HTTP/1.1
Host: www.olark.com

Response example

{
  "data": {
    "id":"abc123",
    "email":"agent@example.com",
    "nickname":"Agent",
    "available":true
  }
}

Create operator

• Method: POST
• URL: https://www.olark.com/api/v1/operators
• Watch out for: Creating an operator consumes a paid seat; ensure your plan has available seats before provisioning.

Request example

POST /api/v1/operators?apikey=YOUR_API_KEY HTTP/1.1
Host: www.olark.com
Content-Type: application/json

{"email":"new@example.com","password":"s3cr3t","nickname":"New Agent"}

Response example

{
  "data": {
    "id":"xyz789",
    "email":"new@example.com",
    "nickname":"New Agent"
  }
}

Update operator

• Method: PUT
• URL: https://www.olark.com/api/v1/operators/{id}
• Watch out for: Full PUT semantics; omitting optional fields may reset them to defaults depending on API version.

Request example

PUT /api/v1/operators/xyz789?apikey=YOUR_API_KEY HTTP/1.1
Host: www.olark.com
Content-Type: application/json

{"nickname":"Updated Name","available":false}

Response example

{
  "data": {
    "id":"xyz789",
    "nickname":"Updated Name",
    "available":false
  }
}

Delete operator

• Method: DELETE
• URL: https://www.olark.com/api/v1/operators/{id}
• Watch out for: Deletion is irreversible; the operator's chat history is retained but the seat is freed.

Request example

DELETE /api/v1/operators/xyz789?apikey=YOUR_API_KEY HTTP/1.1
Host: www.olark.com

Response example

{
  "data": {"id":"xyz789","deleted":true}
}

List groups

• Method: GET
• URL: https://www.olark.com/api/v1/groups
• Watch out for: Group membership changes do not trigger any webhook or notification.

Request example

GET /api/v1/groups?apikey=YOUR_API_KEY HTTP/1.1
Host: www.olark.com

Response example

{
  "data": [
    {"id":"grp1","name":"Sales","operator_ids":["abc123"]}
  ]
}

Add operator to group

• Method: POST
• URL: https://www.olark.com/api/v1/groups/{group_id}/operators
• Watch out for: Adding an operator to a group that does not exist returns 404, not a validation error.

Request example

POST /api/v1/groups/grp1/operators?apikey=YOUR_API_KEY HTTP/1.1
Host: www.olark.com
Content-Type: application/json

{"operator_id":"abc123"}

Response example

{
  "data": {"group_id":"grp1","operator_id":"abc123","added":true}
}

• Rate limits: Olark's public REST API does not publish explicit rate limit tiers in official documentation. Practical limits are enforced server-side; exceeding them returns HTTP 429.

• Rate-limit headers: No

• Retry-After header: No

• Rate-limit notes: No documented per-plan rate limit values found in official sources. Treat as unknown; implement exponential backoff on 429 responses.

• Pagination method: offset

• Default page size: 100

• Max page size: 100

• Pagination pointer: page

• Webhooks available: Yes

• Webhook notes: Olark supports webhooks for chat events (chat started, chat ended, transcript available) configured via the dashboard or API. Webhooks are not scoped to operator/user lifecycle events.

• Alternative event strategy: Poll the operators endpoint periodically to detect user-management changes, as no operator lifecycle webhooks are documented.

• Webhook events: chat.started, chat.ended, chat.transcript

• SCIM available: No
• SCIM version: Not documented
• Plan required: Not documented
• Endpoint: Not documented

Limitations:

• No native SCIM endpoint is documented by Olark.
• Provisioning via OneLogin is available through OneLogin's Olark connector, which uses Olark's REST API under the hood rather than a SCIM endpoint.
• Okta integration supports SSO but automated provisioning/deprovisioning is not documented as SCIM-based.

Three automation scenarios are well-supported by the API. Provisioning: POST /api/v1/operators with email, password, and nickname; capture the returned operator id; then POST /api/v1/groups/{group_id}/operators to assign team membership - verify with a GET on the new operator record.

Deprovisioning: locate the operator id via GET /api/v1/operators filtered by email. PUT with available=false to take them offline immediately.

then DELETE /api/v1/operators/{id} to free the seat permanently (deletion is irreversible - export chat history first). Group sync from an external directory: GET operators and groups, diff against your directory state, then issue individual POST or DELETE calls per membership change.

No bulk group-assignment endpoint exists, so large team syncs will be slow and should be rate-limited defensively with exponential backoff on HTTP 429 responses.

Provision a new support agent

1. POST /api/v1/operators with email, password, and nickname to create the operator.
2. Capture the returned operator 'id'.
3. POST /api/v1/groups/{group_id}/operators with the new operator_id to assign to the correct team.
4. Verify by GET /api/v1/operators/{id} and confirm group membership.

Watch out for: Ensure the account has an available paid seat before calling POST /operators; the API may return an error rather than a clear seat-limit message.

Deprovision a departing agent

1. GET /api/v1/operators to find the operator's id by email.
2. PUT /api/v1/operators/{id} with available=false to immediately take the agent offline.
3. DELETE /api/v1/operators/{id} to remove the account and free the seat.

Watch out for: Deletion is permanent; export or archive any needed chat history before deleting.

Sync operator group assignments from an external directory

1. GET /api/v1/operators to retrieve all current operators and their IDs.
2. GET /api/v1/groups to retrieve all groups.
3. Compare external directory group memberships against Olark group memberships.
4. POST /api/v1/groups/{group_id}/operators for each operator that should be added.
5. DELETE /api/v1/groups/{group_id}/operators/{operator_id} for each operator that should be removed.

Watch out for: No bulk group-assignment endpoint exists; each add/remove is a separate API call, which can be slow for large teams.

Several API behaviors require explicit handling. Pagination uses integer page offsets with a hard max of 100 records per page and no cursor support - concurrent writes during a paginated list operation can cause page drift and missed records.

Rate limits are enforced server-side but not documented; no rate-limit headers or Retry-After values are returned, so 429 handling must be implemented blind. Seat limits are enforced at operator creation time and may surface as a 402 or 403 rather than a descriptive error message.

PUT semantics on /operators/{id} are full-replace - omitting optional fields may reset them to defaults. Webhooks cover chat lifecycle events only (chat.started, chat.ended, chat.transcript); there are no operator lifecycle webhooks, so detecting external user-management changes requires polling.

No native SCIM endpoint is documented; the OneLogin connector uses this REST API under the hood rather than a standards-based SCIM layer, which limits interoperability with SCIM-native identity providers.