Comment on page
Cross-reference lookups API
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:
1
https://svc-fabric.pwks.co/api/v1/login
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:
Parameter | Summary |
---|---|
The unique identifier associated with the cross-reference lookup. | |
The unique identifier associated with the cross-reference lookup row (also known as a mapping row). |
Having selected a cross-reference lookup to view/edit, the unique mapID 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 mapValueID in the id column:

Summary
Retrieve a list of cross-reference lookups that have been installed or added by your organisation.
URL
1
GET https://core.wearepatchworks.com/api/v1/maps
Required headers
Authorization
: Bearer tokenSample request
1
curl -X GET "https://core.wearepatchworks.com/api/v1/maps" \
2
-H "Authorization: Bearer e1234&FSKFJmytoken"
Sample response (200 OK)
1
{
2
"data": [
3
{
4
"id": 1,
5
"map_template_id": null,
6
"name": "Colour RGB Values",
7
"description": "Convert long-form colours to RGB values",
8
"default_value": "FFFFFF"
9
},
10
{
11
"id": 2,
12
"map_template_id": null,
13
"name": "File types",
14
"description": "Convert long-form file types to abbreviations",
15
"default_value": null
16
}
17
],
18
"links": {
19
"first": "http://core.wearepatchworks.com/api/v1/maps?page=1",
20
"last": "http://core.wearepatchworks.com/api/v1/maps?page=1",
21
"prev": null,
22
"next": null
23
},
24
"meta": {
25
"current_page": 1,
26
"from": 1,
27
"last_page": 1,
28
"links": [
29
{
30
"url": null,
31
"label": "« Previous",
32
"active": false
33
},
34
{
35
"url": "http://core.wearepatchworks.com/api/v1/maps?page=1",
36
"label": "1",
37
"active": true
38
},
39
{
40
"url": null,
41
"label": "Next »",
42
"active": false
43
}
44
],
45
"path": "http://core.wearepatchworks.com/api/v1/maps",
46
"per_page": 50,
47
"to": 2,
48
"total": 2
49
}
50
}
Summary
Retrieve basic details for a specific cross-reference lookup that has been installed or added by your organisation.
URL
1
GET https://core.wearepatchworks.com/api/v1/maps/{{mapId}}
Required headers
Authorization
: Bearer tokenSample request
1
curl -X GET "https://core.wearepatchworks.com/api/v1/maps/2" \
2
-H "Authorization: Bearer e1234&FSKFJmytoken"
Sample response (200 OK)
1
{
2
"data": {
3
"id": 2,
4
"map_template_id": null,
5
"name": "File types",
6
"description": "Convert long-form file types to abbreviations",
7
"default_value": null
8
}
9
}
Summary
Create a new cross-reference lookup for your organisation. The lookup is created without any mapping rows.
URL
1
POST https://core.wearepatchworks.com/api/v1/maps
Required headers
Authorization
: Bearer tokenBody parameters
name
(required) (string)description
(required) (string)default_value
(optional) (string)
Example:
1
{
2
"name": "New lookup name",
3
"description": "New lookup description",
4
"default_value": "New lookup default value"
5
}
Sample request
1
curl -X POST "https://core.wearepatchworks.com/api/v1/maps" \
2
-H "Authorization: Bearer e1234&FSKFJmytoken" \
3
-H "Content-Type: application/json" \
4
-d '{
5
"name": "Colour HEX Values",
6
"description": "Convert long-form colours to HEX codes",
7
"default_value": "FFFFFF"
8
}'
Sample response (200 OK)
1
{
2
"data": {
3
"id": 5,
4
"map_template_id": null,
5
"name": "Colour HEX Values",
6
"description": "Convert long-form colours to HEX codes",
7
"default_value": "FFFFFF"
8
}
9
}
Summary
Update basic details for a cross-reference lookup for your organisation.
URL
1
PATCH https://core.wearepatchworks.com/api/v1/maps/{{mapId}}
Required headers
Authorization
: Bearer tokenBody parameters
name
(optional) (string)description
(optional) (string)default_value
(optional) (string)
At least one parameter must be passed into the request.
Example:
1
{
2
"name": "New lookup name",
3
"description": "New lookup description"
4
"default_value": "New lookup default value"
5
}
Sample request
1
curl -X PATCH "https://core.wearepatchworks.com/api/v1/maps/5" \
2
-H "Authorization: Bearer e1234&FSKFJmytoken" \
3
-H "Content-Type: application/json" \
4
-d '{
5
"name": "Colour HEX Codes",
6
"description": "Convert long-form colours to HEX codes",
7
"default_value": "000000"
8
}'
Sample response (200 OK)
1
{
2
"data": {
3
"id": 5,
4
"map_template_id": null,
5
"name": "Colour HEX Codes",
6
"description": "Convert long-form colours to HEX codes",
7
"default_value": "eeeeee"
8
}
9
}
Summary
Remove a cross-reference lookup (and all associated row values) for your organisation.
URL
1
DELETE https://core.wearepatchworks.com/api/v1/maps/{{mapId}}
Required headers
Authorization
: Bearer tokenSample request
1
curl -X DELETE "https://core.wearepatchworks.com/api/v1/maps/6" \
2
-H "Authorization: Bearer e1234&FSKFJmytoken"
Sample response (200 OK)
1
{
2
"message": "Map deleted successfully."
3
}
Summary
Retrieve a list of row values for a given lookup that has been installed or added by your organisation.
URL
1
GET https://core.wearepatchworks.com/api/v1/maps/{{mapId}}/map-values
Required headers
Authorization
: Bearer tokenSample request
1
curl -X GET "https://core.wearepatchworks.com/api/v1/maps/5/map-values" \
2
-H "Authorization: Bearer e1234&FSKFJmytoken"
Sample response (200 OK)
1
{
2
"data": [
3
{
4
"id": 15,
5
"left_value": "Blue",
6
"right_value": "1D3162"
7
},
8
{
9
"id": 17,
10
"left_value": "Cyan",
11
"right_value": "04A2C9"
12
},
13
{
14
"id": 16,
15
"left_value": "Lilac",
16
"right_value": "B188FF"
17
},
18
{
19
"id": 12,
20
"left_value": "Orange",
21
"right_value": "FF731C"
22
},
23
{
24
"id": 13,
25
"left_value": "Red",
26
"right_value": "EF4212"
27
},
28
{
29
"id": 14,
30
"left_value": "Yellow",
31
"right_value": "FFC309"
32
}
33
],
34
"links": {
35
"first": "http://core.wearepatchworks.com/api/v1/maps/5/map-values?page=1",
36
"last": "http://core.wearepatchworks.com/api/v1/maps/5/map-values?page=1",
37
"prev": null,
38
"next": null
39
},
40
"meta": {
41
"current_page": 1,
42
"from": 1,
43
"last_page": 1,
44
"links": [
45
{
46
"url": null,
47
"label": "« Previous",
48
"active": false
49
},
50
{
51
"url": "http://core.wearepatchworks.com/api/v1/maps/5/map-values?page=1",
52
"label": "1",
53
"active": true
54
},
55
{
56
"url": null,
57
"label": "Next »",
58
"active": false
59
}
60
],
61
"path": "http://core.wearepatchworks.com/api/v1/maps/5/map-values",
62
"per_page": 50,
63
"to": 6,
64
"total": 6
65
}
66
}
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
1
GET https://core.wearepatchworks.com/api/v1/maps/{{mapId}}/map-values/{{mapValueId}}
Required headers
Authorization
: Bearer tokenSample request
1
curl -X GET "https://core.wearepatchworks.com/api/v1/maps/5/map-values/16" \
2
-H "Authorization: Bearer e1234&FSKFJmytoken"
Sample response (200 OK)
1
{
2
"data": {
3
"id": 16,
4
"left_value": "Lilac",
5
"right_value": "B188FF"
6
}
7
}
Summary
Create a new mapping row for a cross-reference lookup that has been installed or added by your organisation.
URL
1
POST https://core.wearepatchworks.com/api/v1/maps/{{mapId}}/map-values
Required headers
Authorization
: Bearer tokenBody parameters
left_value
(required) (string)right_value
(required) (string)
Example:
1
{
2
"left_value": "Your required value",
3
"right_value": "Your required value",
4
}
Sample request
1
curl -X POST "https://core.wearepatchworks.com/api/v1/maps/5/map-values" \
2
-H "Authorization: Bearer e1234&FSKFJmytoken" \
3
-H "Content-Type: application/json" \
4
-d '{
5
"left_value": "Green",
6
"right_value": "496252"
7
}'
Sample response (200 OK)
1
{
2
"data": {
3
"id": 18,
4
"left_value": "Green",
5
"right_value": "496252"
6
}
7
}
Summary
Update mapping row values for a cross-reference lookup that has been installed or added by your organisation.
URL
1
PATCH https://core.wearepatchworks.com/api/v1/maps/{{mapId}}/map-values/{{mapValueId}}
Required headers
Authorization
: Bearer tokenBody parameters
left_value
(optional) (string)right_value
(optional) (string)
At least one parameter must be passed into the request.
Example:
1
{
2
"left_value": "Your required value",
3
"right_value": "Your required value"
4
}
Sample request
1
curl -X PATCH "https://core.wearepatchworks.com/api/v1/maps/5/map-values/16" \
2
-H "Authorization: Bearer e1234&FSKFJmytoken" \
3
-H "Content-Type: application/json" \
4
-d '{
5
"left_value": "Lilac - dark"
6
}'
Sample response (200 OK)
1
{
2
"data": {
3
"id": 16,
4
"left_value": "Lilac - dark",
5
"right_value": "C1A0FF"
6
}
7
}
Summary
Remove a given mapping row for a cross-reference lookup that has been installed or added by your organisation.
URL
1
DELETE https://core.wearepatchworks.com/api/v1/maps/{{mapId}}/map-values/{{mapValueId}}
Required headers
Authorization
: Bearer tokenSample request
1
curl -X DELETE "https://core.wearepatchworks.com/api/v1/maps/5/map-values/16" \
2
-H "Authorization: Bearer e1234&FSKFJmytoken"
3
Sample response (200 OK)
1
{
2
"message": "Map value deleted successfully."
3
}
Last modified 4mo ago