Zip
App · 24 actions
Work with Zip procurement: find and update requests, reject or cancel them, follow approvals, manage vendors, read purchase orders, invoices and contracts, and post comments.
Actions
| Action | What it does |
|---|---|
| Create or update vendor | Create a vendor in Zip under your own vendor ID, or update the vendor that already has it. |
| Delete comment | Delete a comment, as the Zip user who deletes it. |
| Delete vendor | Delete a vendor from Zip for good. |
| Get invoice | Get one invoice with its lines, approvals, matched purchase orders and payments. |
| Get purchase order | Get one purchase order with its lines, invoices, change orders and the request it came from. |
| Get request | Get one request with its amount, line items, vendor, requester, custom fields, purchase order and attachments. |
| Get request questionnaires | Get the questionnaires on a request, such as a security review, with each answer given. |
| Get user | Get one Zip user with their department, entity, manager, roles and permission groups. |
| Get vendor | Get one vendor with its status, contacts, entities, categories and custom fields. |
| List approvals | Find approval steps on requests by request, status, type or date, with who each waits on and when it is due. |
| List comments | List the comments on a request, with who wrote each and when. |
| List contracts | Find contracts (Zip's agreements) by vendor, department or entity, with their dates, amounts and renewal status. |
| List departments | List the departments set up in Zip. |
| List invoices | Find supplier invoices (bills) by number, status, vendor, date or amount. |
| List purchase orders | Find purchase orders by vendor, date or amount still open, with what has been billed against each. |
| List requests | Find purchase and other requests by number, status, type, requester, department, vendor or date, newest first. |
| List users | Find Zip users by email, with their department, manager, roles and permission groups. |
| List vendors | Find vendors by name, status, entity, department or when they last changed. |
| Mark invoice paid | Record that an invoice was paid outside Zip, such as by your ERP or bank, with the day and currency. |
| Post comment | Post a comment on a request or an invoice as a Zip user. |
| Reject or cancel request | Reject or cancel a request, with the reason Zip shows on it and keeps in its audit trail. |
| Send invoice for approval | Check that a draft bill is complete and send it into its approval workflow in Zip. |
| Update request | Change a request's name, description, department, entity, vendor or start and end dates. |
| Update vendor | Change a vendor's name, status, contact emails, risk, tier or entities. |
Create or update vendor
Create a vendor in Zip under your own vendor ID, or update the vendor that already has it.
Inputs
- Your vendor ID
external_idtextRequired - Your own id for the vendor, such as its number in your ERP. A vendor with this id is updated; otherwise a new vendor is made.
- Name
nametextRequired - The vendor's name as people in Zip will see it.
- Legal name
legal_nametext - The vendor's registered company name.
- Status
statustext - Active, Preferred, Inactive or Draft. A new vendor starts as Draft.One of:
1(Active),2(Preferred),3(Inactive),5(Draft). - Currency
currencytext - The vendor's main currency, a three-letter code such as USD.
- Purchase order email
po_emailtext - Where purchase orders for this vendor are sent.
- Remittance email
remittance_emailtext - Where payment notices for this vendor are sent.
- Phone
primary_phonetext - The vendor's main phone number.
- Tax ID
tax_id_numbertext - The vendor's tax identification number.
- Risk
risktext - The vendor's risk rating.One of:
green(Green (low)),yellow(Yellow (medium)),red(Red (high)). - Tier
tiertext - The vendor's tier.One of:
tier_1(Tier 1),tier_2(Tier 2),tier_3(Tier 3),tier_4(Tier 4). - Entities
subsidiary_idslist - The entities (subsidiaries) that may buy from this vendor.
Outputs
vendorobject- The vendor
Example output
{
"vendor": {
"address": {
"country": "US",
"lines": [
"123 Main St"
],
"locality": "San Francisco",
"postcode": "94105",
"region": "US-CA"
},
"attributes": [],
"categories": [
{
"id": "89f7777d-9c5f-4f93-914e-a9ccc60b829c",
"name": "Software"
}
],
"contacts": [],
"created_at": 1791000000,
"currency": "USD",
"department": {
"id": "0667b662-49a0-7dfb-8000-96ab361b9856",
"name": "Engineering"
},
"description": "Office and design supplies.",
"external_id": "V-10042",
"id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
"legal_name": "Acme Supplies LLC",
"name": "Acme Supplies",
"po_email": "orders@example.com",
"primary_phone": "+1 415 555 0100",
"remittance_email": "billing@example.com",
"risk": "green",
"status": 1,
"subsidiaries": [
{
"id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
"name": "Acme Inc."
}
],
"tier": "tier_2",
"updated_at": 1792086400,
"website_link": "https://example.com"
}
}Delete comment
Delete a comment, as the Zip user who deletes it.
Inputs
- Comment ID
comment_idtextRequired - The comment's id, from 'List comments' or 'Post comment'.
- Deleted by
deleted_by_idtextRequired - The Zip user deleting it, usually whoever posted it.
Outputs
comment_idtext- The comment deleted
deletedtrue/false- True once deleted
Example output
{
"comment_id": "0a1b2c3d-4e5f-4061-8728-394a5b6c7d8e",
"deleted": true
}Delete vendor
Delete a vendor from Zip for good. Unlike setting it to Inactive, this cannot be undone.
Inputs
- Vendor
vendor_idtextRequired - The vendor. Pick one, or give its id from an earlier step.
Outputs
deletedtrue/false- True once deleted
vendor_idtext- The vendor deleted
Example output
{
"deleted": true,
"vendor_id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c"
}Get invoice
Get one invoice with its lines, approvals, matched purchase orders and payments.
Inputs
- Invoice ID
invoice_idtextRequired - The invoice's id (not the supplier's invoice number), from 'List invoices' or an earlier step.
Outputs
invoiceobject- The invoice
Example output
{
"invoice": {
"amount": "12000.00",
"amount_usd": "12000.00",
"approvals": [],
"approved_at": 0,
"assignee": {
"email": "jo@example.com",
"first_name": "Jo",
"id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
"last_name": "Bloggs"
},
"created_at": 1794528000,
"currency": "USD",
"department": {
"id": "0667b662-49a0-7dfb-8000-96ab361b9856",
"name": "Engineering"
},
"description": "Design tool licences, year one",
"due_date": 1797120000,
"due_date_iso": "2026-12-31",
"id": "9c0d1e2f-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
"invoice_date": "2026-12-01",
"invoice_number": "INV-7781",
"invoice_url": "https://acme.ziphq.com/invoices/9c0d1e2f-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
"line_items": [],
"purchase_orders": [
{
"id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"po_number": "PO-1042"
}
],
"status": "PENDING_APPROVAL",
"subsidiary": {
"id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
"name": "Acme Inc."
},
"updated_at": 1794614400,
"vendor": {
"id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
"name": "Acme Supplies"
}
}
}Get purchase order
Get one purchase order with its lines, invoices, change orders and the request it came from.
Inputs
- Purchase order ID
purchase_order_idtextRequired - The purchase order's id (not its PO number), from 'List purchase orders' or an earlier step.
Outputs
purchase_orderobject- The purchase order
Example output
{
"purchase_order": {
"amount_billed": "0.00",
"created_at": 1792090000,
"currency": "USD",
"department": {
"id": "0667b662-49a0-7dfb-8000-96ab361b9856",
"name": "Engineering"
},
"description": "Design tool licences",
"end_date": "2027-11-30",
"id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"invoices": [],
"last_activity_at": 1792090000,
"line_items": [],
"original_request": {
"id": "1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
"name": "Design tool licences",
"request_number": 1042
},
"payment_frequency": "ANNUAL",
"payment_method": "PURCHASE_ORDER",
"po_number": "PO-1042",
"requester": {
"email": "jo@example.com",
"first_name": "Jo",
"id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
"last_name": "Bloggs"
},
"start_date": "2026-12-01",
"status": 0,
"subsidiary": {
"id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
"name": "Acme Inc."
},
"total_amount": "12000.00",
"total_amount_usd": "12000.00",
"updated_at": 1792090000,
"vendor": {
"id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
"name": "Acme Supplies"
}
}
}Get request
Get one request with its amount, line items, vendor, requester, custom fields, purchase order and attachments.
Inputs
- Request ID
request_idtextRequired - The request's id (not its number), from 'List requests' or an earlier step.
Outputs
requestobject- The request
Example output
{
"request": {
"amount_usd": "12000.00",
"attachments": [
{
"id": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d1e",
"name": "quote.pdf",
"url": "https://acme.ziphq.com/files/quote.pdf"
}
],
"attributes": [
{
"config_id": "63d42e86-147b-4fd7-baa3-d52d7e27494d",
"data": [
"CC-100"
],
"name": "Cost center"
}
],
"category": {
"id": "89f7777d-9c5f-4f93-914e-a9ccc60b829c",
"name": "Software"
},
"completed_at": 0,
"created_at": 1792000000,
"department": {
"id": "0667b662-49a0-7dfb-8000-96ab361b9856",
"name": "Engineering"
},
"description": "Ten seats for the design team.",
"id": "1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
"name": "Design tool licences",
"owner": {
"email": "jo@example.com",
"first_name": "Jo",
"id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
"last_name": "Bloggs"
},
"payment_method": "PURCHASE_ORDER",
"price_detail": {
"currency": "USD",
"id": "3c4d5e6f-7081-4923-ab4c-5d6e7f809102",
"line_items": [],
"total": "12000.00",
"total_usd": "12000.00"
},
"priority": 1,
"purchase_order": {
"id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"po_number": "PO-1042"
},
"request_link": "https://acme.ziphq.com/request/1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
"request_number": 1042,
"request_type": "PURCHASE_REQUEST",
"requester": {
"email": "jo@example.com",
"first_name": "Jo",
"id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
"last_name": "Bloggs"
},
"status": 1,
"subsidiary": {
"id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
"name": "Acme Inc."
},
"updated_at": 1792086400,
"vendor": {
"id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
"name": "Acme Supplies"
},
"workflow": {
"id": "2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091",
"name": "Software"
}
}
}Get request questionnaires
Get the questionnaires on a request, such as a security review, with each answer given.
Inputs
- Request ID
request_idtextRequired - The request's id (not its number), from 'List requests' or an earlier step.
Outputs
countnumber- How many
questionnaireslist- The questionnaires
totalnumber- How many in all
Example output
{
"count": 1,
"questionnaires": [
{
"id": "1b2c3d4e-5f60-4172-8839-4a5b6c7d8e9f",
"name": "Security questionnaire",
"question_responses": [
{
"question_prompt": "Do you hold SOC 2?",
"text": "Yes"
}
],
"status": "COMPLETED",
"vendor": {
"id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
"name": "Acme Supplies"
}
}
],
"total": 1
}Get user
Get one Zip user with their department, entity, manager, roles and permission groups.
Inputs
- User
zip_user_idtextRequired - The Zip user. Pick one, or give their id from an earlier step.
Outputs
userobject- The user
Example output
{
"user": {
"department": {
"id": "0667b662-49a0-7dfb-8000-96ab361b9856",
"name": "Engineering"
},
"email": "jo@example.com",
"first_name": "Jo",
"groups": [
{
"id": "9b4a5f6e-7d8c-4b92-8ca3-c4d5e6f7a8b0",
"name": "Default"
}
],
"id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
"is_active": true,
"last_name": "Bloggs",
"manager": {
"email": "sam@example.com",
"first_name": "Sam",
"id": "7f2e3d4c-5b6a-4f70-9a81-a2b3c4d5e6f8",
"last_name": "Lee"
},
"roles": [
{
"id": "8a3f4e5d-6c7b-4a81-9b92-b3c4d5e6f7a9",
"name": "Manager"
}
],
"subsidiary": {
"id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
"name": "Acme Inc."
}
}
}Get vendor
Get one vendor with its status, contacts, entities, categories and custom fields.
Inputs
- Vendor
vendor_idtextRequired - The vendor. Pick one, or give its id from an earlier step.
Outputs
vendorobject- The vendor
Example output
{
"vendor": {
"address": {
"country": "US",
"lines": [
"123 Main St"
],
"locality": "San Francisco",
"postcode": "94105",
"region": "US-CA"
},
"attributes": [],
"categories": [
{
"id": "89f7777d-9c5f-4f93-914e-a9ccc60b829c",
"name": "Software"
}
],
"contacts": [],
"created_at": 1791000000,
"currency": "USD",
"department": {
"id": "0667b662-49a0-7dfb-8000-96ab361b9856",
"name": "Engineering"
},
"description": "Office and design supplies.",
"external_id": "V-10042",
"id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
"legal_name": "Acme Supplies LLC",
"name": "Acme Supplies",
"po_email": "orders@example.com",
"primary_phone": "+1 415 555 0100",
"remittance_email": "billing@example.com",
"risk": "green",
"status": 1,
"subsidiaries": [
{
"id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
"name": "Acme Inc."
}
],
"tier": "tier_2",
"updated_at": 1792086400,
"website_link": "https://example.com"
}
}List approvals
Find approval steps on requests by request, status, type or date, with who each waits on and when it is due.
Inputs
- Request number
request_numbernumber - Only the approvals on this request, by the number Zip shows.At least 1.
- Status
statustext - Only approvals in this status.One of:
0(Upcoming),1(Ready to start (waiting on the approver)),2(Rejected),3(Approved),4(Approved automatically),5(Canceled),6(Custom status, timer on),7(Custom status, timer off). - Request types
request_typeslist - Only approvals on requests of these types.One or more of:
PURCHASE_REQUEST(Purchase request),SOURCING_PROJECT(Sourcing project),SOURCING_INSTANCE(Sourcing event),SOURCING_REQUEST(Sourcing request),BILL,PAYOUT_GROUP(Payout group),INVOICE_ASSIGNMENT(Invoice assignment),PO_CHANGE_ORDER(PO change order),CHANGE_ORDER(Change order),SECURITY_REVIEW(Security review), and 7 more. - Started after
started_afterdate and time - Only approvals that started after this time.
- Completed after
completed_afterdate and time - Only approvals completed after this time.
- Due after
due_afterdate and time - Only approvals due after this time.
- Due before
due_beforedate and time - Only approvals due before this time, such as now for overdue ones.
- Sort by
sort_bytext - What to sort by. Leave empty for Zip's order.One of:
start_time(When started),complete_time(When completed),due_date(Due date),request_create_time(When the request was created),request_number(Request number). - Order
sort_ordertext - Sort direction, when sorting. Defaults to newest or highest first.One of:
desc(Newest or highest first (default)),asc(Oldest or lowest first). - Page size
page_sizenumber - How many to return, 1 to 100.From 1 to 100.
- Next page token
page_tokentext - The 'next_page_token' from an earlier page, to get the page after it.
Outputs
approvalslist- The approval steps
countnumber- How many on this page
next_page_tokentext- Pass as 'Next page token' for the next page; empty on the last
totalnumber- How many match in all
Example output
{
"approvals": [
{
"assignee": {
"email": "jo@example.com",
"first_name": "Jo",
"id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
"last_name": "Bloggs"
},
"complete_time": 0,
"config_type": "APPROVAL",
"created_at": 1792000000,
"display_status": "Ready to start",
"due_date": 1792259800,
"id": "4d5e6f70-8192-4a3b-bc4d-5e6f708192a3",
"name": "Finance approval",
"node_type": "NODE",
"queue": {
"id": "5e6f7081-92a3-4b4c-8d5e-6f708192a3b4",
"name": "Finance"
},
"request": {
"id": "1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
"name": "Design tool licences",
"request_number": 1042,
"request_type": "PURCHASE_REQUEST",
"status": "AWAITING_APPROVAL"
},
"sla_hours": 72,
"start_time": 1792000600,
"status": 1,
"updated_at": 1792000600
}
],
"count": 1,
"next_page_token": "",
"total": 1
}List comments
List the comments on a request, with who wrote each and when.
Inputs
- Request ID
request_idtextRequired - The request's id (not its number), from 'List requests' or an earlier step.
Outputs
commentslist- The comments
countnumber- How many
totalnumber- How many in all
Example output
{
"comments": [
{
"commenter": {
"email": "jo@example.com",
"first_name": "Jo",
"id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
"last_name": "Bloggs"
},
"created_at": 1792090000,
"deleted": false,
"external_display_name": "Lodol",
"external_url": "",
"id": "0a1b2c3d-4e5f-4061-8728-394a5b6c7d8e",
"text": "Quote attached; please review.",
"text_html": "<p>Quote attached; please review.</p>",
"type": "COMMENT",
"updated_at": 1792090000
}
],
"count": 1,
"total": 1
}List contracts
Find contracts (Zip's agreements) by vendor, department or entity, with their dates, amounts and renewal status.
Inputs
- Vendor
vendor_idtext - Only contracts with this vendor.
- Department
department_idtext - Only contracts of this department.
- Entity
subsidiary_idtext - Only contracts of this entity.
- Sort by
sort_bytext - What to sort by. Leave empty for Zip's order.One of:
created_at(When created (default)),updated_at(When last updated). - Order
sort_ordertext - Sort direction, when sorting. Defaults to newest or highest first.One of:
desc(Newest or highest first (default)),asc(Oldest or lowest first). - Page size
page_sizenumber - How many to return, 1 to 100.From 1 to 100.
- Next page token
page_tokentext - The 'next_page_token' from an earlier page, to get the page after it.
Outputs
contractslist- The contracts
countnumber- How many on this page
next_page_tokentext- Pass as 'Next page token' for the next page; empty on the last
totalnumber- How many match in all
Example output
{
"contracts": [
{
"agreement_number": 311,
"agreement_owner": {
"email": "jo@example.com",
"first_name": "Jo",
"id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
"last_name": "Bloggs"
},
"agreement_status": "ACTIVE",
"agreement_type": "MSA",
"amount": "12000.00",
"auto_renews": true,
"currency": "USD",
"department": {
"id": "0667b662-49a0-7dfb-8000-96ab361b9856",
"name": "Engineering"
},
"end_date": "2027-11-30",
"name": "Acme Supplies master agreement",
"original_request": {
"id": "1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
"name": "Design tool licences",
"request_number": 1042
},
"renewal_date": "2027-11-30",
"renewal_status": "NOT_SCHEDULED",
"start_date": "2026-12-01",
"status": "ACTIVE",
"vendor": {
"id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
"name": "Acme Supplies"
}
}
],
"count": 1,
"next_page_token": "",
"total": 1
}List departments
List the departments set up in Zip.
Inputs
- Name
nametext - Only the department with this name.
- Active
activetrue/false - On for active departments only, off for inactive ones only. Leave empty for both.
- Page size
page_sizenumber - How many to return, 1 to 100.From 1 to 100.
- Next page token
page_tokentext - The 'next_page_token' from an earlier page, to get the page after it.
Outputs
countnumber- How many on this page
departmentslist- The departments
next_page_tokentext- Pass as 'Next page token' for the next page; empty on the last
totalnumber- How many match in all
Example output
{
"count": 1,
"departments": [
{
"created_at": 1780000000,
"display_name": "Engineering",
"hide_in_zip": false,
"id": "0667b662-49a0-7dfb-8000-96ab361b9856",
"is_active": true,
"name": "Engineering",
"updated_at": 1780000000
}
],
"next_page_token": "",
"total": 1
}List invoices
Find supplier invoices (bills) by number, status, vendor, date or amount.
Inputs
- Invoice number
invoice_numbertext - Only invoices with this number, as the supplier wrote it.
- Statuses
statuseslist - Only invoices in any of these statuses.One or more of:
INITIAL(New (not yet sent for approval)),PENDING_APPROVAL(Pending approval),APPROVED,REJECTED,ARCHIVED,PENDING_PAYOUT_APPROVAL(Pending payment approval),PAYOUT_SCHEDULED(Payment scheduled),PAYOUT_INITIATED(Payment started),PAID,PAYOUT_FAILED(Payment failed),PAYOUT_CANCELED(Payment canceled),RECEIPT_HOLD(On hold for receipt). - Vendor
vendor_idtext - Only invoices from this vendor.
- Created after
created_afterdate and time - Only invoices created after this time.
- Updated after
updated_afterdate and time - Only invoices changed after this time.
- Approved after
approved_afterdate and time - Only invoices approved after this time.
- Smallest amount
amount_minnumber - Only invoices of at least this amount.At least 0.
- Largest amount
amount_maxnumber - Only invoices of at most this amount.At least 0.
- Sort by
sort_bytext - What to sort by. Leave empty for Zip's order.One of:
created_at(When created (default)),updated_at(When last updated). - Order
sort_ordertext - Sort direction, when sorting. Defaults to newest or highest first.One of:
desc(Newest or highest first (default)),asc(Oldest or lowest first). - Page size
page_sizenumber - How many to return, 1 to 50.From 1 to 50.
- Next page token
page_tokentext - The 'next_page_token' from an earlier page, to get the page after it.
Outputs
countnumber- How many on this page
invoiceslist- The invoices
next_page_tokentext- Pass as 'Next page token' for the next page; empty on the last
totalnumber- How many match in all
Example output
{
"count": 1,
"invoices": [
{
"amount": "12000.00",
"amount_usd": "12000.00",
"approvals": [],
"approved_at": 0,
"assignee": {
"email": "jo@example.com",
"first_name": "Jo",
"id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
"last_name": "Bloggs"
},
"created_at": 1794528000,
"currency": "USD",
"department": {
"id": "0667b662-49a0-7dfb-8000-96ab361b9856",
"name": "Engineering"
},
"description": "Design tool licences, year one",
"due_date": 1797120000,
"due_date_iso": "2026-12-31",
"id": "9c0d1e2f-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
"invoice_date": "2026-12-01",
"invoice_number": "INV-7781",
"invoice_url": "https://acme.ziphq.com/invoices/9c0d1e2f-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
"line_items": [],
"purchase_orders": [
{
"id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"po_number": "PO-1042"
}
],
"status": "PENDING_APPROVAL",
"subsidiary": {
"id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
"name": "Acme Inc."
},
"updated_at": 1794614400,
"vendor": {
"id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
"name": "Acme Supplies"
}
}
],
"next_page_token": "",
"total": 1
}List purchase orders
Find purchase orders by vendor, date or amount still open, with what has been billed against each.
Inputs
- Vendor
vendor_idtext - Only purchase orders with this vendor.
- PO number
po_numbertext - Only the purchase order with this number. Works only if Zip has turned on extra purchase order search for your company.
- Created after
created_afterdate and time - Only purchase orders created after this time.
- Created before
created_beforedate and time - Only purchase orders created before this time.
- Updated after
updated_afterdate and time - Only purchase orders with activity after this time.
- Open amount over
open_amount_greater_thannumber - Only purchase orders with more than this amount not yet billed.At least 0.
- Include custom fields
include_custom_fieldstrue/false - Also return each record's custom fields. Zip answers more slowly.
- Sort by
sort_bytext - What to sort by. Leave empty for Zip's order.One of:
created_at(When created (default)),updated_at(When last updated). - Order
sort_ordertext - Sort direction, when sorting. Defaults to newest or highest first.One of:
desc(Newest or highest first (default)),asc(Oldest or lowest first). - Page size
page_sizenumber - How many to return, 1 to 50.From 1 to 50.
- Next page token
page_tokentext - The 'next_page_token' from an earlier page, to get the page after it.
Outputs
countnumber- How many on this page
next_page_tokentext- Pass as 'Next page token' for the next page; empty on the last
purchase_orderslist- The purchase orders
totalnumber- How many match in all
Example output
{
"count": 1,
"next_page_token": "",
"purchase_orders": [
{
"amount_billed": "0.00",
"created_at": 1792090000,
"currency": "USD",
"department": {
"id": "0667b662-49a0-7dfb-8000-96ab361b9856",
"name": "Engineering"
},
"description": "Design tool licences",
"end_date": "2027-11-30",
"id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"invoices": [],
"last_activity_at": 1792090000,
"line_items": [],
"original_request": {
"id": "1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
"name": "Design tool licences",
"request_number": 1042
},
"payment_frequency": "ANNUAL",
"payment_method": "PURCHASE_ORDER",
"po_number": "PO-1042",
"requester": {
"email": "jo@example.com",
"first_name": "Jo",
"id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
"last_name": "Bloggs"
},
"start_date": "2026-12-01",
"status": 0,
"subsidiary": {
"id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
"name": "Acme Inc."
},
"total_amount": "12000.00",
"total_amount_usd": "12000.00",
"updated_at": 1792090000,
"vendor": {
"id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
"name": "Acme Supplies"
}
}
],
"total": 1
}List requests
Find purchase and other requests by number, status, type, requester, department, vendor or date, newest first.
Inputs
- Request number
request_numbernumber - The request number Zip shows, such as 1042.At least 1.
- Status
statustext - Only requests in this status.One of:
1(Awaiting approval),2(Rejected),3(Approved),4(Canceled),5(Closed),6(Paused). - Priority
prioritytext - Only urgent or only normal requests.One of:
0(Urgent),1(Normal). - Request type
request_typetext - Only requests of this type.One of:
PURCHASE_REQUEST(Purchase request),SOURCING_PROJECT(Sourcing project),SOURCING_INSTANCE(Sourcing event),SOURCING_REQUEST(Sourcing request),BILL,PAYOUT_GROUP(Payout group),INVOICE_ASSIGNMENT(Invoice assignment),PO_CHANGE_ORDER(PO change order),CHANGE_ORDER(Change order),SECURITY_REVIEW(Security review), and 7 more. - Requester
requester_idtext - Only requests made by this person.
- Departments
department_idslist - Only requests for any of these departments.
- Vendor
vendor_idtext - Only requests for this vendor.
- Created after
created_afterdate and time - Only requests created after this time.
- Created before
created_beforedate and time - Only requests created before this time.
- Updated after
updated_afterdate and time - Only requests changed after this time.
- Completed after
completed_afterdate and time - Only requests completed after this time.
- Include custom fields
include_custom_fieldstrue/false - Also return each record's custom fields. Zip answers more slowly.
- Sort by
sort_bytext - What to sort by. Leave empty for Zip's order.One of:
create_time(When created),last_updated_time(When last updated),complete_time(When completed),request_number(Request number),status. - Order
sort_ordertext - Sort direction, when sorting. Defaults to newest or highest first.One of:
desc(Newest or highest first (default)),asc(Oldest or lowest first). - Page size
page_sizenumber - How many to return, 1 to 30.From 1 to 30.
- Next page token
page_tokentext - The 'next_page_token' from an earlier page, to get the page after it.
Outputs
countnumber- How many on this page
next_page_tokentext- Pass as 'Next page token' for the next page; empty on the last
requestslist- The requests
totalnumber- How many match in all
Example output
{
"count": 1,
"next_page_token": "",
"requests": [
{
"amount_usd": "12000.00",
"attachments": [
{
"id": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d1e",
"name": "quote.pdf",
"url": "https://acme.ziphq.com/files/quote.pdf"
}
],
"attributes": [
{
"config_id": "63d42e86-147b-4fd7-baa3-d52d7e27494d",
"data": [
"CC-100"
],
"name": "Cost center"
}
],
"category": {
"id": "89f7777d-9c5f-4f93-914e-a9ccc60b829c",
"name": "Software"
},
"completed_at": 0,
"created_at": 1792000000,
"department": {
"id": "0667b662-49a0-7dfb-8000-96ab361b9856",
"name": "Engineering"
},
"description": "Ten seats for the design team.",
"id": "1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
"name": "Design tool licences",
"owner": {
"email": "jo@example.com",
"first_name": "Jo",
"id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
"last_name": "Bloggs"
},
"payment_method": "PURCHASE_ORDER",
"price_detail": {
"currency": "USD",
"id": "3c4d5e6f-7081-4923-ab4c-5d6e7f809102",
"line_items": [],
"total": "12000.00",
"total_usd": "12000.00"
},
"priority": 1,
"purchase_order": {
"id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"po_number": "PO-1042"
},
"request_link": "https://acme.ziphq.com/request/1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
"request_number": 1042,
"request_type": "PURCHASE_REQUEST",
"requester": {
"email": "jo@example.com",
"first_name": "Jo",
"id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
"last_name": "Bloggs"
},
"status": 1,
"subsidiary": {
"id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
"name": "Acme Inc."
},
"updated_at": 1792086400,
"vendor": {
"id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
"name": "Acme Supplies"
},
"workflow": {
"id": "2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091",
"name": "Software"
}
}
],
"total": 1
}List users
Find Zip users by email, with their department, manager, roles and permission groups.
Inputs
- Email
emailtext - Only the user with this email address.
- Deactivated
deactivatedtrue/false - On for deactivated users only, off for active users only.
- Sort by
sort_bytext - What to sort by. Leave empty for Zip's order.One of:
created_at(When created (default)),updated_at(When last updated),email. - Order
sort_ordertext - Sort direction, when sorting. Defaults to newest or highest first.One of:
desc(Newest or highest first (default)),asc(Oldest or lowest first). - Page size
page_sizenumber - How many to return, 1 to 100.From 1 to 100.
- Next page token
page_tokentext - The 'next_page_token' from an earlier page, to get the page after it.
Outputs
countnumber- How many on this page
next_page_tokentext- Pass as 'Next page token' for the next page; empty on the last
totalnumber- How many match in all
userslist- The users
Example output
{
"count": 1,
"next_page_token": "",
"total": 1,
"users": [
{
"department": {
"id": "0667b662-49a0-7dfb-8000-96ab361b9856",
"name": "Engineering"
},
"email": "jo@example.com",
"first_name": "Jo",
"groups": [
{
"id": "9b4a5f6e-7d8c-4b92-8ca3-c4d5e6f7a8b0",
"name": "Default"
}
],
"id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
"is_active": true,
"last_name": "Bloggs",
"manager": {
"email": "sam@example.com",
"first_name": "Sam",
"id": "7f2e3d4c-5b6a-4f70-9a81-a2b3c4d5e6f8",
"last_name": "Lee"
},
"roles": [
{
"id": "8a3f4e5d-6c7b-4a81-9b92-b3c4d5e6f7a9",
"name": "Manager"
}
],
"subsidiary": {
"id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
"name": "Acme Inc."
}
}
]
}List vendors
Find vendors by name, status, entity, department or when they last changed.
Inputs
- Name
nametext - Only vendors whose name contains this.
- Statuses
statuseslist - Only vendors in any of these statuses.One or more of:
ACTIVE,PREFERRED,INACTIVE,BANNED,DRAFT. - Entity
subsidiary_idtext - Only vendors of this entity.
- Department
department_idtext - Only vendors of this department.
- Updated after
updated_afterdate and time - Only vendors changed after this time.
- Include custom fields
include_custom_fieldstrue/false - Also return each record's custom fields. Zip answers more slowly.
- Sort by
sort_bytext - What to sort by. Leave empty for Zip's order.One of:
name,created_at(When created),updated_at(When last updated). - Order
sort_ordertext - Sort direction, when sorting. Defaults to newest or highest first.One of:
desc(Newest or highest first (default)),asc(Oldest or lowest first). - Page size
page_sizenumber - How many to return, 1 to 100.From 1 to 100.
- Next page token
page_tokentext - The 'next_page_token' from an earlier page, to get the page after it.
Outputs
countnumber- How many on this page
next_page_tokentext- Pass as 'Next page token' for the next page; empty on the last
totalnumber- How many match in all
vendorslist- The vendors
Example output
{
"count": 1,
"next_page_token": "",
"total": 1,
"vendors": [
{
"address": {
"country": "US",
"lines": [
"123 Main St"
],
"locality": "San Francisco",
"postcode": "94105",
"region": "US-CA"
},
"attributes": [],
"categories": [
{
"id": "89f7777d-9c5f-4f93-914e-a9ccc60b829c",
"name": "Software"
}
],
"contacts": [],
"created_at": 1791000000,
"currency": "USD",
"department": {
"id": "0667b662-49a0-7dfb-8000-96ab361b9856",
"name": "Engineering"
},
"description": "Office and design supplies.",
"external_id": "V-10042",
"id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
"legal_name": "Acme Supplies LLC",
"name": "Acme Supplies",
"po_email": "orders@example.com",
"primary_phone": "+1 415 555 0100",
"remittance_email": "billing@example.com",
"risk": "green",
"status": 1,
"subsidiaries": [
{
"id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
"name": "Acme Inc."
}
],
"tier": "tier_2",
"updated_at": 1792086400,
"website_link": "https://example.com"
}
]
}Mark invoice paid
Record that an invoice was paid outside Zip, such as by your ERP or bank, with the day and currency.
Inputs
- Invoice ID
invoice_idtextRequired - The invoice's id (not the supplier's invoice number), from 'List invoices' or an earlier step.
- Paid on
paid_ondateRequired - The day the invoice was paid.
- Currency
currencytextRequired - The currency it was paid in, a three-letter code such as USD.
- Amount paid
amounttext - How much was paid, such as 1250.00. Leave empty for the invoice's amount.
- Payment reference
referencetext - Your reference for the payment, such as a check or transfer number.
Outputs
invoiceobject- The invoice
Example output
{
"invoice": {
"amount": "12000.00",
"amount_usd": "12000.00",
"approvals": [],
"approved_at": 0,
"assignee": {
"email": "jo@example.com",
"first_name": "Jo",
"id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
"last_name": "Bloggs"
},
"created_at": 1794528000,
"currency": "USD",
"department": {
"id": "0667b662-49a0-7dfb-8000-96ab361b9856",
"name": "Engineering"
},
"description": "Design tool licences, year one",
"due_date": 1797120000,
"due_date_iso": "2026-12-31",
"id": "9c0d1e2f-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
"invoice_date": "2026-12-01",
"invoice_number": "INV-7781",
"invoice_url": "https://acme.ziphq.com/invoices/9c0d1e2f-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
"line_items": [],
"purchase_orders": [
{
"id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"po_number": "PO-1042"
}
],
"status": "PAID",
"subsidiary": {
"id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
"name": "Acme Inc."
},
"updated_at": 1794614400,
"vendor": {
"id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
"name": "Acme Supplies"
}
}
}Post comment
Post a comment on a request or an invoice as a Zip user. People mentioned by email are notified by Zip.
Inputs
- Post as
author_idtextRequired - The Zip user the comment is posted as. Pick one, or give their id.
- Comment
texttextRequired - What to say. Mention someone with their Zip email, such as @jo@example.com.
- Request ID
request_idtext - The request to comment on. Give this or an invoice ID.
- Invoice ID
invoice_idtext - The invoice to comment on. Give this or a request ID.
- Posted from
display_nametext - The app name Zip shows on the comment. Defaults to Lodol.
- Link
linktext - A web address Zip links the comment to, such as the record it came from.
Outputs
commentobject- The comment
Example output
{
"comment": {
"commenter": {
"email": "jo@example.com",
"first_name": "Jo",
"id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
"last_name": "Bloggs"
},
"created_at": 1792090000,
"deleted": false,
"external_display_name": "Lodol",
"external_url": "",
"id": "0a1b2c3d-4e5f-4061-8728-394a5b6c7d8e",
"text": "Quote attached; please review.",
"text_html": "<p>Quote attached; please review.</p>",
"type": "COMMENT",
"updated_at": 1792090000
}
}Reject or cancel request
Reject or cancel a request, with the reason Zip shows on it and keeps in its audit trail. This ends the request.
Inputs
- Request ID
request_idtextRequired - The request's id (not its number), from 'List requests' or an earlier step.
- Reject or cancel
outcometextRequired - Reject the request, or cancel it. Either ends it for good.One of:
REJECTED(Reject),CANCELED(Cancel). - Reason
reasontextRequired - Why. Zip shows it on the request and records it in the audit trail.One of:
PURCHASE_NO_LONGER_NEEDED(Purchase no longer needed),NOT_ENOUGH_BUDGET(Not enough budget),DUPLICATE_VENDOR(Duplicate vendor),DUPLICATE_REQUEST(Duplicate request),WRONG_WORKFLOW(Wrong workflow),CHANGE_IN_REQUIREMENTS(Change in requirements),OTHER(Other (say why)). - Other reason
other_reasontext - The reason in your words, when the reason is Other (up to 500 characters).
- Explanation
explanationtext - More detail for the audit trail (up to 2,000 characters).
Outputs
requestobject- The request's new status
Example output
{
"request": {
"canceled_at": 0,
"completed_at": 1792090000,
"id": "1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
"status": "REJECTED",
"type": "request",
"updated_at": 1792090000
}
}Send invoice for approval
Check that a draft bill is complete and send it into its approval workflow in Zip.
Inputs
- Invoice ID
invoice_idtextRequired - The invoice's id (not the supplier's invoice number), from 'List invoices' or an earlier step.
Outputs
invoiceobject- The invoice
Example output
{
"invoice": {
"amount": "12000.00",
"amount_usd": "12000.00",
"approvals": [],
"approved_at": 0,
"assignee": {
"email": "jo@example.com",
"first_name": "Jo",
"id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
"last_name": "Bloggs"
},
"created_at": 1794528000,
"currency": "USD",
"department": {
"id": "0667b662-49a0-7dfb-8000-96ab361b9856",
"name": "Engineering"
},
"description": "Design tool licences, year one",
"due_date": 1797120000,
"due_date_iso": "2026-12-31",
"id": "9c0d1e2f-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
"invoice_date": "2026-12-01",
"invoice_number": "INV-7781",
"invoice_url": "https://acme.ziphq.com/invoices/9c0d1e2f-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
"line_items": [],
"purchase_orders": [
{
"id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"po_number": "PO-1042"
}
],
"status": "PENDING_APPROVAL",
"subsidiary": {
"id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
"name": "Acme Inc."
},
"updated_at": 1794614400,
"vendor": {
"id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
"name": "Acme Supplies"
}
}
}Update request
Change a request's name, description, department, entity, vendor or start and end dates. Empty fields are left as they are.
Inputs
- Request ID
request_idtextRequired - The request's id (not its number), from 'List requests' or an earlier step.
- Name
nametext - A new name for the request. Leave empty to keep it.
- Description
descriptiontext - A new description. Leave empty to keep it.
- Department
department_idtext - Move the request to this department. Leave empty to keep it.
- Entity
subsidiary_idtext - Move the request to this entity. Leave empty to keep it.
- Vendor
vendor_idtext - Change the request's vendor. Leave empty to keep it.
- Start date
start_datedate - When the purchase starts, such as a subscription's first day.
- End date
end_datedate - When the purchase ends.
Outputs
requestobject- The request
Example output
{
"request": {
"amount_usd": "12000.00",
"attachments": [
{
"id": "8b9c0d1e-2f3a-4b4c-9d5e-6f7a8b9c0d1e",
"name": "quote.pdf",
"url": "https://acme.ziphq.com/files/quote.pdf"
}
],
"attributes": [
{
"config_id": "63d42e86-147b-4fd7-baa3-d52d7e27494d",
"data": [
"CC-100"
],
"name": "Cost center"
}
],
"category": {
"id": "89f7777d-9c5f-4f93-914e-a9ccc60b829c",
"name": "Software"
},
"completed_at": 0,
"created_at": 1792000000,
"department": {
"id": "0667b662-49a0-7dfb-8000-96ab361b9856",
"name": "Engineering"
},
"description": "Ten seats for the design team.",
"id": "1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
"name": "Design tool licences",
"owner": {
"email": "jo@example.com",
"first_name": "Jo",
"id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
"last_name": "Bloggs"
},
"payment_method": "PURCHASE_ORDER",
"price_detail": {
"currency": "USD",
"id": "3c4d5e6f-7081-4923-ab4c-5d6e7f809102",
"line_items": [],
"total": "12000.00",
"total_usd": "12000.00"
},
"priority": 1,
"purchase_order": {
"id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
"po_number": "PO-1042"
},
"request_link": "https://acme.ziphq.com/request/1ee3cc9f-055b-46ad-99ff-a20eefdd607a",
"request_number": 1042,
"request_type": "PURCHASE_REQUEST",
"requester": {
"email": "jo@example.com",
"first_name": "Jo",
"id": "6f1d2c3b-4a5e-4f60-8a71-92b3c4d5e6f7",
"last_name": "Bloggs"
},
"status": 1,
"subsidiary": {
"id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
"name": "Acme Inc."
},
"updated_at": 1792086400,
"vendor": {
"id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
"name": "Acme Supplies"
},
"workflow": {
"id": "2b3c4d5e-6f70-4812-9a3b-4c5d6e7f8091",
"name": "Software"
}
}
}Update vendor
Change a vendor's name, status, contact emails, risk, tier or entities. Empty fields are left as they are.
Inputs
- Vendor
vendor_idtextRequired - The vendor. Pick one, or give its id from an earlier step.
- Name
nametext - A new name for the vendor. Leave empty to keep it.
- Legal name
legal_nametext - The vendor's registered company name. Leave empty to keep it.
- Status
statustext - Active, Preferred, Inactive or Draft. Leave empty to keep it.One of:
1(Active),2(Preferred),3(Inactive),5(Draft). - Currency
currencytext - The vendor's main currency, a three-letter code such as USD. Leave empty to keep it.
- Purchase order email
po_emailtext - Where purchase orders for this vendor are sent. Leave empty to keep it.
- Remittance email
remittance_emailtext - Where payment notices for this vendor are sent. Leave empty to keep it.
- Phone
primary_phonetext - The vendor's main phone number. Leave empty to keep it.
- Tax ID
tax_id_numbertext - The vendor's tax identification number. Leave empty to keep it.
- Risk
risktext - The vendor's risk rating. Leave empty to keep it.One of:
green(Green (low)),yellow(Yellow (medium)),red(Red (high)). - Tier
tiertext - The vendor's tier. Leave empty to keep it.One of:
tier_1(Tier 1),tier_2(Tier 2),tier_3(Tier 3),tier_4(Tier 4). - Entities
subsidiary_idslist - The entities (subsidiaries) that may buy from this vendor. On an update, these replace the vendor's current ones.
Outputs
vendorobject- The vendor
Example output
{
"vendor": {
"address": {
"country": "US",
"lines": [
"123 Main St"
],
"locality": "San Francisco",
"postcode": "94105",
"region": "US-CA"
},
"attributes": [],
"categories": [
{
"id": "89f7777d-9c5f-4f93-914e-a9ccc60b829c",
"name": "Software"
}
],
"contacts": [],
"created_at": 1791000000,
"currency": "USD",
"department": {
"id": "0667b662-49a0-7dfb-8000-96ab361b9856",
"name": "Engineering"
},
"description": "Office and design supplies.",
"external_id": "V-10042",
"id": "9b2e7c4a-1d3f-4e5a-8b6c-7d8e9f0a1b2c",
"legal_name": "Acme Supplies LLC",
"name": "Acme Supplies",
"po_email": "orders@example.com",
"primary_phone": "+1 415 555 0100",
"remittance_email": "billing@example.com",
"risk": "green",
"status": 1,
"subsidiaries": [
{
"id": "5fccb224-6a39-4c00-a3bb-e9163586ca3f",
"name": "Acme Inc."
}
],
"tier": "tier_2",
"updated_at": 1792086400,
"website_link": "https://example.com"
}
}