# IDs

> Every record has an id, a hash string you put in paths and bodies. How it differs from unique keys and from the document numbers people see, and how to find a record by its number.

Web page: https://developer.yoprint.com/concepts/ids/

Every YoPrint record has an `id`. Use it whenever an operation needs to name a record: in the path, and in body fields that end in `_id`.

```json
{
  "id": "V4keXwwxMQyXw7",
  "scoped_id": "SO1001",
  "customer_id": "VwYKuTP9vd8Dfo"
}
```

## Three kinds of identifier

| Field        | What it is                                                                                                                 | Use it in requests?                  |
| ------------ | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `id`         | The record's **hash id**: a string of letters and digits, at least 14 long, with no prefix. Keep its upper and lower case. | Yes, everywhere.                     |
| `unique_key` | A second key on some records, starting with a type prefix such as `ord_`.                                                  | Only where a reference page says so. |
| `scoped_id`  | The **document number** people see, such as the sales order number.                                                        | No. Search for it instead.           |

> **Note:** The ids in these docs, such as `V4keXwwxMQyXw7`, are made up, but shaped like real ones. Treat every id as a string of letters and digits with no meaning of its own: never parse it, check its length or characters, change its case, or build one yourself.

## Hash ids

- Read a record's hash id from its `id` field, or from a related record's `*_id` field, such as an order's `customer_id`.
- Path parameters named `{hash_id}`, `{id}` or `{hash_id2}` take hash ids only.
- Body fields that point at another record, such as `customer_id`, `payment_method_id` or `status_id`, take hash ids.
- An id belongs to one team. It finds nothing on another team, even with the same key.

## Unique keys

Sales orders, quotes and their lines, invoices and their lines, shipments and their lines, jobs and payment links also have a unique key, such as `ord_` followed by a long string. Path parameters named `{order_unique_key}`, `{unique_key}` or `{order_item_unique_key}` accept either the hash id or the unique key.

You don't need unique keys. Some paths with `unique_key` in the parameter's name only work with the hash id. For example, listing an order's invoices or shipments with its unique key returns an empty list:

`GET /v2/api/store/{team_slug}/v2/sales_order/{unique_key}/invoice` [List the invoices of a sales order](https://developer.yoprint.com/reference/invoices/v2-sales-order-invoice-index-for-order.md)

Use the `id` field and you'll never hit this.

## Document numbers

The numbers on orders, invoices and other documents (`scoped_id`) are what people see in the web app and on PDFs, such as sales order `SO1001`. They aren't ids:

- A path with a document number answers `404`.
- Numbers can be edited, for example an invoice's or a job's, so they aren't a stable reference.
- Jobs and shipments show their number with a prefix, such as `JOB-7` and `SHIP-45`.

### Find a record by its number

To turn a sales order or quote number into its id, search for it:

`GET /v2/api/store/{team_slug}/search/orders` [Search sales orders and quotes](https://developer.yoprint.com/reference/search/v2-search-orders-get.md)

```bash
curl "https://secure.yoprint.com/v2/api/store/your-team/search/orders?q=SO1001" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "X-Yoprint-Decimal-Format: exact-v1"
```

The search matches order numbers, order names, customer PO numbers, customer names and any part of the addresses, and returns up to 30 matches. Pick the one whose `scoped_id` is exactly the number you want, then use its `id`.

## Catalog product ids

Products from a supplier catalog have their own ids, which start with the supplier's code and a hyphen, such as `smr-10001`. You send them as text where an operation asks for a catalog product, for example in a [catalog product line item](https://developer.yoprint.com/guides/line-items.md).