Advanced Implementation

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.

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 Form 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 image file. Supported file types are pdf, jpeg or png. Maximum image size is 1.5mb.

Unit will extract the bill details from the image via Optical Character Recognition (OCR) and create a draft bill. As a response to this API call you will get a bill form id. Once the OCR is completed you will be notified via webhook.

Verb	`PUT`
Url	`https://api.s.unit.sh/bill-pay/bill-forms`
Required Scope	`bill-pay-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/bill-pay/bill-forms' \
--header 'Content-Type: application/pdf' \
--data-binary 'bill.pdf'

Submit bill details

Verb	`POST`
Url	`https://api.s.unit.sh/bill-pay/bill-forms`
Required Scope	`bill-pay-bills-write`
Data Type	`billForm`
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	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	string	Line item category

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/bill-pay/bill-forms'
-H 'Content-Type: application/vnd.api+json'
-H 'Authorization: Bearer ${TOKEN}'
--data-raw '{
  "data": {
    "type": "billForm",
    "attributes": {
      "invoiceNumber": "1234",
      "amount": 10000,
      "dueDate": "2025-05-10",
      "date": "2025-05-10",
      "tax": 1000,
      "idempotencyKey": "3a1a33be-4e12-4603-9ed0-820922389fb9",
      "lineItems": [
        {
          "totalAmount": 10000,
          "description": "Invoice Line Item 1",
          "tax": 1000,
          "quantity": 1,
          "unitPrice": 10000,
          "category": "Advertising"
        }
      ],
      "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	object	Optional. See Tags.
createdAt	RFC3339 Date string	The date the resource was created.
updatedAt	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": "billForm",
    "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,
          "category": "Advertising"
        }
      ]
    }
  },
  "relationships": {
    "customer": {
      "data": {
        "type": "customer",
        "id": "10001"
      }
    },
    "vendor": {
      "data": {
        "type": "billPayVendor",
        "id": "10001"
      }
    }
  }
}

Creating Vendor

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/bill-pay/vendors`
Required Scope	`bill-pay-vendors-write`
Data Type	`vendor`
Timeout (Seconds)	`5`

Attributes

Name	Type	Description
idempotencyKey	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	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/bill-pay/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"
        },
        "wire": {
          "name": "Weasleys' Wizard Wheezes",
          "accountNumber": "1234567890",
          "routingNumber": "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"
          }
        },
        "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	object	Optional. See Tags.
createdAt	RFC3339 Date string	The date the resource was created.
updatedAt	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"
        },
        "wire": {
          "name": "Weasleys' Wizard Wheezes",
          "accountNumber": "1234567890",
          "routingNumber": "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"
          }
        },
        "preferred": "ach"
      },
      "tags": {
        "external_id": "uuid"
      }
    }
  },
  "relationships": {
    "customer": {
      "data": {
        "type": "customer",
        "id": "10001"
      }
    }
  }
}

Programmatically create bills​

Upload Bill File​

Headers​

Submit bill details​

Attributes​

Line Items​

Relationships​

Response​

201 Created​

Attributes​

Relationships​

Creating Vendor​

Create vendor​

Attributes​

Relationships​

Response​

201 Created​

Attributes​

Relationships​

Programmatically create bills

Upload Bill File

Headers

Submit bill details

Attributes

Line Items

Relationships

Response

201 Created

Attributes

Relationships

Creating Vendor

Create vendor

Attributes

Relationships

Response

201 Created

Attributes

Relationships