API Referencefarm-profiles

Create a farm profile

Provisions a new farm account under your team. This creates a cloud phone, rents an SMS number, and queues account signup as a background job that may take up to 24 hours to complete. TikTok signup challenges (captcha, age gate, SMS verification, recovery-email codes) are handled automatically. The response returns immediately with a `profile_id`. We POST lifecycle webhooks as the profile progresses — `profile.cold` when provisioning completes, warming and account-detail events during warmup (see `webhook_url`), `profile.ready` when warmup finishes, and `profile.banned` if the account is banned (a `failed` webhook is still on the roadmap). The profile is also retrievable at `GET /v1/farm-profiles/{profile_id}` with its current `status`. Each successful provisioning increments your monthly billing quantity. Pricing follows volume tiers — the more accounts you have, the lower the per-account rate. **Rate limit:** 10 requests per minute per team.

Authentication

X-API-Keystring
API Key authentication via header

Request

This endpoint expects an object.
platformstringRequired

Target social platform for the new account (e.g. tiktok). All profiles are currently provisioned in the US — country localization is on the roadmap.

usernamestringRequired
Desired handle for the new account.
webhook_urlstringRequired

HTTPS URL we POST profile lifecycle events to, each as {event, tiktok_username, phone_id}: profile.cold once provisioning finishes; profile.warming_started and profile.warming_completed around each ~15-minute warmup run (profile.warming_completed also carries warmup_count and the resulting status); profile.username_updated, profile.bio_updated, profile.nickname_updated, and profile.avatar_updated as account details are applied during the warm phase; profile.ready once warmup completes and the profile is postable; and profile.banned if the platform bans the account (terminal). Fire-and-forget; no retries.

account_namestring or nullOptional

Display name for the profile. Defaults to username if omitted.

keywordslist of stringsOptional

Search terms used to seed organic browsing during automated warmup. Used literally as TikTok search queries — pick whatever a real user of this account would search for. One is chosen at random per warmup run.

biostring or nullOptional

Account bio/about text set on the profile during setup. Optional.

profile_picture_urlstring or nullOptional
HTTPS URL of an image to set as the account's profile picture during setup. Optional.

Response

Successful Response
profile_idstring

Unique profile identifier. Provisioning runs asynchronously and may take up to 24 hours. Use this ID to look the profile up later — its status starts at configuring and progresses through cold → warming ↔ warm → ready.

Errors

402
Payment Required Error
422
Unprocessable Entity Error
429
Too Many Requests Error
502
Bad Gateway Error