Contacts

Addresses

List, create, update, and delete the authenticated contact's shipping, billing, and work addresses.

Every contact has a list of addresses, each typed shipping, billing, or work. At most one address per type is the default, and the API enforces this transactionally: setting is_default: true on an address clears the previous default of the same type in the same operation. All four endpoints are contact-authenticated (tenant API key plus X-Customer-Token); listing needs the contacts:read scope, writes need contacts:write (customers:read / customers:write accepted).

The address object:

Field	Type	Description
`id`	string (uuid)	Address id.
`type`	string	`shipping`, `billing`, or `work`.
`label`	string or null	Contact-facing label, for example `Home`.
`is_default`	boolean	Whether this is the default address of its type.
`name`	string	Recipient name.
`street`	string	Street and house number.
`postal_code`	string	Postal code.
`city`	string	City.
`country`	string	ISO 3166-1 alpha-2 country code, exactly 2 characters (for example `NL`).
`phone`	string or null	Phone number.

The address object:

Field	Type	Description
`id`	string (uuid)	Address id.
`type`	string	`shipping`, `billing`, or `work`.
`label`	string or null	Contact-facing label, for example `Home`.
`is_default`	boolean	Whether this is the default address of its type.
`name`	string	Recipient name.
`street`	string	Street and house number.
`postal_code`	string	Postal code.
`city`	string	City.
`country`	string	ISO 3166-1 alpha-2 country code, exactly 2 characters (for example `NL`).
`phone`	string or null	Phone number.

GET /v1/api/contacts/me/addresses

Also served at /v1/api/customers/me/addresses for existing integrations; identical request and response.

List the authenticated contact's addresses. Default addresses are ordered first. The list is not paginated; the response is a plain data array.

Headers

Name	Type	Required	Description
`X-Customer-Token`	string	Yes	Contact session token.

No query parameters.

Status: 200 OK.

Errors

401 {"message":"Invalid customer token."} when X-Customer-Token is missing or invalid.

Request

curl https://api.borkol.com/v1/api/contacts/me/addresses \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz"

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "type": "shipping",
      "label": "Home",
      "is_default": true,
      "name": "Jane Doe",
      "street": "Keizersgracht 123",
      "postal_code": "1015 CJ",
      "city": "Amsterdam",
      "country": "NL",
      "phone": "+31612345678"
    }
  ]
}

GET /v1/api/contacts/me/addresses

Also served at /v1/api/customers/me/addresses for existing integrations; identical request and response.

List the authenticated contact's addresses. Default addresses are ordered first. The list is not paginated; the response is a plain data array.

Headers

Name	Type	Required	Description
`X-Customer-Token`	string	Yes	Contact session token.

No query parameters.

Request

curl https://api.borkol.com/v1/api/contacts/me/addresses \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz"

Status: 200 OK.

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "type": "shipping",
      "label": "Home",
      "is_default": true,
      "name": "Jane Doe",
      "street": "Keizersgracht 123",
      "postal_code": "1015 CJ",
      "city": "Amsterdam",
      "country": "NL",
      "phone": "+31612345678"
    }
  ]
}

Errors

401 {"message":"Invalid customer token."} when X-Customer-Token is missing or invalid.

POST /v1/api/contacts/me/addresses

Also served at /v1/api/customers/me/addresses for existing integrations; identical request and response.

Create an address for the authenticated contact. If is_default is true, the previous default of the same type is cleared atomically in the same transaction.

Headers

Name	Type	Required	Description
`X-Customer-Token`	string	Yes	Contact session token.

Body parameters

Name	Type	Required	Description
`type`	string	No	`shipping`, `billing`, or `work`. Default `shipping`.
`label`	string or null	No	Label, maximum 50 characters.
`is_default`	boolean	No	Make this the default address of its type.
`name`	string	Yes	Recipient name, maximum 150 characters.
`street`	string	Yes	Street and house number, maximum 255 characters.
`postal_code`	string	Yes	Postal code, maximum 20 characters.
`city`	string	Yes	City, maximum 100 characters.
`country`	string	Yes	ISO 3166-1 alpha-2 code, exactly 2 characters.
`phone`	string or null	No	Phone number, maximum 50 characters.

Status: 201 Created.

Errors

422 for field validation failures, for example errors.country ["The country field must be 2 characters."].
401 {"message":"Invalid customer token."} when X-Customer-Token is missing or invalid.

Request

curl -X POST https://api.borkol.com/v1/api/contacts/me/addresses \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz" \
  -H "Content-Type: application/json" \
  -d '{"type":"shipping","label":"Home","is_default":true,"name":"Jane Doe","street":"Keizersgracht 123","postal_code":"1015 CJ","city":"Amsterdam","country":"NL","phone":"+31612345678"}'

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "type": "shipping",
    "label": "Home",
    "is_default": true,
    "name": "Jane Doe",
    "street": "Keizersgracht 123",
    "postal_code": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL",
    "phone": "+31612345678"
  }
}

POST /v1/api/contacts/me/addresses

Also served at /v1/api/customers/me/addresses for existing integrations; identical request and response.

Create an address for the authenticated contact. If is_default is true, the previous default of the same type is cleared atomically in the same transaction.

Headers

Name	Type	Required	Description
`X-Customer-Token`	string	Yes	Contact session token.

Body parameters

Name	Type	Required	Description
`type`	string	No	`shipping`, `billing`, or `work`. Default `shipping`.
`label`	string or null	No	Label, maximum 50 characters.
`is_default`	boolean	No	Make this the default address of its type.
`name`	string	Yes	Recipient name, maximum 150 characters.
`street`	string	Yes	Street and house number, maximum 255 characters.
`postal_code`	string	Yes	Postal code, maximum 20 characters.
`city`	string	Yes	City, maximum 100 characters.
`country`	string	Yes	ISO 3166-1 alpha-2 code, exactly 2 characters.
`phone`	string or null	No	Phone number, maximum 50 characters.

Request

curl -X POST https://api.borkol.com/v1/api/contacts/me/addresses \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz" \
  -H "Content-Type: application/json" \
  -d '{"type":"shipping","label":"Home","is_default":true,"name":"Jane Doe","street":"Keizersgracht 123","postal_code":"1015 CJ","city":"Amsterdam","country":"NL","phone":"+31612345678"}'

Status: 201 Created.

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "type": "shipping",
    "label": "Home",
    "is_default": true,
    "name": "Jane Doe",
    "street": "Keizersgracht 123",
    "postal_code": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL",
    "phone": "+31612345678"
  }
}

Errors

422 for field validation failures, for example errors.country ["The country field must be 2 characters."].
401 {"message":"Invalid customer token."} when X-Customer-Token is missing or invalid.

PATCH /v1/api/contacts/me/addresses/{id}

Also served at /v1/api/customers/me/addresses/{id} for existing integrations; identical request and response.

Partially update one of the authenticated contact's addresses. Same fields as create, all optional; only the fields you send are changed. If the resulting address is default (either because you set is_default: true or the address already was default and you changed its type), the previous default of the resulting type is cleared in the same transaction.

Path parameters

Name	Type	Required	Description
`id`	string (uuid)	Yes	Address id. Must belong to the authenticated contact.

Headers

Name	Type	Required	Description
`X-Customer-Token`	string	Yes	Contact session token.

Body parameters

Name	Type	Required	Description
`type`	string	No	`shipping`, `billing`, or `work`.
`label`	string or null	No	Label, maximum 50 characters.
`is_default`	boolean	No	Make this the default address of its type.
`name`	string	No	Recipient name, maximum 150 characters.
`street`	string	No	Street, maximum 255 characters.
`postal_code`	string	No	Postal code, maximum 20 characters.
`city`	string	No	City, maximum 100 characters.
`country`	string	No	ISO 3166-1 alpha-2 code, exactly 2 characters.
`phone`	string or null	No	Phone number, maximum 50 characters.

Status: 200 OK. Returns the updated address.

Errors

404 when the address does not exist or belongs to another contact.
422 for field validation failures.
401 {"message":"Invalid customer token."} when X-Customer-Token is missing or invalid.

Request

curl -X PATCH https://api.borkol.com/v1/api/contacts/me/addresses/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz" \
  -H "Content-Type: application/json" \
  -d '{"label":"Office","is_default":false}'

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "type": "shipping",
    "label": "Office",
    "is_default": false,
    "name": "Jane Doe",
    "street": "Keizersgracht 123",
    "postal_code": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL",
    "phone": "+31612345678"
  }
}

PATCH /v1/api/contacts/me/addresses/{id}

Also served at /v1/api/customers/me/addresses/{id} for existing integrations; identical request and response.

Path parameters

Name	Type	Required	Description
`id`	string (uuid)	Yes	Address id. Must belong to the authenticated contact.

Headers

Name	Type	Required	Description
`X-Customer-Token`	string	Yes	Contact session token.

Body parameters

Name	Type	Required	Description
`type`	string	No	`shipping`, `billing`, or `work`.
`label`	string or null	No	Label, maximum 50 characters.
`is_default`	boolean	No	Make this the default address of its type.
`name`	string	No	Recipient name, maximum 150 characters.
`street`	string	No	Street, maximum 255 characters.
`postal_code`	string	No	Postal code, maximum 20 characters.
`city`	string	No	City, maximum 100 characters.
`country`	string	No	ISO 3166-1 alpha-2 code, exactly 2 characters.
`phone`	string or null	No	Phone number, maximum 50 characters.

Request

curl -X PATCH https://api.borkol.com/v1/api/contacts/me/addresses/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz" \
  -H "Content-Type: application/json" \
  -d '{"label":"Office","is_default":false}'

Status: 200 OK. Returns the updated address.

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "type": "shipping",
    "label": "Office",
    "is_default": false,
    "name": "Jane Doe",
    "street": "Keizersgracht 123",
    "postal_code": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL",
    "phone": "+31612345678"
  }
}

Errors

404 when the address does not exist or belongs to another contact.
422 for field validation failures.
401 {"message":"Invalid customer token."} when X-Customer-Token is missing or invalid.

DELETE /v1/api/contacts/me/addresses/{id}

Also served at /v1/api/customers/me/addresses/{id} for existing integrations; identical request and response.

Delete one of the authenticated contact's addresses (soft delete: it disappears from the API but is retained internally).

Path parameters

Name	Type	Required	Description
`id`	string (uuid)	Yes	Address id. Must belong to the authenticated contact.

Headers

Name	Type	Required	Description
`X-Customer-Token`	string	Yes	Contact session token.

Status: 204 No Content. The response has no body.

Errors

404 when the address does not exist or belongs to another contact.
401 {"message":"Invalid customer token."} when X-Customer-Token is missing or invalid.

Request

curl -X DELETE https://api.borkol.com/v1/api/contacts/me/addresses/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz"

DELETE /v1/api/contacts/me/addresses/{id}

Also served at /v1/api/customers/me/addresses/{id} for existing integrations; identical request and response.

Delete one of the authenticated contact's addresses (soft delete: it disappears from the API but is retained internally).

Path parameters

Name	Type	Required	Description
`id`	string (uuid)	Yes	Address id. Must belong to the authenticated contact.

Headers

Name	Type	Required	Description
`X-Customer-Token`	string	Yes	Contact session token.

Request

curl -X DELETE https://api.borkol.com/v1/api/contacts/me/addresses/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d \
  -H "Authorization: Bearer {api_key}" \
  -H "X-Customer-Token: 13|Gh7rS2uX5vWy8zAbCdEfGhIjKlMnOpQrStUvWxYz"

Status: 204 No Content. The response has no body.

Errors

404 when the address does not exist or belongs to another contact.
401 {"message":"Invalid customer token."} when X-Customer-Token is missing or invalid.

GET /v1/api/contacts/me/addresses#

Headers#

Errors#

GET /v1/api/contacts/me/addresses#

Headers#

Errors#

POST /v1/api/contacts/me/addresses#

Headers#

Body parameters#

Errors#

POST /v1/api/contacts/me/addresses#

Headers#

Body parameters#

Errors#

PATCH /v1/api/contacts/me/addresses/{id}#

Path parameters#

Headers#

Body parameters#

Errors#

PATCH /v1/api/contacts/me/addresses/{id}#

Path parameters#

Headers#

Body parameters#

Errors#

DELETE /v1/api/contacts/me/addresses/{id}#

Path parameters#

Headers#

Errors#

DELETE /v1/api/contacts/me/addresses/{id}#

Path parameters#

Headers#

Errors#

GET /v1/api/contacts/me/addresses

Headers

Errors

GET /v1/api/contacts/me/addresses

Headers

Errors

POST /v1/api/contacts/me/addresses

Headers

Body parameters

Errors

POST /v1/api/contacts/me/addresses

Headers

Body parameters

Errors

PATCH /v1/api/contacts/me/addresses/{id}

Path parameters

Headers

Body parameters

Errors

PATCH /v1/api/contacts/me/addresses/{id}

Path parameters

Headers

Body parameters

Errors

DELETE /v1/api/contacts/me/addresses/{id}

Path parameters

Headers

Errors

DELETE /v1/api/contacts/me/addresses/{id}

Path parameters

Headers

Errors