BigChange Users API

The Users API from BigChange — 1 operation(s) for users.

GitHub OpenAPI

Operations 5

GET /v1/users Gets a list of users #
POST /v1/users Create a user #
GET /v1/users/{userId} Get a user #
PATCH /v1/users/{userId} Update a user #
GET /v1/users/{userId}/parameter/{parameterKey} Get a user's parameter #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/bigchange:bigchange-users-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

bigchange-users-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: BigChange DX Users API
  description: Developer Experience API
  version: '1.0'
servers:
- url: https://api.bigchange.com
security:
- bearer: []
tags:
- name: Users
paths:
  /v1/users:
    get:
      tags:
      - Users
      summary: Gets a list of users
      description: Retrieve a paged collection of users (required scope users:read)
      parameters:
      - name: Customer-Id
        in: header
        description: The customer identifier
        required: true
        schema:
          type: integer
          format: int64
      - name: sortBy
        in: query
        description: The field to sort items in the page by
        schema:
          $ref: '#/components/schemas/UserSortOptions'
      - name: direction
        in: query
        description: The direction to apply the sort
        schema:
          $ref: '#/components/schemas/SortDirection'
      - name: pageNumber
        in: query
        description: 'The page number being requested (minimum: 1, maximum: 2147483)'
        schema:
          maximum: 2147483
          minimum: 1
          type: integer
          format: int32
      - name: pageSize
        in: query
        description: 'The page size being requested (minimum: 1, maximum: 1000)'
        schema:
          maximum: 1000
          minimum: 1
          type: integer
          format: int32
      - name: emailAddress
        in: query
        description: The email address to filter users by
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedResponseReadUserModel'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
      operationId: getV1Users
      x-operation-id-source: derived
    post:
      tags:
      - Users
      summary: Create a user
      description: Create a new user (required scope users:write)
      parameters:
      - name: Customer-Id
        in: header
        description: The customer identifier
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserModel'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostResponseInt64'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
        '422':
          description: Unprocessable Content
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
      operationId: postV1Users
      x-operation-id-source: derived
  /v1/users/{userId}:
    get:
      tags:
      - Users
      summary: Get a user
      description: Retrieve the details of a single user (required scope users:read)
      parameters:
      - name: Customer-Id
        in: header
        description: The customer identifier
        required: true
        schema:
          type: integer
          format: int64
      - name: userId
        in: path
        description: The unique identifier of the user
        required: true
        schema:
          maximum: 9223372036854776000
          minimum: 1
          type: integer
          format: int64
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadUserModel'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
      operationId: getV1UsersByUserId
      x-operation-id-source: derived
    patch:
      tags:
      - Users
      summary: Update a user
      description: Updates the details of a specific user (required scope users:write)
      parameters:
      - name: Customer-Id
        in: header
        description: The customer identifier
        required: true
        schema:
          type: integer
          format: int64
      - name: userId
        in: path
        required: true
        schema:
          type: integer
          format: int64
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserModel'
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
        '422':
          description: Unprocessable Content
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ValidationProblemDetails'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
      operationId: patchV1UsersByUserId
      x-operation-id-source: derived
  /v1/users/{userId}/parameter/{parameterKey}:
    get:
      tags:
      - Users
      summary: Get a user's parameter
      description: Retrieve the details of a user's parameter (required scope users:read)
      parameters:
      - name: Customer-Id
        in: header
        description: The customer identifier
        required: true
        schema:
          type: integer
          format: int64
      - name: userId
        in: path
        description: The unique identifier of the user
        required: true
        schema:
          maximum: 9223372036854776000
          minimum: 1
          type: integer
          format: int64
      - name: parameterKey
        in: path
        description: The unique identifier of the parameter
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadUserParameterModel'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
        '500':
          description: Internal Server Error
          content:
            application/problem+json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ProblemDetails'
                - $ref: '#/components/schemas/HttpValidationProblemDetails'
      operationId: getV1UsersByUserIdParameterByParameterKey
      x-operation-id-source: derived
components:
  schemas:
    HttpValidationProblemDetails:
      type: object
      allOf:
      - $ref: '#/components/schemas/ProblemDetails'
      properties:
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
      additionalProperties: {}
    CreateUserModel:
      required:
      - email
      - name
      - roleId
      type: object
      properties:
        name:
          minLength: 1
          type: string
          description: The name associated with the user
          example: John Doe
        email:
          minLength: 1
          type: string
          description: The email associated with the user
          example: email@example.com
        roleId:
          type: integer
          description: The role ID associated with the user
          format: int64
          example: 12345
        defaultJobCategoryId:
          type:
          - integer
          - 'null'
          description: The default job category ID associated with the user
          format: int64
        position:
          type:
          - string
          - 'null'
          description: The job position or title associated with the user
          example: Engineer
        type:
          $ref: '#/components/schemas/LicenceTypeWrite'
        groupId:
          type:
          - integer
          - 'null'
          description: The group identifier associated with the user
          format: int64
          example: 67890
        mobile:
          type:
          - string
          - 'null'
          description: The mobile phone number associated with the user. The phone number has to start with a + sign followed by the country code, followed by the number without the first zero
          example: '+447700900123'
        customFields:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CustomFieldWriteModel'
          description: Custom fields associated with the user
      additionalProperties: false
      description: Represents a model for creating a user
    UpdateUserModel:
      type: object
      properties:
        name:
          type: string
          description: 'The name associated with the user<br/><br/>Optional: Omit to retain current value'
          example: John Doe
          x-optional: Omit to retain current value
        email:
          type: string
          description: 'The email associated with the user<br/><br/>Optional: Omit to retain current value'
          example: email@example.com
          x-optional: Omit to retain current value
        roleId:
          type: integer
          description: 'The role ID associated with the user<br/><br/>Optional: Omit to retain current value'
          format: int64
          example: 12345
          x-optional: Omit to retain current value
        defaultJobCategoryId:
          type:
          - integer
          - 'null'
          description: 'The default job category ID associated with the user<br/><br/>Optional: Omit to retain current value or provide null to unset'
          format: int64
          x-optional: Omit to retain current value or provide null to unset
        position:
          type:
          - string
          - 'null'
          description: 'The job position or title associated with the user<br/><br/>Optional: Omit to retain current value or provide null to unset'
          example: Engineer
          x-optional: Omit to retain current value or provide null to unset
        type:
          $ref: '#/components/schemas/LicenceTypeWrite'
        groupId:
          type:
          - integer
          - 'null'
          description: 'The group identifier associated with the user<br/><br/>Optional: Omit to retain current value or provide null to unset'
          format: int64
          example: 67890
          x-optional: Omit to retain current value or provide null to unset
        mobile:
          type:
          - string
          - 'null'
          description: 'The mobile phone number associated with the user. The phone number has to start with a + sign followed by the country code, followed by the number without the first zero<br/><br/>Optional: Omit to retain current value or provide null to unset'
          example: '+447700900123'
          x-optional: Omit to retain current value or provide null to unset
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldWriteModel'
          description: 'Custom fields associated with the user<br/><br/>Optional: Omit to retain current value'
          x-optional: Omit to retain current value
      additionalProperties: false
      description: Represents a model for updating a user
    CustomFieldReadModel:
      type: object
      properties:
        definitionId:
          type: integer
          description: The unique identifier of the associated custom field definition
          format: int64
          example: 5514123
        value:
          type:
          - string
          - 'null'
          description: The current value set for the custom field
          example: Purple
        definition:
          $ref: '#/components/schemas/CustomFieldEmbeddedDefinitionModel'
        systemListValueMetadata:
          $ref: '#/components/schemas/SystemListValueMetadataModel'
      additionalProperties: false
      description: Represents a model for a custom field
    UserSortOptions:
      enum:
      - emailAddress
      type: string
      description: 'Represents the fields that can be used to sort users<p>Possible values:</p><ul><li><b>emailAddress</b>: The email address of the user</li></ul>'
      example: emailAddress
    ValidationProblemDetails:
      type: object
      properties:
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
        type:
          type:
          - string
          - 'null'
          description: A URI reference [RFC3986] that identifies the problem type
          example: https://example.com/probs/out-of-credit
        title:
          type:
          - string
          - 'null'
          description: A short, human-readable summary of the problem type
          example: You do not have enough credit
        status:
          type:
          - integer
          - 'null'
          description: The HTTP status code([RFC7231], Section 6) generated by the origin server for this occurrence of the problem
          format: int32
          example: 403
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem
          example: Your current balance is 30, but that costs 50
        instance:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the specific occurrence of the problem
          example: /account/12345/msgs/abc
      additionalProperties: {}
    LicenceTypeWrite:
      enum:
      - active
      - inactive
      - linkedResource
      type: string
      description: 'Represents the type of licence assigned to a user<p>Possible values:</p><ul><li><b>active</b>: Indicates an active licence</li><li><b>inactive</b>: Indicates an inactive licence</li><li><b>linkedResource</b>: Indicates a licence associated with a linked resource</li></ul>'
      example: active
    LicenceType:
      enum:
      - active
      - inactive
      - integration
      - linkedResource
      type: string
      description: 'Represents the type of licence assigned to a user<p>Possible values:</p><ul><li><b>active</b>: Indicates an active licence</li><li><b>inactive</b>: Indicates an inactive licence</li><li><b>integration</b>: Indicates a licence used for system integrations</li><li><b>linkedResource</b>: Indicates a licence associated with a linked resource</li></ul>'
      example: active
    CustomFieldEmbeddedDefinitionModel:
      type: object
      properties:
        caption:
          type: string
          description: The caption of a custom field
          example: Favourite colour
        type:
          $ref: '#/components/schemas/CustomFieldType'
        listOptions:
          type:
          - array
          - 'null'
          items:
            type: string
          description: Shows the possible values for a list type custom field. Value will be null if type is not list
          example:
          - Red
          - Blue
          - Green
          - Purple
        isRequired:
          type: boolean
          description: Indicates if the field is required in the UI. This is NOT enforced in the API
          example: true
        isEditable:
          type: boolean
          description: Indicates if the field is editable
          example: true
        default:
          type:
          - string
          - 'null'
          description: The default value of a custom field. Formatted in accordance with the rules of the field type
          example: '10'
      additionalProperties: false
      description: Represents the definition of a custom field
    CustomFieldSystemListType:
      enum:
      - resource
      - vehicle
      - webUser
      type: string
      description: The type of entity used for custom field value of type system list<p>Possible values:</p><ul><li><b>resource</b></li><li><b>vehicle</b></li><li><b>webUser</b></li></ul>
      example: resource
    CustomFieldWriteModel:
      required:
      - definitionId
      type: object
      properties:
        definitionId:
          type: integer
          description: The unique identifier of the associated custom field definition
          format: int64
          example: 5514123
        value:
          type:
          - string
          - 'null'
          description: The value of this custom field. If set to null, any existing value will be unset
          example: High net worth
      additionalProperties: false
      description: 'Represents a model for writing to a custom field.<br/>If a custom field is omitted from a request its current value will be retained.<br/>The value must be set according to the custom field''s type as shown in the examples below:<ul><li><b>boolean</b>: Indicates a boolean field <i>(Example: "false")</i></li><li><b>integer</b>: Indicates an integer numeric field <i>(Example: "1001")</i></li><li><b>decimal</b>: Indicates a floating point numeric field <i>(Example: "1.42")</i></li><li><b>text</b>: Indicates an editable text field <i>(Example: "Purple")</i></li><li><b>list</b>: Indicates a field with a single value from a predefined list of options <i>(Example: "Purple")</i></li><li><b>statement</b>: Indicates a text field that cannot be edited. The value is always equal to the default value <i>(Example: "By signing this you agree to the following...")</i></li><li><b>date</b>: Indicates a date field, which will be represented as an RFC3339 formatted date string. The default value is not supported for this type and will always be null <i>(Example: "2024-01-31")</i></li><li><b>note</b>: Indicates a multiline, editable text field. Lines are seperated with a line feed character <i>(Example: "This is a note.")</i></li><li><b>time</b>: Indicates a time field, formatted as HH:mm. The default value is not supported for this type and will always be null <i>(Example: "10:30")</i></li><li><b>systemList</b>: Indicates the ID of a related resource, vehicle or web user <i>(Example: "228007")</i></li></ul>'
    PagedResponseReadUserModel:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/ReadUserModel'
          description: The items returned for the requested page
        pageNumber:
          type: integer
          description: The page number of the response where 1 is the first page
          format: int32
          example: 2
        pageSize:
          type: integer
          description: The number of items requested for the current page
          format: int32
          example: 100
        pageItemCount:
          type: integer
          description: The number of items returned in the current page
          format: int32
          readOnly: true
          example: 55
      additionalProperties: false
      description: A paged collection of items
    CustomFieldType:
      enum:
      - boolean
      - integer
      - decimal
      - text
      - list
      - statement
      - date
      - note
      - time
      - systemList
      type: string
      description: 'The type of the custom field. New field types may be added in the future, so integrations should be resilient to this<p>Possible values:</p><ul><li><b>boolean</b>: Indicates a boolean field <i>(Example: "false")</i></li><li><b>integer</b>: Indicates an integer numeric field <i>(Example: "1001")</i></li><li><b>decimal</b>: Indicates a floating point numeric field <i>(Example: "1.42")</i></li><li><b>text</b>: Indicates an editable text field <i>(Example: "Purple")</i></li><li><b>list</b>: Indicates a field with a single value from a predefined list of options <i>(Example: "Purple")</i></li><li><b>statement</b>: Indicates a text field that cannot be edited. The value is always equal to the default value <i>(Example: "By signing this you agree to the following...")</i></li><li><b>date</b>: Indicates a date field, which will be represented as an RFC3339 formatted date string. The default value is not supported for this type and will always be null <i>(Example: "2024-01-31")</i></li><li><b>note</b>: Indicates a multiline, editable text field. Lines are seperated with a line feed character <i>(Example: "This is a note.")</i></li><li><b>time</b>: Indicates a time field, formatted as HH:mm. The default value is not supported for this type and will always be null <i>(Example: "10:30")</i></li><li><b>systemList</b>: Indicates the ID of a related resource, vehicle or web user <i>(Example: "228007")</i></li></ul>'
      example: boolean
    ReadUserModel:
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier of the user
          format: int64
          example: 123456
        email:
          type: string
          description: The email of the user
          example: email@example.com
        name:
          type: string
          description: The name associated with the user
          example: John Doe
        createdAt:
          type: string
          description: The date and time when the user was created
          format: date-time
          example: '2023-12-01T13:00:00.0000000+00:00'
        roleId:
          type: integer
          description: The role id associated with the user
          format: int64
          example: 12345
        defaultJobCategoryId:
          type:
          - integer
          - 'null'
          description: The default job category id associated with the user
          format: int64
        position:
          type:
          - string
          - 'null'
          description: The job position or title associated with the user
          example: Engineer
        type:
          $ref: '#/components/schemas/LicenceType'
        groupId:
          type:
          - integer
          - 'null'
          description: The group identifier associated with the user
          format: int64
          example: 67890
        mobile:
          type:
          - string
          - 'null'
          description: The mobile phone number associated with the user
          example: '+447700900123'
        customFields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldReadModel'
          description: The collection of custom fields applied to this user
      additionalProperties: false
      description: Represents a model for reading user information
    SortDirection:
      enum:
      - ascending
      - descending
      type: string
      description: 'Represents the direction in which sorting should be applied<p>Possible values:</p><ul><li><b>ascending</b>: Indicates ascending sorting order</li><li><b>descending</b>: Indicates descending sorting order</li></ul>'
      example: ascending
    ReadUserParameterModel:
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier of the user
          format: int64
          example: 123456
        parameterTypeId:
          type: integer
          description: Parameter type for given user
          format: int64
        parameterValue:
          type:
          - string
          - 'null'
          description: Parameter value for given user
      additionalProperties: false
      description: Represents the model for reading user parameters
    PostResponseInt64:
      type: object
      properties:
        id:
          type: integer
          description: Identifier of the newly created record
          format: int64
      additionalProperties: false
      description: Represents a response for a POST request, containing the ID of the newly created record
    SystemListValueMetadataModel:
      type: object
      properties:
        label:
          type:
          - string
          - 'null'
          description: A descriptive label for the specific resource, vehicle or web user that this system list value relates to
          example: John Doe
        entityType:
          $ref: '#/components/schemas/CustomFieldSystemListType'
      additionalProperties: false
      description: Represents details of custom field value of type system list
    ProblemDetails:
      type: object
      properties:
        type:
          type:
          - string
          - 'null'
          description: A URI reference [RFC3986] that identifies the problem type
          example: https://example.com/probs/out-of-credit
        title:
          type:
          - string
          - 'null'
          description: A short, human-readable summary of the problem type
          example: You do not have enough credit
        status:
          type:
          - integer
          - 'null'
          description: The HTTP status code([RFC7231], Section 6) generated by the origin server for this occurrence of the problem
          format: int32
          example: 403
        detail:
          type:
          - string
          - 'null'
          description: A human-readable explanation specific to this occurrence of the problem
          example: Your current balance is 30, but that costs 50
        instance:
          type:
          - string
          - 'null'
          description: A URI reference that identifies the specific occurrence of the problem
          example: /account/12345/msgs/abc
      additionalProperties: {}
  securitySchemes:
    bearer:
      type: http
      description: Enter the access token only.
      scheme: bearer
      bearerFormat: JWT
x-provenance:
  method: harvested
  publisher: BigChange
  source: https://api.bigchange.com/swagger/v1/swagger.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)