Connecting a CSV URL (HTTPS) on Clarisights
If a system you use can publish a report as a CSV file at a web address (for example a scheduled export link from a BI tool, a partner's reporting endpoint, or a file you host yourself), Clarisights can download that file on a schedule and load it into a custom channel. This is the URL CSV source.
At a glance
| Connector type | File download over HTTPS (read-only) |
| Authentication | None for public or signed URLs you set up yourself; basic authentication, OAuth 2.0, or custom request headers when set up by Clarisights |
| Channel types | POD and Custom Analytics (self-serve); Custom Advertising (set up by Clarisights) |
| File formats | CSV; gzip (.gz) or ZIP (one CSV per archive) compressed CSV |
| Refresh cadence | Every 1 to 24 hours, set on the channel |
| Fetch Now | Yes |
Before you start
The URL must return the CSV file itself, not a web page. Links that open a login page, a preview, or a download page return HTML and will fail with an invalid file type error.
The first row of the file must be the header row, and the file should be RFC 4180 compliant (comma separated, fields with commas or quotes wrapped in double quotes).
The file needs a date column so Clarisights can place each row in time.
Use an
https://address so the file is encrypted in transit. If the address contains spaces, replace them with%20.
Setting up the connection
Step 1: Add a channel
Click the Integrations icon (the database stack) in the left navigation bar. Under "Set up new connection", find POD (any data, such as CRM data, budgets, or targets) or Custom Analytics (data you want joined to your ad campaigns), and click + Connect. If you already have channels of that type, open the card under "Manage connected channels" and click + Channel.
Step 2: Fill in the form
Name and Abbreviation (up to 4 characters). These cannot be changed later.
Source Type: choose URL CSV.
URL of CSV: paste the address of the file.
Filters (optional): load only the rows that match conditions you set.
Data Refresh Interval: how often to download the file, every 1 to 24 hours. At 24 hours, also set the Data Refresh Time, the hour of the day (in your company timezone) when the download runs.
Look Back Period: how many recent days of data each download refreshes (60 days by default). It cannot exceed the Look Back Period Limit shown next to it; contact support if you need a longer window.
Look Ahead Period (optional): enable it if the file contains future dates, such as planned budgets, so that one year ahead is loaded on every sync.
Target distribution (optional): enable it if the file holds monthly or weekly values that should be spread evenly across days.
Save the channel.
Step 3: Map metrics and dimensions
On the channel list, click Metrics/Dimensions (POD) or Metrics (Custom Analytics) for your channel and add a metric or dimension for each column you want to load. If a column header in the file differs from the name you want in Clarisights, use + Header Map to map it. See Creating a POD data source for this step in detail.
Step 4: Load the data
The file is downloaded at the next scheduled refresh. To load it right away, click Fetch Now on the channel. Use Logs on the channel to check how many rows were imported and download the import report if rows failed.
⚠ Common error: Invalid file type → the URL returned a web page instead of a CSV. Open the URL in a private browser window: it should download a file straight away, without asking you to sign in.
⚠ Common error: We failed to fetch data → the URL could not be reached, returned an error, or has expired. Check that the link still works and, for signed links, that it has not expired.
Dates in the URL
If the address changes every day (for example, it contains the report date), you can put date placeholders in the URL. Clarisights fills them in on every download, using the channel's timezone.
Placeholder | Resolves to |
| Year, for example |
| Month, for example |
| Day of the month, for example |
| Changes which day the placeholders resolve to. Without it, placeholders resolve to yesterday's date. Write it directly after the placeholders, for example |
Example. https://reports.example.com/export?date=<year>-<month>-<day_of_month> downloads the report for yesterday on every run.
If your endpoint takes a start and end date, or needs several files combined, your CSM can configure that for you.
Options set up by Clarisights
Some endpoints need more than a plain link. Contact your CSM if your URL needs any of the following; these are configured on the Clarisights side:
Authentication: basic authentication (username and password), OAuth 2.0 tokens, or API keys and other values sent as request headers.
POST requests with a request body, date range parameters, or paginated responses.
Several URLs combined into one channel.
A URL CSV source on a Custom Advertising channel.
Files on an SFTP server instead of HTTPS (see SFTP Integration in Clarisights).
Share credentials only through the secure channel your CSM provides, never in a support message.
Limitations & known constraints
Each download must return a CSV file (optionally gzip or ZIP compressed, with one CSV per archive). Excel, Parquet, and HTML files are not supported.
Every download must keep the same column headers. If the export layout changes, update the channel's metrics and dimensions.
Read-only: Clarisights only downloads the file and never writes back to the URL.
Very large files take longer to download and process. If your file regularly exceeds a few hundred megabytes, consider Amazon S3, Google Cloud Storage, or a warehouse connector instead.
Need help?
When contacting support from the in-app messenger, please include:
The channel name and abbreviation (Integrations → Channel)
The exact error message or screenshot from Logs
When the issue started