SalesOS

Bulk A P I

Asynchronous bulk import/export jobs

Your bulk jobs, newest first (ADMIN: the org’s)

GET
/v1/bulk/jobs

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

pagenumber
limitnumber
statusstring
curl -X GET "https://api.salesos.org/v1/bulk/jobs?page=0&limit=0&status=%3Cstring%3E" \
  -H "Authorization: Bearer <token>"

BulkJobPage

{
  "data": [
    {
      "id": "string",
      "object": "string",
      "operation": "insert",
      "externalIdField": "string",
      "contentType": "string",
      "status": "QUEUED",
      "totalRows": 0,
      "processedRows": 0,
      "successRows": 0,
      "failedRows": 0,
      "error": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "startedAt": "2019-08-24T14:15:22Z",
      "completedAt": "2019-08-24T14:15:22Z",
      "filesExpireAt": "2019-08-24T14:15:22Z",
      "links": {
        "self": "string",
        "results": "string",
        "failures": "string"
      }
    }
  ],
  "total": 0,
  "page": 0,
  "limit": 0,
  "totalPages": 0
}

Queue an async insert/upsert/update/delete/export job (CSV or JSON lines)

POST
/v1/bulk/jobs

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
objectRequiredstring

lead | contact | account | opportunity | task, or custom:

Pattern: "^(lead|contact|account|opportunity|task|custom:[a-z0-9_]{1,64})$"
operationRequiredstring
Value in: "insert" | "upsert" | "update" | "delete" | "export"
externalIdFieldstring

Upsert key (required for upsert; optional for update/delete, default "id"): a text column such as "email", or "customFields."

Maximum length: 100
contentTypestring

Input/export format. Inferred from the uploaded file name when omitted; records implies jsonl.

Value in: "csv" | "jsonl"
datastring

Inline CSV or JSON-lines input, instead of a multipart file upload

recordsarray<object>

Inline input rows as a JSON array (JSON body only) Items: at most 50000.

fieldsarray<string>

Export only: columns to include (comma-separated in multipart). Custom fields as customFields.. Items: at most 200.

filterobject

Export only: field equality filters on the object’s own columns, e.g. {"status":"NEW"}

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/bulk/jobs" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "object": "contact",
    "operation": "insert",
    "externalIdField": "email",
    "contentType": "csv",
    "data": "string",
    "records": [
      {}
    ],
    "fields": [
      "string"
    ],
    "filter": {}
  }'

BulkJobView

{
  "id": "string",
  "object": "string",
  "operation": "insert",
  "externalIdField": "string",
  "contentType": "string",
  "status": "QUEUED",
  "totalRows": 0,
  "processedRows": 0,
  "successRows": 0,
  "failedRows": 0,
  "error": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "startedAt": "2019-08-24T14:15:22Z",
  "completedAt": "2019-08-24T14:15:22Z",
  "filesExpireAt": "2019-08-24T14:15:22Z",
  "links": {
    "self": "string",
    "results": "string",
    "failures": "string"
  }
}

Job status and processed / failed counts

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

BulkJobView

{
  "id": "string",
  "object": "string",
  "operation": "insert",
  "externalIdField": "string",
  "contentType": "string",
  "status": "QUEUED",
  "totalRows": 0,
  "processedRows": 0,
  "successRows": 0,
  "failedRows": 0,
  "error": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "startedAt": "2019-08-24T14:15:22Z",
  "completedAt": "2019-08-24T14:15:22Z",
  "filesExpireAt": "2019-08-24T14:15:22Z",
  "links": {
    "self": "string",
    "results": "string",
    "failures": "string"
  }
}

Stop a queued or running job

POST
/v1/bulk/jobs/{id}/cancel

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/bulk/jobs/<string>/cancel" \
  -H "Idempotency-Key: <string>" \
  -H "Authorization: Bearer <token>"

BulkJobView

{
  "id": "string",
  "object": "string",
  "operation": "insert",
  "externalIdField": "string",
  "contentType": "string",
  "status": "QUEUED",
  "totalRows": 0,
  "processedRows": 0,
  "successRows": 0,
  "failedRows": 0,
  "error": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "startedAt": "2019-08-24T14:15:22Z",
  "completedAt": "2019-08-24T14:15:22Z",
  "filesExpireAt": "2019-08-24T14:15:22Z",
  "links": {
    "self": "string",
    "results": "string",
    "failures": "string"
  }
}

Download per-row results (row,id,action,externalId), or the exported records

GET
/v1/bulk/jobs/{id}/results

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/bulk/jobs/<string>/results" \
  -H "Authorization: Bearer <token>"

The file

"string"

Download failed rows (row,error,externalId,input)

GET
/v1/bulk/jobs/{id}/failures

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/bulk/jobs/<string>/failures" \
  -H "Authorization: Bearer <token>"

The file

"string"

Graph Q L POST

Read-only GraphQL over the CRM, including custom objects

Search

Global search across all entities