formbricks-formbricks/apps/docs/app/developer-docs/api-sdk/page.mdx

import { MdxImage } from "@/components/mdx-image";

export const metadata = {
  title: "Formbricks API SDK",
  description:
    "An overview of all available methods & how to integrate Formbricks API for backend developers in web applications. Learn the key methods, configuration settings, and best practices.",
};

#### Developer Docs

# SDK: Formbricks API

### Overview

The Formbricks Client API Wrapper is a lightweight package designed to simplify the integration of Formbricks API endpoints into your JavaScript (JS) or TypeScript (TS) projects. With this wrapper, you can easily interact with Formbricks API endpoints without the need for complex setup or manual HTTP requests.

### Install

<Col>
<CodeGroup title="npm">

```js {{ title: 'npm' }}
npm install @formbricks/api
```

```js {{ title: 'yarn' }}
yarn add @formbricks/api
```

```js {{ title: 'pnpm' }}
pnpm add @formbricks/api
```

</CodeGroup>
</Col>

## Methods

### Initialize Formbricks

Initialize the Formbricks API Client for backend developers to interact with Formbricks API endpoints:

<Col>
<CodeGroup title="Initialize Formbricks API">

```javascript
import { FormbricksAPI } from "@formbricks/api";

const api = new FormbricksAPI({
  apiHost: `https://app.formbricks.com`, // If you have self-hosted Formbricks, change this to your self hosted instance's URL
  environmentId: "<environment-id>", // Replace this with your Formbricks environment ID
});
```

</CodeGroup>
</Col>

The API client is now ready to be used across your project. It can be used to interact with the following models:

## Displays

- Create Display

<Col>
<CodeGroup title="Crate Display">

```javascript {{ title: 'Create Display Method Call'}}
await api.client.display.create({
  surveyId: "<your-survey-id>", // required
  userId: "<your-user-id>", // optional
  responseId: "<your-response-id>", // optional
});
```

```javascript {{ title: 'Create Display Method Return Type' }}
Promise<{ id: string }, NetworkError | Error>
```

</CodeGroup>
</Col>

## Responses

- Create Response

<Col>
<CodeGroup title="Create Response">

```javascript {{ title: 'Create Response Method Call'}}
await api.client.response.create({
  surveyId: "<your-survey-id>", // required
  finished: boolean, // required
  data: {
    // required
    questionId: "<answer-to-this-question-in-string>",
    anotherQuestionId: 123, // answer to this question in number
    yetAnotherQuestionId: ["option1", "option2"], // answer to this question in array,
  },

  userId: "<your-user-id>",
  singleUseId: "<your-single-use-id>",
  ttc: {
    questionId: 123,
  },
  meta: {
    source: "<your-source>",
    url: "<your-url>",
    userAgent: {
      browser: "<your-browser>",
      device: "<your-device>",
      os: "<your-os>",
    },
    country: "<your-country>",
  },
});
```

```javascript {{ title: 'Create Response Method Return Type' }}
Promise<{ id: string }, NetworkError | Error>
```

</CodeGroup>
</Col>

- Update Response

<Col>
<CodeGroup title="Update Response">

```javascript {{ title: 'Update Response Method Call'}}
await api.client.response.update({
  responseId: "<your-response-id>", // required
  finished: boolean, // required
  data: {
    // required
    questionId: "<answer-to-this-question-in-string>",
    anotherQuestionId: 123, // answer to this question in number
    yetAnotherQuestionId: ["option1", "option2"], // answer to this question in array,
  },
  ttc: {
    // required
    questionId: 123,
  },
});
```

```javascript {{ title: 'Update Response Method Return Type' }}
Promise<{ }, NetworkError | Error]>
```

</CodeGroup>
</Col>

## Attribute

- Update Attribute

<Col>
<CodeGroup title="Update Attribute">

```javascript {{ title: 'Update Attribute Method Call'}}
await api.client.attribute.update({
  userId: "<your-user-id>", // required
  attributes: {
    key1: "value1",
    key2: "value2",
  }, // required
});
```

```javascript {{ title: 'Update Attribute Method Return Type' }}
Promise<{ changed: boolean, message: string }, NetworkError | Error>
```

</CodeGroup>
</Col>

## People

- Create Person

<Col>
<CodeGroup title="Create Person">

```javascript {{ title: 'Create Person Method Call'}}
await api.client.people.create({
  userId: "<your-user-id>", // required
});
```

```javascript {{ title: 'Create Person Method Return Type' }}
Promise<{ }, NetworkError | Error]>
```

</CodeGroup>
</Col>

## Storage

- Upload File:

<Col>
<CodeGroup title="Upload File">

```javascript {{ title: 'Upload Method Call'}}
await api.client.storage.uploadFile(
  file: File, // required (of interface File of the browser's File API)
  {
    allowedFileTypes: ["file-type-allowed", "for-example", "image/jpeg"],
    surveyId: "<your-survey-id>",
  }
);
```

```javascript {{ title: 'Upload Method Return Type' }}
Promise<fileUrl>
```

</CodeGroup>
</Col>

---

If you have any questions or need help, feel free to reach out to us in **[Github Discussions](https://github.com/formbricks/formbricks/discussions)**