Address API - Address Books

Overview

The Address Book API allows you to manage user addresses efficiently. It provides endpoints to create, read, update, and delete addresses associated with a user's account.

Address Book Id is a unique identifier for each address book. It can be user id or any other unique string that identifies the address book.

Here is an example of how the Ingrid Checkout Widget displays the Address Book feature, allowing users to select from their saved addresses during checkout:

Ingrid Checkout Widget - Address Book

List Addresses in Address Book

List all addresses stored in a specific address book. Used to retrieve all addresses associated with a customer to:

Display saved addresses during checkout
Manage addresses in user profile settings
Facilitate quick address selection for future orders
Enhance user experience by providing easy access to frequently used addresses

curl https://api-stage.ingrid.com/address/v1/address_books/8cad4fce-06ae-4aaf-8eea-82cebbb301a5/contacts \
-X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $PRIVATE_KEY_BASE64"

GET https://api-stage.ingrid.com/address/v1/address_books/8cad4fce-06ae-4aaf-8eea-82cebbb301a5/contacts
Authorization: Bearer $PRIVATE_KEY_BASE64
Content-Type: application/json

{
  "id": "8cad4fce-06ae-4aaf-8eea-82cebbb301a5",
  "contacts": [
    {
      "id": "b04c8dea-e311-40d0-9b24-fdb786d7cc3a",
      "address": {
        "country_code": "SE",
        "postal_code": "113 51",
        "city": "Stockholm",
        "address_lines": [
          "Roslagsgatan 10"
        ],
        "street": "Roslagsgatan",
        "street_number": "10"
      },
      "email": "sven.nilsson@example.com",
      "phone_number": {
        "country_code": "SE",
        "number": "+46 70 123 45 67"
      },
      "first_name": "Sven",
      "last_name": "Nilsson"
    },
    {
      "id": "c1f5d3e2-5f4b-4e2a-9f7e-2d3b6c9f8a1b",
      "address": {
        "country_code": "SE",
        "postal_code": "411 22",
        "city": "Göteborg",
        "address_lines": [
          "Storgatan 5A"
        ],
        "street": "Storgatan",
        "street_number": "5A"
      },
      "email": "sven.nilsson@example.com",
      "phone_number": {
        "country_code": "SE",
        "number": "+46 70 123 45 67"
      },
      "first_name": "Sven",
      "last_name": "Nilsson"
    }
  ]
}

Create Address in Address Book

Create a new address in a specific address book. Used to add new addresses for a customer to:

Save new shipping or billing addresses during checkout
Allow users to manage their addresses in profile settings
Facilitate future orders by storing frequently used addresses

curl https://api-stage.ingrid.com/address/v1/address_books/8cad4fce-06ae-4aaf-8eea-82cebbb301a5/contacts \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $PRIVATE_KEY_BASE64" \
-d '{
    "address": {
      "country_code": "SE",
      "postal_code": "113 51",
      "city": "Stockholm",
      "address_lines": [
        "Roslagsgatan 10"
      ],
      "street": "Roslagsgatan",
      "street_number": "10"
    },
    "email": "sven.nilsson@example.com",
    "phone_number": {
      "country_code": "SE",
      "number": "+46 70 123 45 67"
    },
    "first_name": "Sven",
    "last_name": "Nilsson"
  }'

POST https://api-stage.ingrid.com/address/v1/address_books/8cad4fce-06ae-4aaf-8eea-82cebbb301a5/contacts
Authorization: Bearer $PRIVATE_KEY_BASE64
Content-Type: application/json

{
    "address": {
        "country_code": "SE",
        "postal_code": "113 51",
        "city": "Stockholm",
        "address_lines": [
            "Roslagsgatan 10"
        ],
        "street": "Roslagsgatan",
        "street_number": "10"
    },
    "email": "sven.nilsson@example.com",
    "phone_number": {
        "country_code": "SE",
        "number": "+46 70 123 45 67"
    },
    "first_name": "Sven",
    "last_name": "Nilsson"
}

{
  "id": "913c4417-f5f9-42e0-b9a5-fc8298c4fe33",
  "address": {
    "country_code": "SE",
    "postal_code": "113 51",
    "city": "Stockholm",
    "address_lines": [
      "Roslagsgatan 10"
    ],
    "street": "Roslagsgatan",
    "street_number": "10"
  },
  "email": "sven.nilsson@example.com",
  "phone_number": {
    "country_code": "SE",
    "number": "+46 70 123 45 67"
  },
  "first_name": "Sven",
  "last_name": "Nilsson"
}

Address Deduplication when Creating Address

When creating a new address, the system checks for existing addresses in the address book to prevent duplicates.

When a duplicate address is detected (based on matching key fields such as street, city, postal code, and country), the system will not create a new entry. Instead, it will return an error response indicating that the address already exists.

{
  "error": "creation would duplicate contact ID 913c4417-f5f9-42e0-b9a5-fc8298c4fe33",
  "trace_id": "D20260128110812X87QEWJD33FXNB9Y"
}

Update Address in Address Book

Update an existing address in a specific address book. Used to modify saved addresses for a customer to:

Update shipping or billing addresses during checkout
Allow users to edit their addresses in profile settings
Ensure accurate delivery information for future orders

curl https://api-stage.ingrid.com/address/v1/address_books/8cad4fce-06ae-4aaf-8eea-82cebbb301a5/contacts/913c4417-f5f9-42e0-b9a5-fc8298c4fe33 \
-X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $PRIVATE_KEY_BASE64" \
-d '{
    "address": {
      "country_code": "SE",
      "postal_code": "113 51",
      "city": "Stockholm",
      "address_lines": [
        "Roslagsgatan 11"
      ],
      "street": "Roslagsgatan",
      "street_number": "11"
    },
    "email": "sven.nilsson@example.com",
    "phone_number": {
      "country_code": "SE",
      "number": "+46 70 123 45 67"
    },
    "first_name": "Sven",
    "last_name": "Nilsson"
  }'

PATCH https://api-stage.ingrid.com/address/v1/address_books/8cad4fce-06ae-4aaf-8eea-82cebbb301a5/contacts/913c4417-f5f9-42e0-b9a5-fc8298c4fe33
Authorization: Bearer $PRIVATE_KEY_BASE64
Content-Type: application/json

{
    "address": {
        "country_code": "SE",
        "postal_code": "113 51",
        "city": "Stockholm",
        "address_lines": [
            "Roslagsgatan 11"
        ],
        "street": "Roslagsgatan",
        "street_number": "11"
    },
    "email": "sven.nilsson@example.com",
    "phone_number": {
        "country_code": "SE",
        "number": "+46 70 123 45 67"
    },
    "first_name": "Sven",
    "last_name": "Nilsson"
}

{
  "id": "913c4417-f5f9-42e0-b9a5-fc8298c4fe33",
  "address": {
    "country_code": "SE",
    "postal_code": "113 51",
    "city": "Stockholm",
    "address_lines": [
      "Roslagsgatan 11"
    ],
    "street": "Roslagsgatan",
    "street_number": "11"
  },
  "email": "sven.nilsson@example.com",
  "phone_number": {
    "country_code": "SE",
    "number": "+46 70 123 45 67"
  },
  "first_name": "Sven",
  "last_name": "Nilsson"
}

Delete Address from Address Book

Delete an existing address from a specific address book. Used to remove saved addresses for a customer to:

Delete outdated or incorrect addresses during checkout
Allow users to manage their addresses in profile settings
Maintain an up-to-date list of addresses for future orders

curl https://api-stage.ingrid.com/address/v1/address_books/8cad4fce-06ae-4aaf-8eea-82cebbb301a5/contacts/913c4417-f5f9-42e0-b9a5-fc8298c4fe33 \
-X 'DELETE' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $PRIVATE_KEY_BASE64"

DELETE https://api-stage.ingrid.com/address/v1/address_books/8cad4fce-06ae-4aaf-8eea-82cebbb301a5/contacts/913c4417-f5f9-42e0-b9a5-fc8298c4fe33
Authorization: Bearer $PRIVATE_KEY_BASE64
Content-Type: application/json

{}

Last updated: Thu, Feb 12, 06:59 AM