# 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>