API
Lead capture
Ask a publication's readers for their details before they read on, then list, export and erase what they send.
A document's lead form is part of how it is published. With when set to open or after, the viewer asks readers for the fields that are on, either before the first page or once they turn past afterPages: a name, an email, a company, a phone number, one question of the workspace's own, and a consent box. Until a reader answers, or skips where skip allows, the viewer serves no page past the form and no PDF download. The form shows only while the plan includes lead capture (available on leads.formGet).
Each answer is stored as a submission against the document and raises the form.submitted webhook event. A submission holds only the fields the form asked for, and nothing about the reader's connection. A document keeps at most 50,000 submissions; past that, new answers are not stored and readers are let through.
Submissions are readers' personal data. Reading and exporting them takes documents.publish and edit access to the document, and deleting one also takes documents.publish.manage. leads.find and leads.erase serve data-subject requests across the workspace and also take settings.manage.
A document's lead form: whether readers are asked for their details, when, and for what
GET /documents/{documentId}/lead-form leads.formGet
Returns the document's lead form as stored. A document that never had one returns the default: when off, asking for a name and an email (both required), afterPages 3 and the heading Before you read on. available is false when the workspace's plan does not include lead capture: the form is then not shown to readers, whatever it says.
Needs view access to the document; one the caller cannot open answers 404 not_found.
- Scopes
documents.read
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Response
200 OK. A JSON object:
Response fields (29)
| Name | Type | Description |
|---|---|---|
form | object | The document's lead form. |
form.when | string | When readers of the document's publication are asked: off, never; open, before the first page; after, once they turn past afterPages pages. One of off, open, after. |
form.afterPages | integer | For when after: how many pages a reader may see before the form. Kept, and unused, for the other values of when. 1 to 1,000. |
form.fields | object | The details the form asks for, in the order it shows them. At least one must be on. |
form.fields.name | object | The reader's name. |
form.fields.name.on | boolean | Whether the form asks for it. Only the answers to fields that are on are stored. |
form.fields.name.required | boolean | Whether the reader must answer it to go on. No effect while on is false. |
form.fields.email | object | The reader's email address. An answer must be an email address, and is stored in lower case. |
form.fields.email.on | boolean | Whether the form asks for it. Only the answers to fields that are on are stored. |
form.fields.email.required | boolean | Whether the reader must answer it to go on. No effect while on is false. |
form.fields.company | object | The reader's company. |
form.fields.company.on | boolean | Whether the form asks for it. Only the answers to fields that are on are stored. |
form.fields.company.required | boolean | Whether the reader must answer it to go on. No effect while on is false. |
form.fields.phone | object | The reader's phone number. An answer must be at least six digits, which may be split by spaces, dashes, dots, slashes or brackets, with an optional leading +. |
form.fields.phone.on | boolean | Whether the form asks for it. Only the answers to fields that are on are stored. |
form.fields.phone.required | boolean | Whether the reader must answer it to go on. No effect while on is false. |
form.fields.custom | object | One question of the workspace's own, answered in free text. |
form.fields.custom.on | boolean | Whether the form asks for it. Only the answers to fields that are on are stored. |
form.fields.custom.required | boolean | Whether the reader must answer it to go on. No effect while on is false. |
form.fields.custom.label | string | The question as the form shows it. Needed while on is true. At most 60 characters. |
form.consent | object | A box the reader ticks to agree to something, in the workspace's own words. |
form.consent.on | boolean | Whether the form shows the box. |
form.consent.required | boolean | Whether the reader must tick it to go on. |
form.consent.text | string | What the reader agrees to, shown beside the box. It may run over lines. Needed while on is true. At most 500 characters. |
form.consent.privacyUrl | string | The http or https address of a privacy policy, linked beside the box, or null for none. At most 500 characters. Can be null. |
form.skip | boolean | Whether the reader may go on without filling it in. A reader who skips is asked again in their next browser session. |
form.heading | string | The form's heading. At most 120 characters. |
form.intro | string | Text under the heading, empty for none. It may run over lines. At most 500 characters. |
available | boolean | Whether the workspace's plan includes lead capture. While it is false, readers are not shown the form, whatever when says. |
Example request
curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/lead-form \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"form": {
"when": "off",
"afterPages": 1,
"fields": {
"name": {
"on": true,
"required": true
},
"email": {
"on": true,
"required": true
},
"company": {
"on": true,
"required": true
},
"phone": {
"on": true,
"required": true
},
"custom": {
"on": true,
"required": true,
"label": "Spring campaign"
}
},
"consent": {
"on": true,
"required": true,
"text": "string",
"privacyUrl": "https://example.com/privacy"
},
"skip": true,
"heading": "string",
"intro": "string"
},
"available": true
} Ask a document's readers for their details on opening it, or after some pages
PUT /documents/{documentId}/lead-form leads.formSet
Replaces the whole form. when is off, open (before the first page) or after (once the reader turns past afterPages). Only the fields with on true are asked, and only their answers are stored. The consent box shows text, with a link to privacyUrl when one is given. skip lets a reader go on without answering. The viewer serves no page past the form to a reader who has not answered or skipped it.
What a reader sends is stored as a submission (leads.list) and raises the form.submitted webhook event. Needs edit access to the document: 403 forbidden when the caller may only view it. Returns the form as stored.
- Scopes
documents.publish- Plan
- Lead capture, on Pro, Enterprise
- Retries
- Safe with an
Idempotency-Key
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
when required | string | When readers of the document's publication are asked: off, never; open, before the first page; after, once they turn past afterPages pages. One of off, open, after. |
afterPages required | integer | For when after: how many pages a reader may see before the form. Kept, and unused, for the other values of when. 1 to 1,000. |
fields required | object | The details the form asks for, in the order it shows them. At least one must be on. |
fields.name required | object | The reader's name. |
fields.name.on required | boolean | Whether the form asks for it. Only the answers to fields that are on are stored. |
fields.name.required required | boolean | Whether the reader must answer it to go on. No effect while on is false. |
fields.email required | object | The reader's email address. An answer must be an email address, and is stored in lower case. |
fields.email.on required | boolean | Whether the form asks for it. Only the answers to fields that are on are stored. |
fields.email.required required | boolean | Whether the reader must answer it to go on. No effect while on is false. |
fields.company required | object | The reader's company. |
fields.company.on required | boolean | Whether the form asks for it. Only the answers to fields that are on are stored. |
fields.company.required required | boolean | Whether the reader must answer it to go on. No effect while on is false. |
fields.phone required | object | The reader's phone number. An answer must be at least six digits, which may be split by spaces, dashes, dots, slashes or brackets, with an optional leading +. |
fields.phone.on required | boolean | Whether the form asks for it. Only the answers to fields that are on are stored. |
fields.phone.required required | boolean | Whether the reader must answer it to go on. No effect while on is false. |
fields.custom required | object | One question of the workspace's own, answered in free text. |
fields.custom.on required | boolean | Whether the form asks for it. Only the answers to fields that are on are stored. |
fields.custom.required required | boolean | Whether the reader must answer it to go on. No effect while on is false. |
fields.custom.label required | string | The question as the form shows it. Needed while on is true. At most 60 characters. |
consent required | object | A box the reader ticks to agree to something, in the workspace's own words. |
consent.on required | boolean | Whether the form shows the box. |
consent.required required | boolean | Whether the reader must tick it to go on. |
consent.text required | string | What the reader agrees to, shown beside the box. It may run over lines. Needed while on is true. At most 500 characters. |
consent.privacyUrl required | string | The http or https address of a privacy policy, linked beside the box, or null for none. At most 500 characters. Can be null. |
skip required | boolean | Whether the reader may go on without filling it in. A reader who skips is asked again in their next browser session. |
heading required | string | The form's heading. At most 120 characters. |
intro required | string | Text under the heading, empty for none. It may run over lines. At most 500 characters. |
Response
200 OK. A JSON object:
Response fields (29)
| Name | Type | Description |
|---|---|---|
form | object | The form as stored. |
form.when | string | When readers of the document's publication are asked: off, never; open, before the first page; after, once they turn past afterPages pages. One of off, open, after. |
form.afterPages | integer | For when after: how many pages a reader may see before the form. Kept, and unused, for the other values of when. 1 to 1,000. |
form.fields | object | The details the form asks for, in the order it shows them. At least one must be on. |
form.fields.name | object | The reader's name. |
form.fields.name.on | boolean | Whether the form asks for it. Only the answers to fields that are on are stored. |
form.fields.name.required | boolean | Whether the reader must answer it to go on. No effect while on is false. |
form.fields.email | object | The reader's email address. An answer must be an email address, and is stored in lower case. |
form.fields.email.on | boolean | Whether the form asks for it. Only the answers to fields that are on are stored. |
form.fields.email.required | boolean | Whether the reader must answer it to go on. No effect while on is false. |
form.fields.company | object | The reader's company. |
form.fields.company.on | boolean | Whether the form asks for it. Only the answers to fields that are on are stored. |
form.fields.company.required | boolean | Whether the reader must answer it to go on. No effect while on is false. |
form.fields.phone | object | The reader's phone number. An answer must be at least six digits, which may be split by spaces, dashes, dots, slashes or brackets, with an optional leading +. |
form.fields.phone.on | boolean | Whether the form asks for it. Only the answers to fields that are on are stored. |
form.fields.phone.required | boolean | Whether the reader must answer it to go on. No effect while on is false. |
form.fields.custom | object | One question of the workspace's own, answered in free text. |
form.fields.custom.on | boolean | Whether the form asks for it. Only the answers to fields that are on are stored. |
form.fields.custom.required | boolean | Whether the reader must answer it to go on. No effect while on is false. |
form.fields.custom.label | string | The question as the form shows it. Needed while on is true. At most 60 characters. |
form.consent | object | A box the reader ticks to agree to something, in the workspace's own words. |
form.consent.on | boolean | Whether the form shows the box. |
form.consent.required | boolean | Whether the reader must tick it to go on. |
form.consent.text | string | What the reader agrees to, shown beside the box. It may run over lines. Needed while on is true. At most 500 characters. |
form.consent.privacyUrl | string | The http or https address of a privacy policy, linked beside the box, or null for none. At most 500 characters. Can be null. |
form.skip | boolean | Whether the reader may go on without filling it in. A reader who skips is asked again in their next browser session. |
form.heading | string | The form's heading. At most 120 characters. |
form.intro | string | Text under the heading, empty for none. It may run over lines. At most 500 characters. |
available | boolean | Whether the workspace's plan includes lead capture. While it is false, readers are not shown the form, whatever when says. |
Example request
curl -X PUT https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/lead-form \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"when": "off",
"afterPages": 1,
"fields": {
"name": {
"on": true,
"required": true
},
"email": {
"on": true,
"required": true
},
"company": {
"on": true,
"required": true
},
"phone": {
"on": true,
"required": true
},
"custom": {
"on": true,
"required": true,
"label": "Spring campaign"
}
},
"consent": {
"on": true,
"required": true,
"text": "string",
"privacyUrl": "https://example.com/privacy"
},
"skip": true,
"heading": "string",
"intro": "string"
}' Example response
{
"form": {
"when": "off",
"afterPages": 1,
"fields": {
"name": {
"on": true,
"required": true
},
"email": {
"on": true,
"required": true
},
"company": {
"on": true,
"required": true
},
"phone": {
"on": true,
"required": true
},
"custom": {
"on": true,
"required": true,
"label": "Spring campaign"
}
},
"consent": {
"on": true,
"required": true,
"text": "string",
"privacyUrl": "https://example.com/privacy"
},
"skip": true,
"heading": "string",
"intro": "string"
},
"available": true
} What readers sent through a document's lead form, newest first
GET /documents/{documentId}/leads leads.list
Returns one page of the document's submissions. Pass nextCursor back as cursor for the next page; it is null when a page holds fewer than limit. Needs edit access to the document: 403 forbidden when the caller may only view it.
- Scopes
documents.publish
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Query parameters
| Name | Type | Description |
|---|---|---|
cursor | string | The previous page's nextCursor. Left out, or one that cannot be read, the first page. At most 200 characters. |
limit | integer | Most submissions to return. Default 50. 1 to 200. |
Response
200 OK. A JSON object:
Response fields (20)
| Name | Type | Description |
|---|---|---|
leads | array of objects | This page's submissions, newest first. |
leads[].id | string | The submission's id. |
leads[].documentId | string | The document whose lead form it was sent through. |
leads[].name | string | The name the reader gave, or null when the form did not ask for it or the reader left it empty. Can be null. |
leads[].email | string | The email address the reader gave, in lower case, or null when the form did not ask for it or the reader left it empty. Can be null. |
leads[].company | string | The company the reader gave, or null when the form did not ask for it or the reader left it empty. Can be null. |
leads[].phone | string | The phone number the reader gave, or null when the form did not ask for it or the reader left it empty. Can be null. |
leads[].custom | object | The answer to the form's own question, or null when the form did not ask for it or the reader left it empty. Can be null. |
leads[].custom.label | string | The form's question as it was worded when the reader answered. |
leads[].custom.answer | string | The reader's answer. |
leads[].consent | object | The consent box as the reader saw it and whether they ticked it, or null when the form had no box. Can be null. |
leads[].consent.given | boolean | Whether the reader ticked the box. |
leads[].consent.text | string | The consent wording the reader saw. |
leads[].consent.privacyUrl | string | The privacy policy address the reader saw, or null when there was none. Can be null. |
leads[].gate | string | How the form was shown: open, before the first page; after, after some pages. One of open, after. |
leads[].embed | boolean | Whether the reader was reading in an embed on another site. |
leads[].submittedAt | number | When the reader sent it, in epoch milliseconds. |
nextCursor | string | Pass it back as cursor for the next page. Null when this page holds fewer than limit. Can be null. |
total | integer | How many submissions the document keeps. |
max | integer | The most submissions a document keeps (50,000). At it, new answers are not stored, and readers are let through as after a skip, until some are deleted. |
Example request
curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/leads \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" Example response
{
"leads": [
{
"id": "string",
"documentId": "…",
"name": "Spring catalogue",
"email": "alex@example.com",
"company": "string",
"phone": "string",
"custom": {
"label": "Spring campaign",
"answer": "string"
},
"consent": {
"given": true,
"text": "string",
"privacyUrl": "https://example.com/privacy"
},
"gate": "open",
"embed": true,
"submittedAt": 1767225600000
}
],
"nextCursor": "string",
"total": 1,
"max": 1
} A document's leads as CSV
GET /documents/{documentId}/leads/export leads.export
Newest first, every submission the document keeps (at most 50,000). A value a spreadsheet would run as a formula starts with ' so it opens as text. The columns are submitted_at (ISO 8601, UTC), name, email, company, phone, question, answer, consent (yes, no, or empty with no box), consent_text, privacy_url, gate, embed (yes or no) and id, one row per submission.
The file downloads as an attachment. Each export is recorded in the audit log, with the number of rows. Needs edit access to the document: 403 forbidden when the caller may only view it.
- Scopes
documents.publish
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
Response
200 OK. The file itself, with its own Content-Type. A refusal is a JSON error, as everywhere else.
Example request
curl https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/leads/export \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-OJ Delete one reader's submission
DELETE /documents/{documentId}/leads/{leadId} leads.delete
The form.submitted webhook event that carried it is deleted too, if it is still kept. A submission the document does not have answers 404 not_found. Needs edit access to the document: 403 forbidden when the caller may only view it.
- Scopes
documents.publish,documents.publish.manage- Retries
- Safe with an
Idempotency-Key
Path parameters
| Name | Type | Description |
|---|---|---|
documentId required | string | The document's id. An id starting doc_. |
leadId required | string | The submission's id. An id starting led_. |
Response
200 OK. An empty JSON object, {}.
Example request
curl -X DELETE https://api.flipbird.io/api/v1/documents/doc_7m2kq9vx4c8d1r5t6wnb/leads/led_7m2kq9vx4c8d1r5t6wnb \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" Every submission one reader made, by email, across the workspace
POST /leads/find leads.find
For a data-subject request. Looks at the newest 1,000 submissions with the address, newest first. Submissions to documents the caller cannot open are counted in hidden, not listed; leads.erase reaches them. Each search is recorded in the audit log, without the address.
- Scopes
documents.publish,settings.manage- Retries
- Safe with an
Idempotency-Key
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
email required | string | The reader's email address. Case does not matter. At most 254 characters. |
Response
200 OK. A JSON object:
Response fields (19)
| Name | Type | Description |
|---|---|---|
leads | array of objects | The reader's submissions to documents the caller may open, newest first. |
leads[].id | string | The submission's id. |
leads[].documentId | string | The document whose lead form it was sent through. |
leads[].name | string | The name the reader gave, or null when the form did not ask for it or the reader left it empty. Can be null. |
leads[].email | string | The email address the reader gave, in lower case, or null when the form did not ask for it or the reader left it empty. Can be null. |
leads[].company | string | The company the reader gave, or null when the form did not ask for it or the reader left it empty. Can be null. |
leads[].phone | string | The phone number the reader gave, or null when the form did not ask for it or the reader left it empty. Can be null. |
leads[].custom | object | The answer to the form's own question, or null when the form did not ask for it or the reader left it empty. Can be null. |
leads[].custom.label | string | The form's question as it was worded when the reader answered. |
leads[].custom.answer | string | The reader's answer. |
leads[].consent | object | The consent box as the reader saw it and whether they ticked it, or null when the form had no box. Can be null. |
leads[].consent.given | boolean | Whether the reader ticked the box. |
leads[].consent.text | string | The consent wording the reader saw. |
leads[].consent.privacyUrl | string | The privacy policy address the reader saw, or null when there was none. Can be null. |
leads[].gate | string | How the form was shown: open, before the first page; after, after some pages. One of open, after. |
leads[].embed | boolean | Whether the reader was reading in an embed on another site. |
leads[].submittedAt | number | When the reader sent it, in epoch milliseconds. |
leads[].documentTitle | string | The title of the document the submission was sent through. |
hidden | integer | How many of the reader's submissions are to documents the caller cannot open: counted, not listed. |
Example request
curl -X POST https://api.flipbird.io/api/v1/leads/find \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"email": "alex@example.com"
}' Example response
{
"leads": [
{
"id": "string",
"documentId": "…",
"name": "Spring catalogue",
"email": "alex@example.com",
"company": "string",
"phone": "string",
"custom": {
"label": "Spring campaign",
"answer": "string"
},
"consent": {
"given": true,
"text": "string",
"privacyUrl": "https://example.com/privacy"
},
"gate": "open",
"embed": true,
"submittedAt": 1767225600000,
"documentTitle": "string"
}
],
"hidden": 1
} Erase every submission one reader made, by email, across the workspace
POST /leads/erase leads.erase
For a data-subject request. Deletes every submission with the address, including those to documents the caller cannot open, and the form.submitted webhook events still kept for them. The audit log records how many went, not the address. An erasure that finds nothing answers erased 0.
- Scopes
documents.publish,settings.manage- Retries
- Safe with an
Idempotency-Key
Request body
A JSON object, at most 64 KiB.
| Name | Type | Description |
|---|---|---|
email required | string | The reader's email address. Case does not matter. At most 254 characters. |
Response
200 OK. A JSON object:
Response fields (1)
| Name | Type | Description |
|---|---|---|
erased | integer | How many submissions were deleted. |
Example request
curl -X POST https://api.flipbird.io/api/v1/leads/erase \
-H "Authorization: Bearer $FLIPBIRD_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"email": "alex@example.com"
}' Example response
{
"erased": 1
}