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

• Lookup 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:

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:

{
    "email": "[email protected]",
    "password": "mypassword123*"
}

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
{{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).

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

GET https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups

Required headers

Authorization : Bearer token

Sample request

curl -X GET "https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups" \
-H "Authorization: Bearer e1234&FSKFJmytoken"

Sample response (200 OK)

{
    "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
    }
}

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

GET https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups/{{id}}

Required headers

Authorization : Bearer token

Sample request

curl -X GET "https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups/2" \
-H "Authorization: Bearer e1234&FSKFJmytoken"

Sample response (200 OK)

{
    "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
    }
}

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

POST https://https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups

Required headers

Authorization : Bearer token

Body parameters

• name (required) (string)

• description (required) (string)

• default_value (optional) (string)

Example:

{
    "name": "New lookup name",
    "description": "New lookup description",
    "default_value": "New lookup default value"
}

Sample request

curl -X POST "https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups" \
-H "Authorization: Bearer e1234&FSKFJmytoken" \
-H "Content-Type: application/json" \
-d '{
    "name": "Colour HEX Values",
    "description": "Convert long-form colours to HEX codes",
    "default_value": "FFFFFF"
}'

Sample response (200 OK)

{
    "data": {
        "id": 9,
        "cross_reference_lookup_template_id": null,
        "name": "Colour HEX Values",
        "description": "Convert long-form colours to HEX codes",
        "default_value": "FFFFFF"
    }
}

Update a cross-reference lookup

Summary

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

URL

PATCH https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups/{{id}}

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:

{
    "name": "New lookup name",
    "description": "New lookup description"
    "default_value": "New lookup default value"
}

Sample request

curl -X PATCH "https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups/8" \
-H "Authorization: Bearer e1234&FSKFJmytoken" \
-H "Content-Type: application/json" \
-d '{
    "name": "Colour HEX Codes",
    "description": "Convert long-form colours to HEX codes",
    "default_value": "000000"
}'

Sample response (200 OK)

{
    "data": {
        "id": 9,
        "cross_reference_lookup_template_id": null,
        "name": "Colour HEX Codes",
        "description": "Convert long-form colours to HEX codes",
        "default_value": "000000"
    }
}

Delete a cross-reference lookup

Summary

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

URL

DELETE https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups/{{id}}

Required headers

Authorization : Bearer token

Sample request

curl -X DELETE "https://

Sample response (200 OK)

{
    "message": "Cross reference lookup deleted successfully."
}

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

GET https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups/{{id}}/cross-reference-lookup-values

Required headers

Authorization : Bearer token

Sample request

curl -X GET "https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups/7/cross-reference-lookup-values" \
-H "Authorization: Bearer e1234&FSKFJmytoken"

Sample response (200 OK)

{
    "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
    }
}

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

GET https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups/{{id}}/cross-reference-lookup-values/{{valueID}}

Required headers

Authorization : Bearer token

Sample request

curl -X GET "https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups/7/cross-reference-lookup-values/557
-H "Authorization: Bearer e1234&FSKFJmytoken"

Sample response (200 OK)

{
    "data": {
        "id": 557,
        "left_value": "August",
        "right_value": "Aug"
    }
}

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

POST https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups/{{id}}/cross-reference-lookup-values

Required headers

Authorization : Bearer token

Body parameters

• left_value (required) (string)

• right_value (required) (string)

Example:

{
    "left_value": "Your required value",
    "right_value": "Your required value"
}

Sample request

curl -X POST "https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups/7/cross-reference-lookup-values" \
-H "Authorization: Bearer e1234&FSKFJmytoken" \
-H "Content-Type: application/json" \
-d '{
    "left_value": "Test",
    "right_value": "TST"
}'

Sample response (200 OK)

{
    "data": {
        "id": 568,
        "left_value": "Test",
        "right_value": "TST"
    }
}

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

PATCH https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups/{{id}}/cross-reference-lookup-values/{{valueId}}

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:

{
    "left_value": "Your required value",
    "right_value": "Your required value"
}

Sample request

curl -X PATCH "https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups/7/cross-reference-lookup-values/568" \
-H "Authorization: Bearer e1234&FSKFJmytoken" \
-H "Content-Type: application/json" \
-d '{
    "left_value": "NEWTest",
    "right_value": "NEWTST"
}'

Sample response (200 OK)

{
    "data": {
        "id": 568,
        "left_value": "NEWTest",
        "right_value": "NEWTST"
    }
}

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

DELETE https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups/{{id}}/cross-reference-lookup-values/{{valueId}}

Required headers

Authorization : Bearer token

Sample request

curl -X DELETE "https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups/7/cross-reference-lookup-values/568" \
-H "Authorization: Bearer e1234&FSKFJmytoken"

Sample response (200 OK)

{
    "message": "Cross reference lookup value deleted successfully."
}

Related information

• Core API