SalesOS

Leads

Lead management and conversion

List

GET
/v1/leads

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

statusstring
ratingstring
leadSourcestring
minScorestring
cursorstring
limitstring
searchstring
namestring
pagestring
sortBystring
sortOrderstring
untouchedstring
ownerstring
createdAfterstring
idsstring
openstring
customFieldsstring
withCustomFieldsstring
curl -X GET "https://api.salesos.org/v1/leads?status=%3Cstring%3E&rating=%3Cstring%3E&leadSource=%3Cstring%3E&minScore=%3Cstring%3E&cursor=%3Cstring%3E&limit=%3Cstring%3E&search=%3Cstring%3E&name=%3Cstring%3E&page=%3Cstring%3E&sortBy=%3Cstring%3E&sortOrder=%3Cstring%3E&untouched=%3Cstring%3E&owner=%3Cstring%3E&createdAfter=%3Cstring%3E&ids=%3Cstring%3E&open=%3Cstring%3E&customFields=%3Cstring%3E&withCustomFields=%3Cstring%3E" \
  -H "Authorization: Bearer <token>"

LeadList

{
  "data": [
    {
      "id": "string",
      "ownerId": "string",
      "organizationId": "string",
      "salesforceId": "string",
      "salutation": "string",
      "firstName": "string",
      "lastName": "string",
      "company": "string",
      "title": "string",
      "email": "string",
      "phone": "string",
      "website": "string",
      "leadSource": "WEB",
      "status": "NEW",
      "rating": "HOT",
      "industry": "string",
      "numberOfEmployees": 0,
      "annualRevenue": 0,
      "street": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "isQualified": true,
      "qualifiedDate": "2019-08-24T14:15:22Z",
      "disqualifiedReason": "string",
      "leadScore": 0,
      "buyingIntent": "HIGH",
      "description": "string",
      "painPoints": [
        "string"
      ],
      "budget": 0,
      "timeline": "string",
      "convertedDate": "2019-08-24T14:15:22Z",
      "convertedAccountId": "string",
      "convertedContactId": "string",
      "convertedOpportunityId": "string",
      "tags": [
        "string"
      ],
      "lastContactedAt": "2019-08-24T14:15:22Z",
      "assignedAt": "2019-08-24T14:15:22Z",
      "firstTouchAt": "2019-08-24T14:15:22Z",
      "territoryId": "string",
      "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

POST
/v1/leads

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
salutationstring
firstNameRequiredstring
lastNameRequiredstring
companystring
titlestring
emailstring
Format: "email"
phonestring
websitestring
leadSourcestring
Value in: "OTHER" | "WEB" | "PHONE_INQUIRY" | "PARTNER_REFERRAL" | "PURCHASED_LIST" | "EXTERNAL_REFERRAL" | "EMPLOYEE_REFERRAL" | "TRADE_SHOW" | "WEB_FORM" | "SOCIAL_MEDIA" | "EMAIL_CAMPAIGN" | "WEBINAR" | "COLD_CALL"
statusstring
Value in: "NEW" | "CONTACTED" | "QUALIFIED" | "UNQUALIFIED" | "NURTURING" | "CONVERTED" | "LOST"
ratingstring
Value in: "HOT" | "WARM" | "COLD"
industrystring
numberOfEmployeesnumber
annualRevenuenumber
streetstring
citystring
statestring
postalCodestring
countrystring
descriptionstring
painPointsarray<string>
budgetnumber
timelinestring

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/leads" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "salutation": "string",
    "firstName": "string",
    "lastName": "string",
    "company": "string",
    "title": "string",
    "email": "[email protected]",
    "phone": "string",
    "website": "string",
    "leadSource": "OTHER",
    "status": "NEW",
    "rating": "HOT",
    "industry": "string",
    "numberOfEmployees": 0,
    "annualRevenue": 0,
    "street": "string",
    "city": "string",
    "state": "string",
    "postalCode": "string",
    "country": "string",
    "description": "string",
    "painPoints": [
      "string"
    ],
    "budget": 0,
    "timeline": "string"
  }'

Lead

{
  "id": "string",
  "ownerId": "string",
  "organizationId": "string",
  "salesforceId": "string",
  "salutation": "string",
  "firstName": "string",
  "lastName": "string",
  "company": "string",
  "title": "string",
  "email": "string",
  "phone": "string",
  "website": "string",
  "leadSource": "WEB",
  "status": "NEW",
  "rating": "HOT",
  "industry": "string",
  "numberOfEmployees": 0,
  "annualRevenue": 0,
  "street": "string",
  "city": "string",
  "state": "string",
  "postalCode": "string",
  "country": "string",
  "isQualified": true,
  "qualifiedDate": "2019-08-24T14:15:22Z",
  "disqualifiedReason": "string",
  "leadScore": 0,
  "buyingIntent": "HIGH",
  "description": "string",
  "painPoints": [
    "string"
  ],
  "budget": 0,
  "timeline": "string",
  "convertedDate": "2019-08-24T14:15:22Z",
  "convertedAccountId": "string",
  "convertedContactId": "string",
  "convertedOpportunityId": "string",
  "tags": [
    "string"
  ],
  "lastContactedAt": "2019-08-24T14:15:22Z",
  "assignedAt": "2019-08-24T14:15:22Z",
  "firstTouchAt": "2019-08-24T14:15:22Z",
  "territoryId": "string",
  "metadata": null,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Get stats

GET
/v1/leads/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/leads/stats" \
  -H "Authorization: Bearer <token>"

Get speed to lead

GET
/v1/leads/stats/speed-to-lead

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

daysstring
curl -X GET "https://api.salesos.org/v1/leads/stats/speed-to-lead?days=%3Cstring%3E" \
  -H "Authorization: Bearer <token>"

List deleted

GET
/v1/leads/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/leads/deleted" \
  -H "Authorization: Bearer <token>"

LeadArray

[
  {
    "id": "string",
    "ownerId": "string",
    "organizationId": "string",
    "salesforceId": "string",
    "salutation": "string",
    "firstName": "string",
    "lastName": "string",
    "company": "string",
    "title": "string",
    "email": "string",
    "phone": "string",
    "website": "string",
    "leadSource": "WEB",
    "status": "NEW",
    "rating": "HOT",
    "industry": "string",
    "numberOfEmployees": 0,
    "annualRevenue": 0,
    "street": "string",
    "city": "string",
    "state": "string",
    "postalCode": "string",
    "country": "string",
    "isQualified": true,
    "qualifiedDate": "2019-08-24T14:15:22Z",
    "disqualifiedReason": "string",
    "leadScore": 0,
    "buyingIntent": "HIGH",
    "description": "string",
    "painPoints": [
      "string"
    ],
    "budget": 0,
    "timeline": "string",
    "convertedDate": "2019-08-24T14:15:22Z",
    "convertedAccountId": "string",
    "convertedContactId": "string",
    "convertedOpportunityId": "string",
    "tags": [
      "string"
    ],
    "lastContactedAt": "2019-08-24T14:15:22Z",
    "assignedAt": "2019-08-24T14:15:22Z",
    "firstTouchAt": "2019-08-24T14:15:22Z",
    "territoryId": "string",
    "metadata": null,
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
]

Find one

GET
/v1/leads/{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/leads/<string>" \
  -H "Authorization: Bearer <token>"

Lead

{
  "id": "string",
  "ownerId": "string",
  "organizationId": "string",
  "salesforceId": "string",
  "salutation": "string",
  "firstName": "string",
  "lastName": "string",
  "company": "string",
  "title": "string",
  "email": "string",
  "phone": "string",
  "website": "string",
  "leadSource": "WEB",
  "status": "NEW",
  "rating": "HOT",
  "industry": "string",
  "numberOfEmployees": 0,
  "annualRevenue": 0,
  "street": "string",
  "city": "string",
  "state": "string",
  "postalCode": "string",
  "country": "string",
  "isQualified": true,
  "qualifiedDate": "2019-08-24T14:15:22Z",
  "disqualifiedReason": "string",
  "leadScore": 0,
  "buyingIntent": "HIGH",
  "description": "string",
  "painPoints": [
    "string"
  ],
  "budget": 0,
  "timeline": "string",
  "convertedDate": "2019-08-24T14:15:22Z",
  "convertedAccountId": "string",
  "convertedContactId": "string",
  "convertedOpportunityId": "string",
  "tags": [
    "string"
  ],
  "lastContactedAt": "2019-08-24T14:15:22Z",
  "assignedAt": "2019-08-24T14:15:22Z",
  "firstTouchAt": "2019-08-24T14:15:22Z",
  "territoryId": "string",
  "metadata": null,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Update

PATCH
/v1/leads/{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
statusstring
Value in: "NEW" | "CONTACTED" | "QUALIFIED" | "UNQUALIFIED" | "NURTURING" | "CONVERTED" | "LOST"
ratingstring
Value in: "HOT" | "WARM" | "COLD"
isQualifiedboolean
disqualifiedReasonstring
leadScorenumber
buyingIntentstring
Value in: "HIGH" | "MEDIUM" | "LOW" | "UNKNOWN"
ownerIdstring

Reassign; must be an active member of the caller's organization.

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/leads/<string>" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "NEW",
    "rating": "HOT",
    "isQualified": true,
    "disqualifiedReason": "string",
    "leadScore": 0,
    "buyingIntent": "HIGH",
    "ownerId": "string"
  }'

Lead

{
  "id": "string",
  "ownerId": "string",
  "organizationId": "string",
  "salesforceId": "string",
  "salutation": "string",
  "firstName": "string",
  "lastName": "string",
  "company": "string",
  "title": "string",
  "email": "string",
  "phone": "string",
  "website": "string",
  "leadSource": "WEB",
  "status": "NEW",
  "rating": "HOT",
  "industry": "string",
  "numberOfEmployees": 0,
  "annualRevenue": 0,
  "street": "string",
  "city": "string",
  "state": "string",
  "postalCode": "string",
  "country": "string",
  "isQualified": true,
  "qualifiedDate": "2019-08-24T14:15:22Z",
  "disqualifiedReason": "string",
  "leadScore": 0,
  "buyingIntent": "HIGH",
  "description": "string",
  "painPoints": [
    "string"
  ],
  "budget": 0,
  "timeline": "string",
  "convertedDate": "2019-08-24T14:15:22Z",
  "convertedAccountId": "string",
  "convertedContactId": "string",
  "convertedOpportunityId": "string",
  "tags": [
    "string"
  ],
  "lastContactedAt": "2019-08-24T14:15:22Z",
  "assignedAt": "2019-08-24T14:15:22Z",
  "firstTouchAt": "2019-08-24T14:15:22Z",
  "territoryId": "string",
  "metadata": null,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Remove

DELETE
/v1/leads/{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/leads/<string>" \
  -H "Authorization: Bearer <token>"

MessageResponse

{
  "message": "string"
}

Restore

POST
/v1/leads/{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/leads/<string>/restore" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>"

Lead

{
  "id": "string",
  "ownerId": "string",
  "organizationId": "string",
  "salesforceId": "string",
  "salutation": "string",
  "firstName": "string",
  "lastName": "string",
  "company": "string",
  "title": "string",
  "email": "string",
  "phone": "string",
  "website": "string",
  "leadSource": "WEB",
  "status": "NEW",
  "rating": "HOT",
  "industry": "string",
  "numberOfEmployees": 0,
  "annualRevenue": 0,
  "street": "string",
  "city": "string",
  "state": "string",
  "postalCode": "string",
  "country": "string",
  "isQualified": true,
  "qualifiedDate": "2019-08-24T14:15:22Z",
  "disqualifiedReason": "string",
  "leadScore": 0,
  "buyingIntent": "HIGH",
  "description": "string",
  "painPoints": [
    "string"
  ],
  "budget": 0,
  "timeline": "string",
  "convertedDate": "2019-08-24T14:15:22Z",
  "convertedAccountId": "string",
  "convertedContactId": "string",
  "convertedOpportunityId": "string",
  "tags": [
    "string"
  ],
  "lastContactedAt": "2019-08-24T14:15:22Z",
  "assignedAt": "2019-08-24T14:15:22Z",
  "firstTouchAt": "2019-08-24T14:15:22Z",
  "territoryId": "string",
  "metadata": null,
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}

Score lead

POST
/v1/leads/{id}/score

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/leads/<string>/score" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>"

Convert lead

POST
/v1/leads/{id}/convert

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
createAccountboolean
Default: true
createContactboolean
Default: true
createOpportunityboolean
Default: true
opportunityNamestring
opportunityAmountnumber
accountNamestring
existingAccountIdstring
opportunityCloseDatestring
opportunityStageIdstring

Pipeline stage for the new deal; defaults to the first open stage of the default pipeline.

qualifyboolean

Qualify an unqualified lead as part of converting it.

ownerIdstring

Owner for the created records; defaults to the lead's owner (not the converting user).

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/leads/<string>/convert" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "createAccount": true,
    "createContact": true,
    "createOpportunity": true,
    "opportunityName": "string",
    "opportunityAmount": 0,
    "accountName": "string",
    "existingAccountId": "string",
    "opportunityCloseDate": "string",
    "opportunityStageId": "string",
    "qualify": true,
    "ownerId": "string"
  }'

LeadConversionResult

{
  "accountId": "string",
  "contactId": "string",
  "opportunityId": "string",
  "reusedAccountId": "string",
  "reusedContactId": "string"
}

Bulk update

POST
/v1/leads/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/leads/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/leads/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/leads/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/leads/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/leads/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"
    }
  ]
}

Users

User profile and preferences

Contacts

Contact records and relationships