> ## Documentation Index
> Fetch the complete documentation index at: https://docs.portal.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a Location to a Contact

> POST /public/people/{ContactId}/location — Adds an address to a contact. Street is required. When Country is provided, State is also required.

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.

<Note>
  The request body must be submitted as `application/x-www-form-urlencoded`.
</Note>

<RequestExample>
  ```bash curl theme={null}
  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'
  ```

  ```python python theme={null}
  import requests
  from portal_auth import sign_request

  url = "https://api.portal.io/public/people/1042/location"
  timestamp = "Mon, 06 Apr 2026 00:22:19 GMT"
  content_type = "application/x-www-form-urlencoded"
  signature = sign_request("POST", url, content_type, timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY")

  response = requests.post(url, headers={
      "Accept": "application/json",
      "Content-Type": content_type,
      "X-MSS-API-APPID": "YOUR_APP_ID",
      "X-MSS-API-USERKEY": "YOUR_USER_KEY",
      "X-MSS-CUSTOM-DATE": timestamp,
      "X-MSS-SIGNATURE": signature
  }, data={
      "Street": "456 Oak Ave",
      "City": "Austin",
      "State": "Texas",
      "PostalCode": "78702",
      "Country": "United States",
      "IsPrimary": "true"
  })
  print(response.json())
  ```

  ```javascript node.js theme={null}
  const { signRequest } = require('./portalAuth');

  const url = "https://api.portal.io/public/people/1042/location";
  const timestamp = new Date().toUTCString();
  const contentType = "application/x-www-form-urlencoded";
  const signature = signRequest("POST", url, contentType, timestamp, "YOUR_USER_KEY", "YOUR_SECRET_KEY");

  const response = await fetch(url, {
      method: "POST",
      headers: {
          "Accept": "application/json",
          "Content-Type": contentType,
          "X-MSS-API-APPID": "YOUR_APP_ID",
          "X-MSS-API-USERKEY": "YOUR_USER_KEY",
          "X-MSS-CUSTOM-DATE": timestamp,
          "X-MSS-SIGNATURE": signature
      },
      body: new URLSearchParams({
          Street: "456 Oak Ave",
          City: "Austin",
          State: "Texas",
          PostalCode: "78702",
          Country: "United States",
          IsPrimary: "true"
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "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": ""
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /public/people/{ContactId}/location
openapi: 3.1.0
info:
  title: Portal.Api
  version: '1.0'
servers:
  - url: http://127.0.0.1:5000
security: []
tags: []
paths:
  /public/people/{ContactId}/location:
    post:
      tags:
        - People
      summary: Create New Contact Location
      description: >-
        Adds a location to the specified contact. Street is required. When
        Country is provided, State is also required. Use IsPrimary to make the
        new location the primary location and IsBilling to make it the billing
        location.
      operationId: AddPersonLocation
      parameters:
        - $ref: '#/components/parameters/Accept'
        - name: X-MSS-API-APPID
          in: header
          description: Application Id
          required: true
          schema:
            type: string
        - name: X-MSS-CUSTOM-DATE
          in: header
          description: A date timestamp of the request
          required: true
          schema:
            type: string
        - name: X-MSS-SIGNATURE
          in: header
          description: A signature for the request
          required: true
          schema:
            type: string
        - name: X-MSS-API-USERKEY
          in: header
          description: User API Key
          required: true
          schema:
            type: string
        - name: ContactId
          in: path
          required: true
          schema:
            type: integer
            format: int32
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                ContactFirstName:
                  description: Contact First Name (Maximum character length is 50)
                  type: string
                ContactLastName:
                  description: Contact Last Name (Maximum character length is 50)
                  type: string
                ContactPhoneNumber:
                  description: Contact Phone Number (Maximum character length is 50)
                  type: string
                ContactEmail:
                  description: Contact Email (Maximum character length is 100)
                  type: string
                Street:
                  description: Street (Maximum character length is 100)
                  type: string
                Suite:
                  description: Suite (Maximum character length is 100)
                  type: string
                City:
                  description: City (Maximum character length is 50)
                  type: string
                PostalCode:
                  description: Postal Code (Maximum character length is 20)
                  type: string
                State:
                  description: State (Maximum character length is 256)
                  type: string
                Country:
                  description: Country (Maximum character length is 256)
                  type: string
                IsPrimary:
                  type: boolean
                IsBilling:
                  type: boolean
              required:
                - Street
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicContactLocationModel'
        '401':
          description: >-
            Not Authorized to access this endpoint or your HMAC hash was
            incorrect.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebServiceException'
        '402':
          description: This action requires an active subscription.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '403':
          description: You do not have permission for this API call.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
        '404':
          description: This person does not exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpError'
      deprecated: false
      x-codeSamples: []
components:
  parameters:
    Accept:
      name: Accept
      in: header
      description: Accept Header
      required: true
      schema:
        type: string
        enum:
          - application/json
  schemas:
    PublicContactLocationModel:
      title: PublicContactLocationModel
      required:
        - isPrimary
        - isBilling
      properties:
        contactFirstName:
          description: Location contact first name
          type: string
        contactLastName:
          description: Location contact last name
          type: string
        contactPhoneNumber:
          description: Location contact phone number
          type: string
        contactEmail:
          description: Location contact email address
          type: string
        isPrimary:
          description: Whether this location is the primary location for the contact
          type: boolean
        isBilling:
          description: Whether this location is the billing location for the contact
          type: boolean
        id:
          description: Unique numeric identifier of the location, when available.
          type: integer
          format: int32
        street:
          description: Primary street address line.
          type: string
        suite:
          description: Secondary address line, apartment, or suite.
          type: string
        city:
          description: City or locality.
          type: string
        postalCode:
          description: Postal or ZIP code.
          type: string
        state:
          description: State, province, or region name.
          type: string
        stateAbbrev:
          description: State or province abbreviation when available.
          type: string
        country:
          description: Country name.
          type: string
        phone:
          description: Location phone number when one is associated with this address.
          type: string
      description: Contact-location detail model
      type: object
    WebServiceException:
      title: WebServiceException
      properties:
        statusCode:
          type: integer
          format: int32
        statusDescription:
          type: string
        responseHeaders:
          $ref: '#/components/schemas/WebHeaderCollection'
        responseDto:
          $ref: '#/components/schemas/Object'
        responseBody:
          type: string
        message:
          type: string
        errorCode:
          type: string
        errorMessage:
          type: string
        serverStackTrace:
          type: string
        state:
          $ref: '#/components/schemas/Object'
        responseStatus:
          $ref: '#/components/schemas/ResponseStatus'
        targetSite:
          $ref: '#/components/schemas/MethodBase'
        data:
          $ref: '#/components/schemas/IDictionary'
        innerException:
          $ref: '#/components/schemas/Exception'
        helpLink:
          type: string
        source:
          type: string
        hResult:
          type: integer
          format: int32
        stackTrace:
          type: string
      description: WebServiceException
      type: object
    HttpError:
      title: HttpError
      properties:
        errorCode:
          type: string
        stackTrace:
          type: string
        contentType:
          type: string
        headers:
          $ref: '#/components/schemas/Dictionary_String_String_'
        cookies:
          type: array
          items:
            $ref: '#/components/schemas/Cookie'
        status:
          type: integer
          format: int32
        statusCode:
          type: string
        statusDescription:
          type: string
        response:
          $ref: '#/components/schemas/Object'
        responseFilter:
          $ref: '#/components/schemas/IContentTypeWriter'
        requestContext:
          $ref: '#/components/schemas/IRequest'
        paddingLength:
          type: integer
          format: int32
        resultScope:
          $ref: '#/components/schemas/Func_IDisposable_'
        options:
          $ref: '#/components/schemas/IDictionary_String_String_'
        responseStatus:
          $ref: '#/components/schemas/ResponseStatus'
        targetSite:
          $ref: '#/components/schemas/MethodBase'
        message:
          type: string
        data:
          $ref: '#/components/schemas/IDictionary'
        innerException:
          $ref: '#/components/schemas/Exception'
        helpLink:
          type: string
        source:
          type: string
        hResult:
          type: integer
          format: int32
      description: HttpError
      type: object
    WebHeaderCollection:
      title: WebHeaderCollection
      properties: {}
      description: WebHeaderCollection
      type: object
    Object:
      properties: {}
      description: Object
      type: object
    ResponseStatus:
      title: ResponseStatus
      properties:
        errorCode:
          type: string
        message:
          type: string
        stackTrace:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ResponseError'
        meta:
          $ref: '#/components/schemas/Dictionary_String_String_'
      description: ResponseStatus
      type: object
    MethodBase:
      title: MethodBase
      properties: {}
      description: MethodBase
      type: object
    IDictionary:
      title: IDictionary
      properties: {}
      description: IDictionary
      type: object
    Exception:
      title: Exception
      properties: {}
      description: Exception
      type: object
    Dictionary_String_String_:
      title: Dictionary<String,String>
      additionalProperties:
        type: string
      description: Dictionary<String,String>
      type: object
    Cookie:
      title: Cookie
      properties: {}
      description: Cookie
      type: object
    IContentTypeWriter:
      title: IContentTypeWriter
      properties: {}
      description: IContentTypeWriter
      type: object
    IRequest:
      title: IRequest
      properties: {}
      description: IRequest
      type: object
    Func_IDisposable_:
      title: Func`1
      properties: {}
      description: Func<IDisposable>
      type: object
    IDictionary_String_String_:
      title: IDictionary<String,String>
      additionalProperties:
        type: string
      description: IDictionary<String,String>
      type: object
    ResponseError:
      title: ResponseError
      properties:
        errorCode:
          type: string
        fieldName:
          type: string
        message:
          type: string
        meta:
          $ref: '#/components/schemas/Dictionary_String_String_'
      description: ResponseError
      type: object

````