Как правильно выбрать версию при работе с публичным API вы можете посмотреть здесь.

При работе с внутренним API следует придерживаться следующих правил:

• Обязательно указывать версию используемого API.
• Для всех измененных API необходимо обязательно перейти на использование новой версии, так как к следующему релизу поддержка предыдущей версии прекратится.

Особенности версионирования публичного API:

• Новая версия размещается, если в публичном API появляются изменения, не обладающие обратной совместимостью с предыдущей версией API — т.е. в том случае, когда запрос к старой версии API не может быть обработан новой версией API.
• Версии публичного API нумеруются последовательно (начиная с 1.0).
• Используемая версия публичного API указывается в сегменте URL-запроса — невозможно обратиться к публичному API, не указав версию (например, https://yourinstance.case.one/swagger/index.html?urls.primaryName=v3).

Публичный API может быть версии 1.0, 2.0, 3.0 или 4.0:

• Если вы давно используете API Case.one, то, возможно, у вас настроена интеграция через API 1.0 — в таком случае, используйте версию 1.0 (она тоже работает, просто содержит меньшее количество конечных точек).
• Версия 2.0 более полная, охватывает большее количество конечных точек. Если вы новый клиент, мы рекомендуем использовать именно ее.
• Версия 3.0 содержит группы методов, которые работают через связку Тег — Значение и позволяют обрабатывать сущности Case.one, содержащие дополнительные атрибуты.
• Версия 4.0 содержит группы методов, которые позволяют:
  • Настраивать права для роли
  • Обрабатывать новые системные поля карточки участника Телефон и Электронная почта