openapi: 3.1.0
info:
  title: Sendoso SCIM API
  version: '2.0'
  summary: SCIM 2.0 user provisioning and deprovisioning for the Sendoso platform.
  description: >-
    Sendoso implements the SCIM Version 2.0 protocol so identity providers can automatically
    provision users, assign them to teams, manage their roles, and deprovision them.


    Sendoso does not publish an OpenAPI document. This description was generated by API
    Evangelist from Sendoso's own published reference pages at https://developer.sendoso.com —
    every path, method, parameter and response field below is traceable to the page named in
    that operation's `externalDocs`.
  contact:
    name: Sendoso Developer Support
    email: developers@sendoso.com
    url: https://developer.sendoso.com/
  x-generated-from: documentation
  x-generated-by: API Evangelist enrichment pipeline (local-v1)
  x-generated-on: '2026-08-13'
  x-source-docs: https://developer.sendoso.com/scim/overview/introduction
servers:
  - url: https://app.sendoso.com
    description: Production
externalDocs:
  description: Sendoso SCIM documentation
  url: https://developer.sendoso.com/scim/overview/introduction
security:
  - OAuth2: [scim]
tags:
  - name: Users
    description: SCIM 2.0 User resource.
paths:
  /api/scim/v2/Users:
    get:
      operationId: scimGetUsers
      summary: Get All Users
      description: Get all users, as a SCIM 2.0 ListResponse.
      tags: [Users]
      externalDocs:
        url: https://developer.sendoso.com/scim/reference/get-users
      parameters:
        - name: startIndex
          in: query
          required: false
          description: >-
            The 1-based index of the first query result. A value less than 1 is interpreted
            as 1. Defaults to 1.
          schema:
            type: integer
        - name: count
          in: query
          required: false
          description: >-
            Desired maximum number of query results per page. If unspecified, the maximum
            is 100.
          schema:
            type: integer
      responses:
        '200':
          description: SCIM ListResponse.
          content:
            application/json:
              schema:
                type: object
                required: [schemas, itemsPerPage, startIndex, totalResults, Resources]
                properties:
                  schemas:
                    type: array
                    description: Always `urn:ietf:params:scim:api:messages:2.0:ListResponse`.
                    items:
                      type: string
                  itemsPerPage:
                    type: integer
                  startIndex:
                    type: integer
                  totalResults:
                    type: integer
                  Resources:
                    type: array
                    items:
                      $ref: '#/components/schemas/ScimUser'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    post:
      operationId: scimCreateUser
      summary: Create User
      description: Create a new user and assign them a role and a team.
      tags: [Users]
      externalDocs:
        url: https://developer.sendoso.com/scim/reference/create-users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScimUserWrite'
      responses:
        '201':
          description: User created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimUser'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/scim/v2/Users/{user_id}:
    put:
      operationId: scimUpdateUser
      summary: Update User
      description: Updates a user.
      tags: [Users]
      externalDocs:
        url: https://developer.sendoso.com/scim/reference/update-user
      parameters:
        - name: user_id
          in: path
          required: true
          description: The user's identifier.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScimUserWrite'
      responses:
        '200':
          description: User updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimUser'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: User not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: >-
        OAuth 2.0 Authorization Code grant with `scope=scim`. SCIM requires a client id and
        secret specific to the SCIM API, obtained from developers@sendoso.com; Core API
        credentials do not work here.
      flows:
        authorizationCode:
          authorizationUrl: https://app.sendoso.com/oauth/authorize
          tokenUrl: https://app.sendoso.com/oauth/token
          refreshUrl: https://app.sendoso.com/oauth/token
          scopes:
            scim: Access the SCIM API.
  responses:
    Unauthorized:
      description: Unauthorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: >-
        Too Many Requests. Sendoso does not publish a numeric SCIM limit; the documentation
        states only that exceeding it returns 429 and temporarily blocks further requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
    ScimName:
      type: object
      required: [givenName, familyName]
      properties:
        givenName:
          type: string
        familyName:
          type: string
    ScimUser:
      type: object
      required: [schemas, id, userName, active, name, emails]
      properties:
        schemas:
          type: array
          description: Always `urn:ietf:params:scim:schemas:core:2.0:User`.
          items:
            type: string
        id:
          type: string
        userName:
          type: string
          description: The user's email address.
        active:
          type: boolean
          description: Whether the user is active in the Sendoso platform.
        name:
          $ref: '#/components/schemas/ScimName'
        emails:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
    ScimUserWrite:
      type: object
      required: [userName, name, userType, division]
      properties:
        userName:
          type: string
          description: The user's email address.
        name:
          $ref: '#/components/schemas/ScimName'
        userType:
          type: string
          enum: [sender, manager, admin]
          description: The user's role.
        division:
          type: string
          description: >-
            The user's team. Must match the exact team group name in Sendoso — read them from
            GET /api/v3/groups on the Core API.