Skip to content
API reference
/
Company
/
/
Get department

Company API (v2)

Download OpenAPI description
CompanyApi.json
CompanyApi.yaml
Languages
Servers
Sandbox URL
https://api-ext-sboxmeta.partners.spotnana.com/
Spotnana mock server
https://developer.spotnana.com/_mock/openapi/companyapi/

Companies

APIs to onboard and manage company.

Operations

Cost Centers

APIs to create and manage company cost centers.

Operations

Offices

APIs to create and manage company offices.

Operations

Departments

APIs to create and manage departments.

Operations

Create department

Request

This endpoint creates a department.

Security
Bearer
Path
companyIdstring(uuid)required

Identifier for company.

Example: 4974a66b-7493-4f41-908c-58ba81093947
Bodyapplication/jsonrequired
namestringrequired

Name of the department

externalIdstring

External id of the department

Example: "department-external-id"
curl -i -X POST \
  https://api-ext-sboxmeta.partners.spotnana.com/v2/companies/4974a66b-7493-4f41-908c-58ba81093947/departments \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "externalId": "department-external-id"
  }'

Responses

OK

Bodyapplication/json
idstring(uuid)required
Example: "b93dc51f-12dd-46c7-b7d6-1cb12cd3f5b3"
Response
application/json
{
  "id": "b93dc51f-12dd-46c7-b7d6-1cb12cd3f5b3"
}

Get department

Request

This endpoint gets a department by ID.

Security
Bearer
Path
companyIdstring(uuid)required

Identifier for company.

Example: 4974a66b-7493-4f41-908c-58ba81093947
departmentIdstring(uuid)required

Identifier for department.

Example: 4974a66b-7493-4f41-908c-58ba81093947
curl -i -X GET \
  https://api-ext-sboxmeta.partners.spotnana.com/v2/companies/4974a66b-7493-4f41-908c-58ba81093947/departments/4974a66b-7493-4f41-908c-58ba81093947 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
idstring(uuid)required
namestringrequired

Name of the department

Example: "IT Department"
externalIdstring

External id of the department

Example: "department-ext-id"
Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "IT Department",
  "externalId": "department-ext-id"
}

Update department

Request

This endpoint updates department by ID.

Security
Bearer
Path
companyIdstring(uuid)required

Identifier for company.

Example: 4974a66b-7493-4f41-908c-58ba81093947
departmentIdstring(uuid)required

Identifier for department.

Example: 4974a66b-7493-4f41-908c-58ba81093947
Bodyapplication/jsonrequired
idstring(uuid)required
namestringrequired

Name of the department

Example: "IT Department"
externalIdstring

External id of the department

Example: "department-ext-id"
curl -i -X PUT \
  https://api-ext-sboxmeta.partners.spotnana.com/v2/companies/4974a66b-7493-4f41-908c-58ba81093947/departments/4974a66b-7493-4f41-908c-58ba81093947 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "IT Department",
    "externalId": "department-ext-id"
  }'

Responses

Updated Successfully

Response
No content

Delete department

Request

This endpoint deletes department by ID.

Security
Bearer
Path
companyIdstring(uuid)required

Identifier for company.

Example: 4974a66b-7493-4f41-908c-58ba81093947
departmentIdstring(uuid)required

Identifier for department.

Example: 4974a66b-7493-4f41-908c-58ba81093947
Query
detachUsersboolean

Whether to remove this entity's reference from associated user entities.

Default false
curl -i -X DELETE \
  'https://api-ext-sboxmeta.partners.spotnana.com/v2/companies/4974a66b-7493-4f41-908c-58ba81093947/departments/4974a66b-7493-4f41-908c-58ba81093947?detachUsers=false' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Deleted Successfully

Response
No content

List departments

Request

This endpoint lists departments of a company.

Security
Bearer
Path
companyIdstring(uuid)required

Identifier for company.

Example: 4974a66b-7493-4f41-908c-58ba81093947
Bodyapplication/jsonrequired
searchTextstring

Search string entered by the user

Example: "Engineering"
paginationParamsobject(OffsetBasedPaginationRequestParams)required
paginationParams.​offsetinteger(int32)>= 0

The starting index in the list from which results are returned. The value must be greater than or equal to 0.

Default 0
paginationParams.​limitinteger(int32)>= 1

Maximum number of results to be fetched.

Default 100
filtersArray of objects(ListDepartmentsFilter)

List of filters. Departments matching with any filter would be returned.

curl -i -X POST \
  https://api-ext-sboxmeta.partners.spotnana.com/v3/companies/4974a66b-7493-4f41-908c-58ba81093947/departments/list \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "searchText": "Engineering",
    "paginationParams": {
      "offset": 0,
      "limit": 100
    },
    "filters": [
      {
        "externalIds": [
          "department-external-id"
        ],
        "departmentIds": [
          "731ccbca-0415-6fe1-d235-c324dfbe7423"
        ]
      }
    ]
  }'

Responses

OK

Bodyapplication/json
paginationParamsobject(OffsetBasedPaginationResponseParams)required
paginationParams.​totalNumResultsinteger(int32)required

Total number of results.

departmentsArray of objects(DepartmentInfo)

List of departments containing id and name.

Response
application/json
{
  "paginationParams": {
    "totalNumResults": 0
  },
  "departments": [
    { … }
  ]
}

List departmentsDeprecated

Request

This endpoint lists departments of a company.

Security
Bearer
Path
companyIdstring(uuid)required

Identifier for company.

Example: 4974a66b-7493-4f41-908c-58ba81093947
Query
externalIdstring

External id of the department.

Example: externalId=department-external-id
curl -i -X GET \
  'https://api-ext-sboxmeta.partners.spotnana.com/v2/companies/4974a66b-7493-4f41-908c-58ba81093947/departments?externalId=department-external-id' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
lengthinteger(int32)
elementsArray of objects(Reference)

List of references containing id and name.

totalNumResultsinteger(int32)

Total number of results

Response
application/json
{
  "length": 0,
  "elements": [
    { … }
  ],
  "totalNumResults": 0
}

Service Charge Plan

APIs to manage service charge plans.

Operations

Service Charge

Operations

Company Enrollment

Operations

Company Tier

Operations
Copyright © 2025 Spotnana Technology, Inc.