Stream a CallRail account

A CallRail stream lands a CallRail account's calls, form submissions and text conversations in your warehouse, with the marketing source, campaign, keywords, click ids and lead status CallRail recorded for each, and the lists that explain them: tracking numbers, companies, tags, users and leads. Join them to your jobs and invoices to see which channels bring the work in.

CallRail is a published source, like Postgres and Bite: sanda wrote the code that reads it and runs it as its own, so there is no connector for sam to write or for anyone to approve. A CallRail user makes an API key, you connect it, choose the account and what to read, and set a schedule.

What it costs at CallRail

Every request sanda makes with the key counts toward your account's API usage at CallRail, and CallRail bills an account each month for its usage past the first 1,500 calls. That charge is CallRail's, on your CallRail invoice, and separate from what sanda charges for the stream.

So a CallRail stream asks for as little as it can:

• It runs at most every 60 minutes, and one run makes at most 500 requests.
• Each request asks for a full page of 250 records, with every field the warehouse needs, never one record at a time.
• Tracking numbers, companies, tags, users and leads are read once a day, whatever the stream's schedule.
• Leads stays off until you tick it, because the whole list is read each day, a request for every page of it.

Each run makes at least one request for each of calls, form submissions and text conversations it reads, so a stream that runs every hour can use up the free calls before the month is out. Run it every few hours unless you need the calls sooner. CallRail's own billing page (Account · Account Settings · Billing) shows your usage, key by key.

Before you start

• A CallRail user makes the key, and it sees what they see. A key belongs to the user who makes it and reaches the same accounts and companies they can. Make it as a user who will stay: CallRail keys don't expire, but one stops working when its user deletes it, or for an account its user is removed from.
• Read-only is enough. CallRail makes every key read-only unless Allow Writes is turned on, and sanda only reads.
• One account a stream. A key whose user sees several accounts (an agency, say) connects once, and each stream reads one of its accounts. The stream keeps that account whichever key it reads with, so a key whose user is later given more accounts, or loses one, keeps working for the streams whose account it still sees.
• Australian tracking numbers need CallRail's international features. CallRail serves Australia, but its support turns on international features before an account outside the US and Canada can have Australian tracking numbers. sanda reads whatever the account holds.

Connect a CallRail API key

sanda keeps the key encrypted and sends it only to CallRail. It is never shown again, in the console or to sam. Type it again replaces it, for when its user makes a new one, whatever accounts that user sees now: each stream on it carries on reading its own account, as long as the new key can see it. Disconnect forgets the key: streams reading it wait until it is typed again, or until you choose another key for them.

Make a stream

What it reads

CallRail has no list of what changed, yet a call's lead status, value, tags and note are often edited days after it rang. So each run reads the last few days again, from where the last run got to, and an edit lands on the next run: a call's or form's lead status, value, tags or note, and a text conversation's lead status. CallRail says most edits happen within a day and suggests reading two or three days again. The default is a week so that an edit made later in the week still lands; set Days read again lower to save requests.

Calls

Each run reads the calls that started in its days, oldest first. Each call lands with what CallRail leaves out unless it is asked for: its source, medium, campaign, keywords, the Google, Microsoft and Meta click ids, its landing page and referrer, the UTM tags, its lead status, value, tags and note, the company and tracking number it came through, who answered it (agent_email), the lead it belongs to (person_id), its attribution milestones and a link to the lead's timeline.

A call CallRail stops listing (one marked as spam, say) is marked _deleted_at once a run reads its days again, and kept. recording and recording_player land as CallRail's links: sanda never fetches a recording. CallRail's player link carries a key that plays the recording to anyone who has the link, with no CallRail sign-in, so sanda takes that key off before the call lands. Without it, the link in recording_player opens the recording in CallRail, which asks for a CallRail sign-in.

Form submissions

CallRail's form list is read by its own named date ranges, so each run asks for this year's forms (and last year's too, when its days reach back into last year), newest first, and stops at the first page that reaches back past its days. Forms from before the start of last year are out of reach of those ranges, so a Read history from date earlier than that reads forms from the start of last year. What the visitor typed lands in form_data, as JSON, beside its source, campaign, keywords, UTM tags, form name, lead status, value, tags, note and attribution milestones. A form CallRail stops listing is kept as it was, never marked deleted.

Text conversations

Each run reads the conversations with messages in its days, newest first. Each lands with its source and lead status and its two most recent messages, in recent_messages. A message's media address is left out, because CallRail says those addresses are short-lived and must never be stored: type says whether a message was a text or carried media. A conversation moves as new messages arrive, so one is never marked deleted by a run.

The lists

Tracking numbers (with their campaign name), companies (with their time zone), tags, users and leads are read whole once a day, whatever the stream's schedule. Load everything again, on the stream's page, reads them on the next run. A row a list no longer has is marked _deleted_at, and kept.

Left out

• Transcripts, call summaries, sentiment and lead scores. CallRail returns them only on some of its plans, and they carry the conversation itself.
• Recordings and media. Their links land; the audio and pictures are never fetched. The key in CallRail's player link that lets anyone play a recording without signing in never lands.
• SMS threads. A text conversation's value, tags and notes live on CallRail's list of SMS threads, which sanda doesn't read yet: the conversations it reads carry their lead status only.
• A conversation's whole history, and a lead's timeline. Each costs a request per conversation or lead.
• CallRail's own totals (summaries and time series). Count them from the rows instead.

What lands in your warehouse

Every field becomes a column, typed by its values, and the whole record is kept in _record, as for every pull. A few things are worth knowing when you model them:

• Times carry their offset, so they convert to any zone. sanda asks for calls and conversations in UTC. Each call also carries its company's own time zone, in company_time_zone.
• Ids are CallRail's own: CAL… for a call, FOR… for a form, PER… for a lead. A call's or form's person_id is a lead's id, a call's tracker_id a tracking number's, company_id a company's, and agent_email a user's email. A form with no lead has person_id anonymous, so leave those out when you join or count leads.
• Deletions show as _deleted_at on a call or a list's row that CallRail stops listing, and the row is kept. A form or a conversation is never marked deleted.
• Phone numbers are in E.164 form, such as +61412345678, ready to match to your customers.
• Tags are a JSON list of names, and milestones is JSON: first touch, lead created, qualified and last touch, each with its source and campaign.
• value is a number, as it was set in CallRail.

Change a stream

Edit, on the stream's page, changes everything but the account and the warehouse. A stream keeps the account it reads, but it may move to another CallRail API key whose user can see the same account (when the key's user leaves, say). Something you take off keeps its table, with what it landed. A new Days read again takes effect on the next run. A new Read history from date takes effect the next time everything is read from the start: press Load everything again on the stream's page.

When something goes wrong

A failed run counts toward the stream pausing itself, as any stream's does. A run that stopped early on CallRail's allowance didn't fail. See runs.

Limits

• A CallRail stream runs at most every 60 minutes, and makes at most 500 requests in one run.
• A run makes 1 request a second, each asking for up to 250 records.
• CallRail allows an account 1,000 API requests an hour and 10,000 a day by default, shared with every other integration using a key on it.
• Read history from goes back at most 755 days, inside the 25 months CallRail keeps calls, forms and texts. Form submissions go back no further than the start of last year.
• Days read again is from 1 to 30.
• One run lands at most 20,000,000 records, so a long history is several runs.

A CallRail stream is billed like any pull: a charge for each run that does its work, and the rows it lands past what your edition includes. See what streams cost.