Cyclr Community
  • Forums
  • Tutorials
  • Documentation
    • User Documentation
    • Connector Guides
  • Resources
    • New Features
    • Blog
    • Changelog
    • Support Portal
    • Newsletter Archive
    Sign in
    Cyclr Logo
    Cyclr Logo
    • Forums
    • Tutorials
    • Documentation
      • User Documentation
      • Connector Guides
    • Resources
      • New Features
      • Blog
      • Changelog
      • Support Portal
      • Newsletter Archive

    About Cyclr

    6
    • Introduction to Cyclr
    • Minimum requirements
    • Glossary
    • Errors
    • IP Allow List
    • Legal notices

    Cyclr Console

    14
    • Partner Console Dashboard
    • The Builder
    • Reports
    • Console Configuration
    • General Settings
    • Notifications
    • Embedding Customization
    • Security settings
    • Data retention settings
    • Custom Service Domains
    • Handle transaction errors
    • Payload Size Limitations
    • Performance tips
    • GitHub Integration

    Connectors

    33
    • Introduction to Connectors
    • Connectivity Comparison
    • Connector Guides
    • Application Connectors
      • Introduction to Application Connectors
    • Utility Connectors
      • Introduction to Utility Connectors
      • Counter Storage
      • Cross Updating Preventer
      • Data Tools
      • Entity Cross Ref Storage
      • Generic File
      • Generic File Downloader
      • Generic Form
      • Generic Webhook
      • Data Storage
        • Introduction to Data Storage Connectors
        • Global Data Storage
        • Global Object Storage
        • Cycle Data Storage
        • Cycle Object Storage
    • Custom Connectors
      • Introduction to Custom Connectors
      • Methods
      • Triggers
      • Last Successful Run Date
      • Parameters
      • Scripting
      • Data Types
      • Paging
      • Custom Objects
      • Dynamic Custom Fields
      • Automatically Install Webhooks
      • Connector Standards
      • Settings
      • Authentication
      • Rate Limits

    Templates

    17
    • Introduction to Templates
    • Template Settings
    • Create a Template
    • Tools
    • Connectivity Tools
    • Map fields
    • Add custom fields
    • Custom Object Method Categories
    • Test Scripts
    • Collection splitting
    • Pass data between two steps
    • Test a template
    • Template versioning
    • Introduction to Cycles
    • Stop a cycle
    • Copy Cycles as Templates
    • Import or Export Templates

    Accounts

    5
    • Introduction to Accounts
    • Account Users
    • Sub Accounts
    • Connector Authentication Link
    • Export or Import Cycles

    Embedding

    17
    • Introduction to Embedding
    • ORBIT
    • Installing a Partner Connector
    • Embed Cyclr in an iFrame
    • Launch
      • Introduction to Launch
      • User Experience
      • Customize Appearance
      • Build Compatible Templates
      • Handle LAUNCH callbacks
      • Deploy LAUNCH
    • Marketplace
      • Introduction to Marketplace
      • Set up a Marketplace
      • Styling Marketplace
      • Deploying a Marketplace
      • Marketplace Callback
      • Marketplace Webhook Callback
      • Marketplace Settings

    API

    19
    • Introduction to the Cyclr API
    • Authentication
    • Authorize Account API calls
    • Install Connectors into an Account
    • Install a Cycle from a Template
    • Step Setup
    • Activate a Cycle
    • Install Connectors
    • Create an Account
    • API Example Walkthrough
    • Connector Authentication
      • Introduction to Connector Authentication
      • API Key Authentication
      • HTTP Basic Authentication
      • OAuth Authentication
    • Data on Demand
      • Introduction to Data on Demand
      • Get Account Connectors
      • Get Connector Methods
      • Call a Connector Method
      • IP Restriction

    Release Notes

    28
    • Introduction to Release Notes
    • 2025
      • 2025-06
      • 2025-05
      • 2025-04
      • 2025-03
      • 2025-02
      • 2025-01
    • 2024
      • 2024-12
      • 2024-11
      • 2024-10
      • 2024-09
      • 2024-08
      • 2024-07
      • 2024-06
      • 2024-05
      • 2024-04
      • 2024-03
      • 2024-02
      • 2024-01
    • 2023
      • 2023-12
      • 2023-11
      • 2023-10
      • 2023-06
      • 2023-05
      • 2023-04
    • Archive
      • Archive
      • 2022
      • 2021
    View Categories
    • Home
    • Documentation
    • API
    • Step Setup

    Step Setup

    7 min read

    The articles in this section describe how to use the Cyclr API to set the different mapping options available on a step.

    You must already have a Cyclr API Access Token.

    Mappings Overview #

    When setting a mapping on a Step through the Cyclr API, you will need to identify whether you’re mapping to a Parameter or a Field.

    You can do this by retrieving a Step using one of these endpoints:

    • GET /v1.0/cycles/{id}/steps
    • GET /v1.0/cycles/{id}/steps/{stepId}

    The Responses from those endpoints include a Method property which contains details of the Connector Method used by the Step.

    You can then check witin the Method property’s Parameters and RequestFields for the particular item you wish to map to:

    • If it’s within the Parameters property, it’s a Parameter and can be modified using /v1.0/steps/{id}/parameters endpoints.
    • If it’s within the RequestFields property, it’s a Field and can be modified using /v1.0/steps/{id}/fieldmappings endpoints

    Using an ID of the wrong type with these endpoints will return an error.

    Step Prerequisites #

    Templates in Cyclr may include steps that require mapping or parameter values that are specific to your end user’s use of those templates.

    If the Cycle prerequisites method returned Steps that required mapping, you need to loop through them to determine what is required.

    Request:

    GET /steps/{Step ID}/prerequisites
    Authorization Bearer ********************
    X-Cyclr-Account: 00000000-0000-0000-0000-000000000000

    Response:

        [{
                "ReasonCode": 40,
                "Reason": "Missing parameter mapping",
                "ObjectType": "Parameter",
                "ObjectId": 16017
            },
            {
                "ReasonCode": 41,
                "Reason": "Missing field mapping",
                "ObjectType": "ConnectorFieldMapping",
                "ObjectId": 283792
            },
            {
                "ReasonCode": 41,
                "Reason": "Missing field mapping",
                "ObjectType": "ConnectorFieldMapping",
                "ObjectId": 283793
            },
            {
                "ReasonCode": 41,
                "Reason": "Missing field mapping",
                "ObjectType": "ConnectorFieldMapping",
                "ObjectId": 283794
            },
            {
                "ReasonCode": 41,
                "Reason": "Missing field mapping",
                "ObjectType": "ConnectorFieldMapping",
                "ObjectId": 283795
            },
            {
                "ReasonCode": 41,
                "Reason": "Missing field mapping",
                "ObjectType": "ConnectorFieldMapping",
                "ObjectId": 283796
            }
        ]
    

    Map Parameters #

    Step Parameters are passed as a header or part of the URL (hostname, path, or query string parameters) to the third party API endpoint.

    Get Parameter details #

    For each missing Parameter Mapping returned by the step prerequisites request:

    Request:

        GET /v1.0/steps/{Step ID}/parameters/{Parameter ID}
        Authorization Bearer ********************
        X-Cyclr-Account: 00000000-0000-0000-0000-000000000000

    Response:

        {
            "Parameter": {
                "Id": 16017,
                "Name": "List ID",
                "Description": "Select a List.",
                "IsOptional": false,
                "DataType": "Undefined",
                "TriggerName": "Lookup List",
                "Values": [],
                "DisplayOrder": 1,
                "Triggers": [{
                    "AccountConnectorId": 36329,
                    "MethodId": 36666,
                    "Name": "Lookup List",
                    "HumanReadableKey": "[lists].name",
                    "IdentifierKey": "[lists].id",
                    "SubTriggers": [],
                    "EntityId": 16017
                }]
            },
            "IsEntityIdentifier": false,
            "MappingType": null,
            "SourceFieldId": null,
            "SourceStepId": null,
            "TriggerValue": null,
            "TriggerValueDisplayName": null,
            "Value": null
        }

    In the example above, the Triggers array provides directions as to the source of valid values.

    In this example the method 36666 of Account Connector 36329 should be called, with the [lists].name values presented to the user for selection and the [lists].id value used as the actual parameter value.

    Retrieve Values #

    Values can be retrieved from the trigger by calling the identified trigger method as below:

    Request:

    GET /v1.0/account/connectors/36329/methods/36666
    Authorization Bearer ********************
    X-Cyclr-Account: 00000000-0000-0000-0000-000000000000

    Response:

        {
            "lists": [{
                "id": "a78f86e7d7",
                "web_id": 227621,
                "name": "Newsletter Subscribers",
                "contact": {
                    "company": "Acme Inc",
                    "address1": "1 Commercial Road",
                    "address2": "",
                    "city": "Eastbourne",
                    "state": "East Sussex",
                    "zip": "BN21 3XQ",
                    "country": "GB",
                    "phone": "+44 (0)330 354 2525"
                },
                "permission_reminder": "You are receiving this email as a subscriber to our regular newsletters. If you unsubscribe you will miss important news and announcements.",
                "use_archive_bar": true,
                "campaign_defaults": {
                    "from_name": "Acme Inc",
                    "from_email": "news@acmeinc.com",
                    "subject": "",
                    "language": "en"
                },
                "notify_on_subscribe": "hello@cyclr.com",
                "notify_on_unsubscribe": "hello@cyclr.com",
                "date_created": "2016-08-22T09:46:58+00:00",
                "list_rating": 0,
                "email_type_option": false,
                "subscribe_url_short": "http://eepurl.com/ABC123",
                "subscribe_url_long": "https://cyclr.us5.list-manage.com/subscribe?u=534685638659&id=84378947",
                "beamer_address": "us5-f578sd58f-cb2bd1adc8@inbound.mailchimp.com",
                "visibility": "pub",
                "modules": [],
                "stats": {
                    "member_count": 723,
                    "unsubscribe_count": 12,
                    "cleaned_count": 0,
                    "member_count_since_send": 2,
                    "unsubscribe_count_since_send": 0,
                    "cleaned_count_since_send": 0,
                    "campaign_count": 2,
                    "campaign_last_sent": "",
                    "merge_field_count": 2,
                    "avg_sub_rate": 0,
                    "avg_unsub_rate": 0,
                    "target_sub_rate": 0,
                    "open_rate": 100,
                    "click_rate": 100,
                    "last_sub_date": "2016-08-22T11:36:09+00:00",
                    "last_unsub_date": ""
                },
                "_links": []
            }]
        }
    

    This response can then be used to present the user with valid options.

    In this example there is a single value to present to the user, Newsletter Subscribers, with a corresponding value to pass to Cyclr as the parameter value a78f86e7d7.

    Step Setup Map fields #

    Field Mappings are passed to the third party API as the request body.

    For each missing field mapping returned in the Step prerequisites:

    Request:

    GET /v1.0/steps/{Step ID}/fieldmappings/{Field ID}
    Authorization Bearer ********************
    X-Cyclr-Account: 00000000-0000-0000-0000-000000000000

    Response:

        {
            "Field": {
                "Id": 283792,
                "Name": "Email",
                "Description": null,
                "IsOptional": false,
                "DataType": "Undefined",
                "TriggerName": null,
                "Values": [],
                "DisplayOrder": 1,
                "Triggers": []
            },
            "MappingType": "Ignore",
            "SourceFieldId": null,
            "SourceStepId": null,
            "TriggerValue": null,
            "TriggerValueDisplayName": null,
            "Value": null
        }

    The IsOptional property indicates if a field mapping is optional or required before the Cycle can run.

    There are multiple ways of setting a Field Mapping value.

    Map Fields with static values #

    A static value can be set as the field mapping, a static value is a value that will never change.

    This value should be obtained from your user, or automatically assigned by your application, then provided to Cyclr as below:

    Request:

    PUT /v1.0/steps/{Step ID}/fieldmappings/{Field ID}
    Authorization Bearer ********************
    X-Cyclr-Account: 00000000-0000-0000-0000-000000000000
    
    {
      "MappingType": "StaticValue",
      "Value": "MyStaticValue"
    }

    Response:

        {
          "Field": {
            "Id": 283792,
            "Name": "Email",
            "Description": null,
            "IsOptional": false,
            "DataType": undefined,
            "TriggerName": null,
            "Values": [],
            "DisplayOrder": 1,
            "Triggers": []
          },
          "MappingType": "StaticValue",
          "SourceFieldId": null,
          "SourceStepId": null,
          "TriggerValue": null,
          "TriggerValueDisplayName": null,
          "Value": "MyStaticValue"
        }

    Map Fields with Step data #

    A Step Data mapping uses a value from a previous step response as the value for this steps request.

    Cyclr provides an endpoint to discover valid field mapping options for a given step.

    Request:

    GET /v1.0/steps/{Step ID}/fieldsformapping
    Authorization Bearer ********************
    X-Cyclr-Account: 00000000-0000-0000-0000-000000000000

    Response:

        [{
                "Id": 283797,
                "Name": "Member ID",
                "Description": null,
                "IsOptional": false,
                "DataType": "Undefined",
                "TriggerName": null,
                "Values": null,
                "DisplayOrder": 0,
                "Triggers": []
            },
            {
                "Id": 283798,
                "Name": "Email",
                "Description": null,
                "IsOptional": false,
                "DataType": "Undefined",
                "TriggerName": null,
                "Values": null,
                "DisplayOrder": 0,
                "Triggers": []
            },
            {
                "Id": 283799,
                "Name": "Status",
                "Description": null,
                "IsOptional": false,
                "DataType": "Undefined",
                "TriggerName": null,
                "Values": null,
                "DisplayOrder": 0,
                "Triggers": []
            },
            {
                "Id": 283800,
                "Name": "Average Open Rate",
                "Description": null,
                "IsOptional": false,
                "DataType": "Undefined",
                "TriggerName": null,
                "Values": null,
                "DisplayOrder": 0,
                "Triggers": []
            },
            {
                "Id": 283801,
                "Name": "Average Click Rate",
                "Description": null,
                "IsOptional": false,
                "DataType": "Undefined",
                "TriggerName": null,
                "Values": null,
                "DisplayOrder": 0,
                "Triggers": []
            },
            {
                "Id": 283802,
                "Name": "Member Rating",
                "Description": null,
                "IsOptional": false,
                "DataType": "Undefined",
                "TriggerName": null,
                "Values": null,
                "DisplayOrder": 0,
                "Triggers": []
            },
            {
                "Id": 283803,
                "Name": "Language",
                "Description": null,
                "IsOptional": false,
                "DataType": "Undefined",
                "TriggerName": null,
                "Values": null,
                "DisplayOrder": 0,
                "Triggers": []
            },
            {
                "Id": 283804,
                "Name": "Unique Email ID",
                "Description": null,
                "IsOptional": false,
                "DataType": "Text",
                "TriggerName": null,
                "Values": null,
                "DisplayOrder": 0,
                "Triggers": []
            },
            {
                "Id": 283805,
                "Name": "Email Type",
                "Description": null,
                "IsOptional": false,
                "DataType": "Text",
                "TriggerName": null,
                "Values": null,
                "DisplayOrder": 0,
                "Triggers": []
            },
            {
                "Id": 283806,
                "Name": "IP Signup Address",
                "Description": null,
                "IsOptional": false,
                "DataType": "Text",
                "TriggerName": null,
                "Values": null,
                "DisplayOrder": 0,
                "Triggers": []
            },
            {
                "Id": 283807,
                "Name": "Signup Timestamp",
                "Description": null,
                "IsOptional": false,
                "DataType": "DateTime",
                "TriggerName": null,
                "Values": null,
                "DisplayOrder": 0,
                "Triggers": []
            },
            {
                "Id": 283808,
                "Name": "Opt-In Timestamp",
                "Description": null,
                "IsOptional": false,
                "DataType": "DateTime",
                "TriggerName": null,
                "Values": null,
                "DisplayOrder": 0,
                "Triggers": []
            },
            {
                "Id": 283809,
                "Name": "List ID",
                "Description": null,
                "IsOptional": false,
                "DataType": "Text",
                "TriggerName": null,
                "Values": null,
                "DisplayOrder": 0,
                "Triggers": []
            },
            {
                "Id": 283810,
                "Name": "Opt-In IP",
                "Description": null,
                "IsOptional": false,
                "DataType": "Text",
                "TriggerName": null,
                "Values": null,
                "DisplayOrder": 0,
                "Triggers": []
            }
        ]
    

    Map Fields from a list of values #

    Fields within a step may contain a set of pre-defined values that can be selected from, returned in the “Values” array below:

    Get field values #

    Request:

    GET /v1.0/steps/{Step ID}/fieldmappings/{Field ID}
    Authorization Bearer ********************
    X-Cyclr-Account: 00000000-0000-0000-0000-000000000000

    Response:

        {
          "Field": {
            "Id": 283792,
            "Name": "Email",
            "Description": null,
            "IsOptional": false,
            "DataType": "Undefined",
            "TriggerName": null,
            "Values": [
              "List Option 1",
              "List Option 2",
              "List Option 3"
            ],
            "DisplayOrder": 1,
            "Triggers": []
          },
          "MappingType": "Ignore",
          "SourceFieldId": null,
          "SourceStepId": null,
          "TriggerValue": null,
          "TriggerValueDisplayName": null,
          "Value": null
        }

    Update Field values #

    For these steps, the list of valid values should be presented to your user for them to make a selection. Their selection should then be used to update the field value.

    Request:

    POST /v1.0/steps/{Step ID}/fieldmappings/{Field ID} 
    Authorization Bearer ********************
    X-Cyclr-Account: 00000000-0000-0000-0000-000000000000
    
    {
        "MappingType": "ValueList",
        "Value": "List Option 1"
    }

    Response:

        {
          "Field": {
            "Id": 283792,
            "Name": "Email",
            "Description": null,
            "IsOptional": false,
            "DataType": undefined,
            "TriggerName": null,
            "Values": [],
            "DisplayOrder": 1,
            "Triggers": []
          },
          "MappingType": "ValueList",
          "SourceFieldId": null,
          "SourceStepId": null,
          "TriggerValue": null,
          "TriggerValueDisplayName": null,
          "Value": "List Option 1" 
        }

    Share This Article :
    • Facebook
    • X
    • LinkedIn
    • Pinterest
    Install a Cycle from a TemplateActivate a Cycle
    Page Contents
    • Mappings Overview
    • Step Prerequisites
    • Map Parameters
      • Get Parameter details
      • Retrieve Values
    • Step Setup Map fields
    • Map Fields with static values
    • Map Fields with Step data
    • Map Fields from a list of values
      • Get field values
      • Update Field values

    Company

    • Company
    • About Us
    • Security and Compliance
    • Pricing
    • Blog
    • Branding
    • Embedded iPaaS

    Legal

    • Website Terms
    • Privacy Policy
    • Terms and Conditions
    • Data Protection Agreement
    • SLA
    • GDPR

    UK Office

    +44 (0) 3300 102 525

    US Office

    +1 (646) 585-2525


    White labelled API integration framework for creating & managing in-app SaaS integrations.

    © 2025 Cyclr. All rights reserved.