# Working with parameters

## About parameters

Parameters can be defined throughout the connector builder, in:

* [Authentication method URL parameters](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/authentication-method-options/url-parameters)
* [Authentication method headers](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/authentication-method-options/header)
* [Authentication method body](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/authentication-method-options/body)
* [Endpoint URL parameters](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints/endpoint-options/url)
* [Endpoint headers](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints/endpoint-options/header)
* [Endpoint body](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints/endpoint-options/body)

When a [process flow](https://doc.wearepatchworks.com/product-documentation/process-flows/about-process-flows) runs, any associated API requests are injected with given variable values wherever a corresponding `{{key}}` is found - this is Irrespective of where parameters are defined 

{% hint style="info" %}
All parameters specified in connector builder API requests must be placed within double-curly brackets - for example: `{{store_name}}`.
{% endhint %}

## Optional vs default parameters

Depending on where you are in the connector builder, you will encounter both [default](#default-parameters) and [optional](#optional-parameters) parameters, where:

* [Default](#default-parameters-key-pairs) parameters are always applied to API requests, whenever it is used.  
* [Optional](#optional-parameters) parameters are those that users can choose to apply with their own values - either when adding connector instances (in the case of parameters defined for [authentication methods](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/authentication-method-options)) or as filter parameters when configuring [connection shapes](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape) for [process flows](https://doc.wearepatchworks.com/product-documentation/process-flows/about-process-flows).  

Irrespective of where parameters are defined, any associated API requests are injected with given default and optional parameter values wherever a corresponding `{{key}}` is found.

In some places, you can only add [default variables](#default-parameters-key-pairs), but in others you can add both types. In this case, the variables page is split into two panels - for example:

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FQQ8UHOSKqcaFTZqSrn4N%2Ftwo%20panels.png?alt=media&#x26;token=c453d7af-5fba-4bfa-9e52-bbf1c7be2d59" alt=""><figcaption></figcaption></figure>

[Default](#default-parameters) parameters are defined in the top panel, with [optional](#optional-parameters) parameters in the lower panel. The sections below explain the use of these parameters in general terms - for specific guidance in a particular context, please use the links provided [above](#about-parameters).

## Default parameters

**Default** parameters are those which must always be passed into the request **URL**, **header**, or **body** using values that you specify as part of the configuration. They are added as key pairs:

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FiaY4VGmukX9UcPvFLX6X%2Fheader%20endpoint%20-%20add%20default.png?alt=media&#x26;token=d86cdf76-0a58-454c-8bc1-a1889039074b" alt=""><figcaption></figcaption></figure>

Defined values can be static or dynamic. Default parameters are passed straight into requests - users are never asked to provide values for these.

{% hint style="info" %}
There is one scenario where a user can influence the value of a default parameter. This is where you define a default parameter value as an endpoint {{variable}}. For an example scenario please see our [What if I want to force users to enter their required value for a URL parameter? ](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/4-endpoints/endpoint-options/url#what-if-i-want-to-force-users-to-enter-their-required-value-for-a-url-parameter)section.&#x20;
{% endhint %}

## Optional parameters

**Optional** parameters are those that you want to expose to your users in [process flows](https://doc.wearepatchworks.com/product-documentation/process-flows/about-process-flows), and then pass values that they provide into your API requests (via the **URL**, **header**, or **body**).&#x20;

Any optional parameters that you define are displayed as **filter parameters** for a [connection shape](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape) when a user selects the associated instance/endpoint. Essentially, you are defining filter options for users to apply in process flows. For example:

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2Fa8KlqjpTRJeDECFHqA2F%2Ffilter%20parameters.png?alt=media&#x26;token=d71e0549-88f7-4ed5-88a5-79480d7dbe11" alt=""><figcaption></figcaption></figure>

### Adding optional parameters

When you choose to add an optional parameter, you're prompted to complete the fields as below:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FL2Z39raEEw7SKRguH2lM%2Foptional%20parameters.png?alt=media&#x26;token=1ffd0abd-c53a-49bb-b99f-55cd96f7f1d0" alt="" width="563"><figcaption></figcaption></figure></div>

Use the following table as a guide for completing these fields:

<table><thead><tr><th width="338">Field</th><th>Summary</th></tr></thead><tbody><tr><td>Field</td><td>Enter a valid parameter field from the API documentation associated with the third-party application that you're building. </td></tr><tr><td>Select an operator</td><td>Operators determine how matching should be performed on the value given for this field (for example: <code>contains</code>, <code>equal to</code>, <code>greater than or equal to</code>, etc.).</td></tr><tr><td>Select a type</td><td>Choose the type of field that users will be prompted to update when they set this parameter in process flows. Available options are <code>string</code>, <code>number</code>, <code>specific date</code>, and <code>dynamic date</code>. For examples of these types, please see the <a href="#optional-parameter-type-examples">Optional parameter type examples</a> section below.</td></tr><tr><td>Value</td><td>Available value fields depend on your type selection above. For examples, please see the <a href="#optional-parameter-type-examples">Optional parameter type examples</a> section below.</td></tr></tbody></table>

### Optional parameter type examples

As noted above, the parameter type selected determines the user experience of updating this parameter (via [connection shapes](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape)) in [process flows](https://doc.wearepatchworks.com/product-documentation/process-flows/about-process-flows). Below is an example of each parameter type, so you can see the resulting behaviour in a process flow.

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FuKTXJEY34CVnak6PxrOz%2Fexample%20icon%202.svg?alt=media&#x26;token=7c8af2c5-9519-4757-bea9-172569a023bd" alt="" data-size="line"> String </summary>

When a parameter **type** is set to **string**, the user is prompted to add their required value in a single text field.

Below we have configured a 'Product Type' parameter with a **string** type:

![](https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2Fytuzfj66T8MG36gz0YNQ%2Fparameter%20type%20string%20-%20setup.png?alt=media\&token=633ee85c-bf87-48f7-b8d8-2f493aec37e3)

When a user adds an instance for this connector to a process flow and selects this endpoint, they will see a 'Product Type' parameter option, with a text field where they can enter a value:

![](https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FqV5gyLXcK7zO3qmbd1vt%2Fparameter%20type%20string%20-%20example.png?alt=media\&token=49c2a777-8893-4246-95d5-6fede261d13a)

</details>

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FuKTXJEY34CVnak6PxrOz%2Fexample%20icon%202.svg?alt=media&#x26;token=7c8af2c5-9519-4757-bea9-172569a023bd" alt="" data-size="line"> Number </summary>

When a parameter **type** is set to **number**, the user is prompted to add their required value in a single numeric field.

Below we have configured an 'Order Number' parameter with a **number** type:

![](https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F28i1Bn4sQkOfS5lV7203%2Fparameter%20type%20number%20-%20setup.png?alt=media\&token=61269ae7-f6f3-4767-baa6-2ddcfd174123)

When a user adds an instance for this connector to a process flow and selects this endpoint, they will see an 'Order Number' parameter option, with a text field where they can enter a value:

![](https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F8zXMUPnoZxeWdoUbBzIB%2Fparameter%20type%20number%20-%20example.png?alt=media\&token=dbb8d5b2-32aa-4860-b0d6-1d45c4f0ee9f)

</details>

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FuKTXJEY34CVnak6PxrOz%2Fexample%20icon%202.svg?alt=media&#x26;token=7c8af2c5-9519-4757-bea9-172569a023bd" alt="" data-size="line"> Dynamic date </summary>

When a parameter **type** is set to **dynamic date**, the user is prompted to provide a +/- number of seconds, minutes, hours, days, months, years to match on, relative to the current date.

Below we have configured a 'Date Created' parameter with a **dynamic date** type:

![](https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FOBaM1QALg6M5H1stZ5Er%2Fheader%20optional%20parameter%20in%20endpoint.png?alt=media\&token=a4b7677f-e89b-49a9-948b-fd99a950ef28)

When a user adds an instance for this connector to a process flow and selects this endpoint, they will see a 'Date Created' parameter option, with selectors to choose the required period:

![](https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F1M7FTCeaNkXN5UzevhnI%2Fheader%20optional%20parameter%20in%20flow%20b.png?alt=media\&token=6013200f-db73-423d-aa51-a85d4e2df34b)

</details>

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FuKTXJEY34CVnak6PxrOz%2Fexample%20icon%202.svg?alt=media&#x26;token=7c8af2c5-9519-4757-bea9-172569a023bd" alt="" data-size="line"> Specific date</summary>

When a parameter **type** is set to **specific date**, the user is prompted to select a specific date, using a date picker.

Below we have configured a 'created at' parameter with a **specific date** type:

![](https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FyLo96PZ8Hl6j1xNn5qMS%2Furl%20parameter%20-%20created%20at%20-%20config.png?alt=media\&token=75758437-9208-4a6f-b9ce-bdbc11dfd9d1)

When a user adds an instance for this connector to a process flow and selects this endpoint, they will see a 'Created At' parameter option, with selectors to choose a specific date:

![](https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FXDojFfNev1YSmBXjYwsK%2Furl%20parameter%20-%20created%20at%20-%20in%20flow.png?alt=media\&token=919b5bac-26e9-4758-807b-4e85c6a58cec)

</details>

## Updating & removing parameters

Having added a parameter, you can simply click its name to access details in edit mode - for example:

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FGSmSSVHWDKEGcd3MilY9%2Fremove%20param%200.png?alt=media&#x26;token=982ce206-f0d1-48b2-9384-a3e3e1372b4c" alt=""><figcaption></figcaption></figure>

From here, you can edit **key** and **value** fields, or choose the **delete** this entry - for example:

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2Fr6Cf5xj0P0E7KruQU0q1%2Fremove%20param.png?alt=media&#x26;token=8c68c20b-43cb-4f53-9ba6-1e70e4a1126b" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/techniques-for-working-with-variables-and-parameters/working-with-parameters.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.