{"openapi":"3.1.0","info":{"title":"MCAFax caller lookup","version":"1.2","description":"Look up one phone number or email address that contacted your business and see whether merchants have reported it to MCAFax. Possible matches, not proof of who called. Numbers get reassigned. Data under the MCAFax Data Terms; not legal advice.","termsOfService":"https://mcafax.com/lookup/sources#data-terms","contact":{"name":"MCAFax","url":"https://mcafax.com/stop-calls","email":"info@mcafax.com"}},"servers":[{"url":"https://mcafax.com/v1","description":"Same-origin API. Use this. It works with no extra DNS."},{"url":"https://api.mcafax.com/v1","description":"Optional alias of the same API, after the owner adds the DNS alias."}],"paths":{"/lookup":{"get":{"operationId":"lookupCaller","summary":"Look up one phone number or email address","description":"Exactly one identifier per call. Phones are normalized to E.164 (US default). Anonymous use is limited to 10 lookups an hour and 30 a day per IP; a key (POST /keys) allows 100 a day and 10 a minute. Never loop over many numbers.","parameters":[{"name":"phone","in":"query","required":false,"schema":{"type":"string"},"description":"A phone number, any common format; +1 is assumed for 10-digit numbers."},{"name":"email","in":"query","required":false,"schema":{"type":"string"},"description":"An email address."},{"name":"X-API-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Optional API key."}],"responses":{"200":{"description":"The lookup result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookupResult"}}}},"400":{"description":"Missing or invalid identifier, or more than one identifier."},"429":{"description":"Rate limit reached. Retry-After carries the seconds to wait.","headers":{"Retry-After":{"schema":{"type":"integer"}}}}}}},"/shops":{"get":{"operationId":"listShops","summary":"List directory shops (shop fields only, paged)","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1}},{"name":"category","in":"query","schema":{"type":"string","enum":["broker","debt_collector","lead_gen","direct_lender","vendor","other"]}}],"responses":{"200":{"description":"A page of shops."}}}},"/shops/{shop_id}":{"get":{"operationId":"getShop","summary":"One shop, every field with its source","parameters":[{"name":"shop_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The shop."},"404":{"description":"No such shop."}}}},"/templates":{"get":{"operationId":"listTemplates","summary":"Stop-letter templates keyed by caller category. General information, not legal advice.","responses":{"200":{"description":"The templates."}}}},"/changes":{"get":{"operationId":"listChanges","summary":"Public change log (no requester details)","parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Changes since the date."}}}},"/disputes":{"post":{"operationId":"fileDispute","summary":"Ask for a number or email to be corrected or removed","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisputeRequest"}}}},"responses":{"202":{"description":"Received. Acknowledged within 2 business days, decided within 5."}}}},"/corrections":{"post":{"operationId":"fileCorrection","summary":"Ask for a directory entry to be corrected","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CorrectionRequest"}}}},"responses":{"202":{"description":"Received."}}}},"/keys":{"post":{"operationId":"createKey","summary":"Get an API key","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"201":{"description":"The key, shown once."}}}}},"components":{"schemas":{"LookupResult":{"type":"object","properties":{"query":{"type":"object","properties":{"type":{"type":"string","enum":["phone","email"]},"value":{"type":"string"}}},"match":{"type":"boolean"},"summary":{"type":["string","null"],"description":"A match is category-neutral: \"Reported by merchants as associated with <shop>\" or \"Reported by merchants as a <category label> number\". No match: \"No association found in MCAFax's records.\""},"caller_category":{"type":["string","null"],"enum":["broker","debt_collector","lead_gen","direct_lender","vendor","other",null]},"caller_category_label":{"type":["string","null"]},"report_count":{"type":["integer","null"]},"first_report":{"type":["string","null"],"format":"date"},"last_report":{"type":["string","null"],"format":"date"},"status":{"type":["string","null"],"enum":["unverified","matched",null]},"shop":{"type":["object","null"],"properties":{"shop_id":{"type":"string"},"business_name":{"type":"string"},"url":{"type":"string"}}},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}},"disclaimer":{"type":"string","description":"No match: \"No match does not mean the caller is not a broker.\" Match: \"Possible match in MCAFax's records, not proof of who called. Numbers get reassigned. Not legal advice.\""},"dispute_url":{"type":"string"},"data_terms_url":{"type":"string"},"sources_url":{"type":"string"},"letter_template":{"type":["string","null"],"description":"The /templates key for this caller category."}}},"Source":{"type":"object","properties":{"source_type":{"type":"string"},"source_url":{"type":"string"},"first_seen":{"type":["string","null"]},"last_verified":{"type":["string","null"]}}},"DisputeRequest":{"type":"object","required":["reason"],"properties":{"phone":{"type":"string"},"email":{"type":"string"},"relationship":{"type":"string","enum":["my_number","reassigned","business","other"]},"reason":{"type":"string","maxLength":2000},"contact_email":{"type":"string","format":"email"}}},"CorrectionRequest":{"type":"object","required":["shop_id","reason"],"properties":{"shop_id":{"type":"string"},"field":{"type":"string"},"proposed_value":{"type":"string","maxLength":500},"reason":{"type":"string","maxLength":2000},"contact_email":{"type":"string","format":"email"}}}}}}