Toggle Side Panel
Close search
View Categories

API Example Walkthrough

1 min read

This document describes how to approach the following use cases using Cyclr’s API:

  1. Create an Account
  2. Install a Template as a new Cycle
  3. Authenticate a Connector
  4. Set Step Field Mapping
  5. Start the Cycle

Throughout this article, the example requests use a domain of api.cyclr.com.
That should be replaced with the appropriate API Domain for your Cyclr Console.
To find your API Domain, see the Interactive API Reference page.

1. Create an Account #

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d  '{ \ 
 "Id": "(Optional) The External Account ID you would like for this account", \  "Name": "Account Name", \ 
 "Description": "(Optional) Account Description", \ 
 "Timezone": "(Optional) Timezone for the account, IANA time zone database format.", \  }' 'https://api.cyclr.com/v1.0/accounts'

See how to Create an Account for more details.

2. Install a Template as a new Cycle #

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -- header 'X-Cyclr-Account: ACCOUNT ID FROM PREVIOUS STEP' -d '{ \  }' 'https://api.cyclr.com/v1.0/templates/TEMPLATE-ID/install'

Depending on the template being installed, there may be more to specify in this call, but this is the minimum.

See Installing a Template for more details.

3. Authenticate a Connector (using OAuth) #

3a. Get a Sign-in Token #

curl -X POST --header 'Content-Type: application/json' --header 'Accept:  application/json' -d '{ \
"Username": "string" \ 
 }' 'https://api.cyclr.com/v1.0/accounts/ACCOUNT ID FROM STEP 1/signintoken'

3b. Update Connector Authentication #

curl --request POST \
  --url 'https://YOUR-SERVICE-DOMAIN/connectorauth/updateaccountconnectoroauth?id=ACCOUNT CONNECTOR ID FROM STEP 2&token=TOKEN-FROM-STEP-3a&targetOrigin=https://www.mydomain.com/completionPage'

Your Service Domain can be found by visiting General Settings in your Cyclr console.

It usually has a format matching one of the following:

  • mycompany-h.cyclr.com
  • mycompany-h.eu.cyclr.com
  • mycompany-h.cyclr.uk

targetOrigin should be either the origin of another browser window for the JavaScript callback event to be dispatched to, or a URL to redirect the user to.

For more on authenticating Connectors, see these articles:

4. Set Step Field Mapping #

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'X-Cyclr-Account: ACCOUNT ID FROM STEP 1' -d '{ \ 
     "Field": { \ 
         "Id": 0 \ 
     }, \ 
     "MappingType": "StaticValue", \ 
     "Value": "string" \ 
 }' 'https://api.cyclr.com/v1.0/steps/STEP-ID-FROM-STEP-2/fieldmappings/FIELD-ID-FROM-STEP-2'

See Field Mapping for more details.

5. Start the Cycle #

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -- header 'X-Cyclr-Account: Account ID' -d '{ \ 
 "StartTime": "2021-12-07T09:17:50.888Z", \ 
 "Interval": 0, \ 
 "RunOnce": true \ 
 }' 'https://api.cyclr.com/v1.0/cycles/Cycle ID/activate'

See Cycle Activation for more details.