# Working with scoped controls

When integrating with the Hyperproof API, managing scoped controls is a critical part of the process. This article explains the essential concepts and shows you how to work with scoped controls—from retrieving scope data to updating assignments through API calls.

## What is a scoped control?

A scoped control is the child control of a parent control. Scoped controls have a variety of use cases, but the most common is to track proof collection on controls for subdivisions of an organization. For more information, refer to [Working with scopes](https://docs.hyperproof.io/admin/en/get-to-know-hyperproof/working-with-teams).

When a scope is assigned to a control in the UI, Hyperproof generates a new child control. This control includes a `parentControlId` that links it to the original control, maintaining a clear hierarchy and ensuring each scoped control can be traced back to its source.

## Accessing scope information for controls

### Fetching a single control with GET /controls/{controlId}

If you call `https://api.hyperproof.app/v1/controls/{controlId}` to retrieve a control’s details, you may notice that `scopeName` and other scope-related fields aren’t included in the response. That's expected behavior.

### Getting the full picture with GET /controls and expanded scopes

Use the `GET /controls` endpoint with the `expandscopes=true` query parameter. This returns additional scoped-control details, including:

- Controls that have a `parentControlId`, indicating their parent control.
- The associated `scopeId` and `scopeName` for each scoped control.



```
GET https://api.hyperproof.app/v1/controls?expandscopes=true
```

## Assigning or changing scopes on controls

### Changing the scope on an existing control with PATCH

To update the scope of an existing control, issue a PATCH request to `https://api.hyperproof.app/v1/controls/{controlId}`. Be sure to include the `scopeId` you want to assign in the request body. This links the control to the specified scope.

> **Note**: Because there's no API endpoint to list all available `scopeIds`, the `scopeId` must be determined beforehand. To get the `scopeId`, run the `GET /controls?expandscopes=true` call. Be sure to double-check that the `scopeId` is valid for your Hyperproof setup before sending the request.


`PATCH https://api.hyperproof.app/v1/controls/{controlId}`


```
Content-Type: application/json  
{  
"scopeId": "desiredScopeId"  
}
```

### Setting up a new control with a scope using POST

If you’re creating a control from scratch, you can assign a scope right away with the `POST /controls` endpoint. Be sure to use the desired `scopeId` in the request payload alongside other control details.

> **Note**: This action creates a NEW control that can be used as a parent. Child controls are not created using the API.


**Currently, the creation of scoped child controls on existing controls is not supported.**

`POST https://api.hyperproof.app/v1/controls`


```
Content-Type: application/json

{
"name": "New Control Name",
"scopeId": "desiredScopeId",
...other control properties...
}
```

## Known limitations

Since there is no dedicated endpoint for listing `scopeIds`, the recommended approach for finding scope IDs is to query controls with the `expandscopes=true` parameter or retrieve the IDs directly from the Hyperproof UI.