In this article:

Overview

CSV Data Sync via Amazon S3 lets you automatically keep your Crossbeam data up to date by uploading CSV files directly to an Amazon S3 bucket—no manual uploads in the Crossbeam UI required. Once a file is uploaded, Crossbeam processes it automatically and refreshes your overlap data.

This method requires API access and is best suited for teams who want to automate their data syncs programmatically.

Plan Availability

✍️ Note

CSV Data Sync via Amazon S3 is only available on the Supernode and Enterprise plans. To upgrade your account, visit the Plan & Billing page.

File Requirements

Naming Convention

Files must follow this pattern: OBJECTTYPE_DATETIME_FILETYPE.csv

ObjectType — ACCOUNT, DEAL, LEAD, or USER
Datetime — YYYYMMDDTHHMMSS format (timezone must be consistent)
FileType — FULL or DELTA

File Type	What it contains	When to use
FULL	Your entire dataset. Replaces all previously imported records.	Weekly; always required as your first upload
DELTA	Changes only—new, updated, or deleted records. Each record must include all its fields, even if only some changed. Set `is_deleted` to `true` for deleted records.	At least once daily after initial setup

✍️ Note

Once a file is uploaded, it cannot be modified or replaced. To correct data, upload a new file with a new datetime in the filename.

Format Requirements

Encoded in UTF-8, max 500 MB per file
One record per line; fields separated by commas
Must include a header row, an ID column, and an Is Deleted column
Column names must match Crossbeam's standard field definitions (additional fields are permitted)

Account Source

Field Name	Description	Required?
`Id`	Unique ID of the account; subsequent uploads will be treated as upserts on this field	✓
`Name`	Company name	✓
`Website`	Company website/domain	✓
`Phone`	Company phone number	—
`Address`	Address line 1	—
`City`		—
`Region`	Address region (global) or state (US)	—
`Postal Code`	Address postal code (global) or zip (US)	—
`Country`		—
`Industry`		—
`Created At`	Date the company was created in your CRM	—
`Number of Employees`		—
`DUNS Number`		—
`Type`	Account type	—
`Owner ID`	ID of the internal user who owns this account in your CRM (links to the Owner source file)	✓ if syncing Owners
`Is Deleted`	If set to `true`, triggers a delete of the record with the associated Id	—

Owner Source

Field Name	Description	Required?
`Id`	Unique ID of the user; subsequent uploads will be treated as upserts on this field	✓
`Name`	First + last name	—
`Email`		✓
`Phone`		—
`Title`	Job title	—
`Is Deleted`	If set to `true`, triggers a delete of the record with the associated Id	—

Deal Source

Field Name	Description	Required?
`Id`	Unique ID of the deal; subsequent uploads will be treated as upserts on this field	✓
`Account Id`	Unique ID of the account this deal is associated with (links to the Account source file)	✓
`Name`	Deal name	—
`Amount`		—
`Currency`	Currency for the Amount; if not provided, amounts will be assumed to be USD	—
`Open Date`		—
`Closed Date`		—
`Stage`		—
`Is Won`	Boolean; `true` if won, `false` if not	—
`Is Closed`	Boolean; `true` if closed, `false` if not	—
`Last Activity At`		—
`Last Stage Change Date`		—
`Type`		—
`Owner ID`	ID of the internal user who owns this deal in your CRM (links to the Owner source file)	—
`Is Deleted`	If set to `true`, triggers a delete of the record with the associated Id	—

Lead Source

Field Name	Description	Required?
`Id`	Unique ID of the lead; subsequent uploads will be treated as upserts on this field	✓
`Name`	First + last name	—
`Email`		✓
`Phone`		—
`Title`	Job title	—
`Account Name`	Company name	—
`Account Website`	Company website/domain	—
`Address`	Address line 1	—
`City`		—
`Region`	Address region (global) or state (US)	—
`Postal Code`	Address postal code (global) or zip (US)	—
`Country`		—
`Created At`	Date the lead was created in your CRM	—
`Owner ID`	ID of the internal user who owns this lead in your CRM (links to the Owner source file)	✓ if syncing Owners
`Is Deleted`	If set to `true`, triggers a delete of the record with the associated Id	—

Step 1: Set Up API Access

API integrations now live on the API page. For more on the page and its tabs, see How to Use the API Page in Crossbeam.

Go to Data > API, open the API Integrations tab, and click Create Integration.

In the modal, complete the following fields:

Integration name: Choose a name to identify this integration
Integration description: optional, 140 character max
Callback URL: set to https://oauth.pstmn.io/v1/callback
Allowed Origins: leave blank

Click Create Integration.

Your client ID and client secret are in the integration’s Settings on the API Integrations tab.You'll need these in Step 2.

✍️ Note

For full instructions on completing the OAuth 2.0 authorization flow and obtaining your refresh token, see the Crossbeam API authentication documentation. During authorization, request the following scopes: openid, offline_access, and write:data-sources.

Step 2: Get an Access Token

Exchange your refresh token for a short-lived access token. You'll need this for all subsequent API calls.

Call https://auth.crossbeam.com/oauth/token with your credentials:

curl --location 'https://auth.crossbeam.com/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
    "grant_type": "refresh_token",
    "client_id": "your client id",
    "client_secret": "your client secret",
    "refresh_token": "your refresh token"
}'

Response:

{
  "access_token": "...",
  "id_token": "...",
  "scope": "openid write:data-sources offline_access",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Step 3: Get Temporary S3 Credentials

Call the Crossbeam API to get temporary AWS credentials for write-only access to your organization's S3 folder.

First, retrieve your organization UUID:

curl --location 'https://api.crossbeam.com/v1/users/me' \
--header 'Authorization: Bearer <your access token>' \
| jq -r '.data[0].organizations[].uuid'

Then request your temporary credentials:

curl --location --request POST 'https://api.crossbeam.com/v0.1/s3-tokens' \
--header 'xbeam-organization: <your org uuid>' \
--header 'Authorization: Bearer <your access token>'

Response:

{
  "access_key_id": "...",
  "secret_access_key": "...",
  "session_token": "...",
  "bucket": "prod.crossbeam.file-drop-off",
  "prefix": "22287/",
  "expires_in_seconds": 3600
}

The response includes your bucket, prefix (your org's dedicated folder) and temporary AWS credentials. Save these—you'll need them in Step 5.

✍️ Note

Credentials expire after one hour. Request new credentials when they expire.

Step 4: Connect Your Data Source in Crossbeam

Once your API access is configured, connect your data source in Crossbeam.

Click on Data from the navigation bar, then select Data Sources from the dropdown.

Scroll to the Amazon S3 tile and click on it.
Follow the prompts to name your data source and define the object types you plan to sync (e.g., Account, Deal, Lead, User).
Map your CSV columns to Crossbeam's standard properties (e.g., Account Name, Website, Opportunity Amount).

✍️ Note

No data is being shared at this point. This step syncs your data source with Crossbeam. You'll decide what to share with your ecosystem later.

Step 5: Upload Your CSV to S3

Use the credentials from Step 3 to upload your file. The upload path must follow this format:

s3://{bucket}/{prefix}{filename}.csv

Example using the AWS CLI:

export AWS_ACCESS_KEY_ID="access_key_id from step 3"
export AWS_SECRET_ACCESS_KEY="secret_access_key from step 3"
export AWS_SESSION_TOKEN="session_token from step 3"
export PREFIX="prefix from step 3"

aws s3 cp ACCOUNT_20260226T090000_FULL.csv \
s3://prod.crossbeam.file-drop-off/${PREFIX}ACCOUNT_20260226T090000_FULL.csv \
--region us-east-1

Crossbeam automatically processes the file once uploaded. If processing fails (for example, due to a schema mismatch), an email notification is sent to the designated contact.

How to Connect CSV Data via Amazon S3 as a Data Source

Overview

Plan Availability

File Requirements

Naming Convention

Format Requirements

Step 1: Set Up API Access

Step 2: Get an Access Token

Step 3: Get Temporary S3 Credentials

Step 4: Connect Your Data Source in Crossbeam

Step 5: Upload Your CSV to S3