POST /v1/projects/:projectId/leased-accounts/request

POST/v1/projects/:projectId/leased-accounts/request

Phase 1stableidempotent

Auth: Bearer
Scope: leased:write

Ask for warmed TikTok accounts in a niche. Layers reviews the request, allocates accounts from the warmed pool, and attaches them to your project.

Requests are accepted via this API; accounts appear in GET /v1/leased-accounts once Layers assigns them.

Leased accounts are billed at $150/account/month, charged to the partner wallet on assignment - not on request. If Layers fulfills a request partially (say you asked for 5 and we could only assign 3), the status comes back as partial and you're only billed for the 3.

Path

projectId
stringrequired
Project that will own the assigned accounts.

Headers

Idempotency-Key
string (UUID)optional
Recommended. Same key + same body replays the response - prevents double-queueing the same request if your side retries.

Body

projectId
stringrequired
Must match the path :projectId. Included in the body so the server can reject mismatched retries.
count
integerrequired
How many accounts to lease. 1–50 per request.
niche
Nicherequired
What kind of account you want. See the Niche shape below.
target
stringoptional
Free-form description of what content will run on these accounts.
note
stringoptional
Any extra context. 2000 chars max.
requestId
stringoptional
Partner-created request id. If omitted, server generates one.

Niche

vertical
stringrequired
Broad category - coffee, fitness, mobile games, etc.
audience
stringoptional
Target audience description.
language
stringoptional
BCP-47 language tag. Determines which language pools we search.
geo
string[]optional
ISO country codes. Used to match accounts with relevant audiences.

Example request

curl https://api.layers.com/v1/projects/prj_254a4ce1-f4ca-42b1-9e36-17ca45ef3d39/leased-accounts/request \
  -H "Authorization: Bearer lp_..." \
  -H "Idempotency-Key: 9a2f1e44-6b3c-4d19-9e8a-f2d7c1b5e777" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "prj_254a4ce1-f4ca-42b1-9e36-17ca45ef3d39",
    "count": 5,
    "niche": {
      "vertical": "coffee",
      "audience": "home baristas 25–40",
      "language": "en",
      "geo": ["US", "CA", "GB"]
    },
    "target": "Short-form brew tutorials; paid UGC-style creative for ads."
  }'

const { requestId } = await layers.leasedAccounts.request(
  {
    projectId: "prj_254a4ce1-f4ca-42b1-9e36-17ca45ef3d39",
    count: 5,
    niche: {
      vertical: "coffee",
      audience: "home baristas 25–40",
      language: "en",
      geo: ["US", "CA", "GB"],
    },
    target: "Short-form brew tutorials; paid UGC-style creative for ads.",
  },
  { idempotencyKey: crypto.randomUUID() },
);

// poll requestId via getLeaseRequest

result = layers.leased_accounts.request(
    project_id="prj_254a4ce1-f4ca-42b1-9e36-17ca45ef3d39",
    count=5,
    niche={
        "vertical": "coffee",
        "audience": "home baristas 25–40",
        "language": "en",
        "geo": ["US", "CA", "GB"],
    },
    target="Short-form brew tutorials; paid UGC-style creative for ads.",
    idempotency_key=str(uuid.uuid4()),
)

Response

202Request accepted

{
  "requestId": "lreq_01HXZR7K8M2P4RSTUV56789AB",
  "status": "requested",
  "submittedAt": "2026-04-18T19:24:11Z"
}

Poll GET /v1/leased-accounts/requests/:id for progress. If something is holding up your request, the response may include a note.

Errors

Status	Code	When
422	`VALIDATION`	`count` out of range, `niche.vertical` missing, `geo` contains a non-ISO code.
401	`UNAUTHENTICATED`	Missing or invalid key.
402	`BILLING_EXHAUSTED`	Partner wallet wouldn't cover even one assignment. Request is not queued.
403	`FORBIDDEN_SCOPE`	Key lacks `leased:write`.
404	`NOT_FOUND`	Project not in your organization.
409	`CONFLICT`	Same `Idempotency-Key` replayed with a different body.
429	`RATE_LIMITED`	Write budget exhausted.

POST /v1/projects/:projectId/leased-accounts/request

Example request

Response

Errors

See also

On this page