---
title: "Form Integrations API Reference"
description: "Connect Tally, Typeform, Jotform or Paperform: each response lands on the visitor whose visit opened the form, through a hidden lbid field and a webhook."
canonical: "https://linkbreakers.com/help/api/form-integrations"
---

# Form Integrations

Connect Tally, Typeform, Jotform or Paperform: each response lands on the visitor whose visit opened the form, through a hidden lbid field and a webhook.

## Form Integrations

## [#](#form-integrations-object)The Integration Delivery object

IntegrationDelivery is the same three settings on every integration that sends data out: where (which links), when (which moments or steps) and what (how much visitor data). Everything has a default, so an integration works the moment it is connected and this is only for refining it.

directoryIds

array<string>

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

linkIds

array<string>

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

moments

array<string (enum)>

When: the moments of a visit it sends at. Ignored when step\_ids is set.

stepIds

array<string>

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

tagIds

array<string>

Where: tags it applies to.

targetsGone

boolean

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<string>

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

visitorData

string (enum)

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

##### Allowed values

`INTEGRATION_VISITOR_DATA_UNSPECIFIED`

`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 visitor\_attribute\_keys.

Example object

```json
{
  "directoryIds": [
    "string"
  ],
  "linkIds": [
    "string"
  ],
  "moments": [
    "KIND_UNSPECIFIED"
  ],
  "stepIds": [
    "string"
  ],
  "tagIds": [
    "string"
  ],
  "targetsGone": false,
  "visitorAttributeKeys": [
    "string"
  ],
  "visitorData": "INTEGRATION_VISITOR_DATA_UNSPECIFIED"
}
```

GET

`/v1/form-integrations`

Requires auth

## [#](#list-form-tool-connections)List form tool connections

Return the workspace's connected form tools: Tally, Typeform, Jotform and Paperform. Requires the \`integrations:read\` scope.

### [#](#list-form-tool-connections-parameters)Parameters

This endpoint does not accept any parameters.

### [#](#list-form-tool-connections-response)Response

200

Everything worked as expected.

connections

array<object>

### [#](#list-form-tool-connections-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

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

Typical response

```json
{
  "connections": [
    {
      "accountLabel": "string",
      "createdAt": "2026-11-07T23:20:28.804Z",
      "delivery": {
        "directoryIds": [],
        "linkIds": [],
        "moments": [],
        "stepIds": [],
        "tagIds": [],
        "targetsGone": false,
        "visitorAttributeKeys": [],
        "visitorData": "INTEGRATION_VISITOR_DATA_UNSPECIFIED"
      },
      "lastResponseAt": "2026-11-07T23:20:28.805Z",
      "region": "string",
      "responsesReceived": 0,
      "responsesSkipped": 0,
      "status": "FORM_CONNECTION_STATUS_UNSPECIFIED",
      "tool": "FORM_TOOL_UNSPECIFIED",
      "visitorsEnriched": 0,
      "webhookUrl": "https://example.com"
    }
  ]
}
```

Base URL: `https://api.linkbreakers.com`

GET

`/v1/form-integrations/{tool}`

Requires auth

## [#](#get-a-form-tool-connection)Get a form tool connection

Return one form tool's connection, empty when it is not connected. Requires the \`integrations:read\` scope.

### [#](#get-a-form-tool-connection-parameters)Parameters

#### path parameters

tool

string

Required

path

### [#](#get-a-form-tool-connection-response)Response

200

Everything worked as expected.

connection

object

FormConnection is the workspace's account at one form tool.

### [#](#get-a-form-tool-connection-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

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

Typical response

```json
{
  "connection": {
    "accountLabel": "string",
    "createdAt": "2026-11-07T23:20:28.805Z",
    "delivery": {
      "directoryIds": [
        "string"
      ],
      "linkIds": [
        "string"
      ],
      "moments": [
        "KIND_UNSPECIFIED"
      ],
      "stepIds": [
        "string"
      ],
      "tagIds": [
        "string"
      ],
      "targetsGone": false,
      "visitorAttributeKeys": [
        "string"
      ],
      "visitorData": "INTEGRATION_VISITOR_DATA_UNSPECIFIED"
    },
    "lastResponseAt": "2026-11-07T23:20:28.805Z",
    "region": "string",
    "responsesReceived": 0,
    "responsesSkipped": 0,
    "status": "FORM_CONNECTION_STATUS_UNSPECIFIED",
    "tool": "FORM_TOOL_UNSPECIFIED",
    "visitorsEnriched": 0,
    "webhookUrl": "https://example.com"
  }
}
```

Base URL: `https://api.linkbreakers.com`

GET

`/v1/form-integrations/{tool}/forms`

Requires auth

## [#](#list-the-forms-found-behind-links)List the forms found behind links

Return the forms of a connected tool behind the workspace's links, each with whether it is ready. Requires the \`integrations:read\` scope.

### [#](#list-the-forms-found-behind-links-parameters)Parameters

#### path parameters

tool

string

Required

path

### [#](#list-the-forms-found-behind-links-response)Response

200

Everything worked as expected.

forms

array<object>

### [#](#list-the-forms-found-behind-links-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

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

Typical response

```json
{
  "forms": [
    {
      "checkedAt": "2026-11-07T23:20:28.806Z",
      "customerStep": "string",
      "formId": "string",
      "formUrl": "https://example.com",
      "lastError": "string",
      "linkId": "string",
      "linkName": "string",
      "readiness": "FORM_READINESS_UNSPECIFIED"
    }
  ]
}
```

Base URL: `https://api.linkbreakers.com`

GET

`/v1/form-integrations/{tool}/oauth-url`

Requires auth

## [#](#start-signing-in-to-a-form-tool)Start signing in to a form tool

Return the URL where the user signs in to Typeform to connect it. Requires the \`integrations:write\` scope.

### [#](#start-signing-in-to-a-form-tool-parameters)Parameters

#### path parameters

tool

string

Required

path

### [#](#start-signing-in-to-a-form-tool-response)Response

200

Everything worked as expected.

oauthUrl

string

### [#](#start-signing-in-to-a-form-tool-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

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

Typical response

```json
{
  "oauthUrl": "https://example.com"
}
```

Base URL: `https://api.linkbreakers.com`

POST

`/v1/form-integrations/{tool}/connect`

Requires auth

## [#](#connect-a-form-tool-with-an-api-key)Connect a form tool with an API key

Connect Tally, Jotform or Paperform with the account's API key. The forms behind the workspace's links are prepared at once: a hidden lbid field and a webhook. Requires the \`integrations:write\` scope.

### [#](#connect-a-form-tool-with-an-api-key-parameters)Parameters

#### path parameters

tool

string

Required

path

#### header parameters

Idempotency-Key

string

header

Makes retrying this request safe. See components.parameters.IdempotencyKey.

### [#](#connect-a-form-tool-with-an-api-key-request)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.

### [#](#connect-a-form-tool-with-an-api-key-response)Response

200

Everything worked as expected.

connection

object

FormConnection is the workspace's account at one form tool.

### [#](#connect-a-form-tool-with-an-api-key-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

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

Sample payload (application/json)

```json
{
  "apiKey": "string",
  "region": "string"
}
```

Typical response

```json
{
  "connection": {
    "accountLabel": "string",
    "createdAt": "2026-11-07T23:20:28.806Z",
    "delivery": {
      "directoryIds": [
        "string"
      ],
      "linkIds": [
        "string"
      ],
      "moments": [
        "KIND_UNSPECIFIED"
      ],
      "stepIds": [
        "string"
      ],
      "tagIds": [
        "string"
      ],
      "targetsGone": false,
      "visitorAttributeKeys": [
        "string"
      ],
      "visitorData": "INTEGRATION_VISITOR_DATA_UNSPECIFIED"
    },
    "lastResponseAt": "2026-11-07T23:20:28.806Z",
    "region": "string",
    "responsesReceived": 0,
    "responsesSkipped": 0,
    "status": "FORM_CONNECTION_STATUS_UNSPECIFIED",
    "tool": "FORM_TOOL_UNSPECIFIED",
    "visitorsEnriched": 0,
    "webhookUrl": "https://example.com"
  }
}
```

Base URL: `https://api.linkbreakers.com`

POST

`/v1/form-integrations/{tool}/forms/prepare`

Requires auth

## [#](#check-the-forms-again)Check the forms again

Add the hidden field and webhook to every form behind a link now, rather than at the next daily check. Requires the \`integrations:write\` scope.

### [#](#check-the-forms-again-parameters)Parameters

#### path parameters

tool

string

Required

path

#### header parameters

Idempotency-Key

string

header

Makes retrying this request safe. See components.parameters.IdempotencyKey.

### [#](#check-the-forms-again-request)Request body

No structured schema available for this section.

### [#](#check-the-forms-again-response)Response

200

Everything worked as expected.

forms

array<object>

### [#](#check-the-forms-again-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

```bash
curl -X POST "https://api.linkbreakers.com/v1/form-integrations/{tool}/forms/prepare" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  --data '{}'
```

Sample payload (application/json)

```json
{}
```

Typical response

```json
{
  "forms": [
    {
      "checkedAt": "2026-11-07T23:20:28.806Z",
      "customerStep": "string",
      "formId": "string",
      "formUrl": "https://example.com",
      "lastError": "string",
      "linkId": "string",
      "linkName": "string",
      "readiness": "FORM_READINESS_UNSPECIFIED"
    }
  ]
}
```

Base URL: `https://api.linkbreakers.com`

POST

`/v1/form-integrations/{tool}/oauth-callback`

Requires auth

## [#](#finish-signing-in-to-a-form-tool)Finish signing in to a form tool

Exchange the code Typeform returned after sign-in and connect the account. Requires the \`integrations:write\` scope.

### [#](#finish-signing-in-to-a-form-tool-parameters)Parameters

#### path parameters

tool

string

Required

path

#### header parameters

Idempotency-Key

string

header

Makes retrying this request safe. See components.parameters.IdempotencyKey.

### [#](#finish-signing-in-to-a-form-tool-request)Request body

code

string

state

string

### [#](#finish-signing-in-to-a-form-tool-response)Response

200

Everything worked as expected.

connection

object

FormConnection is the workspace's account at one form tool.

### [#](#finish-signing-in-to-a-form-tool-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

```bash
curl -X POST "https://api.linkbreakers.com/v1/form-integrations/{tool}/oauth-callback" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  --data '{"code":"string","state":"string"}'
```

Sample payload (application/json)

```json
{
  "code": "string",
  "state": "string"
}
```

Typical response

```json
{
  "connection": {
    "accountLabel": "string",
    "createdAt": "2026-11-07T23:20:28.806Z",
    "delivery": {
      "directoryIds": [
        "string"
      ],
      "linkIds": [
        "string"
      ],
      "moments": [
        "KIND_UNSPECIFIED"
      ],
      "stepIds": [
        "string"
      ],
      "tagIds": [
        "string"
      ],
      "targetsGone": false,
      "visitorAttributeKeys": [
        "string"
      ],
      "visitorData": "INTEGRATION_VISITOR_DATA_UNSPECIFIED"
    },
    "lastResponseAt": "2026-11-07T23:20:28.806Z",
    "region": "string",
    "responsesReceived": 0,
    "responsesSkipped": 0,
    "status": "FORM_CONNECTION_STATUS_UNSPECIFIED",
    "tool": "FORM_TOOL_UNSPECIFIED",
    "visitorsEnriched": 0,
    "webhookUrl": "https://example.com"
  }
}
```

Base URL: `https://api.linkbreakers.com`

PATCH

`/v1/form-integrations/{tool}`

Requires auth

## [#](#update-a-form-tool-connection)Update a form tool connection

Pause or resume it, or change which links' forms bring answers in and which answers are kept. Requires the \`integrations:write\` scope.

### [#](#update-a-form-tool-connection-parameters)Parameters

#### path parameters

tool

string

Required

path

#### header parameters

Idempotency-Key

string

header

Makes retrying this request safe. See components.parameters.IdempotencyKey.

### [#](#update-a-form-tool-connection-request)Request body

delivery

object

IntegrationDelivery is the same three settings on every integration that sends data out: where (which links), when (which moments or steps) and what (how much visitor data). Everything has a default, so an integration works the moment it is connected and this is only for refining it.

status

string (enum)

FormConnectionStatus is whether a connection brings answers in.

##### Allowed values

`FORM_CONNECTION_STATUS_UNSPECIFIED`

`FORM_CONNECTION_STATUS_ACTIVE`

`FORM_CONNECTION_STATUS_PAUSED`

### [#](#update-a-form-tool-connection-response)Response

200

Everything worked as expected.

connection

object

FormConnection is the workspace's account at one form tool.

### [#](#update-a-form-tool-connection-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

```bash
curl -X PATCH "https://api.linkbreakers.com/v1/form-integrations/{tool}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  --data '{"delivery":{"directoryIds":["string"],"linkIds":["string"],"moments":["KIND_UNSPECIFIED"],"stepIds":["string"],"tagIds":["string"],"targetsGone":false,"visitorAttributeKeys":["string"],"visitorData":"INTEGRATION_VISITOR_DATA_UNSPECIFIED"},"status":"FORM_CONNECTION_STATUS_UNSPECIFIED"}'
```

Sample payload (application/json)

```json
{
  "delivery": {
    "directoryIds": [
      "string"
    ],
    "linkIds": [
      "string"
    ],
    "moments": [
      "KIND_UNSPECIFIED"
    ],
    "stepIds": [
      "string"
    ],
    "tagIds": [
      "string"
    ],
    "targetsGone": false,
    "visitorAttributeKeys": [
      "string"
    ],
    "visitorData": "INTEGRATION_VISITOR_DATA_UNSPECIFIED"
  },
  "status": "FORM_CONNECTION_STATUS_UNSPECIFIED"
}
```

Typical response

```json
{
  "connection": {
    "accountLabel": "string",
    "createdAt": "2026-11-07T23:20:28.805Z",
    "delivery": {
      "directoryIds": [
        "string"
      ],
      "linkIds": [
        "string"
      ],
      "moments": [
        "KIND_UNSPECIFIED"
      ],
      "stepIds": [
        "string"
      ],
      "tagIds": [
        "string"
      ],
      "targetsGone": false,
      "visitorAttributeKeys": [
        "string"
      ],
      "visitorData": "INTEGRATION_VISITOR_DATA_UNSPECIFIED"
    },
    "lastResponseAt": "2026-11-07T23:20:28.805Z",
    "region": "string",
    "responsesReceived": 0,
    "responsesSkipped": 0,
    "status": "FORM_CONNECTION_STATUS_UNSPECIFIED",
    "tool": "FORM_TOOL_UNSPECIFIED",
    "visitorsEnriched": 0,
    "webhookUrl": "https://example.com"
  }
}
```

Base URL: `https://api.linkbreakers.com`

DELETE

`/v1/form-integrations/{tool}`

Requires auth

## [#](#disconnect-a-form-tool)Disconnect a form tool

Remove our webhooks from its forms and forget the credential. Requires the \`integrations:write\` scope.

### [#](#disconnect-a-form-tool-parameters)Parameters

#### path parameters

tool

string

Required

path

### [#](#disconnect-a-form-tool-response)Response

200

Everything worked as expected.

No structured schema available for this section.

### [#](#disconnect-a-form-tool-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

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

Typical response

```json
{}
```

Base URL: `https://api.linkbreakers.com`

---

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