Adding an inbound API connector with a custom payload

Introduction

An Inbound API connector is added like any other Patchworks connector. However, extra steps are required to configure a custom entity for the custom payload.

Prerequisites

To add a custom entity for an API connector, you need a JSON file (or JSON content ready to copy/paste), containing the data structure that Patchworks should expect to receive.

Patchworks provide sample structures for products and orders, which you can download and update as required - or define your own from first principles. For services using ‘standard’ connectors, you can define filters to control what source data is processed (and what is ignored). However, filters are not available for API connectors. With custom payloads, you must ensure that your data is pre-filtered before it is sent to Patchworks, so you are only sending data that needs to be processed.

The steps

Follow the steps below to add a new Inbound API connector with a custom entity:

Step 1 Select connectors from the left-hand navigation menu:

Step 2 Click the Inbound API connector tile to access setup options:​

​

The Inbound API connector is available in both test and live environments, for clients on Professional or Enterprise plans.

Step 3 Select the settings tab:

​​

… default entities are displayed for orders and products:

​​

If required, you can download these sample payloads and adjust them as needed for your custom payload.

Step 4 Click the add custom entity button:

​​

… the manage entity page is displayed:

​​

Step 5 Click the entity type field:

​

...then select a type that best describes data that you will be sending in the custom payload - for example:

Step 6 Enter a name for this entity - this name is displayed for selections later, so ensure that it’s meaningful - for example:

Step 7 If your custom payload field data is available in a file, click the choose file button to browse for and select this file:

… alternatively, you can copy/paste a JSON object - for example:

Step 8 Check detected fields to ensure that recognised fields are as expected - for example:

… if you’re not satisfied with detected fields, click the cancel button, adjust the JSON content and try again - otherwise, click the save button to add the custom entity:

The Inbound API connector is now ready to use in a Patchworks service. However, before exiting from the new connector, it's a good idea to grab the information you'll need later for API authentication - see Generating token credentials for API access.​