> For the complete documentation index, see [llms.txt](https://docs.stacksync.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stacksync.com/developers/getting-started-with-stacksync-cli/build-your-first-workflow-connector.md).

# Build your first workflow connector

In this guide, you will create, develop, test, and deploy a Workflow Connector using the project generated by the Stacksync CLI.

Each project includes a `guide/` directory that documents the project structure and connector development model. You can follow these guides directly or provide them as context to an AI coding assistant.

### :sparkles: Build with an AI coding assistant

<details>

<summary>Paste this prompt into your AI coding assistant to build a Stacksync Workflow Connector.</summary>

```
Stacksync is an integration platform with a workflow automation tool. Builders can use the Stacksync Connector Development Kit (CDK) to create new Stacksync Workflow Connectors.
Every connector enables to connect to a system and can have several triggers or actions called modules. One connector has one or more modules. Each module has inputs and outputs. Modules are used in a workflow to automate tasks. Once the connector is built, the user can use the Stacksync workflow builder UI to create workflows that automate tasks between different applications.

Requirements:
- Application: <application name> // ask the user for the application name if not provided.
- Operations: <operations the connector must support> // ask the user or define this from web search if the user does not know.
- API documentation: <optional official documentation URL> // can be found via web search
- Additional requirements: <optional constraints>

Follow this process:

1. Search the Stacksync documentation at https://docs.stacksync.com/developers/getting-started-with-stacksync-cli/overview and the other links available from this page. Explore thoroughly the Stacksync CLI and CDK documentation to understand how to create a connector and modules.

2. Research the application for which a connector should be built using its official API documentation. Determine the authentication method, base URL, required permissions, relevant endpoints, request and response schemas, pagination, and rate limits.

3. Check if the Stacksync CLI is already installed by running `stacksync --version`. If not, install it using the following command:

   curl -fsSL https://cli.stacksync.com/install.sh | sh

4. Check if the user is authenticated with Stacksync by running `stacksync login`. If not, authenticate using the following command (the login will ask the user to connect via the web (or API token connection option is available) and to choose which Stacksync workspace to use):

   stacksync login

5. Create the connector and enter the generated project:

   stacksync workflow-connector create "<Application Name>"
   cd <generated-project-directory>

6. Read the entire guide/ directory before changing any files.

   Treat the guide/ directory as the source of truth for the project structure, CDK usage, connector architecture, module implementation, credentials, inputs, outputs, errors, and testing. Follow it exactly.

7. Update stacksync.yml with the correct connector metadata.

8. Implement the requested operations. Create additional modules when required:

   stacksync workflow-module create "<Module Name>"

   Keep generic_api_credentials as the connection type until the user provides the application-specific connection type. To create a generic_api_credentials connection, the user has to go in the UI > connections > create connection > generic_api_credentials. The user will need to provide the API key or the information to connect to the system vua the API depending on the authentication method of the application.

9. Start the connector locally:

   stacksync workflow-connector run

   // Once the connector is running, the modules will become available to use in the Stacksync workflow builder UI. Tell the user they can refresh the workflow builder UI to see the new module appearing in the list of available modules.

10. Instruct the user on how to test each module in the Stacksync workflow builder.

11. Stop after local testing. Do not deploy unless the user explicitly asks.

Ask only for information that cannot be determined from the official API documentation or the project guides. Do not invent endpoints, schemas, credentials, connection types, or tenant-specific values.
If the user is just exploring and does not know which system they want to build a connector for, suggest the user to create a connector for a popular application such as Salesforce or Postgres.
```

</details>

### Prerequisites

* Stacksync CLI installed and authenticated
* Python 3.10 or later

See [**Getting Started**](/developers/getting-started-with-stacksync-cli/quickstart.md) for installation and authentication instructions.

### 1. Create the Connector

Create a new Workflow Connector project:

```bash
stacksync workflow-connector create "My App"
```

Move into the generated directory:

```bash
cd workflows-app-my-app
```

### 2. Create a Module

The generated project includes a sample module named `create_records` under `modules/`, providing a working reference implementation.

You can modify the sample module or create a new one:

```bash
stacksync workflow-module create "Create Contact"
```

Remove the sample module when it is no longer required:

```bash
stacksync workflow-module delete "create_records"
```

A module defines a capability exposed by the connector in the workflow builder.

### 3. Develop the Module

The `guide/` directory explains how to:

* Define inputs
* Load dynamic options
* Access connection credentials
* Implement execution logic
* Return outputs and errors

You can develop the module directly or with an AI coding assistant.

#### Using an AI Coding Assistant

Open the project in an AI-enabled editor and instruct the assistant to review the `guide/` directory before making changes.

Describe:

* The application or API to integrate
* The operation the module should perform
* The required inputs
* The expected output
* The authentication method

The included guides provide the implementation context required to follow Stacksync conventions.

#### Developing Directly

Review the `guide/` directory and follow the instructions for each component of the module.

### 4. Run and Test

Start the connector locally:

```bash
stacksync workflow-connector run
```

Then test it from your Stacksync workspace:

1. Create or open a workflow.
2. Add an **Action** node.
3. Select the your connector and module from the list of moudles.
4. Configure the inputs and run the node.

While the local process is running, workflow requests execute against the code on your machine. Saved changes are applied immediately.

Press **Ctrl+C** to stop the process.

### 5. Deploy

Deploy the connector to your workspace:

```bash
stacksync workflow-connector deploy
```

After deployment, the connector is available in your workspace and can be used in workflows.