# Quickstart

[Open in the interactive reference](https://docs.api.lensing.ai/guides/start)

The Lensing REST API lets your integration read and change your Lensing data. Every request carries an access token and the API version it was written for, and every response is JSON.

In a few minutes, you create a sandbox and an access token, list two of your customers, fetch the next page and change one of them. To view the API endpoints, select the [Reference](https://docs.api.lensing.ai/) tab.

**Before you start**, you need:

- The permission **Manage System Access Token Scope (API-HUB)**, to create the access token. Roles such as Integration Admin include it.
- A role that can create sandboxes, such as **Sandbox User (No Merges)** or **Sandbox Developer (Merges allowed)**. You don't need this if you already have a public sandbox.

If you don't have these, ask your administrator.

Steps 1 to 4 are one-time setup. Steps 5 to 8 make your first calls.

### 1. Create a sandbox

Make your test calls in a sandbox, so that none of them affect your production data. If you already have a public sandbox, skip this step.

1. Sign in to Lensing.
2. Select the sandbox icon in the top right corner.
3. Select **Create Sandbox**.
4. Make sure **Make Public** is selected. Your token needs a public sandbox.
5. Select **Create**.

### 2. Create an access token

The token is tied to your sandbox, so its calls never touch production data.

1. Open **API Hub › Connect › Access Tokens** and select **Create Token**.
2. Enter a **Name**.
3. Select **Restrict this token to a sandbox** and choose your sandbox as the **Sandbox Environment**. You can set this only now: a token created without it reads and writes your production data.
4. Leave the **Expiration** at 30 days.
5. Select **Create Token**, then **Copy Token**. The value is shown only once.
6. Select **Close**. The token's page opens.

### 3. Grant it access

A new token can call nothing. On the token's page:

1. Select **Grant Access**.
2. In the tree on the left, open **Accounting › Customers**, or type *Accounting Customers* in the search box and select **Customers**.
3. On the **Broad Access** tab, select **Accounting Customers: Read Access**. Also select **Accounting Customers: Write Access** if you plan to change a record in step 8. Read access does not include it.
4. Select **Review Changes**, then **Confirm Changes**.

A grant can take up to five minutes to reach the token. If a request in step 5 answers `403` right after you grant access, wait a few minutes and try again. [Access tokens](https://docs.api.lensing.ai/guides/tokens.html) explains grants in full.

### 4. Store the token in your shell

The samples read the token from the `ACCESS_TOKEN` environment variable. Set it in the terminal you run them from, with the value you copied in step 2:

**Shell**

```
export ACCESS_TOKEN='<your access token>'
```

The samples are written for a macOS or Linux shell. On Windows, run them in Git Bash or WSL.

### 5. List customers

Ask for the first two customers. Every request carries the token in an `Authorization` header and the version it is written against in an `Api-Version` header.

**Request**

```
curl -g 'https://<your-tenant-host>/public/api/lensing/accounting/customers?page[size]=2' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Api-Version: v1'
```

Replace `<your-tenant-host>` with the address of your tenant, the one you sign in to the product at. `-g` stops curl from reading the brackets in `page[size]` as a pattern of its own.

### 6. Read the response

**Response**

```json
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "customerNumber": "CUS-1001",
      "customerName": "Acme Inc.",
      …
    },
    { … }
  ],
  "pagination": { "hasMore": true, "nextCursor": "…" }
}
```

The records are under `data`. A `401` means the token is missing or not valid; a `403` means it has not been granted this endpoint.

### 7. Fetch the next page

`pagination.hasMore` says there are more records. To fetch the next page, send the value of `pagination.nextCursor` back in the `page[cursor]` query parameter:

**Next page**

```
curl -g -G 'https://<your-tenant-host>/public/api/lensing/accounting/customers' \
  -d 'page[size]=2' \
  --data-urlencode 'page[cursor]=<nextCursor>' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Api-Version: v1'
```

Replace `<nextCursor>` with the value from the response. `--data-urlencode` encodes the cursor for the URL, and `-G` sends both parameters in the query string. When a response has no `nextCursor`, you have the last page.

### 8. Change a record

Set the invoice email of one of the customers you read. Replace `<id>` with that customer's `id` from the response. This needs the write access from step 3.

**Request**

```
curl -X PATCH 'https://<your-tenant-host>/public/api/lensing/accounting/customers/<id>' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Api-Version: v1' \
  -H 'Content-Type: application/json' \
  -d '{ "invoiceEmail": "ap@example.com" }'
```

A request with a body also needs `Content-Type: application/json`. Without it, the body is not read, and the request can succeed without changing anything. Only the fields you send change.

If the change worked, the response is an empty `data` object:

**Response**

```json
{ "data": {} }
```

To see the change, read the customer back:

**Request**

```
curl 'https://<your-tenant-host>/public/api/lensing/accounting/customers/<id>' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Api-Version: v1'
```

**Response**

```json
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "customerNumber": "CUS-1001",
    "name": "Acme Inc.",
    "invoiceEmail": "ap@example.com",
    …
  }
}
```

To check the change in Lensing, enter your sandbox, open the customer and look at its invoice email.

### Next steps

- Look up your calls on the **API Request Logs** page, under **API Hub** › **Operate** › **API Request Logs**.
- Read every page of a collection: [Pagination and querying](https://docs.api.lensing.ai/guides/pagination.html).
- Handle failures: [Responses and errors](https://docs.api.lensing.ai/guides/responses.html).
- Create and change records, and retry safely: [Writes](https://docs.api.lensing.ai/guides/writes.html) and [Idempotency](https://docs.api.lensing.ai/guides/idempotency.html).
- Be told about changes instead of polling for them: [Webhooks](https://docs.api.lensing.ai/guides/webhooks.html).

## Examples

**Base URL**

```
https://<your-tenant-host>/public/api/lensing
```

**Headers**

```
Authorization: Bearer <access token>
Api-Version: v1
Content-Type: application/json
```

Every path is appended to the base URL. `<your-tenant-host>` stands for your tenant's address. `Content-Type` is needed only on a request with a body; without it, the body is not read. The samples use `v1`, the version selected at the top of the page.