Decisiv SRM Gateway - Account Management

openapi: 3.1.0
info:
  version: 0.48.24
  termsOfService: https://www.decisiv.com/terms-of-use
  contact:
    name: Decisiv Support
    email: support@decisiv.com
    url: https://www.decisiv.com
  title: Account Management
  description: Inside of **Decisiv SRM Gateway**, the `Account Management` module represents all the accounts the current
    user has access granted to
  license:
    name: Proprietary
    identifier: proprietary
    url: https://www.decisiv.com/terms-of-use/
servers:
- url: https://srm-api.staging.decisivapps.com
- url: https://srm-api.decisivapps.com
security:
- OAuth2AuthorizationCode: []
  AccessToken: []
- OAuth2Password: []
  AccessToken: []
paths:
  /account_management/v1/accounts:
    get:
      summary: List all Accounts the current user has access granted to
      description: Returns the accounts the authenticated user has been granted access to, with pagination and filtering.
        Supports `?include=roles` to sideload the user's RBAC roles on each account; when present, each account gains a `relationships.roles`
        object and the related role resources are returned in the top-level `included` array.
      tags:
      - Accounts
      operationId: getAccounts
      parameters:
      - name: include
        in: query
        required: false
        schema:
          type: string
          enum:
          - roles
        description: Sideload related resources (e.g. `roles`)
      - name: page[number]
        in: query
        required: false
        schema:
          type: integer
          default: 1
          minimum: 1
        description: Sets the desired `page` when encountering larger result sets
      - name: page[size]
        in: query
        required: false
        schema:
          type: integer
          default: 25
          minimum: 1
        description: Sets the desired maximum number of results per page
      - name: filter[name]
        in: query
        required: false
        schema:
          type: string
          minLength: 3
          maxLength: 255
        description: List `accounts` that match the `name` attribute. Cannot be combined with `filter[name:like]`.
      - name: filter[name:like]
        in: query
        required: false
        schema:
          type: string
          minLength: 3
          maxLength: 255
        description: List `accounts` that match partially the `name` attribute. Cannot be combined with `filter[name]`. in
          the value are matched as literal characters, not wildcards.
      - name: filter[external_reference.decisiv]
        in: query
        required: false
        schema:
          type: string
        description: List `accounts` that match the `decisiv` attribute inside the external_reference object.
      - name: filter[external_reference.srm_account]
        in: query
        required: false
        schema:
          type: string
        description: List `accounts` that match the `srm_account` attribute inside the external_reference object.
      - name: filter[external_reference.business_system]
        in: query
        required: false
        schema:
          type: string
        description: List `accounts` that match the `business_system` attribute inside the external_reference object.
      - name: filter[module_subscriptions.key:include]
        in: query
        required: false
        deprecated: true
        schema:
          type: array
          items:
            type: string
            enum:
            - account_management
            - asset_management
            - maintenance
            - service_management
            - telematics
        description: '**Deprecated** — use `filter[module_subscriptions.key:includes]` instead. List `accounts` that have
          the modules chosen in the filter. Accepts up to 50 comma-separated values.'
      - name: filter[module_subscriptions.key:exclude]
        in: query
        required: false
        deprecated: true
        schema:
          type: array
          items:
            type: string
            enum:
            - account_management
            - asset_management
            - maintenance
            - service_management
            - telematics
        description: '**Deprecated** — use `filter[module_subscriptions.key:excludes]` instead. List `accounts` that does
          not have the modules chosen in the filter. Accepts up to 50 comma-separated values.'
      - name: filter[module_subscriptions.key:includes]
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - account_management
            - asset_management
            - maintenance
            - service_management
            - telematics
        description: List `accounts` that have the modules chosen in the filter. Accepts up to 50 comma-separated values.
      - name: filter[module_subscriptions.key:excludes]
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - account_management
            - asset_management
            - maintenance
            - service_management
            - telematics
        description: List `accounts` that does not have the modules chosen in the filter. Accepts up to 50 comma-separated
          values.
      responses:
        '200':
          description: Returns list of accounts
          content:
            application/vnd.api+json:
              examples:
                WithoutInclude:
                  summary: Default response (no ?include=roles)
                  description: Accounts are returned without a `relationships.roles` object and without a top-level `included`
                    array.
                  value:
                    data:
                    - type: accounts
                      id: 7b86dc31-4ae3-4710-aab4-0e7d10f5dffc
                      attributes:
                        name: Southbound Trucking
                        address1: 1000 Little Martha Lane
                        address2: ''''
                        city: Macon
                        state: GA
                        country: US
                        postal_code: '31204'
                        phone: '+14157894567'
                        fax: '+14157894567'
                        email: southbound.trucking@example.com
                        external_reference:
                          business_system: ''
                          dms: ''
                          decisiv: EATAPEACH
                          srm_account: AB1-532
                        module_subscriptions:
                        - key: account_management
                          name: Account Management
                          description: Handles user permissions, business relationships, and core account settings across
                            the SRM platform
                        - key: asset_management
                          name: Asset Management
                          description: Allows fleet / asset operators to track, manage and maintain their vehicles/assets
                            across their entire lifecycle
                        - key: maintenance
                          name: Maintenance
                          description: Helps consumers plan and execute preventive maintenance programs to reduce downtime
                            and extend asset life
                        - key: service_management
                          name: Service Management
                          description: Enables service providers to manage repairs, estimates, and workflow for commercial
                            vehicle maintenance and repairs
                        - key: telematics
                          name: Telematics
                          description: Provides real-time vehicle data, diagnostics, and location tracking to optimize asset
                            operations and maintenance
                WithInclude:
                  summary: Response with ?include=roles
                  description: Each account carries a `relationships.roles` object and the related role resources are returned
                    in the top-level `included` array. Both public and private (account-owned) roles are reflected.
                  value:
                    data:
                    - type: accounts
                      id: 7b86dc31-4ae3-4710-aab4-0e7d10f5dffc
                      attributes:
                        name: Southbound Trucking
                        external_reference:
                          decisiv: EATAPEACH
                          srm_account: AB1-532
                      relationships:
                        roles:
                          data:
                          - type: roles
                            id: 58295ebf-2cd5-4540-aef5-786739cbe07a
                          - type: roles
                            id: 1d9a0ad3-1922-4ace-a647-581c98b30b92
                    included:
                    - type: roles
                      id: 58295ebf-2cd5-4540-aef5-786739cbe07a
                      attributes:
                        name: Fleet Administrator
                        description: Full administrative access to the account
                        public: true
                        permissions:
                        - assets:read
                        - assets:write
                    - type: roles
                      id: 1d9a0ad3-1922-4ace-a647-581c98b30b92
                      attributes:
                        name: Billing Approver
                        description: Account-owned custom role
                        public: false
                        permissions:
                        - invoices:approve
              schema:
                $ref: '#/components/schemas/accounts'
        '400':
          description: This response may occur when an invalid request has been provided to the server.  The request may be
            corrected by the consumer and resubmitted.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/errors_response'
              examples:
                Filter not allowed:
                  value:
                    errors:
                    - title: Filter not allowed
                      detail: '''{{filter_name}}'' is not allowed. Valid filters: {{filters_list}}'
                      code: decisiv:filters:001
                      status: '400'
                      source:
                        parameter: filter[filter_name]
                Conflicting filters:
                  value:
                    errors:
                    - title: Conflicting filters
                      detail: Cannot combine filter[name] with its :like variant. Use only one.
                      code: decisiv:filters:012
                      status: '400'
                      source:
                        parameter: filter[name]
                Too many filter values:
                  value:
                    errors:
                    - title: Too many filter values
                      detail: 'Too many values for filter[module_subscriptions.key:include]. Maximum allowed: 50.'
                      code: decisiv:filters:011
                      status: '400'
                      source:
                        parameter: filter[module_subscriptions.key:include]
                Filter value too long:
                  value:
                    errors:
                    - title: Maximum character length not met
                      detail: Filter value must be less than 4096 characters
                      code: decisiv:filters:008
                      status: '400'
                      source:
                        parameter: filter[external_reference.decisiv]
                Invalid filter characters:
                  value:
                    errors:
                    - title: Invalid filter characters
                      detail: Filter value for filter[name] contains invalid characters.
                      code: decisiv:filters:013
                      status: '400'
                      source:
                        parameter: filter[name]
                Invalid filter shape:
                  value:
                    errors:
                    - title: Invalid filter value shape
                      detail: Filter value for filter[name] must be a string.
                      code: decisiv:filters:014
                      status: '400'
                      source:
                        parameter: filter[name]
        '401':
          description: This response may occur when the access token provided within the Authorization token has expired.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Access unauthorized
                  detail: Access unauthorized
                  code: decisiv::access_token:001
                  status: '401'
              schema:
                $ref: '#/components/schemas/errors_response'
        '403':
          description: This response may occur when the authenticated user embedded within the Authorization header does not
            have access to the requested resource.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Forbidden
                  detail: User does not have permission to perform this action on the requested resource(s)
                  code: decisiv:access:001
                  status: '403'
              schema:
                $ref: '#/components/schemas/errors_response'
        '504':
          description: This response may occur when there is an unexpected system timeout.
          content:
            application/vnd.api+json:
              example:
                errors:
                - code: '504'
                  detail: Gateway timeout error
                  status: '504'
                  title: Gateway timeout error
              schema:
                $ref: '#/components/schemas/errors_response'
  /account_management/v1/accounts/{account_id}:
    get:
      summary: List details on a specific Account
      description: Returns the details of a single account the authenticated user has access to. Supports `?include=roles`
        to sideload the user's RBAC roles on the account; when present, the account gains a `relationships.roles` object and
        the related role resources are returned in the top-level `included` array.
      tags:
      - Accounts
      operationId: getAccountsById
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
      - name: include
        in: query
        required: false
        schema:
          type: string
          enum:
          - roles
        description: Sideload related resources (e.g. `roles`)
      responses:
        '200':
          description: Show details for requested Account
          content:
            application/vnd.api+json:
              examples:
                WithoutInclude:
                  summary: Default response (no ?include=roles)
                  description: The account is returned without a `relationships.roles` object and without a top-level `included`
                    array.
                  value:
                    data:
                      type: accounts
                      id: 7b86dc31-4ae3-4710-aab4-0e7d10f5dffc
                      attributes:
                        name: Southbound Trucking
                        address1: 1000 Little Martha Lane
                        address2: ''''
                        city: Macon
                        state: GA
                        country: US
                        postal_code: '31204'
                        phone: '+14157894567'
                        fax: '+14157894567'
                        email: southbound.trucking@example.com
                        external_reference:
                          business_system: ''
                          dms: ''
                          decisiv: EATAPEACH
                          srm_account: AB1-532
                        module_subscriptions:
                        - key: account_management
                          name: Account Management
                          description: Handles user permissions, business relationships, and core account settings across
                            the SRM platform
                        - key: asset_management
                          name: Asset Management
                          description: Allows fleet / asset operators to track, manage and maintain their vehicles/assets
                            across their entire lifecycle
                        - key: maintenance
                          name: Maintenance
                          description: Helps consumers plan and execute preventive maintenance programs to reduce downtime
                            and extend asset life
                        - key: service_management
                          name: Service Management
                          description: Enables service providers to manage repairs, estimates, and workflow for commercial
                            vehicle maintenance and repairs
                        - key: telematics
                          name: Telematics
                          description: Provides real-time vehicle data, diagnostics, and location tracking to optimize asset
                            operations and maintenance
                WithInclude:
                  summary: Response with ?include=roles
                  description: The account carries a `relationships.roles` object and the related role resources are returned
                    in the top-level `included` array. Both public and private (account-owned) roles are reflected.
                  value:
                    data:
                      type: accounts
                      id: 7b86dc31-4ae3-4710-aab4-0e7d10f5dffc
                      attributes:
                        name: Southbound Trucking
                        external_reference:
                          decisiv: EATAPEACH
                          srm_account: AB1-532
                      relationships:
                        roles:
                          data:
                          - type: roles
                            id: 58295ebf-2cd5-4540-aef5-786739cbe07a
                          - type: roles
                            id: 1d9a0ad3-1922-4ace-a647-581c98b30b92
                    included:
                    - type: roles
                      id: 58295ebf-2cd5-4540-aef5-786739cbe07a
                      attributes:
                        name: Fleet Administrator
                        description: Full administrative access to the account
                        public: true
                        permissions:
                        - assets:read
                        - assets:write
                    - type: roles
                      id: 1d9a0ad3-1922-4ace-a647-581c98b30b92
                      attributes:
                        name: Billing Approver
                        description: Account-owned custom role
                        public: false
                        permissions:
                        - invoices:approve
              schema:
                $ref: '#/components/schemas/account_by_id'
        '401':
          description: This response may occur when the access token provided within the Authorization token has expired.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Access unauthorized
                  detail: Access unauthorized
                  code: decisiv::access_token:001
                  status: '401'
              schema:
                $ref: '#/components/schemas/errors_response'
        '403':
          description: This response may occur when the authenticated user embedded within the Authorization header does not
            have access to the requested resource.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Forbidden
                  detail: User does not have permission to perform this action on the requested resource(s)
                  code: decisiv:access:001
                  status: '403'
              schema:
                $ref: '#/components/schemas/errors_response'
        '404':
          description: This response may occur when the requested resource is not found.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Record not found
                  detail: The requested record or one of its relationships could not be found
                  code: '404'
                  status: '404'
              schema:
                $ref: '#/components/schemas/errors_response'
        '504':
          description: This response may occur when there is an unexpected system timeout.
          content:
            application/vnd.api+json:
              example:
                errors:
                - code: '504'
                  detail: Gateway timeout error
                  status: '504'
                  title: Gateway timeout error
              schema:
                $ref: '#/components/schemas/errors_response'
  /account_management/v1/accounts/{account_id}/ecosystem_users:
    get:
      summary: Search ecosystem users
      description: Search for users across the entire ecosystem, scoped to an account context. At least one filter parameter
        is required.
      tags:
      - Ecosystem Users
      operationId: listEcosystemUsers
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The account's UUID
      - name: filter[email]
        in: query
        required: false
        schema:
          type: string
        description: Filter by exact email address
      - name: filter[first_name:like]
        in: query
        required: false
        schema:
          type: string
        description: Filter by first name (partial, case-insensitive)
      - name: filter[last_name:like]
        in: query
        required: false
        schema:
          type: string
        description: Filter by last name (partial, case-insensitive)
      - name: filter[external_reference.business_system]
        in: query
        required: false
        schema:
          type: string
        description: Filter by the user's business-system identifier (the same value returned in `external_reference.business_system`).
      - name: page[number]
        in: query
        required: false
        schema:
          type: integer
          default: 1
          minimum: 1
        description: Page number for paginated results
      - name: page[size]
        in: query
        required: false
        schema:
          type: integer
          default: 25
          minimum: 1
          maximum: 100
        description: Number of results per page
      responses:
        '200':
          description: Successful response
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ecosystem_users'
        '400':
          description: Missing required filter parameter
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/errors_response'
        '401':
          description: Invalid or expired access token
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/errors_response'
        '403':
          description: Forbidden — untrusted application or insufficient RBAC permissions
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/errors_response'
        '428':
          description: OAuth application not provisioned for this module
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/errors_response'
    post:
      summary: Create an ecosystem user
      description: 'Provisions a new user in the Decisiv SRM ecosystem. This endpoint is **not** idempotent: a duplicate email
        or username — including one belonging to a discarded user — is rejected with `422`, matching the legacy vendor self-registration
        and admin-create flows. A welcome notification is sent automatically on success — either a password setup email or
        an SSO welcome email depending on the user''s email domain.'
      tags:
      - Ecosystem Users
      operationId: createEcosystemUser
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The account's UUID
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/ecosystem_user_create'
            example:
              data:
                type: ecosystem_users
                attributes:
                  username: jane.smith
                  email: jane.smith@decisiv.com
                  first_name: Jane
                  last_name: Smith
                  job_role: Service Manager
                  address1: 100 Main St
                  city: Greensboro
                  state: NC
                  postal_code: '27410'
                  country: US
                  external_reference:
                    business_system: BS-12345
      responses:
        '201':
          description: User created successfully
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ecosystem_user_by_id'
        '400':
          description: Missing required attributes
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/errors_response'
        '422':
          description: Validation error — invalid email format (`decisiv:email:001`–`004` syntax/length/host), reserved email
            domain (`decisiv:email:005`), unresolvable email domain (`decisiv:email:001`), invalid country/state (`decisiv:location:001`/`002`/`004`),
            duplicate email (`decisiv:account_user:005`), or duplicate username (`decisiv:account_user:004`). Discarded users
            count toward duplicates.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/errors_response'
  /account_management/v1/accounts/{account_id}/ecosystem_users/{id}:
    get:
      summary: Get an ecosystem user
      description: Retrieve a single ecosystem user by UUID.
      tags:
      - Ecosystem Users
      operationId: getEcosystemUser
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The account's UUID
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: The user's UUID
      responses:
        '200':
          description: Successful response
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ecosystem_user_by_id'
        '404':
          description: User not found
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/errors_response'
  /account_management/v1/accounts/{account_id}/users:
    get:
      summary: List account users
      description: List all users assigned to an account. Supports `?include=roles` to sideload role assignments.
      tags:
      - Account Users
      operationId: listAccountUsers
      parameters:
      - name: account_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: include
        in: query
        required: false
        schema:
          type: string
          enum:
          - roles
        description: Sideload related resources (e.g. `roles`)
      - name: filter[email]
        in: query
        required: false
        schema:
          type: string
        description: Filter by exact email address
      - name: filter[first_name:like]
        in: query
        required: false
        schema:
          type: string
        description: Filter by first name (partial, case-insensitive)
      - name: filter[last_name:like]
        in: query
        required: false
        schema:
          type: string
        description: Filter by last name (partial, case-insensitive)
      - name: filter[external_reference.business_system]
        in: query
        required: false
        schema:
          type: string
        description: Filter by the user's business-system identifier (the same value returned in `external_reference.business_system`).
      - name: filter[roles.id]
        in: query
        required: false
        schema:
          type: string
        description: 'Filter by role ID. Accepts a comma-separated list; users must have ALL listed roles on this account
          (AND). Example: filter[roles.id]=1,2'
      - name: filter[roles.id:includes]
        in: query
        required: false
        schema:
          type: string
        description: 'Filter by role ID. Accepts a comma-separated list; users must have ANY of the listed roles on this account
          (OR). Example: filter[roles.id:includes]=1,2'
      - name: filter[roles.id:excludes]
        in: query
        required: false
        schema:
          type: string
        description: 'Filter by role ID. Accepts a comma-separated list; returns users who do NOT have ANY of the listed roles
          on this account. Example: filter[roles.id:excludes]=1,2'
      - name: filter[job_role]
        in: query
        required: false
        schema:
          type: string
        description: Filter by exact `job_role` (e.g. `Branch Manager`). Pass the same value returned in the `job_role` attribute
          on the response.
      - name: filter[job_role:like]
        in: query
        required: false
        schema:
          type: string
        description: 'Filter by partial `job_role` match (case-insensitive). Example: `Manager` matches users whose `job_role`
          is `Branch Manager` or `Service Manager`.'
      - name: filter[last_login_at:gte]
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: 'Filter to users whose most recent login is on or after the given ISO 8601 timestamp. Example: filter[last_login_at:gte]=2026-01-01T00:00:00Z'
      - name: filter[last_login_at:lte]
        in: query
        required: false
        schema:
          type: string
          format: date-time
        description: Filter to users whose most recent login is on or before the given ISO 8601 timestamp.
      - name: filter[last_login_at:exists]
        in: query
        required: false
        schema:
          type: boolean
        description: Filter users by whether a `last_login_at` timestamp exists. Use `true` to list only users who have logged
          in at least once, or `false` to list only users who have never logged in.
      - name: sort
        in: query
        required: false
        schema:
          type: string
        description: 'Sort the results. Accepts a comma-separated list of fields; prefix any field with `-` for descending.
          The first field is the primary sort key; subsequent fields break ties. Allowed fields: `last_login_at`, `roles.name`,
          `job_role`. Examples: `sort=last_login_at`, `sort=-job_role`, `sort=roles.name,-last_login_at`. Defaults to `last_name
          asc, first_name asc` when omitted. For `roles.name`, multi-role users are placed by their alphabetically first role
          (asc) or last role (desc) on this account. Empty/null values for any sortable column are always grouped at the end
          (NULLS LAST) regardless of direction.'
      - name: page[number]
        in: query

# --- truncated at 32 KB (128 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/decisiv/refs/heads/main/openapi/decisiv-account-management-openapi.yml