All Collections
Hosts
Host Directories
Directory syncing via cURL method
Directory syncing via cURL method

This article describes how to use cURL to upload your Active Directory(AD) / LDAP directory as hosts

Chris Green avatar
Written by Chris Green
Updated over a week ago

Please note:
​
​By default, accounts are limited to 5000 hosts per team. Hosts are unlimited on all Sine plans (subject to appropriate use) and so this can be increased on request — please chat with our support team.

The contents of this page is intended for a system administrator or IT specialist to set up automatic host upload. Please contact them for assistance in setting up this feature.

The ‘cURL’ command is not natively supported in some programs such as Windows Powershell.

Active Directory and LDAP can be used to automatically export data (such as employee or host data) to a CSV file periodically. This CSV file can then be uploaded directly to Sine’s back-end, updating your account, without using the dashboard. This can be accomplished by using shell script and the cURL command.

In a complete setup for maintaining your host list:

  1. Active Directory (or your database system) exports the host data to a CSV file.

  2. The cURL command connects to Sine’s database, which asks for an API key(which Sine will generate). With a valid key, the CSV is uploaded to Sine’s database.

  3. Sine processes the CSV, adds missing hosts and updates existing ones on your host list. Your host list will then contain all of the data listed in the CSV file. Optionally, you can also remove any hosts not included in the uploaded CSVand send emails to all new hosts.

You can then automate this process, eliminating the need for the administrator to manually update your host list.

Generating an API Key

In order to connect to Sine’s database, you will need to copy an API key (generated automatically by Sine) and use it in the cURL command. To do so:

  1. Navigate to the Sine Web Dashboard (https://dashboard.sine.co) and select Team from the side-menu.

    2. Open the API Keys tab

   3. Select the Generate button on the right.

  4. An API key will be generated for you. This API key can be used to upload CSV Host lists to your Host list in Sine’s database. Keep this key private – anyone with access to this key can edit your host list without logging in.

 5. Once your API key is generated, copy the generated cURL command to a shell or shell script. Please see the Using the cURL command segment of this article for more instructions on how to accomplish this. (Note: cURL command is not natively supported in some programs such as Windows Powershell)

(Optional): You can tick the boxes underneath the command to replace all hosts not in the data or send a welcome to all new hosts respectively.

6. The check-boxes allow you to control if the old hosts are removed from your host list and if new hosts will receive an email invite to Sine. ‘remove-hosts=true‘ will add all new hosts AND remove any host that is not in the CSV. ‘send-emails=true‘ will send an invite to all new hosts in the list to create a Sine account.

CSV Layout

Please see this page for a sample CSV, in order to correctly format your CSV output to so that it can be read by Sine’s database.

The following is the header layout required in the CSV for correct parsing:

Email,First Name,Last Name,Group Name,Site Name,Mobile


This must be the first line of your CSV file. All fields are case-sensitive. The mobile field must be in the header, but hosts’ mobile numbers are optional.

Using the cURL command

You have now generated your command and want to give it a go? First off, you will need to have generated a CSV file to upload using the command. Use Active Directory (or other automated process) to generate your CSV file. Alternatively, follow the steps here to export your host list to generate a CSV file manually.

NOTE: cURL is not natively supported in some programs such as Windows Powershell. Please follow the steps outlined below to ensure that you are running cURL correctly.

Now that you have your CSV file, you will need to ensure your system can use the cURL command correctly. As some systems (such as Windows computers) do not support cURL by default and it may be necessary to download cURL. To ensure you are running the correct version of cURL, please follow the steps below:

  1. Navigate to this site: https://curl.se/download.html

  2. Select curl executable.

  3. For Operating System, choose which operating system you are running from the drop-down menu.

  4. For What Flavour, select Generic from the drop-down menu.

  5. For Which OS Version, select Unspecified from the drop-down menu.

  6. For What CPU, leave it as the default.

  7. Download the applicable file. For most users, this will be the top .7z or .zip file (similar to the examples pictured below).

  8. Once the file has downloaded, navigate to it and find the curl.exe file. This will be in the “bin” folder.
  9. In Windows computers, hold shift and right-click on the curl.exe file. After doing so, a drop-down menu should open up, please click on Copy as Path(using the default click only).

 10. Open your default terminal and paste the path in there (remove the quotes around it). It should read similar to:

 11. Navigate back to Sine and the API key page.
 12. Click Copy cURL to clipboard.

 13. Navigate back to Powershell and paste the command into the terminal (be sure to add a space after “…curl.exe” and remove the “curl” included in the pasted command). It should read similar to:

 14. Navigate to your CSV file (for a host export, this will be called host-list.csv) and Copy as Path again (as in Step 9)
 15. Navigate back to Powershell and remove the “HostsFile.csv” segment and replace it with the file path of the host-list.csv file (paste it in and remove the quotes around it). It should read similar to:

 16. Press Enter and the cURL command will run. If it ran correctly, it shouldn’t say anything. If any errors have appeared, please ensure that everything is typed in correctly and located in the correct places. Failing that, please contact [email protected] or click on the live-chat bubble in the bottom-right of this page.

Automating Host Upload

Windows

Task Scheduler makes it easy to upload a CSV on a periodic basis. The following instructions assume cURL is installed into a directory in the PATH environment variable.

  1. Generate an API key by following the process above and copy the command from Step 5 to the clipboard.

   2. Open Task Scheduler. This is found in Start > All Programs > Administrative Tools > Task Scheduler.

3. On the right, in the Actions pane, select Create Basic Task.

4. Give your task a name and description, and click Next.

5. Select the frequency that you would like the CSV to upload. Daily uploads are recommended.
 * If your database system triggers an event when it exports as a CSV, select “When a specific event is logged” instead, and navigate to the event.


6. Set the time you wish to automatically upload the CSV.

7. Check Start a program.

8. Paste the cURL command into the Program/script box. Make sure to change the file path to the CSV you wish to upload.

9. If a message box appears, select Yes.

10. Select Finish, and every day at your specified time, the CSV will be uploaded.

11. Hosts will be updated in the Hosts page.

Common Errors

While attempting to upload a CSV, it’s quite possible that you may run into some errors if your data isn’t formatted correctly, your cURL command is incorrect or you simply don’t have your files in the correct locations. Detailed below are a variety of common issues that users may run into. Please note this is not a comprehensive list of all errors and if you are having difficulty, please contact your IT Administrator. Alternatively contact Sine support at [email protected] or by using the chat bubble in the bottom right corner of this page.

Command Errors

Command errors occur when you are invoking the command incorrectly. This can be because you are missing a file, calling cURL incorrectly, not retrieving the CSV from the correct location, etc. Some common errors are listed below.

Invoke-WebRequest : Cannot bind parameter ‘Headers’. Cannot convert the “X-Sine-Api-Key:
​API-KEY-HERE” value of type “System.String” to type “System.Collections.IDictionary”.

An error like this indicates that you are using the wrong command for cURL. Please ensure you have invoked cURL correctly by navigating to the directory that contains it. See Steps 1-10 for more detail.

{“code”:”MULTIPART_INVALID”,”message”:”file field form-data missing”}

This error indicates that you have left of the ‘@’ symbol in front of your Host CSV file in the command. Please see Steps 14-15 for more detail.

Data Errors

Data errors are errors that occur due to invalid or missing data in the CSV file. They will appear in a format similar to {“code”:”CSV_DATA_VALIDATION_ERROR”,”message”:[{“index”:0,”row”:{“Email”:””,”First Name”:”First”,”Last Name”:”Last”,”Group Name”:”Group”,”Site Name”:”Sine HQ | Demo”,”Mobile”:””},”errors”:[“Error Appears Here”]}]}. Depending on the actual issue, the “Error Appears Here” segment will contain a variety of error messages, some common examples are explained below.

Note: The Index number indicates how many rows down the error occurs (skipping the header row) in the data. So if you have an error at index:0, this will be in the first row of data.

"INTERNAL_SERVER_ERROR": please check that your CSV is UTF-8 encoded

Email invalid – This error is displayed when you have an invalid email. This could mean that you haven’t entered an email or you have entered an email incorrectly.

First name missing – This error is displayed when there is no data entered in the first name field for that entry.

Last name missing – This error is displayed when there is no data entered in the last name field for that entry.

Group name missing – This error is displayed when there is no data entered in the group name field for that entry.

Site name missing – This error is displayed when there is no data entered in the Site name field for that entry.

Site name not found – This error is displayed when the Site name for that entry does not match any Sites in your team. Please ensure the Site name is entered exactly as it appears on the web dashboard.

Mobile invalid – This error is displayed when the mobile you have entered is invalid. Please ensure you enter all mobile numbers with the correct area code in front e.g. 61412345678. Numbers not entered with the area code will also cause an invalid error.

If there are multiple issues, these messages will stack up one after another, please look at each error individually and it’s separate data.

Did this answer your question?