Tiled API (0.9.8)

Download OpenAPI specification:Download

This API exposes the power of Tiled through programmatic access. You can automate workflows, integrate with your CRM or embed Tiled in your CMS. All you need to do is generate an API key from your Tiled account and you're ready to go!

If you need help working with the API, we recommend downloading our Postman collection which can be imported from https://www.getpostman.com/collections/48dab7ebed0ca84b000a. To get the collection working, you'll need to setup an environment and replace environment with v1 and apiKey with the API key you copied from the Tiled website.

Authentication

ApiKey

All endpoints must be accompanied with an apiKey as a url param. If the request is a POST or PUT, apiKey can instead be passed in the JSON body. For instance, to get a list of microapps, you would call https://v1.tiled.co/microapps?apiKey=myKey. You can generate API keys (or tokens) by going to https://app.tiled.co, clicking on your avatar in the upper right, selecting "Account Settings" and scrolling down to the section named "API Tokens". You can generate a key here as well as name it. Caution, the key/token will only be displayed once so copy it and keep it in a safe place. Keys can be generated and deleted anytime from this interface.

Security scheme type: API Key
Query parameter name: apiKey

analytics

List all sessions

Returns a list of sessions for microapps in your account.

Authorizations:
query Parameters
date
required
string <date-time>

The date for which you want to retrieve analytics session data

microappId
string
Example: "95953ed244a5f409f38cad2a"

A specific microapp Id that you want sessions and completion events for.

Responses

200

An array of microapp sessions for the account

401

Unauthorized Error

get /analytics/sessions
https://v1.tiled.co//analytics/sessions

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Export all sessions

Returns a CSV export of sessions for microapps in your account.

Authorizations:
query Parameters
date
required
string <date-time>

The date for which you want to retrieve analytics session data.

microappId
string
Example: "95953ed244a5f409f38cad2a"

A specific microapp Id that you want sessions and completion events for.

Responses

200

A CSV export of microapp sessions for the account

401

Unauthorized Error

get /analytics/sessions.csv
https://v1.tiled.co//analytics/sessions.csv

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

microapps

List all microapps

Returns a list of microapps in your account along with a few relevant properties.

Authorizations:
query Parameters
archived
boolean

Passing true will return microapps that have been archived in addition to non-archived microapps. The default is false.

Responses

200

An array of microapps in the account

401

Unauthorized Error

get /microapps
https://v1.tiled.co//microapps

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Share microapp by id

Fires off an email to the recipientEmail using an email template. The email will contain a trackable link to the microapp you are sharing with the recipient along with the message set in your Tiled Account settings.

Authorizations:
path Parameters
microappId
required
string

The id of the microapp to share

query Parameters
userEmail
required
string

The email of the Tiled user sharing the microapp

recipientName
required
string

The name of the person receiving the microapp

recipientEmail
required
string

The email of the person receiving the microapp

sendEmail
boolean

If you want to send an email, set this to true. Otherwise, you can just use the link that comes back from this endpoint.

instanceId
object

The id of the instance object that should be inserted when sharing this microapp

expireAt
string <date-time>

The date on which the microapp should expire

Responses

200

Expected response to a valid request

400

Bad Request Error

401

Unauthorized Error

post /microapps/{microappId}/share
https://v1.tiled.co//microapps/{microappId}/share

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Create an instance of a microapp

Creates an instance of a microapp that can be shared using the microapp /share endpoint.

Authorizations:
path Parameters
microappId
required
string

The id of the microapp to which you want to associate a new instance

query Parameters
userEmail
string

The email of the Tiled user that will own this instance. If you omit this, everyone in your organization will have access to this instance.

title
required
string

The name to give this instance

data
required
object

A key/value dictionary to associate with this instance. You can find the API names for instance data mapping from the Settings dialog of a microapp in the Hub.

Responses

200

Expected response to a valid request

400

Bad Request Error

401

Unauthorized Error

post /microapps/{microappId}/instance
https://v1.tiled.co//microapps/{microappId}/instance

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "5be33ed244a5f409f38cad2a",
  • "title": "My Instance",
  • "data":
    {
    }
}

Update an instance of a microapp

Adds or removes keys from the data of an instance. The caller can also change the owner.

Authorizations:
path Parameters
instanceId
required
string

The id of the instance to update

query Parameters
userEmail
string

The email of the Tiled user that owns this instance. If you omit this, the owner will not change. If you set this to empty string (i.e. ""), we'll remove the current owner.

title
string

The name to update this instance with

data
object

A key/value dictionary to update this instance with. If this is omitted, the value won't change. You can find the API names for instance data mappings from the Settings dialog of a microapp in the Hub.

Responses

200

Expected response to a valid request

400

Bad Request Error

401

Unauthorized Error

put /instances/{instanceId}
https://v1.tiled.co//instances/{instanceId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "5be33ed244a5f409f38cad2a",
  • "title": "My Instance",
  • "data":
    {
    }
}

sharedmicroapps

List all shared microapps

Returns a list of shared microapps in your account along with a few relevant properties.

Authorizations:
query Parameters
recipientId
required
string

The id of the recipient (e.g. email or unique identifier) whose shared microapp record you want to retrieve.

userEmail
string

Passing in an email here restricts the returned records to those sent by the Tiled user that has this email address.

extended
boolean

Passing in true will return extended information like the engagement score.

Responses

200

An array of shared microapps in the account

401

Unauthorized Error

get /sharedMicroapps
https://v1.tiled.co//sharedMicroapps

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Get a shared microapp by id

Returns the data associated with every share of a microapp in the account.

Authorizations:
path Parameters
sharedMicroappId
required
string

The id of the shared microapp to get

query Parameters
extended
boolean

Passing in true will return extended information like the engagement score.

Responses

200

Expected response to a valid request

400

Bad Request Error

401

Unauthorized Error

get /sharedMicroapps/{sharedMicroappId}
https://v1.tiled.co//sharedMicroapps/{sharedMicroappId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "5be33ed244a5f409f38cad2c",
  • "microappId": "5be33ed244a5f409f38cad2b",
  • "createdAt": "2018-11-10 19:36:50.095Z",
  • "emailOpenedAt": "2018-11-11 19:36:50.095Z",
  • "openedAt": "2018-11-12 19:36:50.095Z",
  • "instanceId": "5be33ed244a5f409f38cad2a",
  • "userEmail": "user@tiled.co",
  • "recipientEmail": "alice@example.com",
  • "recipientName": "Alice Waters",
  • "expireAt": "2019-12-31 19:36:50.095Z",
  • "engagementScore": 50.5,
  • "completions":
    [
    ]
}

Update a shared microapp by id

Update a shared microapp with a new expiration. Note that this doesn't fire off a new email. Instead, it updates the data backing the email that already went out.

Authorizations:
path Parameters
sharedMicroappId
required
string

The id of the shared microapp to update

query Parameters
expireAt
string <date-time>

The date the shared microapp should expire at

Responses

200

Expected response to a valid request

400

Bad Request Error

401

Unauthorized Error

put /sharedMicroapps/{sharedMicroappId}
https://v1.tiled.co//sharedMicroapps/{sharedMicroappId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "5be33ed244a5f409f38cad2c",
  • "microappId": "5be33ed244a5f409f38cad2b",
  • "createdAt": "2018-11-10 19:36:50.095Z",
  • "emailOpenedAt": "2018-11-11 19:36:50.095Z",
  • "openedAt": "2018-11-12 19:36:50.095Z",
  • "instanceId": "5be33ed244a5f409f38cad2a",
  • "userEmail": "user@tiled.co",
  • "recipientEmail": "alice@example.com",
  • "recipientName": "Alice Waters",
  • "expireAt": "2019-12-31 19:36:50.095Z",
  • "engagementScore": 50.5,
  • "completions":
    [
    ]
}

embed

iFrame embed a Tiled microapp

The link structure to embed a Tiled microapp in an iframe. The embed can be copied from the settings pane of a microapp and the iframe code will look something like
<iframe src="https://s.tiled.co/abcdef7?dynamic=true&recipientId=7bdc2f3fb094448392619a5465402128&recipientName=Bob%20Beetlejuice&data=%7B"test"%3A"val1"%2C"test-2"%3A"val2"%7D" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen width="800" height="450"></iframe>

Authorizations:
path Parameters
shortUrlKey
required
string

The shortened url for key for the embedded microapp

query Parameters
dynamic
boolean

This must be set to "true" if you want to track the viewer as a unique user

recipientId
string

A unique identifier (e.g. email, GUID. Must be unique) of the person receiving the microapp. Required if dynamic=true

recipientName
string

The full name of the person receiving the microapp

userEmail
string

The email of the Tiled user you would like to associate with this session. By setting this, you can find all the analytics for a session by drilling into this Tiled user on Tiled's website.

data
string

The JSON instance data to insert into this microapp. Note that this parameter will need to be URI encoded just like any other URL param. You can find the API names for instance data mappings from the Settings dialog of a microapp in the Hub.

Responses

200

HTML for microapp embed

get /{shortUrlKey}
https://s.tiled.co//{shortUrlKey}

Deep link into a microapp

By using a URL like https://app.tiled.co/microapp/abc1234, you are able to link directly to a microapp. This only applies to users who have an account in Tiled. When going to this URL, you will either go to the microapp in your browser or you will deep link into the iOS or Android app if you open it on a mobile device with the Tiled app installed. You can construct this link programatically by taking the microappId from the /microapps endpoint and appending it to https://app.tiled.co/microapp/

Authorizations:
path Parameters
microappId
required
string

The id for the microapp you want to link to

Responses

200

Deep link to microapp

get /{microappId}
https://app.tiled.co/microapp/{microappId}