API Reference
This page details the objects and fields available through the Fizz API. This API is constantly changing as we add new features, but we will never remove anything. So, to make sure that your code is future-proof, make sure that you use xml best practices:
- never rely on the order of the xml nodes
- ignore xml nodes that you don't need
- ignore any unexpected xml attributes
The fizzid is the critical link to the data in your system. You should store the ID from your database/system in this field, and use it when matching records between the two systems.
Customers
/fizz/customers/{customer-id}.xml
field | sample value | type | access |
---|---|---|---|
id | 12 | unique integer id | read-only |
fizzid | cust-123 | string (store your database ids here) | |
fizz-issues | Invalid phone number | string (this will be visible to the user) | |
account-number | 12345 | string | |
company-name | Acme | string | |
jdoe@example.com | string (valid email address, or blank) | ||
first-name | John | string | |
last-name | Doe | string | |
name | Thompsons | string (name of last resort -- see below) | |
phone-1 | 5553334444 | 10-digit string (used for outbound calling) | |
phone-2 | 5553334444 | 10-digit string | |
phone-3 | 5553334444 x22 | 10-digit string with optional extension | |
phone-1-label | home | string | |
phone-2-label | cell | string | |
phone-3-label | work | string | |
created-at | 2011-09-12T20:42:13Z | UTC datetime (iso8601) | read-only |
updated-at | 2011-10-14T19:15:14Z | UTC datetime (iso8601) | read-only |
Each customer must have at least one of the following:
- first-name and last-name
- company-name
- name
The name field should only be set as a last resort, in cases where the customer doesn't have: a company name, or a first and last name.
NOTE: When the name field is empty, Fizz will return a default value for the name that is generated using a combination of the first-name, last-name and company-name fields.
Coolfront Agreements makes automated phone calls to notify customers, about their visits, but it not allow calls to numbers that have extensions. That is why phone-1 and phone-2 cannot have extensions.The phone labels will show up in Coolfront Agreements so the user knows what those phone numbers are.
- phone-1: called for automated messages
- phone-2: used if phone-1 is missing or failing
- phone-3: does not receive automated calls (extension allowed)
Addresses
/fizz/addresses/{address-id}.xml
/fizz/customers/{customer-id}/addresses.xml
field | sample value | type | access |
---|---|---|---|
id | 44 | unique integer id | read-only |
fizzid | a1 | string (store your database ids here) | |
customer-id | 12 | integer | |
name | Rental | string (a label for the location) | |
street | 123 Fake St. | string | |
second-line | BigTime Condos | string | |
city | Somewhere | string | |
state | CA | 2-letter string | |
zip | 12345 | US or Canadian postal code | |
created-at | 2011-09-12T20:42:13Z | UTC datetime (iso8601) | read-only |
updated-at | 2011-10-14T19:15:14Z | UTC datetime (iso8601) | read-only |
For an address to be valid, at least one field must have a value.
Agreements
/fizz/agreements/{agreement-id}.xml
/fizz/addresses/{address-id}/agreements.xml
/fizz/customers/{customer-id}/agreements.xml
/fizz/employees/{employee-id}/agreements.xml
field | sample value | type | access |
---|---|---|---|
id | 56 | unique integer id | read-only |
fizzid | 63-234 | string (your database id) | |
address-id | 44 | integer | |
customer-id | 12 | integer | |
employee-id | 83 | integer | |
price | 123.45 | decimal | |
months-per-billing-cycle | 12 | integer (how often price is paid) | |
start-date | 2009-10-14T19:15:14Z | UTC datetime (iso8601) | |
end-date | 2010-10-14T19:15:14Z | UTC datetime (iso8601) | |
kind | Heating and Cooling | string | |
status | active | string (active or cancelled) | |
annual-visit-count | 2 (default) | integer (auto-generates visits) | |
visit-count | 3 | integer (total number of visits) | read-only |
created-at | 2011-09-12T20:42:13Z | UTC datetime (iso8601) | read-only |
updated-at | 2011-10-14T19:15:14Z | UTC datetime (iso8601) | read-only |
Agreements must non-empty values in the following fields:
- price
- month-per-billing-cycle
- kind
- address-id
- customer-id
...and the address must belong to the customer.
The visits on agreements with no end-date will automatically repeat annually. Each time one of those repeating visits is completed, a new visit will be created one year from the completion date.
Visits
/fizz/visits/{visit-id}.xml
/fizz/agreements/{agreement-id}/visits.xml
field | sample value | type | access |
---|---|---|---|
id | 424 | unique integer id | read-only |
fizzid | v12 | string (store your database ids here) | |
agreement-id | 56 | integer | |
completed-on | 2009-04-02T16:14:22Z | UTC datetime (iso8601) | |
scheduled-start | 2009-04-02T09:00:00Z | UTC datetime (iso8601) | |
scheduled-end | 2009-04-02T14:30:00Z | UTC datetime (iso8601) | |
status | active | string (active, cancelled, or completed) | |
tentative | true | boolean (true or false) | |
created-at | 2011-09-12T20:42:13Z | UTC datetime (iso8601) | read-only |
updated-at | 2011-10-14T19:15:14Z | UTC datetime (iso8601) | read-only |
Visits must have a scheduled-start and an agreement-id.
If the agreement has no end-date, setting a visit to "completed" status will cause a new visit to be created one year from the completed-on date.
Agreement Types
/fizz/agreement-types/{agreement-type-id}.xml
field | sample value | type | access |
---|---|---|---|
id | 37 | unique integer id | read-only |
fizzid | 63aa234 | string (your database id) | |
name | Heating and Cooling | string (must be unique) | |
price | 12.83 | decimal | |
months-per-billing-cycle | 1 | integer (how often price is paid) | |
duration-in-months | 12 | integer | |
annual-visit-count | 2 | integer | |
created-at | 2011-09-12T20:42:13Z | UTC datetime (iso8601) | read-only |
updated-at | 2011-10-14T19:15:14Z | UTC datetime (iso8601) | read-only |
The "kind" field on an agreement does not have to be the same as the "name" of an agreement type, but if it is, the agreement will pick up the default values from the agreement type on any missing fields.
Employees
/fizz/employees/{employee-id}.xml
field | sample value | type | access |
---|---|---|---|
id | 83 | unique integer id | read-only |
fizzid | emp-123 | string (store your database ids here) | |
number | 123 | string (this will be visible to the user) | |
status | active | string (active or cancelled) | |
first-name | Charlie | string (required field) | |
last-name | Bucket | string | |
wonka@example.com | string (valid email address, or blank) | ||
cell-phone | 5559876543 | 10-digit string | |
home-phone | 5552225050 | 10-digit string | |
created-at | 2011-09-12T20:42:13Z | UTC datetime (iso8601) | read-only |
updated-at | 2011-10-14T19:15:14Z | UTC datetime (iso8601) | read-only |
If an employee has a cell phone number, it must be unique across all employees.
Syncs
/fizz/syncs/{sync-id}.xml
field | sample value | type | access |
---|---|---|---|
id | 12 | unique integer id | read-only |
fizzid | cust-123 | string (store your database ids here) | |
in-progress | false | boolean (not completed, cancelled, or stalled) | read-only |
issues | System is offline | string (problems to show user) | |
log | Syncing record:123 | string (for debugging) | |
percent-complete | 45 | integer (0-100) -- controls sync status bar | |
created-at | 2011-09-12T20:42:13Z | UTC datetime (iso8601) | read-only |
updated-at | 2011-10-14T19:15:14Z | UTC datetime (iso8601) | read-only |
Syncs are used to communicate sync-related information (and issues) to the user. The user will be able to see:
- The time that the last sync completed
- The progress of the current sync (if one is in progress)
- Any issues encountered during the last sync
If you include a value for the "issues" field, a warning message will show up the user's Home page, and it will link to a page where they can see the text that is stored in the issues field.
You can also use the fizz-issues field on the customer to show sync issues that are specific to a certain customer -- these will also show a warning on the home page, but the details will include a link to the customer's page where the issue will be shown.
- Home
- Overview
- Workflow
- Authentication
- Pulling Data
- Pushing Data
- API Reference
- Getting Support
- ChangeLog