Skip to main content
Adds a new address to an existing contact. Street is the only required field. When Country is supplied, State must also be provided. Use IsPrimary=true to replace the contact’s current primary address, and IsBilling=true to set this as the billing address. A contact can have only one primary and one billing location at a time; setting either flag moves it from the previous location.
The request body must be submitted as application/x-www-form-urlencoded.

​
Request

POST /public/people/{ContactId}/location

​
Headers

​
Accept
string
required
Must be application/json.
​
Content-Type
string
required
Must be application/x-www-form-urlencoded.
​
X-MSS-API-APPID
string
required
Your API Application Key.
​
X-MSS-API-USERKEY
string
required
Your User API Key.
​
X-MSS-CUSTOM-DATE
string
required
Current UTC timestamp in RFC 7231 format (e.g. Mon, 06 Apr 2026 00:22:19 GMT).
​
X-MSS-SIGNATURE
string
required
HMAC-SHA256 signature of the canonical request, Base64-encoded.

​
Path Parameters

​
ContactId
integer
required
Unique numeric identifier of the contact to add a location to.

​
Body Parameters

​
Street
string
required
Street address. Maximum 255 characters.
​
Suite
string
Suite, unit, or apartment number.
​
City
string
City name.
​
PostalCode
string
ZIP or postal code.
​
State
string
State or province name. Required when Country is provided.
​
Country
string
Country name. When supplied, State must also be provided.
​
ContactFirstName
string
First name of the on-site contact for this address. Maximum 50 characters.
​
ContactLastName
string
Last name of the on-site contact for this address. Maximum 50 characters.
​
ContactPhoneNumber
string
Phone number of the on-site contact.
​
ContactEmail
string
Email address of the on-site contact.
​
IsPrimary
boolean
Set true to make this the contact’s primary location.
​
IsBilling
boolean
Set true to make this the contact’s billing location.

​
Response

​
200 Success

Returns the newly created location object.
​
id
integer
Unique numeric identifier assigned to the new location.
​
street
string
Street address.
​
suite
string
Suite, unit, or apartment number.
​
city
string
City name.
​
postalCode
string
ZIP or postal code.
​
state
string
Full state or province name.
​
stateAbbrev
string
Two-letter state abbreviation.
​
country
string
Country name.
​
phone
string
Location phone number.
​
contactFirstName
string
On-site contact first name.
​
contactLastName
string
On-site contact last name.
​
contactPhoneNumber
string
On-site contact phone number.
​
contactEmail
string
On-site contact email address.
​
isPrimary
boolean
true if this is the contact’s primary location.
​
isBilling
boolean
true if this is the contact’s billing location.

​
Error Codes

CodeMeaning
401Not authorized. Your HMAC signature was incorrect or credentials are invalid.
402An active Portal.io subscription is required to use this endpoint.
403Your user account does not have permission for this API call.
404The specified contact does not exist.

​
Example

curl -i -X POST \
  'https://api.portal.io/public/people/1042/location' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'X-MSS-API-APPID: YOUR_APP_ID' \
  -H 'X-MSS-API-USERKEY: YOUR_USER_KEY' \
  -H 'X-MSS-CUSTOM-DATE: Mon, 06 Apr 2026 00:22:19 GMT' \
  -H 'X-MSS-SIGNATURE: BASE64_SIGNATURE' \
  -d 'Street=456+Oak+Ave' \
  -d 'City=Austin' \
  -d 'State=Texas' \
  -d 'PostalCode=78702' \
  -d 'Country=United+States' \
  -d 'IsPrimary=true'

{
  "contactFirstName": "",
  "contactLastName": "",
  "contactPhoneNumber": "",
  "contactEmail": "",
  "isPrimary": true,
  "isBilling": false,
  "id": 305,
  "street": "456 Oak Ave",
  "suite": "",
  "city": "Austin",
  "postalCode": "78702",
  "state": "Texas",
  "stateAbbrev": "TX",
  "country": "United States",
  "phone": ""
}