Connect Other Apps
Quick and simple data sources for your snippet
These are the easiest ways to get data from other sources into your snippets. They require little setup and get you saving time right away.
User input using Form fields
Adding form fields to your snippets creates placeholders that can be customized with each use of the template. Manually entering data into these fields is the most lightweight way to input information from another system. While manual, it’s infinitely customizable and can be set up in seconds.
Reading data from the page
The {site} command can read text that’s on the page where you’re using your snippet, and merge portions of that text directly into your snippet.
There’s a full guide available on this feature here. Additional information about the website content texts selector can also be found in our community.
Accessing your Data Blaze data
Data Blaze makes it easy to organize and manage your data in the form of smart spreadsheets. With Data Blaze you can also easily access your data and edit it from anywhere using Text Blaze snippets.
This makes it extremely easy to use your data across all of your snippets, with your data centralized in one place. Read more about retrieving data from and writing data to Data Blaze here.
Using the content of the Clipboard
The {clipboard} command automatically adds the contents of your clipboard into your snippet. Simply copy data from another system to your clipboard, then add this command where you’d like that information to be placed.
Making API calls
Text Blaze snippets can read data from and write data to other apps using their APIs. The The {urlload} command and The {urlsend} command are used to make API calls. This guide covers the use of these commands.
API Authentication
Text Blaze can integrate with APIs that authenticate with API keys or tokens passed through the URL or in the headers of the API call. Currently, Text Blaze cannot authenticate via oAuth.
Many apps, such as Hubspot, allow for API tokens to be scoped to only specific permissions. We suggest, when possible, restricting the scope of your API tokens to only what’s necessary for your Text Blaze integration.
Working with JSON files
APIs often use JSON files to transmit data. Text Blaze uses lists, and specifically keyed lists, to handle and manipulate large data sets.
The fromJSON() function converts JSON to a keyed list. toJSON() can be used to convert lists into JSON format. Examples of both are below.
Retrieving information with {urlload}
Adding the {urlload} command to your snippet
The {urlload} command is used for retrieving information from APIs. This command is not listed in the menu of commands on the right side of the editor.
To add the command to your snippet, have the API endpoint URL handy and enter it into your snippet with this format:
Once added to your snippet, double-click on the text to turn it back into “capsule” form. Then, single-click on the capsule to access the different command settings.
Once added, you’ll also need to allow the folder to communicate with the other application. You should see this image prompting you to allow that connection:
Configuring settings
How you configure the settings available in the {urlload} command will be determined by the API you’re using and how you’re using it.
- URL: this is the URL of the API endpoint
- done: determines how to handle the response. See section below for full detail.
- body: contains the body of the API call
- Depending on the complexity of the body, it can be entered here or stored in another variable and called from here (e.g. {=body})
- headers: the headers of the API call.
- The box on the left is for the key, the box on the right is for the value. The colon between the key and value is added automatically
- method: choose the appropriate method based on the API documentation of the integrating app
- start: useful for setting variable statuses at the start of the API call. Typically used to provide a “still loading…” status
Setting up the “done” setting
The done setting allows for handling the API’s response data. It's a function that takes one or more variables as input (the API response) and creates a keyed list as output.
For example, the done function can look like this:
If your response data is in JSON, you can use the fromjson() function
The done function can also take multiple variable and create a list with multiple elements:
Error handling
The catch() command can be used to handle API errors or unforeseen responses.
Using the response data
The output of the command are variables that correspond to the keys of the list and can be accessed like any other variable using the {=<variable name>} notation, e.g. {=key} or {=contents}
The content of these variables will often be in the form of lists (especially when converted from JSON). Refer to our guide about lists for further details about how to use this information in your snippets, especially the list of lists section.
Sending data with {urlsend}
{urlsend}
{urlsend} commands is used to send data to an endpoint.
{urlsend} supports GET, POST, PUT, PATCH and DELETE HTTP request methods. It defaults to GET.
{urlload} makes the request when the snippet is triggered. {urlsend} makes the call when the snippet is inserted (the user clicks insert). As a result, {urlload} doesn't process the returned data using the done setting.
Example snippets
Examples of retrieving data
This snippet retrieves a random fact from a random fact API and repeats through the two results it retrieves.
{note: preview=no}{urlload: https://api.api-ninjas.com/v1/facts?limit=2; headers=X-Api-Key:vjBPppLwCTWCw2vElgQnCQ==9qBSecSXfikhWS3U; done=(res) -> ["results": res]}{endnote}
This random fact generator API returns the results in JSON, which can be seen here: {=results}
Transforming it into a list using the fromjson function makes it easier to interact with inside a Text Blaze snippet: {=fromjson(results)}
The urlload's done setting could instead be written as done=(res) -> ["results": fromjson(res)] so that the results variable is already formatted as a list.
Once in list format, it's easy to use the data inside of that list:
{repeat: for x in fromjson(results)}{=x["fact"]}
{endrepeat}
The following snippet has a formtext field to enter a word, and then uses that formtext field's value as a parameter in the API call.
{note: preview=no}{token="vjBPppLwCTWCw2vElgQnCQ==9qBSecSXfikhWS3U"}{if:response<>"???"}{synonyms=response["synonyms"]}{antonyms=response["antonyms"]}{else}{synonyms=[]}{antonyms=[]}{endif}{endnote} {note}Enter an English word to look up in the thesaurus: {formtext: default=blaze; name=lookup}{urlload: https://api.api-ninjas.com/v1/thesaurus?word={=lookup}; done=(res) -> ["response": catch(fromjson(res), "???")]; headers=X-Api-Key:{=token}}{endnote} {if: lookup=""}{error: enter a word to look up}{else} Here's all the synonyms the API returned: {if: count(synonyms)>0}{repeat: for words in synonyms}{=words} {endrepeat}{else}The API returned no synonyms{endif}
Here's all the antonyms the API returned: {if: count(antonyms)>0}{repeat: for words in antonyms}{=words} {endrepeat}{else}The API returned no antonyms{endif}{endif}
The following snippet does not make a live API call to Hubspot for security puroses, but uses real Hubspot response data. This snippet shows how data from the API response can be used in a snippet's text.
This example uses a Hubspot private app access token scoped to crm.objects.contacts.read and crm.objects.contacts.write.
{note}Enter email to look up in Hubspot: {formtext: default=bh@hubspot.com; name=email}{endnote: trim=left}
Hey {=first},
I'm the Customer Success Manager for {=company} and I'm reaching out about your use of our Product. I'd love to connect with you about your use-case. I know you're based in {=state} -- I'm in WA, so it shouldn't be too hard to find a time we could connect. What works well for you?
{if: admin=="true"}
I also see that you're an administrator of your plan. I'd love to get feedback from you about the reporting enhancements that we rolled out recently. As an administrator, you have unique perspective on those features.{endif: trim=left}
Thanks!
Your Name
{note: preview=no; trim=yes}{token="REPLACE_ME_WITH_REAL_TOKEN"}
{urlload: https://api.hubapi.com/contacts/v1/contact/email/{=email}/profile; method=GET; headers=Authorization: Bearer {=token}; done=(res) -> ["results2": catch(fromJSON(res), "???")]}
Retrieved first name: {first=results["firstname"]["value"]}
Retrieved company name: {company=results["company"]["value"]}
Retrieved state location: {state=results["state"]["value"]}
Are they an administrator? {admin=results["administrator"]["value"]}
Email: {=results["email"]["value"]}
Twitter Handle: @{=results["twitterhandle"]["value"]}
Simulated response date: {results=["vid": 51, "canonical-vid": 51, "merged-vids": [], "portal-id": 23696765, "is-contact": yes, "properties": ["hs_latest_source_data_2": ["value": "sample-contact", "versions": [["value": "sample-contact", "source-type": "ANALYTICS", "source-id": "ContactAnalyticsDetailsUpdateWorker", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781679083, "selected": no]]], "hs_latest_source_data_1": ["value": "API", "versions": [["value": "API", "source-type": "ANALYTICS", "source-id": "ContactAnalyticsDetailsUpdateWorker", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781679083, "selected": no]]], "hs_is_unworked": ["value": "true", "versions": [["value": "true", "source-type": "CALCULATED", "source-id": "CalculatedPropertyComputer", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662992, "selected": no]]], "firstname": ["value": "Brian", "versions": [["value": "Brian", "source-type": "CONTACTS_WEB", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662366, "selected": no]]], "associatedcompanyid": ["value": "10529379465", "versions": [["value": "10529379465", "source-type": "CALCULATED", "source-id": "RollupProperties", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781664987, "selected": no]]], "city": ["value": "Cambridge", "versions": [["value": "Cambridge", "source-type": "CONTACTS_WEB", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662366, "selected": no]]], "num_unique_conversion_events": ["value": "0", "versions": [["value": "0", "source-type": "CALCULATED", "source-id": "", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781663439, "selected": no]]], "hs_latest_source": ["value": "OFFLINE", "versions": [["value": "OFFLINE", "source-type": "ANALYTICS", "source-id": "ContactAnalyticsDetailsUpdateWorker", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781679083, "selected": no]]], "hs_pipeline": ["value": "contacts-lifecycle-pipeline", "versions": [["value": "contacts-lifecycle-pipeline", "source-type": "API", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662992, "selected": no]]], "hs_analytics_revenue": ["value": "0.0", "versions": [["value": "0.0", "source-type": "ANALYTICS", "source-id": "ContactAnalyticsDetailsUpdateWorker", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781679083, "selected": no]]], "hs_social_num_broadcast_clicks": ["value": "0", "versions": [["value": "0", "source-type": "ANALYTICS", "source-id": "ContactAnalyticsDetailsUpdateWorker", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781679083, "selected": no]]], "createdate": ["value": "1672781662992", "versions": [["value": "1672781662992", "source-type": "API", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662992, "selected": no]]], "hs_analytics_num_visits": ["value": "0", "versions": [["value": "0", "source-type": "ANALYTICS", "source-id": "ContactAnalyticsDetailsUpdateWorker", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781679083, "selected": no]]], "hs_sequences_actively_enrolled_count": ["value": "0", "versions": [["value": "0", "source-type": "CALCULATED", "source-id": "RollupProperties", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781664987, "selected": no]]], "hs_social_linkedin_clicks": ["value": "0", "versions": [["value": "0", "source-type": "ANALYTICS", "source-id": "ContactAnalyticsDetailsUpdateWorker", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781679083, "selected": no]]], "hs_marketable_until_renewal": ["value": "true", "versions": [["value": "true", "source-type": "API", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781663306, "selected": no]]], "hs_marketable_status": ["value": "true", "versions": [["value": "true", "source-type": "API", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781663306, "selected": no]]], "administrator": ["value": "true", "versions": [["value": "true", "source-type": "CRM_UI", "source-id": "userId:48953480", "source-label": "", "updated-by-user-id": 48953480, "timestamp": 1672783702008, "selected": no]]], "hs_analytics_source": ["value": "OFFLINE", "versions": [["value": "OFFLINE", "source-type": "ANALYTICS", "source-id": "ContactAnalyticsDetailsUpdateWorker", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781679083, "selected": no]]], "hs_email_domain": ["value": "hubspot.com", "versions": [["value": "hubspot.com", "source-type": "CALCULATED", "source-id": "", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662992, "selected": no]]], "hs_analytics_num_page_views": ["value": "0", "versions": [["value": "0", "source-type": "ANALYTICS", "source-id": "ContactAnalyticsDetailsUpdateWorker", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781679083, "selected": no]]], "hs_marketable_reason_id": ["value": "Sample Contact", "versions": [["value": "Sample Contact", "source-type": "API", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781663306, "selected": no]]], "company": ["value": "HubSpot", "versions": [["value": "HubSpot", "source-type": "CONTACTS_WEB", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662366, "selected": no]]], "state": ["value": "MA", "versions": [["value": "MA", "source-type": "CONTACTS_WEB", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662366, "selected": no]]], "email": ["value": "bh@hubspot.com", "versions": [["value": "bh@hubspot.com", "source-type": "API", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662366, "selected": no]]], "hs_latest_source_timestamp": ["value": "1672781663113", "versions": [["value": "1672781663113", "source-type": "ANALYTICS", "source-id": "ContactAnalyticsDetailsUpdateWorker", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781679083, "selected": no]]], "website": ["value": "http://www.HubSpot.com", "versions": [["value": "http://www.HubSpot.com", "source-type": "CONTACTS_WEB", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662366, "selected": no]]], "hs_marketable_reason_type": ["value": "SAMPLE_CONTACT", "versions": [["value": "SAMPLE_CONTACT", "source-type": "API", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781663306, "selected": no]]], "jobtitle": ["value": "CEO", "versions": [["value": "CEO", "source-type": "CONTACTS_WEB", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662366, "selected": no]]], "lastmodifieddate": ["value": "1672783702025", "versions": [["value": "1672783702025", "source-type": "CONTACTS", "source-id": "userId:48953480", "source-label": "", "updated-by-user-id": "", "timestamp": 1672783702025, "selected": no], ["value": "1672781679083", "source-type": "API", "source-id": "", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781679083, "selected": no], ["value": "1672781664987", "source-type": "CALCULATED", "source-id": "", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781664987, "selected": no], ["value": "1672781663335", "source-type": "API", "source-id": "", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781663335, "selected": no], ["value": "1672781662992", "source-type": "API", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662992, "selected": no]]], "hs_analytics_first_timestamp": ["value": "1672781662992", "versions": [["value": "1672781662992", "source-type": "ANALYTICS", "source-id": "ContactAnalyticsDetailsUpdateWorker", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781679083, "selected": no]]], "hs_social_google_plus_clicks": ["value": "0", "versions": [["value": "0", "source-type": "ANALYTICS", "source-id": "ContactAnalyticsDetailsUpdateWorker", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781679083, "selected": no]]], "hs_analytics_average_page_views": ["value": "0", "versions": [["value": "0", "source-type": "ANALYTICS", "source-id": "ContactAnalyticsDetailsUpdateWorker", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781679083, "selected": no]]], "lastname": ["value": "Halligan (Sample Contact)", "versions": [["value": "Halligan (Sample Contact)", "source-type": "CONTACTS_WEB", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662366, "selected": no]]], "hs_all_contact_vids": ["value": "51", "versions": [["value": "51", "source-type": "API", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662992, "selected": no]]], "twitterhandle": ["value": "bhalligan", "versions": [["value": "bhalligan", "source-type": "CONTACTS_WEB", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662366, "selected": no]]], "hs_social_facebook_clicks": ["value": "0", "versions": [["value": "0", "source-type": "ANALYTICS", "source-id": "ContactAnalyticsDetailsUpdateWorker", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781679083, "selected": no]]], "hs_is_contact": ["value": "true", "versions": [["value": "true", "source-type": "CALCULATED", "source-id": "", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662992, "selected": no]]], "num_conversion_events": ["value": "0", "versions": [["value": "0", "source-type": "CALCULATED", "source-id": "", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781663439, "selected": no]]], "twitterprofilephoto": ["value": "https://pbs.twimg.com/profile_images/3491742741/212e42c07d3348251da10872e85aa6b0.jpeg", "versions": [["value": "https://pbs.twimg.com/profile_images/3491742741/212e42c07d3348251da10872e85aa6b0.jpeg", "source-type": "CONTACTS_WEB", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662366, "selected": no]]], "hs_object_id": ["value": "51", "versions": [["value": "51", "source-type": "API", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662992, "selected": no]]], "hs_analytics_num_event_completions": ["value": "0", "versions": [["value": "0", "source-type": "ANALYTICS", "source-id": "ContactAnalyticsDetailsUpdateWorker", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781679083, "selected": no]]], "hs_social_twitter_clicks": ["value": "0", "versions": [["value": "0", "source-type": "ANALYTICS", "source-id": "ContactAnalyticsDetailsUpdateWorker", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781679083, "selected": no]]], "hs_analytics_source_data_2": ["value": "sample-contact", "versions": [["value": "sample-contact", "source-type": "ANALYTICS", "source-id": "ContactAnalyticsDetailsUpdateWorker", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781679083, "selected": no]]], "hs_lifecyclestage_lead_date": ["value": "1672781662992", "versions": [["value": "1672781662992", "source-type": "API", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662992, "selected": no]]], "hs_analytics_source_data_1": ["value": "API", "versions": [["value": "API", "source-type": "ANALYTICS", "source-id": "ContactAnalyticsDetailsUpdateWorker", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781679083, "selected": no]]], "lifecyclestage": ["value": "lead", "versions": [["value": "lead", "source-type": "API", "source-id": "sample-contact", "source-label": "", "updated-by-user-id": "", "timestamp": 1672781662992, "selected": no]]], "hs_updated_by_user_id": ["value": "48953480", "versions": [["value": "48953480", "source-type": "CONTACTS", "source-id": "userId:48953480", "source-label": "", "updated-by-user-id": 48953480, "timestamp": 1672783702025, "selected": no]]]], "form-submissions": [], "list-memberships": [], "identity-profiles": [["vid": 51, "saved-at-timestamp": 1672781663113, "deleted-changed-timestamp": 0, "identities": [["type": "EMAIL", "value": "bh@hubspot.com", "timestamp": 1672781662366, "is-primary": yes], ["type": "LEAD_GUID", "value": "d0e7aef5-b991-4ff0-bfcd-682c7cd0ff46", "timestamp": 1672781663108]]]], "merge-audits": [], "associated-company": ["company-id": 10529379465, "portal-id": 23696765, "properties": ["country": ["value": "United States"], "num_associated_contacts": ["value": "2"], "timezone": ["value": "America/New_York"], "facebook_company_page": ["value": "https://facebook.com/hubspot"], "hs_pipeline": ["value": "companies-lifecycle-pipeline"], "createdate": ["value": "1672781663167"], "description": ["value": "HubSpot is an American developer and marketer of software products for inbound marketing, sales, and customer service."], "hs_analytics_latest_source_data_2": ["value": "sample-contact"], "hs_analytics_latest_source_data_1": ["value": "API"], "hs_num_blockers": ["value": "0"], "industry": ["value": "COMPUTER_SOFTWARE"], "total_money_raised": ["value": "100.5M"], "web_technologies": ["value": "unbounce;app_nexus;piwik;google_analytics;mixpanel;google_tag_manager;facebook_advertiser;salesforce;stripe;cloud_flare;dstillery;twitter_button;hubspot;youtube;vidyard;facebook_connect;crazy_egg;amazon__cloudfront;wistia;optimizely"], "numberofemployees": ["value": "10000"], "hs_analytics_num_visits": ["value": "0"], "linkedin_company_page": ["value": "https://www.linkedin.com/company/hubspot"], "hs_analytics_latest_source_timestamp": ["value": "1672781663113"], "hs_analytics_source": ["value": "OFFLINE"], "annualrevenue": ["value": "1000000000"], "founded_year": ["value": "2006"], "hs_annual_revenue_currency_code": ["value": "USD"], "hs_analytics_num_page_views": ["value": "0"], "state": ["value": "NY"], "linkedinbio": ["value": "HubSpot is an American developer and marketer of software products for inbound marketing, sales, and customer service."], "hs_num_open_deals": ["value": "0"], "zip": ["value": "test"], "website": ["value": "hubspot.com"], "address": ["value": "First Street"], "hs_analytics_first_timestamp": ["value": "1672781662366"], "first_contact_createdate": ["value": "1672781662382"], "twitterhandle": ["value": "HubSpot"], "hs_target_account_probability": ["value": "0.5596858859062195"], "hs_lastmodifieddate": ["value": "1672781685731"], "hs_num_decision_makers": ["value": "0"], "phone": ["value": "+1 888-482-7768"], "num_conversion_events": ["value": "0"], "domain": ["value": "hubspot.com"], "hs_num_child_companies": ["value": "0"], "hs_num_contacts_with_buying_roles": ["value": "0"], "hs_object_id": ["value": "10529379465"], "is_public": ["value": "true"], "name": ["value": "Hubspot, Inc."], "hs_analytics_source_data_2": ["value": "sample-contact"], "hs_analytics_latest_source": ["value": "OFFLINE"], "hs_analytics_source_data_1": ["value": "API"], "lifecyclestage": ["value": "lead"]]]]["properties"]}
{endnote: trim=yes}