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

NameTypeDescription
documentId required string The document's id. An id starting doc_.

Response

200 OK. A JSON object:

Response fields (29)
NameTypeDescription
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

NameTypeDescription
documentId required string The document's id. An id starting doc_.

Request body

A JSON object, at most 64 KiB.

NameTypeDescription
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)
NameTypeDescription
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

NameTypeDescription
documentId required string The document's id. An id starting doc_.

Query parameters

NameTypeDescription
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)
NameTypeDescription
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

NameTypeDescription
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

NameTypeDescription
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.

NameTypeDescription
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)
NameTypeDescription
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.

NameTypeDescription
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)
NameTypeDescription
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
}