> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/saas-applications/ziphq.md).
# ZipHQ
The ZipHQ integration lets you connect your procurement platform to Harmony and sync data automatically. Once connected, Harmony pulls vendor details, contract terms, contract values, and renewal dates directly into the Contracts tab - no manual entry required. Harmony also syncs your ZipHQ user roster and each user's daily activity, so ZipHQ itself can be tracked as a managed application alongside the rest of your IT footprint.
Harmony only reads from ZipHQ. It never creates, modifies, or deletes anything in your ZipHQ account.
***
### Prerequisites
Before connecting ZipHQ to Harmony, make sure you have:
* An active ZipHQ account with access to your organization's contract, vendor, and user data.
* A ZipHQ API key. Keys are created by an Administrator, or by a user with the **Manage company API keys** permission - see [Step 1](#step-1-create-a-ziphq-api-key) below.
* A **Zip Premier** subscription, if you want ZipHQ activity data. ZipHQ requires Zip Premier to export audit trail events, which is where Harmony's ZipHQ activity data comes from. Contract and user syncs work without it.
* The appropriate permissions in Harmony to manage integrations.
{% hint style="warning" %}
**ZipHQ and NetSuite overlap.** Both systems track vendor and purchase information, so connecting both can produce duplicate contract and spend records on the Contracts page. Harmony warns you before connecting if the other one is already connected - you can still connect both and manage the duplicates manually.
{% endhint %}
***
### Connect ZipHQ to Harmony
#### Step 1: Create a ZipHQ API key
1. Log in to ZipHQ and click the **gear icon** at the top of the page.
2. Select **Company settings**.
3. In the Company Settings menu on the left-hand side, find the **Setup** section and click **API**.
4. Open the **API keys** tab and click **+ Create API key**.
5. Give the key a name and choose the key type:
* **Standard** - an unrestricted key that can read and write on all ZipHQ API endpoints.
* **Restricted** - a key limited to the record types you select, with **Read only** or **Read and write** access per record type. Harmony only reads, so **Read only** is enough. Grant read access to the record types covering **agreements**, **purchase orders**, **users**, and **audit logs (event logs)** - these are the only ZipHQ endpoints Harmony calls. Leave every other record type blank.
6. Optionally set an expiration date (`MM/DD/YYYY`). The field is optional; if you set one, choose a date at least a year out and plan to rotate the key before it lapses.
7. Click **Create**, then copy the API key token immediately and store it securely - ZipHQ does not show the full token again once you close the dialog.
{% hint style="warning" %}
**Deleting or expiring a key breaks the sync immediately.** Deleting an API key in ZipHQ is immediate and permanent, and any request made with a deleted or expired key fails with a `401` error straight away. If you rotate the key, paste the new one into Harmony as soon as it is created.
{% endhint %}
#### Step 2: Enter the key in Harmony
1. Log in to your Harmony dashboard.
2. Navigate to **Settings** > **Integrations**.
3. Find **ZipHQ** under **Procurement** and click **Connect**.
4. Enter your ZipHQ API key in the field provided.
5. Click **Save** to confirm the connection.
Once connected, Harmony begins pulling your ZipHQ data. Vendor details, contract terms, values, and renewal dates appear in the **Contracts** tab, and your user roster and activity are collected on their own schedules - see [Ongoing Sync Behavior](#ongoing-sync-behavior).
***
### What Syncs from ZipHQ
Harmony runs three separate syncs against ZipHQ: contracts, users, and activity.
#### Contracts
Sourced from your ZipHQ agreements and the purchase orders linked to them, and shown in the Harmony **Contracts** tab.
| Field | Description |
| ------------------------ | -------------------------------------------------------------------------------------- |
| Vendor details | The name and ID of the vendor on the agreement. |
| Contract name and number | The agreement's name and agreement number. |
| Status | The agreement status as recorded in ZipHQ. |
| Contract value | The agreement amount and its currency. |
| Contract terms | Start date, end date, and execution date. |
| Renewal details | Renewal date, renewal status, renewal alert date, auto-renewal flag, and opt-out date. |
| Ownership and org data | Agreement owner, department, subsidiaries, and categories. |
| Purchase orders | The purchase orders linked to the agreement, including their line items. |
| Attachments | The documents attached to the agreement in ZipHQ. |
#### Users
Sourced from your ZipHQ user list.
| Field | Description |
| ------------------------- | ------------------------------------------------------------- |
| Name and email | First and last name, and email address. |
| Status | Whether the user is active or deactivated in ZipHQ. |
| Department and subsidiary | The department and subsidiary assigned to the user. |
| Manager | The email address of the user's manager. |
| Permission groups | The names of the ZipHQ permission groups the user belongs to. |
| SSO enforcement | Whether SSO is enforced for the user. |
Both active and deactivated users are synced, so deactivated accounts stay visible for access reviews.
#### Activity
| Field | Description |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Daily activity | One record per user per day on which they took an action in ZipHQ, carrying the user's email and name and the channel the action came through. |
{% hint style="info" %}
**How ZipHQ activity is measured.** Harmony reads ZipHQ's audit trail, keeps only human-initiated actions - those taken through the ZipHQ web app or through Slack - and collapses them into a single record per user per day. This captures real usage even when someone has a persistent session and never triggers a fresh sign-in event. It is a presence signal rather than a count: a user who filed forty requests and a user who opened one page each produce one record for that day.
On the first activity sync, Harmony backfills the previous 30 days.
{% endhint %}
{% hint style="warning" %}
**Activity data requires Zip Premier.** ZipHQ requires a Zip Premier subscription to export audit trail events. Without Premier, contracts and users still sync but no ZipHQ activity data is collected.
{% endhint %}
***
### Ongoing Sync Behavior
Harmony keeps your ZipHQ data up to date automatically - you do not need to manually trigger a refresh.
| Sync | Frequency | Behavior |
| --------- | -------------- | ---------------------------------------------------------------------------------------- |
| Contracts | Every 24 hours | Full refresh - all agreements and purchase orders are re-read each cycle. |
| Users | Every 6 hours | Full refresh - the entire user list is re-read each cycle. |
| Activity | Every 6 hours | Incremental - only audit events newer than the last one already collected are requested. |
Any change made in ZipHQ - an updated renewal date, a revised contract value, a deactivated user - is reflected in Harmony on the next cycle for that sync.
***
### Disconnect ZipHQ
To remove the ZipHQ integration:
1. In Harmony, go to **Settings** and open the **Integrations** section.
2. Find **ZipHQ** in your connected integrations and click **Disconnect**.
3. Confirm the action when prompted.
After disconnecting, Harmony will stop syncing data from ZipHQ. Previously synced contract records will remain in the Contracts tab until you choose to remove them.
To also revoke Harmony's access on the ZipHQ side, delete the API key under **Company settings** > **Setup** > **API** > **API keys**.
***
### Troubleshooting
No data appears after connecting
**Possible causes:**
* The first sync cycle has not run yet - contracts refresh every 24 hours, users and activity every 6 hours
* The API key is Restricted and does not grant read access to the record types Harmony reads
* The API key was deleted or has expired in ZipHQ
**Solutions:**
1. Wait for the next sync cycle to complete
2. In ZipHQ, go to **Company settings** > **Setup** > **API** > **API keys** and confirm the key is still listed and has not expired
3. If the key is Restricted, confirm it grants read access to agreements, purchase orders, users, and audit logs - or replace it with a Standard key
4. Re-enter the key in Harmony under **Settings** > **Integrations** > **ZipHQ**
Contracts and users sync, but no activity data appears
**Possible causes:**
* Your ZipHQ account is not on Zip Premier, which ZipHQ requires for exporting audit trail events
* The API key is Restricted and does not grant read access to audit logs (event logs)
* Nobody performed a human-initiated action in the synced period - only actions taken through the ZipHQ web app or through Slack are counted
**Solutions:**
1. Contact your Zip CSM to confirm whether your account includes Zip Premier
2. Grant the API key read access to audit logs, or replace it with a Standard key
ZipHQ rejects Harmony's requests
**Possible causes:**
* The API key was deleted or expired - ZipHQ deletion is immediate and permanent, and requests then fail with `401`
* The user account the API key belongs to does not have read permissions for the records Harmony reads - a ZipHQ key carries its owning user's permissions in addition to the key's own access settings
**Solutions:**
1. Create a new API key in ZipHQ and paste it into Harmony under **Settings** > **Integrations** > **ZipHQ**
2. Confirm the user who owns the key has read access to agreements, purchase orders, users, and audit logs in ZipHQ
***
### Data & Privacy
Key privacy principles
For information about how Harmony handles your data, see our [Privacy Policy](https://harmony.io/privacy).
* Harmony accesses ZipHQ data in read-only mode and does not create, modify, or delete anything in your ZipHQ account
* Harmony reads four ZipHQ data sets only: agreements, purchase orders, users, and audit trail event logs
* The user data Harmony stores is limited to the fields listed under [What Syncs from ZipHQ](#what-syncs-from-ziphq) - name, email, active status, department, subsidiary, manager email, permission group names, and whether SSO is enforced
* Activity is stored as one record per user per day. The IP addresses that ZipHQ returns on audit events are not stored
* Access can be revoked at any time by deleting the API key in ZipHQ or by disconnecting the integration in Harmony
***
### Related Articles
* [NetSuite](/integrations/saas-applications/netsuite.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://docs.harmony.io/integrations/saas-applications/ziphq.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.