formbricks/packages/api/README.md

# @formbricks/api - API Wrapper for Formbricks

This is the official API wrapper for Formbricks. It is used to interact with the Formbricks API. To know more about Formbricks, visit [Formbricks.com](https://formbricks.com).

The direct API documentation can be found in our official docs [here](https://formbricks.com/docs/api/client/overview). To interact with the Formbricks API, you need to have an environment ID. You can get it from the Formbricks dashboard at [app.formbricks.com](https://app.formbricks.com).

## Installation

```bash
npm install @formbricks/api
```

## Usage

### Init

```ts
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
});
```

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

### Display

- Create a Display

  ```ts
  await api.client.display.create({
    surveyId: "<your-survey-id>", // required
    userId: "<your-user-id>", // optional
    responseId: "<your-response-id>", // optional
  });
  ```

- Update a Display

  ```ts
  await api.client.display.update(
    displayId: "<your-display-id>",
    {
      userId: "<your-user-id>", // optional
      responseId: "<your-response-id>", // optional
    },
  );
  ```

### Response

- Create a Response

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

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

- Update a Response

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

### Action

- Create an Action

  ```ts
  await api.client.action.create({
    name: "<your-action-name>", // required
    properties: {
      key1: "value1",
      key2: "value2",
      key3AsNumber: 123,
    }, // required

    personId: "<your-person-id>", // optional
    sessionId: "<your-session-id>", // optional
  });
  ```

### People

- Create a Person

  ```ts
  await api.client.people.create({
    userId: "<your-user-id>", // required
  });
  ```

- Update a Person

  ```ts
  await api.client.people.update(personId: "<your-person-id>", // required
  {
    attributes: {
      key1: "value1",
      key2: "value2",
      key3AsNumber: 456,
    }, // required
  }
  ```

### Storage

- Upload a file

  ```ts
  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"], // optional
      surveyId: "<your-survey-id>", // optional

    } // optional
  );
  ```

If you have any questions or need help, feel free to reach out to us on our [Discord](https://formbricks.com/discord)