SFTP v1.0.0

On visitor action (such as click on a button, scoring, input...) Screeb can upload a JSON file to an external SFTP server containing the response data.

Entities

• Organization: A Screeb account, shared by many Screeb users of your company
• Channel: A distribution channel for your survey (Javascript SDK, Android SDK, iOS SDK...)
• Survey
• Survey scenario: A versioned survey: on survey update, your flow is saved in a new scenario. New users will see the last scenario.
• User: Information about the visitor
• Response: A response is a chain of question+answers. A user sometimes has many responses to a single survey.
• Question
• Answer: An answer is part of a response. Each answer is associated with a question.
• Field: An answer may have many fields (eg: multiple choices question)

Hook types

You can trigger SFTP uploads on 3 different events:

• On survey display: a survey is shown to visitors, but no question is replied. You will get notified even if no response is given.
• On question answered: a question has been replied. This webhook will be triggered for each question of a single survey.
• On response end: a survey has been closed or fully replied to by the user.

Configuration

To configure your SFTP integration, you need to provide:

• Host: The SFTP server hostname or IP address
• Port: The SFTP connection port. If empty, Screeb uses 22.
• Username: Your SFTP account username
• Password: Your SFTP account password
• Path: Optional base directory on the SFTP server. If provided, Screeb trims leading and trailing slashes and appends its own folder structure below it.

Remote file structure

Screeb always uploads JSON files in a deterministic directory layout:

• Survey display events: /workspaces/<workspace_id>/surveys/<survey_id>/displays/<response_id>.json
• Question answered events: /workspaces/<workspace_id>/surveys/<survey_id>/responses/<response_id>.json
• Response ended events: /workspaces/<workspace_id>/surveys/<survey_id>/responses/<response_id>.json

If you configure a custom base path, it is prepended to the structure above. For example:

• Configured path: /exports/screeb
• Final upload path: /exports/screeb/workspaces/<workspace_id>/surveys/<survey_id>/responses/<response_id>.json

Because response.answered and response.ended use the same destination path for a given response, later uploads replace the previous file for that response.

Payload format

The SFTP integration uploads survey data in JSON format. The filename is the response identifier:

<response_id>.json

Payload structure

{
  "event_id": "64c7ea3b-827b-4679-b25d-7fd61f6c3d33",
  "event_type": "response.ended",
  "version": "1.0.0",
  "time": "2021-07-29T13:45:09.325344042Z",
  "time_ms": 1627566309325,
  "payload": {
    "organization": {
      "id": "b5969d13-5e5e-4648-9806-5339ddafd984",
      "name": "ACME"
    },
    "channel": {
      "id": "411ee7c3-7e64-409f-9d75-c782b3f73aa4",
      "type": "android"
    },
    "survey": {
      "id": "9b913c69-3daf-4a6e-a26d-042004fc7881",
      "name": "Measure NPS",
      "scenario_id": "cc4a3710-e8ee-4672-a35c-5c17485ec441",
      "scenario_version": 9,
      "scenario_time": "2021-07-29T00:08:31.069497Z",
      "scenario_time_ms": 1627517311069
    },
    "user": {
      "anonymous_id": "2eb83fb4-b1b3-4e48-be48-a8fd9c4e5a7d",
      "user_id": "samuel@screeb.app",
      "name": "Samuel Berthe",
      "email": "samuel@screeb.app",
      "group_names": ["Screeb", "10-100-companies", "plan-enterprise"],
      "properties": {
        "firstname": "Samuel",
        "lastname": "Berthe",
        "email": "samuel@screeb.app",
        "plan": "free"
      }
    },
    "response": {
      "id": "5854a797-628c-4906-bb4c-da03e418cf47",
      "locale": "en-US",
      "time": "2021-07-29T13:44:59.831Z",
      "time_ms": 1627918228831,
      "time_to_complete_second": 34,
      "completion": "fully_completed",
      "hidden_fields": {
        "variable-from-crm": "blablabla"
      },
      "context": {
        "active_page": {
          "url": "https://screeb.app/solutions/product-analytics?utm_medium=email"
        },
        "locale": "en-GB"
      },
      "question": {
        "id": "a44252c3-ef3d-4156-90d6-a3d6364516c0",
        "correlation_id": "c6d4d007-879f-43fe-b4cf-d58e1f8ed1f8",
        "type": "input",
        "title": "How can we improve your experience?"
      },
      "answer": {
        "field": {
          "id": "c71dfe9d-6b47-452f-bda2-6091c13561b0",
          "correlation_id": "eb398cc0-1223-4590-bb60-e41ac8dfb0f6",
          "type": "string",
          "value": "The new dashboard is buggy.",
          "text": "The new dashboard is buggy."
        },
        "fields": [
          {
            "id": "c71dfe9d-6b47-452f-bda2-6091c13561b0",
            "correlation_id": "eb398cc0-1223-4590-bb60-e41ac8dfb0f6",
            "type": "string",
            "value": "The new dashboard is buggy.",
            "text": "The new dashboard is buggy."
          }
        ],
        "replied_at": "2021-07-29T13:45:09.286Z",
        "replied_at_ms": 1627566309286,
        "tags": ["screeb", "feedback"]
      },
      "tags": ["screeb", "feedback"],
      "items": [
        {
          "question": {
            "id": "a44252c3-ef3d-4156-90d6-a3d6364516c0",
            "correlation_id": "c6d4d007-879f-43fe-b4cf-d58e1f8ed1f8",
            "type": "input",
            "title": "How can we improve your experience?"
          },
          "answer": {
            "fields": []
          }
        }
      ]
    }
  }
}

Payload notes

• The top-level JSON contains event_id, event_type, version, time, time_ms, and payload.
• payload.user.properties, payload.response.context, and payload.response.hidden_fields are free-form nested objects.
• payload.response.question and payload.response.answer are mainly useful for response.answered events.
• payload.response.items contains the ordered list of answered questions available at the time the file is generated.
• payload.response.answer.field is kept for backward compatibility, while payload.response.answer.fields is the complete list.
• Question and answer fields include both id and correlation_id.

Event-specific behavior

• response.displayed uploads to the displays folder and uses the response creation time as event time.
• response.answered uploads to the responses folder and includes question, answer, items, tags, and a computed completion status.
• response.ended uploads to the responses folder and includes the final items, tags, completion, and time_to_complete_second.

Best practices

1. Use a dedicated SFTP directory for Screeb exports.
2. Expect files to be overwritten for the same response in the responses folder.
3. Restrict the SFTP account to write access on the export directory only.
4. Consume files by parsing JSON content rather than relying on filename patterns.
5. If needed, archive files after ingestion on your side.

Troubleshooting

Connection failed

• Verify that the SFTP server is reachable
• Check firewall rules allow outbound connections to the SFTP port
• Verify credentials are correct

Authentication error

• Ensure username and password are correct
• Check if the SFTP account has the necessary permissions

Upload failed

• Verify the remote path exists and the account has write permissions
• Check available disk space on the SFTP server

Compatibility notes

• Authentication currently uses username/password.
• If no port is configured, Screeb connects on port 22.
• Screeb creates missing directories automatically before uploading the file.

Support

For additional help with your SFTP integration, please contact our support team or refer to the main API documentation.