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 'file=@"/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": "your_user@their_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 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": "your_user@their_domain.com",
    "loginCredentialId": "6237",
    "userRole": "OWNER",
    "status": "ACTIVE",
    "phoneMobile": "",
    "phoneWork": "",
    "nickname": "Jane",
    "ownPercent": 100,
    "needsEmailVerification": null,
    "lastUpdatedDate": "2020-09-02T21:46:01.000Z"
  }'