Quickstart

Open in the interactive reference

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 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.

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

2. Create an access token

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

Open API Hub › Connect › Access Tokens and select Create Token.
Enter a Name.
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.
Leave the Expiration at 30 days.
Select Create Token, then Copy Token. The value is shown only once.
Select Close. The token's page opens.

3. Grant it access

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

Select Grant Access.
In the tree on the left, open Accounting › Customers, or type Accounting Customers in the search box and select Customers.
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.
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 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

{
  "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

{ "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

{
  "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.
Handle failures: Responses and errors.
Create and change records, and retry safely: Writes and Idempotency.
Be told about changes instead of polling for them: Webhooks.

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.