Roistat

The gem sends every request with the Api-key header (never as a key query param). Project-scoped calls also send project in the query string.

Official docs differ by language. Prefer help-ru for the method list. help-en documents additional endpoints (dashboards, widgets, and alternate access/counter paths); this gem wraps those as well.

Installation
Configuration
Clients
Low-level HTTP API
Resource APIs
- Projects
- Access
- Dashboards
- Widgets
- Billing
- Calltracking
- Orders
- Proxy leads
- Leads
- Managers
- Clients
- Visits
- Events
- Analytics
- Channels
- Statistics
- Indicators
- Lead hunter
- Email tracking
- SMS
- Mediaplan
- Speech analytics
- Cloud PBX (VPBX)
Responses
Errors
Development
License

Installation

Add the gem to the Gemfile:

gem "roistat"

Then run:

bundle install

Or install it directly:

gem install roistat

Rails

Generate the initializer:

rails generate roistat:install

This creates config/initializers/roistat.rb with all configuration options.

Configuration

Global config (Rails-friendly)

Roistat.configure do |config|
  config.api_key = ENV.fetch("ROISTAT_API_KEY")
  config.project = ENV.fetch("ROISTAT_PROJECT_ID")

  # Optional:
  # config.base_url = "https://cloud.roistat.com/api/v1"
  # config.timeout = 30
  # config.open_timeout = 10
  # config.binary_tempfile_threshold = 1_048_576
end

Then use the shared client:

Roistat.client.projects.list

Configuration options

Option	Required	Default	Description
`api_key`	yes	—	Roistat API key (`Api-key` header)
`project`	yes for project-scoped calls	—	Project id (query `project`)
`base_url`	no	`https://cloud.roistat.com/api/v1`	API base URL
`timeout`	no	`30`	Request timeout in seconds
`open_timeout`	no	`10`	Connection open timeout in seconds
`binary_tempfile_threshold`	no	`1048576` (1 MiB)	Binary bodies larger than this become a `Tempfile`

Environment variables (install generator)

Variable	Maps to
`ROISTAT_API_KEY`	`config.api_key`
`ROISTAT_PROJECT_ID`	`config.project`
`ROISTAT_BASE_URL`	`config.base_url` (commented in template)
`ROISTAT_TIMEOUT`	`config.timeout` (commented)
`ROISTAT_OPEN_TIMEOUT`	`config.open_timeout` (commented)
`ROISTAT_BINARY_TEMPFILE_THRESHOLD`	`config.binary_tempfile_threshold` (commented)

Clients

Shared client

Roistat.client builds a client from the global configuration.

Explicit client

Use a dedicated instance when you need another project or key:

client = Roistat::Client.new(
  api_key: "…",
  project: "12345",
  timeout: 20
)

client.access.user_list

API-key-only client

Some account endpoints do not need a project id:

client = Roistat::Client.new(api_key: "…", project_required: false)
client.get("user/projects")

Resource helpers that are API-key-only (projects.list, projects.create) create that client internally.

Blank or whitespace-only credentials raise Roistat::ConfigurationError before any HTTP call.

Low-level HTTP API

Use these for any documented Roistat path that does not have a resource method yet:

client.get("project/calltracking/phone/list", params: {limit: 10})
client.post("project/events/send", body: {name: "purchase"})
client.request(:get, "project/permissions/user/list")

Method signatures

Method	Purpose
`get(path, params: {}, parse: :json)`	GET request
`post(path, params: {}, body: nil, parse: :json)`	POST request
`request(method, path, params: {}, body: nil, parse: :json)`	Arbitrary verb

Notes:

path is relative to base_url (leading slash is optional).
params become query parameters. The client adds project automatically when the client has a project id.
body is JSON-encoded. The gem sets Content-Type: application/json.
parse: :json (default) returns a parsed Hash/Array.
parse: :binary returns a String or Tempfile (see Responses).

Resource APIs

High-level helpers are available on every client:

client.projects
client.access
client.dashboards
client.widgets
client.billing
client.calltracking
client.orders
client.proxy_leads
client.leads
client.managers
client.clients
client.visits
client.events
client.analytics
client.channels
client.statistics
client.indicators
client.lead_hunter
client.emailtracking
client.sms
client.mediaplan
client.speech
client.vpbx

Official parameter details live in the Roistat API docs.

Projects — `client.projects`

Ruby method	HTTP	Path	Auth
`list`	GET	`/user/projects`	API key only
`create(name:, currency:)`	POST	`/account/project/create`	API key only
`modules_list(method: :get)`	GET or POST	`/project/settings/module/list`	API key + project
`counter_list`	POST	`/project/settings/counter/list`	API key + project (help-en)

Examples:

Roistat.client.projects.list
Roistat.client.projects.create(name: "Demo", currency: "RUB")
Roistat.client.projects.modules_list
Roistat.client.projects.modules_list(method: :post)
Roistat.client.projects.counter_list

Access — `client.access`

Ruby method	HTTP	Path	Auth
`user_list`	GET	`/project/permissions/user/list`	API key + project (help-ru)
`authorized_users(method: :get)`	GET or POST	`/project/access/get-authorized-users`	API key + project (help-en)
`change(**body)`	POST	`/project/access/change`	API key + project (help-en)

Examples:

Roistat.client.access.user_list
Roistat.client.access.authorized_users
Roistat.client.access.authorized_users(method: :post)
Roistat.client.access.change(email: "user@example.com", permissions: ["access_analytics_base_read"])

Dashboards — `client.dashboards`

Documented on help-en.

Ruby method	HTTP	Path
`list`	GET	`/project/dashboards`
`widgets(dashboard_id:)`	GET	`/project/dashboards/{dashboardId}/widgets`

Examples:

Roistat.client.dashboards.list
Roistat.client.dashboards.widgets(dashboard_id: 1)

Widgets — `client.widgets`

Documented on help-en. Default verb is POST (matches curl examples); pass method: :get when needed.

Ruby method	HTTP	Path
`data(widget_id:, method: :post, **body)`	GET or POST	`/project/widget/{widgetId}/data`

Examples:

Roistat.client.widgets.data(widget_id: 9, period: "2026-01-01-2026-01-31")
Roistat.client.widgets.data(widget_id: 9, method: :get)

Billing — `client.billing`

Ruby method	HTTP	Path	Auth	Response
`transactions_list(period:)`	POST	`/user/billing/transactions/list`	API key + project	JSON
`transactions_export_excel(period:)`	POST	`/user/billing/transactions/list/export/excel`	API key + project	binary

period must include from and to (Roistat date strings).

Examples:

period = {
  from: "2026-01-01T00:00:00+0300",
  to: "2026-07-22T23:59:59+0300"
}

Roistat.client.billing.transactions_list(period: period)

file = Roistat.client.billing.transactions_export_excel(period: period)
# String if ≤ 1 MiB, otherwise Tempfile

Calltracking — `client.calltracking`

Official docs: calltracking API. The gem uses POST for these endpoints.

Ruby method	HTTP	Path	Notes
`script_list(**body)`	POST	`/project/calltracking/script/list`	optional body (e.g. `is_deleted:`)
`script_create(**body)`	POST	`/project/calltracking/script/create`
`script_update(**body)`	POST	`/project/calltracking/script/update`
`script_delete(id:)`	POST	`/project/calltracking/script/delete`
`phone_list(**body)`	POST	`/project/calltracking/phone/list`
`phone_prefix_list(**body)`	POST	`/project/calltracking/phone/prefix/list`
`phone_create(phones:)`	POST	`/project/calltracking/phone/create`
`phone_buy(prefix:, count:)`	POST	`/project/calltracking/phone/buy`
`phone_update(**body)`	POST	`/project/calltracking/phone/update`
`phone_delete(phones:)`	POST	`/project/calltracking/phone/delete`	phone ids
`call_list(**body)`	POST	`/project/calltracking/call/list`	filters, extend, sort, limit, offset
`call_update(**body)`	POST	`/project/calltracking/call/update`
`call_delete(ids:)`	POST	`/project/calltracking/call/delete`
`call_file(call_id:)`	POST	`/project/calltracking/call/{id}/file`	binary (MP3)
`call_xls_export(period:)`	POST	`/project/calltracking/call/xls/export`	binary (XLS)
`data(period:)`	POST	`/project/calltracking/data`	dashboard analytics
`phone_call(**body)`	POST	`/project/phone-call`	create call history row

Examples:

Roistat.client.calltracking.phone_list
Roistat.client.calltracking.script_list(is_deleted: 0)
Roistat.client.calltracking.call_list(
  filters: {and: [["date", ">", "2026-01-01T00:00:00+0000"]]},
  limit: 50
)
Roistat.client.calltracking.data(period: period)
audio = Roistat.client.calltracking.call_file(call_id: 1234)

Orders — `client.orders`

Official docs: orders API.

Ruby method	HTTP	Path
`list(**body)`	POST	`/project/integration/order/list`
`add(orders)`	POST	`/project/add-orders` (JSON array body)
`info(order_id:)`	GET	`/project/orders/{id}/info`
`external_url(order_id:)`	GET	`/project/orders/{id}/external-url`
`status_list(**body)`	POST	`/project/integration/status/list`
`set_statuses(statuses)`	POST	`/project/set-statuses` (JSON array body)
`custom_fields(**body)`	POST	`/project/analytics/order-custom-fields`
`status_update(order_id:, status_id:)`	POST	`/project/integration/order/{id}/status/update`
`goal_update(order_id:, **body)`	POST	`/project/integration/order/{id}/goal/update`
`update(orders:)`	POST	`/project/integration/order/update`
`delete(order_id:)`	POST	`/project/integration/order/{id}/delete`
`delete_many(ids:)`	POST	`/project/integration/order/delete`

Examples:

Roistat.client.orders.list(limit: 50)
Roistat.client.orders.status_list
Roistat.client.orders.info(order_id: "order_12345")
Roistat.client.orders.add([
  {id: "1", name: "New order", date_create: "2022-06-19T00:32:12+0000"}
])

Proxy leads — `client.proxy_leads`

Official docs: proxy leads API. period is YYYY-MM-DD-YYYY-MM-DD in the query string.

Ruby method	HTTP	Path
`list(period:)`	GET	`/project/proxy-leads`
`duplicates(period:)`	GET	`/project/proxy-leads/duplicates`
`get(id:)`	GET	`/project/proxy-leads/{id}`

Examples:

Roistat.client.proxy_leads.list(period: "2026-01-01-2026-07-22")
Roistat.client.proxy_leads.get(id: "2")

Leads — `client.leads`

Official docs: lead management API.

Ruby method	HTTP	Path
`list(**body)`	POST	`/project/leads/lead/list`
`status_list(**body)`	POST	`/project/leads/status/list`
`create(**body)`	POST	`/project/leads/lead/create`
`update(**body)`	POST	`/project/leads/lead/update`

Examples:

Roistat.client.leads.status_list
Roistat.client.leads.list(
  period: {from: "2023-10-17T21:00:00.000Z", to: "2023-11-30T20:59:59.999Z"},
  sort_field: "creation_date",
  limit: 20
)

Managers — `client.managers`

Official docs: managers API.

Ruby method	HTTP	Path
`list(**body)`	POST	`/project/integration/manager/list`
`add(**body)`	POST	`/project/integration/manager/add`
`update(**body)`	POST	`/project/integration/manager/update`
`delete(id:)`	POST	`/project/integration/manager/delete`

Examples:

Roistat.client.managers.list
Roistat.client.managers.add(id: "12345", name: "Petrov", email: "a@b.c")

Clients — `client.clients`

Official docs: clients API.

Ruby method	HTTP	Path
`list(**body)`	POST	`/project/clients`
`import(clients)`	POST	`/project/clients/import` (JSON array body)
`detail_feed(client:)`	GET	`/project/clients/detail/feed` (`client` query)
`campaign_list(**body)`	POST	`/project/clients/campaign/list`
`campaign_contact_list(**body)`	POST	`/project/clients/campaign/contact/list`

Examples:

Roistat.client.clients.list(limit: 100)
Roistat.client.clients.detail_feed(client: "123")
Roistat.client.clients.import([{id: "111", name: "Valera"}])

Visits — `client.visits`

Official docs: visits API.

Ruby method	HTTP	Path
`list(**body)`	POST	`/project/site/visit/list`
`params_update(**body)`	POST	`/project/site/visit/params/update`

Examples:

Roistat.client.visits.list(limit: 100)
Roistat.client.visits.params_update(visit: "123", roistat_param1: "onlineshop")

Events — `client.events`

Official docs: events API. send_event avoids shadowing Ruby Kernel#send.

Ruby method	HTTP	Path
`send_event(**body)`	POST	`/project/events/send`
`bulk_send(events)`	POST	`/project/events/bulk/send` (JSON array)
`add(events)`	POST	`/project/events/add` (JSON array)
`log(**params)`	GET	`/project/events/log` (filters as query params)
`archive(event_id:, events:)`	POST	`/project/events/meta/{id}/archive` (JSON array)

Examples:

Roistat.client.events.log(name: "Cart")
Roistat.client.events.send_event(name: "Purchase", visit: "100001")

Analytics — `client.analytics`

Official docs: analytics API.

Ruby method	HTTP	Path
`data(**body)`	POST	`/project/analytics/data`
`data_export_excel(**body)`	POST	`/project/analytics/data/export/excel` (binary)
`metrics_new(**body)`	POST	`/project/analytics/metrics-new`
`dimensions(**body)`	POST	`/project/analytics/dimensions`
`dimension_values(**body)`	POST	`/project/analytics/dimension-values`
`attribution_models(**body)`	POST	`/project/analytics/attribution-models`
`list_orders(**body)`	POST	`/project/analytics/list-orders`
`custom_metrics_list(**params)`	GET	`/project/analytics/metrics/custom/list`
`custom_manual_value_list(**body)`	POST	`/project/analytics/metrics/custom/manual/value/list`
`custom_manual_value_add(**body)`	POST	`/project/analytics/metrics/custom/manual/value/add`
`custom_manual_value_delete(**body)`	POST	`/project/analytics/metrics/custom/manual/value/delete`
`funnel_data(**body)`	POST	`/project/reports/funnel/data`
`event_add(**body)`	POST	`/project/analytics/event/add`

Examples:

Roistat.client.analytics.dimensions
Roistat.client.analytics.metrics_new
Roistat.client.analytics.custom_metrics_list
Roistat.client.analytics.data(
  period: {from: "2026-01-01T00:00:00+0300", to: "2026-07-31T23:59:59+0300"},
  metrics: ["visits"],
  dimensions: ["marker_level_1"]
)

Channels — `client.channels`

Official docs: channels / source costs API.

Ruby method	HTTP	Path
`source_list(**body)`	POST	`/project/analytics/source/list`
`cost_list(**body)`	POST	`/project/analytics/source/cost/list`
`cost_add(**body)`	POST	`/project/analytics/source/cost/add`
`cost_update(**body)`	POST	`/project/analytics/source/cost/update`
`cost_delete(id:)`	POST	`/project/analytics/source/cost/delete`

Examples:

Roistat.client.channels.source_list
Roistat.client.channels.cost_list

Statistics — `client.statistics`

Official docs: statistics API.

Ruby method	HTTP	Path
`get_daily(**body)`	POST	`/project/statistics/get-daily` (`period`: `YYYY-MM-DD-YYYY-MM-DD` in UTC; optional `time_zone`, `channel`)

Examples:

Roistat.client.statistics.get_daily(period: "2026-01-01-2026-07-22")

Indicators — `client.indicators`

Official docs: health indicators API.

Ruby method	HTTP	Path
`list`	GET	`/project/health/indicator/list`
`run_script(indicator_id:)`	POST	`/project/health/indicator/{id}/run-script`

Examples:

Roistat.client.indicators.list
Roistat.client.indicators.run_script(indicator_id: 7)

Lead hunter — `client.lead_hunter`

Official docs: lead hunter API.

Ruby method	HTTP	Path
`list(**params)`	GET	`/project/lead-hunter/lead/list` (filters as query params)

Examples:

Roistat.client.lead_hunter.list

Email tracking — `client.emailtracking`

Official docs: email tracking API.

Ruby method	HTTP	Path
`list(**body)`	POST	`/project/emailtracking/email/list`
`attachment(email_id:, attachment_id:)`	GET	`/project/emailtracking/email/{email_id}/attachment/{attachment_id}` (binary)

Examples:

Roistat.client.emailtracking.list(limit: 10)

SMS — `client.sms`

Ruby method	HTTP	Path
`set_report_enabled(enabled:)`	POST	`/project/set-sms-report-enabled` (`enabled`: `"0"` or `"1"`)

Examples:

Roistat.client.sms.set_report_enabled(enabled: true)

Mediaplan — `client.mediaplan`

Official docs: mediaplan API.

Ruby method	HTTP	Path
`target_list(**body)`	POST	`/project/mediaplan/target/list`
`target_create(**body)`	POST	`/project/mediaplan/target/create`
`target_update(**body)`	POST	`/project/mediaplan/target/update`
`target_delete(id:)`	POST	`/project/mediaplan/target/delete`

Examples:

Roistat.client.mediaplan.target_list(
  period: {from: "2026-07-01T00:00:00+0300", to: "2026-07-31T23:59:59+0300"}
)

Speech analytics — `client.speech`

RU help only. Official docs: speech analytics API.

Ruby method	HTTP	Path
`call_list(**body)`	POST	`/project/speech/call/list`
`call_list_export_excel(**body)`	POST	`/project/speech/call/list/export/excel` (binary)
`call_add(**body)`	POST	`/project/speech/call/add`
`call_comment_update(**body)`	POST	`/project/speech/call/comment/update`
`call_operator_update(**body)`	POST	`/project/speech/call/operator/update`
`call_transcription_list(**body)`	POST	`/project/speech/call/transcription/list`
`dictionary_list(**body)`	POST	`/project/speech/dictionary/list`
`dictionary_custom_create(**body)`	POST	`/project/speech/dictionary/custom/create`
`dictionary_custom_update(**body)`	POST	`/project/speech/dictionary/custom/update`
`dictionary_custom_delete(**body)`	POST	`/project/speech/dictionary/custom/delete`
`dictionary_custom_phrase_list(**body)`	POST	`/project/speech/dictionary/custom/phrase/list`
`settings_list(**body)`	POST	`/project/speech/settings/list`
`settings_update(**body)`	POST	`/project/speech/settings/update`

Examples:

Roistat.client.speech.dictionary_list
Roistat.client.speech.call_list

Cloud PBX (VPBX) — `client.vpbx`

RU help only. Official docs: VPBX API.

Ruby method	HTTP	Path
`call_list(**body)`	POST	`/project/vpbx/call/list`
`operator_list(**body)`	POST	`/project/vpbx/operator/list`
`operator_create(**body)`	POST	`/project/vpbx/operator/create`
`operator_update(**body)`	POST	`/project/vpbx/operator/update`
`operator_deactivate(**body)`	POST	`/project/vpbx/operator/deactivate`
`operator_group_list(**body)`	POST	`/project/vpbx/operator/group/list`
`operator_group_create(**body)`	POST	`/project/vpbx/operator/group/create`
`operator_group_update(**body)`	POST	`/project/vpbx/operator/group/update`
`phone_list(**params)`	GET	`/project/vpbx/phone/list`
`phone_create(**body)`	POST	`/project/vpbx/phone/create`
`phone_update(**body)`	POST	`/project/vpbx/phone/update`
`phone_delete(**body)`	POST	`/project/vpbx/phone/delete`
`script_list(**params)`	GET	`/project/vpbx/script/list`
`script_create(**body)`	POST	`/project/vpbx/script/create`
`script_update(**body)`	POST	`/project/vpbx/script/update`
`script_delete(**body)`	POST	`/project/vpbx/script/delete`
`report_data(**body)`	POST	`/project/vpbx/report/data`
`settings_update(**body)`	POST	`/project/vpbx/settings/update`
`settings_file_audio_upload(file:, **fields)`	POST	`/project/vpbx/settings/file/audio/upload` (multipart)

settings_file_audio_upload sends multipart/form-data via Client#post_multipart. Pass an IO or open file as file:; other keyword args become form fields.

Examples:

Roistat.client.vpbx.phone_list
Roistat.client.vpbx.script_list

Responses

JSON

Successful JSON responses return the parsed body (usually a Hash with string keys).

Binary

With parse: :binary (billing Excel export, calltracking XLS export, call audio, email attachments, speech call export):

Body size	Return type
≤ `binary_tempfile_threshold` (default 1 MiB)	`String`
> threshold	`Tempfile` (caller should close/unlink)

Errors

Roistat API errors with "status": "error" map to typed exceptions:

Roistat `error` code	Exception
`authentication_failed`	`Roistat::AuthenticationError`
`authorization_failed`	`Roistat::AuthorizationError`
`access_denied`	`Roistat::AccessDeniedError`
`request_limit_error`	`Roistat::RateLimitError`
other / unknown	`Roistat::Error`

Invalid local config raises Roistat::ConfigurationError.

Error instances may expose:

code — Roistat error code
http_status — HTTP status
response_body — parsed body when available

Development

bin/setup
bundle exec rake          # RSpec + RuboCop
# or
mise test
mise lint

Install Lefthook once for pre-commit hooks:

bundle exec lefthook install

Interactive console:

bin/console

Read-only playground: roistat_demo.

Release:

mise release            # build gem, create tag, push gem + tag
mise github-release     # create GitHub Release for v$VERSION (needs gh + existing tag)
# or: bundle exec rake release

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/alec-c4/roistat.

License

The gem is available as open source under the terms of the MIT License.

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.github		.github
bin		bin
docs/ru		docs/ru
lib		lib
sig		sig
spec		spec
.gitignore		.gitignore
.rspec		.rspec
.rubocop.yml		.rubocop.yml
.ruby-version		.ruby-version
CHANGELOG.md		CHANGELOG.md
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
LICENSE.txt		LICENSE.txt
README.md		README.md
Rakefile		Rakefile
lefthook.yml		lefthook.yml
mise.toml		mise.toml
roistat.gemspec		roistat.gemspec

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Roistat

Contents

Installation

Rails

Configuration

Global config (Rails-friendly)

Configuration options

Environment variables (install generator)

Clients

Shared client

Explicit client

API-key-only client

Low-level HTTP API

Method signatures

Resource APIs

Projects — client.projects

Access — client.access

Dashboards — client.dashboards

Widgets — client.widgets

Billing — client.billing

Calltracking — client.calltracking

Orders — client.orders

Proxy leads — client.proxy_leads

Leads — client.leads

Managers — client.managers

Clients — client.clients

Visits — client.visits

Events — client.events

Analytics — client.analytics

Channels — client.channels

Statistics — client.statistics

Indicators — client.indicators

Lead hunter — client.lead_hunter

Email tracking — client.emailtracking

SMS — client.sms

Mediaplan — client.mediaplan

Speech analytics — client.speech

Cloud PBX (VPBX) — client.vpbx

Responses

JSON

Binary

Errors

Development

Contributing

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

Projects — `client.projects`

Access — `client.access`

Dashboards — `client.dashboards`

Widgets — `client.widgets`

Billing — `client.billing`

Calltracking — `client.calltracking`

Orders — `client.orders`

Proxy leads — `client.proxy_leads`

Leads — `client.leads`

Managers — `client.managers`

Clients — `client.clients`

Visits — `client.visits`

Events — `client.events`

Analytics — `client.analytics`

Channels — `client.channels`

Statistics — `client.statistics`

Indicators — `client.indicators`

Lead hunter — `client.lead_hunter`

Email tracking — `client.emailtracking`

SMS — `client.sms`

Mediaplan — `client.mediaplan`

Speech analytics — `client.speech`

Cloud PBX (VPBX) — `client.vpbx`