Learn about the Finale Inventory API's resource patterns

Read, modify, and write resources

The Finale Inventory API follows the REST architecture. The initial 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, by downloading the whole resource collection and retrieving the correct product, or by filtering by id.

Action URLs

Some resources 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 representations describes 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.

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 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 make 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.

countryGeoId

Enumerated value for the country. Applicable only to POSTAL_ADDRESS.

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.