<access-service>/api/v1/organisations/{orgGroupId}/plans

​

URL structure

https://access-service.xy-company.com/api/v1/organisations/{orgGroupId}/plans

​

Supported methods and overview

• POST - used to add a new plan to an organization (specified by orgGroupId).
• GET - used to retrieve a list of information for all plans configured within an organization (specified by orgGroupId).

​

Detailed description

• Adds a new plan to an organization (specified by orgGroupId).
  Note: It is necessary for an organization to have at least one plan to grant the Originator role to Covata user accounts within this organization - see the <access-service>/api/v1/organisations/{orgGroupId}/users API endpoint for more information.
• Retrieves a list of information for all plans configured within an organization (specified by orgGroupId).

​

Supported roles and conditions

• Organization administrator - when this user is a member of the organization specified by {orgGroupId} in the request’s URL.

​

Required headers

• Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE0NjcwMTY2NjYsInVzZXJfbmFtZSI6ImFsZXgub...

• Content-Type: application/json

​

Required POST-request parameters

• name - The name of the plan to be added to the organization specified by {orgGroupId} in the request’s URL.
• description - The description for this new plan.
• quota - The quota (in MiB) to set for this new plan.
  Note: A MiB is a mebibyte, where one MiB = 1 x 1024 x 1024 bytes = 1048576 bytes.
  Example (request):
  {
    "name": "Temporary Staff Originators",
    "description": "Temporary staff members with the Originator role.",
    "quota": 4096
  }
  

​

Optional POST-request parameters

• default - A boolean value determining whether (true) or not (false) the new plan being added to the organization (specified by {orgGroupId} in the URL) will be flagged as the default plan for this organization.
  Example (request):
  {
    "name": "Temporary Staff Originators",
    "description": "Temporary staff members with the Originator role.",
    "quota": 4096,
    "default": true
  }
  

​

Optional GET-request parameters

• limit - An integer value from 0 to 100, representing the maximum number of items to be returned in the response, where an individual item is information about a plan configured in the organization (specified by {orgGroupId} in the request’s URL). If this parameter is omitted, then its value is 0 by default, which does not apply restrictions to the number of items returned in the response.
• offset - A value representing the count order of all retrievable items (i.e. plans in the organization specified by {orgGroupId} in the URL) returned in the response. Calls to this API endpoint may amount to potentially large numbers of items being returned from the Covata Platform. Since the order of these items in the response could differ significantly, based on the values of the orderBy and sortBy parameters below, this offset parameter provides pagination for items returned in responses, allowing items to be retrieved from any count greater than 0 (i.e. the first item returned in a response). If this parameter is omitted, then its value is 0 by default.
• orderBy - An enumeration (enum) value representing the order in which items (i.e. plans in the organization specified by {orgGroupId} in the URL) are returned in the response. This parameter orders items according to the value of the sortBy parameter specified below. Ordering items can be in either ascending alphanumeric order (by specifying the value ASC for this parameter) or descending order (by specifying the value DESC). If this parameter is omitted, then its value is ASC by default.
• sortBy - A value representing the field (i.e. member) of a retrieved item by which items (i.e. plans in the organization specified by {orgGroupId} in the URL) returned in the response will be sorted. Valid field values for this parameter include:
  • name - the name of the plan and
  • description - the description of the plan.
  • quota - the description of the plan.
  Example (request):
  https://access-service.xy-company.com/api/v1/organisations/760756644367081472/plans?limit=10
  

​

Returns

• items ( from GET requests only ) - An array containing information about all existing plans configured in the organization (specified by {orgGroupId} in the request’s URL), where these groups have been filtered by any parameters submitted in the request. Each element of this array contains information about one of these plans (represented as an object containing the following members unless otherwise stated).
• id - The ID of the (new) plan.
• name - The name of the (new) plan.
• description - The description of the (new) plan.
• quota - The current quota of the plan (in MiB).
• default - A boolean value indicating whether (true) or not (false) this plan is flagged as the default plan for this organization.
• count ( from GET requests only when specifying a limit parameter value > 0 ) - The total number of items (i.e. plans configured in the organization specified by {orgGroupId} in the request’s URL) that can be returned in the response.
• offset ( from GET requests only when specifying a limit parameter value > 0 ) - The value of the offset which had been used in the request to this API endpoint.
  Example (response):
  {
      "items": [{
          "id": "760757068528656384",
          "name": "Staff Originators",
          "description": "Staff members with the Originator role.",
          "quota": 10240,
          "default": true
      }, {
          "id": "767973799974182912",
          "name": "Temporary Staff Originators",
          "description": "Temporary staff members with the Originator role.",
          "quota": 4096,
          "default": false
      }],
      "count": "2",
      "offset": "0"
  }