{"openapi":"3.1.0","info":{"title":"call4me API","version":"1.2.0","description":"Manage the account's phone numbers (including the user's own, verified to call from) and retrieve existing call recordings. Phone calls and other account tools are available through MCP."},"servers":[{"url":"https://call4.me"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A call4me API key or OAuth access token for the site or MCP resource."}}},"paths":{"/api/numbers":{"get":{"operationId":"listNumbers","description":"The account's phone numbers, and the countries more can be bought in with today's prices. Calls go out from a number in the callee's country when the account holds one. US, Canadian and European businesses can always be called (Europe from a European number if the account has one, else from its US number), and UAE ($0.40/min) and Japanese ($0.40/min) businesses too, from the account's US number (the business sees a US caller ID); elsewhere, a number in the country is what lets the account call there. Numbers cost exactly what the carrier charges: the upfront cost plus the first month when bought, then the monthly cost every 30 days, taken from the balance. own_numbers are the user's own phone numbers verified with call4me_verify_number: free, and used only when call4me_place_call names one in from.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The account's numbers and the countries more can be bought in","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"numbers":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string","description":"formatted for people"},"e164":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2"},"country_name":{"type":"string"},"type":{"type":"string","description":"local, mobile, national or toll_free"},"included":{"type":"boolean","description":"the free number that came with the account"},"monthly":{"type":"string"},"monthly_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"renews":{"description":"date the next monthly charge is due; null for the free number","type":["string","null"]},"overdue":{"type":"boolean","description":"the last renewal failed for lack of credits"},"release_after":{"description":"when an overdue number is released unless credits are added","type":["string","null"]}},"required":["number","e164","country","country_name","type","included","monthly","monthly_cents","renews","overdue","release_after"],"additionalProperties":{}}},"pending_numbers":{"description":"numbers paid for and waiting on the carrier's approval (numbers abroad are reviewed first, minutes to a few days). They activate by themselves and cannot place calls until they move to numbers. Omitted when there are none","type":"array","items":{"type":"object","properties":{"number":{"type":"string","description":"formatted for people"},"e164":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2"},"country_name":{"type":"string"},"type":{"type":"string","description":"local, mobile, national or toll_free"},"monthly":{"type":"string"},"monthly_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ordered":{"type":"string","description":"date it was bought; it activates once the carrier approves it, and its first month starts then"}},"required":["number","e164","country","country_name","type","monthly","monthly_cents","ordered"],"additionalProperties":{}}},"own_numbers":{"description":"the user's own phone numbers, verified to call from: calls go out from one only when place_call names it in from. Omitted when the account has none","type":"array","items":{"type":"object","properties":{"number":{"type":"string","description":"formatted for people"},"e164":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2"},"country_name":{"type":"string"},"status":{"type":"string","enum":["pending","verified"],"description":"pending: the code was sent and has not come back yet"},"method":{"type":"string","enum":["sms","call"],"description":"how the code was sent"},"verified_at":{"type":["string","null"]}},"required":["number","e164","country","country_name","status","method","verified_at"],"additionalProperties":{}}},"countries":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"available":{"type":"boolean"},"reason":{"description":"why a number cannot be bought there right now","type":["string","null"]},"upfront_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"monthly_cents":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"price":{"description":"taken from the balance when buying: upfront cost plus the first month","type":["string","null"]},"monthly":{"type":["string","null"]}},"required":["country","name","type","available","reason","upfront_cents","monthly_cents","price","monthly"],"additionalProperties":{}}}},"required":["numbers","countries"],"additionalProperties":{}}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}},"post":{"operationId":"buyNumber","description":"Buy another phone number, in the US or abroad, paid from the balance at the carrier's own price (see call4me_list_numbers for prices). It renews from the balance every 30 days; if the balance can't cover a renewal the number is released after 7 days. Only buy when the user asks for a number or needs one to call a country. A number abroad is reviewed by the carrier after it's paid for, from minutes to a few days: it comes back pending, activates by itself, and can't place calls until then.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"country":{"type":"string","pattern":"^[A-Za-z]{2}$","description":"ISO country code from the countries list, e.g. \"NL\", \"GB\", \"CA\", \"US\""},"area_code":{"description":"preferred area code (national destination code), e.g. \"415\" or \"20\"; the nearest available is used otherwise","type":"string","pattern":"^\\d{2,5}$"}},"required":["country"],"additionalProperties":false}}}},"responses":{"201":{"description":"The number bought, ready to call from","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"number":{"type":"string","description":"formatted for people"},"e164":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2"},"country_name":{"type":"string"},"type":{"type":"string","description":"local, mobile, national or toll_free"},"included":{"type":"boolean","description":"the free number that came with the account"},"monthly":{"type":"string"},"monthly_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"renews":{"description":"date the next monthly charge is due; null for the free number","type":["string","null"]},"overdue":{"type":"boolean","description":"the last renewal failed for lack of credits"},"release_after":{"description":"when an overdue number is released unless credits are added","type":["string","null"]}},"required":["number","e164","country","country_name","type","included","monthly","monthly_cents","renews","overdue","release_after"],"additionalProperties":{}}}}},"202":{"description":"The number bought and waiting on the carrier's approval; it activates by itself","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"pending":{"type":"object","properties":{"number":{"type":"string","description":"formatted for people"},"e164":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2"},"country_name":{"type":"string"},"type":{"type":"string","description":"local, mobile, national or toll_free"},"monthly":{"type":"string"},"monthly_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ordered":{"type":"string","description":"date it was bought; it activates once the carrier approves it, and its first month starts then"}},"required":["number","e164","country","country_name","type","monthly","monthly_cents","ordered"],"additionalProperties":{}}},"required":["pending"],"additionalProperties":false}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"402":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"502":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"503":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/numbers/{number}":{"delete":{"operationId":"releaseNumber","description":"Give up one of the account's bought numbers. Its monthly charge stops; what was already paid is not refunded, and the number cannot be gotten back. The free number that came with the account cannot be released. Only do this when the user asks.","security":[{"bearerAuth":[]}],"parameters":[{"name":"number","in":"path","required":true,"description":"E.164, URL-encoded (+ as %2B)","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":3,"maxLength":40,"description":"one of the account's numbers, e.g. \"+31612345678\""}}],"responses":{"200":{"description":"The number released","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"number":{"type":"string","description":"formatted for people"},"e164":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2"},"country_name":{"type":"string"},"type":{"type":"string","description":"local, mobile, national or toll_free"},"included":{"type":"boolean","description":"the free number that came with the account"},"monthly":{"type":"string"},"monthly_cents":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"renews":{"description":"date the next monthly charge is due; null for the free number","type":["string","null"]},"overdue":{"type":"boolean","description":"the last renewal failed for lack of credits"},"release_after":{"description":"when an overdue number is released unless credits are added","type":["string","null"]}},"required":["number","e164","country","country_name","type","included","monthly","monthly_cents","renews","overdue","release_after"],"additionalProperties":{}}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"502":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/numbers/own":{"post":{"operationId":"sendNumberVerification","description":"Send a verification code to the user's own phone number: a text, or a call that reads the code out. Submit the code with POST /api/numbers/own/{number}/verify. At most 5 codes a day.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"number":{"type":"string","minLength":3,"maxLength":40,"description":"the user's own phone number, e.g. \"+14155550123\" or \"(415) 555-0123\""},"method":{"default":"sms","description":"how to send the code: a text, or a call that reads it out (for landlines)","type":"string","enum":["sms","call"]},"extension":{"description":"keys the verification call dials once answered, to get past a phone menu to an extension; w waits half a second, W one second. method \"call\" only","type":"string","pattern":"^[0-9A-D*#wW]{1,50}$"}},"required":["number","method"],"additionalProperties":false}}}},"responses":{"202":{"description":"The code was sent; the number waits on it","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"number":{"type":"string","description":"formatted for people"},"e164":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2"},"country_name":{"type":"string"},"status":{"type":"string","enum":["pending","verified"],"description":"pending: the code was sent and has not come back yet"},"method":{"type":"string","enum":["sms","call"],"description":"how the code was sent"},"verified_at":{"type":["string","null"]}},"required":["number","e164","country","country_name","status","method","verified_at"],"additionalProperties":{}}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"502":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/numbers/own/{number}/verify":{"post":{"operationId":"confirmNumberVerification","description":"Submit the code the user's own number received. Once accepted, calls can go out from it (from in call4me_place_call), to businesses in its own country.","security":[{"bearerAuth":[]}],"parameters":[{"name":"number","in":"path","required":true,"description":"E.164, URL-encoded (+ as %2B)","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":3,"maxLength":40,"description":"one of the user's own numbers on the account, e.g. \"+14155550123\""}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"code":{"type":"string","pattern":"^[0-9A-Za-z]{3,12}$","description":"the code the user received"}},"required":["code"],"additionalProperties":false}}}},"responses":{"200":{"description":"The number, verified","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"number":{"type":"string","description":"formatted for people"},"e164":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2"},"country_name":{"type":"string"},"status":{"type":"string","enum":["pending","verified"],"description":"pending: the code was sent and has not come back yet"},"method":{"type":"string","enum":["sms","call"],"description":"how the code was sent"},"verified_at":{"type":["string","null"]}},"required":["number","e164","country","country_name","status","method","verified_at"],"additionalProperties":{}}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"502":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/numbers/own/{number}":{"delete":{"operationId":"removeOwnNumber","description":"Stop calling from one of the user's own numbers, or drop one still waiting on its code. Verifying it again needs a new code. Only do this when the user asks.","security":[{"bearerAuth":[]}],"parameters":[{"name":"number","in":"path","required":true,"description":"E.164, URL-encoded (+ as %2B)","schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":3,"maxLength":40,"description":"one of the user's own numbers on the account, e.g. \"+14155550123\""}}],"responses":{"200":{"description":"The number removed","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"number":{"type":"string","description":"formatted for people"},"e164":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2"},"country_name":{"type":"string"},"status":{"type":"string","enum":["pending","verified"],"description":"pending: the code was sent and has not come back yet"},"method":{"type":"string","enum":["sms","call"],"description":"how the code was sent"},"verified_at":{"type":["string","null"]}},"required":["number","e164","country","country_name","status","method","verified_at"],"additionalProperties":{}}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"502":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/calls/{call_id}/recordings":{"get":{"operationId":"getCallRecordings","description":"Get existing recordings of a finished call owned by the signed in account. Returns fresh download links when available. An empty list means no recording is available yet. Links may expire; request this again for fresh links. Only share the links with the user.","security":[{"bearerAuth":[]}],"parameters":[{"name":"call_id","in":"path","required":true,"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"string","minLength":1,"maxLength":40,"description":"The call id returned when placing or listing calls."}}],"responses":{"200":{"description":"Available recordings and fresh download links","content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"call_id":{"type":"string"},"recordings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"download_urls":{"type":"object","properties":{"mp3":{"type":"string","format":"uri"},"wav":{"type":"string","format":"uri"}},"additionalProperties":{}},"duration_millis":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"started_at":{"type":["string","null"]},"ended_at":{"type":["string","null"]}},"required":["id","download_urls","duration_millis","started_at","ended_at"],"additionalProperties":{}}},"message":{"type":"string"}},"required":["call_id","recordings","message"],"additionalProperties":{}}}}},"400":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"502":{"description":"Request failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}}}}