---
title: "Integrations: Forms API Reference | Linkbreakers"
description: "Connect Tally, Typeform, Jotform or Paperform: each response is attached to the visitor whose visit opened the form."
canonical: "https://linkbreakers.com/help/api/integrations-forms"
---

# Integrations: Forms

Connect Tally, Typeform, Jotform or Paperform: each response is attached to the visitor whose visit opened the form.

7 entries on this page

### Response

200

`connections` array of object

11 child attributes

`accountLabel` string

The account it is connected to, such as an email address.

`createdAt` string (date-time) 

Read-only

`delivery` object

Where: the links whose forms bring answers in. What: ALL answers, or SELECTED keys.

8 child attributes

`directoryIds` array of string

Where: directories it applies to, with every directory below them.

`linkIds` array of string

Where: links it applies to. All three lists empty means every link.

`moments` array of enum

When: the moments of a visit it sends at. Ignored when stepIds is set.

`stepIds` array of string

When: send only when a visit reaches one of these workflow steps.

`tagIds` array of string

Where: tags it applies to.

`targetsGone` boolean 

Read-only

Every link, directory and tag chosen has since been deleted, so this covers nothing. The lists above are then empty without meaning every link.

`visitorAttributeKeys` array of string

What: with SELECTED, the attribute keys sent, such as "$email" or "rating".

`visitorData` enum

How much of what is known about the visitor an integration sends.

Allowed values

* `INTEGRATION_VISITOR_DATA_NONE` Only the visit: the link, the step, the device and the place.
* `INTEGRATION_VISITOR_DATA_ALL` The visit, and every attribute known about the visitor.
* `INTEGRATION_VISITOR_DATA_SELECTED` The visit, and only the attributes named in visitorAttributeKeys.

`lastResponseAt` string (date-time) 

Read-only

`region` string

Jotform only: EU or HIPAA when the account lives there.

`responsesReceived` integer (int64) 

Read-only

`responsesSkipped` integer (int64) 

Read-only

Responses that came in without a visit ID, from another workspace, or from a link outside delivery.

`status` enum

Whether a connection brings answers in.

Allowed values

* `FORM_CONNECTION_STATUS_ACTIVE`
* `FORM_CONNECTION_STATUS_PAUSED`

`tool` enum

A form builder Linkbreakers connects to.

Allowed values

* `FORM_TOOL_TALLY`
* `FORM_TOOL_TYPEFORM`
* `FORM_TOOL_JOTFORM`
* `FORM_TOOL_PAPERFORM`

`visitorsEnriched` integer (int64) 

Read-only

`webhookUrl` string 

Read-only

The address to paste in the tool when it cannot be registered for the customer (Paperform without the Business API plan).

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X GET "https://api.linkbreakers.com/v1/form-integrations" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

Response 200

```json
{
  "connections": [
    {
      "accountLabel": "string",
      "createdAt": "2026-01-15T09:30:00Z",
      "delivery": {
        "directoryIds": [
          "string"
        ],
        "linkIds": [
          "string"
        ],
        "moments": [
          "KIND_ENTRY"
        ],
        "stepIds": [
          "string"
        ],
        "tagIds": [
          "string"
        ],
        "targetsGone": false,
        "visitorAttributeKeys": [
          "string"
        ],
        "visitorData": "INTEGRATION_VISITOR_DATA_NONE"
      },
      "lastResponseAt": "2026-01-15T09:30:00Z",
      "region": "string",
      "responsesReceived": 0,
      "responsesSkipped": 0,
      "status": "FORM_CONNECTION_STATUS_ACTIVE",
      "tool": "FORM_TOOL_TALLY",
      "visitorsEnriched": 0,
      "webhookUrl": "https://example.com"
    }
  ]
}
```

### Parameters

`tool` string 

path

Required

### Response

200

`connection` object

Empty when the tool is not connected.

11 child attributes, the same as [connections in the List form tool connections response](#list-form-tool-connections-response-connections).

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X GET "https://api.linkbreakers.com/v1/form-integrations/{tool}" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

Response 200

```json
{
  "connection": {
    "accountLabel": "string",
    "createdAt": "2026-01-15T09:30:00Z",
    "delivery": {
      "directoryIds": [
        "string"
      ],
      "linkIds": [
        "string"
      ],
      "moments": [
        "KIND_ENTRY"
      ],
      "stepIds": [
        "string"
      ],
      "tagIds": [
        "string"
      ],
      "targetsGone": false,
      "visitorAttributeKeys": [
        "string"
      ],
      "visitorData": "INTEGRATION_VISITOR_DATA_NONE"
    },
    "lastResponseAt": "2026-01-15T09:30:00Z",
    "region": "string",
    "responsesReceived": 0,
    "responsesSkipped": 0,
    "status": "FORM_CONNECTION_STATUS_ACTIVE",
    "tool": "FORM_TOOL_TALLY",
    "visitorsEnriched": 0,
    "webhookUrl": "https://example.com"
  }
}
```

### Parameters

`tool` string 

path

Required

### Response

200

`forms` array of object

8 child attributes

`checkedAt` string (date-time)

`customerStep` string

`formId` string

`formUrl` string

`lastError` string

`linkId` string

`linkName` string

`readiness` enum

Whether a form will match its responses to visits.

Allowed values

* `FORM_READINESS_READY` The hidden field and the webhook are in place.
* `FORM_READINESS_NEEDS_HIDDEN_FIELD` The customer must add the hidden lbid field in the tool (see customerStep).
* `FORM_READINESS_NEEDS_WEBHOOK` The customer must paste webhookUrl in the tool.
* `FORM_READINESS_FAILED` The tool refused a call; lastError says why.
* `FORM_READINESS_NOT_CHECKED` Not checked yet.

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X GET "https://api.linkbreakers.com/v1/form-integrations/{tool}/forms" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

Response 200

```json
{
  "forms": [
    {
      "checkedAt": "2026-01-15T09:30:00Z",
      "customerStep": "string",
      "formId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
      "formUrl": "https://example.com",
      "lastError": "string",
      "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
      "linkName": "string",
      "readiness": "FORM_READINESS_READY"
    }
  ]
}
```

### Parameters

`tool` string 

path

Required

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`apiKey` string

The account's API key: Tally Settings > API keys, Jotform Settings > API, Paperform Account > Developer.

`region` string

Jotform only: EU or HIPAA when the account lives there.

### Response

200

`connection` object

The workspace's account at one form tool.

11 child attributes, the same as [connections in the List form tool connections response](#list-form-tool-connections-response-connections).

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X POST "https://api.linkbreakers.com/v1/form-integrations/{tool}/connect" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "apiKey": "string",
  "region": "string"
}'
```

Response 200

```json
{
  "connection": {
    "accountLabel": "string",
    "createdAt": "2026-01-15T09:30:00Z",
    "delivery": {
      "directoryIds": [
        "string"
      ],
      "linkIds": [
        "string"
      ],
      "moments": [
        "KIND_ENTRY"
      ],
      "stepIds": [
        "string"
      ],
      "tagIds": [
        "string"
      ],
      "targetsGone": false,
      "visitorAttributeKeys": [
        "string"
      ],
      "visitorData": "INTEGRATION_VISITOR_DATA_NONE"
    },
    "lastResponseAt": "2026-01-15T09:30:00Z",
    "region": "string",
    "responsesReceived": 0,
    "responsesSkipped": 0,
    "status": "FORM_CONNECTION_STATUS_ACTIVE",
    "tool": "FORM_TOOL_TALLY",
    "visitorsEnriched": 0,
    "webhookUrl": "https://example.com"
  }
}
```

### Parameters

`tool` string 

path

Required

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

An empty JSON object.

### Response

200

`forms` array of object

8 child attributes

`checkedAt` string (date-time)

`customerStep` string

`formId` string

`formUrl` string

`lastError` string

`linkId` string

`linkName` string

`readiness` enum

Whether a form will match its responses to visits.

Allowed values

* `FORM_READINESS_READY` The hidden field and the webhook are in place.
* `FORM_READINESS_NEEDS_HIDDEN_FIELD` The customer must add the hidden lbid field in the tool (see customerStep).
* `FORM_READINESS_NEEDS_WEBHOOK` The customer must paste webhookUrl in the tool.
* `FORM_READINESS_FAILED` The tool refused a call; lastError says why.
* `FORM_READINESS_NOT_CHECKED` Not checked yet.

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X POST "https://api.linkbreakers.com/v1/form-integrations/{tool}/forms/prepare" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json"
```

Response 200

```json
{
  "forms": [
    {
      "checkedAt": "2026-01-15T09:30:00Z",
      "customerStep": "string",
      "formId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
      "formUrl": "https://example.com",
      "lastError": "string",
      "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
      "linkName": "string",
      "readiness": "FORM_READINESS_READY"
    }
  ]
}
```

### Parameters

`tool` string 

path

Required

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`delivery` object

Leave it out to keep the current setting.

7 child attributes

`directoryIds` array of string

Where: directories it applies to, with every directory below them.

`linkIds` array of string

Where: links it applies to. All three lists empty means every link.

`moments` array of enum

When: the moments of a visit it sends at. Ignored when stepIds is set.

`stepIds` array of string

When: send only when a visit reaches one of these workflow steps.

`tagIds` array of string

Where: tags it applies to.

`visitorAttributeKeys` array of string

What: with SELECTED, the attribute keys sent, such as "$email" or "rating".

`visitorData` enum

How much of what is known about the visitor an integration sends.

Allowed values

* `INTEGRATION_VISITOR_DATA_NONE` Only the visit: the link, the step, the device and the place.
* `INTEGRATION_VISITOR_DATA_ALL` The visit, and every attribute known about the visitor.
* `INTEGRATION_VISITOR_DATA_SELECTED` The visit, and only the attributes named in visitorAttributeKeys.

`status` enum

Leave UNSPECIFIED to keep the status.

Allowed values

* `FORM_CONNECTION_STATUS_ACTIVE`
* `FORM_CONNECTION_STATUS_PAUSED`

### Response

200

`connection` object

The workspace's account at one form tool.

11 child attributes, the same as [connections in the List form tool connections response](#list-form-tool-connections-response-connections).

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X PATCH "https://api.linkbreakers.com/v1/form-integrations/{tool}" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "delivery": {
    "directoryIds": [
      "string"
    ],
    "linkIds": [
      "string"
    ],
    "moments": [
      "KIND_ENTRY"
    ],
    "stepIds": [
      "string"
    ],
    "tagIds": [
      "string"
    ],
    "visitorAttributeKeys": [
      "string"
    ],
    "visitorData": "INTEGRATION_VISITOR_DATA_NONE"
  },
  "status": "FORM_CONNECTION_STATUS_ACTIVE"
}'
```

Response 200

```json
{
  "connection": {
    "accountLabel": "string",
    "createdAt": "2026-01-15T09:30:00Z",
    "delivery": {
      "directoryIds": [
        "string"
      ],
      "linkIds": [
        "string"
      ],
      "moments": [
        "KIND_ENTRY"
      ],
      "stepIds": [
        "string"
      ],
      "tagIds": [
        "string"
      ],
      "targetsGone": false,
      "visitorAttributeKeys": [
        "string"
      ],
      "visitorData": "INTEGRATION_VISITOR_DATA_NONE"
    },
    "lastResponseAt": "2026-01-15T09:30:00Z",
    "region": "string",
    "responsesReceived": 0,
    "responsesSkipped": 0,
    "status": "FORM_CONNECTION_STATUS_ACTIVE",
    "tool": "FORM_TOOL_TALLY",
    "visitorsEnriched": 0,
    "webhookUrl": "https://example.com"
  }
}
```

### Parameters

`tool` string 

path

Required

### Response

200

An empty JSON object.

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X DELETE "https://api.linkbreakers.com/v1/form-integrations/{tool}" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

---

Source: https://linkbreakers.com/help/api/integrations-forms
