API reference

Leads

Lead forms of your Facebook Pages and LinkedIn ad accounts and X ad accounts, and the leads people submit.

GET/leads

List leads

Leads people submitted on your connected lead forms, newest first, without their answers (fields names the questions they answered) unless answers asks for them. New leads arrive by the platform's lead webhook within seconds and are read again on a schedule and after outages; each is announced once as the lead.received webhook event. Keyset-paged: pass nextAfter as after.

Permission: read

Parameters

NameTypeRequiredDescription
formIdquerystringOptionalThe form's ID on its platform.
pageIdquerystringOptionalThe Page's ID on its platform (a Facebook Page on Meta).
adIdquerystringOptionalThe ad's ID on its platform: only leads that came through this ad.
sincequerystringOptionalOnly leads created after this time (RFC 3339).
afterquerystringOptionalCursor: nextAfter from the previous page.
limitquerystringOptionalPage size (1-200, default 50).
platformquerystringOptionalA platform from GET /platforms: only its leads, and access describes its connection. Without it: every platform's leads (each has adPlatform), access for Meta.
answersquerystringOptionaltrue: each listed lead's answers too, in answers on the page. Answers are personal data: this needs the write permission (403 otherwise) and the read is recorded once in the audit log.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

accessobjectRequired
access.availablebooleanRequired
Whether leads are on for this connection. False: the lists are empty and there is nothing to read; not an error.
access.lastErrorstring or null
Why a Page or form couldn't be read.
access.lastWebhookAtstring (date-time) or null
The latest lead webhook from Meta.
access.missingPermissionsarray of stringsRequired
Grant these by reconnecting Meta.
access.pagesintegerRequired
Connected Pages whose forms are read.
access.readAtstring (date-time) or null
Every Page's forms were last read to the end.
access.statusstringRequired
Whether leads are read.One of ready, missing_permissions, reauthorize, disconnected, unavailable
access.syncJobIdstring (uuid) or null
The read in progress.
access.unreadarray of objects
Meta Pages whose leads Meta counts but Pluto can't read with this connection, most leads first. Absent when there are none.
access.unread[].leadsintegerRequired
Meta's count of the leads on the Page's forms (its last 90 days, what Meta still lets be read).
access.unread[].pageIdstringRequired
Meta's Page ID.
access.unread[].pageNamestring or nullRequired
The Page's name.
access.unread[].reasonstringRequired
not_connected: the Page left the connected Meta account's Pages; no_lead_access: the account reaches the Page, but Meta answers its reads of the leads with none (no lead access, for example through Leads Access Manager).One of not_connected, no_lead_access
access.unread[].sincestring (date-time) or nullRequired
When the Page left the connected account's Pages (not_connected).
access.webhookPagesintegerRequired
Pages that push new leads; the rest are read every few minutes.
answersmap of array of objects
Only with answers=true: each listed lead's answers by its ID (personal data). A lead whose platform's terms keep its answers in Pluto's own app is left out.
itemsarray of objectsRequired
This page.
items[].adobject or null
The ad it came through; null for organic leads and form previews.
items[].ad.adSetIdstring or null
Meta ad set ID.
items[].ad.campaignIdstring or null
Meta campaign ID.
items[].ad.campaignNamestring or null
The campaign's name from the platform's synced campaigns; null when Pluto doesn't hold it, and outside Pluto's own app on a platform whose terms keep its data there.
items[].ad.idstringRequired
Meta ad ID.
items[].ad.namestring or null
Ad name, when synced.
items[].adPlatformstring
The ad platform it came through: meta, or a platform from GET /platforms.
items[].createdTimestring (date-time)Required
Submitted.
items[].fieldsarray of stringsRequired
The questions it answered (not the answers).
items[].formobject or null
The form.
items[].form.idstringRequired
Meta form ID.
items[].form.namestring or null
Form name, when read.
items[].idstring (uuid)Required
Lead (Pluto ID).
items[].isOrganicboolean or null
Submitted without an ad.
items[].isTestboolean
True for a lead the platform marked as a test (sent from the platform's own test button): nobody's enquiry. Absent where the platform doesn't say.
items[].metaIdstringRequired
Meta's lead ID. Deprecated: providerId names it on every platform.
items[].pageIdstringRequired
Facebook Page, or the form's owner (the ad account) on other platforms.
items[].platformstring or null
fb or ig, when Meta says.
items[].providerIdstring
The platform's lead ID.
items[].receivedAtstring (date-time)Required
Stored in Pluto.
items[].receivedViastringRequired
How it first arrived.One of webhook, backfill
items[].withheldboolean
Only on a platform whose terms keep its data in Pluto (policy.dataLeavesUi off on GET /platforms): true when what the platform reported about the lead (its answers, the fields answered, the form's and ad's names) was held back here, which is everywhere but Pluto's own app. IDs and times still travel.
nextAfterstring or null
Cursor for the next page; null at the end.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/leads" \
  -H "Authorization: Bearer $PLUTO_KEY"
GET/leads/forms

List lead forms

The lead forms of your connected ad platforms as each last reported them (on Meta your Facebook Pages' forms; where forms belong to an ad account, that account's), with their questions (never answers), the platform's lead count when it gives one, the leads Pluto holds and how far they've been read. access says whether the connection reads leads (Meta's without platform). With platform, only that platform's forms, and access describes its connection.

Permission: read

Parameters

NameTypeRequiredDescription
platformquerystringOptionalA platform from GET /platforms: only its forms. Without it: every platform's forms (each has adPlatform), access for Meta.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

accessobjectRequired
access.availablebooleanRequired
Whether leads are on for this connection. False: the lists are empty and there is nothing to read; not an error.
access.lastErrorstring or null
Why a Page or form couldn't be read.
access.lastWebhookAtstring (date-time) or null
The latest lead webhook from Meta.
access.missingPermissionsarray of stringsRequired
Grant these by reconnecting Meta.
access.pagesintegerRequired
Connected Pages whose forms are read.
access.readAtstring (date-time) or null
Every Page's forms were last read to the end.
access.statusstringRequired
Whether leads are read.One of ready, missing_permissions, reauthorize, disconnected, unavailable
access.syncJobIdstring (uuid) or null
The read in progress.
access.unreadarray of objects
Meta Pages whose leads Meta counts but Pluto can't read with this connection, most leads first. Absent when there are none.
access.unread[].leadsintegerRequired
Meta's count of the leads on the Page's forms (its last 90 days, what Meta still lets be read).
access.unread[].pageIdstringRequired
Meta's Page ID.
access.unread[].pageNamestring or nullRequired
The Page's name.
access.unread[].reasonstringRequired
not_connected: the Page left the connected Meta account's Pages; no_lead_access: the account reaches the Page, but Meta answers its reads of the leads with none (no lead access, for example through Leads Access Manager).One of not_connected, no_lead_access
access.unread[].sincestring (date-time) or nullRequired
When the Page left the connected account's Pages (not_connected).
access.webhookPagesintegerRequired
Pages that push new leads; the rest are read every few minutes.
itemsarray of objectsRequired
Forms.
items[].adAccountIdstring or null
The ad account that owns the form, on platforms where forms belong to one (null on Meta).
items[].adPlatformstring
The ad platform the form is on: meta, or a platform from GET /platforms.
items[].createdTimestring (date-time) or null
Created on the platform.
items[].idstringRequired
The form's ID on its platform.
items[].lastErrorstring or null
Why the last read of its leads failed.
items[].leadsCountinteger or null
The platform's count of the form's leads, when it gives one.
items[].leadsThroughstring (date-time) or null
Leads created up to this time have been read.
items[].localestring or null
Form locale.
items[].namestringRequired
Form name.
items[].pageIdstringRequired
The Facebook Page on Meta; where forms belong to an ad account, that account.
items[].pageNamestring or null
Page name.
items[].questionsarray of objectsRequired
Questions, in order.
items[].questions[].keystringRequired
The question's key (email, full_name, or a custom key).
items[].questions[].labelstring or null
The question as asked.
items[].questions[].typestring or null
Meta's question type (EMAIL, FULL_NAME, CUSTOM, ...).
items[].statusstring or null
The platform's status (on Meta: ACTIVE, ARCHIVED, DELETED or DRAFT).
items[].storedLeadsintegerRequired
Leads Pluto holds for the form.
items[].syncedAtstring (date-time)Required
Last read from the platform.
items[].withheldboolean
Only on a platform whose terms keep its data in Pluto (policy.dataLeavesUi off on GET /platforms): true when the form's name, status and questions were held back here, which is everywhere but Pluto's own app (name is then empty). IDs and Pluto's own counts still travel.
websiteUrlstring or null
The workspace's website (launch defaults): a new form's privacy and thank-you links default to it.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/leads/forms" \
  -H "Authorization: Bearer $PLUTO_KEY"
POST/leads/forms

Create a lead form

Creates a lead form on a connected ad platform (platform, Meta when left out; where forms belong to an ad account, a form of that account, as platform in the body says). On Meta it is an Instant Form on a connected Facebook Page that asks for the full name and email (both required), optionally a phone number and short-answer custom questions, and links your privacy policy, which Meta shows on every form (it defaults to the workspace's website from the launch defaults; without one the link is required). Optional: a headline over the questions, an intro page, a thank-you page with a button to a website (the website defaults the same way), Meta's form locale (EN_US by default) and the form type, volume (More volume, the default) or quality (Higher intent). Queues one job and returns it: the job creates the form (on Meta with the Page's token), reads it back and adds it to GET /leads/forms, where the backfill and the New lead trigger pick it up; the job's item carries the form's ID on the platform as providerId. On Meta a retry after an unanswered request checks the Page's forms first, so a form is never created twice, and the form needs the pages_manage_ads permission in Meta and a Meta account that can advertise for the Page.

Permission: publishCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

adAccountIdstring
The ad account that owns the form, on platforms where forms belong to one.
businessNamestring
The business the form is from, on platforms whose forms show one (up to 25 characters). Defaults to the ad account's name.
callToActionobject
callToAction.descriptionstring
The line beside the button (up to 30 characters). Defaults to the headline.
callToAction.typestring
The form's button, as the platform names it (LEARN_MORE by default; also GET_QUOTE, APPLY_NOW, SIGN_UP, CONTACT_US, SUBSCRIBE, DOWNLOAD, BOOK_NOW, GET_OFFER, REGISTER, GET_INFO, REQUEST_DEMO, JOIN_NOW, GET_STARTED).
descriptionstring
A line under the headline, on platforms whose forms have one (up to 160 characters; where the platform requires it, up to 200).
fieldsarray of objects
On platforms whose forms ask for the platform's own fields in place of questions: the fields in order, each key once.
fields[].keystringRequired
The platform's field key, such as EMAIL, FULL_NAME or PHONE_NUMBER.
fields[].optionalboolean
The person may skip it. At least one field is required.
finalPageobject
finalPage.buttonobject
finalPage.button.titlestringRequired
The button's text (up to 100 characters).
finalPage.button.urlstringRequired
Where the button goes (a full https address).
finalPage.descriptionstring
A line under it (up to 1,000 characters).
finalPage.headlinestringRequired
The headline after submitting (up to 190 characters).
formTypestring
volume (More volume, the default) or quality (Higher intent: people review their answers before submitting).One of volume, quality
headlinestring
A headline over the questions.
introobject
intro.descriptionstringRequired
What the intro says.
intro.titlestringRequired
The intro's headline.
introductionobject
introduction.descriptionstring
A line under it (up to 1,000 characters).
introduction.headlinestringRequired
The headline before the fields (up to 190 characters).
localestring
Meta's form locale. Defaults to EN_US.One of AR_AR, CS_CZ, DA_DK, DE_DE, EL_GR, EN_GB, EN_US, ES_ES, ES_LA, FI_FI, FR_FR, HE_IL, HI_IN, HU_HU, ID_ID, IT_IT, JA_JP, KO_KR, NB_NO, NL_NL, PL_PL, PT_BR, PT_PT, RO_RO and 8 more
namestringRequired
The form's name (up to 200 characters).
pageIdstring
The connected Facebook Page (Meta ID). Required on Meta.
platformstring
A platform from GET /platforms (Meta when left out). On platforms whose forms belong to an ad account, send adAccountId instead of pageId, up to 3 CUSTOM questions and up to 12 profile fields; intro, locale and formType are Meta's.
privacyPolicyobject
privacyPolicy.companyNamestring
The company the policy belongs to, on platforms whose forms name it (up to 255 characters).
privacyPolicy.linkTextstring
The link's text, up to 70 characters. Defaults to "Privacy policy".
privacyPolicy.urlstring
Your privacy policy (a full https address). Defaults to the workspace's website.
purposestring
On platforms whose forms say why the details are collected: that sentence, shown to the person (up to 1,000 characters). Required there.
questionsarray of objects
The questions in order (up to 15).
questions[].labelstring
The question a CUSTOM one asks.
questions[].typestringRequired
FULL_NAME, EMAIL, PHONE or CUSTOM (a short answer); on Meta, FULL_NAME and EMAIL are required. Platforms whose forms ask for profile fields also take FIRST_NAME, LAST_NAME, WORK_EMAIL, PHONE_NUMBER, WORK_PHONE_NUMBER, CITY, STATE, COUNTRY, ZIP_CODE, JOB_TITLE, JOB_FUNCTION, SENIORITY, COMPANY_NAME, COMPANY_SIZE, INDUSTRY, DEGREE, FIELD_OF_STUDY, SCHOOL, START_DATE, GRADUATION_DATE and GENDER.
thankYouPageobject
thankYouPage.bodystring
A line under it.
thankYouPage.buttonTextstring
The button's text. Defaults to "View website".
thankYouPage.titlestringRequired
The headline after submitting.
thankYouPage.websiteUrlstring
Where the button goes. Defaults to the workspace's website; without one there is no button.
websiteUrlstring
The page the form belongs to, on platforms whose forms have one. Defaults to the thank-you page's website, then the workspace's website.

Response202 Accepted

jobIdstring (uuid)Required
The job that creates the form on the platform.
namestringRequired
The form's name.
pageIdstringRequired
The Page (or ad account) the form belongs to.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404The Page (or ad account) isn't one of the connected ones.
  • 409The platform isn't connected, or the connection lacks the permissions (on Meta reason: meta_permissions, missingPermissions).
  • 422The form breaks one of the platform's rules (errors names each field).
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/leads/forms" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 7c479659-2764-4bc0-8351-647fd79ad073" \
  -H "Content-Type: application/json" \
  -d '{
    "adAccountId": "act_741877585619437",
    "businessName": "Vitamin C Serum, UGC 9x16",
    "callToAction": {
      "description": "Two drops every morning for brighter, even skin.",
      "type": "LEARN_MORE"
    },
    "description": "Two drops every morning for brighter, even skin.",
    "fields": [
      {
        "key": "sk_VRkhilsHfXRm99YUSGqRrLwKeuymhz6O",
        "optional": true
      }
    ],
    "finalPage": {
      "button": {
        "title": "Vitamin C Serum, UGC 9x16",
        "url": "https://brevanne.com/products/vitamin-c-serum"
      },
      "description": "Two drops every morning for brighter, even skin.",
      "headline": "Brighter skin in 14 days"
    },
    "formType": "volume",
    "headline": "Brighter skin in 14 days",
    "intro": {
      "description": "Two drops every morning for brighter, even skin.",
      "title": "Vitamin C Serum, UGC 9x16"
    },
    "introduction": {
      "description": "Two drops every morning for brighter, even skin.",
      "headline": "Brighter skin in 14 days"
    },
    "locale": "AR_AR",
    "name": "Vitamin C Serum, UGC 9x16",
    "pageId": "229657833239852",
    "platform": "adAccountId",
    "privacyPolicy": {
      "companyName": "Vitamin C Serum, UGC 9x16",
      "linkText": "Brevanne",
      "url": "https://brevanne.com/products/vitamin-c-serum"
    },
    "purpose": "Brevanne",
    "questions": [
      {
        "label": "Vitamin C Serum, UGC 9x16",
        "type": "FULL_NAME"
      }
    ],
    "thankYouPage": {
      "body": "Can we try the 4x5 cut for Instagram feed before we publish?",
      "buttonText": "Brevanne",
      "title": "Vitamin C Serum, UGC 9x16",
      "websiteUrl": "https://brevanne.com/products/vitamin-c-serum"
    },
    "websiteUrl": "https://brevanne.com/products/vitamin-c-serum"
  }'
PATCH/leads/forms/{id}

Change a lead form

Changes a lead form on a platform whose forms can be changed from here (a form on any other platform answers 409 naming where it's changed). Only what the body names changes; fields, privacyPolicy, introduction and finalPage are each replaced whole, and none of them can be removed once set. The change is checked against the platform's rules first, then queued as one job; the form in GET /leads/forms follows once the platform confirmed it.

Permission: publishCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe form's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

fieldsarray of objects
The fields asked for, in order (each key once).
fields[].keystringRequired
The platform's field key, such as EMAIL, FULL_NAME or PHONE_NUMBER.
fields[].optionalboolean
The person may skip it. At least one field is required.
finalPageobject
finalPage.buttonobject
finalPage.button.titlestringRequired
The button's text (up to 100 characters).
finalPage.button.urlstringRequired
Where the button goes (a full https address).
finalPage.descriptionstring
A line under it (up to 1,000 characters).
finalPage.headlinestringRequired
The headline after submitting (up to 190 characters).
introductionobject
introduction.descriptionstring
A line under it (up to 1,000 characters).
introduction.headlinestringRequired
The headline before the fields (up to 190 characters).
namestring
The form's name (up to 255 characters).
privacyPolicyobject
privacyPolicy.companyNamestringRequired
The company the policy belongs to (up to 255 characters).
privacyPolicy.urlstringRequired
Your privacy policy (a full https address).
purposestring
Why the details are collected, shown to the person (up to 1,000 characters).

Response202 Accepted

jobIdstring (uuid)Required
The job that changes the form on the platform.
namestringRequired
The form's name.
pageIdstringRequired
The ad account the form belongs to.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404No such lead form, or its platform is off for your organization.
  • 409The form is archived, its platform changes forms elsewhere, the platform isn't connected, or the connected account's role can't change forms.
  • 422The change breaks one of the platform's rules (errors names each field), or names nothing.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X PATCH "$PLUTO_API/leads/forms/341c1eaa-e2d7-4414-a82f-75208110bab6" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 37348e00-7034-4407-9013-0ff342bd265b" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {
        "key": "sk_fXzFiJMkaFQ5I8KwOsZG1yXto6fJMR6T",
        "optional": true
      }
    ],
    "finalPage": {
      "button": {
        "title": "Vitamin C Serum, UGC 9x16",
        "url": "https://brevanne.com/products/vitamin-c-serum"
      },
      "description": "Two drops every morning for brighter, even skin.",
      "headline": "Brighter skin in 14 days"
    },
    "introduction": {
      "description": "Two drops every morning for brighter, even skin.",
      "headline": "Brighter skin in 14 days"
    },
    "name": "Vitamin C Serum, UGC 9x16",
    "privacyPolicy": {
      "companyName": "Vitamin C Serum, UGC 9x16",
      "url": "https://brevanne.com/products/vitamin-c-serum"
    },
    "purpose": "Brevanne"
  }'
DELETE/leads/forms/{id}

Archive a lead form

Archives a lead form on a platform whose forms can be archived from here. The platform can't bring it back: the form stops taking leads and can't be changed. The leads Pluto holds stay. Queued as one job; the form's status in GET /leads/forms reads ARCHIVED once the platform confirmed it.

Permission: publishCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe form's ID.
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response202 Accepted

jobIdstring (uuid)Required
The job that changes the form on the platform.
namestringRequired
The form's name.
pageIdstringRequired
The ad account the form belongs to.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404No such lead form, or its platform is off for your organization.
  • 409The form is already archived, its platform archives forms elsewhere, the platform isn't connected, or the connected account's role can't change forms.
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X DELETE "$PLUTO_API/leads/forms/341c1eaa-e2d7-4414-a82f-75208110bab6" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 5f5e0fda-1513-458b-ba28-ffb27ed9abfa"
POST/leads/sync

Read leads now

Reads new leads from an ad platform now (platform; without it, Meta's) instead of at the next scheduled read (webhooks deliver new leads within seconds; every few minutes the forms are read again). A platform that reads every ad account's leads together takes no filter. On Meta, narrow it to one form or Page with the body: only that form's new leads (or that Page's forms and their new leads) are read, on their own, so the read takes seconds. Without a filter, every connected Page's lead forms and their new leads are read, which can take minutes in a large workspace. Returns the read job: a new one, or the same read already under way (queued, waiting on Meta's limits, or running), which then also covers this request; follow it with GET /jobs/{id}, then list the leads.

Permission: writeCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringOptionalThe command ID. A retry with the same key returns the stored result; the same key with different input is a 409. Without it a retry cannot be recognized.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Request body

formIdstring
Only this lead form's new leads (Meta form ID).
pageIdstring
Only this Facebook Page's forms and their new leads (Meta Page ID).
platformstring
A platform from GET /platforms: read that platform's leads (every ad account's, together; no formId or pageId). Without it: Meta's.

Response200 OK

availablebooleanRequired
False: the platform's leads aren't on for the connection, so nothing is read (not an error).
jobIdstring (uuid) or nullRequired
The read job; null when available is false.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404The form or Page isn't one of the workspace's connected Pages' (or, given together, the form isn't on that Page).
  • 409Meta isn't connected, or the connection lacks the lead permissions (reason: meta_permissions, missingPermissions).
  • 422Validation failed; errors lists every field problem at once.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl -X POST "$PLUTO_API/leads/sync" \
  -H "Authorization: Bearer $PLUTO_KEY" \
  -H "Idempotency-Key: 39a9a1b4-089b-4ca6-87c8-c42aa95cea7a" \
  -H "Content-Type: application/json" \
  -d '{
    "formId": "6139465182125218",
    "pageId": "229657833239852",
    "platform": "formId"
  }'
GET/leads/{id}

Get a lead

One lead with its answers and disclaimer responses. Answers are personal data: they are stored encrypted, returned only here, need the write permission (guests and read-only keys get 403), and every read is recorded in the audit log.

Permission: write

Parameters

NameTypeRequiredDescription
idpathstringRequiredThe lead's ID.
Pluto-Workspaceheaderstring (uuid)OptionalThe workspace to act in, for credentials that can reach several (sessions, agent tokens). API keys belong to one workspace; another value is a 403.

Response200 OK

adobject or null
The ad it came through; null for organic leads and form previews.
ad.adSetIdstring or null
Meta ad set ID.
ad.campaignIdstring or null
Meta campaign ID.
ad.campaignNamestring or null
The campaign's name from the platform's synced campaigns; null when Pluto doesn't hold it, and outside Pluto's own app on a platform whose terms keep its data there.
ad.idstringRequired
Meta ad ID.
ad.namestring or null
Ad name, when synced.
adPlatformstring
The ad platform it came through: meta, or a platform from GET /platforms.
answersarray of objectsRequired
The answers (personal data).
answers[].labelstring or null
The question as asked, when the form is known.
answers[].namestringRequired
The question's key.
answers[].valuesarray of stringsRequired
What the person entered.
createdTimestring (date-time)Required
Submitted.
disclaimersany
The consent or disclaimer answers as the platform sent them (on Meta its custom_disclaimer_responses: checkbox keys and whether they were ticked); null when none.
fieldsarray of stringsRequired
The questions it answered (not the answers).
formobject or null
The form.
form.idstringRequired
Meta form ID.
form.namestring or null
Form name, when read.
idstring (uuid)Required
Lead (Pluto ID).
isOrganicboolean or null
Submitted without an ad.
isTestboolean
True for a lead the platform marked as a test (sent from the platform's own test button): nobody's enquiry. Absent where the platform doesn't say.
metaIdstringRequired
Meta's lead ID. Deprecated: providerId names it on every platform.
pageIdstringRequired
Facebook Page, or the form's owner (the ad account) on other platforms.
platformstring or null
fb or ig, when Meta says.
providerIdstring
The platform's lead ID.
receivedAtstring (date-time)Required
Stored in Pluto.
receivedViastringRequired
How it first arrived.One of webhook, backfill
withheldboolean
Only on a platform whose terms keep its data in Pluto (policy.dataLeavesUi off on GET /platforms): true when what the platform reported about the lead (its answers, the fields answered, the form's and ad's names) was held back here, which is everywhere but Pluto's own app. IDs and times still travel.

Errors

  • 400The request is malformed.
  • 401No valid credential.
  • 403The credential lacks the permission, or belongs to another workspace.
  • 404Not found in this workspace.
  • 429Too many requests from this credential. Wait Retry-After seconds. People in the app have their own budget, so an agent swarm can't starve them.
curl "$PLUTO_API/leads/1a65e4c7-db3f-464c-b4c4-529750883057" \
  -H "Authorization: Bearer $PLUTO_KEY"