Organisations

List organisations for a company

GET

https://api.gosmarter.ai

/api/company/{companyId}/organisations

Retrieves all organisations (suppliers, customers, distributors, etc.) belonging to the specified company with their assigned roles. Use the /company/{companyId}/organisation-reference/roles endpoint to enumerate available role IDs.

List organisations for a company › path Parameters

companyId

string · uuid · required

The unique identifier of the company. Example: 11111111-2222-3333-4444-555555555555

List organisations for a company › query Parameters

roleId

integer · int32

Optional filter by organisation role ID (e.g., 1 for Supplier, 2 for Customer). If omitted, returns all organisations. To get available role IDs, call /company/{companyId}/organisation-reference/roles.

List organisations for a company › Headers

GoSmarter-Api-Key

string · required

The GoSmarter-Api-Key header is used to authenticate with the API using your API key. Value is of the format YOUR_KEY_HERE.

List organisations for a company › Responses

List of organisations retrieved successfully

metaOrganisationDto[]

metaOrganisationDto

createdAt

string · date-time

Timestamp when the record was created (UTC)

updatedAt

string · date-time

Timestamp when the record was last updated (UTC)

address

string

Organisation address

contactInfo

string

Contact information (email, phone, etc.)

taxId

string

Tax identification number

roleIds

integer[]

List of role IDs assigned to this organisation

roles

string[]

List of role names assigned to this organisation

organisationId

string · uuid

Unique identifier for the organisation

companyId

string · uuid

Identifier of the owning company

name

string

Organisation name

Create new organisations

POST

https://api.gosmarter.ai

/api/company/{companyId}/organisations

Creates one or more new organisations for the specified company. Each organisation can have multiple roles assigned.

Create new organisations › path Parameters

companyId

string · uuid · required

The unique identifier of the company

Create new organisations › Headers

GoSmarter-Api-Key

string · required

The GoSmarter-Api-Key header is used to authenticate with the API using your API key. Value is of the format YOUR_KEY_HERE.

Create new organisations › Request Body

organisationCreateUpdateDto[]

organisationCreateUpdateDto

name

string

Organisation name

address

string

Organisation address

contactInfo

string

Contact information (email, phone, etc.)

taxId

string

Tax identification number

roleIds

integer[]

List of role IDs to assign to this organisation

Create new organisations › Responses

Organisations created successfully

organisationDto[]

organisationDto

address

string

Organisation address

contactInfo

string

Contact information (email, phone, etc.)

taxId

string

Tax identification number

roleIds

integer[]

List of role IDs assigned to this organisation

roles

string[]

List of role names assigned to this organisation

organisationId

string · uuid

Unique identifier for the organisation

companyId

string · uuid

Identifier of the owning company

name

string

Organisation name

POST/api/company/{companyId}/organisations

curl https://api.gosmarter.ai/api/company/:companyId/organisations \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'GoSmarter-Api-Key: <string>' \
  --header 'Authorization: Bearer <token>' \
  --data '[
  {
    "name": "name",
    "address": "address",
    "contactInfo": "contactInfo",
    "taxId": "taxId",
    "roleIds": [
      0
    ]
  }
]'

Example Request Body

[
  {
    "name": "name",
    "address": "address",
    "contactInfo": "contactInfo",
    "taxId": "taxId",
    "roleIds": [
      0
    ]
  }
]

json

Example Responses

[
  {
    "address": "address",
    "contactInfo": "contactInfo",
    "taxId": "taxId",
    "roleIds": [
      0
    ],
    "roles": [
      "string"
    ],
    "organisationId": "00000000-0000-0000-0000-000000000000",
    "companyId": "00000000-0000-0000-0000-000000000000",
    "name": "name"
  }
]

json

application/json

Get organisation by ID

GET

https://api.gosmarter.ai

/api/company/{companyId}/organisations/{organisationId}

Retrieves a specific organisation by its unique identifier.

Get organisation by ID › path Parameters

companyId

string · uuid · required

The unique identifier of the company

organisationId

string · uuid · required

The unique identifier of the organisation

Get organisation by ID › Headers

GoSmarter-Api-Key

string · required

The GoSmarter-Api-Key header is used to authenticate with the API using your API key. Value is of the format YOUR_KEY_HERE.

Get organisation by ID › Responses

Organisation retrieved successfully

metaOrganisationDto

createdAt

string · date-time

Timestamp when the record was created (UTC)

updatedAt

string · date-time

Timestamp when the record was last updated (UTC)

address

string

Organisation address

contactInfo

string

Contact information (email, phone, etc.)

taxId

string

Tax identification number

roleIds

integer[]

List of role IDs assigned to this organisation

roles

string[]

List of role names assigned to this organisation

organisationId

string · uuid

Unique identifier for the organisation

companyId

string · uuid

Identifier of the owning company

name

string

Organisation name

Update an existing organisation

PUT

https://api.gosmarter.ai

/api/company/{companyId}/organisations/{organisationId}

Updates an existing organisation's details and role mappings.

Update an existing organisation › path Parameters

companyId

string · uuid · required

The unique identifier of the company

organisationId

string · uuid · required

The unique identifier of the organisation to update

Update an existing organisation › Headers

GoSmarter-Api-Key

string · required

The GoSmarter-Api-Key header is used to authenticate with the API using your API key. Value is of the format YOUR_KEY_HERE.

Update an existing organisation › Request Body

organisationCreateUpdateDto

name

string

Organisation name

address

string

Organisation address

contactInfo

string

Contact information (email, phone, etc.)

taxId

string

Tax identification number

roleIds

integer[]

List of role IDs to assign to this organisation

Update an existing organisation › Responses

Organisation updated successfully

organisationDto

address

string

Organisation address

contactInfo

string

Contact information (email, phone, etc.)

taxId

string

Tax identification number

roleIds

integer[]

List of role IDs assigned to this organisation

roles

string[]

List of role names assigned to this organisation

organisationId

string · uuid

Unique identifier for the organisation

companyId

string · uuid

Identifier of the owning company

name

string

Organisation name

PUT/api/company/{companyId}/organisations/{organisationId}

curl https://api.gosmarter.ai/api/company/:companyId/organisations/:organisationId \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'GoSmarter-Api-Key: <string>' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "name": "name",
  "address": "address",
  "contactInfo": "contactInfo",
  "taxId": "taxId",
  "roleIds": [
    0
  ]
}'

Example Request Body

{
  "name": "name",
  "address": "address",
  "contactInfo": "contactInfo",
  "taxId": "taxId",
  "roleIds": [
    0
  ]
}

json

Example Responses

{
  "address": "address",
  "contactInfo": "contactInfo",
  "taxId": "taxId",
  "roleIds": [
    0
  ],
  "roles": [
    "string"
  ],
  "organisationId": "00000000-0000-0000-0000-000000000000",
  "companyId": "00000000-0000-0000-0000-000000000000",
  "name": "name"
}

json

application/json

Delete organisation

DELETE

https://api.gosmarter.ai

/api/company/{companyId}/organisations/{organisationId}

Soft deletes an organisation by marking it as inactive. The organisation will no longer appear in lists but data is preserved for audit purposes.

Delete organisation › path Parameters

companyId

string · uuid · required

The unique identifier of the company

organisationId

string · uuid · required

The unique identifier of the organisation to delete

Delete organisation › Headers

GoSmarter-Api-Key

string · required

The GoSmarter-Api-Key header is used to authenticate with the API using your API key. Value is of the format YOUR_KEY_HERE.

Delete organisation › Responses

Organisation deleted successfully

deleteResponse

deletedCount

integer · int32

Number of items deleted

deletedIds

string[]

List of IDs that were deleted

Download organisations as CSV

GET

https://api.gosmarter.ai

/api/company/{companyId}/organisations/download

Downloads all organisations for a company as a CSV file

Download organisations as CSV › path Parameters

companyId

string · uuid · required

The unique identifier of the company

Download organisations as CSV › Headers

GoSmarter-Api-Key

string · required

The GoSmarter-Api-Key header is used to authenticate with the API using your API key. Value is of the format YOUR_KEY_HERE.

Download organisations as CSV › Responses

CSV file with organisations data

string · binary

Get organisation change history

GET

https://api.gosmarter.ai

/api/company/{companyId}/organisations/{organisationId}/history

Returns field-level audit history for a specific organisation, derived from SQL Server temporal tables.

Get organisation change history › path Parameters

companyId

string · uuid · required

The unique identifier of the company

organisationId

string · uuid · required

The unique identifier of the organisation

Get organisation change history › Headers

GoSmarter-Api-Key

string · required

The GoSmarter-Api-Key header is used to authenticate with the API using your API key. Value is of the format YOUR_KEY_HERE.

Get organisation change history › Responses

List of audit events for the organisation

auditEventDto[]

auditEventDto

changedAt

string · date-time

changedById

string · uuid

changedByName

string

changeType

string

auditFieldChange[]

entityType

string

entityLabel

string

Upload organisations from CSV

POST

https://api.gosmarter.ai

/api/company/{companyId}/organisations/upload

Uploads and processes a CSV file to create or update organisations in bulk. If OrganisationId is provided in CSV, existing records will be updated (merged); otherwise new records are created. Supports case-insensitive and flexible header names.

Upload organisations from CSV › path Parameters

companyId

string · uuid · required

The unique identifier of the company

Upload organisations from CSV › Headers

GoSmarter-Api-Key

string · required

The GoSmarter-Api-Key header is used to authenticate with the API using your API key. Value is of the format YOUR_KEY_HERE.

Upload organisations from CSV › Request Body

Upload organisations from CSV › Responses

CSV uploaded and processed successfully

Get organisations CSV template

GET

https://api.gosmarter.ai

/api/company/{companyId}/organisations/upload-template

Downloads a CSV template file for uploading organisations

Get organisations CSV template › path Parameters

companyId

string · uuid · required

The unique identifier of the company

Get organisations CSV template › Headers

GoSmarter-Api-Key

string · required

The GoSmarter-Api-Key header is used to authenticate with the API using your API key. Value is of the format YOUR_KEY_HERE.

Get organisations CSV template › Responses

CSV template file

string · binary

Company Company Settings