Import behavior signals in bulk via SFTP

Acoustic Connect can bulk-import behavior signals from a file already staged on your Acoustic SFTP server, processing many historical or batched signals in a single job. Use this method instead of createSignals when you need to backfill historical data or move signals captured outside Connect's real-time tracking — for example, a data pipeline that exports nightly behavior logs.

Requirements

Signal limits

Your Connect subscription determines which signal types you can import. The same catalog and tier restrictions apply as for real-time import:

Contact mapping

Each signal in the file maps to a contact via identifiableAttributes, using one of: contactKey (existing contacts only), email, sms, or whatsapp. A contact key alone cannot create a new contact — a signal with only a contact key for an unknown contact is discarded.

File format

• Format: JSONL only — each line is one standalone signal JSON object. fileFormat: DELIMITED is not applicable to signals imports.
• Maximum file size: 500 MB.
• Files are automatically removed from the SFTP server 14 days after upload.

Batch size

Not applicable — the entire file is submitted as one import job rather than as discrete batches.

Before you begin

Obtain your application key, which maps imported signals to an application:

• Connect Pro: Supplied during onboarding
• Connect Premium and Ultimate: Generated via Connect interface (see generate credentials documentation)

Confirm you have:

• Access to the Acoustic SFTP server (see Connect to the Acoustic SFTP server)
• A properly formatted JSONL file, already uploaded to your subscription's SFTP folder

The file must exist on the SFTP server before you call createImportJob. The mutation starts a job against a file that's already there — it does not accept or upload file content itself.

Running the mutation

First-time API users should review "Using the Connect API" for authentication and testing tool recommendations.

mutation CreateImportJob($importInput: ImportInput!) {
  createImportJob(importInput: $importInput) {
    id
  }
}

Example

{
  "importInput": {
    "importType": "ADD_UPDATE",
    "into": "SIGNALS",
    "fileFormat": "JSONL",
    "skipFirstRow": false,
    "jobName": "SignalsImportJob_<uuid>",
    "fileLocation": {
      "type": "SFTP",
      "folder": "automation",
      "filename": "signals.jsonl"
    }
  }
}

Mutation arguments

importInput (required): Object — see fields below. ImportInput has additional fields used by audience and reference-set imports (dataSetId, dataSetType, mappings, attributes, consent, createSegment, and others); none of those apply when into: SIGNALS and can be omitted.

ImportInput fields for a signals import

• importType (required): Enum — ADD_UPDATE is the value used for signals imports.
• into (required for this flow): Enum — SIGNALS. Unlike audience or reference-set imports, no dataSetId or dataSetType is required.
• fileFormat (required): Enum — JSONL.
• jobName (required): String — a name for the import job. Convention: SignalsImportJob_<uuid>.
• fileLocation (required): Object —
  • type (required): Enum — SFTP.
  • folder (required for SFTP): String — the SFTP subfolder name containing the file (not the full path).
  • filename (required for SFTP): String — the filename only, excluding the folder.
• notifications: Array of objects — optional; omit to send no notifications.
  • channel (required): Enum — valid value: EMAIL.
  • destination (required): String — where to send notifications.
• skipFirstRow: Boolean (default false) — not meaningful for fileFormat: JSONL; applies only to DELIMITED files.

Signal file object (one per line in the JSONL file)

• appKey (required): String — your application identifier in Connect.
• identifiableAttributes (required): Object — one contact identifier as a key-value pair. Valid keys: contactKey, email, sms, whatsapp.
• sessionId: String — optional; groups signals from the same contact session. See Session ID behavior below.
• signalContent (required): JSON object — the signal data specific to each signal type. See the Real-time signal import reference for the field breakdown per signal type — the same signalContent shapes apply here.
• test: Boolean (default false) — optional; flag for test signals.

{
  "signal": {
    "appKey": "YOUR_APP_KEY",
    "identifiableAttributes": {
      "email": "[email protected]"
    },
    "sessionId": "SESS-789456123AB",
    "signalContent": {
      "signalType": "addToCart"
    },
    "test": false
  }
}

Response fields

The mutation returns a JSON response containing:

• data: Object — root data object containing mutation results
  • createImportJob: Object — result of the import job creation
    • id: String — the import job identifier. Use this to track progress in Job monitoring.

Verification methods

Method 1: Check job status

1. Go to Data management > Job monitoring.
2. Select the Job status tab.
3. Find the job by name and track its progress.

Method 2: Review contact activity

1. Go to Data management > Audience.
2. On the All contacts tab, select a contact associated with the imported signals.
3. Check the activity feed for the signals.

Notes:

• Activity feed shows the 5 most recent signals per session (identification signals aren't displayed).
• Displays the last 1,000 signals or signals from the last 30 days, sorted by signal timestamp.
• Newly imported signals may not be immediately visible — wait a few minutes and refresh.

Method 3: Signal management

Go to Behavioral management > Signal management and select a signal type to confirm imported signals appear in the list.

How it works

Required vs. optional fields

If any required field in a signal line is missing or invalid, that entire signal is discarded — the rest of the file continues processing independently. Optional fields enhance a signal but don't prevent processing if omitted.

File and job requirements

• The file must already exist in the specified SFTP folder before createImportJob is called.
• Source files are automatically removed from the SFTP server 14 days after upload — re-upload if you need to re-run an import on older data.
• Maximum file size is 500 MB.

Test signals

When test is set to true:

• Signals undergo standard validation.
• They have no impact on campaigns.
• They aren't visible in the Activity feed, Segmentation, or Insights.

Session ID behavior

When you provide a sessionId:

• The system registers the session as if it was generated by the Connect library.
• Signals are included in aggregate reports and in-market interest calculations.

When you omit sessionId:

• Signals appear in contacts' activity feeds.
• Signals aren't used for aggregate reports or behavioral intelligence calculations.

Related pages

• Enable real-time import of behavior signals to Connect
• Import behavior signals from local storage
• Import behavior signals from SFTP
• Send signals from a backend system