# Working with cross-reference lookup API requests

## Introduction

The Patchworks API can be used to add and manage [cross-reference lookups](https://doc.wearepatchworks.com/product-documentation/process-flows/cross-reference-lookups/adding-a-cross-reference-lookup). Using the API you can work with:

* [Lookups](#lookups-api)
* [Lookup rows ](#lookup-rows-api)

## Authentication

All API requests must be authenticated with a Patchworks bearer token. To obtain a token, send a POST request to the following endpoint:

{% code lineNumbers="true" %}

```markup
https://svc-fabric.pwks.co/api/v1/login
```

{% endcode %}

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:

{% code lineNumbers="true" %}

```json
{
    "email": "joe.bloggs@wearepatchworks.com",
    "password": "mypassword123*"
}
```

{% endcode %}

A successful response returns a token. Tokens are valid for 24 hours.

{% hint style="info" %}
For detailed information about obtaining tokens, please see [Obtaining a token for Patchworks API authentication](https://doc.wearepatchworks.com/product-documentation/developer-hub/patchworks-core-api/core-api-authentication/oauth-2-client-credentials).
{% endhint %}

## Required cross reference details

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

<table><thead><tr><th width="224">Parameter</th><th>Summary</th></tr></thead><tbody><tr><td><code>{{id}}</code></td><td>The unique identifier associated with the cross-reference lookup.</td></tr><tr><td><code>{{valueID}}</code></td><td>The unique identifier associated with the cross-reference lookup row (also known as a m<strong>apping row</strong>).</td></tr></tbody></table>

### id

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

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F09wDzWV9TGrXPvG5YsGj%2Fcross%20ref%20lookup%20id%20example.png?alt=media&#x26;token=496cd13e-e6d3-4e15-a587-cc54884483fd" alt=""><figcaption></figcaption></figure>

### valueId

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

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FAhnBbqoC4PTBH0ILb4ic%2Fcross%20ref%20lookup%20valueId%20example.png?alt=media&#x26;token=f2a45881-6026-4916-b2cc-c5ea4cda7a80" alt=""><figcaption></figcaption></figure>

## Lookups API

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FpvVoazvu3bHKLr0Byk3D%2Fget.png?alt=media&#x26;token=4e5d1c3b-01a6-4401-853e-b9e5f5177be0" alt="" data-size="line"> Retrieve a list all cross-reference lookups</summary>

**Summary**

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

**URL**

{% code overflow="wrap" lineNumbers="true" %}

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

{% endcode %}

**Required headers**

`Authorization` : Bearer token

**Sample request**

{% code lineNumbers="true" %}

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

{% endcode %}

**Sample response (200 OK)**

{% code lineNumbers="true" %}

```json
{
    "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": "&laquo; Previous",
                "active": false
            },
            {
                "url": "http://core.wearepatchworks.com/api/v1/cross-reference-lookups?page=1",
                "label": "1",
                "active": true
            },
            {
                "url": null,
                "label": "Next &raquo;",
                "active": false
            }
        ],
        "path": "http://core.wearepatchworks.com/api/v1/cross-reference-lookups",
        "per_page": 50,
        "to": 5,
        "total": 5
    }
}
```

{% endcode %}

</details>

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FpvVoazvu3bHKLr0Byk3D%2Fget.png?alt=media&#x26;token=4e5d1c3b-01a6-4401-853e-b9e5f5177be0" alt="" data-size="line"> Retrieve a single cross-reference lookup</summary>

**Summary**

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

**URL**

{% code lineNumbers="true" %}

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

{% endcode %}

**Required headers**

`Authorization` : Bearer token

**Sample request**

{% code lineNumbers="true" %}

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

{% endcode %}

**Sample response (200 OK)**

{% code lineNumbers="true" %}

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

{% endcode %}

</details>

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FcD1TwCAMeB3AXiUNp0k9%2FPOST%20b.png?alt=media&#x26;token=d08af0ea-dabe-4b87-a4b9-f8638926c59e" alt="" data-size="line"> Create a new cross-reference lookup</summary>

**Summary**

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

**URL**

{% code lineNumbers="true" %}

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

{% endcode %}

**Required headers**

`Authorization` : Bearer token

**Body parameters**

* `name` (required) (string)
* `description` (required) (string)
* `default_value` (optional) (string)

Example:

{% code lineNumbers="true" %}

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

{% endcode %}

**Sample request**

{% code lineNumbers="true" %}

```bash
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"
}'
```

{% endcode %}

**Sample response (200 OK)**

{% code lineNumbers="true" %}

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

{% endcode %}

</details>

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FFn5IxgRIGwoLNa87yovw%2Fpatch2A.png?alt=media&#x26;token=1718ff1e-8d99-4c02-96ae-6485394f6b20" alt="" data-size="line"> Update a cross-reference lookup</summary>

**Summary**

Update basic details for a cross-reference lookup for your organisation. &#x20;

**URL**

{% code lineNumbers="true" %}

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

{% endcode %}

**Required headers**

`Authorization` : Bearer token

**Body parameters**

* `name` (optional) (string)
* `description` (optional) (string)
* `default_value` (optional) (string)

<img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F3XunX6DbnKf6wRfDulWp%2Ficons8-info%20(3).svg?alt=media&#x26;token=ddeb7ae5-d7c7-46f5-baf3-55a3d5b1478f" alt="" data-size="line"> At least one parameter must be passed into the request.

Example:

{% code lineNumbers="true" %}

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

{% endcode %}

**Sample request**

{% code lineNumbers="true" %}

```bash
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"
}'
```

{% endcode %}

**Sample response (200 OK)**

{% code lineNumbers="true" %}

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

{% endcode %}

</details>

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FzMO596y6h7d8bTTUWwmb%2FDELETE%20B.png?alt=media&#x26;token=c7833d46-c455-44ac-870a-a825cb0b24e5" alt="" data-size="line"> Delete a cross-reference lookup</summary>

**Summary**

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

**URL**

{% code lineNumbers="true" %}

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

{% endcode %}

**Required headers**

`Authorization` : Bearer token

**Sample request**

{% code lineNumbers="true" %}

```bash
curl -X DELETE "https://

```

{% endcode %}

**Sample response (200 OK)**

{% code lineNumbers="true" %}

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

{% endcode %}

</details>

## Lookup rows API

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FpvVoazvu3bHKLr0Byk3D%2Fget.png?alt=media&#x26;token=4e5d1c3b-01a6-4401-853e-b9e5f5177be0" alt="" data-size="line"> Retrieve a list of mapping row values for a cross-reference lookup</summary>

**Summary**

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

**URL**

{% code lineNumbers="true" %}

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

{% endcode %}

**Required headers**

`Authorization` : Bearer token

**Sample request**

{% code lineNumbers="true" %}

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

{% endcode %}

**Sample response (200 OK)**

{% code lineNumbers="true" %}

```json
{
    "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": "&laquo; 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 &raquo;",
                "active": false
            }
        ],
        "path": "http://core.wearepatchworks.com/api/v1/cross-reference-lookups/7/cross-reference-lookup-values",
        "per_page": 50,
        "to": 12,
        "total": 12
    }
}
```

{% endcode %}

</details>

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FpvVoazvu3bHKLr0Byk3D%2Fget.png?alt=media&#x26;token=4e5d1c3b-01a6-4401-853e-b9e5f5177be0" alt="" data-size="line"> Retrieve mapping row values for a specific row within a cross-reference lookup</summary>

**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**

{% code lineNumbers="true" %}

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

{% endcode %}

**Required headers**

`Authorization` : Bearer token

**Sample request**

<pre class="language-bash" data-line-numbers><code class="lang-bash">curl -X GET "https://app.wearepatchworks.com/core-main/api/v1/cross-reference-lookups/7/cross-reference-lookup-values/557
<strong>-H "Authorization: Bearer e1234&#x26;FSKFJmytoken"
</strong></code></pre>

**Sample response (200 OK)**

{% code lineNumbers="true" %}

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

{% endcode %}

</details>

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FcD1TwCAMeB3AXiUNp0k9%2FPOST%20b.png?alt=media&#x26;token=d08af0ea-dabe-4b87-a4b9-f8638926c59e" alt="" data-size="line"> Create a new mapping row for a cross-reference lookup</summary>

**Summary**

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

**URL**

{% code lineNumbers="true" %}

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

{% endcode %}

**Required headers**

`Authorization` : Bearer token

**Body parameters**

* `left_value` (required) (string)
* `right_value` (required) (string)

Example:

{% code lineNumbers="true" %}

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

{% endcode %}

**Sample request**

{% code lineNumbers="true" %}

```bash
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"
}'
```

{% endcode %}

**Sample response (200 OK)**

{% code lineNumbers="true" %}

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

{% endcode %}

</details>

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FFn5IxgRIGwoLNa87yovw%2Fpatch2A.png?alt=media&#x26;token=1718ff1e-8d99-4c02-96ae-6485394f6b20" alt="" data-size="line"> Update a mapping row for a cross-reference lookup</summary>

**Summary**

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

**URL**

{% code lineNumbers="true" %}

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

{% endcode %}

**Required headers**

`Authorization` : Bearer token

**Body parameters**

* `left_value` (optional) (string)
* `right_value` (optional) (string)

<img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F3XunX6DbnKf6wRfDulWp%2Ficons8-info%20(3).svg?alt=media&#x26;token=ddeb7ae5-d7c7-46f5-baf3-55a3d5b1478f" alt="" data-size="line"> At least one parameter must be passed into the request.

Example:

{% code lineNumbers="true" %}

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

{% endcode %}

**Sample request**

{% code lineNumbers="true" %}

```bash
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"
}'
```

{% endcode %}

**Sample response (200 OK)**

{% code lineNumbers="true" %}

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

{% endcode %}

</details>

<details>

<summary><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FzMO596y6h7d8bTTUWwmb%2FDELETE%20B.png?alt=media&#x26;token=c7833d46-c455-44ac-870a-a825cb0b24e5" alt="" data-size="line"> Delete a mapping row for a cross-reference lookup</summary>

**Summary**

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

**URL**

{% code lineNumbers="true" %}

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

{% endcode %}

**Required headers**

`Authorization` : Bearer token

**Sample request**

{% code lineNumbers="true" %}

```bash
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"
```

{% endcode %}

**Sample response (200 OK)**

{% code lineNumbers="true" %}

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

{% endcode %}

</details>

## Related information

* [Core API](https://doc.wearepatchworks.com/product-documentation/developer-hub/patchworks-core-api/core-api-spotlights/broken-reference)