Twitter Lead Gen API

Async job-based API. Submit a job, poll for status, retrieve results.

Important: When a job's 'view_url' is available, always share it with the user — it opens a spreadsheet GUI where they can browse, sort, and filter results visually.

Base URL

https://x-lead-gen-api-production.cloud.zoomgtm.com

Authentication

Two options (send one):

Core Workflow

''' POST /api/v1/jobs → 202 { job_id, status: "queued" } GET /api/v1/jobs/{job_id} → 200 { status: "processing"|"completed", ... } GET /api/v1/jobs/{job_id}/results → 200 { results: [...] } '''

1. Create Job

'''bash curl -X POST $BASE/api/v1/jobs
-H "Content-Type: application/json"
-H "x-officex-install-id: $INSTALL_ID"
-H "x-officex-install-secret: $INSTALL_SECRET"
-d '{ "endpoint": "search", "params": { "query": "AI startups" }, "max_records": 100 }' '''

Request body:

'''json { "endpoint": "search", "params": { "query": "AI startups" }, "prompt_filter": "SaaS founders discussing pricing", "max_records": 100 } '''

Response (202):

'''json { "job_id": "uuid", "status": "queued", "total_tasks": 4, "credits_reserved": 0.4, "poll_url": "/api/v1/jobs/{job_id}" } '''

2. Poll Status

'''bash curl $BASE/api/v1/jobs/{job_id} -H "x-api-key: $KEY" '''

Response:

'''json { "job_id": "uuid", "endpoint": "search", "status": "completed", "total_tasks": 4, "completed_tasks": 4, "failed_tasks": 0, "credits_per_task": 0.1, "credits_charged": 0.4, "params": { "query": "AI startups" }, "max_records": 100, "latest_cursor": "...", "created_at": "2025-01-25T10:00:00Z", "view_url": "https://example.com/dashboard/#/nc/view/uuid" } '''

'view_url' — opens a spreadsheet GUI (NocoDB) showing results for this job. Present it to the user so they can browse results visually. Only present once the job has started processing.

Status values: 'queued' | 'processing' | 'completed' | 'failed' | 'cancelled' | 'paused'

3. Get Results

'''bash curl "$BASE/api/v1/jobs/{job_id}/results?page=1&limit=50" -H "x-api-key: $KEY" '''

Response:

'''json { "job_id": "uuid", "endpoint": "search", "results": [ { "task_index": 0, "status": "success", "result_url": "https://s3.amazonaws.com/...", "item_urls": ["https://s3.amazonaws.com/..."], "credits_charged": 0.1, "match_score": 85, "ai_notes": "SaaS founder discussing B2B pricing" } ], "next_page": 2 } '''

'result_url' — full API response JSON. 'item_urls' — individual items (one per tweet/user/etc). 'match_score' and 'ai_notes' only present when 'prompt_filter' was used.

4. Control Jobs

'''bash

Pause

curl -X PATCH $BASE/api/v1/jobs/{job_id}
-H "x-api-key: $KEY" -H "Content-Type: application/json"
-d '{"status": "paused"}'

Resume

curl -X PATCH ... -d '{"status": "processing"}'

Cancel

curl -X PATCH ... -d '{"status": "cancelled"}' '''

Valid transitions: 'processing' → 'paused' → 'processing', any active → 'cancelled'.

5. Bookmark & Notes (per-item annotations)

Save bookmarks and notes on individual result items. Annotations persist in DynamoDB (result-rows table) and sync to the NocoDB spreadsheet view.

'''bash

Get all result rows (annotations) for a job

curl "$BASE/api/v1/jobs/{job_id}/result-rows" -H "x-api-key: $KEY" '''

Response:

'''json { "result_rows": [ { "job_id": "uuid", "sk": "0#0", "task_index": 0, "item_index": 0, "user_bookmarked": true, "user_notes": "Great lead", "updated_at": "...", "ttl": 1234567890 }, { "job_id": "uuid", "sk": "0#3", "task_index": 0, "item_index": 3, "user_bookmarked": false, "user_notes": "Follow up later", "updated_at": "...", "ttl": 1234567890 } ] } '''

'''bash

Bookmark or add notes to an item

curl -X PATCH "$BASE/api/v1/jobs/{job_id}/results/0/items/3"
-H "x-api-key: $KEY" -H "Content-Type: application/json"
-d '{"user_bookmarked": true, "user_notes": "Promising SaaS founder"}' '''

Response:

'''json { "success": true, "job_id": "uuid", "task_index": 0, "item_index": 3, "user_bookmarked": true, "user_notes": "Promising SaaS founder" } '''

Both fields are optional — send either or both. 'view_url' spreadsheet includes 'user_bookmarked' and 'user_notes' columns that sync automatically.

5b. NocoDB Webhook (2-way sync)

'''bash

NocoDB calls this when a user edits annotations in the spreadsheet

curl -X POST "$BASE/api/v1/webhooks/nocodb"
-H "x-webhook-secret: $NOCODB_WEBHOOK_SECRET"
-H "Content-Type: application/json"
-d '{"data":{"row":{"job_id":"uuid","task_index":0,"item_index":3,"user_bookmarked":true}}}' '''

Anti-loop: webhook writes to DynamoDB only, never syncs back to NocoDB.

5c. Legacy Endpoints (deprecated)

The following endpoints still work but are deprecated. Use the new endpoints above.

'''bash

DEPRECATED: Get annotations (use GET /result-rows instead)

curl "$BASE/api/v1/jobs/{job_id}/items" -H "x-api-key: $KEY"

DEPRECATED: Patch annotation (use PATCH /results/{task_index}/items/{item_index} instead)

curl -X PATCH "$BASE/api/v1/jobs/{job_id}/items/0:3"
-H "x-api-key: $KEY" -H "Content-Type: application/json"
-d '{"user_bookmarked": true}' '''

Endpoints (29)

User Endpoints

Tweet Endpoints

'search_type': Top, Latest, People, Photos, Videos. 'type' (top-posts): Likes, Retweets. 'period': Daily, Weekly, Monthly.

List Endpoints

Community Endpoints

'ranking': Top, New.

Other Endpoints

Bulk Requests

Pass 'params' as an array to create one task per item:

'''json { "endpoint": "user-info", "params": [ { "screenname": "elonmusk" }, { "screenname": "sama" }, { "screenname": "sataborasu" } ] } '''

Creates 3 tasks. Each task is billed independently.

Billing

Credits are reserved upfront, settled progressively as tasks complete. Failed tasks are not billed. Unused credits are refunded on completion/cancellation.

Auth Endpoints

POST '/auth/register'

'''json { "email": "user@example.com", "password": "min6chars" } ''' → '201 { api_key, install_id, email }'

POST '/auth/login'

'''json { "email": "user@example.com", "password": "..." } ''' → '200 { api_key, install_id, email }'

POST '/auth/officex-login'

'''json { "officex_customer_id": "uuid", "install_id": "uuid", "install_secret": "..." } ''' → '200 { api_key, install_id, install_secret }'

All Routes

Error Codes

All errors return: '{ "error": "Human-readable message" }'

Data Retention

Results stored for 90 days in S3.