Read, modify, and write resources

The Finale Inventory API follows the REST architecture. The intial authentication URL returns a set of URLs for the various resource collections defined in the API. Performing a GET on any of the collections returns a column major representation of the resource in the collection. Each resource is identified with a URL which can be used with GET to retrieve a representation of the resource and POST to update the resource (using POST instead of PUT is the primary departure from the REST architecture).

URL for modifying resources

Finale uses a different internal identifier than the external resource id for some resources. This is especially true on the product resource collection (URL is not always "/[account name]/[resource collection name]/[resource id]"). The correct resource URL can be retrieved on product creation (See complete example), by downloading the whole resource collection and retrieving the correct product (see below), or by filtering by id(See filtering resources).

Action URLs

Some resource have additional operations that can be triggered through a POST to a specific URL for that resource. For example, a shipment is shipped by posting information about the shipment operation to the URL contained actionUrlShip field of the shipment representation. The API documentation for the various resource representation describe these action URLs. These action URLs are included in the representation returned from the server only when the action is valid given the current state of the resource (otherwise they are omitted or are null).

Column major collection representation

Performing a GET operation on the URL of a resource collection will return a column major representation of the collection. For example, consider the product resource collection with three fields: productId, productUrl, and internalName (the product representation has additional fields but three fields are enough for this discussion).

When retrieving a representation of the single resource, the JSON document will be returned as an object with the three fields as the keys and the value of each key being the value for of the field for the resource:

{ "productId" : "NCP-002",
  "internalName" : "Green peony to crackle",
  "productUrl" : "/newcentury/api/product/NCP-002",
}

When retrieving the representation of the resource collection, the JSON document will still be returned with the three fields as the keys but the value of each key will be an array with exactly one entry per resource in the collection:

{ "productId" : ["NCP-002","NCP-018"],
  "internalName" : ["Green peony to crackle","Blue mine"],
  "productUrl" : ["/newcentury/api/product/NCP-002","/newcentury/api/product/NCP-018"],
}

This example shows the representation for a product resource collection containing two resources. The first resource has the value at position 0 in each array, and the second resource has the value at position 1.

Finale Inventory uses this representation to reduce the number of HTTP requests required for API clients to retrieve a local copy of commonly used data, such as the complete list of products or customers. This representation supports retrieving an entire resource collection in a single HTTP request. The column major structure interacts well with HTTP compression to create a very compact representation over the network.

Common data structures and data types

Contact mechanism

A contact mechanism is JSON structure which represents a physical address, telephone number, email address, or web address. Several resource types makes use of the contact mechanisms.

Fields in a contact mechanism structure:

contactMechTypeId
The type must be one of the following values: EMAIL_ADDRESS, POSTAL_ADDRESS, TELECOM_NUMBER, or WEB_ADDRESS.
infoString
For EMAIL_ADDRESS, TELECOM_NUMBER, or WEB_ADDRESS this is the email address, telephone number, or web address respectively. String of up to 255 characters.
address1
Street address. Applicable only to POSTAL_ADDRESS. String of up to 255 characters.
city
City. Applicable only to POSTAL_ADDRESS. String of up to 100 characters.
stateProvinceGeoId
Enumerated value for the state / province. Applicable only to POSTAL_ADDRESS. Must be one of the following (the bold letters are the value, the name is not part of the value):
AK Alaska, AL Alabama, AR Arkansas, AZ Arizona, CA California, CO Colorado, CT Connecticut, DC District of Columbia, DE Delaware, FL Florida, GA Georgia, GU Guam, HI Hawaii, IA Iowa, ID Idaho, IL Illinois, IN Indiana, KS Kansas, KY Kentucky, LA Louisiana, MA Massachusetts, MD Maryland, ME Maine, MI Michigan, MN Minnesota, MO Missouri, MS Mississippi, MT Montana, NC North Carolina, ND North Dakota, NE Nebraska, NH New Hampshire, NJ New Jersey, NM New Mexico, NV Nevada, NY New York, OH Ohio, OK Oklahoma, OR Oregon, PA Pennsylvania, PR Puerto Rico, RI Rhode Island, SC South Carolina, SD South Dakota, TN Tennessee, TX Texas, UT Utah, VA Virginia, VI Virgin Islands, VT Vermont, WA Washington, WI Wisconsin, WV West Virginia, WY Wyoming, AB Alberta, BC British Columbia, MB Manitoba, NB New Brunswick, NL Newfoundland and Labrador, NS Nova Scotia, NT Northwest Territories, NU Nunavut, ON Ontario, PE Prince Edward Island, QC Quebec, SK Saskatchewan, YT Yukon, AU-ACT Australian Capital Territory, AU-NSW New South Wales, AU-NT Northern Territory, AU-QLD Queensland, AU-SA South Australia, AU-TAS Tasmania, AU-VIC Victoria, AU-WA Western Australia, UK-ENG England, UK-NIR Northern Ireland, UK-SCT Scotland, UK-WLS Wales, UK-BFP British Forces.
countryGeoId
Enumerated value for the country. Applicable only to POSTAL_ADDRESS. Must be one of the following (the bold letters are the value, the name is not part of the value):
AFG Afghanistan, AGO Angola, ALB Albania, DZA Algeria, AND Andorra, ARE United Arab Emirates, ARG Argentina, ARM Armenia, ATA Antarctica, AUS Australia, AUT Austria, AZE Azerbaijan, BDI Burundi, BEL Belgium, BEN Benin, BFA Burkina Faso, BGD Bangladesh, BGR Bulgaria, BHR Bahrain, BHS Bahamas, BIH Bosnia And Herzegovina, BLR Belarus, BLZ Belize, BMU Bermuda, BOL Bolivia, BRA Brazil, BRB Barbados, BTN Bhutan, BWA Botswana, CAF Central African Republic, CAN Canada, CHE Switzerland, CHL Chile, CHN China, CIV Cote D'ivoire, CMR Cameroon, COD The Democratic Republic of The Congo, COG Congo, COL Colombia, CRI Costa Rica, CUB Cuba, CYP Cyprus, CZE Czech Republic, DEU Germany, DJI Djibouti, DNK Denmark, DOM Dominican Republic, DZA Algeria, ECU Ecuador, EGY Egypt, ERI Eritrea, ESH Western Sahara, ESP Spain, EST Estonia, ETH Ethiopia, FIN Finland, FJI Fiji, FLK Falkland Islands (malvinas), FRA France, GAB Gabon, GBR United Kingdom, GEO Georgia, GHA Ghana, GIB Gibraltar, GIN Guinea, GMB Gambia, GNB Guinea-bissau, GNQ Equatorial Guinea, GRC Greece, GRL Greenland, GTM Guatemala, GUY Guyana, HKG Hong Kong, HND Honduras, HRV Croatia (local Name: Hrvatska), HTI Haiti, HUN Hungary, IDN Indonesia, IND India, IRL Ireland, IRN Iran (islamic Republic Of), IRQ Iraq, ISL Iceland, ISR Israel, ITA Italy, JAM Jamaica, JOR Jordan, JPN Japan, KAZ Kazakhstan, KEN Kenya, KGZ Kyrgyzstan, KHM Cambodia, KOR Republic Of Korea, KWT Kuwait, LAO Lao People's Democratic Republic, LBN Lebanon, LBR Liberia, LBY Libyan Arab Jamahiriya, LIE Liechtenstein, LKA Sri Lanka, LSO Lesotho, LTU Lithuania, LUX Luxembourg, LVA Latvia, MAR Morocco, MCO Monaco, MDA Moldova, Republic Of, MDG Madagascar, MEX Mexico, MKD The Former Yugoslav Republic Of Macedonia, MLI Mali, MLT Malta, MMR Myanmar, MNE Montenegro, MNG Mongolia, MOZ Mozambique, MRT Mauritania, MWI Malawi, MYS Malaysia, NAM Namibia, NCL New Caledonia, NER Niger, NGA Nigeria, NIC Nicaragua, NLD Netherlands, NOR Norway, NPL Nepal, NZL New Zealand, OMN Oman, PAK Pakistan, PAN Panama, PER Peru, PHL Philippines, PNG Papua New Guinea, POL Poland, PRI Puerto Rico, PRK Democratic People's Republic Of Korea, PRT Portugal, PRY Paraguay, PSE Palestinian Territory, Occupied, QAT Qatar, ROU Romania, RUS Russian Federation, RWA Rwanda, SAU Saudi Arabia, SCOT Scotland, SDN Sudan, SEN Senegal, SGP Singapore, SJM Svalbard And Jan Mayen Islands, SLB Solomon Islands, SLE Sierra Leone, SLV El Salvador, SMR San Marino, SOM Somalia, SRB Serbia, SUR Suriname, SVK Slovakia (slovak Republic), SVN Slovenia, SWE Sweden, SWZ Swaziland, SYR Syrian Arab Republic, TCD Chad, TGO Togo, THA Thailand, TJK Tajikistan, TKM Turkmenistan, TLS East Timor, TTO Trinidad And Tobago, TUN Tunisia, TUR Turkey, TWN Taiwan, TZA United Republic Of Tanzania, UGA Uganda, UKR Ukraine, URY Uruguay, USA United States, UZB Uzbekistan, VEN Venezuela, VNM Vietnam, VUT Vanuatu, XKX Kosovo, YEM Yemen, ZAF South Africa, ZMB Zambia, ZWE Zimbabwe
contactMechId
Assigned by the server. Read only.

Example contact mechanism structures:

{
  "contactMechId":"10035",  
  "contactMechTypeId":"TELECOM_NUMBER",  
  "infoString":"(212) 123-0193",  
  "contactMechPurposeTypeId":"FAX_NUMBER"  
}

{
  "contactMechTypeId":"POSTAL_ADDRESS",  
  "infoString":"",  
  "address1":"89812 Lowell Ave.",  
  "city":"Campbell",  
  "stateProvinceGeoId":"CA",  
  "postalCode":"91022"  
}

Dates and times

The system expects all dates and times to be specified as ISO 8601 strings in UTC.

Normalized packing string

Most lists of items (e.g. shipment items, order items, etc.) in Finale have a normalizedPackingString field that specifies the packing for the item. If null, then the item is an open stock item. If not null, the normalized packing string starts with a floating point number which is the conversion factory. The conversion factor is followed by a space and then the user visible representation of the packing. The conversion factor is number of open stock units in each case of this packing. Currently the user visible representation must start with the letters cs indicating case.

Examples:

12 cs 12/1 Each packed unit converts to 12 open stock units and displays to the users as cs 12/1 or 12/1 depending on context
12 cs 4/3 Each packed unit converts to 12 open stock units, however is not interchangable with the previous example of cases packed 12 cs 12/1. Displays to the users as cs 4/3 or 4/3 depending on context
cs 12/1 This is an error, missing conversion factor
18 This is an error, missing user visible representation