Skip to main content

Import Addresses

Addresses in Propeller belong to companies or customers. There are two ways to import them: inline as part of a company or customer bulk payload, or through dedicated address endpoints that target a specific company or customer.

The inline approach is the most common. It lets you send addresses together with the company or customer data. This is what most ERP integrations use. The dedicated address endpoints are useful when you need to manage addresses independently, for example when addresses come from a different source than the company data.

Approach 1: Inline addresses​

The simplest way to import addresses is to include them in the company or customer bulk payload. This is described in Import Companies, Contacts and Customers.

POST /v2/companies/bulk/sourceId
POST /v2/customers/bulk/sourceId

Address-only updates​

If you only want to add or update addresses on existing companies without touching any other company fields, combine the company bulk endpoint with the skipCreate directive. This pattern ensures that:

  • No new companies are created (only existing companies get updated)
  • Only the addresses in the payload are processed

This is the recommended approach when addresses come from a separate sync or a different source than the company master data.

{
  "companies": [
    {
      "source": "MY_ERP",
      "sourceId": "1032644",
      "addresses": [
        {
          "type": "delivery",
          "code": "35101",
          "street": "Industrieweg",
          "number": "8",
          "postalCode": "3542 AD",
          "city": "Utrecht",
          "country": "NL",
          "email": "magazijn@bakkerbouw.nl"
        },
        {
          "type": "delivery",
          "code": "35102",
          "street": "Havenstraat",
          "number": "22",
          "postalCode": "1013 AW",
          "city": "Amsterdam",
          "country": "NL",
          "numberExtension": "B",
          "email": "levering@bakkerbouw.nl"
        }
      ]
    },
    {
      "source": "MY_ERP",
      "sourceId": "1032645",
      "addresses": [
        {
          "type": "delivery",
          "code": "35103",
          "street": "Boslaan",
          "number": "5",
          "postalCode": "7311 HN",
          "city": "Apeldoorn",
          "country": "NL"
        }
      ]
    }
  ],
  "directives": [
    {
      "operation": "skipCreate",
      "fields": []
    }
  ]
}

Each company in the payload is identified by its source and sourceId. The endpoint looks up the company in Propeller and adds or updates the addresses listed. The same approach works for customers using POST /v2/customers/bulk/sourceId.

Grouping addresses per company​

If your source system provides addresses as a flat list rather than grouped per company, you need to group them by company before sending the payload. Each company object in the companies array should contain all addresses for that company. A common pattern in middleware is to group addresses by source and source ID.

Approach 2: Dedicated address endpoints​

When you want to manage addresses for a specific company or customer independently, use the dedicated bulk address endpoints:

POST /v2/companies/{lookupKey}/{lookupValue}/addresses/bulk
POST /v2/customers/{lookupKey}/{lookupValue}/addresses/bulk

These endpoints target a single company or customer and accept a list of addresses for that entity.

Path parameters​

  • lookupKey: either id (Propeller internal ID) or sourceId (the external source ID)
  • lookupValue: the value to look up

When using sourceId as the lookup key, add the source query parameter to specify which source system the ID belongs to:

POST /v2/companies/sourceId/1032644/addresses/bulk?source=MY_ERP

Request body​

{
  "addresses": [
    {
      "type": "delivery",
      "code": "35101",
      "street": "Industrieweg",
      "number": "8",
      "postalCode": "3542 AD",
      "city": "Utrecht",
      "country": "NL",
      "email": "magazijn@bakkerbouw.nl",
      "isDefault": "Y"
    },
    {
      "type": "delivery",
      "code": "35102",
      "street": "Havenstraat",
      "number": "22",
      "numberExtension": "B",
      "postalCode": "1013 AW",
      "city": "Amsterdam",
      "country": "NL",
      "email": "levering@bakkerbouw.nl"
    }
  ]
}

Address types​

Every address requires a type. Propeller supports three address types:

  • delivery: a shipping or delivery address
  • invoice: a billing address

A company or customer can have multiple addresses of the same type. Use isDefault set to "Y" to mark one address as the default for its type.

Address code​

The code field acts as a lookup key for upsert behavior on addresses. When you send an address with a code that already exists on the company or customer, the existing address is updated. When the code is new, a new address is created. This is how you keep addresses in sync without creating duplicates.

The code can be up to 64 characters. Use whatever identifier your source system has for the address record.

The icp field​

The icp field is relevant for B2B scenarios where you ship orders across borders within the EU. When icp is set to "Y" on a delivery address, Propeller does not apply tax to orders shipped to that address. This implements the EU intra-community supply (ICP) rule where VAT is reverse-charged to the buyer.

Response​

The inline approach returns the standard company or customer bulk response as described in Import Companies, Contacts and Customers.

The dedicated address endpoints return a 200 status code on success.

See also​