#%RAML 0.8
title: Organization API
baseUri: https://api.us1.covisint.com/organization/v1
protocols:
- HTTPS
schemas:
- resourceReference: |
    {
      "id" : "http://api.covisint.com/schema/resourceReference",
      "$schema" : "http://json-schema.org/draft-04/schema",
      "description" : "Schema representing links",
      "type" : "object",
      "properties" : {
        "id" : {
          "type" : "string",
          "description" : "The unique identifier for the resource.",
          "required": true
        },
        "type" : {
          "type" : "string",
          "description" : "The type of the resource."
        },
        "realm" : {
          "type" : "string",
          "description" : "The realm of the resource."
        }
      }
    }
- namedResourceReference: "{\n  \"id\" : \"http://api.covisint.com/schema/namedScopedResource\",\n
    \ \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n  \"type\" : \"object\",\n
    \ \"description\" : \"Expands on the basic resource reference and adds internationalized
    name and description.\",\n  \"extends\" : {\n        \"$ref\" : \"http://api.covisint.com/schema/resourceReference#\"\n
    \ },\n  \"properties\" : {\n     \"name\" : {  \n       \"description\": \"Internationalized
    resource name.\",\n       \"$ref\" : \"http://api.covisint.com/idm/schema/internationalString#\"\n
    \    },\n     \"description\" : {  \n       \"description\": \"Internationalized
    resource description.\",\n       \"$ref\" : \"http://api.covisint.com/idm/schema/internationalString#\"\n
    \    }\n   }\n}\n"
- resource: "{\n  \"id\" : \"http://api.covisint.com/schema/resource\",\n  \"$schema\"
    : \"http://json-schema.org/draft-04/schema\",\n  \"description\" : \"Core schema\",\n
    \ \"definitions\" : {\n    \"resource\" : {\n      \"id\" : \"resource\",\n      \"type\"
    : \"object\",\n      \"description\" : \"A basic resource.\",\n      \"properties\"
    : {\n        \"id\" : {\n          \"type\" : \"string\",\n          \"maxLength\"
    : 64,\n          \"description\" : \"The unique identifier for this resource.\",\n
    \         \"required\": true\n        },\n        \"version\": {\n          \"type\"
    : \"number\",\n          \"minimum\" : 0,\n          \"maximum\" : 9223372036854775807,\n
    \         \"description\" : \"The current version for this resource.  Exists once
    the resource has been saved. This is mandatory for PUT requests, but should not
    be supplied for POST requests.\",\n          \"required\": false\n        },\n
    \       \"creator\" : {\n          \"type\" : \"string\",\n          \"maxLength\"
    : 64,\n          \"description\" : \"The creator of this resource. This is mandatory
    if x-requestor header is NOT available\",\n          \"required\": false\n        },\n
    \       \"creatorAppId\" : {\n          \"type\" : \"string\",\n          \"maxLength\"
    : 64,\n          \"description\" : \"The application id of the creator of this
    resource.\",\n          \"required\": false\n        },\n        \"creation\"
    : {\n          \"type\" : \"number\",\n          \"minimum\" : 0,\n          \"maximum\"
    : 9223372036854775807,\n          \"description\" : \"If this value is provided
    in a POST / PUT request body, it will be ignored and system will generate value
    as time, in milliseconds since the epoch, when this resource was created or upda\",\n
    \         \"required\": false            \n        }\n      }\n    }\n  }\n}\n"
- resourceV2: "{\n  \"id\" : \"http://api.covisint.com/schema/resourceV2\",\n  \"$schema\"
    : \"http://json-schema.org/draft-04/schema\",\n  \"description\" : \"Core schema\",\n
    \ \"definitions\" : {\n    \"resource\" : {\n      \"id\" : \"resourceV2\",\n
    \     \"type\" : \"object\",\n      \"description\" : \"A basic resource (version
    V2).\",\n      \"properties\" : {\n        \"id\" : {\n          \"type\" : \"string\",\n
    \         \"maxLength\" : 64,\n          \"description\" : \"The unique identifier
    for this resource.\",\n          \"required\": true\n        },\n        \"version\":
    {\n          \"type\" : \"string\",\n          \"description\" : \"The current
    version for this resource. Exists once the resource has been saved. This is mandatory
    for PUT requests, but should not be supplied for POST requests.\",\n          \"required\":
    false\n        },\n        \"creator\" : {\n          \"type\" : \"string\",\n
    \         \"maxLength\" : 64,\n          \"description\" : \"The creator of this
    resource. This is mandatory if x-requestor header is NOT available\",\n          \"required\":
    false\n        },\n        \"creatorAppId\" : {\n          \"type\" : \"string\",\n
    \         \"maxLength\" : 64,\n          \"description\" : \"The application id
    of the creator of this resource.\",\n          \"required\": false\n        },\n
    \       \"creation\" : {\n          \"type\" : \"number\",\n          \"minimum\"
    : 0,\n          \"maximum\" : 9223372036854775807,\n          \"description\"
    : \"If this value is provided in a POST / PUT request body, it will be ignored
    and system will generate value as time, in milliseconds since the epoch, when
    this resource was created or upda\",\n          \"required\": false            \n
    \       }\n      }\n    }\n  }        \n}\n"
- realmScopedResource: |
    {
      "id" : "http://api.covisint.com/schema/realmScopedResource",
      "$schema" : "http://json-schema.org/draft-04/schema",
      "type" : "object",
      "description" : "Expands on the base resource and adds a realm attribute.",
      "extends" : {
            "$ref" : "http://api.covisint.com/schema/resource#"
      },
      "properties" : {
        "realm" : {
          "type" : "string",
          "maxLength" : 25,
          "pattern" : "^[A-Za-z0-9]{2,25}$",
          "description" : "The realm in which this resource is being created. This is mandatory if x-realm header is NOT available",
          "required": false
        }
      }
    }
- realmScopedResourceV2: "{\n  \"id\" : \"http://api.covisint.com/schema/realmScopedResourceV2\",\n
    \ \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n  \"type\" : \"object\",\n
    \ \"description\" : \"A realm scoped resource (version V2). Expands on the base
    resource (version V2) and adds a realm attribute.\",\n  \"extends\" : {\n        \"$ref\"
    : \"http://api.covisint.com/schema/resourceV2#\"\n  },\n  \"properties\" : {\n
    \   \"realm\" : {\n      \"type\" : \"string\",\n      \"maxLength\" : 25,\n      \"pattern\"
    : \"^[A-Za-z0-9]{2,25}$\",\n      \"description\" : \"The realm in which this
    resource is being created. This is mandatory if x-realm header is NOT available\",\n
    \     \"required\": false\n    }\n  }\n} \n"
- errorResponseSchema: "{\n  \"id\" : \"http://api.covisint.com/schema/errorResponseSchema\",\n
    \ \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n  \"type\" : \"object\",\n
    \ \"description\" : \"Representation of an HTTP 4xx/5xx error response.\",\n  \"properties\"
    : {\n    \"status\" : { \n      \"type\" : \"number\",\n      \"minimum\" : 400,\n
    \     \"maximum\" : 599,\n      \"description\" : \"The HTTP status code.\",\n
    \     \"required\": true\n    },\n    \"apiMessage\" : { \n      \"type\" : \"string\",\n
    \     \"description\" : \"A helpful, human-readable description of the error,
    useful for basic diagnostics.\" \n    },\n    \"apiStatusCode\" : {\n      \"type\"
    : \"string\",\n      \"description\" : \"The API-specific status code.\"\n    }\n
    \ }\n}\n"
- serviceCode: "{\n  \"id\" : \"http://api.covisint.com/schema/serviceCodes\",\n  \"$schema\"
    : \"http://json-schema.org/draft-04/schema\",\n  \"type\": \"object\",\n  \"description\":
    \"The site/service/location codes granted along with a service.\",\n  \"properties\":
    {\n    \"code\": { \"type\": \"string\", \"required\": true, \"maxLength\": 200,
    \"description\": \"The code value.\" },\n    \"codeKind\": { \"type\": \"string\",
    \"required\": true, \"maxLength\": 36, \"description\": \"The associated business
    unit.\" }\n  }\n}     \n"
- serviceCodes: |
    {
      "type" : "array",
      "description" : "The site/service/location codes granted along with the service, if any.",
      "items" : { "$ref" : "http://api.covisint.com/schema/serviceCode#"},
      "required": false
    }
- address: |
    {
      "id" : "http://api.covisint.com/idm/schema/address",
      "$schema" : "http://json-schema.org/draft-04/schema",
      "type" : "object",
      "description" : "A container for the subject's address elements.",
      "properties" : {
        "type" : "string",
        "streets" : {
            "type" : "array",
            "description" : "An array of address streets (i.e. address line 1, 2, 3).",
            "minItems" : 0,
            "items" : {
              "type": "string",
              "maxLength" : 255
            }
          },
          "city" : { "type" : "string", "maxLength" : 60, "description" : "The city name." },
          "state" : { "type" : "string", "maxLength" : 60, "description" : "The state/province name or code." },
          "postal" : { "type" : "string", "maxLength" : 10, "description" : "The postal or zip code." },
          "country" : { "type" : "string", "minLength" : 2, "maxLength" : 3, "description" : "The ISO country code. http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2"}
      }
    }
- phone: "{\n  \"id\" : \"http://api.covisint.com/idm/schema/phone\",\n  \"$schema\"
    : \"http://json-schema.org/draft-04/schema\",\n  \"type\" : \"object\",\n    \"description\"
    : \"A container for phone number details.\",\n    \"properties\" : {\n      \"number\"
    : { \"type\" : \"string\",\"maxLength\" : 100, \"description\" : \"The phone number.\"
    },\n      \"type\" : { \"enum\" : [ \"main\", \"mobile\", \"fax\" ], \"description\"
    : \"The phone number type.\" }\n    },\n    \"required\" : [ \"type\" ]\n}             \n"
- internationalString: |
    {
      "id": "http://api.covisint.com/idm/schema/internationalString",
      "$schema": "http://json-schema.org/draft-04/schema",
      "type": "array",
      "description" : "An internationalized string value, supporting one or more language translations.",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "lang": { "type": "string", "maxLength": 10, "description": "The language or locale in which the text is written." },
          "text": { "type": "string", "maxLength": 2000, "description": "The internationalized text value." }
        }
      }
    }
- tags: |
    {
      "id": "http://api.covisint.com/idm/schema/tag",
      "$schema": "http://json-schema.org/draft-04/schema",
      "type": "array",
      "description" : "The tags associated with a resource.  This array is read-only, and may be modified on the resource endpoint with the appropriate tagging APIs.",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "tagName": { "type": "string", "description": "The tag associated with a resource." }
        }
      }
    }
- organization: "{\n  \"id\" : \"http://api.covisint.com/schema/organization/v1\",\n
    \ \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n  \"type\" : \"object\",\n
    \ \"description\" : \"Schema respreseing an organization resource.\",\n  \"extends\"
    : {\n    \"$ref\" : \"http://api.covisint.com/schema/realmScopedResource#\"\n
    \ },\n  \"properties\" : {\n    \"id\": {\n       \"maxLength\" : 100\n    },\n
    \   \"version\": {\n      \"description\" : \"The current version for this resource.
    \ Exists once the resource has been saved. This is mandatory for PUT requests,
    and will be ignored for POST requests.\"\n    },\n    \"status\" : { \n      \"enum\"
    : [ \"active\", \"suspended\", \"inactive\", \"unactivated\" ], \n      \"description\"
    : \"The organization's status.  This property is read-only. Status can be changed
    through tasks.\"\n    },\n    \"parentOrganization\": {\n      \"description\":
    \"The parent organization.  Used to create an organization hierarchy.  Required
    when creating an organization, read only when updating.\",\n      \"$ref\": \"http://api.covisint.com/schema/resourceReference#\"\n
    \   },\n    \"rootOrganization\": {\n      \"description\": \"The organization
    at the root of this hierarchy.  This is the top-most organization that does not
    have a parent. This property is read-only.\",\n      \"$ref\": \"http://api.covisint.com/schema/resourceReference#\"\n
    \   },\n    \"name\" : {\n      \"type\" : \"string\",\n      \"description\"
    : \"The organization's name.\",\n      \"maxLength\" : 244,\n      \"required\":
    true\n    },\n    \"addresses\" : {\n      \"type\" : \"array\",\n      \"description\"
    : \"A container for the organization's addresses.\",\n      \"minItems\" : 1,\n
    \     \"items\" : { \n        \"ref\" : \"http://api.covisint.com/schema/address#\",\n
    \       \"properties\" : {             \n         \"streets\" : {\n            \"minItems\"
    : 1,\n            \"required\": true\n          },\n          \"city\" : { \n
    \           \"required\": true \n          },\n          \"state\" : { \n            \"required\":
    true \n          },\n          \"country\" : { \n            \"required\": true\n
    \         }\n        } \n      },\n      \"required\" : true              \n    },\n
    \   \"phones\" : {\n      \"type\" : \"array\",\n      \"description\" : \"A container
    for the organization's phone number(s).\",\n      \"minItems\" : 0,\n      \"items\"
    : { \"$ref\" : \"http://api.covisint.com/schema/phone#\" }\n    },\n    \"email\"
    : {\n      \"type\" : \"string\",\n      \"maxLength\" : 1000, \n      \"description\"
    : \"The organization's email address.\"\n    },\n    \"url\" : {\n      \"type\"
    : \"string\",\n      \"description\" : \"A URL representing this organization.\",\n
    \     \"maxLength\" : 1000\n    },\n    \"authDomain\" : {\n      \"type\" : \"string\",\n
    \     \"description\" : \"This organization's authentication domain.\",\n      \"maxLength\"
    : 50\n    },\n    \"organizationType\" : {\n      \"type\" : \"string\",\n      \"description\"
    : \"The organization type.  Unless there is reason to specify otherwise, this
    value doesn't need to be provided and will be defaulted.\",\n      \"maxLength\"
    : 5,\n      \"default\" : \"AO\"\n    },\n    \"organizationSubtype\" : {\n      \"type\"
    : \"string\",\n      \"description\" : \"The organization subtype.  Unless there
    is reason to specify otherwise, this value doesn't need to be provided and will
    be defaulted.\",\n      \"maxLength\" : 10\n    },\n    \"accountNumber\" : {\n
    \     \"type\" : \"string\",\n      \"description\" : \"The organization account
    number.\",\n      \"maxLength\" : 50\n    },\n    \"externalCode\" : {\n      \"type\"
    : \"string\",\n      \"description\" : \"Code assigned to identify the organization
    to external systems.\",\n      \"maxLength\" : 50\n    },\n    \"duns\" : {\n
    \     \"type\" : \"string\",\n      \"description\" : \"The organization DUNS
    number.\",\n      \"maxLength\" : 50\n    },\n    \"classification\" : {\n      \"type\"
    : \"string\",\n      \"description\" : \"The organization classification.\",\n
    \     \"maxLength\" : 100\n    },\n    \"public\" : {\n      \"type\" : \"boolean\",\n
    \     \"description\" : \"Whether this is a public organization.  Defaults to
    true.\"\n    },\n    \"passwordPolicy\" : {\n      \"description\": \"The password
    policy associated to this particular organization.\",  \n      \"$ref\": \"http://api.covisint.com/schema/resourceReference#\"\n
    \   },\n    \"authenticationPolicy\" : {\n      \"description\": \"The authentication
    policy associated to this particular organization.\",  \n      \"$ref\": \"http://api.covisint.com/schema/resourceReference#\"\n
    \   }\n  }\n}\n"
traits:
- secured:
    usage: Apply this to any method that needs to be secured. Requests with this trait
      require authentication using a bearer token.
    headers:
      Authorization:
        description: Access token that is obtained from the /token endpoint of the
          oauth API.
        pattern: "^Bearer .*$"
        example: Bearer ZCtYUGpYRXpET0JvVE1rZzlWV3I1Yk
        required: true
    responses:
      401:
        description: Unauthenticated request.  This is returned if the access token
          is missing, invalid, or expired.  Access tokens are obtained through the
          /token endpoint of the Oauth API.
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
      403:
        description: Unauthorized request.  The requestor is not authorized to perform
          the requested operation.
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
- getResponse:
    responses:
      404: &3
        description: |
          The URI requested is invalid or the resource requested does not exist.
          ___
          Substatus codes and error messages are mentioned below:
          + (If a resource id is a URI parameter) framework:resource:missing - A resource with the following ID was not found: {resourceId}
          + No message for an invalid URI
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
      406: &1
        description: |
          Unable to produce content of specified 'Accept' media type
          ___
          Substatus codes and error messages are mentioned below:
          + framework:request:unsupported:mediatype - The server is unable to produce content of type {acceptMediaType}
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
      500: &2
        description: |
          An unknown server error occurred
          ___
          Substatus codes and error messages are mentioned below:
          + framework:unknown
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
- getSearchResponse:
    responses:
      406: *1
      500: *2
- postResponse:
    responses:
      406: *1
      415: &4
        description: |
          Unable to consume content of specified 'Content-Type' media type
          ___
          Substatus codes and error messages are mentioned below:
          + framework:request:unsupported:mediatype - The server is unable to consume content of type {contentMediaType}
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
      500: *2
- deleteResponse:
    responses:
      500: *2
- putResponse:
    responses:
      404: *3
      406: *1
      409: &5
        description: |
          There is a conflict in identifying the resource being acted on.  There are two categories.  (1) The unique identifier in the URL and in the body are different.  (2) The current version of the resource being updated and the version sent in the body of the request. This may be an indication that the resource has changed since the client loaded it. The conflict should be resolved and the update resubmitted with the current version of the resource.
          + framework:resource:conflict
          + framework:resource:conflict:id - The ID of the resource in the request, {requestedId}, does not match the ID of the given resource, {resourceId}
          + framework:resource:conflict:version - The version of the provided resource, {requestVersion}, does not match the current version of the resource, {latestVersion}
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
      415: *4
      500: *2
- putResponseV2:
    responses:
      404: *3
      406: *1
      409:
        description: |
          There is a conflict in identifying the resource being acted on. The unique identifier in the URL and body are different.
          + framework:resource:conflict
          + framework:resource:conflict:id - The ID of the resource in the request, {requestedId}, does not match the ID of the given resource, {resourceId}
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
      415: *4
      500: *2
- putCreateResponse:
    responses:
      406: *1
      409: *5
      415: *4
      500: *2
- pagableRequest:
    queryParameters:
      page:
        description: Which page to return in the paginated results.  The first page
          is page 1.
        type: integer
        required: false
        minimum: 1
        default: 1
      pageSize:
        description: How many items per page in the paginated results.
        type: integer
        required: false
        minimum: 1
        default: 50
        maximum: 200
- taggable:
    queryParameters:
      tag:
        description: Get the resource based on specified tag. Multiple parameters
          are allowed and the search results will be a union.
        type: string
        required: false
- sortable:
    queryParameters:
      sortBy:
        description: Sort the results based on some criteria.
        example: +creation, -name (These will sort by creation ascending, name descending.
          If "+/-" prefix is omitted, then an ascending sort is assumed).
        type: string
        required: false
- searchable:
    description: Search resources based on the given filter parameters. Search is
      case-insensitive. <<since>> <<entitlement>>
"/organizations":
  is:
  - secured
  description: Collection endpoint for organization resources
  get:
    is:
    - getSearchResponse
    - pagableRequest
    description: Performs a search for organization resources.
    headers:
      Accept:
        description: Used to request the appropriate organization resource media type.
        example: application/vnd.com.covisint.platform.organization.v1+json
        type: string
        required: true
    queryParameters:
      name:
        description: Retrieve only organizations with the specified name.  The search
          is case-insensitve.  Multiple parameters are supported and the search results
          will be a union.
        type: string
        required: false
      parentOrganization:
        description: Retrieve the organizations with the specified parent organization
          id.
        type: string
        required: false
      rootOrganization:
        description: Retrieve the organizations with the specified root organization
          id.
        type: string
        required: false
    responses:
      200:
        description: All organizations that satisfy the query parameters were successfully
          retrieved (response collection may be empty).
        body:
          application/vnd.com.covisint.platform.organization.v1+json:
            schema: organization
      400:
        description: |
          There was a problem with the client's request
          ___
          Substatus codes are mentioned below:
          + framework:request:param:invalid - The following parameter should not be part of the request: {queryParameterName}
          + framework:request:invalid:header:value - Invalid x-requestor header value. Valid values are &#91;person, application&#93;
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
  post:
    is:
    - postResponse
    description: Create a new organization.
    headers:
      Accept:
        description: The organization media type being sent in the entity body.
        example: application/vnd.com.covisint.platform.organization.v1+json
        type: string
        required: true
    body:
      application/vnd.com.covisint.platform.organization.v1+json:
        schema: organization
    responses:
      201:
        description: The organization was successfully created.
        body:
          application/vnd.com.covisint.platform.organization.v1+json:
            schema: organization
      400:
        description: |
          There was a problem with the client's request
          ___
          Substatus codes are mentioned below:
          + framework:request
          + framework:request:io
          + framework:request:io:read - Invalid input. There was an error while parsing.
          + framework:request:io:read:parsing
          + framework:request:io:write
          + framework:request:header:missing - Missing request header: {headerName}
          + framework:request:param:missing - Missing request parameter: {queryParameterName}
          + framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}
          + framework:request:data:invalid - The following information should not be part of the resource: {resourceFieldName}
          + framework:resource:data:illegal - The following information was illegal from the resource:  {fieldSpecificError(s)}
          + framework:request:invalid:header:value - Invalid x-requestor header value. Valid values are &#91;person, application&#93;
          + organization:request:invalid:phone:type - Unsupported Phone type: {phoneType(s)}
          + organization:request:invalid:password:policy:type - The password policy type supplied is not valid
          + organization:request:invalid:authentication:policy:type - The authentication policy type supplied is not valid
          + framework:resource:missing - The following resources were not found: {resources}
        body:
          application/vnd.com.covisint.error.v1+json:
            schema: errorResponseSchema
  "/{id}":
    uriParameters:
      id:
        description: The unique organization identifier.
        type: string
        maxLength: 36
        required: true
    is:
    - secured
    description: Individual resource endpoint for organization resources.
    get:
      is:
      - getResponse
      description: get organization by id.
      headers:
        Accept:
          description: The organization media type being sent in the entity body.
          example: application/vnd.com.covisint.platform.organization.v1+json
          type: string
          required: true
      responses:
        200:
          description: The organization was successfully retrieved.
          body:
            application/vnd.com.covisint.platform.organization.v1+json:
              schema: organization
        400:
          description: |
            There was a problem with the client's request
            ___
            Substatus codes are mentioned below:
            + framework:request:invalid:header:value - Invalid x-requestor header value. Valid values are &#91;person, application&#93;
          body:
            application/vnd.com.covisint.error.v1+json:
              schema: errorResponseSchema
    put:
      is:
      - putResponse
      description: Update an organization.
      headers:
        Accept:
          description: The organization media type being sent in the entity body.
          example: application/vnd.com.covisint.platform.organization.v1+json
          type: string
          required: true
      body:
        application/vnd.com.covisint.platform.organization.v1+json:
          schema: organization
      responses:
        200:
          description: The organization was successfully updated.
          body:
            application/vnd.com.covisint.platform.organization.v1+json:
              schema: organization
        400:
          description: |
            There was a problem with the client's request
            ___
            Substatus codes are mentioned below:
            + framework:request
            + framework:request:io
            + framework:request:io:read - Invalid input. There was an error while parsing.
            + framework:request:io:read:parsing
            + framework:request:io:write
            + framework:request:header:missing - Missing request header: {headerName}
            + framework:request:param:missing - Missing request parameter: {queryParameterName}
            + framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}
            + framework:resource:data:illegal - The following information was illegal from the resource:  {fieldSpecificError(s)}
            + framework:request:invalid:header:value - Invalid x-requestor header value. Valid values are &#91;person, application&#93;
            + organization:request:invalid:phone:type - Unsupported Phone type: {phoneType(s)}
            + framework:resource:missing - The following resources were not found: {resources}
            + organization:request:invalid:id - The organization with id {id} belongs to another realm
          body:
            application/vnd.com.covisint.error.v1+json:
              schema: errorResponseSchema
    "/hierarchy":
      is:
      - secured
      description: hierarchy endpoint for organization resources
      get:
        is:
        - getResponse
        description: Get organization hierarchy for the given root organization id.
        headers:
          Accept:
            description: The named hierarchy media type being sent back in the response
              entity body.
            example: application/vnd.com.covisint.platform.reference.hierarchy.v1+json
            type: string
            required: true
        responses:
          200:
            description: The organization hierarchy was successfully retrieved.  Returns
              a named resource reference to the root organization, which can be traversed
              to get the child organization references.
            body:
              application/vnd.com.covisint.platform.reference.hierarchy.v1+json:
                schema: namedResourceReference
          400:
            description: "There was a problem with the client's request\n___\nSubstatus codes are mentioned below:\n+ framework:request:invalid:header:value - Invalid x-requestor header value. Valid values are &#91;person, application&#93; \n"
            body:
              application/vnd.com.covisint.error.v1+json:
                schema: errorResponseSchema