Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Using the Patchworks dashboard, you sync data between standard/prebuilt connectors using either process flows or services. However, with secure, real-time connectivity and access to any system or data source, our API takes things further.
Perhaps your business doesn't have a well-defined API for one of its systems, but you need the ability to exchange data, or perhaps you just need to control trigger points in real time - whatever the reason, the Patchworks API provides an additional layer of flexibility.
Setup and usage for the Patchworks API varies, depending on whether you use Patchworks process flows or services to sync data:
Our full core API and associated documentation is available as a Postman collection - please see our Core API page for details. In this section we spotlight some common API functionality, including step-by-step tutorials.
This section walks through the steps required to pass data from your own system into a Patchworks process flow, via the Patchworks API.
To complete these steps it's assumed that you have:
Registered for a Patchworks account and have a username and password to access your Patchworks dashboard
Built at least one process flow that you want to update via the Patchworks API
The required steps are detailed in the following stages:
In this guide we're using Postman for API calls - you can use your preferred tool for these steps.
Stage # | Action | Tool |
---|---|---|
1
Your preferred text editor
2
Patchworks dashboard (process flows)
3
Patchworks dashboard (process flows)
4
Postman
5
Postman
If you use to sync data, you can initialise a process flow and send in a payload, via the API. Pages in this section walk through the steps required to achieve this.
Patchworks API requests must be authenticated with a bearer token. To obtain a token, you need to send a login request which includes credentials that you use to access the Patchworks dashboard.
Step 1 Create a POST request for the following endpoint:
This endpoint is for the Patchworks production environment.
Step 2 In the request body, add the email and password that you use to log into the Patchworks dashboard. You should add this as JSON - for example:
Step 3 Send the request - if successful, a token is returned. For example:
Access tokens are valid for 24 hours - for example: Issued: Wednesday 20th July at 10:03:08 GMT Expires: Tuesday 21st July at 10:03:08 GMT
Step 4 Save this token ready for use in your initialise request.
Having obtained a Patchworks token, it can be applied to an API request to initialise a process flow with your data passed in the request body.
Step 1 Create a POST request for the following endpoint:
This endpoint is for the Patchworks production environment.
Step 3
In the request body
, pass in the required payload - for example:
Step 4
Send the request - if successful, a 200 'flow initialised' response is given, together with a flow run id
:
If your process flow is sending source data into a target connection, you should map this data using the . This is done in the with two points to note:
In a typical situation, the is used to map data from a source connection to a target connection. However in this scenario, we don't have a source connection - Patchworks doesn't know what data you are sending in or what system it's coming from.
For further guidance please see our page.
You must control when your API requests are sent - the process flow schedule cannot currently be used. With this in mind, please ensure that the default trigger shape in your process flow is not configured with any schedules.
...replacing <flowID>
and <flowVERSION>
with details for your required process flow noted .
Step 2
In the request headers
, pass in the token obtained - this should be prefixed with the word Bearer
- for example:
Remember that the payload must be provided as a JSON object with a payload key containing a string of data. For more information please see .
You can check the status of this flow run via the .
With Patchworks standard integrations, you define a service with one system (a connector) configured as the source and another as the destination. Patchworks suggests field mappings between the two, but these can be tweaked as required.
Using an Inbound API Connector, you can configure a custom entity to define what information Patchworks should expect to receive in a payload from your bespoke system. Once configured, you specify this connector as the source in a Patchworks service, with another standard connector defined as the destination.
As part of this, you define your preferred URL for API access. This means that you can create a managed set of API endpoints for your services, without reinventing the wheel - all completely code-free with error-handling, and guaranteed delivery.
The steps are:
If you have exited the 'new service' flow and need to get back to this point, you can access all service configuration options via the canvas tab:
If you have exited the 'new service' flow and need to get back to this point, you can access all service configuration options via the canvas tab:
Follow the steps below to configure service settings.
... for example:
Step 2 Click the destination entity dropdown field and select which entity should be mapped for the destination connector - for example:
Step 3 Notice that the service settings name updates automatically, based on selections you made in the previous steps - for example:
This name is displayed for the service throughout the system - if required, you can change the default.
Step 4 All other settings on this page are automatically updated and can’t be changed - click the create button to confirm your changes:
This page is part 2 of the instruction set for :
Part # | Link to instructions |
---|
The steps detailed on this page assume that you are following the flow and have just finished , so the configure service settings page is displayed:
Step 1 Click the source entity dropdown field and select the custom entity that you created :
… the service is created, and service trigger options are displayed - please see the page for guidance.
To add a service for an Inbound API connector, start by adding a default service in the usual way, then define settings specific to the API.
To complete the steps detailed here, you must have completed the following tasks:
Patchworks walks you through a series of setup pages in a 'wizard' style flow when adding a new service. Guidance for this setup is detailed in the following sections:
​Add a default service​
​Define field mappings​
​Activate the service​
You can exit anytime and pick up/change service configuration later.
1 |
2 | Configure service settings |
3 |
4 |
5 |
A Patchworks access token is required to authorise API requests for sending data to the inbound URL for a Patchworks service.
To obtain this token, you send a set of client credentials to a Patchworks token endpoint. Patchworks validates these credentials and returns an access token you can use to POST custom payload data to the required service. Once the custom payload is received, it’s processed in the usual way.These steps are illustrated below:
Access tokens are valid for 24 hours - for example: Issued: Wednesday 20th July at 10:03:08 GMT Expires: Tuesday 21st July at 10:03:08 GMTUse the authentication tab for an Inbound API connector to obtain/generate details required to request access tokens for secure access to the inbound URL for a Patchworks service. You will need:
A Patchworks token endpoint
OAuth credentials for this endpoint
Patchworks uses OAuth 2.0. Watch this space for Basic Authentication support, coming soon!
To complete the steps detailed here, you must have completed the following tasks:
Follow the steps below:
Step 1 Select the authentication tab for the required Inbound API Connector:
These steps assume you are following a 'create new' connector flow. If you need to use an existing connector, find the required connector and select the authentication tab:
Step 2 Copy the token endpoint and paste it somewhere safe for future use:
… when prompted, enter a name for this set of credentials:
Step 3 Move down to the OAuth2 Clients section and select create an OAuth2 client:
… when prompted, enter a name for this set of credentials:
Step 4 Click the create new OAuth2 client button to confirm and display generated credentials:
Step 5 Copy/paste this information somewhere safe for future use.
Once this page is closed, you can’t reaccess the client secret. If you lose this information, you need to generate a new set of credentials.
Step 6 Click the close button to exit back to the connector authentication tab, where the new set of credentials is listed:
Step 7 You are now ready to add a Patchworks service - see Adding a Patchworks service for an Inbound API connector.​
Follow the steps below to add a default service.
Step 1 Select services from the left-hand navigation menu:
Step 2 Click the add new service button:
When you add a new service from a connector, this connector becomes the source automatically.
Step 3 When prompted to choose a source connector (all configured connectors for your implementation are listed), select the Inbound API connector:
Step 4 When prompted to choose a destination connector, select the connector that you want to receive incoming data from the API connector:
All configured connectors - excluding the one already selected for the source (i.e. the Inbound API connector) - are available for selection.
​
This page is part 1 of the instruction set for :
Part # | Link to instructions |
---|
This option is also available from the bottom of any connector setup page, so if you’ve just finished , you can go straight to service setup from there:​
​
Step 5 The configure service settings page is displayed - please see for guidance.
1 | Add a default service |
2 |
3 |
4 |
5 |
Mappings are at the heart of Patchworks.
When we pull data from one system and push it into another, it’s unlikely that the two will have a like-for-like data structure. By creating mappings between source and destination data fields, the Patchworks engine knows how to transform incoming data as needed to update the destination system.
The illustration below helps to visualise this:
With its standard connectors, Patchworks knows what mappings are likely to be between two given systems - default mappings are provided and can be tweaked if needed.
However, the Inbound API connector is unique for every client - Patchworks has no prior knowledge about how fields in a custom payload correlate to fields in other systems. As such, you must define the required mappings.
If you have exited the 'new service' flow and need to get back to this point, you can access all service configuration options via the canvas tab:
Step 1 Click the add new row button:​​
... a new row is created, with fields to complete for source and destination entities - for example:​​
Step 2 Use the source field dropdown list to select a field from your Inbound API connector custom payload - for example:​​
…if required, set a preferred display name - for example:
Step 3 Use the destination field dropdown list to choose a field from your chosen destination connector to be mapped to the selected source field - if required, set a preferred display name.
Step 4 Click the done button associated with this row, to confirm changes:​
Step 5 Repeat steps 1- 4 for all required field mappings.
Alternatively, you can use the advanced editor to add a mapping file in JSON format - for example:
​
This page is part 4 of the instruction set for :
Part # | Link to instructions |
---|
The steps detailed on this page assume that you are following the flow and have just saved service trigger schedule settings so the field mappings page is displayed:
Follow the steps below to define field mappings between the , and the chosen destination connector.
​​
Step 6 Click the next button to access final service settings and activate the service - please see the page for guidance.​
Having added a Patchworks service for your Inbound API connector, you can implement your own API requests to send required data to the Patchworks endpoint for that service. This page summarises the information that you will need to accomplish this task.
To implement API requests for sending data to a Patchworks service, you must have completed the following tasks in Patchworks:
To implement API requests for sending custom data to a Patchworks service, you will need:
You must provide a valid access token to POST custom data to a Patchworks service. To obtain access tokens, send a GET request to the Patchworks token endpoint, with your OAuth client credentials.
Access tokens are valid for 24 hours - for example:
Issued: Wednesday 20th July at 10:03:08 GMT Expires: Tuesday 21st July at 10:03:08 GMT
You can generate OAuth client credentials and view the required token endpoint from the authentication tab for your Inbound API connector. For details, please see: Generating token credentials for API access.
To minimise the chance of any issues with rate limits, we advise obtaining an access token once a day and storing this for use in any requests (rather than requesting an access token every time you want to post data).
If you attempt to post data with an expired access token, Patchworks returns a 401 status code, which should be your trigger to request a new token.
To POST custom payload data to a Patchworks service, you need the URL for that service. Service URLs are always in the form:
https://inbound.pwks.co/v1/[YOUR COMPANY NAME]/[VANITY URL]…where:
[YOUR COMPANY NAME] is auto-generated by Patchworks, based on the company name provided for implementation.
[VANITY URL] is your preferred text value to complete the URL.
1 |
2 |
3 |
4 | Define field mappings |
5 |
If you have exited the 'new service' flow and need to get back to this point, you can access all service configuration options via the canvas tab:
Follow the steps below to activate the configured service:
Step 1 Toggle the service status to active, so it starts running according to the defined schedule.
Step 2 Click the save button.
Step 4 When you’re ready, you can re-access this option and activate the service:
​
This page is part 5 of the instruction set for :
Part # | Link to instructions |
---|
The steps detailed on this page assume that you are following the flow and have just saved field mappings so the final service settings page is displayed:​
​
Step 3 Service configuration is finished - you can now complete your .
1 |
2 |
3 |
4 |
5 | ​Activate the service |
The Patchworks API can be used to add and manage cross-reference lookups. Using the API you can work with:
All API requests must be authenticated with a Patchworks bearer token. To obtain a token, send a POST request to the following endpoint:
In the request body, add the email and password that you use to log into the Patchworks dashboard. You should add this as JSON - for example:
A successful response returns a token. Tokens are valid for 24 hours.
For detailed information about obtaining tokens, please see Obtaining a token for Patchworks API authentication.
The Patchworks cross-reference lookup API accepts two identifiers as parameters:
Having selected a cross-reference lookup to view/edit, the unique id can be found at the end of the URL - for example:
Having selected a cross-reference lookup to view/edit, each existing lookup row is displayed with a unique valueId in the id column:
Patchworks API requests must be authenticated with a bearer token. To obtain a token, you need to send a login request which includes credentials that you use to access the Patchworks dashboard.
Step 1 Create a POST request for the following endpoint:
This endpoint is for the Patchworks production environment.
Step 2 In the request body, add the email and password that you use to log into the Patchworks dashboard. You should add this as JSON - for example:
Step 3 Send the request - if successful, a token is returned. For example:
Access tokens are valid for 24 hours - for example: Issued: Wednesday 20th July at 10:03:08 GMT Expires: Tuesday 21st July at 10:03:08 GMT
Step 4 Save this token ready for use in your API requests.
The Patchworks inbound API supports data within strings. This data must be passed within a payload
key.
The required data format is a JSON object with a payload key containing a string of data. For example:
Non-strings and raw payloads are not currently supported.
Here, note that the payload
key is in a JSON object, and is being used to hold different types of data as strings - text, XML and JSON.
When you send a Patchworks API request to initialise a process flow, you must provide the internal IDs for the required process flow and version. This guide walks through the steps required to obtain this information.
Step 1 Log in to the Patchworks dashboard.
Step 2 Select process flows from the left-hand navigation menu and select the process flow that you want to update.
Step 3
Check the title bar in the top-left corner and make a note of the number above the title - this is the process flow ID
:
Step 4 Click the settings icon:
...to access process flow settings:
Step 5
Look in the versions panel and find the version of this process flow that you want to initialise, then note the associated ID - this is the process flow version ID
:
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.
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.
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:
Parameter | Summary |
---|---|
For more information about process flow versioning please see our page.
Step 6 You'll use this information in any API requests made to initialise this process flow.
​
​
​
​
Response code | Status | Summary |
---|
Response code | Status | Summary |
---|
Response code | Status | Summary |
---|
​
​​
​​
​​
​​
​
The Inbound API connector is now ready to use in a . However, before exiting from the new connector, it's a good idea to grab the information you'll need later for API authentication - see .​
At least one parameter must be passed into the request.
At least one parameter must be passed into the request.
{{id}}
The unique identifier associated with the cross-reference lookup.
{{valueID}}
The unique identifier associated with the cross-reference lookup row (also known as a mapping row).
200 | OK | The request succeeded. The meaning of 'success' depends on the HTTP method - |
201 | OK | Typically returned in response to a POST request, indicating that the request has been received but not yet actioned. This response is intended for cases where another process or server handles the request, or for batch processing. |
401 | Unauthorised | Although the HTTP standard specifies 'unauthorised', semantically this response means 'unauthenticated'. That is, the client must authenticate itself to get the requested response. The token supplied may be incorrect/expired. |
413 | Payload too large | The payload exceeds the limit on this API server. Our limit is 8MB. Reduce the payload size by splitting the data and sending over multiple calls |
422 | Invalid | The payload is invalid.
|
500 | Internal server error | The server has encountered an error and it is unable to continue |
This section includes Patchworks API reference information which is common to both process flows and services use-case scenarios.
This page is part 3 of the instruction set for adding a Patchworks service for an Inbound API connector:
The steps detailed on this page assume that you are following the 'new service' flow and have just saved service settings, so the service trigger page is displayed:
If you have exited the 'new service' flow and need to get back to this point, you can access all service configuration options via the canvas tab:
Follow the steps below to set a schedule on which the service for your Inbound API connector will be triggered.
Step 1 Click the trigger type dropdown field and select the schedule option:​
Step 2 Set scheduling options as required:
Step 3 Click the next button. Schedule settings are saved, and mapping options are displayed - please see the define field mappings page for guidance.
Part # | Link to instructions |
---|---|
​
​​
1
2
3
Set the service trigger schedule
4
5