# Scope Assigments

POST /

#### Description

Creates or updates hiearchical scope assignments in a Hyperproof organization.

Endpoint: POST /
Version: 1.0
Security: oauth2

## Request fields (application/json):

  - `objectType` (string)
    The type of the object.
    Enum: "audit", "connection", "control", "controlScope", "domain", "freshnessHistory", "exportFile", "label", "organization", "organizationUser", "policy", "program", "proof", "request", "requirement", "risk", "riskRegister", "section", "task", "scope", "template", "user"

  - `objectId` (string)
    The unique identifier of the object which will be associated with one or more scopes

  - `scopeIds` (array)
    The unique identifiers of the scopes which will be associated with the object

## Response 200 fields (application/json):

  - `controls` (array)
    Example: [{"id":"d88d505d-5199-11ee-a644-522476618ae8","orgId":"ce83e3cd-5199-11ee-a644-522476618ae8","controlType":"scopeAssignment","controlIdentifier":"SOC2-P4.1.1_Legal","name":"Include in the privacy notice the use of collected personal information","scopeName":"Legal","description":"The privacy notice identifies the use of collected personal information.","notes":"","domainId":"d7cf0a26-5199-11ee-a644-522476618ae8","domainName":"Privacy","freshnessPolicy":"manual","freshForDuration":"PT720H","freshness":"fresh","freshAsOfDate":"2025-01-12T18:26:10.00.5365Z","freshAsOfNote":"Initial freshness set","implementation":"inProgress","testingStatus":"effective","testingDeficiency":[],"computeTestingStatus":false,"automation":"partial","health":"notAvailable","overrideHealth":false,"owner":{"id":"d2363cab-5199-11ee-a644-522476618ae8","type":"activeUser","userId":"82d7c228-8bcd-11e9-a94b-ab3de8494987","email":"jane.doe@example.com","givenName":"Jane","surname":"Doe","language":"en","locale":"US","timeZone":"America/Los_Angeles","status":"active"},"customFields":[{"fieldId":"ceb912ab-519b-11ee-a644-522476618ae8","fieldName":"Sponsor","fieldType":"text","textValue":"John Smith"}],"status":"active","createdBy":"82d7c228-8bcd-11e9-a94b-ab3de8494987","createdOn":"2023-09-12T18:26:10.005365Z","updatedBy":"82d7c228-8bcd-11e9-a94b-ab3de8494987","updatedOn":"2023-09-12T18:26:10.005365Z","permissions":[]}]

  - `controls.id` (string)
    The unique identifier for the control
    Example: "d88d505d-5199-11ee-a644-522476618ae8"

  - `controls.orgId` (string)
    The unique identifier for the organization
    Example: "ce83e3cd-5199-11ee-a644-522476618ae8"

  - `controls.controlType` (string)
    Type of control
    Enum: "simple", "parent", "scopeAssignment"

  - `controls.controlIdentifier` (string)
    The human readable unique identifier for the control within the organization
    Example: "SOC2-P4.1.1_Legal"

  - `controls.name` (string)
    The name of the control
    Example: "Include in the privacy notice the use of collected personal information"

  - `controls.scopeName` (string)
    Name of the scope associated with the control populated if the 'controlType' is 'scopeAssignment'
    Example: "Legal"

  - `controls.description` (string)
    The description of the control
    Example: "The privacy notice identifies the use of collected personal information."

  - `controls.notes` (string)
    Additional notes about the control

  - `controls.domainId` (string)
    The unique identifier of the domain
    Example: "d7cf0a26-5199-11ee-a644-522476618ae8"

  - `controls.domainName` (string)
    The name of the domain
    Example: "Privacy"

  - `controls.freshnessPolicy` (string)
    The freshness policy of an object. Set to 'manual' with a 'freshAsOfDate' value otherwise 'freshness' will be set to 'unknown'.
    Enum: "none", "manual"

  - `controls.freshForDuration` (string)
    The duration after which control becomes stale
    Example: "PT720H"

  - `controls.freshness` (string)
    The freshness status of an object. Cannot be set if 'freshnessPolicy' is 'none' and 'freshAsOfDate' is null.
    Enum: "noFreshness", "fresh", "expired", "unknown"

  - `controls.freshAsOfDate` (string)
    The date when freshness was last marked 'fresh'
    Example: "2025-01-12T18:26:10.00.5365Z"

  - `controls.freshAsOfNote` (string)
    The note populated when the control was marked fresh
    Example: "Initial freshness set"

  - `controls.implementation` (string)
    Implementation status
    Enum: "unknown", "notStarted", "inProgress", "completed"

  - `controls.testingStatus` (string)
    Testing status
    Enum: "notTested", "inProgress", "effective", "ineffective"

  - `controls.testingDeficiency` (array)
    Design deficiency: The control, as designed, is inadequate to meet its intended objective. Operation deficiency: The control’s design is sound, but it is not being executed or followed as intended in practice.
    Enum: "design", "operation"

  - `controls.computeTestingStatus` (boolean)
    Whether testing status is computed automatically

  - `controls.automation` (string)
    Determines whether this control can be automated and its current status
    Enum: "notStarted", "partial", "fullyAutomated", "cantAutomate"

  - `controls.health` (string)
    Whether the health status is available and its current status
    Enum: "critical", "atRisk", "healthy", "notAvailable"

  - `controls.overrideHealth` (boolean)
    Whether health status is overridden

  - `controls.owner` (object)
    Example: {"id":"d2363cab-5199-11ee-a644-522476618ae8","type":"activeUser","userId":"82d7c228-8bcd-11e9-a94b-ab3de8494987","email":"jane.doe@example.com","givenName":"Jane","surname":"Doe","language":"en","locale":"US","timeZone":"America/Los_Angeles","status":"active"}

  - `controls.owner.id` (string)
    Unique identifier for the user within the organization
    Example: "d2363cab-5199-11ee-a644-522476618ae8"

  - `controls.owner.type` (string)
    Type of Hyperproof user
    Enum: "activeUser", "deactivatedUser", "contact", "serviceAccount", "deactivatedServiceAccount syncServiceAccount", "deactivatedSyncServiceAccount"

  - `controls.owner.userId` (string)
    Unique identifier for the user across all Hyperproof organizations
    Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"

  - `controls.owner.email` (string)
    The email address of the user
    Example: "jane.doe@example.com"

  - `controls.owner.givenName` (string)
    The given name of the user
    Example: "Jane"

  - `controls.owner.surname` (string)
    The surname of the user
    Example: "Doe"

  - `controls.owner.language` (string)
    The language of the user
    Example: "en"

  - `controls.owner.locale` (string)
    The locale of the user
    Example: "US"

  - `controls.owner.timeZone` (string)
    The time zone of the user
    Example: "America/Los_Angeles"

  - `controls.owner.title` (string)
    The title of the user

  - `controls.owner.status` (string)
    The status of the user
    Enum: "active", "archived", "deleted", "pending", "canceled"

  - `controls.groupId` (string)
    The unique identifier of the group assigned to the control

  - `controls.customFields` (array)
    Example: [{"fieldId":"ceb912ab-519b-11ee-a644-522476618ae8","fieldName":"Sponsor","fieldType":"text","textValue":"John Smith"}]

  - `controls.customFields.fieldId` (string)
    Unique identifier for the custom field

  - `controls.customFields.fieldName` (string)
    Name of the custom field

  - `controls.customFields.fieldType` (string)
    Type of field
    Enum: "text", "number", "date", "user", "textSingleSelect", "textMultiSelect"

  - `controls.customFields.numberFormat` (string)
    Format if the field type is number
    Enum: "decimal", "percentage"

  - `controls.customFields.textValue` (string)
    Value if the field type is text

  - `controls.customFields.numberValue` (number)
    Value if the field type is number

  - `controls.customFields.dateValue` (string)
    Value if the field type is date

  - `controls.customFields.userValue` (string)
    Value if the field type is user

  - `controls.customFields.selection` (string)
    Value for textSingleSelect

  - `controls.customFields.selections` (array)
    List of values for textMultiSelect

  - `controls.status` (string)
    The status of the object
    Enum: "active", "archived"

  - `controls.createdBy` (string)
    The unique identifier of the user who created the control
    Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"

  - `controls.createdOn` (string)
    The date the control was created (ISO-8601 format)
    Example: "2023-09-12T18:26:10.005365Z"

  - `controls.updatedBy` (string)
    The unique identifier of the user who last updated the control
    Example: "82d7c228-8bcd-11e9-a94b-ab3de8494987"

  - `controls.updatedOn` (string)
    The date the control was updated (ISO-8601 format)
    Example: "2023-09-12T18:26:10.005365Z"

  - `controls.permissions` (array)
    List of permissions the API user has on the control
    Example: []

  - `controls._isPartialData` (boolean)
    This is true when the user does not have read permissions on the control

  - `controls.teamName` (string)
    This field is deprecated and will be removed in a future version. Use scopeName instead