generated: '2026-08-13'
method: searched
source: >-
  https://developer.zendesk.com/api-reference/sales-crm/requests/ and
  https://developer.zendesk.com/api-reference/sales-crm/errors/
base_url: https://api.getbase.com
authentication:
  style: oauth2-bearer
  header: 'Authorization: Bearer <access_token>'
  detail: authentication/zendesk-sell-authentication.yml
  scopes: scopes/zendesk-sell-scopes.yml
envelope:
  request: >-
    Requests wrap the payload in a `data` object; `meta/type` may be supplied to name the
    object type.
  response: >-
    Responses wrap the payload in `data` with a sibling `meta` object. Collection responses
    return an `items` array, each element carrying its own `data` + `meta`.
  content_type: application/json
  accept: application/json
pagination:
  style: page-number
  params:
    page: 1-based page index, default 1
    per_page: page size, default 25, maximum 100
  example: "?page=2&per_page=100"
  response_fields: []
  note: >-
    Offset/page pagination only — no cursor and no documented total-count or next-link field
    in `meta`. Firehose streams paginate by `position` (top/tail/opaque string) + `limit`
    (1-100, default 25) instead; see asyncapi/zendesk-sell-firehose-events.yml.
sorting:
  param: sort_by
  default_direction: asc
  syntax: "sort_by=first_name:desc"
  custom_fields: "sort_by=custom_fields:fieldname:desc"
filtering:
  style: query-parameter
  examples:
  - "?contact_id=1&city=NY"
  - "?ids=1,2,3"
  - "?custom_fields[sku]=SKU1"
  note: >-
    Custom fields are only filterable when the field is marked "Filterable" in the Sell
    admin UI. Complex boolean filters and aggregations are the job of the separate Search
    API (https://developer.zendesk.com/api-reference/sales-crm/search/introduction).
field_expansion:
  supported: false
  note: No expand / sparse-fieldset parameter is documented for the Core API.
metadata:
  supported: true
  mechanism: custom_fields
  note: >-
    Arbitrary key/value data is carried on the `custom_fields` object of leads, contacts and
    deals; fields must be defined in the account first. There is no free-form `metadata` bag.
idempotency:
  supported: false
  header: null
  note: >-
    Zendesk publishes NO idempotency-key contract for the Sell API — no Idempotency-Key
    header, no request-deduplication window, and no idempotency parameter appears in the
    OpenAPI. The closest primitive is the upsert family (POST /v2/leads/upsert,
    /v2/contacts/upsert, /v2/deals/upsert), which matches on caller-supplied business
    attributes and creates-or-updates; that makes the OPERATION repeatable in effect but is
    not a replay-safe idempotency key — a retry with different matching params creates a new
    record. No `Idempotency` pointer is emitted for this provider.
request_tracing:
  header: X-Request-Id
  echoed_in: meta.logref
  note: >-
    Error responses carry `meta.logref`, "a unique request identifier" that matches the
    X-Request-Id response header — the value to quote to Zendesk support.
versioning:
  style: uri-path
  current: v2
  pattern: https://api.getbase.com/{api-version}/{resource}
  detail: lifecycle/zendesk-sell-lifecycle.yml
required_headers:
  User-Agent:
    required: true
    note: >-
      Requests without a User-Agent are rejected with HTTP 400 and error code
      `invalid_user_agent`. This is unusual and trips most default HTTP clients that omit
      the header.
  Accept-Language:
    required: false
    note: ISO-639 language + ISO-3166 country codes; controls the language of error `message`.
datetime:
  format: ISO 8601
  timezone: UTC
  sentinel: '9999-12-31T00:00:00Z means "forever"'
error_envelope:
  shape: >-
    { "errors": [ { "error": { "code", "message", "details", "resource", "field" } } ],
    "meta": { "http_status", "logref", "links" } }
  problem_json: false
  detail: errors/zendesk-sell-problem-types.yml
rate_limit_signaling:
  headers: []
  status: 429
  detail: rate-limits/zendesk-sell-rate-limits.yml
  note: No rate-limit headers are documented; 429 + error code rate_limit_exceeded is the only signal.
x-evidence:
- url: https://developer.zendesk.com/api-reference/sales-crm/requests/
  status: 200
- url: https://developer.zendesk.com/api-reference/sales-crm/errors/
  status: 200