Priority REST API: The Errors That Waste the Most Time

The Priority REST API is built on OData and works well once you understand it, but a small set of behaviours costs hours on every first project. This is what is worth knowing before you start debugging rather than after.

For planning and scoping an integration project, see integrating with the Priority API. For pushing events out instead of polling, see Priority webhooks.

The URL shape - and what breaks in it

The base URL is:

https://<server>/odata/Priority/<tabula.ini>/<environment>/<FORM>

Three of these are a source of mistakes: tabula.ini is the tabula file the installation uses, and environment is the company's internal name in Priority - not the display name. Both differ between clients, and between test and production at the same client.

Guessing them wastes time. Ask whoever maintains the installation.

The most confusing error: XML from a JSON API

You send JSON, expect JSON, and get XML back. Validation errors return as a <FORM> element containing <InterfaceErrors>:

<InterfaceErrors>
  <text>Specify 'N' or 'Y' as the default value...</text>
</InterfaceErrors>

The practical problem: if your client tries to parse every response as JSON, every validation failure looks like a parse error, and the real message - which is usually precise and helpful - gets thrown away.

What to do: check the response content type, and when it is not JSON, extract the text from InterfaceErrors and log it verbatim. That message tells you exactly which field was rejected and why.

Keys: where this breaks

Single and composite keys

A record is addressed in parentheses after the entity name:

GET  /FAMILY_LOG('765')
GET  /AINVOICES(IVNUM='T9696',IVTYPE='A',DEBIT='D')

A composite key separates components by commas, each named explicitly. Omitting one component does not produce a clear error - it simply fails to find the record.

The trap: PATCH by auto-unique key

This is probably the most frustrating error on a first project. You cannot update a record by its auto-unique key. Use the regular unique key instead.

Why it is frustrating: the GET returns the record with the auto-unique key in it, you naturally use that key in the PATCH, and the result is a failure that looks like the record does not exist. If you see "not found" on a record you just read, this is almost always the reason.

Subforms

Subform rows are written by navigating from the parent:

POST  /ORDERS('SO18000002')/ORDERITEMS_SUBFORM
PATCH /ORDERS('SO18000002')/ORDERITEMS_SUBFORM(1)

You can also create parent and children in a single request by nesting the subform array in the body:

{
  "CUSTNAME": "007",
  "ORDERITEMS_SUBFORM": [
    { "PARTNAME": "111-001", "DUEDATE": "2016-08-01T00:00:00+03:00" }
  ]
}

This is the recommended way to create a document: one atomic request beats creating a header and then lines in separate calls, because a failure halfway through leaves a partial document in the system.

Authentication: three methods and one forbidden combination

The forbidden combination: you cannot use Basic Authentication while External ID access is enabled. This matters beyond setup - it means enabling External ID on the installation, for reasons entirely unrelated to you, will break an integration that has run for a year. Worth documenting with the client.

One more point: user permissions apply to the API. If the API user cannot see a form in the interface, they will not see it through the API either - and that manifests as missing records rather than a permission error.

Limits worth knowing up front

• Minimum version: the REST API is available from Priority 17.2 onward.
• Batching: up to 100 requests per call. Before version 21.0 the limit was 1,000. If you wrote an importer that relies on batches of 1,000 and the client upgraded, it is now broken.
• Field names: not intuitive, and not identical across installations.

$metadata - the biggest time saver

The /$metadata endpoint returns the full schema of that specific installation: entities, fields, types and relationships.

This matters especially in Priority because customised forms and fields differ between sites. Two clients on the same version can require completely different integration code. Any answer you find in a forum about a field name is correct for the installation of whoever wrote it, not necessarily yours.

So: before guessing a field name, pull $metadata from the client's installation and search it. It is also the correct way to discover which subforms exist and what they are called.

A debugging order that works

1. Confirm the URL is right - particularly tabula.ini and the environment name.
2. Verify the user holds an API licence and can see the form in the interface.
3. Pull $metadata and confirm the entity and field names.
4. GET a single record before attempting any write.
5. If a write fails - read the XML. The text in InterfaceErrors is almost always the precise explanation.