API Calls

The following are optional implementation steps that can be taken to optimize the branding, streamline the end customer experience, and provide access to richer functionality.

Pre filling end-user information

1-2 days

Unit will make an HTTP request to this endpoint with a JWT token associated with this user in the Authorization header before initiating the end customer application process. The server will need to return the End User Configuration resource. The response must include the data, type: whiteLabelAppEndUserConfig and attributes keys.

To enable Bill Pay for your end customers, include the BillPay product in the requestedProducts array in the End User Configuration resource.

For the full HTTP contract, JWT validation, allowedApplicationTypes behavior for bill pay, and response examples, see Pre-filling User Information.

Please contact Unit in order to configure the endpoint.

Request example:

curl -X GET 'https://yourdomain.com/unit/application-form-prefill' \
-H "Authorization: Bearer ${JWT Token}"

Programmatically create bills

1-2 days

If your business has knowledge of bills that your customers have paid or need to pay, you can choose to programmatically create these bills using the Bill API. You have the flexibility to submit either the file of the bill or provide the bill details as a raw JSON.

When using Managed Solutions, any bills you create this way will be saved as Draft. The end-customer can view the draft bill in Managed Bill Pay, make any necessary edits, and then submit it to generate the final bill.

Upload Bill File

Uploads bill file. Supported file types are pdf, jpeg or png. Maximum image size is 1.5mb.

Unit will extract the bill details from the file via Optical Character Recognition (OCR) and create a draft bill.

Verb	`POST`
URL	`https://api.s.unit.sh/billpay/bills`
Required Scope	`billpay-bills-write`
Timeout (Seconds)	`5`

Headers

Index	Value
Content-Type	One of `image/png`, `image/jpeg`, or `application/pdf`.

curl \
--request POST 'https://api.s.unit.sh/billpay/bills' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: ${TOKEN}' \
--form 'file=@"bill.pdf"'

Submit bill details

Verb	`POST`
URL	`https://api.s.unit.sh/billpay/bills`
Required Scope	`billpay-bills-write`
Data Type	`bill`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
invoiceNumber Required	string	Invoice number.
amount Required	cents	Bill amount.
dueDate Required	RFC3339 Date string	Bill due date.
date Required	RFC3339 Date string	Bill date.
tax Required	percentage	Bill tax.
lineItems Required	object[]	Bill line items.
tags Optional	object	See Tags.

Line Items

Name	Type	Description
totalAmount Required	cents	Line item total amount.
description Required	string	Line item description.
quantity Required	integer	Line item quantity.
unitPrice Required	cents	Line item unit price.
category Required	identifier	Line item category id.

Relationships

Name	Type	Description
customer Required	JSON:API Relationship	Customer to which the vendor belongs.
vendor	Optional, JSON:API Relationship	Bill Vendor

Example Request:

curl -X POST 'https://api.s.unit.sh/billpay/bills'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "bill",
    "attributes": {
      "invoiceNumber": "1234",
      "dueDate": "2025-05-10",
      "date": "2025-05-10",
      "tax": 1000,
      "idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb9",
      "lineItems": [
        {
          "totalAmount": 10000,
          "description": "Love Potions",
          "tax": 1000,
          "quantity": 1,
          "unitPrice": 1000000
        }
      ],
      "tags": {
        "external_id": "uuid"
      }
    }
  },
  "relationships": {
    "customer": {
      "data": {
        "type": "customer",
        "id": "10001"
      }
    },
    "vendor": {
      "data": {
        "type": "billPayVendor",
        "id": "10001"
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

Attributes

Name	Type	Description
invoiceNumber	string	Invoice number.
amount	cents	Bill amount.
dueDate	RFC3339 Date string	Bill due date.
date	RFC3339 Date string	Bill date.
tax	percentage	Bill tax.
lineItems	object[]	Bill line items.
tags Optional	object	See Tags.
createdAt	RFC3339 Date string	The date the resource was created.
updatedAt Optional	RFC3339 Date string	The date the resource was updated.

Relationships

Name	Type	Description
customer	JSON:API Relationship	Customer to which the vendor belongs.
vendor	Optional, JSON:API Relationship	Bill Vendor

Example Response:
{
  "data": {
    "type": "bill",
    "id": "10001",
    "attributes": {
      "invoiceNumber": "1234",
      "amount": 10000,
      "dueDate": "2025-05-10",
      "date": "2025-05-10",
      "tax": 1000,
      "tags": {
        "external_id": "uuid"
      },
      "status": "Draft",
      "lineItems": [
        {
          "totalAmount": 10000,
          "description": "Invoice Line Item 1",
          "tax": 1000,
          "quantity": 1,
          "unitPrice": 10000
        }
      ]
    }
  },
  "relationships": {
    "customer": {
      "data": {
        "type": "customer",
        "id": "10001"
      }
    },
    "vendor": {
      "data": {
        "type": "billPayVendor",
        "id": "10001"
      }
    }
  }
}

Get Bill

Get a bill resource by id.

Verb	`GET`
URL	`https://api.s.unit.sh/billpay/bills/{id}`
Required Scope	`billpay-bills`
Timeout (Seconds)	`5`

curl -X GET 'https://api.s.unit.sh/billpay/bills/10001' \
-H "Authorization: Bearer ${TOKEN}"

Response

Response is a JSON:API document.

200 OK

Attributes

Name	Type	Description
status	string	Bill status. One of `Draft`, `Pending`, `Scheduled`, `Paid`, `PaymentInProgress`, `FundsPushed`, `DeductionPaymentFailed`, `VendorPaymentFailed`, `RefundInitiated`, `Refunded`, `CancellationInitiated`, `Canceled`, `Archived`.
version	integer	Bill version number.
currency	string	Three-letter ISO currency code (e.g., `USD`).
invoiceNumber	string	Invoice number.
description	string	Bill description.
total	integer	Bill total amount in cents.
dueDate	RFC3339 Date string	Bill due date.
billDate	RFC3339 Date string	Bill date.
tax	number	Bill tax percentage (0–100).
lineItems	object[]	Bill line items.
paymentMethod	object	Payment method used for the bill. One of `ach`, `sameDayAch`, `check`, or `external`. `null` if no payment method is set.
tags Optional	object	See Tags.
createdAt	RFC3339 Date string	The date the resource was created.
updatedAt	RFC3339 Date string	The date the resource was updated.
failureReason	string	Reason for payment failure. Present when status is `DeductionPaymentFailed` or `VendorPaymentFailed`.

Line Items

Name	Type	Description
reference	string	Line item reference.
description	string	Line item description.
categoryId	string	Line item category id.
quantity	number	Line item quantity.
unitPrice	cents	Line item unit price in cents.

Payment Method

Each payment method object may include the following fields:

Platform Payment Methods (`ach`, `sameDayAch`, `check`)

Name	Type	Description
deductionDate	RFC3339 Date string	Date funds are deducted from the customer's account.
expectedDate	RFC3339 Date string	Expected date the vendor receives the payment.
feeAmount	integer	Fee amount in cents.

External Payment Method (`external`)

Name	Type	Description
paymentDate	RFC3339 Date string	Date the payment was made.

Relationships

Name	Type	Description
org	JSON:API Relationship	Organization to which the bill belongs.
customer	JSON:API Relationship	Customer to which the bill belongs.
vendor	JSON:API Relationship	Vendor associated with the bill.
billFile	JSON:API Relationship	The bill file associated with this bill.
fee	JSON:API Relationship	Fee associated with the bill.
payment	JSON:API Relationship	Payment associated with the bill.
linkedAccount	JSON:API Relationship	Linked account used for the bill payment.

Example Response:
{
  "data": {
    "type": "bill",
    "id": "10001",
    "attributes": {
      "status": "Scheduled",
      "version": 2,
      "currency": "USD",
      "invoiceNumber": "1234",
      "description": "Monthly office supplies",
      "total": 11000,
      "dueDate": "2025-05-10",
      "billDate": "2025-05-01",
      "tax": 10,
      "lineItems": [
        {
          "description": "Love Potions",
          "quantity": 1,
          "unitPrice": 10000,
          "categoryId": "501"
        }
      ],
      "paymentMethod": {
        "ach": {
          "deductionDate": "2025-05-08",
          "expectedDate": "2025-05-10",
          "feeAmount": 0
        }
      },
      "tags": {
        "external_id": "uuid"
      },
      "createdAt": "2025-04-15T10:30:00.000Z",
      "updatedAt": "2025-04-20T14:15:00.000Z"
    },
    "relationships": {
      "org": {
        "data": {
          "type": "org",
          "id": "5"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10001"
        }
      },
      "vendor": {
        "data": {
          "type": "vendor",
          "id": "10001"
        }
      },
      "linkedAccount": {
        "data": {
          "type": "linkedAccount",
          "id": "15"
        }
      }
    }
  }
}

Creating Vendors

1-2 days

A vendor is an individual or business entity that supplies goods or services to an end user in exchange for payment. Each customer maintains a list of vendors they transact with, and every bill must be linked to a vendor before it can be paid.

Our OCR model can automatically extract the vendor name from a bill image and match it to an existing vendor in the system. If you already have a list of vendors your customers work with, you can proactively create a vendor directory to reduce end user manual effort.

Create vendor

Verb	`POST`
URL	`https://api.s.unit.sh/billpay/vendors`
Required Scope	`billpay-vendors-write`
Data Type	`vendor`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
idempotencyKey Optional	string	See Idempotency.
legalName Required	string	Vendor legal name.
address Required	object	Vendor address.
email Required	string	Vendor email.
phone Required	object	Vendor phone.
website Required	string	Vendor website.
logoUrl Required	string	Vendor logo URL.
paymentMethods Required	object	Vendor payment methods.
tags Optional	object	See Tags.

Relationships

Name	Type	Description
customer Required	JSON:API Relationship	Customer to which the vendor belongs.

Example Request:

curl -X POST 'https://api.s.unit.sh/billpay/vendors'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "vendor",
    "attributes": {
      "idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb9",
      "legalName": "Weasleys' Wizard Wheezes",
      "address": {
        "street": "93 Diagon Alley ",
        "city": "Anytown",
        "state": "CA",
        "zip": "12345"
      },
      "email": "info@weasleys.com",
      "phone": {
        "countryCode": "1",
        "number": "5555555555"
      },
      "website": "https://www.weasleys.com",
      "logoUrl": "https://www.weasleys.com/logo.png",
      "paymentMethods": {
        "ach": {
          "name": "Weasleys' Wizard Wheezes",
          "accountNumber": "1234567890",
          "routingNumber": "1234567890"
        },
        "check": {
          "name": "Weasleys' Wizard Wheezes",
          "address": {
            "street": "93 Diagon Alley ",
            "city": "Anytown",
            "state": "CA",
            "zip": "12345"
          }
        },
        "preferred": "ach"
      },
      "tags": {
        "external_id": "uuid"
      }
    }
  },
  "relationships": {
    "customer": {
      "data": {
        "type": "customer",
        "id": "10001"
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

Attributes

Name	Type	Description
legalName	string	Vendor legal name.
address	object	Vendor address.
email	string	Vendor email.
phone	object	Vendor phone.
website	string	Vendor website.
logoUrl	string	Vendor logo URL.
paymentMethods	object	Vendor payment methods.
tags Optional	object	See Tags.
createdAt	RFC3339 Date string	The date the resource was created.
updatedAt Optional	RFC3339 Date string	The date the resource was updated.

Relationships

Name	Type	Description
customer	JSON:API Relationship	Customer to which the vendor belongs.

Example Response:
{
  "data": {
    "type": "vendor",
    "id": "10001",
    "attributes": {
      "legalName": "Weasleys' Wizard Wheezes",
      "address": {
        "street": "93 Diagon Alley ",
        "city": "Anytown",
        "state": "CA",
        "zip": "12345"
      },
      "email": "info@weasleys.com",
      "phone": {
        "countryCode": "1",
        "number": "5555555555"
      },
      "website": "https://www.weasleys.com",
      "logoUrl": "https://www.weasleys.com/logo.png",
      "paymentMethods": {
        "ach": {
          "name": "Weasleys' Wizard Wheezes",
          "accountNumber": "1234567890",
          "routingNumber": "1234567890"
        },
        "check": {
          "name": "Weasleys' Wizard Wheezes",
          "address": {
            "street": "93 Diagon Alley ",
            "city": "Anytown",
            "state": "CA",
            "zip": "12345"
          }
        },
        "preferred": "ach"
      },
      "tags": {
        "external_id": "uuid"
      }
    }
  },
  "relationships": {
    "customer": {
      "data": {
        "type": "customer",
        "id": "10001"
      }
    }
  }
}

Getting Vendors

1-2 days

List vendors

List bill pay vendors.

Verb	`GET`
URL	`https://api.s.unit.sh/billpay/vendors`
Required Scope	`billpay-vendors`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
page[limit]	integer	100	Optional. Maximum number of resources to return. Maximum is 10000 resources.
page[offset]	integer	0	Optional. Number of resources to skip. See Pagination.
sort	string	(empty)	Optional. One of `createdAt`, `‑createdAt`, `updatedAt`, `‑updatedAt`, `legalName`, `‑legalName`.
filter[customerId]	integer	(empty)	Optional. Filters the results by the specified customer id.
filter[ids]	integer[]	(empty)	Optional. Filters the results by the specified vendor ids.

Example Request:

curl -X GET 'https://api.s.unit.sh/billpay/vendors' \
-H "Authorization: Bearer ${TOKEN}"

Response

Returns a paginated list of vendor resources with their details.

Response is a JSON:API document.

200 OK

Name	Type	Description
data	Array of vendors	Array of vendor resources.

Attributes

Name	Type	Description
legalName	string	Vendor legal name.
address	object	Vendor address.
email	string	Vendor email.
phone	object	Vendor phone.
website	string	Vendor website.
logoUrl	string	Vendor logo URL.
paymentMethods	object	Vendor payment methods.
tags Optional	object	See Tags.
createdAt	RFC3339 Date string	The date the resource was created.
updatedAt Optional	RFC3339 Date string	The date the resource was updated.

Relationships

Name	Type	Description
customer	JSON:API Relationship	Customer to which the vendor belongs.

Example Response:
{
  "data": [
    {
      "type": "vendor",
      "id": "5001",
      "attributes": {
        "legalName": "Weasleys' Wizard Wheezes",
        "address": {
          "street": "93 Diagon Alley",
          "city": "Anytown",
          "state": "CA",
          "zip": "12345"
        },
        "email": "info@weasleys.com",
        "phone": {
          "countryCode": "1",
          "number": "5555555555"
        },
        "website": "https://www.weasleys.com",
        "logoUrl": "https://www.weasleys.com/logo.png",
        "paymentMethods": {
          "preferred": "ach",
          "ach": {
            "name": "Weasleys' Wizard Wheezes",
            "routingNumber": "1234567890",
            "accountNumber": "1234567890"
          },
          "wire": {
            "name": "Weasleys' Wizard Wheezes",
            "routingNumber": "1234567890",
            "accountNumber": "1234567890",
            "address": {
              "street": "93 Diagon Alley",
              "city": "Anytown",
              "state": "CA",
              "zip": "12345"
            }
          },
          "check": {
            "name": "Weasleys' Wizard Wheezes",
            "address": {
              "street": "93 Diagon Alley",
              "city": "Anytown",
              "state": "CA",
              "zip": "12345"
            }
          }
        },
        "tags": {
          "tier": "preferred",
          "external_id": "uuid"
        },
        "createdAt": "2024-02-07T15:24:51.179Z",
        "updatedAt": "2024-02-08T10:30:00.000Z"
      },
      "relationships": {
        "customer": {
          "data": {
            "type": "customer",
            "id": "10001"
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": "1",
      "limit": "100",
      "offset": "0"
    }
  }
}

Get vendor

Get a vendor by its ID.

Verb	`GET`
URL	`https://api.s.unit.sh/billpay/vendors/:vendorId`
Required Scope	`billpay-vendors`
Timeout (Seconds)	`5`

Example Request:

curl -X GET 'https://api.s.unit.sh/billpay/vendors/5001' \
-H "Authorization: Bearer ${TOKEN}"

Response

Returns the vendor resource.

Response is a JSON:API document.

200 OK

Attributes

Name	Type	Description
legalName	string	Vendor legal name.
address	object	Vendor address.
email	string	Vendor email.
phone	object	Vendor phone.
website	string	Vendor website.
logoUrl	string	Vendor logo URL.
paymentMethods	object	Vendor payment methods.
tags Optional	object	See Tags.
createdAt	RFC3339 Date string	The date the resource was created.
updatedAt Optional	RFC3339 Date string	The date the resource was updated.

Relationships

Name	Type	Description
customer	JSON:API Relationship	Customer to which the vendor belongs.

Example Response:
{
  "data": {
    "type": "vendor",
    "id": "5001",
    "attributes": {
      "legalName": "Weasleys' Wizard Wheezes",
      "address": {
        "street": "93 Diagon Alley",
        "city": "Anytown",
        "state": "CA",
        "zip": "12345"
      },
      "email": "info@weasleys.com",
      "phone": {
        "countryCode": "1",
        "number": "5555555555"
      },
      "website": "https://www.weasleys.com",
      "logoUrl": "https://www.weasleys.com/logo.png",
      "paymentMethods": {
        "preferred": "ach",
        "ach": {
          "name": "Weasleys' Wizard Wheezes",
          "routingNumber": "1234567890",
          "accountNumber": "1234567890"
        },
        "wire": {
          "name": "Weasleys' Wizard Wheezes",
          "routingNumber": "1234567890",
          "accountNumber": "1234567890",
          "address": {
            "street": "93 Diagon Alley",
            "city": "Anytown",
            "state": "CA",
            "zip": "12345"
          }
        },
        "check": {
          "name": "Weasleys' Wizard Wheezes",
          "address": {
            "street": "93 Diagon Alley",
            "city": "Anytown",
            "state": "CA",
            "zip": "12345"
          }
        }
      },
      "tags": {
        "tier": "preferred",
        "external_id": "uuid"
      },
      "createdAt": "2024-02-07T15:24:51.179Z",
      "updatedAt": "2024-02-08T10:30:00.000Z"
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "10001"
        }
      }
    }
  }
}

Create Transaction Categories

1-2 days

Categories are immutable and can be associated with line items on bills. They are meant to help customers categorize expenses according to their existing Chart of Accounts. Categories can be associated with individual customers or with all customers. Categorized expenses help customers with their accounting and internal reporting. Categories can have subcategories.

Once a category is created it cannot be deleted, only archived.

Create category with subcategories

Verb	`POST`
URL	`https://api.s.unit.sh/billpay/categories`
Data Type	`category`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
idempotencyKey Required	string	See Idempotency.
name Required	string	Category name.
erpId Required	string	ERP identifier for the category.
tags Optional	object	See Tags.
subcategories Optional	object[]	Array of subcategories. Mutually exclusive with parentId relationship.

Subcategories

Name	Type	Description
name Required	string	Subcategory name.
erpId Required	string	ERP identifier for the subcategory.
tags Optional	object	See Tags.

Relationships

Name	Type	Description
customer Optional	JSON:API Relationship	Customer to which the category belongs.

Example Request:

curl -X POST 'https://api.s.unit.sh/billpay/categories'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "category",
    "attributes": {
      "idempotencyKey": "create-marketing-category-2024-01-15-abc123",
      "name": "Marketing",
      "erpId": "ERP-MKT-001",
      "tags": {
        "department": "marketing",
        "budgetCode": "MKT-2024"
      },
      "subcategories": [
        {
          "name": "Internet Advertising",
          "erpId": "ERP-MKT-INT-ADV-001",
          "tags": {
            "channel": "digital",
            "subType": "online"
          }
        }
      ]
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "10001"
        }
      }
    }
  }
}'

Create category with parent category

Verb	`POST`
URL	`https://api.s.unit.sh/billpay/categories`
Data Type	`category`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
idempotencyKey Required	string	See Idempotency.
name Required	string	Category name.
erpId Required	string	ERP identifier for the category.
tags Optional	object	See Tags

Relationships

Name	Type	Description
customer Optional	JSON:API Relationship	Customer to which the category belongs.
parentId Optional	JSON:API Relationship	Parent category. Mutually exclusive with subcategories attribute.

Example Request:

curl -X POST 'https://api.s.unit.sh/billpay/categories'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "category",
    "attributes": {
      "idempotencyKey": "create-marketing-category-2024-01-15-abc123",
      "name": "Marketing",
      "erpId": "ERP-MKT-001",
      "tags": {
        "department": "marketing",
        "budgetCode": "MKT-2024"
      }
    },
    "relationships": {
      "parentId": {
        "data": {
          "type": "category",
          "id": "10501"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10001"
        }
      }
    }
  }
}'

Create categories in bulk

Verb	`POST`
URL	`https://api.s.unit.sh/billpay/categories/bulk`
Data Type	`categories`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
idempotencyKey Required	string	See Idempotency.
categories Required	object[]	Array of categories.

Name	Type	Description
name Required	string	category name.
erpId Required	string	ERP identifier for the category.
tags Optional	object	See Tags.
parentId Optional	string	Parent category id.

Relationships

Name	Type	Description
customer Optional	JSON:API Relationship	Customer to which the categories belong.

Example Request:

curl -X POST 'https://api.s.unit.sh/billpay/categories/bulk'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "categories",
    "attributes": {
      "idempotencyKey": "create-marketing-categories-2024-01-15-abc123",
      "categories": [
        {
          "name": "Utilities",
          "erpId": "UTIL-001",
          "tags": {
            "description": "Monthly utility bills",
            "priority": "high"
          }
        },
        {
          "name": "Office Supplies",
          "erpId": "OFFICE-001",
          "tags": {
            "description": "Office equipment and supplies",
            "category": "business"
          }
        },
        {
          "name": "Marketing",
          "erpId": "MKT-001",
          "tags": {
            "description": "Marketing and advertising expenses",
            "category": "business"
          },
          "parentId": "10004"
        }
      ]
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "10234"
        }
      }
    }
  }
}'

Updating Transaction Categories

Patch category

Verb	`PATCH`
URL	`https://api.s.unit.sh/billpay/categories/:categoryId`
Data Type	`categories`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
idempotencyKey Required	string	See Idempotency.
name Required	string	Category name.
erpId Required	string	ERP identifier for the category.
tags Optional	object	See Tags

Relationships

Name	Type	Description
parentId Optional	JSON:API Relationship	Parent category. Putting `"id": null` will remove an existing parent. Cannot add a parent category to a category that has subcategories.

Example Request:

curl -X PATCH 'https://api.s.unit.sh/billpay/categories/402'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "category",
    "attributes": {
      "idempotencyKey": "patch-marketing-category-2024-01-15-abc123",
      "name": "Marketing",
      "erpId": "ERP-MKT-001",
      "tags": {
        "department": "marketing",
        "budgetCode": "MKT-2024"
      }
    },
    "relationships": {
      "parentId": {
        "data": {
          "type": "category",
          "id": "10501"
        }
      }
    }
  }
}'

Archive category

Archive a category by its ID.

Verb	`POST`
URL	`https://api.s.unit.sh/billpay/categories/:categoryId/archive`
Timeout (Seconds)	`5`

Example Request:

curl -X POST 'https://api.s.unit.sh/billpay/categories/501/archive'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'

Response

Returns the category resource.

Response is a JSON:API document.

200 OK

Attributes

Name	Type	Description
createdAt	RFC3339 Date string	The date the resource was created.
updatedAt	RFC3339 Date string	The date the resource was updated.
name	string	Category name.
erpId	string	ERP identifier for the category.
tags Optional	object	See Tags.
status	string	Status of the category. One of `Active` or `Archived`.

Relationships

Name	Type	Description
customer Optional	JSON:API Relationship	Customer to which the category belongs.
parentId Optional	JSON:API Relationship	Parent category.

Example Response:
{
  "data": {
    "type": "category",
    "id": "501",
    "attributes": {
      "createdAt": "2026-06-07T13:52:22.709Z",
      "updatedAt": "2026-07-10T07:41:51.685Z",
      "status": "Archived",
      "name": "Marketing",
      "erpId": "ERP-MKT-001",
      "tags": {
        "department": "marketing",
        "budgetCode": "MKT-2024"
      }
    },
    "relationships": {
      "parentId": {
        "data": {
          "type": "category",
          "id": "500"
        }
      }
    }
  }
}

Getting Transaction Categories

1-2 days

List bill pay transaction categories.

Verb	`GET`
URL	`https://api.s.unit.sh/billpay/categories`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
page[limit]	integer	100	Optional. Maximum number of resources to return. Maximum is 10000 resources.
page[offset]	integer	0	Optional. Number of resources to skip. See Pagination.
sort	string	(empty)	Optional. One of `createdAt`, `‑createdAt`, `updatedAt`, `‑updatedAt`, `name`, `‑name`.
filter[ids]	integer[]	(empty)	Optional. Filters the results by the specified category ids.
filter[parentId]	integer	(empty)	Optional. Filters the results by the specified parent category id.
filter[customerId]	integer	(empty)	Optional. Filters the results by the specified customer id.
filter[name]	string	(empty)	Optional. Filters the results by category name.
filter[erpId]	string	(empty)	Optional. Filters the results by ERP identifier.
filter[status]	string	(empty)	Optional. Filters by status. One of `Active` or `Archived`.

Example Request:

curl -X GET 'https://api.s.unit.sh/billpay/categories' \
-H "Authorization: Bearer ${TOKEN}"

Response

Returns a paginated list of category resources with their details.

Response is a JSON:API document.

200 OK

Name	Type	Description
data	Array of categories	Array of category resources.

Attributes

Name	Type	Description
createdAt	RFC3339 Date string	The date the resource was created.
updatedAt	RFC3339 Date string	The date the resource was updated.
name	string	Category name.
erpId	string	ERP identifier for the category.
tags Optional	object	See Tags.
status	string	Status of the category. One of `Active` or `Archived`.

Relationships

Name	Type	Description
customer Optional	JSON:API Relationship	Customer to which the category belongs.
parentId Optional	JSON:API Relationship	Parent category.

Example Response:
{
  "data": [
    {
      "type": "category",
      "id": "501",
      "attributes": {
        "createdAt": "2026-06-07T13:52:22.709Z",
        "updatedAt": "2026-07-10T07:41:51.685Z",
        "status": "Active",
        "name": "Marketing",
        "erpId": "ERP-MKT-001",
        "tags": {
          "department": "marketing",
          "budgetCode": "MKT-2024"
        }
      }
    },
    {
      "type": "category",
      "id": "502",
      "attributes": {
        "createdAt": "2026-06-07T13:52:22.709Z",
        "updatedAt": "2026-07-10T07:41:51.685Z",
        "status": "Archived",
        "name": "Internet Advertising",
        "erpId": "ERP-MKT-INT-ADV-001",
        "tags": {
          "channel": "digital",
          "subType": "online"
        }
      },
      "relationships": {
        "parentId": {
          "data": {
            "type": "category",
            "id": "501"
          }
        }
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": "2",
      "limit": "100",
      "offset": "0"
    }
  }
}

Get category

Get a category by its ID.

Verb	`GET`
URL	`https://api.s.unit.sh/billpay/categories/:categoryId`
Timeout (Seconds)	`5`

Example Request:

curl -X GET 'https://api.s.unit.sh/billpay/categories/501' \
-H "Authorization: Bearer ${TOKEN}"

Response

Returns the category resource.

Response is a JSON:API document.

200 OK

Attributes

Name	Type	Description
createdAt	RFC3339 Date string	The date the resource was created.
updatedAt	RFC3339 Date string	The date the resource was updated.
name	string	Category name.
erpId	string	ERP identifier for the category.
tags Optional	object	See Tags.
status	string	Status of the category. One of `Active` or `Archived`.

Relationships

Name	Type	Description
customer Optional	JSON:API Relationship	Customer to which the category belongs.
parentId Optional	JSON:API Relationship	Parent category.

Example Response:
{
  "data": {
    "type": "category",
    "id": "501",
    "attributes": {
      "createdAt": "2026-06-07T13:52:22.709Z",
      "updatedAt": "2026-07-10T07:41:51.685Z",
      "status": "Active",
      "name": "Marketing",
      "erpId": "ERP-MKT-001",
      "tags": {
        "department": "marketing",
        "budgetCode": "MKT-2024"
      }
    },
    "relationships": {
      "parentId": {
        "data": {
          "type": "category",
          "id": "500"
        }
      }
    }
  }
}

Linking Accounts

1-2 days

Control which Unit deposit accounts your customers can use to fund their bill payments. By default, all active accounts are automatically linked upon onboarding to ensure funds are available immediately.

Create Linked Account

Links a Unit deposit account to Bill Pay for a specific customer.

Verb	`POST`
URL	`https://api.s.unit.sh/billpay/linked-accounts`
Required Scope	`billpay-linked-accounts-write`
Data Type	`billpayLinkedAccount`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
idempotencyKey Required	string	See Idempotency. Length 1–255 characters.
tags Optional	object	See Tags.

Relationships

Name	Type	Description
account Required	JSON:API Relationship	The Unit deposit account to link to Bill Pay. Type must be `depositAccount` or `account`.

Example Request:

curl -X POST 'https://api.s.unit.sh/billpay/linked-accounts'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "unitLinkedAccount",
    "attributes": {
      "idempotencyKey": "unique-key-123",
      "tags": {}
    },
    "relationships": {
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "12345"
        }
      }
    }
  }
}'

Response

Response is a JSON:API document.

201 Created

Attributes

Name	Type	Description
name	string	The friendly name for the linked account.
createdAt	RFC3339 Date string	The date the resource was created.
updatedAt Optional	RFC3339 Date string	The date the resource was updated.
tags Optional	object	See Tags.

Relationships

Name	Type	Description
customer	JSON:API Relationship	Customer to which the linked account belongs.
account	JSON:API Relationship	The Unit deposit account linked to Bill Pay.
org	JSON:API Relationship	Organization to which the linked account belongs.

Example Response:
{
  "data": {
    "type": "billpayLinkedAccount",
    "id": "15",
    "attributes": {
      "name": "Primary Business Account",
      "createdAt": "2024-02-07T15:24:51.179Z",
      "updatedAt": "2024-02-07T15:24:51.179Z",
      "tags": {}
    },
    "relationships": {
      "customer": {
        "data": {
          "type": "customer",
          "id": "10006"
        }
      },
      "account": {
        "data": {
          "type": "depositAccount",
          "id": "12345"
        }
      },
      "org": {
        "data": {
          "type": "org",
          "id": "1"
        }
      }
    }
  }
}

Get Linked Account

Get a linked account resource by id.

Verb	`GET`
URL	`https://api.s.unit.sh/billpay/linked-accounts/{id}`
Required Scope	`billpay-linked-accounts`
Timeout (Seconds)	`5`

Response

Response is a JSON:API document.

200 OK

Name	Type	Description
data	billpayLinkedAccount	The linked account resource.

The response includes the linked Unit deposit account in the account relationship.

curl -X GET 'https://api.s.unit.sh/billpay/linked-accounts/15' \
-H "Authorization: Bearer ${TOKEN}"

Archive Linked Account

Archives a linked account, deactivating it for Bill Pay. Archived accounts will not be shown as an option in the UI and bills scheduled for payment using this account will not be paid.

Verb	`POST`
URL	`https://api.s.unit.sh/billpay/linked-accounts/{id}/archive`
Required Scope	`billpay-linked-accounts-write`
Data Type	`billpayLinkedAccount`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
idempotencyKey Required	string	See Idempotency. Length 1–255 characters.

Example Request:

curl -X POST 'https://api.s.unit.sh/billpay/linked-accounts/{id}/archive'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "linkedAccount",
    "attributes": {
      "idempotencyKey": "unique-key-456"
    }
  }
}'

Response

Response is a JSON:API document.

200 OK

Returns the archived linked account resource.

List Linked Accounts

List linked accounts. Filtering and paging can be applied.

Verb	`GET`
URL	`https://api.s.unit.sh/billpay/linked-accounts`
Required Scope	`billpay-linked-accounts`
Timeout (Seconds)	`5`

Query Parameters

Name	Type	Default	Description
page[limit]	integer	100	Optional. Maximum number of resources that will be returned. Maximum is 1000 resources. See Pagination.
page[offset]	integer	0	Optional. Number of resources to skip. See Pagination.
filter[ids]	string[]	(empty)	Optional. Filters the results by the specified linked account ids.
filter[customerId]	integer	(empty)	Optional. Filters the results by the specified customer id.
filter[orgId]	integer	(empty)	Optional. Filters the results by the specified organization id.
filter[tags]	Tags (JSON)	(empty)	Optional. Filter linked accounts by Tags.
filter[status]	string	(empty)	Optional. Filters by status. One of `Active` or `Archived`.

curl -X GET 'https://api.s.unit.sh/billpay/linked-accounts?filter[customerId]=10006' \
-H "Authorization: Bearer ${TOKEN}"

Response

Response is a JSON:API document.

200 OK

Name	Type	Description
data	Array of billpayLinkedAccount	Array of linked account resources. Each resource includes the linked Unit deposit account in the `account` relationship.

Example Response:
{
  "data": [
    {
      "type": "billpayLinkedAccount",
      "id": "15",
      "attributes": {
        "name": "Primary Business Account",
        "createdAt": "2024-02-07T15:24:51.179Z",
        "updatedAt": "2024-02-07T15:24:51.179Z",
        "tags": {}
      },
      "relationships": {
        "customer": {
          "data": {
            "type": "customer",
            "id": "10006"
          }
        },
        "account": {
          "data": {
            "type": "depositAccount",
            "id": "12345"
          }
        },
        "org": {
          "data": {
            "type": "org",
            "id": "1"
          }
        }
      }
    },
    {
      "type": "billpayLinkedAccount",
      "id": "16",
      "attributes": {
        "name": "Secondary Business Account",
        "createdAt": "2024-02-08T10:30:00.000Z",
        "updatedAt": "2024-02-08T10:30:00.000Z",
        "tags": {}
      },
      "relationships": {
        "customer": {
          "data": {
            "type": "customer",
            "id": "10006"
          }
        },
        "account": {
          "data": {
            "type": "depositAccount",
            "id": "12346"
          }
        },
        "org": {
          "data": {
            "type": "org",
            "id": "1"
          }
        }
      }
    }
  ]
}

Customer Activation and Deactivation

Control Bill Pay access by activating or deactivating customers via API. Use this to enforce paywalls or subscription requirements. Customers are active by default.

Deactivated customers see a read-only UI with their existing bill data. They cannot create new bills or pay bills.

When you deactivate a customer, we automatically refund any in-flight payments. This includes ACH payments not yet transmitted and checks mailed but not yet deposited. Funds return to the customer's deposit account Both activate and deactivate operations are idempotent - if the config is already in the target state, the operation returns the existing config without making changes.

Activate Bill Pay Customer

Activates a customer's Bill Pay configuration, enabling Bill Pay functionality for the customer.

Verb	`POST`
URL	`https://api.s.unit.sh/customers/:customerId/billpay/activate`
Data Type	`billpayCustomerConfig`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
idempotencyKey Required	string	See Idempotency.

Example Request:

curl -X POST 'https://api.s.unit.sh/customers/:customerId/billpay/activate'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "billpayCustomerConfig",
    "attributes": {
      "idempotencyKey": "activate-billpay-12345-2026-02-01"
    }
  }
}'

Response

Response is a JSON:API document.

200 OK

Attributes

Name	Type	Description
status	string	The status of the Bill Pay configuration. Will be `Active` after successful activation.

Relationships

Name	Type	Description
org	JSON:API Relationship	Organization to which the configuration belongs.
billpayTerms	JSON:API Relationship	The Bill Pay terms associated with this configuration.
customer	JSON:API Relationship	Customer to which the configuration belongs.

Example Response:
{
  "data": {
    "type": "billpayCustomerConfig",
    "attributes": {
      "passthroughAccountId": "10014",
      "status": "Active"
    },
    "relationships": {
      "org": {
        "data": {
          "type": "org",
          "id": "5"
        }
      },
      "billpayTerms": {
        "data": {
          "type": "billpayTerms",
          "id": "1000"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10008"
        }
      }
    }
  }
}

Deactivate Bill Pay Customer

Deactivates a BIll Pay Customer. Deactivated customers see a read-only UI with their existing bill data. They cannot create new bills or pay bills.

Verb	`POST`
URL	`https://api.s.unit.sh/customers/:customerId/billpay/deactivate`
Data Type	`billpayCustomerConfig`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
idempotencyKey Required	string	See Idempotency.

Example Request:

curl -X POST 'https://api.s.unit.sh/customers/:customerId/billpay/deactivate'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "billpayCustomerConfig",
    "attributes": {
      "idempotencyKey": "deactivate-billpay-12345-2026-02-01"
    }
  }
}'

Response

Response is a JSON:API document.

200 OK

Attributes

Name	Type	Description
status	string	The status of the Bill Pay configuration. Will be `Inactive` after successful deactivation.

Relationships

Name	Type	Description
org	JSON:API Relationship	Organization to which the configuration belongs.
billpayTerms	JSON:API Relationship	The Bill Pay terms associated with this configuration.
customer	JSON:API Relationship	Customer to which the configuration belongs.

Example Response:
{
  "data": {
    "type": "billpayCustomerConfig",
    "attributes": {
      "passthroughAccountId": "10014",
      "status": "Inactive"
    },
    "relationships": {
      "org": {
        "data": {
          "type": "org",
          "id": "5"
        }
      },
      "billpayTerms": {
        "data": {
          "type": "billpayTerms",
          "id": "1000"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10008"
        }
      }
    }
  }
}

Set Bill Pay Reactivation URL

Set the URL where customers land when they click to reactivate Bill Pay. This should be your product's billing or plan selection page.

Dashboard Configuration

If you have access to the Unit Dashboard, you can configure this URL through the Managed Solutions Admin Settings in the Dashboard:

Navigate to the Managed Solutions Settings page
Click on the Callbacks tab
Locate the Reactivation Bill Pay Page URL field
Enter the URL where customers should be redirected for Bill Pay reactivation
Click Save

API Configuration

You can also configure this URL programmatically using the White Label App Config API.

Verb	`PATCH`
URL	`https://api.s.unit.sh/white-label/app/configs`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
billpayReactivationPageURL Optional	string	The URL where customers land when they click to reactivate Bill Pay.

Relationships

Name	Type	Description
org Required	JSON:API Relationship	Organization to which the configuration belongs.

{
  "data": {
    "type": "whiteLabelAppConfig",
    "attributes": {
      "billpayReactivationPageURL": "https://example.com/billpay/reactivate"
    },
    "relationships": {
      "org": {
        "data": {
          "type": "org",
          "id": "5"
        }
      }
    }
  }
}

Pre filling end-user information​

Programmatically create bills​

Upload Bill File​

Headers​

Submit bill details​

Attributes​

Line Items​

Relationships​

Response​

201 Created​

Attributes​

Relationships​

Get Bill​

Response​

200 OK​

Attributes​

Line Items​

Payment Method​

Platform Payment Methods (ach, sameDayAch, check)​

External Payment Method (external)​

Relationships​

Creating Vendors​

Create vendor​

Attributes​

Relationships​

Response​

201 Created​

Attributes​

Relationships​

Getting Vendors​

List vendors​

Query Parameters​

Response​

200 OK​

Attributes​

Relationships​

Get vendor​

Response​

200 OK​

Attributes​

Relationships​

Create Transaction Categories​

Create category with subcategories​

Attributes​

Subcategories​

Relationships​

Create category with parent category​

Attributes​

Relationships​

Create categories in bulk​

Attributes​

Categories​

Relationships​

Updating Transaction Categories​

Patch category​

Attributes​

Relationships​

Archive category​

Response​

200 OK​

Attributes​

Relationships​

Getting Transaction Categories​

List categories​

Query Parameters​

Response​

200 OK​

Attributes​

Relationships​

Get category​

Response​

200 OK​

Attributes​

Relationships​

Linking Accounts​

Create Linked Account​

Attributes​

Relationships​

Response​

201 Created​

Pre filling end-user information

Programmatically create bills

Upload Bill File

Headers

Submit bill details

Attributes

Line Items

Relationships

Response

201 Created

Attributes

Relationships

Get Bill

Response

200 OK

Attributes

Line Items

Payment Method

Platform Payment Methods (`ach`, `sameDayAch`, `check`)

External Payment Method (`external`)

Relationships

Creating Vendors

Create vendor

Attributes

Relationships

Response

201 Created

Attributes

Relationships

Getting Vendors

List vendors

Query Parameters

Response

200 OK

Attributes

Relationships

Get vendor

Response

200 OK

Attributes

Relationships

Create Transaction Categories

Create category with subcategories

Attributes

Subcategories

Relationships

Create category with parent category

Attributes

Relationships

Create categories in bulk

Attributes

Categories

Relationships

Updating Transaction Categories

Patch category

Attributes

Relationships

Archive category

Response

200 OK

Attributes

Relationships

Getting Transaction Categories

List categories

Query Parameters

Response

200 OK

Attributes

Relationships

Get category

Response

200 OK

Attributes

Relationships

Linking Accounts

Create Linked Account

Attributes

Relationships

Response

201 Created