External Query Step

Using an External Query step in the Call Flow Builder, you can set custom rules as to how your calls should route. For example, if you'd like a repeat caller to route to your support team, and a new caller to route to your sales team, you can build an external API that tells CallRail how to route the call. Or, if your external API returns a telephone number, you can use an external query step to dial that number directly as well. This is an advanced configuration for the Call Flow Builder, and should only be implemented by a developer.

Use this article to learn how to:

  • Add an External Query step to a call flow
  • Assign your call flow to your tracking numbers

Getting Started

Creating an External Query step requires the following:

  • Contacting CallRail's support team to have this feature enabled within your account.
  • An API endpoint that you've built in order to use this feature.

Your endpoint will receive a POST with a JSON body similar to the format of Call objects returned via our API. For a full description of this format, see our API documentation. Note that since the call is still ringing, many fields may still be null. The following example shows this format:

"call": {
"id": 227799611,
"tracking_number": "+16785551234",
"customer_phone_number": "+17705551111",
... additional fields are included ...

In order for the Call Flow Builder to follow the rules you create, use the fields in the call object from the JSON to determine the response to send back to CallRail. The response should be a text response body that matches one of the strings defined in the Call Flow Builder for the External Query step. Note that this response must not be wrapped in HTML, and you may need to specify a header of "Content-Type: text/plain" to ensure your chosen development framework does not apply any additional markup.

Additionally, you may choose to validate a signature so that your endpoint can verify that incoming requests are legitimate requests from CallRail. This step is optional, but if you choose to validate our signature, you may do so by verifying the value in the "X-CallRail-Signature" header. The signature can be validated using the following pseudocode approach:

# First, generate the base string that was originally signed. This
# base string is a concatenation of several fields from the call
# information, separated by newlines. Note that the "timestamp" field
# is the same as the timestamp string included with the POST data.
base_string = [

# Next, calculate the digest of the base string via the HMAC-SHA1
# algorithm, using the company's Signing Key as the key. This Signing
# Key can be found in the Call Flow builder where the Endpoint URL is
# defined for an External Query step.
digest = HMAC-SHA1(signing_key, base_string)

# Finally, encode the digest as Base64. Compare the computed value to
# the value specified in the X-CallRail-Signature header; these values
# should match.
signature = Base64(digest)

Create an External Query Step

Call flows are company-specific in your account. Follow the instructions below to create a call flow with an External Query step in the company of your choice.

  1. Choose the company where you'd like to use an External Query step.


  2. Click Numbers at the top of the page.


  3. Select your Call Flows from the left menu.


  4. Create a new call flow by clicking + Create New Call Flow. You can also click the pencil icon to Edit an existing call flow.


  5. Name your Call Flow at the top of the page.

  6. Choose your call recording preference. Slide the toggle to ON to record all calls to this call flow. Keep the toggle OFF if you don’t want calls to this flow recorded.


  7. Select External Query from the list of available steps.


  8. Enter your external endpoint URL that's been created outside of CallRail. Use the signing key listed below this field to verify to the API endpoint that a request is a legitimate request from CallRail. Using a signing key is optional. 


  9. Indicate where calls should route according to your external API rules in the secondary fields. If you'd like to enter more than two fields, select + Add External API Response for additional routing options. If your external API returns a telephone number, we'll dial that directly here as well.


  10. Select the first field you've entered, and indicate where calls should route to according to your external API rules. In this example, we'll include a dial step to illustrate that if the caller is a new caller, they should be forwarded to the sales number. 


  11. Return to the External Query step, and select the second field. In this example, we'll include a dial step to illustrate that if the caller is a repeat caller, they should be forwarded to the support number. 


  12. Finally, return to the External Query step to indicate where the call should route in the event of an unknown value or error. This will allow the call to route to your business if the caller doesn't match any criteria created in your external API. Select In the event of an unknown value or error, and indicate where the call should go.


  13. Continue configuring your call flow to your personal preference. Then, click Save at the top of the page to save your call flow.


    Assigning Your Call Flow

    Once you’ve created your call flow, you’ll assign it to your tracking numbers. Since your call flows can be shared, you’re able to assign a single call flow to multiple tracking numbers within the same company in your account. When you assign a call flow to a tracking number, your call routing updates immediately.

    Call Flows can only route to a destination number in the country selected at the top of the call flow, or a US/Canada number.

    1. Choose the company whose call flow you’d like to assign to a tracking number.


    2. Click Numbers at the top of the page.


    3. Select your Active Numbers from the left menu.


    4. Choose the call flow you’d like to assign to a tracking number in the Destination column. Select the call flow from the drop down that you’d like to assign to that destination number.


    5. Click Save and update call flow on the prompt.

Have more questions? Submit a request


Need additional help? Ask our Community!