# Avatars API Source: https://docs.cleariflow.com/avatars GET https://avatars.cleariflow.com/v1 Cleariflow Avatars API is a fast, lightweight, modern, and RESTful JSON API for creating highly customizable avatar images with a person's name or initials to improve your user experience. Using this service is straightforward: simply provide your `api_key` along with a `name`, and the system will create an avatar image that corresponds to the initials of the provided name. ## Getting started ### REST The Avatars API follows the same architectural pattern as all Cleariflow services, built around REST principles. It employs predictable, resource-focused URLs and utilizes HTTP status codes for error communication. ### HTTPS The Avatars API mandates that all data transmission be protected using TLS 1.2 or higher encryption protocols. ### API Versions Every Cleariflow service includes versioning. The Avatars API presently operates on Version 1. ### Your API Key Your API key serves as your exclusive authentication credential for accessing the Cleariflow Avatars API. Keep in mind that every Cleariflow service possesses its own distinct API key, meaning you'll require separate keys for different services like Avatars and Email Validation APIs. To verify your requests, you must include your API key in the base URL. ### Base URL ``` https://avatars.cleariflow.com/v1/ ``` ### Validation endpoint The Cleariflow Avatars API only needs your exclusive API key and the user's name for avatar generation: ``` https://avatars.cleariflow.com/v1/ ? api_key = YOUR_UNIQUE_API_KEY & name = Alexander Rodriguez ``` This request was processed successfully, and the resulting avatar for the specified name appears below: Avatar for Alexander Rodriguez ### Request parameters Your exclusive API key. Remember that each user possesses unique API keys for every Cleariflow service, so your Avatars API key won't function with your IP Geolocation API, for instance. The name for which you wish to generate an avatar. You can input multiple names (including first, middle, and last), and the service will automatically show two letters in the avatar. You can modify the letter count using the char\_limit parameter below. The dimensions of the square avatar image in pixels. It automatically defaults to 64 pixels, with available sizes ranging from 6 to 512 pixels. The preferred format for the generated image. It automatically defaults to "png", but you can also choose "svg". The font size expressed as a percentage of the image\_size. It automatically defaults to 0.7, with acceptable values between 0.1 and 1.0. The maximum character count to display in the avatar. It automatically defaults to 2. The actual character count shown may be fewer than this limit, but never more. Character selection prioritizes distinct words first, then the second letter of distinct words. The hexadecimal color code for the background. It automatically defaults to #335eea. When specifying a hex color, omit the "#" symbol. For example, \&background\_color=e4704a is valid while \&background\_color=#e4704a is invalid. The hexadecimal color code for the text. It automatically defaults to white (ffffff). When specifying a hex color, omit the "#" symbol. For example, \&font\_color=e4704a is valid while \&font\_color=#e4704a is invalid. Generates a circular avatar image instead of a square one. It automatically defaults to false. Converts all initials in the avatar to capital letters. It automatically defaults to true. Applies italic styling to all initials in the avatar. It automatically defaults to false. Applies bold styling to all initials in the avatar. It automatically defaults to false. # Introduction Source: https://docs.cleariflow.com/bank-validation Cleariflow Bank Validation API provides comprehensive validation for International Bank Account Numbers (IBAN) and Business Identifier Codes (BIC) through a modern RESTful JSON interface, supporting 50+ countries with detailed validation and formatting information. ## Getting started The `iban` endpoint validates International Bank Account Numbers with comprehensive country-specific validation, format checking, and detailed structural information for financial applications. The `bic` endpoint validates Business Identifier Codes, providing detailed breakdown of bank codes, country information, and institution types for international banking operations. Comprehensive list of supported countries for IBAN and BIC validation, including country codes, currency information, and specific formatting requirements. ### REST Architecture The Bank Validation API follows REST principles, utilizing predictable resource-oriented URLs and standard HTTP status codes for seamless integration and error handling. ### HTTPS Security All API communications are secured using TLS 1.2 or higher encryption protocols to ensure data integrity and privacy. ### API Versioning The Bank Validation API maintains backward compatibility through versioning, currently operating on Version 1 with planned future enhancements. ### Authentication Your API key serves as the exclusive credential for accessing the Bank Validation API. Each Cleariflow service requires a unique key, ensuring secure and isolated access across different APIs. ## Response and error codes When requests fail, the API returns structured JSON error responses with specific codes and descriptions for effective troubleshooting. | Code | Type | Details | | ---- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | OK | Everything worked as expected. | | 400 | Bad request | Bad request - missing or invalid parameters. | | 401 | Unauthorized | The request was unacceptable. Typically due to the API key missing or incorrect. | | 422 | Quota reached | The request was aborted due to insufficient API credits. (Free plans) | | 429 | Too many requests | The request was aborted due to the number of allowed requests per second being reached. This happens on free plans as requests are limited to 1 per second. | | 500 | Internal server error | The request could not be completed due to an error on the server side. | | 503 | Service unavailable | The server was unavailable. | # BIC validation Source: https://docs.cleariflow.com/bank-validation/bic GET https://bankvalidation.cleariflow.com/v1/bic/ The `bic` endpoint validates Business Identifier Codes, providing detailed breakdown of bank codes, country information, and institution types for international banking operations. ## Getting started ### Base URL ``` https://bankvalidation.cleariflow.com/v1/bic/ ``` ### Validation endpoint The `bic` endpoint requires your API key and a BIC parameter to perform comprehensive validation of Business Identifier Codes. ``` https://bankvalidation.cleariflow.com/v1/bic/ ? api_key = YOUR_UNIQUE_API_KEY & bic = DEUTDEFF500 ``` This successful request validates a German BIC and returns detailed information: ```json theme={"system"} { "bic": "DEUTDEFF500", "is_valid": true, "country_code": "DE", "country_name": "Germany", "bank_code": "DEUT", "bank_name": "Bank information not available", "location_code": "F", "branch_code": "500", "details": { "type": "BIC", "active": true, "institution_type": "Bank" } } ``` ### Request parameters Your unique API key. Note that each user has unique API keys *for each of Cleariflow APIs*, so your Bank Validation API key will not work for your Exchange Rates API, for example. The Business Identifier Code to validate. Spaces are allowed and will be automatically removed during processing. The BIC should follow the ISO 9362 standard format. ### Response parameters The API response is returned in a universal and lightweight [JSON format](https://www.json.org/json-en.html). The normalized BIC without spaces, returned in uppercase format. Overall validation result indicating whether the BIC is valid according to all validation rules. The two-letter ISO country code (e.g., DE for Germany, US for United States). The full name of the country associated with the BIC. The 4-character bank identifier code (e.g., DEUT for Deutsche Bank). The name of the bank (currently shows "Bank information not available"). The 2-character location code indicating the city or region (e.g., FF for Frankfurt). The 3-character branch code (optional, may be empty for 8-character BICs). Additional detailed information about the BIC type and status. The type of identifier (typically "BIC"). Whether the BIC is currently active and in use. The type of financial institution (e.g., "Bank", "Credit Union"). ## Examples ### Valid German BIC (8 characters) **Request:** ``` GET https://bankvalidation.cleariflow.com/v1/bic/?api_key=YOUR_API_KEY&bic=DEUTDEFF ``` **Response:** ```json theme={"system"} { "bic": "DEUTDEFF", "is_valid": true, "country_code": "DE", "country_name": "Germany", "bank_code": "DEUT", "bank_name": "Bank information not available", "location_code": "FF", "branch_code": "", "details": { "type": "BIC", "active": true, "institution_type": "Bank" } } ``` ### Valid German BIC (11 characters with branch) **Request:** ``` GET https://bankvalidation.cleariflow.com/v1/bic/?api_key=YOUR_API_KEY&bic=DEUTDEFF500 ``` **Response:** ```json theme={"system"} { "bic": "DEUTDEFF500", "is_valid": true, "country_code": "DE", "country_name": "Germany", "bank_code": "DEUT", "bank_name": "Bank information not available", "location_code": "FF", "branch_code": "500", "details": { "type": "BIC", "active": true, "institution_type": "Bank" } } ``` ### Valid US BIC **Request:** ``` GET https://bankvalidation.cleariflow.com/v1/bic/?api_key=YOUR_API_KEY&bic=CHASUS33 ``` **Response:** ```json theme={"system"} { "bic": "CHASUS33", "is_valid": true, "country_code": "US", "country_name": "United States", "bank_code": "CHAS", "bank_name": "Bank information not available", "location_code": "33", "branch_code": "", "details": { "type": "BIC", "active": true, "institution_type": "Bank" } } ``` ### Valid UK BIC **Request:** ``` GET https://bankvalidation.cleariflow.com/v1/bic/?api_key=YOUR_API_KEY&bic=NWBKGB2L ``` **Response:** ```json theme={"system"} { "bic": "NWBKGB2L", "is_valid": true, "country_code": "GB", "country_name": "United Kingdom", "bank_code": "NWBK", "bank_name": "Bank information not available", "location_code": "2L", "branch_code": "", "details": { "type": "BIC", "active": true, "institution_type": "Bank" } } ``` ### Invalid BIC **Request:** ``` GET https://bankvalidation.cleariflow.com/v1/bic/?api_key=YOUR_API_KEY&bic=INVALID ``` **Response:** ```json theme={"system"} { "bic": "INVALID", "is_valid": false, "country_code": "", "country_name": "", "bank_code": "", "bank_name": "Bank information not available", "location_code": "", "branch_code": "", "details": { "type": "BIC", "active": true } } ``` ## Error handling ### Missing BIC parameter **Request:** ``` GET https://bankvalidation.cleariflow.com/v1/bic/?api_key=YOUR_API_KEY ``` **Response:** ```json theme={"system"} { "error": { "message": "Missing bic", "code": "missing_bic" } } ``` ### Missing API key **Request:** ``` GET https://bankvalidation.cleariflow.com/v1/bic/?bic=DEUTDEFF500 ``` **Response:** ```json theme={"system"} { "error": { "message": "API key is required", "code": "missing_api_key" } } ``` ## BIC Structure The BIC consists of several components: 1. **Bank Code (4 characters)**: Unique identifier for the financial institution 2. **Country Code (2 characters)**: ISO 3166-1 alpha-2 country code 3. **Location Code (2 characters)**: City or region identifier 4. **Branch Code (3 characters)**: Optional branch identifier (XXX for main office) ### Format examples * **8-character BIC**: `DEUTDEFF` (Deutsche Bank, Germany, Frankfurt) * **11-character BIC**: `DEUTDEFF500` (Deutsche Bank, Germany, Frankfurt, Branch 500) ### Common location codes * **FF**: Frankfurt, Germany * **33**: New York, United States * **2L**: London, United Kingdom * **PP**: Paris, France * **MM**: Milan, Italy ## Validation Rules The API performs comprehensive validation including: 1. **Length Validation**: Checks if the BIC is 8 or 11 characters long 2. **Format Validation**: Verifies the BIC follows the ISO 9362 standard 3. **Character Validation**: Ensures only alphanumeric characters are used 4. **Country Code Validation**: Validates the country code format 5. **Bank Code Validation**: Checks the bank identifier format ### BIC format requirements * **Bank Code**: 4 alphanumeric characters * **Country Code**: 2 alphabetic characters (ISO 3166-1) * **Location Code**: 2 alphanumeric characters * **Branch Code**: 3 alphanumeric characters (optional) ## BIC vs SWIFT BIC (Business Identifier Code) and SWIFT are often used interchangeably: * **BIC**: The official ISO 9362 standard name * **SWIFT**: The messaging network that popularized the code * **SWIFT Code**: Alternative name for BIC All BICs can be used for SWIFT messaging, but not all SWIFT codes are valid BICs. ## Supported Countries The API supports BIC validation for 50+ countries including: * **Europe**: Germany, France, Italy, Spain, Netherlands, Belgium, Austria, Switzerland, UK, Poland * **Americas**: United States, Canada, Brazil, Mexico * **Asia**: Japan, Singapore, Hong Kong, Australia * **Africa**: South Africa, Egypt, Nigeria For a complete list of supported countries, see the [Supported Countries](/bank-validation/countries) page. ## Use Cases BIC validation is essential for: 1. **International Wire Transfers**: Ensuring accurate routing information 2. **SEPA Payments**: European payment system requirements 3. **Banking Applications**: Customer account validation 4. **Financial Compliance**: Regulatory reporting requirements 5. **Payment Processing**: E-commerce and fintech applications # Supported countries Source: https://docs.cleariflow.com/bank-validation/countries Comprehensive list of supported countries for IBAN and BIC validation, including country codes, currency information, and specific formatting requirements. ## Getting started The Bank Validation API supports validation for **50+ countries** across Europe, Asia, Americas, and Africa. Each country has specific IBAN and BIC formats, lengths, and validation rules. ## Europe ### Eurozone Countries | Country | Code | IBAN Length | Currency | IBAN Example | BIC Example | | --------------- | ---- | ----------- | -------- | ---------------------------------------- | ------------- | | **Germany** | DE | 22 | EUR | `DE89 3704 0044 0532 0130 00` | `DEUTDEFF500` | | **France** | FR | 27 | EUR | `FR14 2004 1010 0505 0001 3M02 606` | `BNPAFRPP` | | **Italy** | IT | 27 | EUR | `IT60 X054 2811 1010 0000 0123 456` | `UNCRITMM` | | **Spain** | ES | 24 | EUR | `ES91 2100 0418 4502 0005 1332` | `CAIXESBBXXX` | | **Netherlands** | NL | 18 | EUR | `NL91 ABNA 0417 1643 00` | `ABNANL2A` | | **Belgium** | BE | 16 | EUR | `BE68 5390 0754 7034` | `GEBABEBB` | | **Austria** | AT | 20 | EUR | `AT61 1904 3002 3457 3201` | `RZBAATWW` | | **Finland** | FI | 18 | EUR | `FI21 1234 5600 0007 85` | `NDEAFIHH` | | **Portugal** | PT | 25 | EUR | `PT50 0031 0001 0000 0000 0123 4` | `BBVAPTPL` | | **Ireland** | IE | 22 | EUR | `IE64 IRCE 9209 2011 2345 67` | `AIBKIE2D` | | **Luxembourg** | LU | 20 | EUR | `LU28 0019 4006 4475 0000` | `BSUILULL` | | **Slovenia** | SI | 19 | EUR | `SI56 1910 0000 0123 438` | `KREESI2X` | | **Slovakia** | SK | 24 | EUR | `SK31 1200 0000 1987 4263 7541` | `TATRSKBX` | | **Estonia** | EE | 20 | EUR | `EE38 2200 2210 2014 5685` | `EEUHEE2X` | | **Latvia** | LV | 21 | EUR | `LV80 BANK 0000 4351 9500 1` | `RIKOLV2X` | | **Lithuania** | LT | 20 | EUR | `LT12 1000 0111 0100 1000` | `EVIULT2X` | | **Cyprus** | CY | 28 | EUR | `CY17 0020 0128 0000 0012 0052 7600` | `BCYPCY2N` | | **Malta** | MT | 31 | EUR | `MT84 MALT 0110 0001 2345 MTLC AST0 01S` | `VALLMTMT` | ### Non-Eurozone European Countries | Country | Code | IBAN Length | Currency | IBAN Example | BIC Example | | -------------------------- | ---- | ----------- | -------- | ------------------------------------ | ------------- | | **United Kingdom** | GB | 22 | GBP | `GB29 NWBK 6016 1331 9268 19` | `NWBKGB2L` | | **Switzerland** | CH | 21 | CHF | `CH93 0076 2011 6238 5295 7` | `UBSWCHZH80A` | | **Norway** | NO | 15 | NOK | `NO93 8601 1117 947` | `DNBANOKKXXX` | | **Sweden** | SE | 24 | SEK | `SE45 5000 0000 0583 9825 7466` | `NDEASESS` | | **Denmark** | DK | 18 | DKK | `DK50 0040 0440 1162 43` | `DABADKKK` | | **Poland** | PL | 28 | PLN | `PL61 1090 1014 0000 0712 1981 2874` | `BPKOPLPW` | | **Czech Republic** | CZ | 24 | CZK | `CZ65 0800 0000 1920 0014 5399` | `CEKOCZPP` | | **Hungary** | HU | 28 | HUF | `HU42 1177 3016 1111 1018 0000 0000` | `OTPVHUHB` | | **Romania** | RO | 24 | RON | `RO49 AAAA 1B31 0075 9384 0000` | `RZBRROBU` | | **Bulgaria** | BG | 22 | BGN | `BG80 BNBG 9661 1020 3456 78` | `BNBGBGSD` | | **Croatia** | HR | 21 | EUR | `HR12 1001 0051 8630 0016 0` | `ZABAHR2X` | | **Serbia** | RS | 22 | RSD | `RS35 2600 0560 1001 6113 79` | `GIBARS22` | | **Montenegro** | ME | 22 | EUR | `ME25 5050 0001 2345 6789 51` | `CKBAMEME` | | **Albania** | AL | 28 | ALL | `AL47 2121 1009 0000 0002 3569 8741` | `TIRNALT2` | | **Macedonia** | MK | 19 | MKD | `MK07 2501 2000 0058 984` | `STSPMK22` | | **Bosnia and Herzegovina** | BA | 20 | BAM | `BA39 1290 0794 0102 8494` | `UNBABA2S` | ## Asia ### Middle East | Country | Code | IBAN Length | Currency | IBAN Example | BIC Example | | ------------------------ | ---- | ----------- | -------- | --------------------------------------- | ----------- | | **United Arab Emirates** | AE | 23 | AED | `AE07 0331 2345 6789 0123 456` | `SCBLAEAD` | | **Bahrain** | BH | 22 | BHD | `BH67 BMAG 0000 1299 1234 56` | `BMAGBHBM` | | **Kuwait** | KW | 30 | KWD | `KW81 CBKU 0000 0000 0000 1234 5601 01` | `NBOKKWKW` | | **Qatar** | QA | 29 | QAR | `QA58 DOHB 0000 1234 5678 90AB CDEF G` | `QNBAQAQA` | | **Saudi Arabia** | SA | 24 | SAR | `SA03 8000 0000 6080 1016 7519` | `RJSRSAUD` | | **Oman** | OM | 23 | OMR | `OM70 0000 0000 1234 5678 9` | `MUSCOMSM` | | **Jordan** | JO | 30 | JOD | `JO94 CBJO 0010 0000 0000 0131 0003 02` | `CBJOJOAX` | | **Lebanon** | LB | 28 | LBP | `LB62 0999 0000 0001 0019 0122 9114` | `BNLALBBE` | | **Israel** | IL | 23 | ILS | `IL62 0108 0000 0009 9999 999` | `BOFAIL3X` | ### Central Asia | Country | Code | IBAN Length | Currency | IBAN Example | BIC Example | | ---------------- | ---- | ----------- | -------- | ---------------------------- | ----------- | | **Kazakhstan** | KZ | 20 | KZT | `KZ86 125K ZT20 6910 0100` | `KZNBKZKX` | | **Uzbekistan** | UZ | 20 | UZS | `UZ60 0000 0000 0000 0100 1` | `UZSBUZ22` | | **Tajikistan** | TJ | 20 | TJS | `TJ35 0000 0000 0000 0100 1` | `TJSBTJ22` | | **Kyrgyzstan** | KG | 20 | KGS | `KG38 0000 0000 0000 0100 1` | `KGSBKG22` | | **Turkmenistan** | TM | 20 | TMT | `TM36 0000 0000 0000 0100 1` | `TMNBTM22` | ### South Asia | Country | Code | IBAN Length | Currency | IBAN Example | BIC Example | | -------------- | ---- | ----------- | -------- | ------------------------------- | ----------- | | **Pakistan** | PK | 24 | PKR | `PK36 SCBL 0000 0011 2345 6702` | `SCBLPKKX` | | **Bangladesh** | BD | 24 | BDT | `BD18 0000 0000 0000 0000 0000` | `SBLBBBDD` | | **Sri Lanka** | LK | 24 | LKR | `LK20 0000 0000 0000 0000 0000` | `BCEYLKLX` | | **Nepal** | NP | 24 | NPR | `NP20 0000 0000 0000 0000 0000` | `NRBNNPKA` | | **Maldives** | MV | 24 | MVR | `MV20 0000 0000 0000 0000 0000` | `MBNBMVMV` | ### East Asia | Country | Code | IBAN Length | Currency | IBAN Example | BIC Example | | --------------- | ---- | ----------- | -------- | ------------------------------- | ----------- | | **Japan** | JP | 24 | JPY | `JP20 0000 0000 0000 0000 0000` | `BOTKJPJT` | | **South Korea** | KR | 24 | KRW | `KR20 0000 0000 0000 0000 0000` | `KOEXKRSE` | | **China** | CN | 24 | CNY | `CN20 0000 0000 0000 0000 0000` | `BKCHCNBJ` | | **Hong Kong** | HK | 24 | HKD | `HK20 0000 0000 0000 0000 0000` | `HSBCHKHH` | | **Singapore** | SG | 24 | SGD | `SG20 0000 0000 0000 0000 0000` | `DBSBSGSG` | | **Taiwan** | TW | 24 | TWD | `TW20 0000 0000 0000 0000 0000` | `TACBTWTP` | | **Thailand** | TH | 24 | THB | `TH20 0000 0000 0000 0000 0000` | `BKKBTHBK` | | **Malaysia** | MY | 24 | MYR | `MY20 0000 0000 0000 0000 0000` | `MBBEMYKL` | | **Indonesia** | ID | 24 | IDR | `ID20 0000 0000 0000 0000 0000` | `BNIAIDJA` | | **Philippines** | PH | 24 | PHP | `PH20 0000 0000 0000 0000 0000` | `BOPIPHMM` | | **Vietnam** | VN | 24 | VND | `VN20 0000 0000 0000 0000 0000` | `BFTVVNVX` | ## Americas ### North America | Country | Code | IBAN Length | Currency | IBAN Example | BIC Example | | ----------------- | ---- | ----------- | -------- | ------------------------------- | ----------- | | **United States** | US | 22 | USD | `US64 SVBK US6S 3300 9588 79` | `CHASUS33` | | **Canada** | CA | 22 | CAD | `CA21 0000 0000 0000 0000 00` | `BNDCCAMM` | | **Mexico** | MX | 24 | MXN | `MX20 0000 0000 0000 0000 0000` | `BNMXMXMM` | ### Central America | Country | Code | IBAN Length | Currency | IBAN Example | BIC Example | | --------------- | ---- | ----------- | -------- | ------------------------------- | ----------- | | **Costa Rica** | CR | 22 | CRC | `CR05 0000 0000 0000 0000 00` | `BNCRCRSJ` | | **Guatemala** | GT | 24 | GTQ | `GT20 0000 0000 0000 0000 0000` | `BAGTGUGT` | | **Honduras** | HN | 24 | HNL | `HN20 0000 0000 0000 0000 0000` | `BANFOHNX` | | **El Salvador** | SV | 24 | USD | `SV20 0000 0000 0000 0000 0000` | `BANFOSVX` | | **Nicaragua** | NI | 24 | NIO | `NI20 0000 0000 0000 0000 0000` | `BANFONIX` | | **Panama** | PA | 24 | PAB | `PA20 0000 0000 0000 0000 0000` | `BANFOPAX` | | **Belize** | BZ | 24 | BZD | `BZ20 0000 0000 0000 0000 0000` | `BANFOBZX` | ### South America | Country | Code | IBAN Length | Currency | IBAN Example | BIC Example | | ------------- | ---- | ----------- | -------- | -------------------------------------- | ----------- | | **Brazil** | BR | 29 | BRL | `BR97 0036 0305 0000 1000 9795 493P 1` | `BBDEBRSP` | | **Argentina** | AR | 24 | ARS | `AR20 0000 0000 0000 0000 0000` | `BANFARAR` | | **Chile** | CL | 24 | CLP | `CL20 0000 0000 0000 0000 0000` | `BANFOCLX` | | **Colombia** | CO | 24 | COP | `CO20 0000 0000 0000 0000 0000` | `BANFOCOX` | | **Peru** | PE | 24 | PEN | `PE20 0000 0000 0000 0000 0000` | `BANFOPEX` | | **Uruguay** | UY | 24 | UYU | `UY20 0000 0000 0000 0000 0000` | `BANFOUYX` | | **Paraguay** | PY | 24 | PYG | `PY20 0000 0000 0000 0000 0000` | `BANFOPYX` | | **Ecuador** | EC | 24 | USD | `EC20 0000 0000 0000 0000 0000` | `BANFOECX` | | **Venezuela** | VE | 24 | VES | `VE20 0000 0000 0000 0000 0000` | `BANFOVEX` | | **Bolivia** | BO | 24 | BOB | `BO20 0000 0000 0000 0000 0000` | `BANFOBOX` | ### Caribbean | Country | Code | IBAN Length | Currency | IBAN Example | BIC Example | | ----------------------- | ---- | ----------- | -------- | ------------------------------- | ----------- | | **Dominican Republic** | DO | 24 | DOP | `DO20 0000 0000 0000 0000 0000` | `BANFODOX` | | **Jamaica** | JM | 24 | JMD | `JM20 0000 0000 0000 0000 0000` | `BANFOJMX` | | **Trinidad and Tobago** | TT | 24 | TTD | `TT20 0000 0000 0000 0000 0000` | `BANFOTTX` | | **Barbados** | BB | 24 | BBD | `BB20 0000 0000 0000 0000 0000` | `BANFOBBX` | | **Bahamas** | BS | 24 | BSD | `BS20 0000 0000 0000 0000 0000` | `BANFOBSX` | ## Africa ### North Africa | Country | Code | IBAN Length | Currency | IBAN Example | BIC Example | | ----------- | ---- | ----------- | -------- | --------------------------------------- | ----------- | | **Egypt** | EG | 29 | EGP | `EG38 0019 0005 0000 0000 2631 8000 13` | `BNPAEGCX` | | **Morocco** | MA | 24 | MAD | `MA20 0000 0000 0000 0000 0000` | `BANFOMAX` | | **Tunisia** | TN | 24 | TND | `TN59 1000 6035 1835 9847 8831` | `BANFOTNX` | | **Algeria** | DZ | 24 | DZD | `DZ20 0000 0000 0000 0000 0000` | `BANFODZX` | | **Libya** | LY | 25 | LYD | `LY20 0000 0000 0000 0000 0000 0` | `BANFOLYX` | ### West Africa | Country | Code | IBAN Length | Currency | IBAN Example | BIC Example | | ---------------- | ---- | ----------- | -------- | ------------------------------- | ----------- | | **Nigeria** | NG | 24 | NGN | `NG20 0000 0000 0000 0000 0000` | `BANFONGX` | | **Ghana** | GH | 24 | GHS | `GH20 0000 0000 0000 0000 0000` | `BANFOGHX` | | **Senegal** | SN | 24 | XOF | `SN20 0000 0000 0000 0000 0000` | `BANFOSNX` | | **Ivory Coast** | CI | 24 | XOF | `CI20 0000 0000 0000 0000 0000` | `BANFOCIX` | | **Mali** | ML | 24 | XOF | `ML20 0000 0000 0000 0000 0000` | `BANFOMLX` | | **Burkina Faso** | BF | 24 | XOF | `BF20 0000 0000 0000 0000 0000` | `BANFOBFX` | | **Niger** | NE | 24 | XOF | `NE20 0000 0000 0000 0000 0000` | `BANFONEX` | | **Togo** | TG | 24 | XOF | `TG20 0000 0000 0000 0000 0000` | `BANFOTGX` | | **Benin** | BJ | 24 | XOF | `BJ20 0000 0000 0000 0000 0000` | `BANFOBJX` | | **Guinea** | GN | 24 | GNF | `GN20 0000 0000 0000 0000 0000` | `BANFOGNX` | ### Central Africa | Country | Code | IBAN Length | Currency | IBAN Example | BIC Example | | ---------------------------- | ---- | ----------- | -------- | ------------------------------- | ----------- | | **Cameroon** | CM | 24 | XAF | `CM20 0000 0000 0000 0000 0000` | `BANFOCMX` | | **Chad** | TD | 24 | XAF | `TD20 0000 0000 0000 0000 0000` | `BANFOTDX` | | **Central African Republic** | CF | 24 | XAF | `CF20 0000 0000 0000 0000 0000` | `BANFOCFX` | | **Gabon** | GA | 24 | XAF | `GA20 0000 0000 0000 0000 0000` | `BANFOGAX` | | **Congo** | CG | 24 | XAF | `CG20 0000 0000 0000 0000 0000` | `BANFOCGX` | | **Equatorial Guinea** | GQ | 24 | XAF | `GQ20 0000 0000 0000 0000 0000` | `BANFOGQX` | ### East Africa | Country | Code | IBAN Length | Currency | IBAN Example | BIC Example | | --------------- | ---- | ----------- | -------- | ------------------------------- | ----------- | | **Kenya** | KE | 24 | KES | `KE20 0000 0000 0000 0000 0000` | `BANFOKEX` | | **Tanzania** | TZ | 24 | TZS | `TZ20 0000 0000 0000 0000 0000` | `BANFOTZX` | | **Uganda** | UG | 24 | UGX | `UG20 0000 0000 0000 0000 0000` | `BANFOUGX` | | **Ethiopia** | ET | 24 | ETB | `ET20 0000 0000 0000 0000 0000` | `BANFOETX` | | **Somalia** | SO | 24 | SOS | `SO20 0000 0000 0000 0000 0000` | `BANFOSOX` | | **Sudan** | SD | 24 | SDG | `SD20 0000 0000 0000 0000 0000` | `BANFOSDX` | | **South Sudan** | SS | 24 | SSP | `SS20 0000 0000 0000 0000 0000` | `BANFOSSX` | ### Southern Africa | Country | Code | IBAN Length | Currency | IBAN Example | BIC Example | | ---------------- | ---- | ----------- | -------- | ------------------------------- | ----------- | | **South Africa** | ZA | 24 | ZAR | `ZA20 0000 0000 0000 0000 0000` | `SBZAZAJJ` | | **Zimbabwe** | ZW | 24 | ZWL | `ZW20 0000 0000 0000 0000 0000` | `BANFOZWX` | | **Zambia** | ZM | 24 | ZMW | `ZM20 0000 0000 0000 0000 0000` | `BANFOZMX` | | **Malawi** | MW | 24 | MWK | `MW20 0000 0000 0000 0000 0000` | `BANFOMWX` | | **Mozambique** | MZ | 24 | MZN | `MZ20 0000 0000 0000 0000 0000` | `BANFOMZX` | | **Angola** | AO | 24 | AOA | `AO20 0000 0000 0000 0000 0000` | `BANFOAOX` | | **Namibia** | NA | 24 | NAD | `NA20 0000 0000 0000 0000 0000` | `BANFONAX` | | **Botswana** | BW | 24 | BWP | `BW20 0000 0000 0000 0000 0000` | `BANFOBWX` | | **Lesotho** | LS | 24 | LSL | `LS20 0000 0000 0000 0000 0000` | `BANFOLSX` | | **Eswatini** | SZ | 24 | SZL | `SZ20 0000 0000 0000 0000 0000` | `BANFOSZX` | ### Indian Ocean | Country | Code | IBAN Length | Currency | IBAN Example | BIC Example | | -------------- | ---- | ----------- | -------- | --------------------------------------- | ----------- | | **Mauritius** | MU | 30 | MUR | `MU17 BOMM 0101 1010 3030 0200 000M UR` | `BOMMMUMU` | | **Seychelles** | SC | 24 | SCR | `SC20 0000 0000 0000 0000 0000` | `BANFOSCX` | | **Madagascar** | MG | 24 | MGA | `MG20 0000 0000 0000 0000 0000` | `BANFOMGX` | | **Comoros** | KM | 24 | KMF | `KM20 0000 0000 0000 0000 0000` | `BANFOKMX` | ## Oceania | Country | Code | IBAN Length | Currency | IBAN Example | BIC Example | | -------------------- | ---- | ----------- | -------- | ------------------------------- | ----------- | | **Australia** | AU | 24 | AUD | `AU20 0000 0000 0000 0000 0000` | `ANZBAU3M` | | **New Zealand** | NZ | 24 | NZD | `NZ20 0000 0000 0000 0000 0000` | `ANZBNZ22` | | **Fiji** | FJ | 24 | FJD | `FJ20 0000 0000 0000 0000 0000` | `BANFOFJX` | | **Papua New Guinea** | PG | 24 | PGK | `PG20 0000 0000 0000 0000 0000` | `BANFOPGX` | | **Solomon Islands** | SB | 24 | SBD | `SB20 0000 0000 0000 0000 0000` | `BANFOSBX` | | **Vanuatu** | VU | 24 | VUV | `VU20 0000 0000 0000 0000 0000` | `BANFOVUX` | ## IBAN Length by Region ### Shortest IBANs (15-18 characters) * **Norway (NO)**: 15 characters * **Belgium (BE)**: 16 characters * **Netherlands (NL)**: 18 characters ### Medium IBANs (19-24 characters) * **Slovenia (SI)**: 19 characters * **Latvia (LV)**: 21 characters * **Germany (DE)**: 22 characters * **United Kingdom (GB)**: 22 characters * **Spain (ES)**: 24 characters ### Longest IBANs (25-31 characters) * **Portugal (PT)**: 25 characters * **Libya (LY)**: 25 characters * **France (FR)**: 27 characters * **Italy (IT)**: 27 characters * **Malta (MT)**: 31 characters ## Currency Distribution ### Major Currencies * **EUR (Euro)**: 19 countries in Eurozone * **USD (US Dollar)**: United States, Ecuador, El Salvador * **GBP (British Pound)**: United Kingdom * **CHF (Swiss Franc)**: Switzerland, Liechtenstein * **JPY (Japanese Yen)**: Japan ### Regional Currencies * **XOF (West African CFA)**: 8 countries in West Africa * **XAF (Central African CFA)**: 6 countries in Central Africa * **XCD (East Caribbean Dollar)**: Caribbean countries * **SEK (Swedish Krona)**: Sweden * **NOK (Norwegian Krone)**: Norway ## Validation Features by Country ### Advanced Validation Countries with comprehensive validation including: * **Format checking** * **Length validation** * **Checksum verification** * **Country-specific rules** ### Basic Validation Countries with standard validation: * **Format checking** * **Length validation** * **Basic structure verification** ## API Response Examples ### Successful Validation ```json theme={"system"} { "iban": "DE89370400440532013000", "is_valid": true, "country_code": "DE", "country_name": "Germany", "length": 22, "expected_length": 22, "checksum_valid": true, "format_valid": true } ``` ### Failed Validation ```json theme={"system"} { "iban": "", "is_valid": false, "country_code": "", "country_name": "", "length": 0, "expected_length": 0, "checksum_valid": false, "format_valid": false } ``` ## Getting Started To start using the Bank Validation API: 1. **Get your API key** from the Cleariflow dashboard 2. **Choose your endpoint**: `/v1/iban/` or `/v1/bic/` 3. **Make your first request** with a valid IBAN or BIC 4. **Handle responses** according to the validation results For detailed API documentation, see: * [IBAN Validation](/bank-validation/iban) * [BIC Validation](/bank-validation/bic) # IBAN validation Source: https://docs.cleariflow.com/bank-validation/iban GET https://bankvalidation.cleariflow.com/v1/iban/ The `iban` endpoint validates International Bank Account Numbers with comprehensive country-specific validation, format checking, and detailed structural information for financial applications. ## Getting started ### Base URL ``` https://bankvalidation.cleariflow.com/v1/iban/ ``` ### Validation endpoint The `iban` endpoint requires your API key and an IBAN parameter to perform comprehensive validation of International Bank Account Numbers. ``` https://bankvalidation.cleariflow.com/v1/iban/ ? api_key = YOUR_UNIQUE_API_KEY & iban = DE89370400440532013000 ``` This successful request validates a German IBAN and returns detailed information: ```json theme={"system"} { "iban": "DE89370400440532013000", "is_valid": true, "country_code": "DE", "country_name": "Germany", "bank_code": "37040044", "account_number": "0532013000", "length": 22, "expected_length": 22, "checksum_valid": true, "format_valid": true, "details": { "structure": "BBBB BBBB BBBB BBBB BB", "example": "DE89 3704 0044 0532 0130 00", "bank_name": "Bank information not available", "bank_bic": "BIC not available", "account_type": "Bank Account", "currency": "EUR" } } ``` ### Request parameters Your unique API key. Note that each user has unique API keys *for each of Cleariflow APIs*, so your Bank Validation API key will not work for your Exchange Rates API, for example. The International Bank Account Number to validate. Spaces are allowed and will be automatically removed during processing. The IBAN should follow the ISO 13616 standard format. ### Response parameters The API response is returned in a universal and lightweight [JSON format](https://www.json.org/json-en.html). The normalized IBAN without spaces, returned in uppercase format. Overall validation result indicating whether the IBAN is valid according to all validation rules. The two-letter ISO country code (e.g., DE for Germany, FR for France). The full name of the country associated with the IBAN. The bank identifier code extracted from the IBAN according to the country's specific format. The account number portion of the IBAN, excluding country code, checksum, and bank code. The actual length of the provided IBAN. The expected length for IBANs from the specific country according to ISO 13616 standard. Whether the IBAN checksum validation passed using the MOD-97 algorithm. Whether the IBAN format matches the expected structure for the country. Additional detailed information about the IBAN structure and formatting. A visual representation of the IBAN structure using B (Bank), S (Sort), C (Customer), and K (Key) placeholders. A properly formatted example of the IBAN with spaces for readability. The name of the bank (currently shows "Bank information not available"). The BIC code for the bank (currently shows "BIC not available"). The type of account (typically "Bank Account"). The currency code for the country (e.g., EUR for Eurozone countries, GBP for UK). ## Examples ### Valid German IBAN **Request:** ``` GET https://bankvalidation.cleariflow.com/v1/iban/?api_key=YOUR_API_KEY&iban=DE89370400440532013000 ``` **Response:** ```json theme={"system"} { "iban": "DE89370400440532013000", "is_valid": true, "country_code": "DE", "country_name": "Germany", "bank_code": "37040044", "account_number": "0532013000", "length": 22, "expected_length": 22, "checksum_valid": true, "format_valid": true, "details": { "structure": "BBBB BBBB BBBB BBBB BB", "example": "DE89 3704 0044 0532 0130 00", "bank_name": "Bank information not available", "bank_bic": "BIC not available", "account_type": "Bank Account", "currency": "EUR" } } ``` ### Valid French IBAN **Request:** ``` GET https://bankvalidation.cleariflow.com/v1/iban/?api_key=YOUR_API_KEY&iban=FR1420041010050500013M02606 ``` **Response:** ```json theme={"system"} { "iban": "FR1420041010050500013M02606", "is_valid": true, "country_code": "FR", "country_name": "France", "bank_code": "2004101005", "account_number": "0500013M02606", "length": 27, "expected_length": 27, "checksum_valid": true, "format_valid": true, "details": { "structure": "BBBB BSSS SSCC CCCC CCCC CCC KK", "example": "FR14 2004 1010 0505 0001 3M02 606", "bank_name": "Bank information not available", "bank_bic": "BIC not available", "account_type": "Bank Account", "currency": "EUR" } } ``` ### Invalid IBAN **Request:** ``` GET https://bankvalidation.cleariflow.com/v1/iban/?api_key=YOUR_API_KEY&iban=INVALID ``` **Response:** ```json theme={"system"} { "iban": "", "is_valid": false, "country_code": "", "country_name": "", "bank_code": "", "account_number": "", "length": 7, "expected_length": 0, "checksum_valid": false, "format_valid": false, "details": { "structure": "", "example": "" } } ``` ## Error handling ### Missing IBAN parameter **Request:** ``` GET https://bankvalidation.cleariflow.com/v1/iban/?api_key=YOUR_API_KEY ``` **Response:** ```json theme={"system"} { "error": { "message": "Missing iban", "code": "missing_iban" } } ``` ### Missing API key **Request:** ``` GET https://bankvalidation.cleariflow.com/v1/iban/?iban=DE89370400440532013000 ``` **Response:** ```json theme={"system"} { "error": { "message": "API key is required", "code": "missing_api_key" } } ``` ## IBAN Structure The IBAN consists of several components: 1. **Country Code (2 characters)**: ISO 3166-1 alpha-2 country code 2. **Check Digits (2 characters)**: MOD-97 algorithm validation 3. **Bank Identifier**: Country-specific bank code 4. **Account Number**: Customer account identifier ### Country-specific formats Different countries have varying IBAN structures: * **Germany (DE)**: 22 characters - `BBBB BBBB BBBB BBBB BB` * **France (FR)**: 27 characters - `BBBB BSSS SSCC CCCC CCCC CCC KK` * **Italy (IT)**: 27 characters - `CAAA AABB BBSS CCCC CCCC CCX` * **United Kingdom (GB)**: 22 characters - `BBBB SSSS SSCC CCCC CC` * **Spain (ES)**: 24 characters - `BBBB SSSS DDCC CCCC CCCC CC` Where: * **B** = Bank code * **S** = Sort code * **C** = Customer account number * **K** = Key/Check digit * **A** = Account type * **D** = Control digit ## Validation Rules The API performs comprehensive validation including: 1. **Format Validation**: Checks if the IBAN follows the expected structure for the country 2. **Length Validation**: Verifies the IBAN length matches the country standard 3. **Checksum Validation**: Performs MOD-97 algorithm validation 4. **Country Code Validation**: Ensures the country code is supported 5. **Character Validation**: Checks for valid alphanumeric characters ## Supported Countries The API supports IBAN validation for 50+ countries including: * **Europe**: Germany, France, Italy, Spain, Netherlands, Belgium, Austria, Switzerland, UK, Poland * **Asia**: UAE, Bahrain, Israel, Jordan, Kazakhstan, Kuwait * **Americas**: Brazil, Costa Rica, Dominican Republic, Guatemala * **Africa**: Mauritania, Mauritius, Tunisia For a complete list of supported countries, see the [Supported Countries](/bank-validation/countries) page. # Email Validation API Source: https://docs.cleariflow.com/email-validation GET https://emailvalidation.cleariflow.com/v1 Enhance inbox placement and keep your mailing lists healthy with Cleariflow’s best‑in‑class Email Validation API. ## Quick Start To make a request, provide your unique `api_key` and the `email` you want to check—nothing else is required: ```bash theme={"system"} https://emailvalidation.cleariflow.com/v1/ ? api_key = YOUR_UNIQUE_API_KEY & email = jane.doe@acme-corp.com ``` The request succeeds and returns all available insights for the address: ```json theme={"system"} { "email": "jane.doe@acme-corp.com", "autocorrect": "", "deliverability": "DELIVERABLE", "quality_score": 0.85, "is_valid_format": { "value": true, "text": "TRUE" }, "is_free_email": { "value": false, "text": "FALSE" }, "is_disposable_email": { "value": false, "text": "FALSE" }, "is_role_email": { "value": false, "text": "FALSE" }, "is_catchall_email": { "value": false, "text": "FALSE" }, "is_mx_found": { "value": true, "text": "TRUE" }, "is_smtp_valid": { "value": true, "text": "TRUE" } } ``` ### Request parameters Your personal API credential. Keys are scoped per Cleariflow product, so an Email Validation key will not authorize requests to, for example, the IP Geolocation API. The email address you want to verify. Optional flag to disable autocorrection. Set `auto_correct=false` to turn it off. It is enabled by default. ### Response parameters Responses are returned as compact, standardized [JSON](https://www.json.org/json-en.html). Echoes the `email` submitted in the request. Suggested correction when a likely typo is detected (e.g., [johnsmith@gmial.com](mailto:johnsmith@gmial.com) => [johnsmith@gmail.com](mailto:johnsmith@gmail.com)). Empty if no suggestion. Cleariflow’s assessment of whether the address can receive mail. Possible values: `DELIVERABLE`, `UNDELIVERABLE`, `UNKNOWN`. `DELIVERABLE` requires a successful SMTP check; if MX records exist but SMTP cannot confirm the mailbox (common with large providers), the result is `UNKNOWN`. All plans run the same checks; free plans differ only in monthly quota and rate limits (see error codes 422 and 429). A decimal score from `0` to `0.99` reflecting address quality. Disposable addresses are capped near `0.05`; unverified SMTP results are capped at `0.55`. True when the address matches the standard pattern `local@domain.tld`. Missing elements or invalid characters yield `false`. True if the domain belongs to a free email provider (e.g., Gmail, Yahoo). True if the domain is on our list of disposable/temporary inbox providers (e.g., Mailinator, Yopmail). True if the local part appears to be a role account rather than an individual, e.g., `team@`, `sales@`, `info@`. True if the domain is configured as a [catch‑all](https://www.corporatecomm.com/faqs/other-questions/what-is-a-catch-all-account). True when [MX records](https://en.wikipedia.org/wiki/MX_record) exist for the domain. True if the [SMTP](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol) verification succeeds. If SMTP fails but other checks pass, the result may be `UNKNOWN`. We advise against blocking signups or form submissions solely on SMTP failures. ## Request examples ### Example: likely misspelling This example shows a request where a probable typo is detected in the submitted address. Even when a likely misspelling is found, all other checks (e.g., free email, disposable domain) are performed against the originally submitted address—not the suggested correction. ```bash theme={"system"} https://emailvalidation.cleariflow.com/v1/ ? api_key = YOUR_UNIQUE_API_KEY & email = johnsmith@gmial.con ``` A successful response looks like: ```json theme={"system"} { "email": "johnsmith@gmial.con", "autocorrect": "johnsmith@gmail.com", "deliverability": "UNKNOWN", "quality_score": 0.4, "is_valid_format": { "value": true, "text": "TRUE" }, "is_free_email": { "value": false, "text": "FALSE" }, "is_disposable_email": { "value": false, "text": "FALSE" }, "is_role_email": { "value": false, "text": "FALSE" }, "is_catchall_email": { "value": false, "text": "FALSE" }, "is_mx_found": { "value": false, "text": "FALSE" }, "is_smtp_valid": { "value": false, "text": "FALSE" } } ``` ### Example: invalid format This example demonstrates an address that fails basic formatting. When `is_valid_format` is `false`, subsequent checks (e.g., `is_free_email`, `is_role_email`) are skipped and reported as `false`. ```bash theme={"system"} https://emailvalidation.cleariflow.com/v1/ ? api_key = YOUR_UNIQUE_API_KEY & email = johnsmith ``` A successful response looks like: ```json theme={"system"} { "email": "johnsmith", "autocorrect": "", "deliverability": "UNDELIVERABLE", "quality_score": 0.0, "is_valid_format": { "value": false, "text": "FALSE" }, "is_free_email": { "value": false, "text": "FALSE" }, "is_disposable_email": { "value": false, "text": "FALSE" }, "is_role_email": { "value": false, "text": "FALSE" }, "is_catchall_email": { "value": false, "text": "FALSE" }, "is_mx_found": { "value": false, "text": "FALSE" }, "is_smtp_valid": { "value": false, "text": "FALSE" } } ``` ## Bulk upload (CSV) Prefer not to call the API directly? Use the CSV bulk uploader—the results will be emailed to you once processing finishes. When uploading a CSV, follow these guidelines: * Place the email addresses in the first column. * Delete any blank rows. * Use one address per row. * Limit files to a maximum of 50,000 rows. ## Response and error codes Errors are returned in JSON with a code and human‑readable description. Common codes are listed below. | Code | Type | Details | | ---- | --------------------- | -------------------------------------------------------------- | | 200 | OK | Request completed successfully. | | 400 | Bad request | Malformed or invalid request. | | 401 | Unauthorized | Authentication failed—usually a missing or invalid API key. | | 422 | Quota reached | Quota exhausted (e.g., insufficient credits on free plans). | | 429 | Too many requests | Rate limit exceeded (free plans allow up to 1 request/second). | | 500 | Internal server error | Unexpected error on our side. | | 503 | Service unavailable | Service temporarily unavailable. | ## Other notes Plan note: All plans (free and paid) run the same validation checks, including MX lookup, SMTP verification, and catch-all detection. Billing note: Each email evaluated consumes one credit per request—regardless of outcome. Submitting an invalid address (e.g., "fda3346ds") still counts as one credit. # Introduction Source: https://docs.cleariflow.com/exchange-rates Cleariflow Exchange Rates API delivers real-time currency conversion capabilities through a streamlined, contemporary RESTful JSON interface, supporting 80+ global currencies with live rates, historical data, and instant conversion tools. ## Getting started The `live` endpoint provides instant access to current exchange rates across multiple currencies, enabling real-time financial calculations and market monitoring. The `convert` endpoint transforms specific amounts between currencies using the most up-to-date exchange rates, perfect for financial applications and e-commerce platforms. The `symbols` endpoint delivers a comprehensive catalog of supported currencies with detailed descriptions, facilitating dynamic currency selection and validation in applications. ### REST Architecture The Exchange Rates API follows REST principles, utilizing predictable resource-oriented URLs and standard HTTP status codes for seamless integration and error handling. ### HTTPS Security All API communications are secured using TLS 1.2 or higher encryption protocols to ensure data integrity and privacy. ### API Versioning The Exchange Rates API maintains backward compatibility through versioning, currently operating on Version 1 with planned future enhancements. ### Authentication Your API key serves as the exclusive credential for accessing the Exchange Rates API. Each Cleariflow service requires a unique key, ensuring secure and isolated access across different APIs. ## Response and error codes When requests fail, the API returns structured JSON error responses with specific codes and descriptions for effective troubleshooting. | Code | Type | Details | | ---- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | OK | Everything worked as expected. | | 204 | OK | Their is no location data for the submitted IP. | | 400 | Bad request | Bad request. | | 401 | Unauthorized | The request was unacceptable. Typically due to the API key missing or incorrect. | | 422 | Quota reached | The request was aborted due to insufficient API credits. (Free plans) | | 429 | Too many requests | The request was aborted due to the number of allowed requests per second being reached. This happens on free plans as requests are limited to 1 per second. | | 500 | Internal server error | The request could not be completed due to an error on the server side. | | 503 | Service unavailable | The server was unavailable. | # Convert exchange rates Source: https://docs.cleariflow.com/exchange-rates/convert GET https://exchange-rates.cleariflow.com/v1/convert The `convert` endpoint enables precise currency conversion by transforming specific amounts between currencies using real-time exchange rates, ideal for financial calculations and payment processing. ## Getting started ### Base URL ``` https://exchange-rates.cleariflow.com/v1/convert ``` ### Validation endpoint The `convert` endpoint requires your API key, a base currency, and a target parameter to perform currency conversions. ``` https://exchange-rates.cleariflow.com/v1/convert ? api_key = YOUR_UNIQUE_API_KEY & base = EUR & target = USD ``` This successful request converts 1 EUR to USD using the most current exchange rate: ```json theme={"system"} { "base": "EUR", "target": "USD", "base_amount": 1, "converted_amount": 1.160968, "exchange_rate": 1.160968, "last_updated": 1755806612 } ``` ### Request parameters Your unique API key. Note that each user has unique API keys *for each of Cleariflow APIs*, so your Exchange Rates API key will not work for your IP Geolocation API, for example. The base currency used to get the latest exchange rate(s) for. Uses the ISO 4217 currency standard (e.g., USD for United States Dollars), like all currency parameters in this API. The target currency or currencies to get the exchange rate of versus the base currency. Like the base parameters, any currency passed here follows the ISO 4217 standard. Note that unlinke the other endpoints, `convert` only accepts one target currency at a time. The historical date you'd like to get rates from, in the format of YYYY-MM-DD. If you leave this blank, it will use the latest available rate(s). The amount of the base currency you would like to convert to the target currency. ### Response parameters The API response is returned in a universal and lightweight [JSON format](https://www.json.org/json-en.html). The base currency used to get the exchange rates. The target currency that the base\_amount was converted into. The date the currencies were pulled from, per the successful request. The amount of the base currency from the request. The amount of the target currency that the base\_amount has been converted into. The exchange rate used to convert the base\_amount from the base currency to the target currency. # Live exchange rates Source: https://docs.cleariflow.com/exchange-rates/live GET https://exchange-rates.cleariflow.com/v1/live The `live` endpoint delivers real-time currency exchange data, providing instant access to current market rates for seamless financial operations and dynamic currency monitoring. ## Getting started ### Base URL ``` https://exchange-rates.cleariflow.com/v1/live ``` ### Validation endpoint When no target currencies are specified, the endpoint returns rates for all available currencies. Explore the complete list of supported currencies [here](getting-started). ``` https://exchange-rates.cleariflow.com/v1/live ? api_key = YOUR_UNIQUE_API_KEY & base = USD ``` This successful request returns exchange rates for all available currencies relative to the base currency: ```json theme={"system"} { "base": "EUR", "last_updated": 1755806612, "exchange_rates": { "AED": 4.26365, "AFN": 79.371761, "ALL": 96.766559, "AMD": 444.303396, "ANG": 2.07788, "AOA": 1064.607378, "ARS": 1526.092012, "AUD": 1.806504, "AWG": 2.091193, "AZN": 1.972485, "BAM": 1.94832, "BBD": 2.337356, "BDT": 141.197895, "BGN": 1.955876, "BHD": 0.437742, "BIF": 3441.108157, "BMD": 1.160968, "BND": 1.493687, "BOB": 8.019865, "BRL": 6.358386, "BSD": 1.160489, "BTC": 0.000010310136, "BTN": 101.21369, "BWP": 15.615325, "BYN": 3.908315, "BYR": 22754.966223, "BZD": 2.328351, "CAD": 1.613524, "CDF": 3326.172282, "CHF": 0.939106, "CLF": 0.028737, "CLP": 1127.358136, "CNH": 8.340287, "CNY": 8.336214, "COP": 4685.375252, "CRC": 585.59961, "CUC": 1.160968, "CUP": 30.765643, "CVE": 110.675173, "CZK": 24.576564, "DJF": 206.327505, "DKK": 7.464964, "DOP": 72.415347, "DZD": 150.838676, "EGP": 56.298231, "ERN": 17.414515, "ETB": 164.622148, "FJD": 2.639866, "FKP": 0.863167, "GBP": 0.865164, "GEL": 3.128807, "GGP": 0.863167, "GHS": 12.776446, "GIP": 0.863167, "GMD": 83.589605, "GNF": 10075.458774, "GTQ": 8.898796, "GYD": 242.80765, "HKD": 9.071975, "HNL": 30.525752, "HRK": 7.533057, "HTG": 151.846358, "HUF": 396.377133, "IDR": 18982.924233, "ILS": 3.959365, "IMP": 0.863167, "INR": 101.308333, "IQD": 1520.86764, "IRR": 48818.690683, "ISK": 143.390958, "JEP": 0.863167, "JMD": 186.50395, "JOD": 0.823108, "JPY": 172.202267, "KES": 150.348297, "KGS": 101.524282, "KHR": 4649.676029, "KMF": 490.514729, "KPW": 1044.880197, "KRW": 1626.556298, "KWD": 0.355128, "KYD": 0.967166, "KZT": 623.825974, "LAK": 25076.901249, "LBP": 103970.458898, "LKR": 350.343584, "LRD": 234.370341, "LSL": 20.51426, "LTL": 3.428035, "LVL": 0.702258, "LYD": 6.298234, "MAD": 10.472154, "MDL": 19.538584, "MGA": 5148.891487, "MKD": 61.564837, "MMK": 2436.793158, "MNT": 4174.925262, "MOP": 9.340105, "MRU": 46.403613, "MUR": 53.102389, "MVR": 17.890252, "MWK": 2016.019751, "MXN": 21.783335, "MYR": 4.904511, "MZN": 74.189833, "NAD": 20.51403, "NGN": 1784.279885, "NIO": 42.724297, "NOK": 11.816444, "NPR": 161.941505, "NZD": 1.994252, "OMR": 0.446385, "PAB": 1.160539, "PEN": 4.074746, "PGK": 4.810464, "PHP": 66.382391, "PKR": 327.334442, "PLN": 4.256788, "PYG": 8385.912082, "QAR": 4.226793, "RON": 5.053583, "RSD": 117.178773, "RUB": 93.545406, "RWF": 1677.598275, "SAR": 4.356784, "SBD": 9.543586, "SCR": 17.083033, "SDG": 697.172079, "SEK": 11.169246, "SGD": 1.496253, "SHP": 0.912338, "SLE": 27.052052, "SLL": 24344.909083, "SOS": 663.494948, "SRD": 44.093416, "STD": 24029.68667, "STN": 24.78666, "SVC": 10.15419, "SYP": 15094.850487, "SZL": 20.51423, "THB": 37.921835, "TJS": 10.909308, "TMT": 4.063387, "TND": 3.356326, "TOP": 2.719101, "TRY": 47.525837, "TTD": 7.864449, "TWD": 35.421552, "TZS": 2891.836946, "UAH": 47.809567, "UGX": 4137.187253, "USD": 1.160968, "UYU": 46.661654, "UZS": 14512.095553, "VES": 160.163499, "VND": 30687.277791, "VUV": 139.211829, "WST": 3.1432, "XAF": 653.501468, "XAG": 0.030479, "XAU": 0.000348, "XCD": 3.137573, "XCG": 2.091641, "XDR": 0.812147, "XOF": 652.464211, "XPF": 119.331742, "YER": 278.86379, "ZAR": 20.58816, "ZMK": 10450.103649, "ZMW": 26.838156, "ZWL": 373.831114 } } ``` ### Request parameters Your unique API key. Note that each user has unique API keys *for each of Cleariflow APIs*, so your Exchange Rates API key will not work for your IP Geolocation API, for example. The base currency used to get the latest exchange rate(s) for. Uses the ISO 4217 currency standard (e.g., USD for United States Dollars), like all currency parameters in this API. The target currency or currencies to get the exchange rate of versus the base currency. Like the base parameters, any currency passed here follows the ISO 4217 standard. If multiple currencies are passed in the target, they should be separated by commas (e.g., \&target=EUR,CAD,AUD). ### Response parameters The API response is returned in a universal and lightweight [JSON format](https://www.json.org/json-en.html). The base currency used to get the exchange rates. The Unix timestamp of when the returned data was last updated. A JSON Object containing each of the target currency as the key and its exchange rate versus the base currency as that key's value. # Currency symbols Source: https://docs.cleariflow.com/exchange-rates/symbols GET https://exchange-rates.cleariflow.com/v1/symbols The `symbols` endpoint provides comprehensive currency information by delivering an extensive catalog of supported currencies with detailed descriptions, enabling dynamic currency selection and validation in applications. ## Getting started ### Base URL ``` https://exchange-rates.cleariflow.com/v1/symbols ``` ### Validation endpoint The `symbols` endpoint represents the most straightforward API call in the Exchange Rates service, requiring only your API key to retrieve the complete list of available currency symbols. ``` https://exchange-rates.cleariflow.com/v1/symbols ? api_key = YOUR_UNIQUE_API_KEY ``` This successful request returns all available currency symbols with their corresponding descriptions: ```json theme={"system"} { "currencies": { "AED": "United Arab Emirates Dirham", "AFN": "Afghan Afghani", "ALL": "Albanian Lek", "AMD": "Armenian Dram", "ANG": "Netherlands Antillean Guilder", "AOA": "Angolan Kwanza", "ARS": "Argentine Peso", "AUD": "Australian Dollar", "AWG": "Aruban Florin", "AZN": "Azerbaijani Manat", "BAM": "Bosnia-Herzegovina Convertible Mark", "BBD": "Barbadian Dollar", "BDT": "Bangladeshi Taka", "BGN": "Bulgarian Lev", "BHD": "Bahraini Dinar", "BIF": "Burundian Franc", "BMD": "Bermudan Dollar", "BND": "Brunei Dollar", "BOB": "Bolivian Boliviano", "BRL": "Brazilian Real", "BSD": "Bahamian Dollar", "BTC": "Bitcoin", "BTN": "Bhutanese Ngultrum", "BWP": "Botswanan Pula", "BYN": "New Belarusian Ruble", "BYR": "Belarusian Ruble", "BZD": "Belize Dollar", "CAD": "Canadian Dollar", "CDF": "Congolese Franc", "CHF": "Swiss Franc", "CLF": "Chilean Unit of Account (UF)", "CLP": "Chilean Peso", "CNH": "Chinese Yuan Offshore", "CNY": "Chinese Yuan", "COP": "Colombian Peso", "CRC": "Costa Rican Colón", "CUC": "Cuban Convertible Peso", "CUP": "Cuban Peso", "CVE": "Cape Verdean Escudo", "CZK": "Czech Republic Koruna", "DJF": "Djiboutian Franc", "DKK": "Danish Krone", "DOP": "Dominican Peso", "DZD": "Algerian Dinar", "EGP": "Egyptian Pound", "ERN": "Eritrean Nakfa", "ETB": "Ethiopian Birr", "EUR": "Euro", "FJD": "Fijian Dollar", "FKP": "Falkland Islands Pound", "GBP": "British Pound Sterling", "GEL": "Georgian Lari", "GGP": "Guernsey Pound", "GHS": "Ghanaian Cedi", "GIP": "Gibraltar Pound", "GMD": "Gambian Dalasi", "GNF": "Guinean Franc", "GTQ": "Guatemalan Quetzal", "GYD": "Guyanaese Dollar", "HKD": "Hong Kong Dollar", "HNL": "Honduran Lempira", "HRK": "Croatian Kuna", "HTG": "Haitian Gourde", "HUF": "Hungarian Forint", "IDR": "Indonesian Rupiah", "ILS": "Israeli New Sheqel", "IMP": "Manx pound", "INR": "Indian Rupee", "IQD": "Iraqi Dinar", "IRR": "Iranian Rial", "ISK": "Icelandic Króna", "JEP": "Jersey Pound", "JMD": "Jamaican Dollar", "JOD": "Jordanian Dinar", "JPY": "Japanese Yen", "KES": "Kenyan Shilling", "KGS": "Kyrgystani Som", "KHR": "Cambodian Riel", "KMF": "Comorian Franc", "KPW": "North Korean Won", "KRW": "South Korean Won", "KWD": "Kuwaiti Dinar", "KYD": "Cayman Islands Dollar", "KZT": "Kazakhstani Tenge", "LAK": "Laotian Kip", "LBP": "Lebanese Pound", "LKR": "Sri Lankan Rupee", "LRD": "Liberian Dollar", "LSL": "Lesotho Loti", "LTL": "Lithuanian Litas", "LVL": "Latvian Lats", "LYD": "Libyan Dinar", "MAD": "Moroccan Dirham", "MDL": "Moldovan Leu", "MGA": "Malagasy Ariary", "MKD": "Macedonian Denar", "MMK": "Myanma Kyat", "MNT": "Mongolian Tugrik", "MOP": "Macanese Pataca", "MRU": "Mauritanian Ouguiya", "MUR": "Mauritian Rupee", "MVR": "Maldivian Rufiyaa", "MWK": "Malawian Kwacha", "MXN": "Mexican Peso", "MYR": "Malaysian Ringgit", "MZN": "Mozambican Metical", "NAD": "Namibian Dollar", "NGN": "Nigerian Naira", "NIO": "Nicaraguan Córdoba", "NOK": "Norwegian Krone", "NPR": "Nepalese Rupee", "NZD": "New Zealand Dollar", "OMR": "Omani Rial", "PAB": "Panamanian Balboa", "PEN": "Peruvian Nuevo Sol", "PGK": "Papua New Guinean Kina", "PHP": "Philippine Peso", "PKR": "Pakistani Rupee", "PLN": "Polish Zloty", "PYG": "Paraguayan Guarani", "QAR": "Qatari Rial", "RON": "Romanian Leu", "RSD": "Serbian Dinar", "RUB": "Russian Ruble", "RWF": "Rwandan Franc", "SAR": "Saudi Riyal", "SBD": "Solomon Islands Dollar", "SCR": "Seychellois Rupee", "SDG": "South Sudanese Pound", "SEK": "Swedish Krona", "SGD": "Singapore Dollar", "SHP": "Saint Helena Pound", "SLE": "Sierra Leonean Leone", "SLL": "Sierra Leonean Leone", "SOS": "Somali Shilling", "SRD": "Surinamese Dollar", "STD": "São Tomé and Príncipe Dobra", "STN": "São Tomé and Príncipe Dobra", "SVC": "Salvadoran Colón", "SYP": "Syrian Pound", "SZL": "Swazi Lilangeni", "THB": "Thai Baht", "TJS": "Tajikistani Somoni", "TMT": "Turkmenistani Manat", "TND": "Tunisian Dinar", "TOP": "Tongan Paʻanga", "TRY": "Turkish Lira", "TTD": "Trinidad and Tobago Dollar", "TWD": "New Taiwan Dollar", "TZS": "Tanzanian Shilling", "UAH": "Ukrainian Hryvnia", "UGX": "Ugandan Shilling", "USD": "United States Dollar", "UYU": "Uruguayan Peso", "UZS": "Uzbekistan Som", "VES": "Sovereign Bolivar", "VND": "Vietnamese Dong", "VUV": "Vanuatu Vatu", "WST": "Samoan Tala", "XAF": "CFA Franc BEAC", "XAG": "Silver (troy ounce)", "XAU": "Gold (troy ounce)", "XCD": "East Caribbean Dollar", "XCG": "Caribbean Guilder", "XDR": "Special Drawing Rights", "XOF": "CFA Franc BCEAO", "XPF": "CFP Franc", "YER": "Yemeni Rial", "ZAR": "South African Rand", "ZMK": "Zambian Kwacha (pre-2013)", "ZMW": "Zambian Kwacha", "ZWL": "Zimbabwean Dollar" }, "last_updated": 1755806612 } ``` ### Request parameters Your unique API key. Note that each user has unique API keys *for each of Cleariflow APIs*, so your Exchange Rates API key will not work for your IP Geolocation API, for example. ### Response parameters The API response is returned in a universal and lightweight [JSON format](https://www.json.org/json-en.html). A JSON Object containing all available currency symbols as keys with their full descriptions as values. This includes traditional fiat currencies (USD, EUR, GBP, etc.) and popular cryptocurrencies (BTC, ETH, etc.). The Unix timestamp of when the currency symbols were last updated from the data source. ## Use cases ### Getting all available currencies The `symbols` endpoint is perfect for: * **Dynamic UI generation**: Populate dropdown menus or currency selectors in your application * **Currency validation**: Check if a currency code is supported before making exchange rate requests * **Currency discovery**: Explore all available currencies in the Exchange Rates API * **Application setup**: Initialize your application with the complete list of supported currencies ### Example use case: Currency selector ```javascript theme={"system"} // Fetch all available currencies const response = await fetch('https://exchange-rates.cleariflow.com/v1/symbols?api_key=YOUR_API_KEY'); const data = await response.json(); // Populate a currency dropdown const select = document.getElementById('currency-select'); Object.entries(data.currencies).forEach(([code, name]) => { const option = document.createElement('option'); option.value = code; option.textContent = `${code} - ${name}`; select.appendChild(option); }); ``` ## Supported currencies The Exchange Rates API supports **80+ currencies**, including: * **Major fiat currencies**: USD, EUR, GBP, JPY, AUD, CAD, CHF, CNY * **European currencies**: SEK, NOK, DKK, PLN, CZK, HUF, RON, BGN, HRK, ISK * **Asian currencies**: KRW, SGD, HKD, TWD, MYR, PHP, THB, IDR, INR, ILS * **Americas currencies**: BRL, MXN, ARS * **African currencies**: ZAR, MAD, DZD * **Cryptocurrencies**: BTC, ETH, BNB, DOGE, XRP, BCH, LTC All currency codes follow the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) standard for international compatibility. # IP Geolocation API Source: https://docs.cleariflow.com/ip-geolocation GET https://ipgeolocation.cleariflow.com/v1 Cleariflow IP Geolocation API is a swift, efficient, contemporary, and RESTful JSON API that identifies the location and additional details of IP addresses across more than 190 countries. The API operates with remarkable simplicity: just provide your API key along with an IP address, and you'll receive comprehensive location data including postal codes, city names, regional information, country details, and precise latitude/longitude coordinates. ## Getting started ### REST Architecture Similar to all Cleariflow APIs, the IP Geolocation API follows REST principles. It employs predictable, resource-oriented URLs and utilizes HTTP status codes for error indication. ### HTTPS Security All communications with the IP Geolocation API must be secured using TLS 1.2 or higher protocols. ### API Versioning All Cleariflow APIs incorporate versioning. The IP Geolocation API currently operates on Version 1. ### Authentication with API Key Your API key serves as the unique authentication credential for accessing the Cleariflow IP Geolocation API. It's important to note that each Cleariflow API requires a distinct API key, meaning you'll need separate keys for different services like IP Geolocation and Email Validation APIs. To authenticate your requests, append your API key to the base URL. ### Base URL ``` https://ipgeolocation.cleariflow.com/v1/ ``` ### Geolocation endpoint The Cleariflow IP Geolocation API requires only your unique API key and automatically detects the IP address from the requesting client. Alternatively, you can include the "ip\_address" parameter to specify a particular IP for analysis: ``` https://ipgeolocation.cleariflow.com/v1/ ? api_key = YOUR_UNIQUE_API_KEY & ip_address = 94.198.41.118 (optional) ``` This represents a successful request, returning the IP address and associated details below: ```json theme={"system"} { "ip_address": "80.255.13.30", "city": null, "city_geoname_id": null, "region": null, "region_iso_code": null, "region_geoname_id": null, "postal_code": null, "country": "Germany", "country_code": "DE", "country_geoname_id": 2921044, "country_is_eu": true, "continent": "Europe", "continent_code": "EU", "continent_geoname_id": 6255148, "longitude": 9.491, "latitude": 51.2993, "security": { "is_vpn": true, "is_proxy": false, "vpn_provider": "NordVPN" }, "timezone": { "name": "Europe/Berlin", "abbreviation": "CEST", "gmt_offset": 2, "current_time": "21:21:22", "is_dst": true }, "flag": { "emoji": "🇩🇪", "unicode": "U+1F1E9 U+1F1EA", "png": "https://static.cleariflow.com/country-flags/DE_flag.png", "svg": "https://static.cleariflow.com/country-flags/DE_flag.svg" }, "currency": { "currency_name": "Euros", "currency_code": "EUR" }, "connection": { "autonomous_system_number": 201011, "autonomous_system_organization": "Core-Backbone GmbH", "connection_type": null, "isp_name": null, "organization_name": null } } ``` ### Request parameters Your unique API key. Note that each user has unique API keys for each of Cleariflow APIs, so your IP Geolocation API key will not work for your Email Validation API, for example. The IP address to geolocate. Both IPv4 and IPv6 addresses are supported. Note that if you leave this parameter blank, the service will geolocate the IP address from which the request was made. Comma-separated list of **top-level** keys to return (for example, `?fields=country,security`). To include VPN/proxy flags, use `security` — the whole object is returned (`is_vpn`, `is_proxy`, and `vpn_provider` when present). Nested keys such as `is_vpn` alone are not supported. ### Response parameters The API response is returned in a universal and lightweight [JSON format](https://www.json.org/json-en.html). The IP address submitted for geolocation. City's name. City's geoname ID. State or province in which the city is located. State or province's ISO 3166-2 code. State or province's geoname ID. ZIP or postal code. Country's name. Country's ISO 3166-1 alpha-2 code. Country's geoname ID. True if the country is in the EU, false if it is not. Continent's name. 2 letter continent code: AF, AS, EU, NA, OC, SA, AN. Continent's geoname ID. Decimal of the longitude. Decimal of the latitude. `true` when the IP matches the enumerated VPN exit-node database (IP-to-VPN MMDB). `true` when the IP matches the proxy database (IP-to-VPN MMDB). VPN service name from the MMDB (for example, `NordVPN`). Omitted when `is_vpn` is `false`. Timezone's name from the IANA Time Zone Database. Timezone's abbreviation, also from the IANA Time Zone Database. Timezone's offset from Greenwich Mean Time (GMT). Current time in the local time zone. True if the location is currently in Daylight Savings Time (DST). Link to a hosted version of the country's flag in SVG format. Link to a hosted version of the country's flag in PNG format. Country's flag as an emoji. Country's flag in unicode. The currency's name. The currency's code in ISO 4217 format. Inferred from the ASN organization name (for example, Cellular, Cable/DSL, Corporate, Cloud, Hosting). VPN and proxy are reported in `security`, not here. Autonomous System number. Autonomous System Organization name. Internet Service Provider (ISP) name. Organization name. ### Limiting response fields You can choose to only receive a few fields from the JSON response. To do so, you can include a fields value in the query parameters with a comma-separated list of the top-level keys you want to be returned. For example, a request to only get the country and city of an IP will look like this: ``` https://ipgeolocation.cleariflow.com/v1/ ? api_key = YOUR_API_KEY & ip_address = 94.198.41.122 & fields = country,city ``` The response would look like this: ```json theme={"system"} { "city": "Vienna", "country": "Austria" } ``` ## Use cases ### Geolocating a website visitor To request the geolocation from an IP address, simply include your unique API key in the template below. Note that you don't need to know the IP of the visitor to make the request. ```javascript theme={"system"} $.getJSON("https://ipgeolocation.cleariflow.com/v1/?api_key=YOUR_UNIQUE_API_KEY", function(data) { console.log(data.ip_address); console.log(data.country); }) ``` That's all you need to get the geolocation and other data from a visitor! There is only one required parameter: your unique API key. ## Response and error codes Whenever you make a request that fails for some reason, an error is returned also in the JSON format. The errors include an error code and description, which you can find in detail below. | Code | Type | Details | | ---- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | OK | Everything worked as expected. | | 204 | OK | There is no location data for the submitted IP. | | 400 | Bad request | Bad request. | | 401 | Unauthorized | The request was unacceptable. Typically due to the API key missing or incorrect. | | 422 | Quota reached | The request was aborted due to insufficient API credits. (Free plans) | | 429 | Too many requests | The request was aborted due to the number of allowed requests per second being reached. This happens on free plans as requests are limited to 1 per second. | | 500 | Internal server error | The request could not be completed due to an error on the server side. | | 503 | Service unavailable | The server was unavailable. | ## Country Codes Below is a list of two-letter ISO 3166 Alpha 2 country codes that are used in the response. View this list in a [CSV](https://docs.google.com/spreadsheets/d/1w4VMneDoL6JW2NaUp2SjTOyvRcD4rlXDI0XpqKS2PeQ/view?usp=sharing). | Country name | Country code | | -------------------------------- | ------------ | | Afghanistan | AF | | Albania | AL | | Algeria | DZ | | American Samoa | AS | | Andorra | AD | | Angola | AO | | Anguilla | AI | | Antigua and Barbuda | AG | | Argentina | AR | | Armenia | AM | | Aruba | AW | | Australia | AU | | Austria | AT | | Azerbaijan | AZ | | Bahrain | BH | | Bangladesh | BD | | Barbados | BB | | Belarus | BY | | Belgium | BE | | Belize | BZ | | Benin | BJ | | Bermuda | BM | | Bhutan | BT | | Bolivia | BO | | Bosnia and Herzegovina | BA | | Botswana | BW | | Brazil | BR | | British Virgin Islands | VG | | Brunei | BN | | Bulgaria | BG | | Burkina Faso | BF | | Burundi | BI | | Cabo Verde | CV | | Cambodia | KH | | Cameroon | CM | | Canada | CA | | Cayman Islands | KY | | Central African Republic | CF | | Chad | TD | | Chile | CL | | China | CN | | Colombia | CO | | Comoros | KM | | Congo | CG | | Congo Democratic Republic | CD | | Cook Islands | CK | | Costa Rica | CR | | Cote d'Ivoire | CI | | Croatia | HR | | Cuba | CU | | Curaçao | CW | | Cyprus | CY | | Czechia | CZ | | Denmark | DK | | Djibouti | DJ | | Dominica | DM | | Dominican Republic | DO | | East Timor | TL | | Ecuador | EC | | Egypt | EG | | El Salvador | SV | | Equatorial Guinea | GQ | | Eritrea | ER | | Estonia | EE | | eSwatini | SZ | | Ethiopia | ET | | Falkland Islands | FK | | Faroe Islands | FO | | Fiji | FJ | | Finland | FI | | France | FR | | French Guiana | GF | | French Polynesia | PF | | Gabon | GA | | Gambia | GM | | Georgia | GE | | Germany | DE | | Ghana | GH | | Gibraltar | GI | | Greece | GR | | Greenland | GL | | Grenada | GD | | Guadeloupe | GP | | Guam | GU | | Guatemala | GT | | Guernsey | GG | | Guinea | GN | | Guinea-Bissau | GW | | Guyana | GY | | Haiti | HT | | Honduras | HN | | Hong Kong | HK | | Hungary | HU | | Iceland | IS | | India | IN | | Indonesia | ID | | Iran | IR | | Iraq | IQ | | Ireland | IE | | Isle of Man | IM | | Israel | IL | | Italy | IT | | Jamaica | JM | | Japan | JP | | Jersey | JE | | Jordan | JO | | Kazakhstan | KZ | | Kenya | KE | | Kiribati | KI | | Kosovo | XK | | Kuwait | KW | | Kyrgyzstan | KG | | Laos | LA | | Latvia | LV | | Lebanon | LB | | Lesotho | LS | | Liberia | LR | | Libya | LY | | Liechtenstein | LI | | Lithuania | LT | | Luxembourg | LU | | Macau | MO | | Madagascar | MG | | Malawi | MW | | Malaysia | MY | | Maldives | MV | | Mali | ML | | Malta | MT | | Marshall Islands | MH | | Martinique | MQ | | Mauritania | MR | | Mauritius | MU | | Mayotte | YT | | Mexico | MX | | Micronesia | FM | | Moldova | MD | | Monaco | MC | | Mongolia | MN | | Montenegro | ME | | Montserrat | MS | | Morocco | MA | | Mozambique | MZ | | Myanmar | MM | | Namibia | NA | | Nauru | NR | | Nepal | NP | | Netherlands | NL | | New Caledonia | NC | | New Zealand | NZ | | Nicaragua | NI | | Niger | NE | | Nigeria | NG | | North Korea | KP | | North Macedonia | MK | | Northern Mariana Islands | MP | | Norway | NO | | Oman | OM | | Pakistan | PK | | Palau | PW | | Panama | PA | | Papua New Guinea | PG | | Paraguay | PY | | Peru | PE | | Philippines | PH | | Poland | PL | | Portugal | PT | | Puerto Rico | PR | | Qatar | QA | | Reunion | RE | | Romania | RO | | Russia | RU | | Rwanda | RW | | Saint Helena | SH | | Saint Kitts and Nevis | KN | | Saint Lucia | LC | | Saint Martin | MF | | Saint Pierre and Miquelon | PM | | Saint Vincent and the Grenadines | VC | | Samoa | WS | | San Marino | SM | | Sao Tome and Principe | ST | | Saudi Arabia | SA | | Senegal | SN | | Serbia | RS | | Seychelles | SC | | Sierra Leone | SL | | Singapore | SG | | Sint Maarten | SX | | Slovakia | SK | | Slovenia | SI | | Solomon Islands | SB | | Somalia | SO | | South Africa | ZA | | South Korea | KR | | South Sudan | SS | | Spain | ES | | Sri Lanka | LK | | St. Barts | BL | | Sudan | SD | | Suriname | SR | | Sweden | SE | | Switzerland | CH | | Syria | SY | | Taiwan | TW | | Tajikistan | TJ | | Tanzania | TZ | | Thailand | TH | | The Bahamas | BS | | Togo | TG | | Tonga | TO | | Trinidad and Tobago | TT | | Tunisia | TN | | Turkey | TR | | Turkmenistan | TM | | Turks and Caicos Islands | TC | | Tuvalu | TV | | Uganda | UG | | Ukraine | UA | | United Arab Emirates | AE | | United Kingdom | GB | | United States | US | | Uruguay | UY | | US Virgin Islands | VI | | Uzbekistan | UZ | | Vanuatu | VU | | Vatican City (Holy See) | VA | | Venezuela | VE | | Vietnam | VN | | Wallis and Futuna | WF | | Yemen | YE | | Zambia | ZM | | Zimbabwe | ZW | ## Other notes Important billing information: Every IP address you process consumes one credit. Billing occurs per request submission, regardless of whether the response is successful. Therefore, even submitting an invalid IP address like "fda3346ds" will still deduct one credit from your account. # Phone Validation API Source: https://docs.cleariflow.com/phone-validation GET https://phonevalidation.cleariflow.com/v1 Cleariflow Phone Number Validation API is a fast, lightweight RESTful JSON API for structural phone number validation, E.164 normalization, and optional carrier, location, timezone, and dialability details. It's very simple to use: submit your API key and a phone number. The API returns whether the number is **structurally valid** and, when valid, normalized E.164 formats plus optional details such as line type, location hints, carrier data, timezones, and dialability where available. `valid: true` means the number matches regional format rules (length, prefix, syntax). It does **not** confirm the line is active, assigned to a subscriber, or reachable. For live line status you need carrier lookup, which is outside this API. ## Getting started ### REST The Phone Number Validation API, like all Cleariflow APIs, is organized around REST. It is designed to use predictable, resource-oriented URLs and HTTP status codes to indicate errors. ### HTTPS The Phone Number Validation API requires all communications to be secured with TLS 1.2 or greater. ### API Versions All Cleariflow APIs are versioned. The Phone Number Validation API is currently on Version 1. ### Your API Key Your API key is your unique authentication key for the Cleariflow Phone Number Validation API. Note that each Cleariflow API has a unique API key, so you will need different keys to access the Phone Number Validation and Email Validation APIs, for example. To authenticate your requests, append your API key to the base URL. ### Base URL ``` https://phonevalidation.cleariflow.com/v1/ ``` ### What `valid` means | `valid` | Meaning | | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `true` | The number is structurally valid for its detected region. | | `false` | The number could not be parsed or fails regional format rules. `format`, `country`, `location`, `type`, `carrier`, `carrier_display`, `timezones`, `geographical`, and `internationally_dialable` are always empty or false; `possible` and `invalid_reason` are still populated when the input could be parsed. `phone` contains digits from your input only. | Fictional US 555 numbers and other structurally valid but unassigned ranges may still return `valid: true`. `carrier` and `location` are populated mainly for US/CA numbers and are often empty elsewhere. ### Validation endpoint The API requires your unique API key and the phone number to check: ``` https://phonevalidation.cleariflow.com/v1/ ? api_key = YOUR_UNIQUE_API_KEY & phone = 14155552671 & country = US ``` **Valid response** (`phone=14155552671`, `country=US`): ```json theme={"system"} { "phone": "14155552671", "valid": true, "possible": true, "format": { "international": "+14155552671", "local": "(415) 555-2671" }, "country": { "code": "US", "name": "United States", "prefix": "+1" }, "location": "San Francisco, CA", "type": "Landline_or_Mobile", "carrier": "", "carrier_display": "", "timezones": ["America/Los_Angeles"], "geographical": true, "internationally_dialable": true } ``` **Invalid response** (`phone=123`, `country=US`): ```json theme={"system"} { "phone": "123", "valid": false, "possible": false, "invalid_reason": "too_short", "format": { "international": "", "local": "" }, "country": { "code": "", "name": "", "prefix": "" }, "location": "", "type": "Unknown", "carrier": "", "carrier_display": "", "timezones": null, "geographical": false, "internationally_dialable": false } ``` ### Request parameters Your unique API key. Note that each user has unique API keys *for each of Cleariflow APIs*, so your Phone Validation API key will not work for your IP Geolocation API, for example. The phone number to validate. Optional ISO 3166-1 alpha-2 hint for national-format numbers without a leading `+`. For example, `country=US` helps parse `4155552671`. Numbers with an international prefix are parsed from their country code; the detected `country.code` in the response may differ from this hint (e.g. `GG` for some `+44` mobile ranges). ### Response parameters The API response is returned in a universal and lightweight [JSON format](https://www.json.org/json-en.html). Normalized E.164 digits (without `+`) when `valid` is true. When `valid` is false, digits from your input only. `true` when the number is structurally valid. This is **not** line-status or subscriber verification. Lenient length check. `true` when the digits and length could belong to a real number, even if `valid` is false. Present when `valid` is false. One of: `not_a_number`, `possible`, `possible_local_only`, `invalid_country_code`, `too_short`, `invalid_length`, `too_long`, `unknown`. Omitted when `valid` is true. `international` and `local` formats. Empty strings when `valid` is false. E.164 format with a leading `+`. Empty when `valid` is false. National format for the detected region. Empty when `valid` is false. Detected country/territory. Empty fields when `valid` is false. Two-letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code for the detected region. English display name for `country.code`. International [calling code prefix](https://en.wikipedia.org/wiki/List_of_country_calling_codes) (e.g. `+1`). Location hint (region, state/province, or city). Often empty outside US/CA. Empty when `valid` is false. Line type when `valid` is true: `Landline`, `Mobile`, `Landline_or_Mobile`, `Toll_Free`, `Premium`, `Paging`, `Special`, or `Unknown`. Always `Unknown` when `valid` is false. Carrier name when available (most often US/CA). Empty string otherwise, including when `valid` is false. Safe carrier name for end-user display (when valid and the region does not use mobile number portability). Empty when `valid` is false or the carrier cannot be shown safely. Timezone identifiers for the number (e.g. `America/New_York`). Empty array when `valid` is true but no mapping exists; `null` when `valid` is false. Whether the number is associated with a geographic region. Always `false` when `valid` is false. Whether the number can be dialed from outside its home region. Always `false` when `valid` is false. ## Bulk upload (CSV) Here are some best practices when bulk uploading a CSV file: * Ensure the first column contains the phone numbers to be analyzed. * Remove any empty rows from the file. * Include only one phone number per row. * The maximum file size permitted is 50,000 rows. ## Response and error codes Whenever you make a request that fails for some reason, an error is returned also in the JSON format. The errors include an error code and description, which you can find in detail below. | Code | Type | Details | | ---- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | OK | Everything worked as expected. | | 400 | Bad request | Bad request. | | 401 | Unauthorized | The request was unacceptable. Typically due to the API key missing or incorrect. | | 422 | Quota reached | The request was aborted due to insufficient API credits. (Free plans) | | 429 | Too many requests | The request was aborted due to the number of allowed requests per second being reached. This happens on free plans as requests are limited to 1 per second. | | 500 | Internal server error | The request could not be completed due to an error on the server side. | | 503 | Service unavailable | The server was unavailable. | ## Other notes A note on metered billing: Each individual phone number you submit counts as a credit used. Credits are also counted per request, not per successful response. So if you submit a request for the (invalid) phone number "kasj8929hs", that still counts as 1 credit. # Introduction Source: https://docs.cleariflow.com/scrape Cleariflow Web Scraping API delivers JavaScript-rendered page extraction through a modern RESTful JSON interface with SSRF protection and flexible rendering options. ## Getting started The `scrape` endpoint runs a browser session and returns rendered HTML in a single request — ideal for low-latency integrations. The `jobs` endpoints enqueue long-running scrapes and let you poll for status and results — ideal for high-volume or slow pages. ### REST Architecture The Web Scraping API follows REST principles, utilizing predictable resource-oriented URLs and standard HTTP status codes for seamless integration and error handling. ### HTTPS Security All API communications are secured using TLS 1.2 or higher encryption protocols to ensure data integrity and privacy. ### API Versioning The Web Scraping API maintains backward compatibility through versioning, currently operating on Version 1. ### Authentication Your API key serves as the exclusive credential for accessing the Web Scraping API. Each Cleariflow service requires a unique key. Include your key in the JSON body as `api_key`. ### Base URL ``` https://scrape.cleariflow.com ``` ### Page rendering Pages are rendered in a real headless browser. JavaScript is fully executed before content is returned. Built-in SSRF protection blocks requests to localhost and private IP ranges. ## Response and error codes When requests fail, the API returns structured JSON error responses with specific codes and descriptions for effective troubleshooting. | Code | Type | Details | | ---- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | OK | Everything worked as expected. | | 202 | Accepted | Async job was enqueued successfully. | | 400 | Bad request | Bad request — invalid URL, blocked target, or malformed payload. | | 401 | Unauthorized | The request was unacceptable. Typically due to the API key missing or incorrect. | | 422 | Quota reached | The request was aborted due to insufficient API credits. (Free plans) | | 429 | Too many requests | The request was aborted due to the number of allowed requests per second being reached. This happens on free plans as requests are limited to 1 per second. | | 500 | Internal server error | The request could not be completed due to an error on the server side. | # Async jobs Source: https://docs.cleariflow.com/scrape/jobs POST https://scrape.cleariflow.com/v1/jobs The `jobs` endpoints enqueue scrape tasks for background processing and let you poll for status and results — ideal for high-volume or long-running scrapes. ## Getting started ### Base URL ``` https://scrape.cleariflow.com/v1/jobs ``` ## Create a job Enqueue an async scrape job with the same `ScrapeRequest` payload used by the synchronous endpoint. ### Example request ```bash theme={"system"} curl -X POST 'https://scrape.cleariflow.com/v1/jobs' \ -H 'Content-Type: application/json' \ -d '{ "request": { "api_key": "YOUR_UNIQUE_API_KEY", "url": "https://example.com" }, "priority": 10 }' ``` This successful request returns a job identifier: ```json theme={"system"} { "job_id": "550e8400-e29b-41d4-a716-446655440000" } ``` ### Create job parameters A `ScrapeRequest` object with the same fields as the synchronous scrape endpoint (`url`, `render`, `actions`, `cookies`, etc.). Job priority. Higher values are processed first. Defaults to 0. ## Get job status Poll a job by ID to check its status and retrieve results when complete. ### Base URL ``` https://scrape.cleariflow.com/v1/jobs/{job_id} ``` ### Example request ```bash theme={"system"} curl 'https://scrape.cleariflow.com/v1/jobs/550e8400-e29b-41d4-a716-446655440000' ``` While the job is running: ```json theme={"system"} { "job_id": "550e8400-e29b-41d4-a716-446655440000", "status": "running" } ``` When the job completes successfully: ```json theme={"system"} { "job_id": "550e8400-e29b-41d4-a716-446655440000", "status": "done", "result": { "ok": true, "html": "...", "meta": { "elapsed_ms": 8123 } } } ``` ### Job status values | Status | Description | | --------- | ----------------------------------------------- | | `queued` | Job is waiting in the queue. | | `running` | Browser session is active. | | `done` | Scrape completed; `result` contains the output. | | `failed` | Scrape failed; `error` contains a description. | ### Response parameters Unique identifier for the async job. Current job status: `queued`, `running`, `done`, or `failed`. The scrape result object (same shape as the synchronous endpoint response). Present when `status` is `done`. Error message. Present when `status` is `failed`. Additional metadata about the job execution. # Synchronous scrape Source: https://docs.cleariflow.com/scrape/scrape POST https://scrape.cleariflow.com/v1/scrape The `scrape` endpoint runs a browser session, executes JavaScript, and returns rendered HTML in a single synchronous request. ## Getting started ### Base URL ``` https://scrape.cleariflow.com/v1/scrape ``` ### Example request ```bash theme={"system"} curl -X POST 'https://scrape.cleariflow.com/v1/scrape' \ -H 'Content-Type: application/json' \ -d '{ "api_key": "YOUR_UNIQUE_API_KEY", "url": "https://example.com", "render": { "wait_until": "networkidle", "timeout_ms": 60000 } }' ``` This successful request returns the rendered page HTML and metadata: ```json theme={"system"} { "ok": true, "html": "...", "meta": { "elapsed_ms": 4521 } } ``` ### Render options The `render` object controls how the browser loads the page before HTML is captured. All fields are optional — when omitted, server defaults apply. ```json theme={"system"} "render": { "wait_until": "networkidle", "timeout_ms": 60000, "post_load_wait_ms": 2000, "ignore_https_errors": false } ``` | Field | Type | Default | Description | | --------------------- | ------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `wait_until` | String | `domcontentloaded` | When to consider navigation finished. Use `domcontentloaded` for faster results; use `networkidle` when the page loads data via XHR/fetch after the initial HTML. | | `timeout_ms` | Integer | `60000` | Maximum time in milliseconds to wait for page load. The request fails if navigation exceeds this limit. | | `post_load_wait_ms` | Integer | `0` | Extra delay in milliseconds after `wait_until` before capturing HTML. Useful for animations, lazy-loaded widgets, or client-side rendering that continues after `networkidle`. | | `ignore_https_errors` | Boolean | `false` | When `true`, ignore TLS certificate errors on the target page. | Example for a JavaScript-heavy page that keeps fetching data after load: ```bash theme={"system"} curl -X POST 'https://scrape.cleariflow.com/v1/scrape' \ -H 'Content-Type: application/json' \ -d '{ "api_key": "YOUR_UNIQUE_API_KEY", "url": "https://quotes.toscrape.com/js/", "render": { "wait_until": "networkidle", "timeout_ms": 60000, "post_load_wait_ms": 1500, "ignore_https_errors": false } }' ``` ### Resource options The `resources` object controls which asset types the browser loads during scraping. Blocking heavy assets speeds up requests when you only need HTML text and structure. ```json theme={"system"} "resources": { "block": ["images", "fonts", "media"] } ``` | Value | Blocks | | -------- | ------------------------------------------------------------- | | `images` | Images (``, CSS backgrounds, SVG icons loaded as images) | | `fonts` | Web fonts | | `media` | Video and audio streams | All fields are optional. When `resources` is omitted, no resource types are blocked unless your deployment sets server-side defaults. Example — scrape faster by skipping images and fonts: ```bash theme={"system"} curl -X POST 'https://scrape.cleariflow.com/v1/scrape' \ -H 'Content-Type: application/json' \ -d '{ "api_key": "YOUR_UNIQUE_API_KEY", "url": "https://quotes.toscrape.com/", "resources": { "block": ["images", "fonts"] } }' ``` ### Request parameters The target URL to scrape. Must be a public HTTP or HTTPS URL. Requests to localhost and private IP addresses are blocked by SSRF protection. Your unique API key. Optional session identifier to reuse browser state (cookies, local storage) across multiple scrape requests. Browser fingerprint preset. Supported values: `desktop_en_us`, `desktop_ru_ru`, `mobile_en_us`. Rendering options for the browser session. When to consider navigation finished. Values: `domcontentloaded`, `networkidle`. Defaults to `domcontentloaded`. Maximum time in milliseconds to wait for page load. Defaults to 60000. Additional delay in milliseconds after the page load event before capturing content. When `true`, ignore TLS certificate errors for the target page. Resource loading controls. Resource types to block. Supported values: `images`, `fonts`, `media`. Ordered list of browser actions to perform before capturing content. Each action is an object with a `type` field. Action type. Supported values: `wait`, `wait_for`, `click`, `type`, `scroll`. CSS selector for `wait_for`, `click`, or `type` actions. Text to type for the `type` action. Scroll target for the `scroll` action (e.g. `bottom`). Duration in milliseconds for the `wait` action. Timeout in milliseconds for `wait_for` actions. Cookies to inject before navigation. Each cookie object requires `name` and `value`; optional fields: `domain`, `path`. ### Response parameters The API response is returned in a universal and lightweight [JSON format](https://www.json.org/json-en.html). Whether the scrape completed successfully. The rendered page HTML. Metadata about the scrape, including final URL, HTTP status code, and duration. Error details when `ok` is `false`. # Introduction Source: https://docs.cleariflow.com/screenshot Cleariflow Website Screenshot API captures pixel-perfect images of any public URL through a modern RESTful JSON interface with SSRF protection, viewport control, and browser automation options. ## Getting started The `screenshot` endpoint runs a browser session and returns a base64-encoded image in JSON — ideal for programmatic integrations and the API Tester. The `jobs` endpoints enqueue screenshot tasks for background processing and let you poll for status and results — ideal for high-volume or slow pages. ### REST Architecture The Website Screenshot API follows REST principles, utilizing predictable resource-oriented URLs and standard HTTP status codes for seamless integration and error handling. ### HTTPS Security All API communications are secured using TLS 1.2 or higher encryption protocols to ensure data integrity and privacy. ### API Versioning The Website Screenshot API maintains backward compatibility through versioning, currently operating on Version 1. ### Authentication Your API key serves as the exclusive credential for accessing the Website Screenshot API. Each Cleariflow service requires a unique key. Include your key in the JSON body as `api_key`, or as a query parameter for the legacy GET endpoint. ### Base URL ``` https://screenshot.cleariflow.com ``` ### Page rendering Pages are rendered in a real headless browser. JavaScript is fully executed before the screenshot is captured. Built-in SSRF protection blocks requests to localhost and private IP ranges. ## Response and error codes When requests fail, the API returns structured JSON error responses with specific codes and descriptions for effective troubleshooting. | Code | Type | Details | | ---- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | OK | Screenshot captured successfully. | | 202 | Accepted | Async job was enqueued successfully. | | 400 | Bad request | Bad request — invalid URL, blocked target, or malformed payload. | | 401 | Unauthorized | The request was unacceptable. Typically due to the API key missing or incorrect. | | 422 | Quota reached | The request was aborted due to insufficient API credits. (Free plans) | | 429 | Too many requests | The request was aborted due to the number of allowed requests per second being reached. This happens on free plans as requests are limited to 1 per second. | | 500 | Internal server error | The request could not be completed due to an error on the server side. | # Async jobs Source: https://docs.cleariflow.com/screenshot/jobs POST https://screenshot.cleariflow.com/v1/jobs The `jobs` endpoints enqueue screenshot tasks for background processing and let you poll for status and results — ideal for high-volume or long-running captures. ## Getting started ### Base URL ``` https://screenshot.cleariflow.com/v1/jobs ``` ## Create a job Enqueue an async screenshot job with the same `ScreenshotRequest` payload used by the synchronous endpoint. ### Example request ```bash theme={"system"} curl -X POST 'https://screenshot.cleariflow.com/v1/jobs' \ -H 'Content-Type: application/json' \ -d '{ "request": { "api_key": "YOUR_UNIQUE_API_KEY", "url": "https://cleariflow.com" }, "priority": 10 }' ``` This successful request returns a job identifier: ```json theme={"system"} { "job_id": "550e8400-e29b-41d4-a716-446655440000" } ``` ### Create job parameters A `ScreenshotRequest` object with the same fields as the synchronous screenshot endpoint (`url`, `render`, `actions`, `cookies`, etc.). Job priority. Higher values are processed first. Defaults to 0. ## Get job status Poll a job by ID to check its status and retrieve results when complete. ### Base URL ``` https://screenshot.cleariflow.com/v1/jobs/{job_id} ``` ### Example request ```bash theme={"system"} curl 'https://screenshot.cleariflow.com/v1/jobs/550e8400-e29b-41d4-a716-446655440000' ``` While the job is running: ```json theme={"system"} { "job_id": "550e8400-e29b-41d4-a716-446655440000", "status": "running" } ``` When the job completes successfully: ```json theme={"system"} { "job_id": "550e8400-e29b-41d4-a716-446655440000", "status": "done", "result": { "ok": true, "image_base64": "/9j/4AAQSkZJRg...", "content_type": "image/jpeg", "meta": { "elapsed_ms": 8123 } } } ``` ### Job status values | Status | Description | | --------- | --------------------------------------------------- | | `queued` | Job is waiting in the queue. | | `running` | Browser session is active. | | `done` | Screenshot completed; `result` contains the output. | | `failed` | Screenshot failed; `error` contains a description. | ### Response parameters Unique identifier for the async job. Current job status: `queued`, `running`, `done`, or `failed`. The screenshot result object (same shape as the synchronous endpoint response). Present when `status` is `done`. Error message. Present when `status` is `failed`. Additional metadata about the job execution. # Synchronous screenshot Source: https://docs.cleariflow.com/screenshot/screenshot POST https://screenshot.cleariflow.com/v1/screenshot The `screenshot` endpoint runs a browser session, executes JavaScript, and returns a base64-encoded image in a single synchronous request. ## Getting started ### Base URL ``` https://screenshot.cleariflow.com/v1/screenshot ``` ### Example request ```bash theme={"system"} curl -X POST 'https://screenshot.cleariflow.com/v1/screenshot' \ -H 'Content-Type: application/json' \ -d '{ "api_key": "YOUR_UNIQUE_API_KEY", "url": "https://cleariflow.com", "capture_full_page": true, "export_format": "jpeg" }' ``` This successful request returns the screenshot as base64 and metadata: ```json theme={"system"} { "ok": true, "image_base64": "/9j/4AAQSkZJRg...", "content_type": "image/jpeg", "meta": { "elapsed_ms": 4521 } } ``` Decode `image_base64` to obtain the raw JPEG or PNG bytes. ### Render options The `render` object controls how the browser loads the page before the screenshot is taken. All fields are optional — when omitted, server defaults apply. ```json theme={"system"} "render": { "wait_until": "networkidle", "timeout_ms": 60000, "post_load_wait_ms": 2000, "ignore_https_errors": false, "full_page": true, "screenshot_format": "jpeg", "user_agent": "Mozilla/5.0 ...", "viewport": { "width": 1365, "height": 768 } } ``` | Field | Type | Default | Description | | --------------------- | ------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `wait_until` | String | `domcontentloaded` | When to consider navigation finished. Use `domcontentloaded` for faster results; use `networkidle` when the page loads data via XHR/fetch after the initial HTML. | | `timeout_ms` | Integer | `60000` | Maximum time in milliseconds to wait for page load. | | `post_load_wait_ms` | Integer | `0` | Extra delay in milliseconds after `wait_until` before capture. Useful for animations or lazy-loaded content. | | `ignore_https_errors` | Boolean | `false` | When `true`, ignore TLS certificate errors on the target page. | | `full_page` | Boolean | `true` | When `true`, capture the entire scrollable page height. | | `screenshot_format` | String | `jpeg` | Output format: `jpeg` or `png`. | | `user_agent` | String | — | Custom User-Agent string for the browser session. | | `viewport` | Object | `1365×768` | Viewport size via `width` and `height` in pixels. | ### Convenience fields These top-level fields are aliases merged into `render` and `actions` for backward compatibility and simpler requests: | Field | Maps to | Description | | ------------------- | -------------------------- | ------------------------------------------------------------------- | | `capture_full_page` | `render.full_page` | Full-page capture toggle. | | `width` / `height` | `render.viewport` | Viewport dimensions in pixels. | | `delay` | `render.post_load_wait_ms` | Delay in **seconds** before capture. | | `export_format` | `render.screenshot_format` | `jpeg` or `png`. | | `user_agent` | `render.user_agent` | Custom User-Agent. | | `css_injection` | `inject_css` action | CSS injected before capture when no `inject_css` action is present. | Example with flat fields: ```bash theme={"system"} curl -X POST 'https://screenshot.cleariflow.com/v1/screenshot' \ -H 'Content-Type: application/json' \ -d '{ "api_key": "YOUR_UNIQUE_API_KEY", "url": "https://cleariflow.com", "width": 1280, "height": 720, "delay": 2, "export_format": "png" }' ``` ### Resource options The `resources` object controls which asset types the browser loads during capture. Blocking heavy assets speeds up requests when visual fidelity allows it. ```json theme={"system"} "resources": { "block": ["images", "fonts", "media"] } ``` | Value | Blocks | | -------- | --------------------------------- | | `images` | Images (``, CSS backgrounds) | | `fonts` | Web fonts | | `media` | Video and audio streams | ### Legacy GET endpoint `GET /v1/` returns raw image bytes (JPEG or PNG) instead of JSON. Pass parameters as query strings: ``` https://screenshot.cleariflow.com/v1/?api_key=YOUR_UNIQUE_API_KEY&url=https://cleariflow.com&capture_full_page=true&export_format=jpeg ``` Supported query parameters: `url`, `api_key`, `session_id`, `fingerprint`, `capture_full_page`, `width`, `height`, `delay`, `css_injection`, `user_agent`, `export_format`. ### Request parameters The target URL to capture. Must be a public HTTP or HTTPS URL. Requests to localhost and private IP addresses are blocked by SSRF protection. Your unique API key. Optional session identifier to reuse browser state (cookies, local storage) across multiple requests. Browser fingerprint preset. Supported values: `desktop_en_us`, `desktop_ru_ru`, `mobile_en_us`. Rendering and capture options for the browser session. When to consider navigation finished. Values: `domcontentloaded`, `networkidle`. Defaults to `domcontentloaded`. Maximum time in milliseconds to wait for page load. Defaults to 60000. Additional delay in milliseconds after the page load event before capture. When `true`, ignore TLS certificate errors for the target page. When `true`, capture the full scrollable page. Defaults to `true`. Output format: `jpeg` or `png`. Defaults to `jpeg`. Custom User-Agent for the browser session. Viewport size with `width` and `height` in pixels. Resource loading controls. Resource types to block. Supported values: `images`, `fonts`, `media`. Ordered list of browser actions to perform before capture. Each action is an object with a `type` field. Action type. Supported values: `wait`, `wait_for`, `click`, `type`, `scroll`, `inject_css`. CSS selector for `wait_for`, `click`, or `type` actions. Text to type for the `type` action. CSS string for the `inject_css` action. Scroll target for the `scroll` action (e.g. `bottom`). Duration in milliseconds for the `wait` action. Cookies to inject before navigation. Each cookie object requires `name` and `value`; optional fields: `domain`, `path`. Convenience alias for `render.full_page`. Convenience alias for `render.viewport.width`. Convenience alias for `render.viewport.height`. Delay in seconds before capture. Mapped to `render.post_load_wait_ms`. CSS injected via an `inject_css` action when not already present in `actions`. Convenience alias for `render.screenshot_format`. Values: `jpeg`, `png`. ### Response parameters The API response is returned in a universal and lightweight [JSON format](https://www.json.org/json-en.html). Whether the screenshot completed successfully. Base64-encoded image data. Decode to obtain raw JPEG or PNG bytes. MIME type of the image (`image/jpeg` or `image/png`). Metadata about the capture, including elapsed time in milliseconds. Error details when `ok` is `false`. # Introduction Source: https://docs.cleariflow.com/vat Cleariflow VAT Validation API delivers comprehensive tax compliance solutions through a streamlined, contemporary RESTful JSON interface, enabling seamless validation and calculation for domestic and international business operations. ## Getting started Verify VAT number authenticity and retrieve comprehensive company information including country, business name, address, and registration details. Compute VAT-compliant pricing based on country-specific regulations, purchase type, and transaction value for accurate financial calculations. Access current VAT rates and tax categories for specific countries to ensure compliance with local tax regulations. ### REST Architecture The VAT Validation API follows REST principles, utilizing predictable resource-oriented URLs and standard HTTP status codes for seamless integration and error handling. All API endpoints must end with a trailing slash (/) and support only GET requests. ### HTTPS Security All API communications are secured using TLS 1.2 or higher encryption protocols to ensure data integrity and privacy. ### API Versioning The VAT Validation API maintains backward compatibility through versioning, currently operating on Version 1 with planned future enhancements. ### Authentication Your API key serves as the exclusive credential for accessing the VAT Validation API. Each Cleariflow service requires a unique key, ensuring secure and isolated access across different APIs. The API implements rate limiting to ensure fair usage across all users. ## Response and error codes When requests fail, the API returns structured JSON error responses with specific codes and descriptions for effective troubleshooting. | Code | Type | Details | | ---- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | OK | Everything worked as expected. | | 400 | Bad request | Bad request. | | 401 | Unauthorized | The request was unacceptable. Typically due to the API key missing or incorrect. | | 422 | Quota reached | The request was aborted due to insufficient API credits. (Free plans) | | 429 | Too many requests | The request was aborted due to the number of allowed requests per second being reached. This happens on free plans as requests are limited to 1 per second. | | 500 | Internal server error | The request could not be completed due to an error on the server side. | | 503 | Service unavailable | The server was unavailable. | ## Country codes Below are the list of countries supported by the VAT endpoints | Country code | Country name | | ------------ | --------------- | | AT | Austria | | BE | Belgium | | BG | Bulgaria | | CY | Cyprus | | CZ | Czech Republic | | DE | Germany | | DK | Denmark | | EE | Estonia | | FI | Finland | | FR | France | | GB | United Kingdom | | GR | Greece | | HR | Croatia | | HU | Hungary | | IE | Ireland | | IT | Italy | | LT | Lithuania | | LU | Luxembourg | | LV | Latvia | | MT | Malta | | NL | The Netherlands | | PL | Poland | | PT | Portugal | | RO | Romania | | SE | Sweden | | SI | Slovenia | | SK | Slovakia | # Calculate VAT endpoint Source: https://docs.cleariflow.com/vat/calculate GET https://vat.cleariflow.com/v1/calculate/ The `calculate` endpoint enables precise VAT computation for compliant pricing, taking into account country-specific regulations, transaction amounts, and optional product categories for accurate tax calculations. ## Getting started ### Base URL ``` https://vat.cleariflow.com/v1/calculate/ ``` ### Calculation endpoint The `calculate` endpoint requires your unique API key, the country and the price you'd like to check: ``` https://vat.cleariflow.com/v1/calculate/ ? api_key = YOUR_UNIQUE_API_KEY & amount = 175 & country_code = DE & category = standard ``` This successful request returns comprehensive VAT calculation results including rates, amounts, and country information: ```json theme={"system"} { "amount_excluding_vat": "175.00", "amount_including_vat": "208.25", "country": { "code": "DE", "name": "Germany" }, "vat_amount": "33.25", "vat_category": "standard", "vat_rate": "0.190" } ``` ### Request parameters Your unique API key. Note that each user has unique API keys for each of Cleariflow APIs, so your VAT Validation API key will not work for as your IP Geolocation API, for example. The amount that you would like to get the VAT amount for or from. The two letter ISO 3166-1 alpha-2 code of the country in which the transaction takes place. The VAT category to use for calculation. Use "standard" for standard VAT rate, or specific categories like "e-books", "audiobooks", etc. for reduced rates. If the amount already has VAT added and you'd like to do the reverse calculation and split out the amount and VAT, set this parameter to true. If this parameter is not explicitly included it will default to false. ### Response parameters The API response is returned in a universal and lightweight [JSON format](https://www.json.org/json-en.html). The amount excluding the VAT. The sum of the base amount and the VAT, i.e., `amount_excluding_vat` + `vat_amount`. The calculated amount of VAT. The category of the purchase, used to determine whether it qualifies for a reduced rate. See below for a list of supported categories. The VAT rate as a decimal string (e.g., "0.190" for 19%). Object containing country information. The two letter ISO 3166-1 alpha-2 code of the country in which the transaction takes place. The name of the country the VAT is being calculated from. # VAT Categories endpoint Source: https://docs.cleariflow.com/vat/categories GET https://vat.cleariflow.com/v1/categories/ The `categories` endpoint provides comprehensive access to current VAT rates and tax categories for specific countries, including reduced rates for qualifying goods and services to ensure accurate tax compliance. ## Getting started ### Base URL ``` https://vat.cleariflow.com/v1/categories/ ``` ### Categories endpoint The `categories` endpoint requires your unique API key, and the country you'd like to check: ``` https://vat.cleariflow.com/v1/categories/ ? api_key = YOUR_UNIQUE_API_KEY & country_code = DE ``` This successful request returns comprehensive VAT rate information including standard rates and reduced rates with their associated categories: ```json theme={"system"} [ { "category": "some agricultural inputs", "country_code": "DE", "description": "Reduced VAT rate (some agricultural inputs)", "rate": "0.070" }, { "category": "taxation of some gold coins and jewellery", "country_code": "DE", "description": "Reduced VAT rate (taxation of some gold coins and jewellery)", "rate": "0.070" }, { "category": "cut flowers and plants for decorative use and food production", "country_code": "DE", "description": "Reduced VAT rate (cut flowers and plants for decorative use and food production)", "rate": "0.070" }, { "category": "e-books", "country_code": "DE", "description": "Reduced VAT rate (e-books)", "rate": "0.070" }, .................. { "category": "standard", "country_code": "DE", "description": "Standard VAT rate", "rate": "0.190" }, { "category": "newspapers and periodicals (except those containing content harmful to minors and/or more than 50% advertising)", "country_code": "DE", "description": "Reduced VAT rate (newspapers and periodicals (except those containing content harmful to minors and/or more than 50% advertising))", "rate": "0.070" }, { "category": "some timber for industrial use", "country_code": "DE", "description": "Reduced VAT rate (some timber for industrial use)", "rate": "0.070" } ] ``` ### Request parameters Your unique API key. Note that each user has unique API keys for each of Cleariflow APIs, so your VAT Validation API key will not work for as your IP Geolocation API, for example. The two letter ISO 3166-1 alpha-2 code of the country for which you want to retrieve VAT categories. ### Response parameters The API response is returned in a universal and lightweight [JSON format](https://www.json.org/json-en.html). The response is an array of category objects, where each object contains: The two letter ISO 3166-1 alpha-2 code of the country for which the categories are returned. The VAT rate for this specific category as a decimal string (e.g., "0.190" for 19%). The name of the category (e.g., "standard", "e-books", "audiobooks"). A description about the category and its applicability. # Validate VAT endpoint Source: https://docs.cleariflow.com/vat/validate GET https://vat.cleariflow.com/v1/validate/ The `validate` endpoint processes VAT number submissions to verify authenticity and retrieve comprehensive business information including company details, address, and country registration data. ## Getting started ### Base URL ``` https://vat.cleariflow.com/v1/validate/ ``` ### Validation endpoint The `validate` endpoint requires your unique API key and the VAT number you'd like to check: ``` https://vat.cleariflow.com/v1/validate/ ? api_key = YOUR_UNIQUE_API_KEY & vat_number = FR64443061841 ``` This successful request returns comprehensive company information associated with the validated VAT number: ```json theme={"system"} { "company": { "address": "8 RUE DE LONDRES\n75009 PARIS", "name": "EURL GOOGLE FRANCE" }, "country": { "code": "FR", "name": "France" }, "valid": true, "vat_number": "FR64443061841" } ``` ### Request parameters Your unique API key. Note that each user has unique API keys for each of Cleariflow APIs, so your VAT Validation and Rates API key will not work for your IP Geolocation API, for example. The VAT number to validate. ### Response parameters The API response is returned in a universal and lightweight [JSON format](https://www.json.org/json-en.html). The VAT number to validate. Is true if the submitted VAT number is valid. Object containing company information. The name of the company associated with the VAT number. The address of the company associated with the VAT number. Object containing country information. The two letter ISO 3166-1 alpha-2 code of the country associated with the VAT number. The name of the country associated with the VAT number.