{"openapi":"3.1.0","info":{"title":"Telegram Finder API","version":"2.0.0-alpha.0","description":"API documentation for Telegram Finder. Rate limit - maximum 100 Telegram user search per hour. If you need higher quotas we can work to unblock them; contact valentin@telegram-finder.io\n        "},"servers":[{"url":"https://www.telegram-finder.io","description":"Production server","variables":{}},null],"paths":{"/api/account/rate-limit":{"get":{"tags":["Account"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string","description":"Api key for authenticating requests, available [here](https://www.telegram-finder.io/account/api)"}}],"responses":{"200":{"description":"Rate limit information","content":{"application/json":{"schema":{"type":"object","properties":{"isPremium":{"type":"boolean","description":"Whether the user has premium access"},"privateSearching":{"type":"boolean","description":"Whether the user has private searching enabled"},"limits":{"type":"object","properties":{"freeDaily":{"type":"object","properties":{"used":{"type":"number","description":"Successful free searches used today"},"limit":{"type":"number","description":"Daily free successful-search credit limit"},"remaining":{"type":"number","description":"Remaining free successful-search credits today"}}},"hourlyRequests":{"type":"object","properties":{"used":{"type":"number","description":"Number of requests in the last hour"},"limit":{"type":"number","description":"Hourly request limit"},"remaining":{"type":"number","description":"Remaining requests for the hour"}}}}}}}}}},"401":{"description":"Unauthorized"},"402":{"description":"Premium membership required"},"500":{"description":"Internal server error"}},"summary":"Get rate limit information","description":"Retrieve current usage and rate limits for the authenticated user. Requires premium membership for API access."}},"/api/account/usage":{"get":{"tags":["Account"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string","description":"Api key for authenticating requests, available [here](https://www.telegram-finder.io/account/api)"}}],"responses":{"200":{"description":"Usage statistics for the current billing period","content":{"application/json":{"schema":{"type":"object","properties":{"start":{"type":"number","description":"Start time of the billing period (Unix timestamp)"},"end":{"type":"number","description":"End time of the billing period (Unix timestamp)"},"total":{"type":"number","description":"Total aggregated usage value"},"summaries":{"type":"array","items":{"type":"object","description":"Meter event summaries"}}}}}}},"400":{"description":"Invalid subscription details."},"402":{"description":"Premium membership required"}},"summary":"Get account usage","description":"Retrieve the usage statistics for the authenticated user's account within the current billing period. Requires premium membership for API access."}},"/api/contacts/{id}":{"delete":{"tags":["Contacts"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string","description":"Api key for authenticating requests, available [here](https://www.telegram-finder.io/account/api)"}},{"name":"id","in":"path","description":"Contact ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Contact deleted successfully"},"400":{"description":"Missing contact ID"},"401":{"description":"Unauthorized"},"402":{"description":"Premium membership required"},"404":{"description":"Contact not found"},"500":{"description":"Internal server error"}},"summary":"Delete contact","description":"Delete a specific contact by ID and all its associated identifiers. Requires premium membership for API access."},"get":{"tags":["Contacts"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string","description":"Api key for authenticating requests, available [here](https://www.telegram-finder.io/account/api)"}},{"name":"id","in":"path","description":"Contact ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Contact details with identifiers and associated Telegram accounts","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Contact ID"},"user_id":{"type":"string","description":"User ID"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"identifiers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Identifier ID"},"contact_id":{"type":"string","description":"Contact ID"},"type":{"type":"string","enum":["phone","email","linkedin"],"description":"Identifier type"},"value":{"type":"string","description":"Identifier value"},"telegram":{"type":["object","null"],"properties":{"username":{"type":"string","description":"Telegram username"},"bio":{"type":"string","description":"Telegram bio"},"firstname":{"type":"string","description":"First name"},"lastname":{"type":"string","description":"Last name"}}}}}}}}}}},"400":{"description":"Missing contact ID"},"401":{"description":"Unauthorized"},"402":{"description":"Premium membership required"},"404":{"description":"Contact not found"}},"summary":"Get specific contact","description":"Retrieve a specific contact by ID for the authenticated user. Requires premium membership for API access."},"put":{"tags":["Contacts"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string","description":"Api key for authenticating requests, available [here](https://www.telegram-finder.io/account/api)"}},{"name":"id","in":"path","description":"Contact ID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Contact updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Contact ID"},"firstname":{"type":"string","description":"First name"},"lastname":{"type":"string","description":"Last name","nullable":true},"location":{"type":"string","description":"Location","nullable":true},"company":{"type":"string","description":"Company","nullable":true},"updated_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Invalid request data or missing contact ID"},"401":{"description":"Unauthorized"},"402":{"description":"Premium membership required"},"404":{"description":"Contact not found"},"500":{"description":"Internal server error"}},"summary":"Update contact","description":"Update a specific contact by ID. Requires premium membership for API access.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstname":{"type":"string","description":"First name"},"lastname":{"type":"string","description":"Last name","nullable":true},"location":{"type":"string","description":"Location","nullable":true},"company":{"type":"string","description":"Company","nullable":true}}}}}}}},"/api/contacts":{"delete":{"tags":["Contacts"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string","description":"Api key for authenticating requests, available [here](https://www.telegram-finder.io/account/api)"}}],"responses":{"200":{"description":"Contacts deleted successfully","content":{"application/json":{"schema":{"type":"object","properties":{"deleted":{"type":"number","description":"Number of contacts deleted"}}}}}},"400":{"description":"Invalid request data"},"401":{"description":"Unauthorized"},"402":{"description":"Premium membership required"},"500":{"description":"Internal server error"}},"summary":"Delete contacts (bulk)","description":"Delete multiple contacts by their IDs and all their associated identifiers. Requires premium membership for API access.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","format":"uuid"},"description":"Array of contact IDs to delete"}},"required":["ids"]}}}}},"get":{"tags":["Contacts"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string","description":"Api key for authenticating requests, available [here](https://www.telegram-finder.io/account/api)"}},{"name":"search","in":"query","description":"Search term to filter contacts by identifier value","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"List of contacts with their identifiers and associated Telegram accounts","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number","description":"Total number of contacts"},"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Contact ID"},"user_id":{"type":"string","description":"User ID"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"identifiers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Identifier ID"},"contact_id":{"type":"string","description":"Contact ID"},"type":{"type":"string","enum":["phone","email","linkedin"],"description":"Identifier type"},"value":{"type":"string","description":"Identifier value"},"telegram":{"type":["object","null"],"properties":{"username":{"type":"string","description":"Telegram username"},"bio":{"type":"string","description":"Telegram bio"},"firstname":{"type":"string","description":"First name"},"lastname":{"type":"string","description":"Last name"}}}}}}}}}}}}}},"401":{"description":"Unauthorized"},"402":{"description":"Premium membership required"},"404":{"description":"Contacts not found"}},"summary":"Get user contacts","description":"Retrieve a list of contacts for the authenticated user, optionally filtered by search term. Requires premium membership for API access."},"post":{"tags":["Contacts"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string","description":"Api key for authenticating requests, available [here](https://www.telegram-finder.io/account/api)"}}],"responses":{"201":{"description":"Contacts created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"number","description":"Number of contacts created"},"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Contact ID"},"firstname":{"type":"string","description":"First name"},"lastname":{"type":"string","description":"Last name","nullable":true},"location":{"type":"string","description":"Location","nullable":true},"company":{"type":"string","description":"Company","nullable":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}}},"400":{"description":"Invalid request data"},"401":{"description":"Unauthorized"},"402":{"description":"Premium membership required"},"500":{"description":"Internal server error"}},"summary":"Create contacts (bulk)","description":"Create multiple contacts with their identifiers in a single request. Requires premium membership for API access.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"firstname":{"type":"string","description":"First name"},"lastname":{"type":"string","description":"Last name","nullable":true},"location":{"type":"string","description":"Location","nullable":true},"company":{"type":"string","description":"Company","nullable":true},"emails":{"type":"array","items":{"type":"string","format":"email"},"description":"Email addresses"},"phones":{"type":"array","items":{"type":"string"},"description":"Phone numbers"},"linkedins":{"type":"array","items":{"type":"string","format":"uri"},"description":"LinkedIn URLs"}},"required":["firstname"]}}},"required":["contacts"]}}}}}},"/api/enrich/phone":{"post":{"tags":["Enrich"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string","description":"Api key for authenticating requests, available [here](https://www.telegram-finder.io/account/api)"}}],"responses":{"200":{"description":"Phone enrichment initiated successfully","content":{"application/json":{"schema":{"type":"boolean","example":true}}}},"400":{"description":"Invalid identifier type (must be linkedin or email)"},"401":{"description":"Unauthorized"},"402":{"description":"Premium membership required"},"404":{"description":"Identifier not found"},"500":{"description":"Failed to enrich phone information"}},"summary":"Enrich contact to get phone number","description":"Enrich a contact identifier to get phone number using LinkedIn URL or email address. Requires premium membership for API access.","requestBody":{"description":"Contact identifier ID to enrich","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Contact identifier ID (must be of type linkedin or email)"}},"required":["id"]}}}}}},"/api/enrich/telegram":{"post":{"tags":["Enrich"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string","description":"Api key for authenticating requests, available [here](https://www.telegram-finder.io/account/api)"}}],"responses":{"200":{"description":"Telegram enrichment initiated successfully","content":{"application/json":{"schema":{"type":"boolean","example":true}}}},"400":{"description":"Invalid identifier type (must be phone)"},"401":{"description":"Unauthorized"},"402":{"description":"Premium membership required"},"404":{"description":"Identifier not found"}},"summary":"Enrich contact to get Telegram account","description":"Enrich a contact identifier to get Telegram account using phone number. Requires premium membership for API access.","requestBody":{"description":"Contact identifier ID to enrich","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Contact identifier ID (must be of type phone)"}},"required":["id"]}}}}}},"/api/telegram":{"post":{"tags":["Telegram"],"parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string","description":"Api key for authenticating requests, available [here](https://www.telegram-finder.io/account/api)"}}],"responses":{"200":{"description":"A mapping of phone numbers to public Telegram user information.","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":["object","null"],"properties":{"id":{"type":"string","description":"Telegram user ID"},"phone":{"type":"string","description":"Phone number associated with the Telegram account"},"username":{"type":"string","description":"Telegram username"},"firstName":{"type":"string","description":"First name of the user"},"lastName":{"type":"string","description":"Last name of the user"},"fullname":{"type":"string","description":"Full name of the user"},"imgUrl":{"type":"string","description":"URL to the user's profile image"},"bio":{"type":"string","description":"User biography"},"verified":{"type":"boolean","description":"Whether the user is verified"},"status":{"type":"string","description":"Current status of the user"}}}}}}},"400":{"description":"Invalid input data"},"401":{"description":"Unauthorized"},"402":{"description":"Premium membership required"},"429":{"description":"Too many requests in the last hour, please try later or enable private mode"},"500":{"description":"Internal server error"}},"summary":"Search Telegram users by phone numbers","description":"Search for Telegram users using an array of phone numbers. Returns public user information for each phone number provided. Requires premium membership for API access. Rate limit - maximum 100 Telegram user search per hour. If you need higher quotas we can work to unblock them; contact valentin@telegram-finder.io","requestBody":{"description":"An object containing an array of phone numbers to search for.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phoneNumbers":{"type":"array","items":{"type":"string"},"description":"Array of phone numbers to search on Telegram.","example":["+1234567890","+1987654321"]}},"required":["phoneNumbers"]}}}}}},"/api/telegram/usernames":{"post":{"tags":["Telegram"],"parameters":[],"responses":{"200":{"description":"One result for each unique username"},"400":{"description":"Invalid input data"},"401":{"description":"Unauthorized"},"402":{"description":"Premium membership required for bulk or API-key access"},"429":{"description":"Telegram rate limit reached"}},"summary":"Search Telegram users by usernames"}}}}