> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/admin/addresses/create-an-address.md).

# Create an address

Creates an address in the address book of the calling account. The address is always assigned to the calling account: `user` and `email` are set from the account.

* The request is checked against `ADDRESS_PHONE_MIN_LENGTH`, `ADDRESS_DISTRICT_REQUIRED`, `IDENTITY_NUMBER_VALIDATOR`, and the country-specific rules of `ADDRESS_SERIALIZER_FIELDS`, and — when enabled in the server configuration — against `CITY_FILTER_ENABLED` and `USER_MAX_ADDRESS`.
* When phone verification for addresses is enabled in `VERIFICATION_TOKEN_CONF` and `phone_number` differs from the account's phone number, a verification token must be sent in the `X-Verification-Token` header or the `verification_token` field.
* An active address with the same content is rejected with `406` (`address_100_6`). A deleted address with the same content is reactivated and returned with its original `pk`.
* With `USER_MAX_ADDRESS` configured, the request is rejected with `406` (`user_100_3`) only when the account already has more active addresses than the limit, so an account can hold one more address than the configured value.
* `primary: true` clears the primary flag on every other address of the account.
* The operation is rate-limited per account (5 requests per 60 seconds by default, configurable through `THROTTLING_SETTINGS`).

```json
{"openapi":"3.1.0","info":{"title":"Admin API","version":"1.0.0"},"tags":[{"name":"Addresses","description":"Endpoints for **customer addresses** — the delivery and billing addresses kept in the address book of a user account. An address consists of the recipient's name and phone number, its place in the geographic hierarchy (country → city → township → district), a free-text address line, a title such as \"Home\", and optional corporate billing details.\n\n> **Important:** These endpoints are scoped to the **calling account**. Every request only sees and changes the addresses that belong to the user who owns the token. They do not list or manage the addresses of other customers — an address owned by another user is reported as not found. Unlike most endpoints in this reference, administrator privileges are **not** required: any authenticated account can call them, and read requests without credentials succeed with an empty result.\n\n## Core Capabilities\n\n**1. Address Book Listing**\n* Retrieve every active customer address of the calling account in a single response.\n* Retrieve the same data with the related country, city, township, district, retail store, and user expanded into full objects through the `detailed` variants.\n* Order results with the `sort` parameter.\n\n**2. Address Lifecycle**\n* Create an address. An address whose content matches an address the account deleted earlier brings that earlier record back instead of creating a new one.\n* Retrieve or update an address. Changing the content of an address **replaces it with a new record** (see *How Updates Work*).\n* Deactivate an address (soft delete — the record is kept but no longer returned).\n\n**3. Primary Address**\n* Mark an address as the primary one; every other address of the account loses its primary flag.\n\n**4. Delivery Address Selection**\n* Select an address for scheduled delivery through `PATCH /addresses/{id}/set_address/`.\n\n## Address Fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `pk` | integer | The unique identifier of the address. Read-only. |\n| `title` | string (2–128 chars) | A label for the address, for example `Home`. Required. |\n| `first_name` | string (2–30 chars) | The recipient's first name. Required. |\n| `last_name` | string (2–30 chars) | The recipient's last name. Required. |\n| `phone_number` | string | The recipient's phone number. Required. Must be at least `ADDRESS_PHONE_MIN_LENGTH` characters long (11 by default). May require phone verification (see *Phone Number Verification*). |\n| `email` | string | The e-mail address of the address owner. Set to the calling account's e-mail. |\n| `country` | integer | The identifier of the country. Required. |\n| `city` | integer | The identifier of the city. Required. Must belong to `country`. |\n| `township` | integer | The identifier of the township. Required; `null` is not accepted. Must belong to `city`. |\n| `district` | integer or `null` | The identifier of the district. Optional unless `ADDRESS_DISTRICT_REQUIRED` is enabled. Must belong to `township`. |\n| `line` | string (10–255 chars) | The street address. Required. |\n| `postcode` | string (max 64 chars) or `null` | The post/zip code. Optional. |\n| `notes` | string or `null` | Delivery instructions. Optional. |\n| `company_name` | string (max 255 chars) or `null` | The company name for corporate invoices. Optional. |\n| `tax_office` | string (max 64 chars) or `null` | The tax office for corporate invoices. Optional. |\n| `tax_no` | string (max 20 chars) or `null` | The tax number for corporate invoices. Optional. |\n| `e_bill_taxpayer` | boolean | Whether the owner is registered for electronic invoicing. Defaults to `false`. |\n| `identity_number` | string or `null` | The national identity number of the recipient. Optional. Checked according to `IDENTITY_NUMBER_VALIDATOR`. |\n| `address_type` | string | `customer`, `retail_store`, `pickup_location`, or `checkout_provider`. Defaults to `customer`. Only `customer` addresses are returned by these endpoints: an address created with another type is saved, but it is not listed and reading it by identifier returns `404`. |\n| `retail_store` | integer or `null` | The identifier of a related retail store. Optional. |\n| `remote_id` | string (max 1024 chars) or `null` | The identifier of the address in an external system. Optional. |\n| `user` | integer or `null` | The identifier of the owning user. Set to the calling account. |\n| `primary` | boolean | Whether this is the primary address of the account. Sending `true` makes the address primary and clears the flag on every other address of the account. To change the primary address, mark another address as primary. |\n| `is_corporate` | boolean | `true` when any of `company_name`, `tax_office`, `tax_no`, or `e_bill_taxpayer` is set. Read-only. |\n| `hash_data` | string | A fingerprint of the address content, used to detect duplicates. Read-only. |\n| `extra_field` | object or `null` | The values of the country-specific extra fields configured through `ADDRESS_SERIALIZER_FIELDS`, keyed by field name. `null` when no such value is stored. Read-only: extra fields are sent as top-level request fields, not inside this object. |\n\n## Validation Rules\n\n* `city` must belong to `country`, `township` to `city`, and `district` to `township`. A mismatch is rejected with `400 Bad Request` and a message under `non_field_errors`; only the first mismatch is reported.\n* Minimum lengths are enforced on `title` (2), `first_name` (2), `last_name` (2), `line` (10), and `phone_number` (`ADDRESS_PHONE_MIN_LENGTH`).\n* Countries can require additional fields, change the rules of existing fields, or attach extra validators through `ADDRESS_SERIALIZER_FIELDS`.\n\n## Duplicate Detection\n\nEach address carries a fingerprint (`hash_data`) calculated from the owner and its content fields: `email`, `phone_number`, `first_name`, `last_name`, `country`, `city`, `township`, `district`, `line`, `title`, `postcode`, `notes`, `company_name`, `tax_office`, `tax_no`, `e_bill_taxpayer`, `identity_number`, and the country-specific extra fields. `address_type`, `retail_store`, `remote_id`, and `primary` are **not** part of the fingerprint.\n\n* Creating an address whose fingerprint matches an **active** address of the account is rejected with `406 Not Acceptable` and error code `address_100_6`.\n* Creating an address whose fingerprint matches a **deactivated** address brings that address back: it is reactivated and returned with its original `pk`.\n\n## How Updates Work\n\n* When an update changes the fingerprint, the current record is deactivated and the new content is saved as a **different record with a new `pk`**. If the new content matches an address the account deleted earlier, that earlier record is reactivated and returned instead. If it matches another **active** address of the account, that address is returned and the updated address is deactivated. Always use the `pk` from the response for later requests.\n* When an update leaves the fingerprint unchanged, the record keeps its `pk`.\n* `primary` is not part of the fingerprint, so an update that changes only `primary` marks the address as primary without creating a new record.\n\n## Soft Delete\n\n`DELETE /addresses/{id}/` does **not** remove the record. It deactivates the address and clears its primary flag. The address is no longer listed and reading it by identifier returns `404`. Creating an address with the same content later reactivates it.\n\n## Listing, Filtering & Ordering\n\n* The list is **not paginated**: every matching address is returned in one response, inside the usual `count` / `next` / `previous` / `results` envelope. `next` and `previous` are always `null`; `page` and `limit` are ignored.\n* No filter parameters are supported; other query parameters are ignored.\n* Results are ordered with the primary address first, then by last modification, newest first. `sort` accepts the address fields stored in the database — for example `pk`, `title`, `first_name`, `last_name`, `city`, `primary` — optionally prefixed with `-`. Unknown field names are ignored.\n* When the calling account is a guest account, the list contains only its most recently created address.\n\n## Phone Number Verification\n\nWhen phone verification for addresses is enabled (the `address-phone` block of `VERIFICATION_TOKEN_CONF`), saving an address whose `phone_number` differs from the phone number of the calling account requires registered (non-guest) accounts to prove that they control the entered number:\n\n1. Request and confirm a one-time code for the entered phone number through the verification endpoints. The code is sent by SMS to the entered number, and a verification token is returned.\n2. Send the token with the create or update request, either in the `X-Verification-Token` header or in a `verification_token` body field.\n\nWithout a valid token the request is rejected with `400 Bad Request` and an error under `verification_token`. The token can be used only once; it is consumed after the address is saved. No verification is needed when the phone number matches the account's phone number or when the feature is disabled (default).\n\n## Rate Limiting\n\nAddress creation (`POST /addresses/`) is rate-limited; reads, updates, and deletions are not.\n\n* By default each account may create **5 addresses per 60 seconds**. The limit can be changed through the `create-address` entry of `THROTTLING_SETTINGS`.\n* Requests over the limit are rejected with `429 Too Many Requests`. The first request over the limit is let through once; the caller's session and IP address are then flagged, and no further request is let through while the flag is active. The IP address flag lasts for `SECURITYCOP_IP_BAN_TIMEOUT` (6 hours by default).\n* Optional nested windows (`windows`) add stricter caps per IP address across all accounts. No request over these caps is let through.\n\n## Dynamic Settings & Environment Variables\n\nThe following dynamic settings (`dj_dynamic_settings`) change the behaviour of these endpoints. Changes made in the management panel are picked up by every server process within about a minute.\n\n| Key | Type & Constraints | Default | Effect | Affected operations |\n|-----|--------------------|---------|--------|---------------------|\n| `ADDRESS_PHONE_MIN_LENGTH` | integer | `11` | The minimum length of `phone_number`. Shorter values are rejected with `400` and an error under `phone_number`. | Create, update. |\n| `ADDRESS_DISTRICT_REQUIRED` | boolean | `false` | When `true`, `district` is required and cannot be `null`. When `false`, `district` is optional and may be `null`. | Create, update. |\n| `IDENTITY_NUMBER_VALIDATOR` | one of `omnicore.address.validators.null_identity_validator` (no validation) or `omnicore.address.validators.tc_identity_number_validator` (Turkish Republic identity number) | `omnicore.address.validators.null_identity_validator` | How `identity_number` is checked. With the Turkish validator the value must be an 11-digit number that does not start with `0` and passes the checksum; otherwise it is rejected with `400` and an error under `identity_number`. | Create, update. |\n| `ADDRESS_SERIALIZER_FIELDS` | object keyed by country code (for example `TR`) plus a `default` key; each value is a list of entries `{\"field\": string, \"validators\": [{\"klass\": string, \"kwargs\": object}], \"kwargs\": object}`. `field` and `validators` are required in every entry (`validators` may be an empty list); `klass` and `kwargs` are required in every validator. A missing `default` key is added as an empty list. | `{\"default\": []}` | Country-specific field rules. The entries for the address's country apply; when the country has no entry, the `default` entries apply. For a field that already exists, `kwargs` changes its rules (for example `{\"required\": true}` or `{\"max_length\": 20}`) and each validator is added to it; `kwargs` has no effect on `phone_number`, `identity_number`, and `address_type`, although their validators still apply. A field name that does not exist becomes an **extra field**: it is accepted as a top-level string field, is **required unless `kwargs` contains `\"required\": false`**, is not returned at the top level, and is stored inside `extra_field`. Extra fields are part of the duplicate fingerprint, so changing one creates a new record. | Create, update. |\n| `THROTTLING_SETTINGS` | object; the `create-address` entry is `{\"count\": integer, \"duration\": seconds}`, optionally with `\"windows\": [[seconds, max_count], ...]` | No `create-address` entry (the built-in limit of 5 per 60 seconds applies) | Changes the address creation limit (see *Rate Limiting*). | Create. |\n| `SECURITYCOP_IP_BAN_TIMEOUT` | integer (seconds) | `21600` (6 hours) | How long an IP address stays flagged after it exceeded the address creation limit (see *Rate Limiting*). | Create. |\n| `VERIFICATION_TOKEN_CONF` | object keyed by `default` or a verification purpose; each block accepts only `enabled` (boolean), `allowed_channels` (list), `token_ttl_seconds` (integer ≥ 1), and `recaptcha_required` (boolean) | `{\"default\": {\"enabled\": false}}` | When the `address-phone` block has `\"enabled\": true`, saving an address with a phone number that differs from the account's phone number requires a verification token (see *Phone Number Verification*). The `default` block alone never enables it. | Create, update. |\n\nThe following Django settings are configured per deployment in the server configuration. They cannot be changed from the management panel, and no environment variable sets them.\n\n| Setting | Type | Default | Effect | Affected operations |\n|---------|------|---------|--------|---------------------|\n| `USER_MAX_ADDRESS` | integer | Not set (no limit) | The limit on active addresses per account. The check runs before a new address is saved and rejects the request only when the account **already has more than** this number of active addresses; an account can therefore reach **one more address than the configured value**. For example, with `USER_MAX_ADDRESS = 2` the third address is accepted and the fourth is rejected. Rejected requests return `406 Not Acceptable` with error code `user_100_3`. All active addresses of the account are counted, whatever their `address_type`. `0` or not set means no limit. | Create (including the reactivation of a deleted address). Updates are not checked. |\n| `CITY_FILTER_ENABLED` | boolean | Not set (`false`) | When `true` and the calling account has a city stored in its attributes, the address `city` must be that city; otherwise the request is rejected with `400` and an error under `city`. Accounts without a stored city are not restricted. | Create, update. |\n| `SCHEDULED_DELIVERY_CONF` | object | Scheduled delivery inactive | Scheduled delivery is inactive unless the deployment enables it in its server configuration. While it is active, selecting an address with `set_address`, creating the first address of an account, updating an address, and deleting an address also remove the items that are no longer available from the basket of the calling account. The address records are not changed by this. While it is inactive (default), `set_address` changes nothing and these side effects do not happen. | Set address, create, update, delete. |\n\n**Environment variables:** No environment variables are read by these endpoints.\n\n**Settings that do not affect these endpoints:** `DEFAULT_COUNTRY_CODE`, `DEFAULT_SHIPPING_COST`, `IDENTITY_NUMBER_REQUIRED_AMOUNT`, `PICKUP_LOCATION_PROVIDER`, `PICKUP_LOCATION_PROVIDER_BASE_URL`, `REMOTE_DELIVERY_OPTION_PROVIDER`, and `CHECKOUT_DELIVERY_OPTION_SELECTION_PAGE` are registered by the address module but are used by checkout and storefront flows. `ANONYMOUS_ADDRESS_EXPIRE_SECONDS` applies only to addresses created without an account and has no effect on token-authenticated calls."}],"servers":[{"description":"Omnitron Remote Proxy (external access — recommended)","url":"https://{omnitron_url}/api/v1/remote/{channel_id}","variables":{"omnitron_url":{"default":"sandbox.akinon.com","description":"Omnitron server URL (e.g., {omnitron.akinon.com})"},"channel_id":{"default":"1","description":"The channel identifier the remote request is routed through"}}},{"description":"Commerce API Server (internal / direct access only)","url":"https://{commerce_url}/api/v1","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Internal commerce server URL, reachable only from within the Omnitron network"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"Token credential sent in the Authorization header, in the form: `Token <your-token>`. Requires a staff (admin) account."}},"schemas":{"AddressRequest":{"type":"object","description":"The body of a create or full update request.\n\nThe address is always assigned to the calling account: `email` and `user` are set from the account. Additional fields may be required, or extra fields accepted, according to the country-specific rules configured in `ADDRESS_SERIALIZER_FIELDS`; extra fields are sent as top-level string properties. When phone verification is enabled, `verification_token` may be sent here instead of in the `X-Verification-Token` header.","required":["title","first_name","last_name","phone_number","country","city","township","line"],"properties":{"title":{"type":"string","minLength":2,"maxLength":128,"description":"A label for the address."},"first_name":{"type":"string","minLength":2,"maxLength":30,"description":"The recipient's first name."},"last_name":{"type":"string","minLength":2,"maxLength":30,"description":"The recipient's last name."},"phone_number":{"type":"string","description":"The recipient's phone number. Must be at least `ADDRESS_PHONE_MIN_LENGTH` characters long (11 by default)."},"country":{"type":"integer","description":"The identifier of an existing country."},"city":{"type":"integer","description":"The identifier of an existing city of `country`."},"township":{"type":"integer","description":"The identifier of an existing township of `city`. `null` is not accepted."},"district":{"type":["integer","null"],"description":"The identifier of an existing district of `township`. Required and not nullable when `ADDRESS_DISTRICT_REQUIRED` is enabled."},"line":{"type":"string","minLength":10,"maxLength":255,"description":"The street address."},"postcode":{"type":["string","null"],"maxLength":64,"description":"The post/zip code."},"notes":{"type":["string","null"],"description":"Delivery instructions."},"company_name":{"type":["string","null"],"maxLength":255,"description":"The company name for corporate invoices."},"tax_office":{"type":["string","null"],"maxLength":64,"description":"The tax office for corporate invoices."},"tax_no":{"type":["string","null"],"maxLength":20,"description":"The tax number for corporate invoices."},"e_bill_taxpayer":{"type":"boolean","default":false,"description":"Whether the owner is registered for electronic invoicing."},"identity_number":{"type":["string","null"],"description":"The national identity number of the recipient, checked according to `IDENTITY_NUMBER_VALIDATOR`."},"address_type":{"$ref":"#/components/schemas/AddressType"},"retail_store":{"type":["integer","null"],"description":"The identifier of an existing retail store."},"remote_id":{"type":["string","null"],"maxLength":1024,"description":"The identifier of the address in an external system."},"primary":{"type":"boolean","default":false,"description":"`true` makes this the primary address and clears the flag on every other address of the account. On update, `false` removes the flag and omitting the field keeps it."},"verification_token":{"type":"string","description":"A phone verification token for `phone_number`. Needed only when phone verification is enabled and `phone_number` differs from the account's phone number."}},"additionalProperties":{"type":"string","description":"A country-specific extra field configured through `ADDRESS_SERIALIZER_FIELDS`."}},"AddressType":{"type":"string","description":"The kind of address. Only `customer` addresses are returned by the address endpoints.\n\n* `customer` — a delivery or billing address of a customer (default).\n* `retail_store` — the address of a retail store.\n* `pickup_location` — the address of a pickup point.\n* `checkout_provider` — an address supplied by an external checkout provider.","enum":["customer","retail_store","pickup_location","checkout_provider"]},"Address":{"type":"object","description":"A customer address as returned by the address endpoints.","properties":{"pk":{"type":"integer","description":"The unique identifier of the address.","readOnly":true},"email":{"type":"string","format":"email","description":"The e-mail address of the owning account."},"phone_number":{"type":"string","description":"The recipient's phone number."},"first_name":{"type":"string","description":"The recipient's first name."},"last_name":{"type":"string","description":"The recipient's last name."},"country":{"type":"integer","description":"The identifier of the country."},"city":{"type":"integer","description":"The identifier of the city."},"township":{"type":"integer","description":"The identifier of the township."},"district":{"type":["integer","null"],"description":"The identifier of the district, or `null`."},"line":{"type":"string","description":"The street address."},"title":{"type":"string","description":"The label of the address."},"postcode":{"type":["string","null"],"description":"The post/zip code."},"notes":{"type":["string","null"],"description":"Delivery instructions."},"company_name":{"type":["string","null"],"description":"The company name for corporate invoices."},"tax_office":{"type":["string","null"],"description":"The tax office for corporate invoices."},"tax_no":{"type":["string","null"],"description":"The tax number for corporate invoices."},"e_bill_taxpayer":{"type":"boolean","description":"Whether the owner is registered for electronic invoicing."},"hash_data":{"type":"string","description":"The fingerprint of the address content, used to detect duplicates.","readOnly":true},"address_type":{"$ref":"#/components/schemas/AddressType"},"retail_store":{"type":["integer","null"],"description":"The identifier of the related retail store, or `null`."},"remote_id":{"type":["string","null"],"description":"The identifier of the address in an external system."},"identity_number":{"type":["string","null"],"description":"The national identity number of the recipient."},"extra_field":{"type":["object","null"],"description":"The values of the country-specific extra fields, keyed by field name, or `null` when none is stored.","readOnly":true,"additionalProperties":{"type":"string"}},"user":{"type":["integer","null"],"description":"The identifier of the owning user."},"is_corporate":{"type":"boolean","description":"`true` when any corporate invoice field (`company_name`, `tax_office`, `tax_no`, `e_bill_taxpayer`) is set.","readOnly":true},"primary":{"type":"boolean","description":"Whether this is the primary address of the account."}}},"ValidationError":{"type":"object","description":"Returned when the request contains invalid or missing data. Errors are grouped by the field they apply to: each key is the name of a field from the request and its value is a list of one or more messages describing what is wrong with that field. Messages that do not belong to any single field are grouped under `non_field_errors`.","properties":{"non_field_errors":{"type":"array","description":"Error messages that apply to the request as a whole rather than to a specific field.","items":{"type":"string"}}},"additionalProperties":{"type":"array","description":"The list of error messages for the field named by the key.","items":{"type":"string"}}},"Error":{"type":"object","description":"An error response.","properties":{"detail":{"type":"string","description":"A human-readable description of the error."}},"additionalProperties":true},"AddressBusinessError":{"type":"object","description":"Returned when an address request is valid in form but violates an address rule.\n\nCodes raised by these endpoints:\n* `address_100_6` — an active address with the same content already exists for the account.\n* `user_100_3` — the account has more active addresses than `USER_MAX_ADDRESS` allows.","properties":{"error_code":{"type":"string","description":"The machine-readable error identifier."},"non_field_errors":{"type":"string","description":"A human-readable error message, translated into the active language. The example shows the English text."}}}},"responses":{"AddressValidationError":{"description":"The request contains invalid or missing data — for example a missing required field, a value shorter than its minimum length, a city that does not belong to the country, an identity number rejected by the configured validator, or a missing or invalid phone verification token (reported under `verification_token`). The response names the field each complaint belongs to; mismatches in the geographic hierarchy are reported under `non_field_errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"Unauthorized":{"description":"Authentication credentials were not provided or are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"AddressBusinessError":{"description":"The request is well-formed but violates an address rule — an active address with the same content already exists, or the account has exceeded the configured address limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressBusinessError"}}}},"AddressTooManyRequests":{"description":"The address creation limit of the calling account (or of the caller's IP address, when nested windows are configured) was exceeded. `detail` carries a human-readable message that states how many seconds to wait, translated into the active language. The example shows the English text.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/addresses/":{"post":{"tags":["Addresses"],"operationId":"createAddress","summary":"Create an address","description":"Creates an address in the address book of the calling account. The address is always assigned to the calling account: `user` and `email` are set from the account.\n\n* The request is checked against `ADDRESS_PHONE_MIN_LENGTH`, `ADDRESS_DISTRICT_REQUIRED`, `IDENTITY_NUMBER_VALIDATOR`, and the country-specific rules of `ADDRESS_SERIALIZER_FIELDS`, and — when enabled in the server configuration — against `CITY_FILTER_ENABLED` and `USER_MAX_ADDRESS`.\n* When phone verification for addresses is enabled in `VERIFICATION_TOKEN_CONF` and `phone_number` differs from the account's phone number, a verification token must be sent in the `X-Verification-Token` header or the `verification_token` field.\n* An active address with the same content is rejected with `406` (`address_100_6`). A deleted address with the same content is reactivated and returned with its original `pk`.\n* With `USER_MAX_ADDRESS` configured, the request is rejected with `406` (`user_100_3`) only when the account already has more active addresses than the limit, so an account can hold one more address than the configured value.\n* `primary: true` clears the primary flag on every other address of the account.\n* The operation is rate-limited per account (5 requests per 60 seconds by default, configurable through `THROTTLING_SETTINGS`).","parameters":[{"name":"X-Verification-Token","in":"header","required":false,"description":"The phone verification token for `phone_number`. Needed only when phone verification for addresses is enabled and `phone_number` differs from the account's phone number.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressRequest"}}}},"responses":{"201":{"description":"The created — or reactivated — address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Address"}}}},"400":{"$ref":"#/components/responses/AddressValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"},"406":{"$ref":"#/components/responses/AddressBusinessError"},"429":{"$ref":"#/components/responses/AddressTooManyRequests"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://apidocs.akinon.com/commerce-openapis/admin/addresses/create-an-address.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
