Groups

Groups are where communities live in Ourvoice — they are a collection of contacts you're talking to all at once. On this page, we'll dive into the different group endpoints you can use to manage groups programmatically. We'll look at how to query, create, update, and delete groups.

The group model contains all the information about your groups, including what contacts are in the group and the group's name and description.

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the group.

  • Name
    name
    Type
    string
    Description

    The name for the group.

  • Name
    description
    Type
    string
    Description

    The description for the group.

  • Name
    contacts
    Type
    array
    Description

    An array of contact objects that are members of the group.

  • Name
    accounts
    Type
    array
    Description

    An array of account objects that are accounts of the group.

  • Name
    created_at
    Type
    timestamp
    Description

    Timestamp of when the group was created.

  • Name
    updated_at
    Type
    timestamp
    Description

    Timestamp of when the group was updated.

GET/v1/groups/{group_id}/contacts

List all contacts

This endpoint allows you to retrieve a paginated list of all contacts in a group.

Required attributes

  • Name
    group_id
    Type
    string
    Description

    The group ID.

Request

GET
/v1/groups/{group_id}/contacts
curl --request GET \
    --get "api.getourvoice.com/v1/groups/c6b52883-7f67-455e-8497-0ff3f09c3830/contacts" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

Response

{
  "data": [
    {
        "id": "7ca20e14-0c44-4f7a-be70-6dfb95152ffd",
        "first_name": "Nanisca",
        "last_name": "Agodjie",
        "phone_number": "22996XXXXXX",
        "language": "french",
        "custom_fields": "{\"custom_field_1\":\"distinctio\", \"custom_field_2\":\"dolores\"}",
        "created_at": "2023-03-02T16:38:02.000000Z",
        "updated_at": "2023-03-02T16:38:02.000000Z"
    },
    {
        "id": "7847c224-58f7-4ae6-84e4-2e0ba477ee04",
        "first_name": "Nanisca",
        "last_name": "Agodjie",
        "phone_number": "22996XXXXXX",
        "language": "french",
        "custom_fields": "{\"custom_field_1\":\"vitae\", \"custom_field_2\":\"voluptatibus\"}",
        "created_at": "2023-03-02T16:38:02.000000Z",
        "updated_at": "2023-03-02T16:38:02.000000Z"
    }
]
}
GET/v1/groups

Retrieve groups

This endpoint allows you to list all your groups in Ourvoice.

Request

GET
/v1/groups
curl --request GET \
    "https://api.getourvoice.com/v1/groups" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \

Response (200)

{
  "data": [
    {
        "id": "09fa725f-057e-4113-a236-c85bd61d0cbd",
        "name": "NaniscaAgodjie",
        "description": "voluptatem",
        "contacts": {
            "totalCount": 0,
            "href": "http://api.getourvoice.com/v1/groups/09fa725f-057e-4113-a236-c85bd61d0cbd/contacts"
        },
        "created_at": "2023-05-31T14:37:56.000000Z",
        "updated_at": "2023-05-31T14:37:56.000000Z"
    },
    {
        "id": "4f0c3c56-7317-49c7-b376-afe1860fe07a",
        "name": "NawiAgodjie",
        "description": "a",
        "contacts": {
            "totalCount": 0,
            "href": "http://api.getourvoice.com/v1/groups/4f0c3c56-7317-49c7-b376-afe1860fe07a/contacts"
        },
        "created_at": "2023-05-31T14:37:56.000000Z",
        "updated_at": "2023-05-31T14:37:56.000000Z"
    }
]
}
GET/v1/groups

Retrieve filtered groups

This endpoint allows you to list your filtered groups in Ourvoice.

Request

GET
/v1/groups
curl --request GET \
    "https://api.getourvoice.com/v1/groups?page=1&limit=10&filter[to]=&filter[from]=&filter[direction]=outgoing&filter[status]=completed&filter[duration]=" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \

Response (200)

{
  "data": [
    {
        "id": "09fa725f-057e-4113-a236-c85bd61d0cbd",
        "name": "NaniscaAgodjie",
        "description": "voluptatem",
        "contacts": {
            "totalCount": 0,
            "href": "http://api.getourvoice.com/v1/groups/09fa725f-057e-4113-a236-c85bd61d0cbd/contacts"
        },
        "created_at": "2023-05-31T14:37:56.000000Z",
        "updated_at": "2023-05-31T14:37:56.000000Z"
    },
    {
        "id": "4f0c3c56-7317-49c7-b376-afe1860fe07a",
        "name": "NawiAgodjie",
        "description": "a",
        "contacts": {
            "totalCount": 0,
            "href": "http://api.getourvoice.com/v1/groups/4f0c3c56-7317-49c7-b376-afe1860fe07a/contacts"
        },
        "created_at": "2023-05-31T14:37:56.000000Z",
        "updated_at": "2023-05-31T14:37:56.000000Z"
    }
]
}
POST/v1/groups

Create a group

This endpoint allows you to create a new group of your Ourvoice contacts.

Required attributes

  • Name
    name
    Type
    string
    Description

    The name for the group.

Optional attributes

  • Name
    description
    Type
    string
    Description

    The description for the group.

Request

POST
/v1/groups
curl --request POST \
    "https://api.getourvoice.com/v1/groups" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
      \"name\": \"vilmah\"
    }"

Response (200)

{
  "data": {
    "id": "aa143351-379b-4a36-bedc-95ac53de3e4f",
    "name": "vilmah",
    "description": "voluptatem",
    "contacts": {
        "totalCount": 0,
        "href": "http://api.getourvoice.com/v1/groups/2b9ac653-bcb5-4bad-a8c5-4f9714bfaebe/contacts"
    },
    "created_at": "2023-05-31T14:37:56.000000Z",
    "updated_at": "2023-05-31T14:37:56.000000Z"
}
}
PUT/v1/groups/{id}

Update a group

This endpoint allows you to perform an update on a group. Examples of updates are changing the name and description. It also takes a PATCH as a method.

Required attributes

  • Name
    id
    Type
    string
    Description

    The ID (uuid) of the group.

  • Name
    name
    Type
    string
    Description

    The new name for the group.

Optional attributes

  • Name
    description
    Type
    string
    Description

    The new description for the group.

Request

PUT
/v1/groups/{id}
curl --request POST \
    "api.getourvoice.com/v1/groups/2b9ac653-bcb5-4bad-a8c5-4f9714bfaebe" \
    --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
      \"name\": \"culpa\",
      \"description\": \"facere\"
    }"

Response (200)

{
  "data": {
    "id": "2b9ac653-bcb5-4bad-a8c5-4f9714bfaebe",
    "name": "culpa",
    "description": "facere",
    "contacts": {
      "totalCount": 0,
      "href": "api.getourvoice.com/v1/groups/2b9ac653-bcb5-4bad-a8c5-4f9714bfaebe/contacts"
    },
    "created_at": "2022-12-07T08:18:02.000000Z",
    "updated_at": "2022-12-07T08:18:02.000000Z"
  }
}
DELETE/v1/groups/{id}

Delete a group

This endpoint allows you to delete groups.

Required attributes

  • Name
    id
    Type
    string
    Description

    The ID (uuid) of the group.

Request

DELETE
/v1/groups/{id}
curl --request DELETE \
  "api.getourvoice.com/v1/groups/2b9ac653-bcb5-4bad-a8c5-4f9714bfaebe" \
  --header "Authorization: Bearer {YOUR_AUTH_KEY}" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json"