Create a scan session

curl --request POST \
  --url https://www.closient.com/scanner/api/v1/sessions \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "capture_mode": "barcode_scan",
  "device_context": {
    "app_version": "2.1.0",
    "platform": "ios"
  },
  "metadata": {
    "order_id": "6735"
  },
  "organization_short_id": "keATfB8VP2gSjcnTbsMNQL",
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)"
}
'

import requests

url = "https://www.closient.com/scanner/api/v1/sessions"

payload = {
    "capture_mode": "barcode_scan",
    "device_context": {
        "app_version": "2.1.0",
        "platform": "ios"
    },
    "metadata": { "order_id": "6735" },
    "organization_short_id": "keATfB8VP2gSjcnTbsMNQL",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    capture_mode: 'barcode_scan',
    device_context: {app_version: '2.1.0', platform: 'ios'},
    metadata: {order_id: '6735'},
    organization_short_id: 'keATfB8VP2gSjcnTbsMNQL',
    user_agent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)'
  })
};

fetch('https://www.closient.com/scanner/api/v1/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.closient.com/scanner/api/v1/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'capture_mode' => 'barcode_scan',
    'device_context' => [
        'app_version' => '2.1.0',
        'platform' => 'ios'
    ],
    'metadata' => [
        'order_id' => '6735'
    ],
    'organization_short_id' => 'keATfB8VP2gSjcnTbsMNQL',
    'user_agent' => 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.closient.com/scanner/api/v1/sessions"

	payload := strings.NewReader("{\n  \"capture_mode\": \"barcode_scan\",\n  \"device_context\": {\n    \"app_version\": \"2.1.0\",\n    \"platform\": \"ios\"\n  },\n  \"metadata\": {\n    \"order_id\": \"6735\"\n  },\n  \"organization_short_id\": \"keATfB8VP2gSjcnTbsMNQL\",\n  \"user_agent\": \"Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.closient.com/scanner/api/v1/sessions")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"capture_mode\": \"barcode_scan\",\n  \"device_context\": {\n    \"app_version\": \"2.1.0\",\n    \"platform\": \"ios\"\n  },\n  \"metadata\": {\n    \"order_id\": \"6735\"\n  },\n  \"organization_short_id\": \"keATfB8VP2gSjcnTbsMNQL\",\n  \"user_agent\": \"Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.closient.com/scanner/api/v1/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"capture_mode\": \"barcode_scan\",\n  \"device_context\": {\n    \"app_version\": \"2.1.0\",\n    \"platform\": \"ios\"\n  },\n  \"metadata\": {\n    \"order_id\": \"6735\"\n  },\n  \"organization_short_id\": \"keATfB8VP2gSjcnTbsMNQL\",\n  \"user_agent\": \"Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)\"\n}"

response = http.request(request)
puts response.read_body

{
  "capture_count": 5,
  "capture_mode": "barcode_scan",
  "created": "2025-08-15T14:00:00Z",
  "metadata": {
    "order_id": "6735"
  },
  "modified": "2025-08-15T14:30:00Z",
  "photo_count": 3,
  "status": "active"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

POST

scanner

api

sessions

Create a scan session

curl --request POST \
  --url https://www.closient.com/scanner/api/v1/sessions \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "capture_mode": "barcode_scan",
  "device_context": {
    "app_version": "2.1.0",
    "platform": "ios"
  },
  "metadata": {
    "order_id": "6735"
  },
  "organization_short_id": "keATfB8VP2gSjcnTbsMNQL",
  "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)"
}
'

import requests

url = "https://www.closient.com/scanner/api/v1/sessions"

payload = {
    "capture_mode": "barcode_scan",
    "device_context": {
        "app_version": "2.1.0",
        "platform": "ios"
    },
    "metadata": { "order_id": "6735" },
    "organization_short_id": "keATfB8VP2gSjcnTbsMNQL",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    capture_mode: 'barcode_scan',
    device_context: {app_version: '2.1.0', platform: 'ios'},
    metadata: {order_id: '6735'},
    organization_short_id: 'keATfB8VP2gSjcnTbsMNQL',
    user_agent: 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)'
  })
};

fetch('https://www.closient.com/scanner/api/v1/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.closient.com/scanner/api/v1/sessions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'capture_mode' => 'barcode_scan',
    'device_context' => [
        'app_version' => '2.1.0',
        'platform' => 'ios'
    ],
    'metadata' => [
        'order_id' => '6735'
    ],
    'organization_short_id' => 'keATfB8VP2gSjcnTbsMNQL',
    'user_agent' => 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.closient.com/scanner/api/v1/sessions"

	payload := strings.NewReader("{\n  \"capture_mode\": \"barcode_scan\",\n  \"device_context\": {\n    \"app_version\": \"2.1.0\",\n    \"platform\": \"ios\"\n  },\n  \"metadata\": {\n    \"order_id\": \"6735\"\n  },\n  \"organization_short_id\": \"keATfB8VP2gSjcnTbsMNQL\",\n  \"user_agent\": \"Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.closient.com/scanner/api/v1/sessions")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"capture_mode\": \"barcode_scan\",\n  \"device_context\": {\n    \"app_version\": \"2.1.0\",\n    \"platform\": \"ios\"\n  },\n  \"metadata\": {\n    \"order_id\": \"6735\"\n  },\n  \"organization_short_id\": \"keATfB8VP2gSjcnTbsMNQL\",\n  \"user_agent\": \"Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.closient.com/scanner/api/v1/sessions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"capture_mode\": \"barcode_scan\",\n  \"device_context\": {\n    \"app_version\": \"2.1.0\",\n    \"platform\": \"ios\"\n  },\n  \"metadata\": {\n    \"order_id\": \"6735\"\n  },\n  \"organization_short_id\": \"keATfB8VP2gSjcnTbsMNQL\",\n  \"user_agent\": \"Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)\"\n}"

response = http.request(request)
puts response.read_body

{
  "capture_count": 5,
  "capture_mode": "barcode_scan",
  "created": "2025-08-15T14:00:00Z",
  "metadata": {
    "order_id": "6735"
  },
  "modified": "2025-08-15T14:30:00Z",
  "photo_count": 3,
  "status": "active"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

{
  "detail": "The requested resource was not found.",
  "error_code": "not_found",
  "retryable": false,
  "status": 404,
  "timestamp": "2026-03-31T12:00:00+00:00",
  "title": "Not Found",
  "type": "https://closient.com/docs/errors/not_found"
}

Authorizations

X-API-Key

string

header

required

Body

application/json

Request body for creating a new scan session.

metadata

Metadata · object | null

Developer-attached key/value data. Send {} or null to clear. Empty-string values delete that key. Omitted keys are preserved.

Show child attributes

organization_short_id

string

default:""

Organization short_id. Required for session auth; optional for API key auth (inferred from key).

user_agent

string

default:""

Browser user-agent string of the scanning device.

device_context

Device Context · object | null

Device metadata.

capture_mode

enum<string>

default:barcode_scan

Capture mode for this session.

Available options:

barcode_scan,

product_photography,

both

Response

Created

Scan session summary.

status

enum<string>

required

Lifecycle state of the session. ACTIVE while the operator is still adding captures; COMPLETED once they explicitly end or submit it; EXPIRED if a maintenance job reaped the session after sitting idle past its TTL.

Available options:

ACTIVE,

COMPLETED,

EXPIRED

capture_mode

enum<string>

required

Session capture mode.

Available options:

barcode_scan,

product_photography,

both

created

string<date-time>

required

Timestamp when the session was created.

modified

string<date-time>

required

Timestamp when the session was last modified.

metadata

Metadata · object

Developer-attached key/value data attached to this object. Up to 50 keys; key max 40 chars, value max 500 chars.

Show child attributes

capture_count

integer

default:0

Total number of captures.

photo_count

integer

default:0

Total number of product photos.

Overview

Account

Products

Brands

Locations

Retailers

Search

GS1 Digital Link

EPCIS 2.0

Integrations

Billing

Scanner

Compliance

Certifications

Sustainability

Notifications

Dashboard

Analytics

Agent

Substances

BYOS

Content

Signals

Create a scan session

Authorizations

Body

Response