{"openapi":"3.1.0","info":{"title":"Find & Flip API","description":"Fresh marketplace searches, API key authentication, and prepaid credits. See /api/docs for pricing and examples.","version":"1.2.0"},"servers":[{"url":"https://findandflip.io"}],"paths":{"/api/v1/balance":{"get":{"tags":["Marketplace API"],"summary":"Get your available API credit balance","operationId":"balance_api_v1_balance_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"ApiKey":[]}]}},"/api/v1/jobs":{"post":{"tags":["Marketplace API"],"summary":"Create a fresh marketplace search","operationId":"create_job_api_v1_jobs_post","security":[{"ApiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128,"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingSearch"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs/{job_id}":{"get":{"tags":["Marketplace API"],"summary":"Get search status and its actual charge","operationId":"status_api_v1_jobs__job_id__get","security":[{"ApiKey":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs/{job_id}/results":{"get":{"tags":["Marketplace API"],"summary":"Read completed results; re-reading is free","operationId":"results_api_v1_jobs__job_id__results_get","security":[{"ApiKey":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Job Id"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":240,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingResults"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs/{job_id}/cancel":{"post":{"tags":["Marketplace API"],"summary":"Cancel a queued or running search","operationId":"cancel_api_v1_jobs__job_id__cancel_post","security":[{"ApiKey":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/phone/services":{"get":{"tags":["Phone numbers"],"summary":"Supported phone services, prices, and rental terms","operationId":"services_api_v1_phone_services_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"ApiKey":[]}]}},"/api/v1/phone/orders":{"post":{"tags":["Phone numbers"],"summary":"Reserve a short-term number or buy a 28-day rental","operationId":"create_api_v1_phone_orders_post","security":[{"ApiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[!-~]+$","title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneOrderInput"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["Phone numbers"],"summary":"List your phone orders and messages","operationId":"orders_api_v1_phone_orders_get","security":[{"ApiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}},{"name":"view","in":"query","required":false,"schema":{"enum":["all","waiting","received","closed"],"type":"string","default":"all","title":"View"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/phone/orders/search":{"post":{"tags":["Phone numbers"],"summary":"Search your numbers and codes without putting them in URLs","operationId":"search_orders_api_v1_phone_orders_search_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PhoneOrderSearch"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKey":[]}]}},"/api/v1/phone/orders/{order_id}":{"get":{"tags":["Phone numbers"],"summary":"Check your number and receive its verification code","operationId":"status_api_v1_phone_orders__order_id__get","security":[{"ApiKey":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/phone/orders/{order_id}/cancel":{"post":{"tags":["Phone numbers"],"summary":"Cancel an unused short-term number","operationId":"cancel_api_v1_phone_orders__order_id__cancel_post","security":[{"ApiKey":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/phone/orders/{order_id}/refund":{"post":{"tags":["Phone numbers"],"summary":"Refund a long-term rental within two hours if no SMS arrived","operationId":"refund_api_v1_phone_orders__order_id__refund_post","security":[{"ApiKey":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/phone/orders/{order_id}/activate":{"post":{"tags":["Phone numbers"],"summary":"Wake a current rental inbox to receive SMS","operationId":"activate_api_v1_phone_orders__order_id__activate_post","security":[{"ApiKey":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/emails/pricing":{"get":{"tags":["Email accounts"],"summary":"Get your price per successful Yahoo account","operationId":"pricing_api_v1_emails_pricing_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"ApiKey":[]}]}},"/api/v1/emails/orders":{"post":{"tags":["Email accounts"],"summary":"Queue owned Yahoo accounts; charge only successful creations","operationId":"create_api_v1_emails_orders_post","security":[{"ApiKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":128,"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailOrderInput"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["Email accounts"],"summary":"List only your email creation orders","operationId":"orders_api_v1_emails_orders_get","security":[{"ApiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/emails/orders/{order_id}":{"get":{"tags":["Email accounts"],"summary":"Read progress and actual charges without credentials","operationId":"status_api_v1_emails_orders__order_id__get","security":[{"ApiKey":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/emails/orders/{order_id}/credentials":{"get":{"tags":["Email accounts"],"summary":"Retrieve credentials for your successfully created accounts","operationId":"credentials_api_v1_emails_orders__order_id__credentials_get","security":[{"ApiKey":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/emails/orders/{order_id}/cancel":{"post":{"tags":["Email accounts"],"summary":"Stop creation and release credits for unfinished accounts","operationId":"cancel_api_v1_emails_orders__order_id__cancel_post","security":[{"ApiKey":[]}],"parameters":[{"name":"order_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Order Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"EmailOrderInput":{"properties":{"count":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Count","default":1},"concurrency":{"type":"integer","maximum":8.0,"minimum":1.0,"title":"Concurrency","default":8},"first_name":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"First Name"},"last_name":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Last Name"},"provider":{"type":"string","const":"yahoo","title":"Provider","default":"yahoo"}},"additionalProperties":false,"type":"object","title":"EmailOrderInput"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ListingResults":{"properties":{"jobId":{"type":"string","format":"uuid","title":"Jobid"},"marketplace":{"type":"string","enum":["facebook","ebay","offerup","vinted","craigslist"],"title":"Marketplace"},"offset":{"type":"integer","title":"Offset"},"count":{"type":"integer","title":"Count"},"total":{"type":"integer","title":"Total"},"items":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Items"}},"type":"object","required":["jobId","marketplace","offset","count","total","items"],"title":"ListingResults","description":"Paginated listings returned by a completed Find & Flip search."},"ListingSearch":{"properties":{"marketplace":{"type":"string","enum":["facebook","ebay","offerup","vinted","craigslist"],"title":"Marketplace"},"timeBudgetSeconds":{"anyOf":[{"type":"integer","maximum":240.0,"minimum":1.0},{"type":"null"}],"title":"Timebudgetseconds"},"query":{"type":"string","maxLength":100,"minLength":2,"title":"Query"},"maxResults":{"type":"integer","maximum":240.0,"minimum":1.0,"title":"Maxresults","default":20},"daysToScrape":{"anyOf":[{"type":"integer","maximum":90.0,"minimum":1.0},{"type":"null"}],"title":"Daystoscrape"},"searchZip":{"anyOf":[{"type":"string","maxLength":20,"minLength":3},{"type":"null"}],"title":"Searchzip"},"maxRadius":{"anyOf":[{"type":"integer","maximum":500.0,"minimum":1.0},{"type":"null"}],"title":"Maxradius"},"maxPrice":{"anyOf":[{"type":"number","exclusiveMinimum":0.0},{"type":"null"}],"title":"Maxprice"},"maxListingAgeHours":{"anyOf":[{"type":"integer","maximum":8760.0,"minimum":1.0},{"type":"null"}],"title":"Maxlistingagehours"},"maxScrollSeconds":{"type":"integer","maximum":90.0,"minimum":8.0,"title":"Maxscrollseconds","default":30},"collectAdditionalDetails":{"type":"boolean","title":"Collectadditionaldetails","default":false},"onlyNewListings":{"type":"boolean","title":"Onlynewlistings","default":false},"sortBy":{"type":"string","enum":["best_match","distance","creation_time","price"],"title":"Sortby","default":"best_match"}},"additionalProperties":false,"type":"object","required":["marketplace","query"],"title":"ListingSearch","description":"Submit a fresh search to Find & Flip's marketplace workers."},"PhoneOrderInput":{"properties":{"service":{"type":"string","enum":["ebay","poshmark","facebook","mercari","yahoo","vinted"],"title":"Service"},"mode":{"type":"string","enum":["short_term","long_term"],"title":"Mode","default":"short_term"},"country":{"type":"string","const":"US","title":"Country","default":"US"},"days":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Days"}},"additionalProperties":false,"type":"object","required":["service"],"title":"PhoneOrderInput"},"PhoneOrderSearch":{"properties":{"q":{"type":"string","maxLength":100,"title":"Q","default":""},"view":{"type":"string","enum":["all","waiting","received","closed"],"title":"View","default":"all"},"limit":{"type":"integer","maximum":100.0,"minimum":1.0,"title":"Limit","default":20},"offset":{"type":"integer","minimum":0.0,"title":"Offset","default":0}},"additionalProperties":false,"type":"object","title":"PhoneOrderSearch"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"ApiKey":{"type":"http","description":"Your ffapi_ API key","scheme":"bearer"}}}}