# Adding a new endpoint

## Introduction

Before a connector can be used (i.e. before [instances of it can be added](https://doc.wearepatchworks.com/product-documentation/connectors-and-instances/working-with-instances/adding-an-instance) for use in [process flows](https://doc.wearepatchworks.com/product-documentation/process-flows/about-process-flows)) you must add at least one **endpoint**. The steps and settings required will vary depending on which type of endpoint you're adding, and how you want it to behave - general steps can be found below.  

{% hint style="info" %}
The steps detailed on this page show how to create an endpoint from first principles. However for speed, it's usually more efficient to clone an existing endpoint and then make required configuration changes. The **clone** option is available from the endpoints list:\
\
![](https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FCMNTNoGlFIeAZIU7NStP%2Fclone%20endpoint.png?alt=media\&token=3540c3ec-6fab-4488-b20d-15cfd1dbc487)<br>
{% endhint %}

**Step 1** \
Click the **add new endpoint** button:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FtitNWkNL3qAVSwdSCTsh%2Fadd%20endpoint%201.png?alt=media&#x26;token=9286a336-deb2-4f1e-b544-161a3f963776" alt=""><figcaption></figcaption></figure></div>

**Step 2** \
You're prompted to enter a **name**, and to select an **entity type**:

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2Fpt4mFNDZ3dcpwZTuo5Vv%2Fadd%20endpoint%202.png?alt=media&#x26;token=975d321d-62ce-465a-9f9e-7d4502d749a3" alt=""><figcaption></figcaption></figure>

...enter a **name** for this endpoint and select the appropriate **entity type** from the dropdown list:

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FHucbcXZg6uCeQl3FKATP%2Fadd%20endpoint%204.png?alt=media&#x26;token=3748be27-2a16-483f-85d3-724ef6ac0e2d" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
The **name** is displayed to users when configuring [connection shape](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape)s in [process flows](https://doc.wearepatchworks.com/product-documentation/process-flows/about-process-flows), so it's advisable to be as clear as possible about what this endpoint does. For example, an endpoint defined to retrieve all products might be named: '*List all products*'. &#x20;

The **entity type** is used to organise endpoints whenever they are displayed to users in process flows.
{% endhint %}

**Step 3** \
Click the **create** button. Basic details are saved and the manage endpoint page is displayed:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FwxKeIy2McljnIuHCeIxe%2Fadd%20endpoint%205.png?alt=media&#x26;token=b5b2f5c9-7aaa-4866-9248-189893a0ddbc" alt=""><figcaption></figcaption></figure></div>

This page is split into upper and lower panes - **endpoint details** at the top and **endpoint setup** in the lower panel.

**Step 4** \
In the top **endpoint details** panel, use dropdown options to set the **direction** as required:

<div align="left"><figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FyPSjv8oE102KOKA5E0Vb%2Fadd%20endpoint%206.png?alt=media&#x26;token=fa0adebb-0ebc-4e6f-93a0-15309839c93d" alt=""><figcaption></figcaption></figure></div>

This determines the direction that data associated with this endpoint will flow:

* Choose **receive** if you will be pulling (i.e. receiving) data for this endpoint - typically these endpoints are associated with a GET http method.
* Choose **send** if you will be pushing (i.e. sending) data to this this endpoint - typically these endpoints are associated with PUT, POST, PATCH or DELETE http methods.

**Step 5**\
Use the lower **endpoint setup** panel to update [configuration options](#configuring-an-endpoint) as required for the new endpoint - options are available over a series of 'metro stop' tabs: &#x20;

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FKvXT0yY7AAHsVh1KfolD%2Fadd%20endpoint%203.png?alt=media&#x26;token=ad84dcbb-5b55-4b91-95af-c092db2190aa" alt=""><figcaption></figcaption></figure>

These  [configuration options](#configuring-an-endpoint) determine the experience your users will have when they choose to add a [connection shape](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/connector-shape) to a [process flow](https://doc.wearepatchworks.com/product-documentation/process-flows/about-process-flows) and associate it with an **instance** of this connector, using this endpoint.&#x20;

**Step 6** \
Having completed all required configuration for this authentication method, click **next** to complete the setup. Your new connector is now available in the [Patchworks marketplace](https://doc.wearepatchworks.com/product-documentation/marketplace/the-patchworks-marketplace), so users **associated with your company profile** can add [instances](https://doc.wearepatchworks.com/product-documentation/connectors-and-instances/working-with-instances) of it. &#x20;

## Configuring an endpoint

For any **endpoint**, the following options are available:

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F0ma9PYS0afgonFUJSb3a%2F1.png?alt=media&#x26;token=803a691a-0e98-4e6f-aa95-0ae793f8d562" alt="" data-size="line"> Authentication</summary>

Choose which [defined authentication methods](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/3-authentication-methods/authentication-method-options) apply for this endpoint. &#x20;

For more information about working with **authentication** settings, please see the [Authentication](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints/endpoint-options/authentication) page.&#x20;

</details>

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F83qvL3DjjvsmiVUYlQiQ%2F2.png?alt=media&#x26;token=dc06fd43-5913-462a-b256-101b3f76867e" alt="" data-size="line"> Endpoint variables</summary>

Endpoint variables are the lowest level of vasriable that you can add - any variables added here are only applicable for the associated endpoint.

For more information about working with these **variables**, please see the [Endpoint variables](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints/endpoint-options/endpoint-variables) page.&#x20;

</details>

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FVCQL42m29ZL1W1x3Q9aW%2F3.png?alt=media&#x26;token=7b70814f-ab70-4b5f-9cae-65c9dcf89da7" alt="" data-size="line"> URL</summary>

Define the HTTP method and URL for authentication, and any required **URL parameters**. You can define **default** parameters which are always applied to requests, and **optional** filters which your users can define when working with this endpoint in [process flows](https://doc.wearepatchworks.com/product-documentation/process-flows/about-process-flows).

For more information about working with **URL parameters**, please see the [URL](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints/endpoint-options/url) page.&#x20;

</details>

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2Fj27NPzQQFoRlKRDAmmsj%2F4.png?alt=media&#x26;token=482820e7-110b-4469-9da4-88339e687f6c" alt="" data-size="line"> Header</summary>

Any variables that need to be passed in endpoint request header should be added here, as per the [API documentation for the underlying third-party application](#user-content-fn-1)[^1]. &#x20;

For more information about working with **headers**, please see the [Header](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints/endpoint-options/header) page.&#x20;

</details>

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FxWO0mmwxJfEEmqcJZvM9%2F5.png?alt=media&#x26;token=72398fcd-7d39-4a4b-b718-36792c786dec" alt="" data-size="line"> Body</summary>

Any variables that need to be passed in the endpoint request body should be added here (typically used for creating or updating resources - i.e. for POST, PUT, PATCH and DELETE requests. &#x20;

For more information about working with **body** parameters, please see the [Body](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints/endpoint-options/body) page.&#x20;

</details>

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FPCaiaYtOfqGTkWgIFzrF%2F6.png?alt=media&#x26;token=2a400a71-222a-4a79-b3e3-59e4d3eb958d" alt="" data-size="line"> Pagination</summary>

Some APIs include pagination functionality so that large HTTP responses can be served in multiple pages, which are more manageable - different APIs use different methods to approach this.&#x20;

For more information please see the [Pagination](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints/endpoint-options/pagination) page.&#x20;

</details>

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F4rSuY2TCJ3a0mHWqbNty%2F7.png?alt=media&#x26;token=db3c692b-1fac-4088-a668-7e5b604eae6d" alt="" data-size="line"> Schema / Taxonomy</summary>

Add a schema for this endpoint, so Patchworks knows what data structure to expect and which fields to make available for [mapping](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/map-shape) instances of this connector in [process flows](https://doc.wearepatchworks.com/product-documentation/process-flows/about-process-flows). &#x20;

Field names used in data schemas can be quite random and overly complex - this is fine if you know the schema and you're the only company ever likely to install the associated connector...but if you think that you might want to share your connector with other Patchworks customers in future, then **field tagging** is really important.

For more information, please see the [Schema / taxonomy](https://doc.wearepatchworks.com/product-documentation/developer-hub/connector-builder/building-your-own-connector/4-endpoints/endpoint-options/schema-taxonomy) page.&#x20;

</details>

[^1]: ![](https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F7ebRB4tRIozWxpBMCAoN%2Ficons8-google-docs-20.svg?alt=media\&token=ac61da4e-764c-452c-b9b5-d65f188769c9) You should be able to confirm this information in the API documentation for the underlying third-party application.&#x20;