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 | UUID | 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.
Addresses
/fizz/addresses/{address-id}.xml
/fizz/customers/{customer-id}/addresses.xml
field | sample value | type | access |
---|---|---|---|
id | 44 | UUID | read-only |
fizzid | a1 | string (store your database ids here) | |
customer-id | 12 | UUID | |
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.
Invoices
/fizz/invoices/{invoice-id}.xml
/fizz/get-optional-invoice-fields.xml
/fizz/invoices/get-payable-invoices.xml
field | sample value | type | access |
---|---|---|---|
id | 91 | UUID | read-only |
fizzid | inv-123 | string (store your database ids here) | |
customer-id | 12 | UUID | read-only |
external-id | 123ABC | string | read-only |
scheduled-at | 2014-10-07 11:30:00 | string | read-only |
total | 125.50 | decimal | read-only |
tax | 10.80 | decimal | 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 |
Line Items
/fizz/line-items/{line_item-id}.xml
field | sample value | type | access |
---|---|---|---|
id | 83 | UUID | read-only |
type | agreement | string (agreement, diagnostic, flatFee, custom) | read-only |
number | 012345 | string (repair number) | read-only |
description | 2" PLEATED FILTER | string | read-only |
price | 12.83 | decimal | 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 |
Syncs
/fizz/syncs/{sync-id}.xml
field | sample value | type | access |
---|---|---|---|
id | 12 | UUID | read-only |
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