Comment on page
Cross-reference lookups API

Introduction
The Patchworks API can be used to add and manage cross-reference lookups. Using the API you can work with:
​Lookups​
​Lookup mapping rows​
Authentication
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:
1
{
2
    "email": "[email protected]",
3
    "password": "mypassword123*"
4
}
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.
Required cross reference details
The Patchworks cross-reference lookup API accepts two identifiers as parameters:
Parameter
Summary
​mapID​
The unique identifier associated with the cross-reference lookup.
​mapValueID​
The unique identifier associated with the cross-reference lookup row (also known as a mapping row).
MapID
Having selected a cross-reference lookup to view/edit, the unique mapID can be found at the end of the URL - for example:
MapValueID
Having selected a cross-reference lookup to view/edit, each existing lookup row is displayed with a unique mapValueID in the id column:
Lookups
​
 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
1
GET https://core.wearepatchworks.com/api/v1/maps
Required headers
Authorization : Bearer token
Sample 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": "&laquo; 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 &raquo;",
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
}
​
 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
1
GET https://core.wearepatchworks.com/api/v1/maps/{{mapId}}
Required headers
Authorization : Bearer token
Sample 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
}
​
 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
1
POST https://core.wearepatchworks.com/api/v1/maps
Required headers
Authorization : Bearer token
Body 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
}
​
 Update a cross-reference lookup
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 token
Body 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
}
​
 Delete a cross-reference lookup
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 token
Sample 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
}
Lookup rows
​
 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
1
GET https://core.wearepatchworks.com/api/v1/maps/{{mapId}}/map-values
Required headers
Authorization : Bearer token
Sample 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": "&laquo; 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 &raquo;",
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
}
​
 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
1
GET https://core.wearepatchworks.com/api/v1/maps/{{mapId}}/map-values/{{mapValueId}}
Required headers
Authorization : Bearer token
Sample 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
}
​
 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
1
POST https://core.wearepatchworks.com/api/v1/maps/{{mapId}}/map-values
Required headers
Authorization : Bearer token
Body 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
}
​
 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
1
PATCH https://core.wearepatchworks.com/api/v1/maps/{{mapId}}/map-values/{{mapValueId}}
Required headers
Authorization : Bearer token
Body 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
}
​
 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
1
DELETE https://core.wearepatchworks.com/api/v1/maps/{{mapId}}/map-values/{{mapValueId}}
Required headers
Authorization : Bearer token
Sample 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
}
Parameter	Summary
mapID	The unique identifier associated with the cross-reference lookup.
mapValueID	The unique identifier associated with the cross-reference lookup row (also known as a mapping row).
Implementing API requests
Patchworks API reference
Last modified 4mo ago