How to export Natterbox data

Natterbox allows you to export bulk data, enabling you to manage and process your call, text, and recording data externally.

Because every business has unique requirements, exports are handled on a per-request basis in close coordination with the Natterbox team.

Supported data

The following records are supported by the export service:

• Call logs

• Call recordings

• SMS messages

• MMS messages

• User data

Pricing

The cost of a data export is variable and is calculated based on two main factors:

• Data volume: the total amount of data being retrieved.

• Urgency: how quickly you need the export completed.

How to get started

To initiate a data export, contact your Account Manager (AM) to submit a formal request. To help us process your request as quickly as possible, provide your AM with the following information:

• Reason for export: why you require this data.

• Legal hold: if the export is for regulatory or evidential purposes, whether the dataset should be placed on legal hold to prevent automatic deletion.

• Timeframe: the date range for the dataset (for example, 2025-01-01 to 2026-01-01).

• Scope: whether you require the entire dataset or a partial export.

• Filtering criteria (if partial): how we should isolate the data (for example, "outbound calls only" or specific UUIDs).

• Destination: whether the files should be delivered to the default Natterbox-hosted SFTP server or directly to your own AWS S3 bucket.

Delivery destinations and requirements

Natterbox-hosted SFTP

This is the default delivery method.

Requirements

• SSH Public Key: The only requirement for this default method is providing an SSH public key to your AM.

  Prerequisite: This is a strict prerequisite; the export cannot be completed without it.

  Security: Please ensure you send Natterbox the public key only—never share your private key.

⚠️

Important: The SSH public key is a strict prerequisite — the export cannot be completed without it. Only ever send Natterbox your public key. Never share your private key.

Accessing your data

You will be notified once the data export is complete - to access your data, please follow these steps:

• Prepare an SFTP Client: Ensure you have an SFTP client installed (for example, FileZilla).

• Connect to the Server: Establish an SFTP connection to exports.natterbox.net (Port 22).

• Enter Your Username: Your username is your 4-digit customer ID, which your AM can provide.

• Authenticate: Log in using the private key paired with the public SSH key you provided during the requirements phase.

See the Data export format and schema section below for details of how the delivered data is structured.

Customer-owned AWS S3 bucket

Skip this section if you are using the default SFTP method.

Requirements

Provide the following configuration details to your AM:

• Bucket name: the exact name of your target S3 bucket.

• AWS region: the region where your bucket is hosted (for example, us-east-1).

• Location: the prefix (folder path) that Natterbox should export data to within your S3 bucket.

• KMS encryption: tell your AM whether you are using KMS encryption on the S3 bucket.

S3 bucket policy configuration

Add the following policy to your target S3 bucket to grant Natterbox the cross-account transfer permissions it needs. Replace <CustomerOrgID> and <CustomerBucketName> with your actual values:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "NatterboxBucketPermissions",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::257278351214:user/archiving-external-s3-<CustomerOrgID>"
            },
            "Action": [
                "s3:GetBucketLocation",
                "s3:ListBucket"
            ],
            "Resource": "arn:aws:s3:::<CustomerBucketName>"
        },
        {
            "Sid": "NatterboxObjectPermissions",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::257278351214:user/archiving-external-s3-<CustomerOrgID>"
            },
            "Action": [
                "s3:PutObject",
                "s3:PutObjectAcl",
                "s3:GetObject",
                "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::<CustomerBucketName>/*"
        }
    ]
}

KMS key policy configuration (optional)

If you use KMS encryption on your S3 bucket, you must also append the following block to your KMS key policy. Replace <OrgID> and <ARN of the KMS key> with your actual values:

{
    "Sid": "Allow-use-of-the-key",
    "Effect": "Allow",
    "Principal": {
        "AWS": [
            "arn:aws:iam::257278351214:user/archiving-external-s3-<OrgID>"
        ]
    },
    "Action": [
        "kms:Encrypt",
        "kms:Decrypt",
        "kms:ReEncrypt*",
        "kms:GenerateDataKey*",
        "kms:DescribeKey"
    ],
    "Resource": "<ARN of the KMS key>"
}

Data export format and schema

Directory structure and file formats

Once your data is exported, it is organised into a logical tree structure. Files are partitioned into monthly and daily sub-folders within your chosen export period to optimise data navigation:

• Call recordings (/recording/): saved as standard WAV files and titled by their unique call UUID. Each recording filename maps directly to a corresponding call log field (either ALegUUID or BLegUUID, depending on call direction and recording rule configuration).

• SMS and MMS messages (/sms/): SMS are saved as XML files with embedded metadata and text. MMS are saved as RFC822 EML files.

• Call logs (/call-logs/): delivered as daily flat datasets in TSV (tab-separated values) format.

• Users (/users.tsv): a single master user reference file located in the root folder, used to map user IDs to staff names.

Data schema reference tables

SMS and MMS fields

Call log fields

Call direction values

User fields

Limitations and considerations

ℹ️

Note: Insight Analytics and transcription data are currently excluded from bulk historical data exports. If you require continuous access to transcription text, consult your AM about live API streams.

Related articles

• How to request call recording deletions

• Reports with the Call Reporting Object