HelloFlex API – Patch Employer Address Operations

Employer Address arrays

Zeroth-based array

HelloFlex API uses a zeroth-based array. Due to dependencies, Employer address array 0 is always present for AddressTypeId 1 and will always be visible in GET /api/employers/{employerGuid} requests.

We recommend to avoid using array 0 for other AddressTypeIds in your Patch Employer API requests.

Array index positions

Be aware that array index positions are not stored in the database and array index positions could be rearranged after each address operation

To determine the corresponding array index position number for an AddressTypeId , such as when using a "replace" operation, we strongly recommend using GET /api/employers/{employerGuid} requests prior to making your PATCH /api/employers/{employerGuid} requests to ensure updating the intended address(es), using the correct array index number(s).

You can determine used array index numbers by counting the position of each address in the GET request results and subtracting 1.

Employer address array operation examples

Adding an Employer address

Add an address to an AddressTypeId using an array index number, provided the used AddressTypeId is not currently filled with existing address data (“add” cannot overwrite an existing address).

This example adds a new address for AddressTypeId 3, using a specified array index position number.

	[	
		{
		"path": "/Addresses/2",
		"from": "/Addresses",
		"value": {
			"addressTypeId" : 3,
			"countryId": 1,
			"city": "City",
			"postalCode": "1000AA",
			"street": "Street",
			"number": 3,
			"unit": "",
			},
		"op": "add"
		}
	]

Using an array already in use is not recommended. You can use the next available array slot number in sequence; if you have address 0 and 1 in use and you want to add 1 new address you cannot use array 3 to add the next new address. Instead, you use array 2 in this example. If you instead want to add 2 new addresses in this example, you would use array 2 and 3 in that order.

We strongly recommend using a GET /api/employers/{employerGuid} request when using array numbers, to ensure using correct array index numbers where required.

We recommend using a dash (-) to add a new address. Using a dash will send the new AddressTypeId to the end of the array, allowing the next subsequently available array index position number to be used for the "add" operation. Using a dash (-) will not prevent possible rearrangement of the array index position numbers, but may simplify adding a new address.

This example adds a new address for AddressTypeId 2, without using a specified array index position number.

	[	
		{
		"path": "/Addresses/-",
		"from": "/Addresses",
		"value": {
			"addressTypeId" : 2,
			"countryId": 1,
			"city": "City",
			"postalCode": "1000AA",
			"street": "Street",
			"number": 2,
			},
		"op": "add"
		}
	]

Replacing an Employer address

Replace existing address data at an AddressTypeId on an array index position number.

We strongly recommend using a GET /api/employers/{employerGuid} request when using array numbers, to ensure using correct array index numbers where required.

This example replaces existing address data for AddressTypeId 2 on the specified array index position number.

	[	
		{
			"path": "/Addresses/1",
			"from": "/Addresses",
			"value": {
				"addressTypeId" : 2,
				"countryId": 1,
				"city": "City",
				"postalCode": "1000AA",
				"street": "Street",
				"number": 2,
				"unit": "",
				},
			"op": "replace"
		}

	]

This example replaces part of an address with the used value, at the specified array index position number.

	[
		{
			"path": "/Addresses/1/postalCode",
			"from": "/Addresses",
			"value": "1000AA",
			"op": "replace"
		}
	]

Removing an Employer address

To fully remove an address, it's sufficient to target the array index position number of the address.

This example removes the address data for the AddressTypeId present on array 1.

	[	
		{
			"path": "/Addresses/1",
			"from": "/Addresses",
			"op": "remove"
		}
	]

Note: to remove more than one address in the same API request, we recommend removing them in reverse order. If 3 addresses are present on arrays 0, 1 and 2 and you want to remove both the addresses on array 1 and 2 simultaneously, you can remove them both in reverse order in the same API request.

Complex combinations

Operation combinations are possible, allowing more complex API requests.

	 [	
		{
			"path": "/Addresses/3",
			"from": "/Addresses",
			"op": "remove"
		},
		{
			"path": "/Addresses/2",
			"from": "/Addresses",
			"op": "remove"
		},
		{
			"path": "/Addresses/1",
			"from": "/Addresses",
			"value": {
				"addressTypeId" : 2,
				"countryId": 1,
				"city": "City",
				"postalCode": "1000AA",
				"street": "Street",
				"number": 2,
				"unit": "",
				},
			"op": "replace"
		},
		{
			"path": "/Addresses/0/postalCode",
			"from": "/Addresses",
			"value": "1000AA",
			"op": "replace"
		},
		{
			"path": "/Addresses/2",
			"from": "/Addresses",
			"value": {
				"addressTypeId" : 3,
				"countryId": 1,
				"city": "City",
				"postalCode": "1000AA",
				"street": "Street",
				"number": 3,
				"unit": "",
				},
			"op": "add"
		},
		{
			"path": "/Addresses/-",
			"from": "/Addresses",
			"value": {
				"addressTypeId" : 5,
				"countryId": 1,
				"city": "City",
				"postalCode": "1000AA",
				"street": "Street",
				"number": 5,
				},
			"op": "add"
		}
	]

Before we sent the above API request, we had the following addresses present on HelloFlex.

After we sent the above API request, the system removed an address on array 3 and 2. Using a prior GET request, we determine in advance which addresses would be removed. In this example we will removed AddressTypeId 4 (Visit address) and 3 (Reminder address).

The system then replaced AddressTypeId 2 (Postal Address) on array 1, which again we determined beforehand by checking this with a GET request. The system then replaced the postal code on AddressTypeId 1 (Main Address) on array 0 (the Main Address is always present at array 0).

We then added AddressTypeId 3 (Reminder Address) and 5 (Billing Address) by targeting the next sequentially available array index position number and a dash (-) respectively.

This gives us the below result in HelloFlex.