> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.fax.plus/llms.txt
> Use this file to discover all available pages before exploring further.
# List contact groups
> Get contact groups with optional search and pagination. You can also retrieve specific groups by providing comma-separated IDs (Permitted scopes: **fax:all:read**)
```js NodeJS SDK theme={null}
const axios = require('axios');
const ContactsApiFp = require('@alohi/faxplus-api').ContactsApiFp;
const Configuration = require('@alohi/faxplus-api').Configuration;
const config = new Configuration({
accessToken: accessToken,
basePath: 'https://restapi.fax.plus/v3',
baseOptions: {
headers: {
"x-fax-clientid": clientId,
}
}
});
async function listContactGroups() {
const req = await ContactsApiFp(config).listContactGroups({
userId: 'self',
search: '',
offset: 0,
limit: 50
});
const resp = await req(axios);
}
listContactGroups()
```
```python Python SDK theme={null}
from faxplus import ApiClient, ContactsApi
from faxplus.configuration import Configuration
conf = Configuration()
conf.access_token = access_token
api_client = ApiClient(header_name='x-fax-clientid', header_value=client_id, configuration=conf)
api = ContactsApi(api_client)
resp = api.list_contact_groups(user_id='self', search='', offset=0, limit=50)
```
```bash cURL theme={null}
curl -X GET https://restapi.fax.plus/v3/accounts/self/contact-groups?search=&offset=0&limit=50 \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {access-token}' \
-H 'x-fax-clientid: "YOUR_CLIENT_ID"'
```
## OpenAPI
````yaml get /accounts/self/contact-groups
openapi: 3.0.1
info:
title: Fax.Plus REST API
description: >-
This is the Fax.Plus API v3 developed for third party developers and
organizations. In order to have a better coding experience with this API,
let's quickly go through some points:
- This API assumes
**/accounts** as an entry point with the base url of
**https://restapi.fax.plus/v3**.
- This API treats all date and
times sent to it in requests as **UTC**. Also, all dates and times returned
in responses are in **UTC**
- Once you have an access_token, you
can easily send a request to the resource server with the base url of
**https://restapi.fax.plus/v3** to access your permitted resources. As an
example to get the user's profile info you would send a request to
**https://restapi.fax.plus/v3/accounts/self** when **Authorization** header
is set to **Bearer YOUR_ACCESS_TOKEN** and custom header of
**x-fax-clientid** is set to YOUR_CLIENT_ID
version: 3.4.0
contact:
name: Fax.Plus
email: info@fax.plus
url: https://github.com/alohi
servers:
- url: https://restapi.fax.plus/v3
- url: /v3
security: []
paths:
/accounts/self/contact-groups:
get:
tags:
- Contacts
summary: List contact groups
description: >-
Get contact groups with optional search and pagination. You can also
retrieve specific groups by providing comma-separated IDs (Permitted
scopes: **fax:all:read**)
operationId: listTags
parameters:
- name: ids
in: query
schema:
type: string
description: >-
Comma-separated list of group IDs to retrieve (max 50). When
provided, other filters are ignored
- name: group
in: query
schema:
type: string
description: Search term to filter groups
- name: offset
in: query
schema:
type: integer
default: 0
description: Offset for pagination
- name: limit
in: query
schema:
type: integer
default: 50
maximum: 50
description: Limit for pagination (max 50)
- name: shared
in: query
schema:
type: boolean
default: false
description: >-
If true, return shared/corporate groups. If false, return personal
groups
responses:
'200':
$ref: '#/components/responses/ContactGroupList'
'400':
$ref: '#/components/responses/Error'
'401':
$ref: '#/components/responses/UnauthorizedError'
'500':
$ref: '#/components/responses/ServerError'
security:
- personal_access_token:
- fax:all:read
- oauth2:
- all
components:
responses:
ContactGroupList:
description: Response containing a list of groups
content:
application/json:
schema:
$ref: '#/components/schemas/ContactGroupList'
Error:
description: Error object in case there's a problem with given data
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: invalid_user_id
description: Invalid user id given
UnauthorizedError:
description: Error object in case there's a problem with the authorization
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: unauthorized
description: >-
The access token provided is expired, revoked, malformed, or
invalid for other reasons.
ServerError:
description: Error object in case there's a server error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: internal_server_error
description: An unexpected error happened, please contact support
schemas:
ContactGroupList:
type: object
properties:
records:
type: array
items:
$ref: '#/components/schemas/ContactGroup'
description: List of groups
total_count:
type: integer
description: Total number of groups matching the query
Error:
properties:
description:
type: string
error:
type: string
additionalProperties: false
ContactGroup:
type: object
properties:
id:
type: string
description: Group ID
example: 5f7a8b9c0d1e2f3a4b5c6d7f
name:
type: string
description: Group name
example: VIP Clients
notes:
type: string
description: Additional notes or description for the group
example: Important clients only
is_shared:
type: boolean
description: Whether group is shared with corporate members
example: true
creation_date:
type: string
description: Date group was created
example: '2024-01-10T09:00:00Z'
modification_date:
type: string
description: Date group was last modified
example: '2024-02-15T11:20:00Z'
securitySchemes:
personal_access_token:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
Personal Access Token (PAT) is a Bearer token used for secure API calls.
For direct API calls, the PAT is used in the Authorization header as
'Bearer {PAT}'. For MCP usage, configure your PAT in your MCP client
settings (e.g., in your IDE's MCP server configuration) - authentication
will be handled automatically.
oauth2:
type: oauth2
description: OAuth2 Authorization Grant
flows:
authorizationCode:
authorizationUrl: >-
https://accounts.fax.plus/login?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost&scope=all
tokenUrl: https://accounts.fax.plus/token
refreshUrl: >-
https://accounts.fax.plus/token?grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN
scopes:
all: >-
for now when a user grants permission, all grants will be
permitted
````