API docs by Redocly

Tiled API (0.9.10)

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 this link. To get the collection working, you'll need to setup an environment and replace environment with v1.tiled.co and apiKey with the API key you copied from the Tiled website.

analytics

List all sessions

Returns a list of sessions for microapps in your account.

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

The date for which you want to retrieve analytics session data

microappId
string
Example: microappId=95953ed244a5f409f38cad2a

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

timezone
string
Example: timezone=America/Los_Angeles

(Defaults to UTC) A specific timezone name to retrieve analytics session data. Please see the list of supported timezones at "TZ database name"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Export all sessions

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

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

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

microappId
string
Example: microappId=95953ed244a5f409f38cad2a

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

timezone
string
Example: timezone=America/Los_Angeles

(Defaults to UTC) A specific timezone name to retrieve analytics session data. Please see the list of supported timezones at "TZ database name"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List aggregated analytics for a specific adaptive format of a microapp

Returns aggregated data of views and average duration for each page of a specific adaptive format.

Authorizations:
ApiKey
query Parameters
documentId
required
string
Example: documentId=95953ed244a5f409f38cad2a

The specific adaptive format's id you are pulling aggregated data for

date
string <date-time>
Example: date=2021-01-01

(optional) The date for which the aggregation should start through the current date. If no date is provided, the call will default to the microapp's created date.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Export aggregated analytics for a specific adaptive format of a microapp

Returns aggregated data of views and average duration for each page of a specific adaptive format.

Authorizations:
ApiKey
query Parameters
documentId
required
string
Example: documentId=95953ed244a5f409f38cad2a

The specific adaptive format's id you are pulling aggregated data for

date
string <date-time>
Example: date=2021-01-01

(optional) The date for which the aggregation should start through the current date. If no date is provided, the call will default to the microapp's created date.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

microapps

List all microapps

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

Authorizations:
ApiKey
query Parameters
archived
boolean

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

Responses

Response samples

Content type
application/json
[
  • {
    }
]

List all completion events of a microapp

Returns a list of all the completion events of a microapp

Authorizations:
ApiKey
path Parameters
microappId
required
string

The id of the microapp

query Parameters
csv
string

To retrieve information in a csv file format, set csv value to "true"

Responses

Response samples

Content type
application/json
{
  • "microappId": "5be33ed244a5f409f38cad2b",
  • "microappName": "Microapp Name",
  • "documents": [
    ]
}

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:
ApiKey
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

Response samples

Content type
application/json
{
  • "id": "5be33ed244a5f409f38cad2c",
  • "shareUrl": "https://s.tiled.co/KF58Y5",
  • "microappId": "5be33ed244a5f409f38cad2b",
  • "createdAt": "2018-11-10 19:36:50.095Z",
  • "recipientEmail": "alice@example.com",
  • "recipientName": "Alice Waters"
}

Create an instance of a microapp

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

Authorizations:
ApiKey
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

Response samples

Content type
application/json
{
  • "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:
ApiKey
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

Response samples

Content type
application/json
{
  • "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:
ApiKey
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

Response samples

Content type
application/json
[
  • {
    }
]

Get all the shares of a specific microapp

Returns the data associated with every share of a specific microapp.

Authorizations:
ApiKey
path Parameters
microappId
required
string

The id of the microapp

query Parameters
extended
boolean

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

Responses

Response samples

Content type
application/json
{
  • "id": "5be33ed244a5f409f38cad2c",
  • "microappId": "5be33ed244a5f409f38cad2b",
  • "shareUrl": "https://s.tiled.co/KF58Y5",
  • "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 link 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:
ApiKey
path Parameters
sharedMicroappId
required
string

The id of the shared microapp link to update

query Parameters
expireAt
string <date-time>

The date the shared microapp link should expire at

Responses

Response samples

Content type
application/json
{
  • "id": "5be33ed244a5f409f38cad2c",
  • "shareUrl": "https://s.tiled.co/KF58Y5",
  • "microappId": "5be33ed244a5f409f38cad2b",
  • "createdAt": "2018-11-10 19:36:50.095Z",
  • "recipientEmail": "alice@example.com",
  • "recipientName": "Alice Waters"
}

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:
ApiKey
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

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:
ApiKey
path Parameters
microappId
required
string

The id for the microapp you want to link to

Responses

personalization

Get info about personalization options for a microapp

Returns information about a microapp's personalization options, including how many created instances exist and what dynamic fields are available to personalize.

Authorizations:
ApiKey
path Parameters
microappId
required
string

The id of the microapp for personalization info

Responses

Response samples

Content type
application/json
{
  • "instanceCount": 5,
  • "dynamicFields": [
    ]
}

Create a new instance of a given microapp

Given a name and some data, creates and fills out fields for a new instance of a microapp

Authorizations:
ApiKey
path Parameters
microappId
required
string

The id of the microapp for personalization info.

query Parameters
name
required
string

A unique name for your instance

ownerEmail
required
string

Your email address

{{fieldId}}
text/file

Dynamic value to apply to the dynamic field id. The field ids can be retrieved via the info endpoint. File must be less than 10MB.

Responses

Response samples

Content type
application/json
{
  • "instanceId": "5be33ed244a5f409f38cad2b",
  • "microappId": "5be33ed244a5f409f38cad2b",
  • "name": "Sales Prospect Alpha"
}

Update an instance and/or its data

Update the native properties of the instance on the microapp, and/or overwrite any or all of the values mapped by each field id.

Authorizations:
ApiKey
path Parameters
microappId
required
string

The id of the microapp for personalization info.

instanceId
required
string

The id of the instance for personalization.

query Parameters
name
string

A unique name for your instance

{{fieldId}}
text/file

Dynamic value to apply to the dynamic field id. The field ids can be retrieved via the info endpoint. File must be less than 10MB.

Responses

Response samples

Content type
application/json
{
  • "instanceId": "5be33ed244a5f409f38cad2b",
  • "microappId": "5be33ed244a5f409f38cad2b",
  • "name": "Sales Prospect Alpha"
}