> ## 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.

# Create a New Contact in Your Account

> POST /public/people — Creates a contact. PartyType (Person/Company), ContactType (Client/Employee/Contractor/Other), and FirstName are required.

Use this endpoint to add a new contact to your Portal.io dealer account. Contacts are used as the client on proposals. `PartyType`, `ContactType`, and `FirstName` are always required. When `PartyType` is `Company`, you must also supply `CompanyName`. Valid `PartyType` values: `Person`, `Company`. Valid `ContactType` values: `Client`, `Employee`, `Contractor`, `Other`.

<Note>
  The request body must be submitted as `application/x-www-form-urlencoded`. Encode special characters in field values before sending.
</Note>

<RequestExample>
  ```bash curl theme={null}
  curl -i -X POST \
    'https://api.portal.io/public/people' \
    -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 'PartyType=Person' \
    -d 'ContactType=Client' \
    -d 'FirstName=Jane' \
    -d 'LastName=Smith' \
    -d 'ContactEmail=jane.smith%40example.com' \
    -d 'ContactPhone=555-555-0100'
  ```

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

  url = "https://api.portal.io/public/people"
  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={
      "PartyType": "Person",
      "ContactType": "Client",
      "FirstName": "Jane",
      "LastName": "Smith",
      "ContactEmail": "jane.smith@example.com",
      "ContactPhone": "555-555-0100"
  })
  print(response.json())
  ```

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

  const url = "https://api.portal.io/public/people";
  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({
          PartyType: "Person",
          ContactType: "Client",
          FirstName: "Jane",
          LastName: "Smith",
          ContactEmail: "jane.smith@example.com",
          ContactPhone: "555-555-0100"
      })
  });
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "notes": "",
    "lastModifiedDate": "2026-04-06T00:22:19Z",
    "primaryLocation": null,
    "billingLocation": null,
    "proposalCount": 0,
    "paymentCount": 0,
    "id": 1042,
    "partyType": "Person",
    "contactType": "Client",
    "firstName": "Jane",
    "lastName": "Smith",
    "companyName": "",
    "contactEmail": "jane.smith@example.com",
    "contactEmailCC": "",
    "contactPhone": "555-555-0100"
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /public/people
openapi: 3.1.0
info:
  title: Portal.Api
  version: '1.0'
servers:
  - url: http://127.0.0.1:5000
security: []
tags: []
paths:
  /public/people:
    post:
      tags:
        - People
      summary: Create a New Contact
      description: >-
        Creates a contact in the current account. PartyType, ContactType, and
        FirstName are required. CompanyName is also required when PartyType is
        Company.
      operationId: AddPerson
      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
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                PartyType:
                  type: string
                ContactType:
                  type: string
                FirstName:
                  description: First Name (Maximum character length is 100)
                  type: string
                LastName:
                  description: Last Name (Maximum character length is 50)
                  type: string
                CompanyName:
                  description: Company Name (Maximum character length is 100)
                  type: string
                ContactEmail:
                  description: Email (Maximum character length is 256)
                  type: string
                ContactEmailCC:
                  description: Additioanl email(s) copied when a proposal is submitted
                  type: string
                ContactPhone:
                  description: Contact Phone (Maximum character length is 30)
                  type: string
                Notes:
                  type: string
              required:
                - PartyType
                - ContactType
                - FirstName
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPeopleContactModel'
        '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'
      deprecated: false
      x-codeSamples: []
components:
  parameters:
    Accept:
      name: Accept
      in: header
      description: Accept Header
      required: true
      schema:
        type: string
        enum:
          - application/json
  schemas:
    PublicPeopleContactModel:
      title: PublicPeopleContactModel
      required:
        - lastModifiedDate
        - id
        - partyType
        - contactType
      properties:
        notes:
          description: Free-text notes stored on the contact
          type: string
        lastModifiedDate:
          description: UTC timestamp when the contact was last modified
          type: string
          format: date-time
        primaryLocation:
          $ref: '#/components/schemas/PublicContactLocationModel'
        billingLocation:
          $ref: '#/components/schemas/PublicContactLocationModel'
        proposalCount:
          description: Number of proposals linked to the contact when counts are requested
          type: integer
          format: int32
        paymentCount:
          description: Number of payments linked to the contact when counts are requested
          type: integer
          format: int32
        id:
          description: Unique numeric identifier of the contact
          type: integer
          format: int32
        partyType:
          description: Contact party type such as Person or Company
          type: string
          enum:
            - Undefined
            - Person
            - Company
        contactType:
          description: Contact category type
          type: string
          enum:
            - Undefined
            - Client
            - Employee
            - Contractor
            - Other
        firstName:
          description: Contact first name
          type: string
        lastName:
          description: Contact last name
          type: string
        companyName:
          description: Company name when the contact represents a company
          type: string
        contactEmail:
          description: Primary contact email address
          type: string
        contactEmailCC:
          description: Additional email addresses copied when a proposal is submitted
          type: string
        contactPhone:
          description: Primary contact phone number
          type: string
      description: Contact 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
    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
    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

````