Sign in

v1

latestOpenAPI 3.1.02026-07-26359254.7 MB
Contacts

Create a contact

<small>Requires the contacts:write scope (or a broader one that includes it).</small>

Use this endpoint when you need to add a single new contact to your account — for example when capturing a lead from your own application. Provide any known profile fields and custom field values; the contact is created under your ownership and returned with its assigned id. To add many contacts at once, or to update existing ones by a match key, use the import endpoint instead.

post/v3/contacts

Request body

emailstring email

Primary email address

firstNamestring

First name

lastNamestring

Last name

phonestring

Phone number

phone2string

Secondary phone number

titlestring

Job title

companystring

Organization name

companySize'Empty' | 'SelfEmployed' | 'Ten' | 'Fifty' | 'TwoHundred' | 'FiveHundred' | 'OneThousand' | 'FiveThousand' | 'TenThousand' | 'OverTenThousand'

Organization employee count range

industrystring

Business sector

citystring

City of residence

statestring

State/province

countrystring

Country

timeZoneIdstring

Timezone identifier

linkedInUrlstring uri

LinkedIn profile URL

linkedInSalesNavigatorUrlstring uri

Sales Navigator URL

linkedInRecruiterUrlstring uri

Recruiter URL

notesstring

Additional information

accountIdinteger nullable

ID of the contact account to link this contact to

Example request

{
  "email": "john.doe@company.com",
  "firstName": "John",
  "lastName": "Doe",
  "title": "Senior Product Manager",
  "company": "Tech Solutions Inc",
  "phone": "+1-415-555-0123",
  "linkedInUrl": "https://www.linkedin.com/in/johndoe",
  "accountId": 100,
  "customFields": [
    {
      "key": "leadSource",
      "value": "Conference"
    }
  ]
}

Response

Contact created successfully

idinteger

Unique ID

emailstring email

Primary email address

domainstring

Email domain (derived from email)

firstNamestring

First name

lastNamestring

Last name

phonestring

Phone number

titlestring

Job title

companystring

Organization name

companySize'empty' | 'selfEmployed' | 'ten' | 'fifty' | 'twoHundred' | 'fiveHundred' | 'oneThousand' | 'fiveThousand' | 'tenThousand' | 'overTenThousand'

Organization employee count range

industrystring

Business sector

citystring

City of residence

statestring

State/province

countrystring

Country

timeZoneIdstring

Timezone identifier

linkedInUrlstring uri

LinkedIn profile URL

linkedInSalesNavigatorUrlstring uri

Sales Navigator URL

linkedInRecruiterUrlstring uri

Recruiter URL

phoneStatus'pending' | 'invalid' | 'valid' | 'validationFailed' | 'notValidated'

Phone validation status

notesstring

Additional information

ownerUserIdinteger

ID of the user who owns this contact

accountIdinteger nullable

ID of the contact account this contact belongs to

isOptedOutboolean

Whether the contact has opted out of communications

callStatus'none' | 'toCall' | 'called'

Contact-level call status. Set via PATCH /v3/contacts/{id} (callStatus field). Pass none to clear.

meetingStatus'none' | 'meetingBooked'

Contact-level meeting status. Set via PATCH /v3/contacts/{id} (meetingStatus field). Pass none to clear.

addingDatestring date-time nullable

Date the contact was added

createdAtstring date-time nullable

Creation timestamp

lastModifiedAtstring date-time nullable

Last modification timestamp

Example response

{
  "id": 12345,
  "email": "john.doe@company.com",
  "firstName": "John",
  "lastName": "Doe",
  "title": "Senior Product Manager",
  "company": "Tech Solutions Inc",
  "domain": "company.com",
  "companySize": "oneThousand",
  "city": "San Francisco",
  "state": "CA",
  "country": "United States",
  "timeZoneId": "America/Los_Angeles",
  "phone": "+1-415-555-0123",
  "phoneStatus": "valid",
  "linkedInUrl": "https://www.linkedin.com/in/johndoe",
  "linkedInSalesNavigatorUrl": "https://www.linkedin.com/sales/profile/123456",
  "linkedInRecruiterUrl": "https://www.linkedin.com/recruiter/profile/789012",
  "industry": "Software & Technology",
  "notes": "Met at SaaS Conference 2024",
  "ownerUserId": 42,
  "accountId": 100,
  "isOptedOut": false,
  "callStatus": "toCall",
  "meetingStatus": "none",
  "addingDate": "2024-03-08T10:00:00+00:00",
  "createdAt": "2024-03-08T10:00:00",
  "lastModifiedAt": "2024-03-10T15:30:00",
  "customFields": [
    {
      "key": "leadSource",
      "value": "Conference"
    },
    {
      "key": "budget",
      "value": "100k-250k"
    }
  ]
}