# GetCodeList

Retrieves a code list by ID for a specific country

`GET /codelists/{codelistId}`

**API:** Avalara E-Invoicing API
**Tag:** Code Lists
**API Version:** 1.6
**Base URL:** https://api.sbx.avalara.com/einvoicing
**Authentication:** Bearer token

Source: https://developer.avalara.com/products/e-invoicing/api/v1.6/methods/Code%20Lists/GetCodeList/

## Description

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.

## Parameters

| Name | Type | In | Required | Description |
|---|---|---|---|---|
| `avalara-version` | string | header | Yes | Header that specifies the API version to use (for example "1.6"). |
| `X-Avalara-Client` | string | header | No | Optional header for a client identifier string used for diagnostics (for example "Fingerprint"). |
| `codelistId` | string | path | Yes | System-generated unique identifier of the code list definition. Typically a UUID used to reference this code list internally or via APIs. |
| `countryCode` | string | query | Yes | Two-letter ISO 3166-1 alpha-2 country code indicating the jurisdiction this code list applies to. |
| `effectiveDate` | string | query | No | 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` | string | query | No | 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. |

## Responses

| Status | Description | Schema |
|---|---|---|
| 200 | OK | `CodeListResponse` |
| 400 | Bad request. | `BadRequest` |
| 401 | Unauthorized. |  |
| 403 | Forbidden. | `ForbiddenError` |
| 404 | Code list not found. | `NotFoundError` |

### 200 Response: `CodeListResponse`

Returns a code list definition for a specific country

| Property | Type | Required | Description |
|---|---|---|---|
| `countryCode` | string | No | Two-letter ISO 3166-1 alpha-2 country code indicating the jurisdiction this code list applies to. Example: `FR`. |
| `codeListId` | string | No | System-generated unique identifier of the code list definition. Typically a UUID used to reference this code list internally or via APIs. Example: `ab123343-3432-423c-ac3f-53453scs9999`. |
| `codeListName` | string | No | Human-readable name of the code list, usually describing what the codes represent (for example, document types, tax categories, currencies). Example: `DocumentType`. |
| `description` | string | No | 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. Example: `Code list of document type identifiers for France, based on UN/CEFACT document type codes, with national (local) extensions where applicable.`. |
| `standard` | string | No | 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. Example: `UNCL1001`. |
| `versions` | CodeListVersion[] | No | 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. |

## Example Request

```bash
curl -X GET "https://api.sbx.avalara.com/einvoicing/codelists/{codelistId}" \
  -H "Authorization: Basic <credentials>" \
  -H "Accept: application/json"
```