SalesOS

Contacts

Contact records and relationships

List contacts

GET
/v1/contacts

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Query Parameters

accountIdstring
searchstring
pagestring
limitstring
sortBystring
sortOrderstring
ownerstring
createdAfterstring
idsstring
customFieldsstring
withCustomFieldsstring
curl -X GET "https://api.salesos.org/v1/contacts?accountId=%3Cstring%3E&search=%3Cstring%3E&page=%3Cstring%3E&limit=%3Cstring%3E&sortBy=%3Cstring%3E&sortOrder=%3Cstring%3E&owner=%3Cstring%3E&createdAfter=%3Cstring%3E&ids=%3Cstring%3E&customFields=%3Cstring%3E&withCustomFields=%3Cstring%3E" \
  -H "Authorization: Bearer <token>"

ContactList

{
  "data": [
    {
      "id": "string",
      "accountId": "string",
      "ownerId": "string",
      "organizationId": "string",
      "reportsToId": "string",
      "salutation": "string",
      "firstName": "string",
      "lastName": "string",
      "email": "string",
      "phone": "string",
      "mobilePhone": "string",
      "title": "string",
      "department": "string",
      "role": "CHAMPION",
      "seniorityLevel": "IC",
      "buyingPower": "NONE",
      "mailingStreet": "string",
      "mailingCity": "string",
      "mailingState": "string",
      "mailingPostalCode": "string",
      "mailingCountry": "string",
      "linkedinUrl": "string",
      "twitterHandle": "string",
      "avatarUrl": "string",
      "description": "string",
      "engagementScore": 0,
      "responseRate": 0,
      "communicationStyle": "string",
      "interests": [
        "string"
      ],
      "tags": [
        "string"
      ],
      "influenceLevel": "HIGH",
      "contactStatus": "ACTIVE",
      "doNotCall": true,
      "doNotEmail": true,
      "emailOptOut": true,
      "lastContactedAt": "2019-08-24T14:15:22Z",
      "lastEmailDate": "2019-08-24T14:15:22Z",
      "lastCallDate": "2019-08-24T14:15:22Z",
      "metadata": null,
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "page": 1,
  "limit": 50,
  "total": 0,
  "totalPages": 0,
  "hasMore": true
}

Create contact

POST
/v1/contacts

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired
accountIdstring
firstNameRequiredstring
lastNameRequiredstring
salutationstring
emailstring
Format: "email"
phonestring
mobilePhonestring
titlestring
departmentstring
rolestring
Value in: "CHAMPION" | "ECONOMIC_BUYER" | "DECISION_MAKER" | "INFLUENCER" | "END_USER" | "GATEKEEPER" | "BLOCKER" | "TECHNICAL_BUYER"
seniorityLevelstring
Value in: "MANAGER" | "OWNER" | "IC" | "SENIOR_MANAGER" | "DIRECTOR" | "SENIOR_DIRECTOR" | "VP" | "SVP" | "C_LEVEL" | "BOARD"
buyingPowerstring
Value in: "NONE" | "DECISION_MAKER" | "INFLUENCER" | "RECOMMENDER" | "BUDGET_HOLDER"
reportsToIdstring
mailingStreetstring
mailingCitystring
mailingStatestring
mailingPostalCodestring
mailingCountrystring
linkedinUrlstring
Format: "uri"
twitterHandlestring
descriptionstring
influenceLevelstring
Value in: "HIGH" | "MEDIUM" | "LOW"
contactStatusstring
Value in: "ACTIVE" | "INACTIVE" | "BOUNCED" | "UNSUBSCRIBED"
doNotCallboolean
doNotEmailboolean
emailOptOutboolean

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X POST "https://api.salesos.org/v1/contacts" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "string",
    "firstName": "string",
    "lastName": "string",
    "salutation": "string",
    "email": "[email protected]",
    "phone": "string",
    "mobilePhone": "string",
    "title": "string",
    "department": "string",
    "role": "CHAMPION",
    "seniorityLevel": "MANAGER",
    "buyingPower": "NONE",
    "reportsToId": "string",
    "mailingStreet": "string",
    "mailingCity": "string",
    "mailingState": "string",
    "mailingPostalCode": "string",
    "mailingCountry": "string",
    "linkedinUrl": "http://example.com",
    "twitterHandle": "string",
    "description": "string",
    "influenceLevel": "HIGH",
    "contactStatus": "ACTIVE",
    "doNotCall": true,
    "doNotEmail": true,
    "emailOptOut": true
  }'

Contact

{
  "id": "string",
  "accountId": "string",
  "ownerId": "string",
  "organizationId": "string",
  "reportsToId": "string",
  "salutation": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "phone": "string",
  "mobilePhone": "string",
  "title": "string",
  "department": "string",
  "role": "CHAMPION",
  "seniorityLevel": "IC",
  "buyingPower": "NONE",
  "mailingStreet": "string",
  "mailingCity": "string",
  "mailingState": "string",
  "mailingPostalCode": "string",
  "mailingCountry": "string",
  "linkedinUrl": "string",
  "twitterHandle": "string",
  "avatarUrl": "string",
  "description": "string",
  "engagementScore": 0,
  "responseRate": 0,
  "communicationStyle": "string",
  "interests": [
    "string"
  ],
  "tags": [
    "string"
  ],
  "influenceLevel": "HIGH",
  "contactStatus": "ACTIVE",
  "doNotCall": true,
  "doNotEmail": true,
  "emailOptOut": true,
  "lastContactedAt": "2019-08-24T14:15:22Z",
  "lastEmailDate": "2019-08-24T14:15:22Z",
  "lastCallDate": "2019-08-24T14:15:22Z",
  "metadata": null,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Get contact stats

GET
/v1/contacts/stats

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

curl -X GET "https://api.salesos.org/v1/contacts/stats" \
  -H "Authorization: Bearer <token>"

List deleted

GET
/v1/contacts/deleted

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

curl -X GET "https://api.salesos.org/v1/contacts/deleted" \
  -H "Authorization: Bearer <token>"

ContactArray

[
  {
    "id": "string",
    "accountId": "string",
    "ownerId": "string",
    "organizationId": "string",
    "reportsToId": "string",
    "salutation": "string",
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "phone": "string",
    "mobilePhone": "string",
    "title": "string",
    "department": "string",
    "role": "CHAMPION",
    "seniorityLevel": "IC",
    "buyingPower": "NONE",
    "mailingStreet": "string",
    "mailingCity": "string",
    "mailingState": "string",
    "mailingPostalCode": "string",
    "mailingCountry": "string",
    "linkedinUrl": "string",
    "twitterHandle": "string",
    "avatarUrl": "string",
    "description": "string",
    "engagementScore": 0,
    "responseRate": 0,
    "communicationStyle": "string",
    "interests": [
      "string"
    ],
    "tags": [
      "string"
    ],
    "influenceLevel": "HIGH",
    "contactStatus": "ACTIVE",
    "doNotCall": true,
    "doNotEmail": true,
    "emailOptOut": true,
    "lastContactedAt": "2019-08-24T14:15:22Z",
    "lastEmailDate": "2019-08-24T14:15:22Z",
    "lastCallDate": "2019-08-24T14:15:22Z",
    "metadata": null,
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
]

Get contact

GET
/v1/contacts/{id}

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

idRequiredstring
curl -X GET "https://api.salesos.org/v1/contacts/<string>" \
  -H "Authorization: Bearer <token>"

Contact

{
  "id": "string",
  "accountId": "string",
  "ownerId": "string",
  "organizationId": "string",
  "reportsToId": "string",
  "salutation": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "phone": "string",
  "mobilePhone": "string",
  "title": "string",
  "department": "string",
  "role": "CHAMPION",
  "seniorityLevel": "IC",
  "buyingPower": "NONE",
  "mailingStreet": "string",
  "mailingCity": "string",
  "mailingState": "string",
  "mailingPostalCode": "string",
  "mailingCountry": "string",
  "linkedinUrl": "string",
  "twitterHandle": "string",
  "avatarUrl": "string",
  "description": "string",
  "engagementScore": 0,
  "responseRate": 0,
  "communicationStyle": "string",
  "interests": [
    "string"
  ],
  "tags": [
    "string"
  ],
  "influenceLevel": "HIGH",
  "contactStatus": "ACTIVE",
  "doNotCall": true,
  "doNotEmail": true,
  "emailOptOut": true,
  "lastContactedAt": "2019-08-24T14:15:22Z",
  "lastEmailDate": "2019-08-24T14:15:22Z",
  "lastCallDate": "2019-08-24T14:15:22Z",
  "metadata": null,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Update contact

PATCH
/v1/contacts/{id}

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired

Path Parameters

idRequiredstring

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X PATCH "https://api.salesos.org/v1/contacts/<string>" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'

Contact

{
  "id": "string",
  "accountId": "string",
  "ownerId": "string",
  "organizationId": "string",
  "reportsToId": "string",
  "salutation": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "phone": "string",
  "mobilePhone": "string",
  "title": "string",
  "department": "string",
  "role": "CHAMPION",
  "seniorityLevel": "IC",
  "buyingPower": "NONE",
  "mailingStreet": "string",
  "mailingCity": "string",
  "mailingState": "string",
  "mailingPostalCode": "string",
  "mailingCountry": "string",
  "linkedinUrl": "string",
  "twitterHandle": "string",
  "avatarUrl": "string",
  "description": "string",
  "engagementScore": 0,
  "responseRate": 0,
  "communicationStyle": "string",
  "interests": [
    "string"
  ],
  "tags": [
    "string"
  ],
  "influenceLevel": "HIGH",
  "contactStatus": "ACTIVE",
  "doNotCall": true,
  "doNotEmail": true,
  "emailOptOut": true,
  "lastContactedAt": "2019-08-24T14:15:22Z",
  "lastEmailDate": "2019-08-24T14:15:22Z",
  "lastCallDate": "2019-08-24T14:15:22Z",
  "metadata": null,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Delete contact

DELETE
/v1/contacts/{id}

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

idRequiredstring
curl -X DELETE "https://api.salesos.org/v1/contacts/<string>" \
  -H "Authorization: Bearer <token>"

No response body.

Restore

POST
/v1/contacts/{id}/restore

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

idRequiredstring

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X POST "https://api.salesos.org/v1/contacts/<string>/restore" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>"

Contact

{
  "id": "string",
  "accountId": "string",
  "ownerId": "string",
  "organizationId": "string",
  "reportsToId": "string",
  "salutation": "string",
  "firstName": "string",
  "lastName": "string",
  "email": "string",
  "phone": "string",
  "mobilePhone": "string",
  "title": "string",
  "department": "string",
  "role": "CHAMPION",
  "seniorityLevel": "IC",
  "buyingPower": "NONE",
  "mailingStreet": "string",
  "mailingCity": "string",
  "mailingState": "string",
  "mailingPostalCode": "string",
  "mailingCountry": "string",
  "linkedinUrl": "string",
  "twitterHandle": "string",
  "avatarUrl": "string",
  "description": "string",
  "engagementScore": 0,
  "responseRate": 0,
  "communicationStyle": "string",
  "interests": [
    "string"
  ],
  "tags": [
    "string"
  ],
  "influenceLevel": "HIGH",
  "contactStatus": "ACTIVE",
  "doNotCall": true,
  "doNotEmail": true,
  "emailOptOut": true,
  "lastContactedAt": "2019-08-24T14:15:22Z",
  "lastEmailDate": "2019-08-24T14:15:22Z",
  "lastCallDate": "2019-08-24T14:15:22Z",
  "metadata": null,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Get contact opportunities

GET
/v1/contacts/{id}/opportunities

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Path Parameters

idRequiredstring
curl -X GET "https://api.salesos.org/v1/contacts/<string>/opportunities" \
  -H "Authorization: Bearer <token>"

Bulk update

POST
/v1/contacts/bulk/update

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X POST "https://api.salesos.org/v1/contacts/bulk/update" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'

BulkActionResult

{
  "message": "string",
  "count": 0,
  "unchanged": 0,
  "failed": [
    {
      "id": "string",
      "error": "string"
    }
  ]
}

Bulk delete

POST
/v1/contacts/bulk/delete

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X POST "https://api.salesos.org/v1/contacts/bulk/delete" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'

BulkActionResult

{
  "message": "string",
  "count": 0,
  "unchanged": 0,
  "failed": [
    {
      "id": "string",
      "error": "string"
    }
  ]
}

Bulk assign

POST
/v1/contacts/bulk/assign

Authorization

AuthorizationRequiredBearer <token>

Session token from the SalesOS web app.

In: header

X-API-Key<token>

API key from Settings → API Keys. Authorization: ApiKey <key> is also accepted. Each operation lists the scope it needs under x-api-key-scopes.

In: header

Request Body

application/jsonRequired

Header Parameters

Idempotency-Keystring

Unique key (a UUID is ideal) that makes this write safe to retry for 24 hours: a retry with the same body replays the original response (Idempotent-Replayed: true); the same key with a different body is a 409.

Maximum length: 255
curl -X POST "https://api.salesos.org/v1/contacts/bulk/assign" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'

BulkActionResult

{
  "message": "string",
  "count": 0,
  "unchanged": 0,
  "failed": [
    {
      "id": "string",
      "error": "string"
    }
  ]
}

Leads

Lead management and conversion

Accounts

Account/company management