Embedding 101

Embedding is the easiest way to get more data out of fewer requests. It isn’t always going to be the right solution – sometimes multiple, limited calls will be more efficient – but this guide will show you how to navigate embeds so you can make the best decision for your project!

Before We Start

Any variables in the examples below that are in bold, like {an order ID} or {this part type} will need to be replaced with the appropriate ID. Constant values like part types and statuses can be found by querying the respective endpoints (ex: /parttype)

Level 1: Look for the _id

The first layer of embeds are easily found by browsing the endpoint in question. If you’re wondering what can be accessed from an Invoice, start by looking at the fields list and check for any fields that end in _id. That will be your first clue that the field in question can be embedded to give you the whole object, not just the ID.

Note that once you identify the field you want to embed, you’ll just embed the object, not object_id. So to get customer data from a specific invoice, your request would be:

GET /invoice/{invoice ID}?embed=customer

Level 2: Chaining Embeds

Let’s say you don’t just want the customer’s name from the invoice, you want to get the customer’s default email address, which isn’t returned by default with the customer embed. Repeat the step above with the customer object to determine which field you need to chain off customer:

Now, your final embed off the invoice to get the default_email object will be:

GET /invoice/{invoice ID}?embed=customer.default_email

Level 3: Supplementary Embeds

There are additional embeds available that aren’t immediately visible from the original object. These are “learn as you go” fields that are often used in the UI, which is why we recommend working through any new process in the UI first to explore possible embeds and endpoints.

Below are some frequently used and especially helpful supplementary embeds. These embeds are not always efficient in every scenario and should be used with discretion.

salesorder.lines

This embed will return an array of all the sales order’s lines along with the order object. You can also chain embeds for additional line data, as needed (note that the embeds after ‘lines’ revert to singular objects, as if being embedded off an individual line):

GET /salesorder?embed=lines.part

salesorder[operations]

These embeds will return the operations associated to the given order. Examples: salesorder.picks, salesorder.invoices, salesorder.pickuplines

GET /salesorder/{salesorder ID}?embed=picks

customer.groups

This will return an array of the groups a customer belongs to.

GET /customer/{customer ID}?embed=groups

Note: many of the above embeds will also work with other object types (part.groups, quote.lines etc.)

What’s Next?

Now that you have embeds down, check out the tutorial on Advanced Filtering to learn more!

Tip: combine embeds and filters with an ampersand:

GET /part?filter=parttype_id={alias}&&parent_part_id={part ID}&embed=parent_part