Customizing Design & Branding

Once you have registered a user, you can easily set your user up to send out custom invoices, by following the below steps.

1. Setting up the user's business info

The Hurdlr API allows users to have more than one business, with custom invoices for each, which provides a lot of flexibility in today's modern workforce. First, you should retrieve a list of the user's businesses. Be sure to include that user's access_token in the headers.

curl \
  --request GET \
  --url https://sandbox.hurdlr.com/rest/v5/clientMgmt/businesses \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \

The response from GET /businesses contains an array of the user's businesses:

[
  {
    "id": 416080,
    "name": "Hurdlr Design Studios",
    "phoneWork": "",
    "address1": "1815 Adams Mills Rd NW",
    "address2": "3rd Floor",
    "city": "Washington",
    "state": "DC",
    "zip": "20009",
    "tin": "",
    "invoicePrefix": "HRDLR",
    "status": "ACTIVE",
    "bizType": "FREELANCER",
    "lastUpdatedDate": "2021-04-19T21:15:02.000Z"
  },
  {
    "id": 416077,
    "name": "ISO Photography Studios",
    "phoneWork": "",
    "address1": "",
    "address2": "",
    "city": "",
    "state": "",
    "zip": "",
    "tin": "",
    "invoicePrefix": "ISO",
    "status": "ACTIVE",
    "bizType": "FREELANCER",
    "lastUpdatedDate": "2021-04-07T15:36:58.000Z"
  },
]

You should update the following fields for any given business, as they will be displayed on the user's invoices:

Field

Description

Format

name

Your user's business's name

Any string

address1

First line of your user's business address

Any string

address2

Second line of your user's business address

Any string

city

City of your user's business address

Any string

state

State/Province of your user's business address

Two-character string

zip

Zip/Postal code of your user's business address

Any string

phoneWork

Your user's business phone number

Numbers only

invoicePrefix

Prefix for invoice numbering

Any string. If the invoicePrefix is "ISO", then the first invoice sent from this business will be invoice "ISO-01"

To update a business, simply POST the updated business JSON object to the /business endpoint:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/clientMgmt/business \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": 416077,
    "name": "ISO Photography",
    "phoneWork": "5555555555",
    "address1": "1815 Adams Mill Rd NW",
    "address2": "3rd Floor",
    "city": "Washington",
    "state": "DC",
    "zip": "20009",
    "tin": "",
    "invoicePrefix": "ISOP",
    "status": "ACTIVE",
    "bizType": "FREELANCER",
  }'

2. Uploading the user's business logo

To upload a logo for a user's business, simply POST the logo's file path, along with an attachToId equal to the user's business id:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/files/upload \
  --header 'Authorization: Bearer ${access_token}' \
  --form 'fileName="logo.png"' \
  --form 'attachToTable="business"' \
  --form 'attachToId="416077"' \
  --form '[email protected]"/Users/username/Desktop/logo.png"'

3. Setting up the user's invoice template

After updating the user's business info, the next step to customize your user's invoice is to update the invoice template info. First, you should retrieve the user's invoice template info.

curl \
  --request GET \
  --url https://sandbox.hurdlr.com/rest/v5/invoicing/invoiceSetup \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \

The response from GET /invoiceSetup contains the user's invoice template info:

{
  "id": 271231,
  "defaultReimbursableMarkUpPercent": 0,
  "defaultInvoiceNote": "",
  "defaultInvoiceTerm": null,
  "invoiceReminderSchedule": null,
  "brandColor": null,
  "thirdPartyPaymentsEnabled": false,
  "invoiceSetupComplete": false,
  "lastUpdatedDate": "2021-03-18T22:22:41.000Z"
}

You can optionally update the following fields, in order to customize the user's invoice template:

Field

Description

Format

brandColor

The primary color of your user's brand

Six digit hexadecimal string, starting with # (e.g. "#5AAE46")

defaultInvoiceNote

Default invoice message, to be appended at the end of the invoice

Any string

defaultInvoiceTerm

Default Invoice Term (i.e. how many days till the invoice is due). This can be overridden at the individual invoice level.

Must be one of the following:
"DUE_NOW", "NET_10", "NET_15", "NET_30", "NET_60"

defaultReimbursableMarkUpPercent

Default expense mark-up percentage (useful when also consuming Hurdlr's Expense Tracking API)

Numbers only, between 0 and 100. For a 17.5% mark-up, use 17.5.

invoiceReminderSchedule

Automatic payment reminder frequencies, to be used as the default on new invoices

Array of strings, which can be any of the following values:
"ON_DUE_DATE", "THREE_DAYS_AFTER_DUE_DATE", "EVERY_SEVEN_DAYS_AFTER_DUE_DATE", "AFTER_TWO_MINS".

Note that "AFTER_TWO_MINS" is solely for dev/testing purposes.

thirdPartyPaymentsEnabled

Whether the user is set up to accept payments through your payment processing engine

Boolean

invoiceSetupComplete

Whether the user has completed all the invoice setup steps (helpful when determining whether to show the user a zero state UI)

Boolean

To update the invoice template info, simply POST the updated JSON object to the /invoiceSetup endpoint:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/invoicing/invoiceSetup \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "invoiceSetup": {
      "id": 271231,
      "defaultReimbursableMarkUpPercent": 17.5,
      "defaultInvoiceNote": "Thank you for your business!",
      "defaultInvoiceTerm": "NET_10",
      "invoiceReminderSchedule": ["ON_DUE_DATE", "EVERY_SEVEN_DAYS_AFTER_DUE_DATE"],
      "brandColor": "#5AAE46",
      "invoiceSetupComplete": true
    }
  }'

4. Adding the user's default billable rate

The Hurdlr API allows users to have more than one employee (e.g. for SMBs), but in many cases, there will be only be one employee, which represents the user himself. In order to set that user's billable rate, you should retrieve a list of the user's employee. Be sure to include that user's access_token in the headers.

curl \
  --request GET \
  --url https://sandbox.hurdlr.com/rest/v5/clientMgmt/employees \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \

The response from GET /businesses contains an array of the user's businesses:

[
  {
    "id": 5616,
    "name": "Jane Doe",
    "billableRate": null,
    "email": "[email protected]_domain.com",
    "loginCredentialId": "6237",
    "userRole": "OWNER",
    "status": "ACTIVE",
    "phoneMobile": "",
    "phoneWork": "",
    "nickname": "Jane",
    "ownPercent": 100,
    "needsEmailVerification": null,
    "lastUpdatedDate": "2020-09-02T21:46:01.000Z"
  }
]

You should update the billableRate field for any employees that whose time will be invoiced, and then simply POST the updated JSON object to the /employee endpoint:

curl \
  --request POST \
  --url https://sandbox.hurdlr.com/rest/v5/clientMgmt/employee \
  --header 'Authorization: Bearer ${access_token}' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": 5616,
    "name": "Jane Doe",
    "billableRate": 50.00,
    "email": "[email protected]_domain.com",
    "loginCredentialId": "6237",
    "userRole": "OWNER",
    "status": "ACTIVE",
    "phoneMobile": "",
    "phoneWork": "",
    "nickname": "Jane",
    "ownPercent": 100,
    "needsEmailVerification": null,
    "lastUpdatedDate": "2020-09-02T21:46:01.000Z"
  }'

What’s Next