---
title: "Generating unique IDs for entities upserted into LUSID"
slug: "generating-unique-ids-for-entities-upserted-into-lusid"
tags: ["sequence", "unique ID", "upsert", "transactions", "entity"]
updated: 2024-12-05T16:34:12Z
published: 2024-12-05T16:34:12Z
canonical: "support.lusid.com/generating-unique-ids-for-entities-upserted-into-lusid"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.lusid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generating unique IDs for entities upserted into LUSID

Some LUSID [entities](/v1/docs/what-is-an-entity) require you to specify a unique ID when performing an upsert operation. For example, consider the `transactionId` field in the following call to the [UpsertTransactions](https://www.lusid.com/docs/api/#operation/UpsertTransactions) API:

```json
curl -X POST 'https://<your-domain>.lusid.com/api/api/transactionportfolios/Equities/Growth/transactions'
   -H 'Authorization: Bearer <your-API-access-token>'
   -H 'Content-Type: application/json-patch+json'
   -d '[
      {
        "transactionId": "txn-equity-1",
        "type": "Buy",
        "instrumentIdentifiers": {"instrument/default/LusidInstrumentId": "LUID_00003D5C"},
        "transactionDate": "2021-11-15T00:00:00.0000000+00:00",
        "settlementDate": "2021-11-16T00:00:00.0000000+00:00",
        "units": 10,
        "transactionPrice": {"price": 350, "type": "Price" },
        "totalConsideration": {"amount": 3500, "currency": "GBP" },
        "transactionCurrency": "GBP"
     },
  ]'
```

You can use the APIs in the [Sequences](https://www.lusid.com/docs/api/lusid/endpoints/sequences/CreateSequence) collection to help automate the process of creating unique values for use in an upsert (or any other) operation.

## Creating a sequence

The first step is to create a sequence defining a number of values, and certain characteristics of those values.

> **Note**: A sequence is single use unless you set its `cycle` field to true. By default, once you have exhausted the values in a sequence, you cannot obtain them again; this helps ensure values are unique. Only change `cycle` to true if you want to generate non-unique values.

1. [Obtain an API token](/v1/docs/how-do-i-obtain-and-use-a-short-lived-api-access-token-from-okta).
2. Call the [CreateSequence](https://www.lusid.com/docs/api#operation/CreateSequence) API for a particular scope in your LUSID domain, specifying a code for the sequence and other characteristics in the body of the request. For example, the following call creates a `test/oddNumber` sequence consisting of 10 values, each with a prefix and a number between 1 and 19, in increments of 2 (so `txn-equity-1`, `txn-equity-3`, `txn-equity-5` and so on):

```json
curl -X POST "https://<your-domain>.lusid.com/api/api/sequences/test"
  -H "Content-Type: application/json-patch+json"
  -H "Authorization: Bearer <your-api-access-token>"
  -d "{
       'code':'oddNumber',
       'increment':2,
       'minValue':1,
       'maxValue':19,
       'start':1,
       'cycle':false,
       'pattern':'txn-equity-{{seqValue}}'
  }"
```

Note the response confirms the operation has succeeded but does not itself return the values:

```json
{
  "id": {
    "scope": "test",
    "code": "oddNumber"
  },
  "increment": 2,
  "minValue": 1,
  "maxValue": 19,
  "start": 1,
  "cycle": false,
  "pattern": "txn-equity-{{seqValue}}",
   ...
}
```

## Obtaining the values in a sequence

You can obtain the values in a sequence either one at a time or in batches.

To do this, call the [Next](https://www.lusid.com/docs/api#operation/Next) API for the scope and code of the sequence as many times as you need. For example, the first call to Next for the `test/oddNumber` sequence :

```json
curl -X GET "https://<your-domain>.lusid.com/api/api/sequences/test/oddNumber/next?batch=2"
  -H "Authorization: Bearer <your-api-access-token>"
```

...retrieves the first two values (to retrieve singly, omit the `batch` parameter):

```json
{
  "values": [
    "txn-equity-1",
    "txn-equity-3"
  ],
   ...
}
```

The second call to `Next` retrieves the next two values, and so on:

```json
{
  "values": [
    "txn-equity-5",
    "txn-equity-7"
  ],
   ...
}
```