Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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).

post
/addresses/
Authorizations
AuthorizationstringRequired

Token credential sent in the Authorization header, in the form: Token <your-token>. Requires a staff (admin) account.

Header parameters
X-Verification-TokenstringOptional

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.

Body

The body of a create or full update request.

The 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.

titlestring · min: 2 · max: 128Required

A label for the address.

Example: Home
first_namestring · min: 2 · max: 30Required

The recipient's first name.

Example: Jane
last_namestring · min: 2 · max: 30Required

The recipient's last name.

Example: Doe
phone_numberstringRequired

The recipient's phone number. Must be at least ADDRESS_PHONE_MIN_LENGTH characters long (11 by default).

Example: 05551234567
countryintegerRequired

The identifier of an existing country.

Example: 1
cityintegerRequired

The identifier of an existing city of country.

Example: 34
townshipintegerRequired

The identifier of an existing township of city. null is not accepted.

Example: 410
districtinteger · nullableOptional

The identifier of an existing district of township. Required and not nullable when ADDRESS_DISTRICT_REQUIRED is enabled.

Example: 5123
linestring · min: 10 · max: 255Required

The street address.

Example: Example Street No 12 Flat 3
postcodestring · max: 64 · nullableOptional

The post/zip code.

notesstring · nullableOptional

Delivery instructions.

company_namestring · max: 255 · nullableOptional

The company name for corporate invoices.

tax_officestring · max: 64 · nullableOptional

The tax office for corporate invoices.

tax_nostring · max: 20 · nullableOptional

The tax number for corporate invoices.

e_bill_taxpayerbooleanOptional

Whether the owner is registered for electronic invoicing.

Default: false
identity_numberstring · nullableOptional

The national identity number of the recipient, checked according to IDENTITY_NUMBER_VALIDATOR.

address_typestring · enumOptional

The kind of address. Only customer addresses are returned by the address endpoints.

  • customer — a delivery or billing address of a customer (default).
  • retail_store — the address of a retail store.
  • pickup_location — the address of a pickup point.
  • checkout_provider — an address supplied by an external checkout provider.
Possible values:
retail_storeinteger · nullableOptional

The identifier of an existing retail store.

remote_idstring · max: 1024 · nullableOptional

The identifier of the address in an external system.

primarybooleanOptional

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.

Default: false
verification_tokenstringOptional

A phone verification token for phone_number. Needed only when phone verification is enabled and phone_number differs from the account's phone number.

Other propertiesstringOptional

A country-specific extra field configured through ADDRESS_SERIALIZER_FIELDS.

Responses
201

The created — or reactivated — address.

application/json

A customer address as returned by the address endpoints.

pkintegerRead-onlyOptional

The unique identifier of the address.

Example: 42
emailstring · emailOptional

The e-mail address of the owning account.

Example: jane.doe@example.com
phone_numberstringOptional

The recipient's phone number.

Example: 05551234567
first_namestringOptional

The recipient's first name.

Example: Jane
last_namestringOptional

The recipient's last name.

Example: Doe
countryintegerOptional

The identifier of the country.

Example: 1
cityintegerOptional

The identifier of the city.

Example: 34
townshipintegerOptional

The identifier of the township.

Example: 410
districtinteger · nullableOptional

The identifier of the district, or null.

Example: 5123
linestringOptional

The street address.

Example: Example Street No 12 Flat 3
titlestringOptional

The label of the address.

Example: Home
postcodestring · nullableOptional

The post/zip code.

Example: 34710
notesstring · nullableOptional

Delivery instructions.

Example: Ring the bell twice.
company_namestring · nullableOptional

The company name for corporate invoices.

tax_officestring · nullableOptional

The tax office for corporate invoices.

tax_nostring · nullableOptional

The tax number for corporate invoices.

e_bill_taxpayerbooleanOptional

Whether the owner is registered for electronic invoicing.

Example: false
hash_datastringRead-onlyOptional

The fingerprint of the address content, used to detect duplicates.

Example: 3f1c2a9b8e7d6c5b4a39281706f5e4d3
address_typestring · enumOptional

The kind of address. Only customer addresses are returned by the address endpoints.

  • customer — a delivery or billing address of a customer (default).
  • retail_store — the address of a retail store.
  • pickup_location — the address of a pickup point.
  • checkout_provider — an address supplied by an external checkout provider.
Possible values:
retail_storeinteger · nullableOptional

The identifier of the related retail store, or null.

remote_idstring · nullableOptional

The identifier of the address in an external system.

identity_numberstring · nullableOptional

The national identity number of the recipient.

extra_fieldobject · nullableRead-onlyOptional

The values of the country-specific extra fields, keyed by field name, or null when none is stored.

userinteger · nullableOptional

The identifier of the owning user.

Example: 7
is_corporatebooleanRead-onlyOptional

true when any corporate invoice field (company_name, tax_office, tax_no, e_bill_taxpayer) is set.

Example: false
primarybooleanOptional

Whether this is the primary address of the account.

Example: true
post/addresses/
POST /api/v1/remote/1/addresses/ HTTP/1.1
Host: sandbox.akinon.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 207

{
  "title": "Home",
  "first_name": "Jane",
  "last_name": "Doe",
  "phone_number": "05551234567",
  "country": 1,
  "city": 34,
  "township": 410,
  "district": 5123,
  "line": "Example Street No 12 Flat 3",
  "postcode": "34710",
  "primary": true
}
{
  "pk": 42,
  "email": "jane.doe@example.com",
  "phone_number": "05551234567",
  "first_name": "Jane",
  "last_name": "Doe",
  "country": 1,
  "city": 34,
  "township": 410,
  "district": 5123,
  "line": "Example Street No 12 Flat 3",
  "title": "Home",
  "postcode": "34710",
  "notes": "Ring the bell twice.",
  "company_name": null,
  "tax_office": null,
  "tax_no": null,
  "e_bill_taxpayer": false,
  "hash_data": "3f1c2a9b8e7d6c5b4a39281706f5e4d3",
  "address_type": "customer",
  "retail_store": null,
  "remote_id": null,
  "identity_number": null,
  "extra_field": null,
  "user": 7,
  "is_corporate": false,
  "primary": true
}

Last updated

Was this helpful?