JS Client wrapper for Typeform API
# install with yarn
yarn add @typeform/api-client
# install with npm
npm install @typeform/api-client --save- Import client library
// If using ESM syntax
import { createClient } from '@typeform/api-client'
// If using CJS syntax
const { createClient } = require('@typeform/api-client')- Create an instance with your personal token
const typeformAPI = createClient({ token: '<your token>' })If your account is configured to store responses in the EU Data Center
you can pass the apiBaseUrl as https://api.eu.typeform.com.
const typeformAPI = createClient(
{
token: '<your token>',
apiBaseUrl: 'https://api.eu.typeform.com'
}
)- Use any of the methods available in the reference
// will retrieve all forms
typeformAPI.forms.list().then((response) => {
// do what do you want with your typeforms
})Note: You can also execute the client binary directly via command line in your project:
yarn typeform-api <method> [params]See next section for more details.
-
Clone this repo on your machine
-
Install all dependencies:
yarn install- Set your personal token as
TF_TOKENenv variable
export TF_TOKEN=tfp_XXXXXXXXXX- Run the client:
yarn typeform-api <method> [params]See reference for all available method names and their params.
Example usage:
yarn typeform-api forms.list
yarn typeform-api forms.get '{uid:"abcd1234"}'
yarn typeform-api themes.list '{pageSize:3}'- Creates a new instance of Typeform's JS client
- Returns an instance with the methods described below
const typeformClient = createClient({ token: '<your token>' })
// If what you are trying to access doesn't require a token, you can construct the client without any argument
const typeformAPI = createClient()If your account is configured to store responses in the EU Data Center
you can pass the apiBaseUrl as https://api.eu.typeform.com.
const typeformAPI = createClient(
{
token: '<your token>',
apiBaseUrl: 'https://api.eu.typeform.com'
}
)Client returns the following properties:
formsimagesteamsworkspacesthemesresponseswebhooks
Each one of them encapsulates the operations related to it (like listing, updating, deleting the resource).
- Get a list of your typeforms
- Returns a list of typeforms with the payload referenced here.
- You can set
page: "auto"to automatically fetch all pages if there are more. It fetches with maximumpageSize: 200.
- Get a typeform by UID
- Returns a typeform with the payload referenced here.
- Create a typeform
- Returns a typeform with the payload referenced here.
- Update a typeform by UID
- Returns a typeform with the payload referenced here.
- Deletes a typeform by UID
- Copies an existing typeform with UID
workspaceUrl(optional) The URL of a workspace to copy the typeform into.
- Get custom messages of the typeform with the given UID
- Updates custom messages of the typeform with the given UID
- Get your images collection
- Get custom image by ID
size: default, thumbnail, mobilebackgroundSize: default, thumbnail, mobile, tabletchoiceSize: default, thumbnail, supersize, supermobile, supersizefit, supermobilefit
- Add an image to Typeform
image: Base64 code for the image. Note that base64 encoders may add descriptors to the code (such asdata:image/png;base64,). Do not include these descriptors in your image string---include only the base64 code. Use this orurl(below)url: URL of the image. Use this orimage(above)fileName: File name for the image
- Deletes an image with the given ID
- Gets your themes collection
page: default1- set
page: "auto"to automatically fetch all pages if there are more, it fetches with maximumpageSize: 200
- set
pageSize: default10`
- Gets a theme for the given ID
- Creates a theme with the given configuration
- See more details of the payload in the documentation
- Updates a theme with the given configuration, requires
id - See more details of the payload in the documentation
- Deletes the theme with the given ID
- Create a workspace.
name: Name of the new workspace.
- Add members to a workspace for the given ID
id: Unique ID for the workspace.members:stringor anarraythat should be the email of the user- Adding multiple members at once is possible using an array of emails
- Delete a workspace.
id: Unique ID for the workspace.
- Retrieve a workspace.
id: Unique ID for the workspace.
- Retrieve all workspaces in your account.
page: The page of results to retrieve. Default1is the first page of results.- set
page: "auto"to automatically fetch all pages if there are more, it fetches with maximumpageSize: 200
- set
pageSize: Number of results to retrieve per page. Default is 10. Maximum is 200.search: Returns items that contain the specified string.
- Remove members from a workspace for the given ID
members:stringor anarraythat should be the email of the user- Removing multiple members at once is possible using an array of emails
- Update a workspace.
id: Unique ID for the workspace.data: Patch operation to perform in an array structure. See more details in the documentation
- Delete responses to a form.
uid: Unique ID for the form.ids: Tokens of the responses to delete. You can list up to 1000 tokens. Accepts either a string or an array of strings.
- Returns form responses and date and time of form landing and submission.
uid: Unique ID for the form.pageSize: Maximum number of responses. Default value is 25. Maximum value is 1000.page: Set to"auto"to automatically fetch all pages if there are more. It fetches with maximumpageSize: 1000. Theaftervalue is ignored when automatic paging is enabled. The responses will be sorted in the order that our system processed them (instead of the default order,submitted_at). Note that it does not accept numeric value to identify page number.since: Limit request to responses submitted since the specified date and time. In ISO 8601 format, UTC time, to the second, with T as a delimiter between the date and time.until: Limit request to responses submitted until the specified date and time. In ISO 8601 format, UTC time, to the second, with T as a delimiter between the date and time.after: Limit request to responses submitted after the specified token. If you use theafterparameter, the responses will be sorted in the order that our system processed them (instead of the default order,submitted_at).before: Limit request to responses submitted before the specified token. If you use thebeforeparameter, the responses will be sorted in the order that our system processed them (instead of the default order,submitted_at).ids: Limit request to the specified ids. Accepts either a string or an array of strings.completed:trueif form was submitted. Otherwise,false.sort: Order of responses. Currently, responses are automatically sorted bysubmitted_at,desc---the date they were submitted, from newest to oldest. We plan to add more options for sort order soon.query: Limit request to only responses that that include the specified string. You can specify any string as thequeryvalue. The string will be escaped, and the query will include Hidden Fields.fields: Limit request to only responses for the specified fields. Accepts either a string or an array of strings.- For parameter details check the documentation
- Returns form level and individual question level insights for a given form.
uid: Unique ID for the form.
- Create a webhook.
uid: Unique ID for the form.tag: Unique name you want to use for the webhook.url: Webhook URL.enabled:trueif you want to send responses to the webhook immediately. Otherwise,false.secret: If specified, will be used to sign the webhook payload with HMAC SHA256, so that you can verify that it came from Typeform. (Recommended to add security)verifySSL:trueif you want Typeform to verify SSL certificates when delivering payloads.
- Delete a webhook.
uid: Unique ID for the form.tag: Unique name of the webhook.
- Get details for a webhook with the given tag
uid: Unique ID for the form.tag: tag of the webhook created
- Retrieve all webhooks for the specified typeform.
uid: Unique ID for the form.
- Update a webhook.
uid: Unique ID for the form.tag: Unique name you want to use for the webhook.url: Webhook URL.enabled:trueif you want to send responses to the webhook immediately. Otherwise,false.secret: If specified, will be used to sign the webhook payload with HMAC SHA256, so that you can verify that it came from Typeform.verifySSL:trueif you want Typeform to verify SSL certificates when delivering payloads.
- Turn on or off a webhook.
uid: Unique ID for the form.tag: tag of the webhook created.enabled:trueorfalse.
Update specific typeform property, as referenced here
typeformClient.forms
.update({
uid: 'asdf',
data: [
{
op: 'replace',
path: '/title',
value: 'new title',
},
],
})
.then((response) => {
//...
})typeformClient.forms
.update({
uid: 'asdf',
override: true,
data: {
title: newTitle,
theme: {
href: 'https://api.typeform.com/themes/6lPNE6',
},
},
})
.then((response) => {
//...
})Note:
The theme property applies a theme to the form. If you don't specify a value for the 'theme' property, Typeform applies a new copy of the default theme to the form, even if you already have a copy of the default theme applied to this form.
typeformClient.images
.add({
image: 'bGRqZmxzZGpmbHNoZmtoc2RrZmpoc2tqZA==',
mediaType: 'image/gif',
fileName: 'newimage.gif',
})
.then((response) => {
//...
})typeformClient.images
.get({ id: 'asdf', size: 'thumbnail' })
.then((response) => {
//...
})To run unit tests.
yarn install
# Runs unit tests
yarn test:unitFeel free to open a Github issue.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent