Skip to main content

DocsREST API and MCP server

Uploads API

Endpoints, auth and live samples for Audience Builder, Connect Data and CRM sync.

Base URLhttps://us-farmvision-new-api.onrender.com

Connect Data: Uploads

Create Upload

Stores a parsed file (its columns and up to 10,000 rows, keyed by column id) as a new upload, ready for mapping. A file name already used on this account (case-insensitive) is a 409. Up to 60 uploads an hour per account, with a request body of up to 60 MB.

POSThttps://us-farmvision-new-api.onrender.com/api/v1/lead-generation/uploadsTry it

In this section

Authentication

Get API key

Bearer token

Send your GTM Scoop API key (llmcp_…) or a signed-in session token as a Bearer token.

Authorization: Bearer YOUR_API_KEY

Request body

application/json
FieldTypeDescription
fileNamebodyrequiredstringName shown in history. 1–255 characters after trimming; must be unique on this account (case-insensitive).
sourceColumnsbodyrequiredarray<object>1–500 columns in file order, each { id, name, sampleValue? }. Values inside an entry must be plain strings.
sourceColumns[].idbodyrequiredstringYour stable id for the column, up to 64 characters (e.g. col_company). previewRows and mappings refer to columns by this id. Built-in object names such as constructor or __proto__ are refused.
sourceColumns[].namebodyrequiredstringThe column header as it appears in the file, up to 256 characters.
sourceColumns[].sampleValuebodystringAn example value for the mapping screen. Filled in from the stored rows when omitted.
previewRowsbodyarray<object>The file's rows, up to 10,000. Each row is a flat object of column id → value: string, number, boolean or null; strings up to 2,000 characters; at most 500 fields per row.
fileSizebodynumberFile size in bytes, 0 or more. Defaults to 0.
recordCountbodyintegerRow count, 0 or more. When previewRows are sent, the number of rows actually stored is recorded instead.
businessContextbodyobject | stringWhat your company sells and to whom, read by AI analysis. The web app sends { companyName, website, businessContext, updatedAt }. At most 4,000 characters, measured as JSON.
sourceModebodystringMust be "upload" if sent; any other value is a 400.

Mounted at

/api/v1/lead-generation

The start of the Connect Data flow: send a parsed file's columns and rows as an upload, then save how its columns map onto GTM Scoop's match fields. A run (see Runs) is created from a mapped upload.

Try it in the playground

Signed out: 10 free tries a day with names hidden. Log in for live data.

Open playground

Related endpoints

All 8 endpoints in this section

Bearer token: an llmcp_ API key or a signed-in session token.

MethodPathWhat it does
POST/api/v1/lead-generation/uploads

Create Upload

Stores a parsed file (its columns and up to 10,000 rows, keyed by column id) as a new upload, ready for mapping. A file name already used on this account (case-insensitive) is a 409. Up to 60 uploads an hour per account, with a request body of up to 60 MB.

10 parameters
  • fileName (string, required) Name shown in history. 1–255 characters after trimming; must be unique on this account (case-insensitive).
  • sourceColumns (array<object>, required) 1–500 columns in file order, each { id, name, sampleValue? }. Values inside an entry must be plain strings.
  • sourceColumns[].id (string, required) Your stable id for the column, up to 64 characters (e.g. col_company). previewRows and mappings refer to columns by this id. Built-in object names such as constructor or __proto__ are refused.
  • sourceColumns[].name (string, required) The column header as it appears in the file, up to 256 characters.
  • sourceColumns[].sampleValue (string) An example value for the mapping screen. Filled in from the stored rows when omitted.
  • previewRows (array<object>) The file's rows, up to 10,000. Each row is a flat object of column id → value: string, number, boolean or null; strings up to 2,000 characters; at most 500 fields per row.
  • fileSize (number) File size in bytes, 0 or more. Defaults to 0.
  • recordCount (integer) Row count, 0 or more. When previewRows are sent, the number of rows actually stored is recorded instead.
  • businessContext (object | string) What your company sells and to whom, read by AI analysis. The web app sends { companyName, website, businessContext, updatedAt }. At most 4,000 characters, measured as JSON.
  • sourceMode (string) Must be "upload" if sent; any other value is a 400.
GET/api/v1/lead-generation/uploads

List Uploads

Your 100 most recent uploads, newest first, including ones never mapped or run. Each carries its mapping and run summary (status is uploaded or mapped; latestRunStatus is the newest run's status, or null).

Try List Uploads in the Playground
GET/api/v1/lead-generation/uploads/:uploadId

Get Upload

Reads one upload back with its columns, saved mapping and rows: what the mapping screen loads. By default every stored row is returned; includeRows=false returns an empty previewRows and fills any missing sample values from the first 25 rows instead. 404 if the upload is not yours or does not exist.

2 parameters
  • uploadId (string, required) The upload's id (a UUID), from Create Upload or List Uploads.
  • includeRows (string) "false" skips the rows (previewRows comes back empty). Any other value, or none, returns every stored row.
Try Get Upload in the Playground
GET/api/v1/lead-generation/uploads/:uploadId/runs

List Upload Runs

Up to 50 runs created from one upload, newest first. An unknown upload id returns an empty list rather than a 404, and hasEnrich is always false here (Get Run reports it).

1 parameter
  • uploadId (string, required) The upload's id (a UUID).
Try List Upload Runs in the Playground
POST/api/v1/lead-generation/uploads/:uploadId/mapping

Save Mapping

Saves (or replaces) how the upload's columns map onto match fields, and marks the upload mapped. The mapping must give matching something to work with, or it is refused with 422 and code MAPPING_COMBO_INCOMPLETE (plus a missing object naming what is absent): Address1 + Zipcode or an APN by default; a phone or email plus Address1 + Zipcode when dataset is business or farm. 404 if the upload is not yours or does not exist.

6 parameters
  • uploadId (string, required) The upload's id (a UUID).
  • mappings (array<object>, required) One entry per source column: { sourceColumnId, targetFieldId }. Suggestion fields (aiSuggested, confidence, reason) are accepted and dropped.
  • mappings[].sourceColumnId (string, required) A column id from the upload's sourceColumns.
  • mappings[].targetFieldId (string | null, required) The match field, or null to leave the column unmapped. One of: Company, First_Name, Last_Name, Address1, Address2, EXcityname (city), StateCode, Zipcode, EXcountyname (county), Telenum (phone), email, URL (website), Faxnum1 (fax), Revenue, NoOfEmployees, SIC_CODE, Industry, APN (parcel number). Matching itself reads Telenum, email, Address1, Zipcode and APN.
  • nameSplits (array) Stored and returned as given; not used by matching. Send [].
  • dataset (string) "business", "farm" or "property": what you will enrich against, which tightens the check (property: APN, or Address1 + Zipcode; phone/email never required). Any other string counts as not chosen yet.
GET/api/v1/lead-generation/uploads/:uploadId/mapping

Get Mapping

The upload's saved mapping on its own. data is null when no mapping has been saved, or when the upload is not yours.

1 parameter
  • uploadId (string, required) The upload's id (a UUID).
Try Get Mapping in the Playground
PATCH/api/v1/lead-generation/uploads/:uploadId

Update Upload

Renames an upload and/or replaces its business context; send at least one of the two. The context is read when an analysis starts, so one added after the upload still reaches the next run. Returns 200 even for an id that is not yours (nothing changes), and a rename is not checked against your other file names.

3 parameters
  • uploadId (string, required) The upload's id (a UUID).
  • fileName (string) New name, 1–255 characters after trimming.
  • businessContext (object) Replaces the stored context, e.g. { companyName, website, businessContext, updatedAt }. Must be an object here (not a string), at most 4,000 characters as JSON.
DELETE/api/v1/lead-generation/uploads/:uploadId

Delete Upload

Permanently deletes the upload, its mapping and its stored rows. Runs created from it are not deleted (use Delete Run), but their enrichment results can no longer be read once the rows are gone. Returns 200 even for an unknown id.

1 parameter
  • uploadId (string, required) The upload's id (a UUID).

Cookies on GTM Scoop

Essential cookies keep you signed in and the site secure, and are always on. Optional cookies (Google Analytics) help us understand how the site is used. They are on by default, except in the EU/EEA, the UK and Switzerland, where they stay off until you choose Accept All Cookies; choose Essential Cookies Only to turn them off. We do not use advertising cookies and we do not sell or share your personal information. The site works the same whichever you choose. We keep a record of your choice with the date, your IP address and the page you were on. Cookie Policy · Privacy Policy