> This page is for APIs, version E-invoicing. > For other versions, use one of these documentation indexes: > - Overview (default): https://avalara.ferndocs.com/api-reference/overview/llms.txt > - Calculations: https://avalara.ferndocs.com/api-reference/calculations/llms.txt > - E-invoicing: https://avalara.ferndocs.com/api-reference/e-invoicing/llms.txt > - Brazil: https://avalara.ferndocs.com/api-reference/brazil/llms.txt > - Returns: https://avalara.ferndocs.com/api-reference/returns/llms.txt > - Shared service: https://avalara.ferndocs.com/api-reference/shared-service/llms.txt > - 1099 & W-9: https://avalara.ferndocs.com/api-reference/1099-w9/llms.txt > - Tax registrations & business licenses: https://avalara.ferndocs.com/api-reference/tax-registrations/llms.txt > - ECM: https://avalara.ferndocs.com/api-reference/ecm/llms.txt > - Cross-Border: https://avalara.ferndocs.com/api-reference/cross-border/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://avalara.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://avalara.ferndocs.com/_mcp/server. # Retrieves a code list by ID for a specific country GET https://api.sbx.avalara.com/einvoicing/codelists/{codelistId} > **Access control:** this endpoint is available to users with the `everyone` role. A Code List is a controlled set of predefined, standardized values used to populate specific fields in electronic documents (such as e-invoices). Each code has a stable, machine-readable identifier and a human-readable description. Code Lists are typically based on global standards (e.g., UN/CEFACT, ISO, EN16931) and may include jurisdiction-specific extensions or restrictions.Code Lists are versioned, and each version may have defined effective and sunset dates to ensure that the correct set of allowable values is applied according to regulatory or jurisdictional requirements.By default, the API returns only non-expired code list versions (versions where the sunset date has not passed). To retrieve expired versions or filter by specific date ranges, use the effectiveDate and sunsetDate query parameters. Reference: https://avalara.ferndocs.com/api-reference/e-invoicing/public-reference/get-code-list ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Path parameters - `codelistId` (string, required) — System-generated unique identifier of the code list definition. Typically a UUID used to reference this code list internally or via APIs. ### Query parameters - `countryCode` (string, required) — Two-letter ISO 3166-1 alpha-2 country code indicating the jurisdiction this code list applies to. - `effectiveDate` (date, optional) — Filter code list versions by effective date. Returns versions that are effective on or before this date. Format: YYYY-MM-DD (ISO 8601). If not specified, defaults to the current date. sunsetDate is required when effectiveDate is provided. - `sunsetDate` (date, optional) — Filter code list versions by sunset date. Returns versions that have not yet sunset on or before this date. Format: YYYY-MM-DD (ISO 8601). If not specified, only non-expired versions are returned. ### Headers - `avalara-version` (string, required) — Header that specifies the API version to use (for example "1.6"). - `X-Avalara-Client` (string, optional) — Optional header for a client identifier string used for diagnostics (for example "Fingerprint"). ## Response ### 200 OK - `countryCode` (string, optional) — Two-letter ISO 3166-1 alpha-2 country code indicating the jurisdiction this code list applies to. - `codeListId` (string, optional) — System-generated unique identifier of the code list definition. Typically a UUID used to reference this code list internally or via APIs. - `codeListName` (string, optional) — Human-readable name of the code list, usually describing what the codes represent (for example, document types, tax categories, currencies). - `description` (string, optional) — Textual description of the code list, including what it is used for and whether it represents a global standard (e.g., UN/CEFACT, ISO, EN16931) or a jurisdiction-specific/local extension of that standard. - `standard` (string, optional) — Identifier of the underlying standard or authoritative source for this code list. This may be a formal code list name (e.g., UNCL1001), a standard reference (e.g., EN16931), or an internal standard identifier. - `versions` (list of CodeListVersion, optional) — Array of versioned definitions of this code list for the given jurisdiction. Each entry represents a version that is valid for a specific effective/sunset date range, optionally per locale. ## Errors ### 400 Bad Request Error Bad request. - `error` (string, optional) — The three-digit HTTP error code for the bad request - `message` (string, optional) — A message explaining the bad request ### 401 Unauthorized Error Unauthorized. - `any` ### 403 Forbidden Error Forbidden. - `Message` (string, optional) — A message that informs the user that they may not access a resource ### 404 Not Found Error Code list not found. - `error` (string, optional) — The three-digit HTTP error code for a not found error - `message` (string, optional) — A message about the not found error ## Types ### CodeListVersion Represents a versioned definition of a code list for a specific jurisdiction and date range - `versionReasons` (list of string, optional) — List of free-text reasons explaining why this version of the code list exists (for example, initial introduction, regulatory update, addition/deprecation of codes). Useful for audit and change tracking. - `jurisEffectiveDate` (date, optional) — Date from which this version of the code list becomes legally or operationally effective in the jurisdiction. Typically corresponds to a go-live, mandate, or release date. - `jurisSunsetDate` (date, optional) — Date after which this version of the code list must no longer be used in the jurisdiction. Use a far-future date (e.g., 9999-12-31) when the sunset is not yet known. - `locale` (string, optional) — Language–region locale identifier indicating the language and regional variant for descriptions in this version of the code list. Follows BCP-47 format such as en-US, fr-FR, de-DE. - `values` (list of CodeListValue, optional) — Array of code entries defined in this version of the code list. Each entry contains the machine-readable code value and its human-readable description in the given locale. ### CodeListValue Represents a single code entry in a code list version - `code` (string, optional) — The actual code value used in documents or systems. This is typically what appears in the e-invoice payload, such as a numeric or alphanumeric code from the official code list. - `value` (string, optional) — Human-readable label or name for the code, localized according to the locale field of the version. - `description` (string, optional) — Detailed explanation of what the code represents, localized according to the locale field of the version. ## Examples **Response** ```json { "countryCode": "FR", "codeListId": "ab123343-3432-423c-ac3f-53453scs9999", "codeListName": "DocumentType", "description": "Code list of document type identifiers for France, based on UN/CEFACT document type codes, with national (local) extensions where applicable.", "standard": "UNCL1001", "versions": [ { "versionReasons": [ "Initial adoption of EN16931 document type codes", "Alignment with French e-invoicing mandate 2026" ], "jurisEffectiveDate": "2025-01-01", "jurisSunsetDate": "9999-12-31", "locale": "fr-FR", "values": [ { "code": "380", "value": "Commercial Invoice", "description": "Commercial Invoice Type" } ] } ] } ``` **SDK Code** ```python import requests url = "https://api.sbx.avalara.com/einvoicing/codelists/ab123343-3432-423c-ac3f-53453scs9999" querystring = {"countryCode":"FR"} headers = { "avalara-version": "1.6", "Authorization": "Bearer " } response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript const url = 'https://api.sbx.avalara.com/einvoicing/codelists/ab123343-3432-423c-ac3f-53453scs9999?countryCode=FR'; const options = { method: 'GET', headers: {'avalara-version': '1.6', Authorization: 'Bearer '} }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.sbx.avalara.com/einvoicing/codelists/ab123343-3432-423c-ac3f-53453scs9999?countryCode=FR" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("avalara-version", "1.6") req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.sbx.avalara.com/einvoicing/codelists/ab123343-3432-423c-ac3f-53453scs9999?countryCode=FR") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["avalara-version"] = '1.6' request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.sbx.avalara.com/einvoicing/codelists/ab123343-3432-423c-ac3f-53453scs9999?countryCode=FR") .header("avalara-version", "1.6") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.sbx.avalara.com/einvoicing/codelists/ab123343-3432-423c-ac3f-53453scs9999?countryCode=FR', [ 'headers' => [ 'Authorization' => 'Bearer ', 'avalara-version' => '1.6', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.sbx.avalara.com/einvoicing/codelists/ab123343-3432-423c-ac3f-53453scs9999?countryCode=FR"); var request = new RestRequest(Method.GET); request.AddHeader("avalara-version", "1.6"); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "avalara-version": "1.6", "Authorization": "Bearer " ] let request = NSMutableURLRequest(url: NSURL(string: "https://api.sbx.avalara.com/einvoicing/codelists/ab123343-3432-423c-ac3f-53453scs9999?countryCode=FR")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```