# List all Number Groups

GET https://YOUR_SPACE.signalwire.com/api/relay/rest/number_groups

Returns a list of your Number Groups. The groups are returned sorted
by creation date, with the most recent appearing first. The list is
filterable by sending in any of the following parameters.

#### Permissions

The API token used to authenticate must have the following scope(s) enabled to make a successful request: _Numbers_.

[Learn more about API scopes](/docs/platform/your-signalwire-api-space).

Reference: https://signalwire.com/docs/apis/relay-rest/number-groups/list-number-groups

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: relay-rest
  version: 1.0.0
paths:
  /number_groups:
    get:
      operationId: list-number-groups
      summary: List all Number Groups
      description: >-
        Returns a list of your Number Groups. The groups are returned sorted

        by creation date, with the most recent appearing first. The list is

        filterable by sending in any of the following parameters.


        #### Permissions


        The API token used to authenticate must have the following scope(s)
        enabled to make a successful request: _Numbers_.


        [Learn more about API scopes](/docs/platform/your-signalwire-api-space).
      tags:
        - subpackage_numberGroups
      parameters:
        - name: filter_name
          in: query
          description: >-
            Filter by name. Returns all number groups containing this value as a
            substring.
          required: false
          schema:
            type: string
        - name: page_number
          in: query
          description: The page number to retrieve.
          required: false
          schema:
            type: integer
            default: 0
        - name: page_size
          in: query
          description: The number of results per page.
          required: false
          schema:
            type: integer
            default: 50
        - name: page_token
          in: query
          description: Token for cursor-based pagination.
          required: false
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            SignalWire Basic Authentication using Project ID and API Token.


            The client sends HTTP requests with the Authorization header
            containing

            the word Basic followed by a space and a base64-encoded string of
            project_id:token.

            The project ID will be used as the username and the API token as the
            password.


            Example:

            ```

            Authorization: Basic base64(project_id:token)

            ```
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NumberGroupListResponse'
        '401':
          description: Access is unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode401'
        '422':
          description: The request failed validation. See errors for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.ValidationError'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
servers:
  - url: https://YOUR_SPACE.signalwire.com/api/relay/rest
components:
  schemas:
    PaginationLinks:
      type: object
      properties:
        self:
          type: string
          description: Link to the current page.
        first:
          type: string
          description: Link to the first page.
        next:
          type: string
          description: Link to the next page. Only present when there are more results.
        prev:
          type: string
          description: Link to the previous page. Only present when not on the first page.
      required:
        - self
        - first
      description: Pagination links for list responses.
      title: PaginationLinks
    uuid:
      type: string
      format: uuid
      description: Universal Unique Identifier.
      title: uuid
    NumberGroup:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/uuid'
          description: >-
            The unique identifier of the Number Group on SignalWire. This can be
            used to update or delete the group programmatically.
        name:
          type: string
          description: >-
            The name given to the number group. Helps to distinguish different
            groups within your project.
        sticky_sender:
          type: boolean
          description: >-
            Whether the number group uses the same 'From' number for outbound
            requests to a number, or chooses a random one.
        phone_number_count:
          type: integer
          description: The number of phone numbers within the group.
      required:
        - id
        - name
        - sticky_sender
        - phone_number_count
      description: Number group model.
      title: NumberGroup
    NumberGroupListResponse:
      type: object
      properties:
        links:
          $ref: '#/components/schemas/PaginationLinks'
          description: Pagination links.
        data:
          type: array
          items:
            $ref: '#/components/schemas/NumberGroup'
          description: List of number groups.
      required:
        - links
        - data
      description: Response containing a list of number groups.
      title: NumberGroupListResponse
    TypesStatusCodesStatusCode401Error:
      type: string
      enum:
        - Unauthorized
      title: TypesStatusCodesStatusCode401Error
    Types.StatusCodes.StatusCode401:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/TypesStatusCodesStatusCode401Error'
      required:
        - error
      description: Access is unauthorized.
      title: Types.StatusCodes.StatusCode401
    Types.StatusCodes.SpaceApiErrorItem:
      type: object
      properties:
        detail:
          type: string
          description: A description of what caused the error.
        status:
          type: string
          description: The HTTP status code.
        title:
          type: string
          description: A short summary of the error type.
        code:
          type: string
          description: The error code.
      required:
        - detail
        - status
        - title
        - code
      description: Details about a specific validation error.
      title: Types.StatusCodes.SpaceApiErrorItem
    Types.StatusCodes.ValidationError:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Types.StatusCodes.SpaceApiErrorItem'
          description: List of validation errors.
      required:
        - errors
      description: The request failed validation. See errors for details.
      title: Types.StatusCodes.ValidationError
    TypesStatusCodesStatusCode500Error:
      type: string
      enum:
        - Internal Server Error
      title: TypesStatusCodesStatusCode500Error
    Types.StatusCodes.StatusCode500:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/TypesStatusCodesStatusCode500Error'
      required:
        - error
      description: An internal server error occurred.
      title: Types.StatusCodes.StatusCode500
  securitySchemes:
    SignalWireBasicAuth:
      type: http
      scheme: basic
      description: >-
        SignalWire Basic Authentication using Project ID and API Token.


        The client sends HTTP requests with the Authorization header containing

        the word Basic followed by a space and a base64-encoded string of
        project_id:token.

        The project ID will be used as the username and the API token as the
        password.


        Example:

        ```

        Authorization: Basic base64(project_id:token)

        ```

```

## SDK Code Examples

```python
import requests

url = "https://your_space.signalwire.com/api/relay/rest/number_groups"

headers = {"Authorization": "Basic <project_id>:<api_token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://your_space.signalwire.com/api/relay/rest/number_groups';
const options = {method: 'GET', headers: {Authorization: 'Basic <project_id>:<api_token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://your_space.signalwire.com/api/relay/rest/number_groups"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Basic <project_id>:<api_token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://your_space.signalwire.com/api/relay/rest/number_groups")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Basic <project_id>:<api_token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://your_space.signalwire.com/api/relay/rest/number_groups")
  .header("Authorization", "Basic <project_id>:<api_token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://your_space.signalwire.com/api/relay/rest/number_groups', [
  'headers' => [
    'Authorization' => 'Basic <project_id>:<api_token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://your_space.signalwire.com/api/relay/rest/number_groups");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Basic <project_id>:<api_token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Basic <project_id>:<api_token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://your_space.signalwire.com/api/relay/rest/number_groups")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```