Marketplace data. Ready to build with.

Create accounts/emails/orders

Order history/emails/orders

Order status/emails/orders/{order_id}

Retrieve credentials/emails/orders/{order_id}/credentials

Cancel an order/emails/orders/{order_id}/cancel

→

Use the same ffapi_ Bearer key and API credits as marketplace searches. These emails are separate from internal inventory. Manage them in your email workspace.

Endpoints

Method	Path	Purpose
GET	`/api/v1/emails/pricing`	Your price per successful account.
POST	`/api/v1/emails/orders`	Queue an order. Requires Idempotency-Key.
GET	`/api/v1/emails/orders`	Your history, with limit and offset.
GET	`/api/v1/emails/orders/{id}`	Progress and actual charges, without passwords.
GET	`/api/v1/emails/orders/{id}/credentials`	Your successful accounts and passwords, including partial results.
POST	`/api/v1/emails/orders/{id}/cancel`	Stop unfinished creation. Completed accounts remain yours.

Create an account

curl -X POST 'https://findandflip.io/api/v1/emails/orders' \
  -H 'Authorization: Bearer ffapi_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: yahoo-order-001' \
  -d '{"provider":"yahoo","count":1,"first_name":"Alice","last_name":"Smith"}'

count defaults to 1 and accepts 1–100. For a single account, optionally provide both names; the address is built from them with a random suffix. Larger orders use generated names. Only Yahoo is supported. Creation uses the US flow.

Queue, billing, and retries

A successful submission returns 202 and an order id. Poll status every 10 seconds through queued → pending → running → completed. Orders may end as failed or canceled with partial results.

The maximum cost is reserved up front. Each saved mailbox is charged once at the price recorded when ordering; failed slots release their credits when the order ends. Read pricing before ordering. Reuse the same idempotency key and request body after timeouts; a new key creates another order. Status and credential reads are free.

Creation retries are bounded to 10 runs per slot, 20 minutes per run, and six hours per active batch. Only three unfinished orders per user are accepted. The shared creator queue limits concurrent VPS work.

Apify

The findandflip-yahoo-email-accounts Actor supports pricing, create, status, list, credentials, and cancel actions. Supply your Find & Flip key and a stable requestId. Results go to OUTPUT and may contain passwords. Stopping an Actor stops polling; use cancel to stop the underlying order. Apify compute charges are separate.

GET STARTED

Authentication

One API key. Access to your searches and credits.

Send a Bearer token

Include this header on every API request. Create and revoke keys in your workspace.

Authorization: Bearer ffapi_YOUR_SECRET_KEY

Try your key here

Paste your key into the live panel and select Connect. This makes a free balance request and loads your actual pricing. The panel sends requests only to this site’s API.

Your key stays in this page’s memory.

It is cleared on reload and is never included in copied code examples. Keep keys on your server, out of public frontend code, URLs, and source control.

Keep environments separate

A key belongs to the environment where you created it. Development uses separate credits and sandbox payments. A key can only access jobs from its own account.

Revoking a key stops future API access. It does not cancel searches already in progress.

GET STARTED

Pay for what
you receive.

Prepaid credits. Per-listing pricing. No subscription needed.

eBay sold listings$1.00per 1,000 listings

Facebook, OfferUp, Vinted & Craigslist$1.50per 1,000 listings

Standard prices in USD. Your balance endpoint and workspace show any custom volume rates assigned to your account. Contact us for volume pricing.

How credits work

Top up. Add $10, $20, $30, or a custom amount from $10 to $1,000. This is a one-time payment, separate from your subscription.
Reserve. Creating a search reserves the cost of its maximum result count.
Settle. You pay for the listings returned. Any unused reservation is released.

50 Facebook results = $0.075

Prices are prorated per listing with six-decimal USD precision. You don’t need to buy results in blocks of 1,000.

What is free?

Polling, re-reading results, and empty searches are free. Failed or cancelled jobs release their reservation. A completed job keeps its final charge, even if you later request cancellation.

A new search is independently billable, even if it returns listings you’ve seen before. Retry the same request with the same idempotency key to avoid creating a second search.

Payment confirmation

Stripe confirms credit purchases through a secure webhook. Returning from checkout alone does not add credits. Refunds and disputes adjust your balance, including credits already spent. API credits cannot be transferred to another user.

SEARCHES

Create a search

Get fresh listings for a marketplace and a set of keywords.

POST/api/v1/jobs202 Accepted

eBay searches return sold listings. Facebook, OfferUp, Vinted, and Craigslist searches return current listings. Searches run asynchronously; save the returned id to check progress and retrieve results.

Required headers

Authorization string · required: Bearer ffapi_… from your API workspace.
Idempotency-Key string · required: A unique identifier, 1–128 characters. Keep the same key and request body when retrying after a timeout.
Content-Type string · required: application/json

Request body

marketplace string · required: ebay, facebook, offerup, vinted, or craigslist.
query string · required: Search keywords, between 2 and 100 characters.
maxResults integer · default 20: 1–240 for eBay, 1–50 for other marketplaces. A maximum, not a guaranteed result count.

View all optional parameters →

Retries shouldn’t create double charges.

Same input + same idempotency key returns the original job. Reusing a key with different input returns 409. The playground keeps the key when you retry and creates a new one when you edit the body.

What happens next?

queued→running→completed

Check search status every 2–5 seconds. Once complete, get the results. Marketplace availability and worker capacity affect how long a search takes.

SEARCHES

Get search status

Follow a search from the queue to completion.

GET/api/v1/jobs/{job_id}

job_id UUID · required path parameter: The id returned when you created the search.

Search lifecycle

Status	Meaning
`queued`	Waiting for an available worker.
`running`	Collecting marketplace listings.
`completed`	Results are ready and the actual charge is settled.
`failed`	The search failed; reserved credits are released.
`cancelled`	The search was cancelled; reserved credits are released.

Polling is free. Use a 2–5 second interval. The playground can watch every 5 seconds for up to 5 minutes, then fetch the first page of completed results.

Stopping the watcher doesn’t cancel the search.

You can return to the job with its ID. Use the cancellation endpoint if you want to stop the job itself.

Billing in the response

billing.reserved shows the active reservation and becomes zero after settlement. billing.charged is the actual charge, and billing.settled says whether billing is final. billedListings counts the results you paid for.

SEARCHES

Get results

Structured JSON, ready for your next step.

GET/api/v1/jobs/{job_id}/results

Results are available after the search is completed. Requesting them earlier returns 409. Reading results again does not incur another charge.

job_id UUID · required path parameter: The ID of a search owned by your account.
offset integer · default 0: Number of results to skip. Must be zero or greater.
limit integer · default 50: 1–240 results per page, capped at the job’s result limit.

Pagination

Increase offset by the returned count. Continue until offset + count reaches total. The live response panel offers a next-page button when more results are available.

Listing fields

items contains marketplace-specific listing objects. Available fields vary by marketplace and listing; missing source information may be absent. Inspect your live response instead of assuming every listing has the same fields.

Example marketplace

Illustrative data, not live listings. IDs, sellers, and URLs are examples. Non-eBay examples include fields available with collectAdditionalDetails: true.

{
  "jobId": "67b201a6-c3b5-49fc-9f82-d3e50281e761",
  "marketplace": "ebay",
  "offset": 0,
  "count": 1,
  "total": 1,
  "items": [
    {
      "marketplace": "ebay",
      "itemId": "123456789012",
      "title": "Nintendo Switch OLED 64GB Console - White",
      "url": "https://www.ebay.com/itm/123456789012",
      "imageUrl": "https://example.com/images/switch-oled.jpg",
      "soldPrice": 219.99,
      "currency": "USD",
      "condition": "Used",
      "soldDate": "2026-10-31",
      "searchQuery": "Nintendo Switch OLED",
      "scrapedAt": "2026-11-01T15:30:00+00:00",
      "raw": {}
    }
  ]
}

eBay’s soldPrice is a number; the other marketplaces’ price is source price text. These are observed prices, not appraisals. Missing fields may be null or absent. Empty searches return count: 0, total: 0, and items: [], with no listing charge.

ACCOUNT

Get balance

Check your credits and account-specific rates.

GET/api/v1/balanceFree request

No request body or query parameters are needed.

available decimal string: Credits ready to use, excluding active reservations.
reserved decimal string: Credits held for active searches.
ratesPer1000 object: Your prices in USD per 1,000 listings for all five marketplaces, including custom volume pricing. OfferUp, Vinted, and Craigslist inherit your Facebook rate.

Use decimal amounts.

Money is returned as decimal strings with up to six decimal places. Use a decimal type for calculations in your application.

Need more credits? Top up in your workspace →

SEARCHES

Cancel a search

Stop a queued or running job and release its reservation.

POST/api/v1/jobs/{job_id}/cancel

job_id UUID · required path parameter: The search to cancel. No request body is needed.

Safe to repeat

Cancellation is idempotent. Calling it again does not create another charge or refund.

Completed searches stay completed.

If a job finished before cancellation, it keeps its results and final charge. The response shows its actual status.

Unused reservations reconcile automatically when you check status, view the workspace, or submit another search.

REFERENCE

Search parameters

Tune your request for each marketplace.

Parameter	Type / default	Details
`marketplace`	string · required	`ebay`, `facebook`, `offerup`, `vinted`, or `craigslist`.
`query`	string · required	2–100 characters.
`maxResults`	integer / 20	1–240 eBay; 1–50 other marketplaces.
`daysToScrape`	integer · optional	eBay only. 1–90 days.
`searchZip`	string · optional	3–20 characters. Required for OfferUp/Craigslist, optional for Facebook. Not supported by Vinted.
`maxRadius`	integer · optional	Facebook, OfferUp, and Craigslist radius: 1–500 miles.
`maxPrice`	number · optional	Maximum price for all marketplaces except eBay; greater than zero.
`maxListingAgeHours`	integer · optional	Facebook listing age, 1–8,760 hours.
`maxScrollSeconds`	integer / 30	8–90 seconds of scrolling.
`collectAdditionalDetails`	boolean / false	All marketplaces except eBay. Collect additional available details.
`onlyNewListings`	boolean / false	All marketplaces except eBay. Exclude listings from your previous completed searches with the same scope.
`sortBy`	string / best_match	`best_match` for OfferUp/Craigslist; Vinted also supports `creation_time` and `price`. Facebook additionally supports `distance`.

Invalid marketplace-specific combinations return 422. Use the JSON editor in the live panel to try optional fields. The OpenAPI schema contains full validation constraints.

← Back to create a search

REFERENCE

Errors & limits

Know what happened and what to do next.

HTTP status	Next step
`401` Unauthorized	Use a valid, active key from a verified account.
`402` Payment required	Add credits to cover the maximum result count.
`403` Forbidden	API access is disabled. Contact support.
`404` Not found	Check the job ID and the account that created it.
`409` Conflict	Check job status or the idempotency key’s original input.
`422` Validation error	Correct the fields identified in the JSON response.
`429` Too many requests	Wait for `Retry-After` before retrying.
`503` Unavailable	Retry later with exponential backoff.

Rate & concurrency limits

Up to 10 active API keys per account.
120 requests per key per minute.
Normally 2 active searches per account, plus a global worker capacity limit.

A 429 queue-capacity response includes the active-job count, limit, and retry delay. Retry 5xx responses with exponential backoff, keeping the same idempotency key for a search submission.

PHONE NUMBERS API

Your number.
Your next code.

US verification numbers for eBay, Poshmark, Facebook, Mercari, Yahoo, and Vinted. One balance across the app, API, and Apify.

Explore the endpoints

7 endpoints

GET

Availability and pricing/phone/services

Create a number/phone/orders

Order history/phone/orders

Status and messages/phone/orders/{order_id}

Cancel a number/phone/orders/{order_id}/cancel

Refund a rental/phone/orders/{order_id}/refund

Activate an inbox/phone/orders/{order_id}/activate

→

Short term$1.00only when a code arrives

28-day rental$42.00$1.50/day · prepaid · no renewal

Use your existing Find & Flip API key and prepaid credits. All responses are JSON. Number availability varies. Open your phone workspace →

How billing works

Short term: reserve $1 when ordering. It becomes a charge only when a verification code arrives. An expired, unused number or confirmed unused cancellation releases the reservation.
Long term: pay $42 upfront for 28 days. Daily usage does not change the price. The number expires without renewing.
Rental refunds: request within two hours of purchase, only if no SMS has arrived. A successful refund closes the number and returns the full $42 to your API balance.

Create a number

POST/api/v1/phone/orders202 Accepted

Send Authorization: Bearer ffapi_…, Content-Type: application/json, and a unique Idempotency-Key (1–128 visible ASCII characters). Reuse the same key and body after a timeout; a new key means a new purchase.

curl 'https://findandflip.io/api/v1/phone/orders' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: my-ebay-number-001' \
  --data '{"service":"ebay","mode":"short_term","country":"US"}'

service required: ebay, poshmark, facebook, mercari, yahoo, or vinted.
mode default short_term: short_term or long_term.
country default US: Only US is currently supported.
days optional: Automatically set to 28 for long-term rentals; other long-term durations are rejected. Short-term orders use 1 and expire at the provider's expiresAt, which is usually much sooner than a day.

Check status and receive codes

GET/api/v1/phone/orders/{order_id}

Save the returned id. Poll every 10 seconds. The response includes phoneNumber, status, expiresAt, billing, and messages. Each message has code, text, and receivedAt; a long-term message may have no extractable code, so always inspect its text. These are private messages—keep API responses out of public logs.

Method	Route	Purpose
GET	`/phone/services`	Current service availability and prices.
GET	`/phone/orders`	Your history: `limit` 1–100 (default 50), `offset` ≥ 0.
POST	`/phone/orders/{id}/cancel`	Cancel an unused short-term order. A code arriving first keeps its $1 charge.
POST	`/phone/orders/{id}/refund`	Request an eligible rental refund. Messages are checked again before refunding.
POST	`/phone/orders/{id}/activate`	Wake a current long-term inbox before requesting an SMS.

All routes above are relative to /api/v1. Cancel, refund, and activate take no request body. Repeated cancellation/refund requests do not duplicate credits. Reads are free.

Order states

Short-term numbers move from submitting to pending, then completed, expired, or cancelled. Rentals move through activating, active, then expired or refunded. Failed purchases return failed and release their reservation.

An interrupted purchase is not a failed purchase.

needs_review means the provider outcome is uncertain: credits remain reserved while support verifies it. refund_pending means a refund awaits confirmation. Keep the order ID; do not keep buying replacement numbers.

Use it through Apify

The Phone Numbers Actor uses your Apify account for ownership and billing. No Find & Flip account, API key, or prepaid balance is required. Select services, create, status, list, or cancel. The Actor offers short-term US numbers with the full verification-service catalog. Creation requires a stable requestId. Reuse it when rerunning a purchase, even in another Actor run.

{
  "action": "create",
  "service": "ebay",
  "mode": "short_term",
  "requestId": "ebay-verification-001",
  "waitForCode": false
}

The Actor saves the number and response to OUTPUT before any optional waiting. Stopping a run does not cancel the number. Apify bills $1 once when an SMS is available and retrieved; compute costs are separate. These purchases do not debit a Find & Flip balance. Long-term rentals, refund, and activate are available only through the separate app/API.

Limits and errors

Up to 10 open phone orders per user by default; 120 API requests per key per minute. Use 10-second polling. 402 means insufficient credit; 409 means an ineligible action or mismatched idempotency key; 422 means invalid inputs; 503 means availability or provider checks could not complete. Keep your request key when retrying.

EMAIL ACCOUNTS API

Account pricing

Read your price per successfully created Yahoo account.

GET/api/v1/emails/pricing200 OK

Returns your provider, country, availability, pricePerAccount, and currency. Reading pricing does not create an order.

Authentication

Send Authorization: Bearer ffapi_YOUR_KEY using a key from your API workspace.

EMAIL ACCOUNTS API

Create email accounts

Queue Yahoo accounts owned by your user.

POST/api/v1/emails/orders202 Accepted

The maximum cost is reserved up front. Saved mailboxes are charged once at the order’s saved price; unused credits are released when creation finishes.

Authentication

Send Authorization: Bearer ffapi_YOUR_KEY using a key from your API workspace.

Request body

provider string · default yahoo: Only Yahoo is supported.
count integer · default 1: 1–100 successful accounts.
first_name / last_name strings · optional: Provide both names for one email, or leave both blank. Bulk orders use generated names.

Reuse your request key when retrying.

Send an Idempotency-Key header containing 1–128 characters. The same input and key return the original order; a new key creates another order.

EMAIL ACCOUNTS API

List email orders

Read your email creation history.

GET/api/v1/emails/orders200 OK

Returns items, total, limit, and offset. Each order includes progress and billing. Passwords are omitted from history.

Authentication

Send Authorization: Bearer ffapi_YOUR_KEY using a key from your API workspace.

Query parameters

limit integer · default 20: 1–100 orders per page.
offset integer · default 0: Number of orders to skip. Must be non-negative.

EMAIL ACCOUNTS API

Get email order status

Check creation progress and actual charges.

GET/api/v1/emails/orders/{order_id}200 OK

Returns requestedCount, createdCount, status, and billing without passwords. Poll every 10 seconds. States include queued, pending, running, completed, failed, and canceled.

Authentication

Send Authorization: Bearer ffapi_YOUR_KEY using a key from your API workspace.

Path parameters

order_id UUID · required: The ID of an order owned by your authenticated user. Other users’ orders return 404.

EMAIL ACCOUNTS API

Get email credentials

Retrieve your successfully created email accounts.

GET/api/v1/emails/orders/{order_id}/credentials200 OK

Returns an accounts array with email, password, firstName, and lastName. Partial results are available during creation. Only the owning user can access the accounts; responses are not cached.

Authentication

Send Authorization: Bearer ffapi_YOUR_KEY using a key from your API workspace.

Path parameters

order_id UUID · required: The ID of an order owned by your authenticated user. Other users’ orders return 404.

EMAIL ACCOUNTS API

Cancel an email order

Stop the remaining work for your email order.

POST/api/v1/emails/orders/{order_id}/cancel200 OK

Successful accounts remain yours and keep their charges. Credits reserved for unfinished accounts are released after stopping is confirmed.

Authentication

Send Authorization: Bearer ffapi_YOUR_KEY using a key from your API workspace.

Path parameters

order_id UUID · required: The ID of an order owned by your authenticated user. Other users’ orders return 404.

Request body

No request body is required.

PHONE NUMBERS API

Services & pricing

Check supported services, current availability, and number pricing.

GET/api/v1/phone/services200 OK

Returns US service availability and pricing. Short-term numbers cost $1 when a verification code arrives. A 28-day rental costs $42 prepaid, with no automatic renewal.

Authentication

Send Authorization: Bearer ffapi_YOUR_KEY using a key from your API workspace.

PHONE NUMBERS API

Create a phone order

Reserve a verification number or purchase a 28-day rental.

POST/api/v1/phone/orders202 Accepted

A short-term order reserves $1 and is charged when a code arrives. A long-term rental charges $42 up front for 28 days. Save the returned order ID.

Authentication

Send Authorization: Bearer ffapi_YOUR_KEY using a key from your API workspace.

Request body

service string · required: ebay, poshmark, facebook, mercari, yahoo, or vinted.
mode string · default short_term: short_term or long_term.
country string · default US: US is supported. Long-term rentals run for 28 days.

Reuse your request key when retrying.

Send an Idempotency-Key header containing 1–128 characters. The same input and key return the original order; a new key creates another order.

PHONE NUMBERS API

List phone orders

Read your number history and verification messages.

GET/api/v1/phone/orders200 OK

Returns items, total, limit, and offset. Each owned order includes its phone number, state, messages, and billing.

Authentication

Send Authorization: Bearer ffapi_YOUR_KEY using a key from your API workspace.

Query parameters

limit integer · default 50: 1–100 orders per page.
offset integer · default 0: Number of orders to skip. Must be non-negative.

PHONE NUMBERS API

Get number & messages

Check your number and read incoming verification codes.

GET/api/v1/phone/orders/{order_id}200 OK

Returns the owned order, phoneNumber, messages, and billing. Poll every 10 seconds. No additional charge applies to status or message reads.

Authentication

Send Authorization: Bearer ffapi_YOUR_KEY using a key from your API workspace.

Path parameters

order_id UUID · required: The ID of an order owned by your authenticated user. Other users’ orders return 404.

PHONE NUMBERS API

Cancel a phone order

Cancel an unused short-term number.

POST/api/v1/phone/orders/{order_id}/cancel200 OK

The service checks for a code before canceling. If a code arrived, the order keeps its $1 charge; otherwise, a confirmed cancellation releases the reservation.

Authentication

Send Authorization: Bearer ffapi_YOUR_KEY using a key from your API workspace.

Path parameters

order_id UUID · required: The ID of an order owned by your authenticated user. Other users’ orders return 404.

Request body

No request body is required.

PHONE NUMBERS API

Refund a rental

Request a refund for an eligible long-term rental.

POST/api/v1/phone/orders/{order_id}/refund200 OK

Refunds are available within two hours if no SMS arrived. Messages are checked again before refunding. A pending provider confirmation is reported as refund_pending; repeated requests do not duplicate credits.

Authentication

Send Authorization: Bearer ffapi_YOUR_KEY using a key from your API workspace.

Path parameters

order_id UUID · required: The ID of an order owned by your authenticated user. Other users’ orders return 404.

Request body

No request body is required.

PHONE NUMBERS API

Activate a rental inbox

Wake your current long-term rental inbox before requesting an SMS.

POST/api/v1/phone/orders/{order_id}/activate200 OK

Use this action for a current rental. It does not purchase another number or renew the rental. Read order status to receive subsequent messages.

Authentication

Send Authorization: Bearer ffapi_YOUR_KEY using a key from your API workspace.

Path parameters

order_id UUID · required: The ID of an order owned by your authenticated user. Other users’ orders return 404.

Request body

No request body is required.