> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.noyax.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Definitions

> Finding the IDs (district, currency, group, ...) used when creating records.

Records such as customers, products or invoices expect the **ID** of a record defined in Noyax in some fields instead of free text. For example, an address takes a `DistrictId`, not a district name. You get these IDs from the definition endpoints.

## Which ID comes from where?

| Field                   | Used in                    | Endpoint                                                                                          |
| ----------------------- | -------------------------- | ------------------------------------------------------------------------------------------------- |
| `DistrictId`            | Customer addresses         | [`GET /definitions/districts`](/en/v1/definitions/districts/list)                                 |
| `CurrencyId`            | Customer bank accounts     | [`GET /definitions/currencies`](/en/v1/definitions/currencies/list)                               |
| `ShipmentDefinitionId`  | Customer                   | [`GET /definitions/shipment-definitions`](/en/v1/definitions/shipment-definitions/list)           |
| `GroupDetailId`         | Customer group memberships | [`GET /customers/groups`](/en/v1/customers/definitions/groups)                                    |
| `ParameterDefinitionId` | Customer parameters        | [`GET /customers/parameter-definitions`](/en/v1/customers/definitions/parameter-definitions/list) |

Country and city lists help you find a district: [country](/en/v1/definitions/countries/list) → [city](/en/v1/definitions/cities/list) (`countryId`) → [district](/en/v1/definitions/districts/list) (`cityId`).

## Example: finding a district for an address

<Steps>
  <Step title="Find the city">
    ```bash theme={null}
    curl "https://api.noyax.com/api/v1/definitions/cities" \
      -H "Authorization: Bearer ACCESS_TOKEN" -H "X-UserID: 12" -H "X-CompanyID: 3"
    ```
  </Step>

  <Step title="Find the district">
    ```bash theme={null}
    curl "https://api.noyax.com/api/v1/definitions/districts?cityId=CITY_ID&search=Kadıköy" \
      -H "Authorization: Bearer ACCESS_TOKEN" -H "X-UserID: 12" -H "X-CompanyID: 3"
    ```
  </Step>

  <Step title="Use it in the address">
    Put the `Id` of the district into the `DistrictId` field of the address.
  </Step>
</Steps>

## Good to know

* **Definitions are company-specific.** Lists return the records of the company sent in `X-CompanyID`. An ID of one company cannot be used in another company.
* **Permissions:** lists under `/definitions` can be read with any valid API key. Creating, updating or deleting countries, cities, districts and shipment definitions requires the key to have **write permission in any module**. Customer definitions (`/customers/groups`, `/customers/parameter-definitions`) require the customer read permission.
* **Cache them.** Definitions rarely change. Instead of querying before every record, store them on your side and refresh, for example, once a day. This saves your [daily request limit](/en/v1/guides/rate-limits).

## Write rules

| Definition                                                            | Required                                                                               | Unique                       | Cannot be deleted if                    |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ---------------------------- | --------------------------------------- |
| [Country](/en/v1/definitions/countries/create)                        | `Name`                                                                                 | Name in the company          | It has cities                           |
| [City](/en/v1/definitions/cities/create)                              | `CountryId`, `Name`                                                                    | Name in the country          | It has districts                        |
| [District](/en/v1/definitions/districts/create)                       | `CityId`, `Name`                                                                       | Name in the city             | It is used in a customer address        |
| [Unit](/en/v1/definitions/units/create)                               | `Name`                                                                                 | Name in the company          | It is the main unit of a product        |
| [Currency](/en/v1/definitions/currencies/create)                      | `Name`, `Code`                                                                         | Name and code in the company | It is the default or used in any record |
| [Shipment definition](/en/v1/definitions/shipment-definitions/create) | `Code`, `TransportMode` (1-4), `TransportInfo1`; carrier company or driver information | Code in the company          | It is used by a customer                |

VAT rates and customer definitions are read-only through the API. Updates are full replaces; fields you do not send are cleared.