Users

Contents

Listing All Users

Returns a paginated list of all the Users in your Account.

API Endpoint

Method URL
GET /v1/users.json

Request Parameters

Name Type Required? Description
per_page number optional How many users to return for this request (default 100, maximum 250).
Example: 25
page number optional Page number that should be returned for this request (the first page is 1).
Example: 3

Response Fields

Name Type Description
id number Unique identifier for this user.
Example: 321752
first_name string The user’s first name.
Example: “John”
last_name string The user’s last name.
Example: “Robertson”
email string The email address assocated with this user.
Example: “john.robertson@example.com”
role string The user’s permission within this CallRail account; one of “admin”, “reporting”, “manager” or “notification”. See User Roles.
Example: “reporting”
created_at string The date and time the user was created in UTC (ISO 8601 format).
Example: “2011-07-05T19:06:10Z”
companies array A list of companies for which this user has permission to access or receive notifications. For the format of each Company object, see Companies.
Example: [{ "id": 53112, "name": "Bob's Garage"}, { "id": 12421, "name": "Bob's Pizzeria" }]

Example

curl -H "Authorization: Token token=abc1234" \
  https://api.callrail.com/v1/users.json?per_page=2&page=1
{
  "page": 1,
  "per_page": 2,
  "total_pages": 2,
  "total_records": 4,
  "users": [
    {
      "id": 1,
      "first_name": "John",
      "last_name": "Robertson",
      "email": "john@example.com",
      "created_at": "2014-05-28T14:14:47-04:00",
      "role": "admin",
      "companies": [
        {
          "id": 162027695,
          "name": "Bob's Garage"
        },
        {
          "id": 220980163,
          "name": "Bob's Pizzeria"
        },
        {
          "id": 267130707,
          "name": "Bob's Dental"
        }
      ]
    },
    {
      "id": 2,
      "first_name": "Carry",
      "last_name": "Robertson",
      "email": "carry@example.com",
      "created_at": "2014-05-28T14:14:48-04:00",
      "role": "reporting",
      "companies": [
        {
          "id": 267130707,
          "name": "Bob's Dental"
        }
      ]
    }
  ]
}

Retrieving a Single User

Retrieve detailed information about a single User with the specified id.

API Endpoint

Method URL
GET /v1/users/{user_id}.json

Request Data

None.

Response Fields

Name Type Description
id number Unique identifier for this user.
Example: 321752
first_name string The user’s first name.
Example: “John”
last_name string The user’s last name.
Example: “Robertson”
email string The email address assocated with this user.
Example: “john.robertson@example.com”
role string The user’s permission within this CallRail account; one of “admin”, “reporting”, “manager” or “notification”. See User Roles.
Example: “reporting”
created_at string The date and time the user was created in UTC (ISO 8601 format).
Example: “2011-07-05T19:06:10Z”
companies array A list of companies for which this user has permission to access or receive notifications. For the format of each Company object, see Companies.
Example: [{ "id": 53112, "name": "Bob's Garage"}, { "id": 12421, "name": "Bob's Pizzeria" }]
call_alerts array A list of objects indicating the trackers for which this user will receive call notifications.
Example: [{ "id": 2511, "name": "Keyword Tracker", "type": "Session"}, { "id": 122, "name": "Radio Ad", "type": "Source" }]
sms_alerts array A list of objects indicating the trackers for which this user will receive text message notifications.
Example: [{ "id": 2511, "name": "Keyword Tracker", "type": "Session"}, { "id": 122, "name": "Radio Ad", "type": "Source" }]
     

Example

curl -H "Authorization: Token token=abc1234" \
  https://api.callrail.com/v1/users/243215.json
{
  "id": 243215,
  "first_name": "Carry",
  "last_name": "Robertson",
  "email": "carry@example.com",
  "created_at": "2014-05-28T14:14:48-04:00",
  "role": "reporting",
  "companies": [
    {
      "id": 267130707,
      "name": "Uptown Dental"
    }
  ],
  "sms_alerts": [
    {
      "id": 289247823,
      "name": "Keyword Tracker",
      "type": "Session"
    }
  ],
  "call_alerts": [
    {
      "id": 2894223,
      "name": "TV Ad Fall 2013",
      "type": "Source"
    }
  ]
}

Creating a New User

Add a new user to your CallRail Account. You can specify the type of user, as well as what companies the user can access.

API Endpoint

Method URL
POST /v1/users.json

Request Body

Name Type Required? Description
first_name string required Example: “Bob”
last_name string required Example: “Johnson”
email string required The email address the user will use to log in to CallRail and receive call or text message notifications.
Example: “jane@example.com”
role string required What level of access the user should have to your CallRail Account or Companies. One of “admin”, “reporting”, “manager”, or “notification”.
See User Roles.
Example: “reporting”

Depending on the role assigned to the new user, there are additional required fields, described below.

Account Administrators

Name Type Required? Description
password string required The password the user will use to log in to CallRail.
Example: “letmein123” (Do not use this as your password.)

Client Reporting

Name Type Required? Description
password string required The password the user will use to log in to CallRail.
Example: “letmein123” (Do not use this as your password.)
companies array required A list of company IDs that the user should be able to access.
Example: [215, 12, 34].

Client Managers

Name Type Required? Description
password string required The password the user will use to log in to CallRail.
Example: “letmein123” (Do not use this as your password.)
companies array required A list of company IDs that the user should be able to access.
Example: [215, 12, 34].

Notification Only

Name Type Required? Description
companies array required A list of company IDs that the user should be able to access. Notification Only users cannot log in, but they must be granted access to a Company before they can be subscribed to email notifications for trackers within that Company.
Example: [215, 12, 34].

Response Fields

When successful, the HTTP response code will indicate 201 CREATED. The newly-created User object will be returned in the same format as described above:

Name Type Description
id number Unique identifier for this user.
Example: 321752
first_name string The user’s first name.
Example: “John”
last_name string The user’s last name.
Example: “Robertson”
email string The email address assocated with this user.
Example: “john.robertson@example.com”
role string The user’s permission within this CallRail account; one of “admin”, “reporting”, “manager” or “notification”. See User Roles.
Example: “reporting”
created_at string The date and time the user was created in UTC (ISO 8601 format).
Example: “2011-07-05T19:06:10Z”
companies array A list of companies for which this user has permission to access or receive notifications. For the format of each Company object, see Companies.
Example: [{ "id": 53112, "name": "Bob's Garage"}, { "id": 12421, "name": "Bob's Pizzeria" }]

If an error occurs, no user will be created and the response code will be 4xx or 5xx. The response will contain only:

Name Type Description
error string Short description of why the request failed.
Example: “email address already in use”

Example

curl -H "Authorization: Token token=abc1234" \
     -H "Content-Type: application/json"     \
     -d '{"first_name": "Ron", "last_name": "Johnson", "email": "ron@example.com",
          "role": "reporting", "companies": [18512, 12451]}' \
  https://api.callrail.com/v1/users.json
{
  "id": 125819,
  "first_name": "Ron",
  "last_name": "Johnson",
  "email": "ron@example.com",
  "role": "reporting",
  "created_at": "2014-05-28T14:14:48-04:00",
  "companies": [
    {
      "id": 18512,
      "name": "Ron's Surf Shop"
    },
    {
      "id": 12451,
      "name": "Ron's Bike Rentals"
    }
  ]
}

Updating a User

You can use the API to add company IDs to an existing user record

API Endpoint

Method URL
PUT /v1/users/{user_id}.json

Request Body

Name Type Required? Description
company_ids array required An array of company ids that you wish to associate with the user record. Example: [395108856, 395108857]

Response Fields

When successfully updated, the response will be 204 NO CONTENT. If an error occurs, the response code will be 4xx or 5xx and include:

Name Type Description
error string Short description of why the request failed.
Example: “Company Ids not found”

Example

curl -H "Authorization: Token token=abc1234" \
     -H "Content-Type: application/json"     \
     -X PUT \
     -v \
     -d '{"company_ids": [395108856, 395108857]}' \
     https://api.callrail.com/v1/users/243215.json
< HTTP/1.1 204 No Content
< Cache-Control: no-cache
< Connection: close
<
* Closing connection 0

User Roles

Account Administrators

Account Administrators have complete access to every company in your account. They can also add companies and users, as well as create new tracking numbers and keyword pools.

Client Reporting Users

Client Reporting users have limited access to assigned companies within your account. They can see call data associated with the companies you assign to them, listen to recordings, and tag and make notes on calls. Client users cannot create or modify tracking phone numbers.

Client Managers

Client Managers can create and edit tracking phone numbers, call flows, tags, and users within any company they’ve been assigned to by an administrator.

Notification Only Users

Notification Only users are unable to log into the application. They can only be assigned to receive call alert and text message alert emails for specific trackers within companies to which they are assigned.