1 of 10

Core API spotlights

Introduction

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.

Pages in this section

Initialising a process flow & sending data via the Patchworks API

Introduction

This section walks through the steps required to pass data from your own system into a Patchworks process flow, via the Patchworks API.

Assumptions

To complete these steps it's assumed that you have:

and have a username and password to access your Patchworks dashboard
that you want to update via the Patchworks API

What you need to do

The required steps are detailed in the following stages:

Stage #

Action

Tool

In this guide we're using Postman for API calls - you can use your preferred tool for these steps.

Quickstart guide

Introduction

All steps required to initialise a process flow via the are detailed . This page provides a quick overview of these steps.

Summary

The steps

Preparing your data

Introduction

The Patchworks inbound API supports data within strings. This data must be passed within a payload key.

Required format

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.

Mapping payload data

Introduction

If your process flow is sending source data into a target connection, you should map this data using the map shape. This is done in the usual way with two points to note:

No source details are set

Source endpoint

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.

As such, you won't select any source details when configuring the map shape - just leave these field blank:

Add mapping rules manually

Because Patchworks has no way of knowing the structure of your incoming data, mapping rules must be added manually.

For further guidance please see our page.

Obtaining process flow & version IDs for API requests

Introduction

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.

The steps

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:

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.

Obtaining a token for Patchworks API authentication

Introduction

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.

The steps

Show me

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 .

Initialising a process flow & sending data

Introduction

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.

You must control when your API requests are sent - the process flow trigger shape 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.

The steps

Show me

Step 1 Create a POST request for the following endpoint:

...replacing <flowID> and <flowVERSION> with details for your required process flow noted .

This endpoint is for the Patchworks production environment.

Step 2 In the request headers, pass in the token obtained - this should be prefixed with the word Bearer - for example:

Step 3 In the request body, pass in the required payload - 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 .

Step 4 Send the request - if successful, a 200 'flow initialised' response is given, together with a flow run id:

You can check the status of this flow run via the .

Working with cross-reference lookup API requests

Introduction

The Patchworks API can be used to add and manage cross-reference lookups. Using the API you can work with:

Lookups

Authentication

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 .

Required cross reference details

The Patchworks cross-reference lookup API accepts two identifiers as parameters:

Parameter

Summary

id

Having selected a cross-reference lookup to view/edit, the unique id can be found at the end of the URL - for example:

valueId

Having selected a cross-reference lookup to view/edit, each existing lookup row is displayed with a unique valueId in the id column:

Lookups API

Retrieve a list all cross-reference lookups

Summary

Retrieve a list of cross-reference lookups that have been installed or added by your organisation.

URL

Required headers

Authorization : Bearer token

Sample request

Retrieve a single cross-reference lookup

Summary

Retrieve basic details for a specific cross-reference lookup that has been installed or added by your organisation.

URL

Required headers

Authorization : Bearer token

Sample request

Create a new cross-reference lookup

Summary

Create a new cross-reference lookup for your organisation. The lookup is created without any mapping rows.

URL

Required headers

Authorization : Bearer token

Body parameters

Update a cross-reference lookup

Summary

Update basic details for a cross-reference lookup for your organisation.

URL

Required headers

Authorization : Bearer token

Body parameters

Delete a cross-reference lookup

Summary

Remove a cross-reference lookup (and all associated row values) for your organisation.

URL

Required headers

Authorization : Bearer token

Sample request

Lookup rows API

Retrieve a list of mapping row values for a cross-reference lookup

Summary

Retrieve a list of row values for a given lookup that has been installed or added by your organisation.

URL

Required headers

Authorization : Bearer token

Sample request

Retrieve mapping row values for a specific row within a cross-reference lookup

Summary

Retrieve mapping row values for a given row within a given cross-reference lookup that has been installed or added by your organisation.

URL

Required headers

Authorization : Bearer token

Create a new mapping row for a cross-reference lookup

Summary

Create a new mapping row for a cross-reference lookup that has been installed or added by your organisation.

URL

Required headers

Authorization : Bearer token

Body parameters

Update a mapping row for a cross-reference lookup

Summary

Update mapping row values for a cross-reference lookup that has been installed or added by your organisation.

URL

Required headers

Authorization : Bearer token

Body parameters

Delete a mapping row for a cross-reference lookup

Summary

Remove a given mapping row for a cross-reference lookup that has been installed or added by your organisation.

URL

Required headers

Authorization : Bearer token

Sample request

Working with cross-reference lookup API requests

Introduction

The Patchworks API can be used to add and manage cross-reference lookups. Using the API you can work with:

Lookups

Authentication

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 .

Required cross reference details

The Patchworks cross-reference lookup API accepts two identifiers as parameters:

Parameter

Summary

id

Having selected a cross-reference lookup to view/edit, the unique id can be found at the end of the URL - for example:

valueId

Having selected a cross-reference lookup to view/edit, each existing lookup row is displayed with a unique valueId in the id column:

Lookups API

Retrieve a list all cross-reference lookups

Summary

Retrieve a list of cross-reference lookups that have been installed or added by your organisation.

URL

Required headers

Authorization : Bearer token

Sample request

Retrieve a single cross-reference lookup

Summary

Retrieve basic details for a specific cross-reference lookup that has been installed or added by your organisation.

URL

Required headers

Authorization : Bearer token

Sample request

Create a new cross-reference lookup

Summary

Create a new cross-reference lookup for your organisation. The lookup is created without any mapping rows.

URL

Required headers

Authorization : Bearer token

Body parameters

Update a cross-reference lookup

Summary

Update basic details for a cross-reference lookup for your organisation.

URL

Required headers

Authorization : Bearer token

Body parameters

Delete a cross-reference lookup

Summary

Remove a cross-reference lookup (and all associated row values) for your organisation.

URL

Required headers

Authorization : Bearer token

Sample request

Lookup rows API

Retrieve a list of mapping row values for a cross-reference lookup

Summary

Retrieve a list of row values for a given lookup that has been installed or added by your organisation.

URL

Required headers

Authorization : Bearer token

Sample request

Retrieve mapping row values for a specific row within a cross-reference lookup

Summary

Retrieve mapping row values for a given row within a given cross-reference lookup that has been installed or added by your organisation.

URL

Required headers

Authorization : Bearer token

Create a new mapping row for a cross-reference lookup

Summary

Create a new mapping row for a cross-reference lookup that has been installed or added by your organisation.

URL

Required headers

Authorization : Bearer token

Body parameters

Update a mapping row for a cross-reference lookup

Summary

Update mapping row values for a cross-reference lookup that has been installed or added by your organisation.

URL

Required headers

Authorization : Bearer token

Body parameters

Delete a mapping row for a cross-reference lookup

Summary

Remove a given mapping row for a cross-reference lookup that has been installed or added by your organisation.

URL

Required headers

Authorization : Bearer token

Sample request

{ "data": [ { "id": 2, "cross_reference_lookup_template_id": 10, "name": "American state name to ANSI Alpha 2", "description": "Mapping of state names and their respective ANSI alpha-2 codes", "default_value": null }, { "id": 4, "cross_reference_lookup_template_id": 13, "name": "Area measurement to abbreviation", "description": "Mapping of area measurements and their abbreviations", "default_value": null }, { "id": 6, "cross_reference_lookup_template_id": 4, "name": "Country name to Primary currency name", "description": "Mapping of country names and their primary currency names", "default_value": null }, { "id": 5, "cross_reference_lookup_template_id": 16, "name": "Currency name to ISO 4217", "description": "Mapping of currency names and their respective ISO 4217 codes", "default_value": null }, { "id": 7, "cross_reference_lookup_template_id": 11, "name": "Month name to abbreviation", "description": "Mapping of month names and their abbreviations", "default_value": null } ], "links": { "first": "http://core.wearepatchworks.com/api/v1/cross-reference-lookups?page=1", "last": "http://core.wearepatchworks.com/api/v1/cross-reference-lookups?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "http://core.wearepatchworks.com/api/v1/cross-reference-lookups?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "http://core.wearepatchworks.com/api/v1/cross-reference-lookups", "per_page": 50, "to": 5, "total": 5 } }

{ "data": [ { "id": 556, "left_value": "April", "right_value": "Apr" }, { "id": 557, "left_value": "August", "right_value": "Aug" }, { "id": 558, "left_value": "December", "right_value": "Dec" }, { "id": 559, "left_value": "February", "right_value": "Feb" }, { "id": 560, "left_value": "January", "right_value": "Jan" }, { "id": 561, "left_value": "July", "right_value": "July" }, { "id": 562, "left_value": "June", "right_value": "June" }, { "id": 563, "left_value": "March", "right_value": "Mar" }, { "id": 564, "left_value": "May", "right_value": "May" }, { "id": 565, "left_value": "November", "right_value": "Nov" }, { "id": 566, "left_value": "October", "right_value": "Oct" }, { "id": 567, "left_value": "September", "right_value": "Sept" } ], "links": { "first": "http://core.wearepatchworks.com/api/v1/cross-reference-lookups/7/cross-reference-lookup-values?page=1", "last": "http://core.wearepatchworks.com/api/v1/cross-reference-lookups/7/cross-reference-lookup-values?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "links": [ { "url": null, "label": "« Previous", "active": false }, { "url": "http://core.wearepatchworks.com/api/v1/cross-reference-lookups/7/cross-reference-lookup-values?page=1", "label": "1", "active": true }, { "url": null, "label": "Next »", "active": false } ], "path": "http://core.wearepatchworks.com/api/v1/cross-reference-lookups/7/cross-reference-lookup-values", "per_page": 50, "to": 12, "total": 12 } }

Core API spotlights

Introduction

Pages in this section

Initialising a process flow & sending data via the Patchworks API

Introduction

Assumptions

What you need to do

Quickstart guide

Introduction

Summary

The steps

Preparing your data

Introduction

Required format

Mapping payload data

Introduction

Source endpoint

Add mapping rules manually

Obtaining process flow & version IDs for API requests

Introduction

The steps

Obtaining a token for Patchworks API authentication

Introduction

The steps

Initialising a process flow & sending data

Introduction

The steps

Working with cross-reference lookup API requests

Introduction

Authentication

Required cross reference details

id

valueId

Lookups API

Lookup rows API

Related information

Core API spotlights

Introduction

Pages in this section

Initialising a process flow & sending data via the Patchworks API

Introduction

Assumptions

What you need to do

The steps

Mapping payload data

Introduction

Source endpoint

Add mapping rules manually

Obtaining process flow & version IDs for API requests

Introduction

The steps

Preparing your data

Introduction

Required format

Quickstart guide

Introduction

Summary

Initialising a process flow & sending data

Introduction

The steps

Obtaining a token for Patchworks API authentication

Introduction

The steps

Working with cross-reference lookup API requests

Introduction

Authentication

Required cross reference details

id

valueId

Lookups API

Lookup rows API

Related information