Typeform API js client
Switch branches/tags
Clone or download
Pull request Compare This branch is 2 commits behind Typeform:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
tests
.babelrc
.gitignore
.travis.yml
README.md
package.json
webpack.config.js
yarn.lock

README.md

Typeform JavaScript SDK

Build Status


JS Client wrapper for Typeform API

Table of contents

Installation

# install with yarn
yarn add @typeform/api-client

# install with npm
npm install @typeform/api-client --save

Usage

Initialize

  1. Import client library
  import { createClient } from '@typeform/api-client'
  1. Create an instance with your personal token
  const typeformAPI = createClient({
    token: '<your token>'
  })
  1. 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
    })

Reference

createClient({token})

  • Creates a new instance of Typeform's JS client
  • Returns an instance with the methods described below
  const typeformClient = createClient({
    token: '<your token>'
  })

Client returns the following properties:

  • forms
  • images
  • teams
  • workspaces
  • themes
  • responses
  • webhooks

Each one of them encapsulates the operations related to it (like listing, updating, deleting the resource).

Forms

forms.list({ page: 1, pageSize = 10, search = '', page })

  • Get a list of your typeforms
  • Returns a list of typeforms with the payload referenced here.

forms.get({ uid })

  • Get a typeform by UID
  • Returns a typeform with the payload referenced here.

forms.update({ uid, data = {}, override = false })

  • Update a typeform by UID
  • Returns a typeform with the payload referenced here.

forms.delete({ uid })

  • Deletes a typeform by UID

forms.messages.get({ uid })

  • Get custom messages of the typeform with the given UID

forms.messages.update({ uid })

  • Updates custom messages of the typeform with the given UID

Images

images.list()

  • Get your images collection

images.get({ id, returns, size, backgroundSize, choiceSize })

  • Get custom image by ID
  • returns: json, binary (default)
  • size: default, thumbnail, mobile
  • backgroundSize: default, thumbnail, mobile, tablet
  • choiceSize: default, thumbnail, supersize, supermobile, supersizefit, supermobilefit

images.add({ image, mediaType, fileName })

  • Update an image to Typeform

images.delete({ id })

  • Deletes an image with the given ID

Teams

teams.get({ id })

  • Gets team information for the given ID

teams.addMembers({ id, members })

  • Add members to a team for the given ID
  • members: string or an array and should be the email fo the user
  • Adding multiple members at once is possible using an array of emails

teams.removeMembers({ id, members })

  • Remove members to a team for the given ID
  • members: string or an array and should be the email fo the user
  • Deleting multiple members at once is possible using an array of emails

Themes

themes.list({ page, pageSize })

  • Gets your themes collection
  • page: default 1
  • pageSize: default 10`

themes.get({ id })

  • Gets a theme for the given ID

themes.create({ background, colors, font, hasTransparentButton, name })

  • Creates a theme with the given configuration
  • See more details of the payload in the documentation

themes.update({ background, colors, font, hasTransparentButton, name })

  • Updates a theme with the given configuration
  • See more details of the payload in the documentation

themes.delete({ id })

  • Deletes the theme with the given ID

Workspaces

workspaces.list({ page, pageSize, search })

  • Gets your workspaces
  • page: default 1
  • pageSize: default 10
  • search: search a workspace that partially matches the search string

workspaces.get({ id })

  • Gets the workspace information for the given ID

workspaces.update({ id, data })

  • Updates the workspace information for the given ID
  • data: operation to perform that is wanted
  • See more details in the documentation

workspaces.delete({ id })

  • Deletes the workspace for the given ID

workspaces.get({ id })

  • Gets the workspace information for the given ID

workspaces.addMembers({ id, members })

  • Add members to a workspace for the given ID
  • members: string or an array that should be the email of the user
  • Adding multiple members at once is possible using an array of emails

workspaces.removeMembers({ id, members })

  • Remove members from a workspace for the given ID
  • members: string or an array that should be the email of the user
  • Removing multiple members at once is possible using an array of emails

Responses

responses.list({ uid, pageSize, since, until, after, before, completed, sort, query, fields })

  • List responses from the given ID
  • uid: typeform UID
  • For parameter details check the documentation

Webhooks

webhook.get({ uid, tag })

  • Get details for a webhook with the given tag
  • uid: typeform UID
  • tag: tag of the webhook created

webhook.create({ uid, tag, url, enable = false })

  • Create a webhook with the given tag
  • uid: typeform UID
  • tag: (string) tag of the webhook (how are you going to identify it)
  • url: (string) url of the service you want to notify
  • enable: (bool)

webhook.update({ uid, tag, url, enable = false })

  • Update a webhook with the given tag
  • uid: typeform UID
  • tag: (string) tag of the webhook (how are you going to identify it)
  • url: (string) url of the service you want to notify
  • enable: (bool)

webhook.delete({ uid, tag })

  • Delete a webhook with the given tag for a given typeform
  • uid: typeform UID
  • tag: (string) tag of the webhook

Examples

Update specific typeform property, as referenced here
  typeformClient
    .forms
    .update({
      uid: 'asdf',
      data: [
        {
          "op": "replace",
          "path": "/title",
          "value": 'new title'
        }
      ]
    })
    .then(response => {
      //... 
    })
Update the whole typeform
  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.

Uploading an image
  typeformClient
    .images
    .add({
      image: "bGRqZmxzZGpmbHNoZmtoc2RrZmpoc2tqZA==",
      mediaType: "image/gif",
      fileName: "newimage.gif"
    })
    .then(response => {
      //...
    })
Getting the thumbnail of an image
  typeformClient
    .images
    .get({ id: 'asdf', size: 'thumbnail' })
    .then(response => {
      //...
    })

Testing

To run unit tests.

yarn install

# Runs unit tests
yarn test:unit

Suggestions or feedback?

Fill out this conversation 🙂