Organizations

Organization management endpoints

Get current organization

get

Retrieve information about the organization associated with the authentication token

Authorizations

AuthorizationstringRequired

OAuth2 Bearer token obtained from authentication endpoint

Responses

200

Organization details

application/json

idinteger · int32Required

Organization unique identifier

Example: 1

namestringRequired

Organization name

Example: Acme Corp

descriptionstringOptional

Organization description

Example: A test organization

parentOrganizationIdinteger · int32Optional

Parent organization ID (for hierarchical structure)

Example: 1

tzstringRequired

A timezone, associated with the organization

Example: Europe/Kyiv

unitSystemstring · enumOptional

Unit system used in the organization.

Example: METRICPossible values:

phoneNumberstringOptional

Phone number, associated with the organization.

Example: +11234567890

lastModifiedTsinteger · int64Required

Timestamp, indicating the time, when the organization was modified last time (Unix epoch milliseconds)

Example: 1707244800000

403

Forbidden

429

Too many requests

500

Internal server error

application/json

get

/api/v1/organization/profile

GET /api/v1/organization/profile HTTP/1.1
Host: blynk.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": 1,
  "name": "Acme Corp",
  "description": "A test organization",
  "parentOrganizationId": 1,
  "tz": "Europe/Kyiv",
  "unitSystem": "METRIC",
  "phoneNumber": "+11234567890",
  "address": {
    "fullAddress": "1234 Apple St, Apt 5B, New York, NY 10001, USA",
    "country": "USA",
    "city": "New York",
    "state": "Texas",
    "zip": "10001"
  },
  "lastModifiedTs": 1707244800000
}

Search organizations

get

Search for organizations by the provided query.

Required permissions, when user-scoped authentication is used: ORG_VIEW.

Authorizations

AuthorizationstringRequired

OAuth2 Bearer token obtained from authentication endpoint

Query parameters

querystring · max: 255Required

Search query string

sortBystringOptional

Field to sort by

sortOrderstring · enumOptional

Sort order

Default: ASCPossible values:

pageinteger · int32Optional

Page number (0-indexed)

Default: 0

sizeinteger · int32 · min: 1 · max: 1000Optional

Page size (max 1000)

Default: 50

Responses

200

Search results

application/json

totalElementsinteger · int64Required

Total amount of organizations, available to fetch.

Example: 1

400

Bad request

application/json

403

Forbidden

429

Too many requests

500

Internal server error

application/json

get

/api/v1/organization/search

GET /api/v1/organization/search?query=text HTTP/1.1
Host: blynk.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "content": [
    {
      "id": 1,
      "name": "Acme Corp",
      "description": "A test organization",
      "parentOrganizationId": 1,
      "tz": "Europe/Kyiv",
      "unitSystem": "METRIC",
      "phoneNumber": "+11234567890",
      "address": {
        "fullAddress": "1234 Apple St, Apt 5B, New York, NY 10001, USA",
        "country": "USA",
        "city": "New York",
        "state": "Texas",
        "zip": "10001"
      },
      "lastModifiedTs": 1707244800000
    }
  ],
  "totalElements": 1
}

Get organization by ID

get

Retrieve information about a specific organization.

Required permissions, when user-scoped authentication is used: ORG_VIEW.

Authorizations

AuthorizationstringRequired

OAuth2 Bearer token obtained from authentication endpoint

Query parameters

orgIdinteger · int32Required

Organization ID

Responses

200

Organization details

application/json

idinteger · int32Required

Organization unique identifier

Example: 1

namestringRequired

Organization name

Example: Acme Corp

descriptionstringOptional

Organization description

Example: A test organization

parentOrganizationIdinteger · int32Optional

Parent organization ID (for hierarchical structure)

Example: 1

tzstringRequired

A timezone, associated with the organization

Example: Europe/Kyiv

unitSystemstring · enumOptional

Unit system used in the organization.

Example: METRICPossible values:

phoneNumberstringOptional

Phone number, associated with the organization.

Example: +11234567890

lastModifiedTsinteger · int64Required

Timestamp, indicating the time, when the organization was modified last time (Unix epoch milliseconds)

Example: 1707244800000

403

Unauthorized - Invalid or missing token

404

Organization not found or access denied

application/json

429

Too many requests - Rate limit exceeded

500

Internal server error

application/json

get

/api/v1/organization

GET /api/v1/organization?orgId=1 HTTP/1.1
Host: blynk.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": 1,
  "name": "Acme Corp",
  "description": "A test organization",
  "parentOrganizationId": 1,
  "tz": "Europe/Kyiv",
  "unitSystem": "METRIC",
  "phoneNumber": "+11234567890",
  "address": {
    "fullAddress": "1234 Apple St, Apt 5B, New York, NY 10001, USA",
    "country": "USA",
    "city": "New York",
    "state": "Texas",
    "zip": "10001"
  },
  "lastModifiedTs": 1707244800000
}

Delete organization

delete

Delete an organization. Users and other resources in the organization are being deleted automatically.

The following organizations cannot be deleted:

The organization used for authentication (your own organization)
The root (super) organization
The Clients group organization
The Partners group organization
Organizations that have sub-organizations
Organizations that have devices

Required permissions, when user-scoped authentication is used: ORG_DELETE.

Authorizations

AuthorizationstringRequired

OAuth2 Bearer token obtained from authentication endpoint

Query parameters

orgIdinteger · int32Required

Organization ID

Responses

204

Organization deleted successfully

400

Some of the validations have not been passed.

application/json

403

Unauthorized - Invalid or missing token

404

Organization not found or access denied

application/json

429

Too many requests

500

Internal server error

application/json

delete

/api/v1/organization

DELETE /api/v1/organization?orgId=1 HTTP/1.1
Host: blynk.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Create a new organization

post

Create a new organization.

Required permissions, when user-scoped authentication is used: ORG_CREATE.

Authorizations

AuthorizationstringRequired

OAuth2 Bearer token obtained from authentication endpoint

Body

namestring · min: 3 · max: 100Required

Organization name. Only letters, digits, spaces, dots, hyphens, and apostrophes are allowed.

Example: Acme Corp

descriptionstring · max: 1000Optional

Organization description. Cannot contain slashes, backslashes, < or >.

Example: A test organization

tzstring · max: 200Optional

Organization timezone in the IANA Time Zone Database (TZDB) format.

Example: Europe/Kyiv

parentIdinteger · int32Optional

Parent organization ID (optional). If none is specified, the organization is created as a child of the organization associated with the authentication token.

Example: 1

phoneNumberstringOptional

Organization phone number.

Example: +11234567890

unitSystemstring · enumOptional

Unit system used in the organization.

Example: METRICPossible values:

Responses

201

Organization created successfully

application/json

400

Bad request - Invalid input

application/json

403

Forbidden

429

Too many requests

500

Internal server error

application/json

post

/api/v1/organization/create

POST /api/v1/organization/create HTTP/1.1
Host: blynk.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 139

{
  "name": "Acme Corp",
  "description": "A test organization",
  "tz": "Europe/Kyiv",
  "parentId": 1,
  "phoneNumber": "+11234567890",
  "unitSystem": "METRIC"
}

{
  "id": 1,
  "name": "Acme Corp",
  "description": "A test organization",
  "parentOrganizationId": 1,
  "tz": "Europe/Kyiv",
  "unitSystem": "METRIC",
  "phoneNumber": "+11234567890",
  "address": {
    "fullAddress": "1234 Apple St, Apt 5B, New York, NY 10001, USA",
    "country": "USA",
    "city": "New York",
    "state": "Texas",
    "zip": "10001"
  },
  "lastModifiedTs": 1707244800000
}

Update organization name

put

Update the name of an existing organization.

Required permissions, when user-scoped authentication is used: ORG_EDIT.

Authorizations

AuthorizationstringRequired

OAuth2 Bearer token obtained from authentication endpoint

Body

orgIdinteger · int32Optional

Organization ID (optional). If none is specified, the organization associated with the authentication token is being edited.

Example: 1

namestring · min: 3 · max: 100Required

New organization name. Only letters, digits, spaces, dots, hyphens, and apostrophes are allowed.

Example: New Organization Name

Responses

200

Organization updated successfully

application/json

idinteger · int32Required

Organization unique identifier

Example: 1

namestringRequired

Organization name

Example: Acme Corp

descriptionstringOptional

Organization description

Example: A test organization

parentOrganizationIdinteger · int32Optional

Parent organization ID (for hierarchical structure)

Example: 1

tzstringRequired

A timezone, associated with the organization

Example: Europe/Kyiv

unitSystemstring · enumOptional

Unit system used in the organization.

Example: METRICPossible values:

phoneNumberstringOptional

Phone number, associated with the organization.

Example: +11234567890

lastModifiedTsinteger · int64Required

Timestamp, indicating the time, when the organization was modified last time (Unix epoch milliseconds)

Example: 1707244800000

400

Bad request

application/json

403

Forbidden

404

Organization not found or access denied

application/json

429

Too many requests

500

Internal server error

application/json

put

/api/v1/organization/edit/name

PUT /api/v1/organization/edit/name HTTP/1.1
Host: blynk.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 42

{
  "orgId": 1,
  "name": "New Organization Name"
}

{
  "id": 1,
  "name": "Acme Corp",
  "description": "A test organization",
  "parentOrganizationId": 1,
  "tz": "Europe/Kyiv",
  "unitSystem": "METRIC",
  "phoneNumber": "+11234567890",
  "address": {
    "fullAddress": "1234 Apple St, Apt 5B, New York, NY 10001, USA",
    "country": "USA",
    "city": "New York",
    "state": "Texas",
    "zip": "10001"
  },
  "lastModifiedTs": 1707244800000
}

Get sub-organizations

get

Retrieve a paginated list of direct sub-organizations (children) of a specified organization.

If orgId is not specified, returns sub-organizations of the organization associated with the authentication token.

Required permissions, when user-scoped authentication is used: ORG_VIEW.

Authorizations

AuthorizationstringRequired

OAuth2 Bearer token obtained from authentication endpoint

Query parameters

orgIdinteger · int32Optional

ID of the parent organization. If not specified, uses the organization from the authentication token.

pageinteger · int32Optional

Page number

Default: 0

sizeinteger · int32 · min: 1 · max: 1000Optional

Page size (max 1000)

Default: 50

Responses

200

List of sub-organizations

application/json

totalElementsinteger · int64OptionalExample: 5

400

Bad request

application/json

403

Forbidden

429

Too many requests

500

Internal server error

application/json

get

/api/v1/organization/sub-organizations

GET /api/v1/organization/sub-organizations HTTP/1.1
Host: blynk.cloud
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "content": [
    {
      "id": 1,
      "name": "Acme Corp",
      "description": "A test organization",
      "parentOrganizationId": 1,
      "tz": "Europe/Kyiv",
      "unitSystem": "METRIC",
      "phoneNumber": "+11234567890",
      "address": {
        "fullAddress": "1234 Apple St, Apt 5B, New York, NY 10001, USA",
        "country": "USA",
        "city": "New York",
        "state": "Texas",
        "zip": "10001"
      },
      "lastModifiedTs": 1707244800000
    }
  ],
  "totalElements": 5
}

PreviousAuthentication NextDevices

Last updated 9 days ago

Was this helpful?