> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runalloy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Passthrough API

> Passthrough APIs are designed to afford an ISV flexibility when accessing endpoints not directly supported within any of Alloy's connectors. With Passthrough API, you can also access the raw data returned by the endpoints supported by Alloy.

## Example Scenario

Consider an ISV that has built an integration to Shopify using Alloy. This ISV is now looking to extend the functionality of its platform for its end-users. To do so, the ISV requires access to Shopify's `GET /admin/api/2023-10/draft_orders.json` endpoint. Without Passthrough API, the ISV would be out of luck as this endpoint is not supported within Alloy’s Shopify connector.

Fortunately, Passthrough API solves this problem. With Passthrough APIs, the ISV can specify the raw `http` path to make a call to using the end-user's underlying authentication.

## Implementation

### Making a Request

To forward a request, use the following curl command:

```sh cURL theme={null}
curl --location 'https://embedded.runalloy.com/2024-03/passthrough?credentialId={{END_USER_SHOPIFY_CREDENTIAL_ID}}' \
--header 'Authorization: Bearer {{YOUR_API_KEY}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "method": "GET",
  "path": "/admin/api/2023-10/draft_orders.json",
  "body": null,
  "query": null,
  "extraHeaders": null
}'
```

**Parameters Explained**

* `method`: (required) The HTTP method of the Passthrough APIs you're trying to make (i.e. GET, POST)
* `path`: (required) The relative path of the endpoint to call (i.e. `/admin/api/2024-04/draft_orders.json`)
* `extraHeaders`: (optional) Any headers to send along with the request. Must be in a stringified JSON format. Pass `null` if not sending anything.
* `query`: (Optional) Any query parameters for the request. Pass `null` if not sending anything.
* `body`: (Optional) Any body parameters for the request. Must be in a stringified JSON format. Pass `null` if not sending anything.

### More Advanced Example

The example below uses the Shopify API to create a new customer using Passthrough APIs. Note that the Passthrough API only accepts `POST` requests.

```sh cURL theme={null}
curl --location 'https://embedded.runalloy.com/2024-03/passthrough?credentialId={{END_USER_SHOPIFY_CREDENTIAL_ID}}' \
--header 'Authorization: Bearer {{YOUR_API_KEY}}' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
  "method": "POST",
  "path": "/admin/api/2023-10/customers.json",
  "body": {
    "customer": {
    "id": 1073339469,
    "email": "steve.lastnameson@example.com",
    "accepts_marketing": false,
    "created_at": "2023-12-11T10:28:27-05:00",
    "updated_at": "2023-12-11T10:28:27-05:00",
    "first_name": "Steve",
    "last_name": "Lastnameson",
    "orders_count": 0
    }
  },
  "query": null,
  "extraHeaders": null
}'
```

## Receiving a Response

Returning to our Shopify example, once invoked, the Passthrough API uses the underlying credential you supplied (via the `credentialId`). The passthrough API will then return the raw data from Shopify's `/admin/api/2023-10/draft_orders.json` endpoint as seen below. Alloy Unified API will return the relevant `headers`, `statusCode`, and `data`.

```javascript JavaScript theme={null}
{
    "request": {
        "headers": null,
        "method": "GET",
        "path": "/admin/api/2023-10/draft_orders.json",
        "data": null,
        "params": null
    },
    "headers": {
        ...
        // Detailed response headers
    },
    "statusCode": 200,
    "data": {
        ...
        // Parsed raw data from Shopify
    }
}
```

## Connectors Supported by Passthrough API

Passthrough API is currently available for the following connectors:

* Aircall
* Asana
* Aspire
* Attentive Legacy
* Attentive
* Avalara
* Best Buy
* BigCommerce
* BrightPearl
* Clearbit
* Salesforce Commerce Cloud
* Customer IO
* Endear
* Facebook Ads
* Freshdesk
* Gorgias
* Hubspot
* Inveterate
* Klaviyo
* LoyaltyLion
* Magento
* Mailchimp
* MS Business Central
* Mintsoft
* Okendo
* Omnisend
* Picquer
* Postscript
* Push Owl
* ReCharge
* Retention Science
* Retently
* Salesforce CRM
* SAP S/4 Hana
* Shipbob
* ShipHero
* ShipStation
* Shopify
* Slack
* Smile IO
* Stamped IO
* Stripe
* WooCommerce
* Xero
* Yotpo
* Yotpo Loyalty
* Zendesk
* Zoho CRM