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

# Zip

> Send Zip procurement requests that need legal review into a Chamelio flow, using a Zip API key and a custom app built in Zip App Studio.

On request

Zip is turned on per organization. If you don't see **Zip** in **Settings** > **Org Integrations**, ask your Chamelio legal engineer to turn it on.

Zip connects your procurement intake to legal. When a Zip request reaches the legal step of its approval workflow, Zip starts a Chamelio flow with the request's details. Legal reviews, negotiates and approves in Chamelio, while procurement keeps working in Zip. Comments sync both ways, so questions and answers reach the other team without email.

## How it works

The connection has a Chamelio side and a Zip side:

| Where | What you set up | Who does it |
| - | - | - |
| Zip | A Zip API key for Chamelio | A Zip admin |
| Chamelio | Connect Zip with that key, and a flow whose intake starts from **Zip** | A Chamelio Admin |
| Chamelio | A Chamelio API key that Zip uses to start the flow | A Chamelio Admin |
| Zip | A custom app in Zip App Studio that starts the Chamelio flow, placed in your Zip approval workflow | A Zip admin, with your Chamelio legal engineer |
| Zip | A webhook that sends new comments on Zip requests to Chamelio | A Zip admin |

When it runs:

1. A Zip request reaches the approval step where your custom app sits.
2. The app reads the request and calls Chamelio to start your Zip flow. The request's answers fill the flow's intake fields, and its files come along as attachments.
3. Chamelio links the task to the Zip request through the **ZIP Request ID** and **ZIP Workflow ID** intake fields.
4. Legal works the task in Chamelio, as in any other [flow](https://docs.chamelio.ai/guides/how-flows-and-tasks-work.md).
5. Comments sync both ways: comments on the Chamelio task are posted on the Zip request, and comments added in Zip appear on the Chamelio task.

## Before you start

* Zip turned on for your organization by your Chamelio legal engineer
* A Chamelio account with Admin permission
* A Zip admin, or a Zip user in the **Manage company API keys** permission group
* Zip App Studio on your Zip plan, to build the custom app

## Step 1: Create a Zip API key

Your Zip admin does this in Zip:

**1. Open the API settings**

In Zip, click the gear icon at the top of the page and select **Company settings**. Under **Setup**, click **API**.

**2. Create the key**

On the **API keys** tab, click **+ Create API key**. Give it a name, for example `Chamelio`.

**3. Copy the key**

Click **Create** and copy the key from the **Save API key** dialog. Zip shows the full key only once.

## Step 2: Connect Zip in Chamelio

**1. Open Org Integrations**

In Chamelio, go to **Settings** > **Org Integrations**.

**2. Enter the API key**

On the **Zip** card, click **Connect**. In **Connect Zip**, paste the key into **API Key** and click **Connect**.

![Zip card in Org Integrations with the Zip logo, a short description and a Connect button](https://mintcdn.com/chamelio/3CGo5DV87eS7IEga/assets/integrations/zip/zip-card.png?fit=max\&auto=format\&n=3CGo5DV87eS7IEga\&q=85\&s=cc664c36e6f57d15b1a039f367b2d0f7)

The Zip card in Settings > Org Integrations

Connect with a key that belongs to a shared company account, not a person's own account, so the connection keeps working when people leave. See [Use a shared IT account](https://docs.chamelio.ai/guides/integrations/summary.md#use-a-shared-it-account-for-organization-connections).

## Step 3: Build the Zip flow in Chamelio

**1. Start the flow from Zip**

Open the flow in the flow builder. In the **Intake** step, select **Zip** under **Start from...**. The intake gets the **ZIP Request ID** and **ZIP Workflow ID** fields, which link each task to its Zip request.

**2. Add the fields Zip sends**

Add an intake field for each value the Zip request sends, such as the supplier name, the amount or the vendor's paper. Note each field's name: the custom app sends values by these names.

**3. Build and publish**

Add the review, approval and signature steps legal needs, then publish the flow. Only published flows can be started from Zip.

See [Intake](https://docs.chamelio.ai/features/flows/intake.md) for the intake settings.

## Step 4: Create a Chamelio API key

The Zip app calls the Chamelio API with its own key. In Chamelio, go to **Settings** > **Developer**, open the **API Key** tab and click **Create API Key**. Copy the key for the next step. See [API keys](https://docs.chamelio.ai/api-reference/api-keys.md).

## Step 5: Build the custom app in Zip App Studio

In Zip App Studio, your Zip admin builds a custom app that starts the Chamelio flow. Your Chamelio legal engineer can build it with you. A typical app has these steps:

| Step in App Studio | What it does |
| - | - |
| **Approval node task** (trigger) | Runs when a request reaches the approval step where the app is placed |
| **Get request** (Zip) | Reads the request's answers, supplier and files |
| **Send HTTP request** | Calls Chamelio with a **Chamelio connection** that holds the Chamelio API key. The base URL is `https://platform.chamelio.ai/` |
| Condition and **Download files** loop | Sends the request's files, such as the vendor's paper, to Chamelio when there are any |

![Zip App Studio canvas with an Approval node task trigger, a Get request step, a Send HTTP request step using a Chamelio connection, a condition and a Download files loop](https://mintcdn.com/chamelio/3CGo5DV87eS7IEga/assets/integrations/zip/zip-app-studio-flow.png?fit=max\&auto=format\&n=3CGo5DV87eS7IEga\&q=85\&s=17770084fbc57be4931d464b9496ebc9)

A Zip App Studio custom app that starts a Chamelio flow from a Zip approval step

The **Send HTTP request** step starts the flow with [Initiate Workflow](https://docs.chamelio.ai/api-reference/endpoint/workflows/initiate.md): `POST /workflows/{workflow_id}/{version}/initiate`, with the key in the `X-API-Key` header. Send the Zip request ID and workflow ID along with the intake fields from Step 3.

When the app is ready, place it in your Zip approval workflow at the point where legal review belongs, for example for new suppliers or purchases above a threshold.

## Step 6: Sync comments with a Zip webhook

Comments from Chamelio reach Zip through the Zip API key you connected in Step 2. For comments made in Zip to reach Chamelio, your Zip admin adds a webhook in Zip:

**1. Get the webhook URL**

Ask your Chamelio legal engineer for your organization's Zip webhook URL.

**2. Add the webhook in Zip**

In Zip, go to **Company settings** > **API** and add a webhook with that URL. Subscribe it to comment events on requests.

Comments then appear on the Chamelio task of the request they were made on. Comments made on a Chamelio task appear on its Zip request.

## Test the connection

Before you turn it on for everyone, submit a test request in Zip that reaches the legal step. Check that:

* A task for your Zip flow appears in Chamelio, with the intake fields filled from the request
* The **ZIP Request ID** matches the request in Zip
* The request's files are attached to the task
* A comment added in Zip appears on the task, and a comment on the task appears on the Zip request

## Common questions

> [accordion] Who can see Zip flows in Chamelio?
>
> Zip flows start from Zip, so they don't appear on the **Flows** page for Members and Viewers. Requesters submit through Zip. See [Who can see and do what](https://docs.chamelio.ai/guides/who-can-see-and-do-what.md).

> [accordion] How do I change the Zip API key?
>
> Create a new key in Zip, then connect Zip again in **Settings** > **Org Integrations** with the new key.
