Create a New Contact in Your Account

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'

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())

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);

{
  "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"
}

POST

public

people

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'

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())

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);

{
  "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"
}

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.

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

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'

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())

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);

{
  "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"
}

Authorizations

X-MSS-API-APPID

string

header

required

Portal application identifier used as part of HMAC-authenticated API requests.

X-MSS-API-USERKEY

string

header

required

Portal user API key used together with the HMAC signature headers.

X-MSS-CUSTOM-DATE

string

header

required

Timestamp header included in the signed request to prevent replay attacks.

X-MSS-SIGNATURE

string

header

required

HMAC-SHA256 signature for the request, calculated over the canonical string defined in the authentication docs.

Headers

enum<string>

required

Accept Header

Available options:

application/json

Body

application/json

People Services

firstName

string

required

First Name (Maximum character length is 100)

partyType

enum<string>

Available options:

Undefined,

Person,

Company

contactType

enum<string>

Available options:

Undefined,

Client,

Employee,

Contractor,

Other

lastName

string

Last Name (Maximum character length is 50)

companyName

string

Company Name (Maximum character length is 100)

contactEmail

string

Email (Maximum character length is 256)

contactEmailCC

string

Additioanl email(s) copied when a proposal is submitted

contactPhone

string

Contact Phone (Maximum character length is 30)

notes

string

Response

Success

Contact detail model

integer<int32>

required

Unique numeric identifier of the contact

lastModifiedDate

string<date-time>

required

UTC timestamp when the contact was last modified

partyType

enum<string>

Available options:

Undefined,

Person,

Company

contactType

enum<string>

Available options:

Undefined,

Client,

Employee,

Contractor,

Other

firstName

string

Contact first name

lastName

string

Contact last name

companyName

string

Company name when the contact represents a company

contactEmail

string

Primary contact email address

contactEmailCC

string

Additional email addresses copied when a proposal is submitted

contactPhone

string

Primary contact phone number

notes

string

Free-text notes stored on the contact

primaryLocation

PublicContactLocationModel · object

Contact-location detail model

Show child attributes

billingLocation

PublicContactLocationModel · object

Contact-location detail model

Show child attributes

proposalCount

integer<int32>

Number of proposals linked to the contact when counts are requested

paymentCount

integer<int32>

Number of payments linked to the contact when counts are requested

⌘I

Authentication

Proposals

Proposal Items

Change Orders

AI Builder

People

Catalog

Users

Webhooks

Zapier Triggers

Create a New Contact in Your Account

Authorizations

Headers

Body

Response