# Working with cross-reference lookup API requests ## Introduction The Patchworks API can be used to add and manage [cross-reference lookups](/product-documentation/process-flows/cross-reference-lookups/adding-a-cross-reference-lookup.md). 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](/product-documentation/developer-hub/patchworks-core-api/core-api-authentication/oauth-2-client-credentials.md). {% endhint %} ## Required cross reference details The Patchworks cross-reference lookup API accepts two identifiers as parameters:
ParameterSummary
{{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** {% 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": "« 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 } } ``` {% endcode %}
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** {% 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 %}
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** {% 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 %}
Update a cross-reference lookup **Summary** Update basic details for a cross-reference lookup for your organisation. **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) 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 %}
Delete a cross-reference lookup **Summary** Remove a cross-reference lookup (and all associated row values) for your organisation. **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 %}
## 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** {% 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": "« 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 } } ``` {% endcode %}
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** {% 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** 
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)** {% code lineNumbers="true" %} ```json { "data": { "id": 557, "left_value": "August", "right_value": "Aug" } } ``` {% endcode %}
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** {% 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 %}
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** {% 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) 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 %}
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** {% 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 %}
## Related information * [Core API](broken://pages/EVn1AesQJtjyoIw7p0HZ) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://doc.wearepatchworks.com/product-documentation/developer-hub/patchworks-core-api/core-api-spotlights/working-with-cross-reference-lookup-api-requests.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.