Onemap8

Companies

Companies are the top level of the business hierarchy: customers, forwarders, vendors, or the tenant’s own entity. Branches, contacts, teams and tickets all belong to a company.

The Company Model

A company: a customer, a forwarder, a vendor, the tenant own legal entity.

Scheme

  • Name
    id
    Type
    integer
    Description
    Unique identifier
  • Name
    name
    Type
    string required
    Description
    Company name
  • Name
    uniqueId
    Type
    string
    Description
    External reference, unique across companies (for example an id from a previous system). Looked up with the uniqueId filter
  • Name
    disabled
    Type
    boolean
    Description
    Whether the company is switched off
  • Name
    attributes
    Type
    object
    Description
    Everything else. By convention _roles_ is a list such as ["customer", "forwarder"] (or a comma-separated string), and tax data, address, contacts and tags live here too. A company webhook for tickets is _ticketWebhook_ with _url_ and _secret_
GET/companies

Fetch a list of Companies

Companies the user can see, sorted by name. A company is visible to the users linked to it; the creator is linked automatically, and more users are linked with the permissions endpoint (userId and companyId).

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description
    HTTP Authorization Scheme: basic
  • Name
    ApiKey
    Type
    scheme
    Description
    HTTP Authorization Scheme: bearer

Query Parameters

  • Name
    all
    Type
    boolean
    Description
    Can only be used by admins or managers to fetch all entities
  • Name
    userId
    Type
    integer
    Description
    Standard users can use this only with their own _userId_
  • Name
    keyword
    Type
    string
    Description
    Search keyword filter (name and uniqueId)
  • Name
    role
    Type
    string
    Description
    Only companies with this role in attributes.roles (case-insensitive), for example _customer_, _forwarder_, _vendor_
  • Name
    uniqueId
    Type
    string
    Description
    The company with this external reference (for example the id a record had before it came to the platform)
  • Name
    excludeAttributes
    Type
    boolean
    Description
    Skip returning the attributes map (ignored when filtering by role)
  • Name
    limit
    Type
    integer
    Description
    Limit the number of returned results
  • Name
    offset
    Type
    integer
    Description
    Offset for pagination

Response schema

  • Name
    application/json
    Type
    schema
    Description

Responses

  • Name
    200
    Type
    success
    Description
    Company
  • Name
    400
    Type
    error
    Description
    Bad request. Invalid input, or the user has no access to the company (the server answers 400 with a text message)
  • Name
    401
    Type
    error
    Description
    Unauthorized

Request

GET
/companies
curl --location 'https://gw.onemap8.com/api/companies?all=<boolean>&userId=<integer>&keyword=<string>&role=<string>&uniqueId=<string>&excludeAttributes=<boolean>&limit=<integer>&offset=<integer>' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}'

Response

[
{
  "id": 0,
  "name": "<string>",
  "uniqueId": "<string>",
  "disabled": true,
  "attributes": {}
}
]
POST/companies

Create a Company

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description
    HTTP Authorization Scheme: basic
  • Name
    ApiKey
    Type
    scheme
    Description
    HTTP Authorization Scheme: bearer

Request body schema

  • Name
    application/json
    Type
    schema
    Description

Body schema

  • Name
    id
    Type
    integer
    Description
    Unique identifier
  • Name
    name
    Type
    string required
    Description
    Company name
  • Name
    uniqueId
    Type
    string
    Description
    External reference, unique across companies (for example an id from a previous system). Looked up with the uniqueId filter
  • Name
    disabled
    Type
    boolean
    Description
    Whether the company is switched off
  • Name
    attributes
    Type
    object
    Description
    Everything else. By convention _roles_ is a list such as ["customer", "forwarder"] (or a comma-separated string), and tax data, address, contacts and tags live here too. A company webhook for tickets is _ticketWebhook_ with _url_ and _secret_

Response schema

  • Name
    application/json
    Type
    schema
    Description

Responses

  • Name
    200
    Type
    success
    Description
    Company
  • Name
    400
    Type
    error
    Description
    Bad request. Invalid input, or the user has no access to the company (the server answers 400 with a text message)
  • Name
    401
    Type
    error
    Description
    Unauthorized

Request

POST
/companies
curl --location --request POST 'https://gw.onemap8.com/api/companies' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}' \
--data '{
"id": 0,
"name": "<string>",
"uniqueId": "<string>",
"disabled": true,
"attributes": {}
}'

Response

{
"id": 0,
"name": "<string>",
"uniqueId": "<string>",
"disabled": true,
"attributes": {}
}
GET/companies/{id}

Fetch a Company

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description
    HTTP Authorization Scheme: basic
  • Name
    ApiKey
    Type
    scheme
    Description
    HTTP Authorization Scheme: bearer

Path parameters

  • Name
    id
    Type
    integer required
    Description

Response schema

  • Name
    application/json
    Type
    schema
    Description

Responses

  • Name
    200
    Type
    success
    Description
    Company
  • Name
    400
    Type
    error
    Description
    Bad request. Invalid input, or the user has no access to the company (the server answers 400 with a text message)
  • Name
    401
    Type
    error
    Description
    Unauthorized
  • Name
    404
    Type
    error
    Description
    Not found

Request

GET
/companies/{id}
curl --location 'https://gw.onemap8.com/api/companies/<integer>' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}'

Response

{
"id": 0,
"name": "<string>",
"uniqueId": "<string>",
"disabled": true,
"attributes": {}
}
PUT/companies/{id}

Update a Company

The id in the body must be the id in the path. Deleting a company also deletes its branches, contacts, teams and tickets.

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description
    HTTP Authorization Scheme: basic
  • Name
    ApiKey
    Type
    scheme
    Description
    HTTP Authorization Scheme: bearer

Path parameters

  • Name
    id
    Type
    integer required
    Description

Request body schema

  • Name
    application/json
    Type
    schema
    Description

Body schema

  • Name
    id
    Type
    integer
    Description
    Unique identifier
  • Name
    name
    Type
    string required
    Description
    Company name
  • Name
    uniqueId
    Type
    string
    Description
    External reference, unique across companies (for example an id from a previous system). Looked up with the uniqueId filter
  • Name
    disabled
    Type
    boolean
    Description
    Whether the company is switched off
  • Name
    attributes
    Type
    object
    Description
    Everything else. By convention _roles_ is a list such as ["customer", "forwarder"] (or a comma-separated string), and tax data, address, contacts and tags live here too. A company webhook for tickets is _ticketWebhook_ with _url_ and _secret_

Response schema

  • Name
    application/json
    Type
    schema
    Description

Responses

  • Name
    200
    Type
    success
    Description
    Company
  • Name
    400
    Type
    error
    Description
    Bad request. Invalid input, or the user has no access to the company (the server answers 400 with a text message)
  • Name
    401
    Type
    error
    Description
    Unauthorized

Request

PUT
/companies/{id}
curl --location --request PUT 'https://gw.onemap8.com/api/companies/<integer>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}' \
--data '{
"id": 0,
"name": "<string>",
"uniqueId": "<string>",
"disabled": true,
"attributes": {}
}'

Response

{
"id": 0,
"name": "<string>",
"uniqueId": "<string>",
"disabled": true,
"attributes": {}
}
DELETE/companies/{id}

Delete a Company

Authorizations

BasicAuth or ApiKey

  • Name
    BasicAuth
    Type
    scheme
    Description
    HTTP Authorization Scheme: basic
  • Name
    ApiKey
    Type
    scheme
    Description
    HTTP Authorization Scheme: bearer

Path parameters

  • Name
    id
    Type
    integer required
    Description

Responses

  • Name
    204
    Type
    success
    Description
    No content
  • Name
    400
    Type
    error
    Description
    Bad request. Invalid input, or the user has no access to the company (the server answers 400 with a text message)
  • Name
    401
    Type
    error
    Description
    Unauthorized
  • Name
    404
    Type
    error
    Description
    Not found

Request

DELETE
/companies/{id}
curl --location --request DELETE 'https://gw.onemap8.com/api/companies/<integer>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic {your_access_token}'

Response

No content