How to connect Custom URL Import to Adriel

Detailed instructions to help you set up the data source with Custom URL Import.

Lastly modified on: Tue, 29th July, 2025 at 05:47 PM

Prerequisite

• An API URL to access the CSV file or JSON that you want to connect to.
• CSV File is supported by a separate connector named "CSV File."

Instructions

1. Move to Adriel's Connections page.
2. Type "Custom URL Import" into the search bar

Step 1: Connection Setting

1. Connection Name: This field will label the connection information, helping to differentiate between multiple sets of credentials.

Step 2a: Required Data Source Settings

Fill in the five required fields.

1. Name:
   1. Fill in the data source name. Any identifiable name is sufficient.
2. Data Type:
   1. Choose between CSV or JSON as the format of the data being sent by the API.
3. URL:
   1. Input the URL of the API used to retrieve the data. If applicable, replace any date parameters with $date.
      1. E.g.,https://api.example.com/data?from=20250101&to=20250201&type=csv
         becomes
         https://api.example.com/data?from=$date&to=$date&type=csv
   2. It is possible to only have one date parameter or two. Please make sure to replace all with $date.
   3. If the method of the URL is POST, it is possible to have no date parameter within the URL. In which case it should be in the Body Parameters in the optional configurations below.
   4. $date is used as a placeholder to specify the date format for your date parameters. Having “from=$date&to=$date” in your URL does not imply that the data will be fetched from the same start and end date. The actual date range for the fetch will be defined later in the connector's configuration.
4. Date format:
   1. Date format expected by the API. 
   2. This should be defined in the API documentation. For more details see https://date-fns.org/v4.1.0/docs/format 
      1. E.g., yyyy-MM-dd or yyyy/MM/dd.
5. HTTP Method: 
   1. Method used for the API call, GET or POST.

Step 2b: Optional Configurations

The following fields are optional configurations that will that can further customize this connector, or handle advanced settings.

1. Alternative Channel Name 
   1. You can customize the name of the channel with this field. If not provided, the data source’s channel name will be “Custom URL Import.”
2. Alternative Channel Icon
   1. Customize the channel’s icon with this field.
   2. Please make sure to upload an SVG file.
3. Unique Identifier Columns
   1. If applicable, list the columns that uniquely identify each row of data. To use more than one column, separate them with commas. This typically refers to columns like date, name, IDs, etc. 
   2. If the system finds a row with the same exact values within these columns, we can confirm it is an existing record, and update that row’s data. If a row has a different value within these columns, we can confirm it does not already exist, and add that data.
      E.g. “ID,NAME” defined as unique identifier columns:
      
   3. If this field is left blank, all data will be replaced daily. If the data being sent does not include any unique identifiers, this field should intentionally be left blank.
   4. If a column that does not exist in the dataset is inputted, the connector will not be created.
4. Number of Days to Fetch 
   1. Number of days in the past that should be fetched upon connector creation. How many days of historic data would you like to cache? If not provided, the default will be 180 days.
   2. API limitations are considered. If you enter a value higher than the API limitation, we will cap the number of days to the limit. 
   3. Note: If the data being sent does not include any date associations, this field should intentionally be left blank.
      
5. Number of Days to Refresh
   1. Number of days in the past that should be re-fetched during each daily refresh. How much data would you like to re-fetch each day? If not provided, the default will be today.
   2. API limitations are considered. If you enter a value higher than the API limitation, we will cap the number of days to the limit.
   3. Note: If the data being sent does not include any date associations, this field should intentionally be left blank.
      
6. [IF CSV] CSV Column Names 
   1. If the API response does not include column headers, please provide in the exact order they appear in the response, separated by commas.
   2. E.g., date, campaign, clicks, impressions
7. [IF JSON] Response Body Path
   1. If the report rows are nested inside the response body, enter the JSON path to the array. (For more information about JSON Path, visit JSON Path Examples and JSON Path Online Evaluator.)
   2. E.g., Given {”data”: { ”reports”: [] } }, input data.reports
   3. Note: If the report rows are not nested, please input the key independently.
8. [IF POST] Body Params
   1. Provide the body parameters for the POST request. Must be a valid JSON. If the date parameters are in the Body Params instead of the URL, replace them with $date. (For more information about the nature of the $date parameter, please refer to step 2a-3.)
   2. E.g., { “start_date”: $date, “end_date”: $date, “timezone”: “UTC”, “metrics”: [] }
9. HTTP Query Header
   1. This field is necessary if the API requires a key or bearer token. Provide the API key or bearer token as an HTTP header to add on the query. Must be a valid JSON. 
   2. This can be found under sections like Authentication, Headers, or Tokens within the API documentation.
      1. E.g., { “x-api-key”: “YOUR_API_KEY” }
      2. E.g., { “Authorization”: “Bearer YOUR_API_TOKEN” }
10. Does the API require a refresh token?
    
    1. This should be checked if the key or token expires and must be refreshed regularly. If so, the token parameter must be replaced by $token in one of the 3 inputs: URL, HTTP Header, or the Body Params (If POST). The token will be reused for one hour once retrieved. 
       1. E.g. of URL: https://api.example.com/data?access_token=$token&from=$date&to=$date 
       2. E.g. of HTTP Header: { “Authorization”: “Bearer $token” }
       3. E.g. of Body Params (If POST): { “token”: $token, “start_date”: $date, “end_date”: $date }
    2. Refresh Token URL
       1. Copy paste the refresh token URL as provided by the API documentation.
    3. Refresh Token Request Body 
       1. Copy paste the refresh token request body as provided by the API documentation.
       2. Provide the JSON path to the access token in the response body. (For more information about JSON Path, visit JSON Path Examples and JSON Path Online Evaluator.)
          1. E.g., Given { ”data”: { “token”: [] } }, input data.token
       3. Note: If the token is not nested, please input the key independently.Refresh Token Response Path 
11. Does the API use pagination?
    1. This should be checked if the API provides paginated data. If so, the page parameter must be replaced by $page in one of the 3 inputs: URL, HTTP Header, or the Body Params (If POST).
       1. E.g. of URL: https://api.example.com/data?page[number]=$page&page[size]=5000&from=$date&to=$date
       2. E.g. of HTTP Header: { “X-Page-Number”: $page, “Authorization: “Bearer YOUR_API_TOKEN” }
       3. E.g. of Body Params (If POST): { “page”: { “number”: $page, “size”: 5000 } }
    2. Total Count Path
       1. Provide the JSON path to the total record count in the response body. (For more information about JSON Path, visit JSON Path Examples and JSON Path Online Evaluator.)
          1. E.g., Given { ”pagination”: { “total”: [] } }, input pagination.total
       2. Note: If the total record count is not nested, please input the key independently.

Click the "Submit" button below to complete the data connection.

It can take a couple hours for the data to be cached upon connector creation.