openapi: 3.2.0
info:
  title: Sendoso Users API
  contact:
    name: Sendoso Developer Support
    email: developers@sendoso.com
    url: https://developer.sendoso.com/
  x-generated-by: API Evangelist enrichment pipeline (local-v1)
  x-generated-from: documentation
  x-generated-on: '2026-08-13'
  x-refined-note:
  - x-source-docs differs across the merged source definitions and was not carried
  version: '1.0'
  description: 'Operations tagged Users across 2 of this provider''s published API definitions: sendoso-core-api-openapi.yml, sendoso-scim-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://app.sendoso.com
  description: Production
- url: https://app.staging.sendo.so
  description: Sandbox / staging (declared in Sendoso's own reference-page code samples)
tags:
- name: Users
  description: Read the authorized user, list organization users, invite new users.
paths:
  /api/v3/me:
    get:
      operationId: getCurrentUser
      summary: Get Current User
      description: Get information about the current authorized user.
      tags:
      - Users
      externalDocs:
        url: https://developer.sendoso.com/rest-api/reference/users/get-current-user
      responses:
        '200':
          description: The authorized user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrentUser'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - OAuth2: []
    servers:
    - url: https://app.sendoso.com
      description: Production
    - url: https://app.staging.sendo.so
      description: Sandbox / staging (declared in Sendoso's own reference-page code samples)
  /api/v3/users:
    get:
      operationId: getUsers
      summary: Get All Users
      description: Retrieve a paginated list of all active users associated to the organization.
      tags:
      - Users
      externalDocs:
        url: https://developer.sendoso.com/rest-api/reference/users/get-users
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: A page of users.
          content:
            application/json:
              schema:
                type: object
                required:
                - current_page
                - per_page
                - total_users
                - users
                properties:
                  current_page:
                    type: integer
                    description: The current page being returned.
                  per_page:
                    type: integer
                    description: The number of results being returned per page.
                  total_users:
                    type: integer
                    description: The total number of users.
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - OAuth2: []
    post:
      operationId: inviteUser
      summary: Invite New User
      description: Create a new user invitation for a specific team group.
      tags:
      - Users
      externalDocs:
        url: https://developer.sendoso.com/rest-api/reference/users/invite-user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - user
              properties:
                user:
                  type: object
                  required:
                  - first_name
                  - last_name
                  - email
                  - role
                  - team_group_id
                  properties:
                    first_name:
                      type: string
                      description: The new user's first name.
                    last_name:
                      type: string
                      description: The new user's last name.
                    email:
                      type: string
                      description: The new user's email address.
                    role:
                      type: string
                      enum:
                      - regular
                      - manager
                      description: The new user's role.
                    team_group_id:
                      type: integer
                      description: The ID of the team to invite the user to. Obtain it from GET /api/v3/groups.
      responses:
        '201':
          description: Invitation created.
          content:
            application/json:
              schema:
                type: object
                required:
                - success
                - message
                - receiver_email
                - team_group_id
                - user_role
                - invitation_status
                - expires_at
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  receiver_email:
                    type: string
                  team_group_id:
                    type: integer
                  user_role:
                    type: string
                  invitation_status:
                    type: string
                    enum:
                    - pending
                    - accepted
                    - expired
                  expires_at:
                    type: string
                    description: When the invitation expires, in ISO 8601 format.
        '400':
          description: 'Bad request. Documented messages include "Please enter a valid team group" and "Role can be one of these: manager,regular".'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security:
      - OAuth2: []
    servers:
    - url: https://app.sendoso.com
      description: Production
    - url: https://app.staging.sendo.so
      description: Sandbox / staging (declared in Sendoso's own reference-page code samples)
  /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_2'
        '429':
          $ref: '#/components/responses/TooManyRequests_2'
      security:
      - OAuth2:
        - scim
    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_2'
        '401':
          $ref: '#/components/responses/Unauthorized_2'
        '429':
          $ref: '#/components/responses/TooManyRequests_2'
      security:
      - OAuth2:
        - scim
    servers:
    - url: https://app.sendoso.com
      description: Production
  /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_2'
        '401':
          $ref: '#/components/responses/Unauthorized_2'
        '404':
          description: User not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error_2'
        '429':
          $ref: '#/components/responses/TooManyRequests_2'
      security:
      - OAuth2:
        - scim
    servers:
    - url: https://app.sendoso.com
      description: Production
components:
  responses:
    Unauthorized:
      description: 'Unauthorized. Documented message: "The access token is invalid".'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Too Many Requests. Sendoso throttles application clients sending more than 10 requests/second; the client is temporarily blocked from making further requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized_2:
      description: Unauthorized.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
    TooManyRequests_2:
      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_2'
  schemas:
    User:
      type: object
      required:
      - id
      - first_name
      - last_name
      - email
      - team_group_id
      properties:
        id:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
        team_group_id:
          type: number
    Error:
      type: object
      description: Sendoso's error envelope. Not RFC 9457 problem+json — errors are returned as `application/json` with a `success` flag and a human-readable `message`. Some documented 401 bodies use `description` and `expired` instead of `message`.
      properties:
        success:
          type: boolean
        message:
          type: string
        description:
          type: string
        expired:
          type: boolean
    CurrentUser:
      type: object
      required:
      - id
      - first_name
      - last_name
      - email
      - role
      - balance
      - team_balance
      properties:
        id:
          type: integer
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
        role:
          type: string
        balance:
          type: string
          description: The user's personal balance.
        team_balance:
          type: integer
          description: The sum of all the users' balance.
    Error_2:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
    ScimName:
      type: object
      required:
      - givenName
      - familyName
      properties:
        givenName:
          type: string
        familyName:
          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.
    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
  parameters:
    PerPage:
      name: per_page
      in: query
      required: false
      description: The number of results to be returned per page. Max is 100.
      schema:
        type: integer
        maximum: 100
    Page:
      name: page
      in: query
      required: false
      description: The page number of the results you want to retrieve. The first page is 1.
      schema:
        type: integer
        minimum: 1
  securitySchemes:
    OAuth2:
      type: oauth2
      description: 'OAuth 2.0 Authorization Code grant. Register your application by contacting developers@sendoso.com to receive a client ID and client secret. Access tokens live 7200 seconds (2 hours) and are refreshed at the same token endpoint. Tokens are sent as `Authorization: Bearer <token>`.'
      flows:
        authorizationCode:
          authorizationUrl: https://app.sendoso.com/oauth/authorize
          tokenUrl: https://app.sendoso.com/oauth/token
          refreshUrl: https://app.sendoso.com/oauth/token
          scopes:
            public: Access the user's basic information.
            write: Send gifts on the user's behalf.
            update: Update the user's account details.
            marketplace: Access the marketplace API.
            smartsend: Access the smartsend API.
x-refined-from:
- sendoso-core-api-openapi.yml
- sendoso-scim-api-openapi.yml