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 Ready-to-Launch, any bills you create this way will be saved as Draft. The end-customer can view the draft bill in the app, 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 PUT '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	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	Optional. See Tags.

Line Items

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

Relationships

Name	Type	Description
customer	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	Optional. See Tags.
createdAt	RFC3339 Date string	The date the resource was created.
updatedAt Optional	RFC3339 Date string	Optional. 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	Optional. 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	Optional. See Idempotency.
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	Optional. See Tags.

Relationships

Name	Type	Description
customer	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	Optional. See Tags.
createdAt	RFC3339 Date string	The date the resource was created.
updatedAt Optional	RFC3339 Date string	Optional. 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	Optional. See Tags.
createdAt	RFC3339 Date string	The date the resource was created.
updatedAt Optional	RFC3339 Date string	Optional. 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	Optional. See Tags.
createdAt	RFC3339 Date string	The date the resource was created.
updatedAt Optional	RFC3339 Date string	Optional. 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. 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

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

Attributes

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

Subcategories

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

Relationships

Name	Type	Description
org	JSON:API Relationship	Organization to which the category belongs.
customer	JSON:API Relationship	Customer to which the category belongs.
parentId Optional	JSON:API Relationship	Optional. 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"
      },
      "subcategories": [
        {
          "name": "Internet Advertising",
          "erpId": "ERP-MKT-INT-ADV-001",
          "tags": {
            "channel": "digital",
            "subType": "online"
          }
        }
      ]
    },
    "relationships": {
      "org": {
        "data": {
          "type": "org",
          "id": "12345"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10001"
        }
      }
    }
  }
}'

Getting Transaction Categories

1-2 days

List bill pay transaction categories.

Verb	`GET`
URL	`https://api.s.unit.sh/billpay/categories`
Required Scope	`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[orgId]	integer	(empty)	Optional. Filters the results by the specified organization id.
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
name	string	Category name.
erpId	string	ERP identifier for the category.
tags Optional	object	Optional. See Tags.

Relationships

Name	Type	Description
org	JSON:API Relationship	Organization to which the category belongs.
category	JSON:API Relationship	Parent category. `null` if this is a top-level category.

Example Response:
{
  "data": [
    {
      "type": "category",
      "id": "501",
      "attributes": {
        "name": "Marketing",
        "erpId": "ERP-MKT-001",
        "tags": {
          "department": "marketing",
          "budgetCode": "MKT-2024"
        }
      },
      "relationships": {
        "org": {
          "data": {
            "type": "org",
            "id": "12345"
          }
        },
        "category": {
          "data": null
        }
      }
    },
    {
      "type": "category",
      "id": "502",
      "attributes": {
        "name": "Internet Advertising",
        "erpId": "ERP-MKT-INT-ADV-001",
        "tags": {
          "channel": "digital",
          "subType": "online"
        }
      },
      "relationships": {
        "org": {
          "data": {
            "type": "org",
            "id": "12345"
          }
        },
        "category": {
          "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`
Required Scope	`billpay-categories`
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
name	string	Category name.
erpId	string	ERP identifier for the category.
tags Optional	object	Optional. See Tags.

Relationships

Name	Type	Description
org	JSON:API Relationship	Organization to which the category belongs.
category	JSON:API Relationship	Parent category. `null` if this is a top-level category.

Example Response:
{
  "data": {
    "type": "category",
    "id": "501",
    "attributes": {
      "name": "Marketing",
      "erpId": "ERP-MKT-001",
      "tags": {
        "department": "marketing",
        "budgetCode": "MKT-2024"
      }
    },
    "relationships": {
      "org": {
        "data": {
          "type": "org",
          "id": "12345"
        }
      },
      "category": {
        "data": null
      }
    }
  }
}

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	Required. See Idempotency. Length 1–255 characters.
tags Optional	object	Optional. See Tags.

Relationships

Name	Type	Description
account Required	JSON:API Relationship	Required. The Unit deposit account to link to Bill Pay. Type must be `depositAccount` or `account`.
customer Optional	JSON:API Relationship	Optional. Customer to which the linked account belongs.

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"
        }
      },
      "customer": {
        "data": {
          "type": "customer",
          "id": "10006"
        }
      }
    }
  }
}'

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	Optional. The date the resource was updated.
tags Optional	object	Optional. 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	Required. 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`
Required Scope	`billpay-customer-config-write`
Data Type	`billpayCustomerConfig`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
idempotencyKey	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`
Required Scope	`billpay-customer-config-write`
Data Type	`billpayCustomerConfig`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
idempotencyKey	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 platform's billing or plan selection page.

Dashboard Configuration

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

Navigate to the Ready to Launch 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`
Required Scope	`white-label-config-write`
Timeout (Seconds)	`5`

Attributes

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

Relationships

Name	Type	Description
org	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​

Attributes​

Subcategories​

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​

Attributes​

Relationships​

Get Linked Account​

Response​

200 OK​

Archive Linked Account​

Attributes​

Response​

200 OK​

List Linked Accounts​

Query Parameters​

Response​

200 OK​

Customer Activation and Deactivation​

Activate Bill Pay Customer​

Attributes​

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

Attributes

Subcategories

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

Attributes

Relationships

Get Linked Account

Response

200 OK

Archive Linked Account

Attributes

Response

200 OK

List Linked Accounts

Query Parameters

Response

200 OK

Customer Activation and Deactivation

Activate Bill Pay Customer

Attributes