File upload

Push first-party (bring-your-own-data, "BYOD") files to Incremental with a four-step presigned-upload flow: find your data source or partner id, request a presigned URL, PUT the file, then poll for the validation result.

File formats and requirements

For supported file formats and details on the files you can upload, see How to bring your own data (BYOD) to Incremental in the help center.

Uploads come in two modes, selected by the identifier you pass in Step 2:

• Single account — set dataSourceSecretId. The file is ingested for the one partner account tied to that data source secret.
• Multiple accounts (multi-PCID) — set partnerId and include a partner_company_id column in the file. Incremental splits the file into one drop per account. See Uploading for multiple accounts.

The request must include exactly one of dataSourceSecretId or partnerId — supplying both or neither is rejected.

Step 1 — Find your data source or partner id

Run the query below. Each entry in dataSourceSecrets ties a company to a partner channel.

query FindCompanyDataSources {
  getCompany(id: "<COMPANY_ID>") {
    id
    name
    dataSourceSecrets {
      items {
        id
        partnerId
        partner {
          name
        }
        partnerCompanyId
        isActive
      }
    }
  }
}

Single account

Pick the entry matching the channel you're uploading for and use its id as dataSourceSecretId in Step 2.

Multiple accounts (multi-PCID)

A multi-account upload targets a partner channel rather than a single data source: use the channel's partnerId (also returned by the query above) as partnerId in Step 2.

Step 2 — Request an upload URL

Call the createFileUpload mutation with a FileUploadInitInput to receive a presigned URL.

mutation ($input: FileUploadInitInput!) {
  createFileUpload(input: $input) {
    id
    presignedUrl
    presignedUrlExpiresAt
    status
  }
}

The type is an UploadTypeName (e.g., BYOD_MARKETING_INSTREAM) — see Supported upload types for the accepted values.

additionalParameters carries per-upload settings that describe the file's contents. The one that applies to every upload is dateOrder, which tells validation how to read the date columns in your file. If you omit it, dates are read as MM_DD_YYYY — see Date formats.

Single account

Variables — single account

{
  "input": {
    "companyId": "<COMPANY_ID>",
    "dataSourceSecretId": "<DATA_SOURCE_SECRET_ID>",
    "type": "<UPLOAD_TYPE>",
    "additionalParameters": {
      "dateOrder": "<DATE_ORDER>"
    }
  }
}

Multiple accounts (multi-PCID)

Variables — multiple accounts (multi-PCID)

{
  "input": {
    "companyId": "<COMPANY_ID>",
    "partnerId": "<PARTNER_ID>",
    "type": "<UPLOAD_TYPE>",
    "additionalParameters": {
      "dateOrder": "<DATE_ORDER>"
    }
  }
}

Which companyId?

For multi-account uploads, companyId can be any company in your organization.

Save the returned id

Save the returned id — you'll need it in Step 4. The URL expires in 15 minutes.

Step 3 — Upload the file

Send the file with an HTTP PUT to the presignedUrl from Step 2:

PUT <PRESIGNED_URL>
Content-Type: text/csv

<raw file bytes>

• Content-Type must match your file format (e.g., text/csv).
• Do not include an Authorization header on this request.

Once the file is uploaded, validation starts automatically — no completion call is required.

Step 4 — Check the validation status

Poll Company.fileUploadLogs, filtering by the id returned in Step 2.

query ($companyId: ID!, $filter: [FileUploadLogsFilterInput]) {
  getCompany(id: $companyId) {
    fileUploadLogs(filter: $filter) {
      items {
        id
        status
        failureReason
      }
    }
  }
}

Variables

{
  "companyId": "<COMPANY_ID>",
  "filter": [{ "id": { "eq": "<UPLOAD_ID>" } }]
}

Status	Definition
AWAITING_UPLOAD	URL issued; file not yet uploaded
VALIDATING	File is being validated
VALIDATION_FAILED	Validation failed — see failureReason
TIMEOUT	Upload URL expired before completion
UPLOADED	File accepted and processed

Polling

Poll every 2–5 seconds, and time out after 5 minutes.

• Upload URLs are single-use and expire after 15 minutes. If the URL expires, call createFileUpload again.
• If validation fails, fix the file and start again from Step 2.

Multi-account uploads

A multi-account upload log has an empty partnerCompanyId — the per-account association comes from the partner_company_id column in the file, not from the upload log.

Supported upload types

API file uploads support the instream upload types — the same set for single-account and multi-account uploads:

• BYOD_MARKETING_INSTREAM
• BYOD_MARKETING_AGE_INSTREAM
• BYOD_MARKETING_GENDER_INSTREAM
• BYOD_MARKETING_SEARCH_INSTREAM
• BYOD_MARKETING_SITE_INSTREAM
• BYOD_MARKETING_PARTNER_SELLABLE_UNIT_INSTREAM
• BYOD_FINANCE_INSTREAM
• BYOD_FULFILLMENT_INSTREAM
• BYOD_RETAIL_INSTREAM

Partner-specific restrictions

Some partner channels accept only a subset of these types. If the type isn't valid for the channel, the request is rejected with an error listing the allowed types.

Date formats

The various BYOD templates accept multiple date formats for date fields (i.e. start_date, end_date, report_date). In order to ensure that these dates are parsed correctly, you will be asked to specify a date order upon upload of BYOD file. The three date order enum options are:

• MM_DD_YYYY — Month-Day-Year (default)
• DD_MM_YYYY — Day-Month-Year
• YYYY_MM_DD — Year-Month-Day

Dates can be input with either slashes or dashes.

Years can be input as either 2-digit or 4-digit years. 2-digit years are assumed to be in the 2000s (e.g. 00 is assumed to be 2000).

Uploading for multiple accounts (multi-PCID)

Use this mode when one file contains rows for several partner accounts ("partner company ids", PCIDs) on the same channel — for example, a single marketing report covering every retailer account you manage. Instead of one upload per data source secret, request one upload with the channel's partnerId (Step 2) and identify the account for each row inside the file.

The partner_company_id column

A multi-account file must contain a partner_company_id column whose value on each row names the partner account that row belongs to. After upload, Incremental splits the file by distinct partner_company_id and processes each part as its own drop for that account.

The example below shows a BYOD_MARKETING_INSTREAM file — the required columns for that type (start_date, end_date, partner_campaign_id) plus the added partner_company_id and a couple of optional metrics. Required columns differ per upload type; see the help center article linked at the top of this page.

Example rows — dateOrder: YYYY_MM_DD

start_date,end_date,partner_campaign_id,partner_company_id,impressions,spend
2026-07-01,2026-07-07,CMP-1001,ACCOUNT_A,10500,432.10
2026-07-01,2026-07-07,CMP-1002,ACCOUNT_B,8200,398.55

Request errors

Case	Result
Both dataSourceSecretId and partnerId supplied	Rejected: Exactly one of dataSourceSecretId or partnerId must be provided
Neither dataSourceSecretId nor partnerId supplied	Rejected: Exactly one of dataSourceSecretId or partnerId must be provided
partnerId not onboarded for your organization	Rejected: the partner channel must be onboarded for your organization (at least one company must have an active data source secret for that channel)