List Benefit Grants

Intent

Reads the available benefit grants as a pageable collection without changing them.

When to call it

Call this when an interface, sync, or support workflow needs to inspect benefit grants. Use the filters and paging controls shown below to limit the result.

Access boundary

Authorize the request with a token that carries benefits:read or benefits:write.

Successful result

A successful request returns 200. The response schema below defines the body your integration receives.

Operational notes

List benefit grants across all benefits accessible to the authenticated subject.

Scopes: benefits:read benefits:write

GET

benefit-grants

List Benefit Grants

curl --request GET \
  --url https://api.getruba.com/v1/benefit-grants/ \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.getruba.com/v1/benefit-grants/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.getruba.com/v1/benefit-grants/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.getruba.com/v1/benefit-grants/"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.getruba.com/v1/benefit-grants/")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "items": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "is_granted": true,
      "is_revoked": true,
      "subscription_id": "<string>",
      "order_id": "<string>",
      "customer_id": "<string>",
      "benefit_id": "<string>",
      "customer": {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "metadata": {},
        "email": "<string>",
        "email_verified": true,
        "type": "<string>",
        "name": "John Doe",
        "billing_name": "John Doe",
        "billing_address": {
          "line1": "<string>",
          "line2": "<string>",
          "postal_code": "<string>",
          "city": "<string>",
          "state": "<string>"
        },
        "tax_id": {
          "[0]": "<string>"
        },
        "organization_id": "<string>",
        "deleted_at": "2023-11-07T05:31:56Z",
        "avatar_url": "https://www.gravatar.com/avatar/xxx?d=404",
        "external_id": "usr_1337",
        "locale": "<string>",
        "default_payment_method_id": "<string>"
      },
      "benefit": {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "type": "<string>",
        "description": "<string>",
        "selectable": true,
        "deletable": true,
        "is_deleted": true,
        "organization_id": "<string>",
        "metadata": {},
        "properties": {
          "note": "<string>"
        },
        "visibility_configurable": true
      },
      "properties": {
        "account_id": "<string>",
        "guild_id": "<string>",
        "role_id": "<string>",
        "granted_account_id": "<string>"
      },
      "granted_at": "2023-11-07T05:31:56Z",
      "revoked_at": "2023-11-07T05:31:56Z",
      "member_id": "<string>",
      "error": {
        "message": "<string>",
        "type": "<string>",
        "timestamp": "<string>"
      },
      "member": {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "customer_id": "<string>",
        "email": "<string>",
        "name": "Jane Doe",
        "external_id": "usr_1337"
      }
    }
  ],
  "pagination": {
    "total_count": 123,
    "max_page": 123
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

Authorization

string

header

required

You can generate a Personal Access Token from your settings.

Query Parameters

organization_id

Filter by organization ID. The organization ID.

Example:

"1dbfc517-0bbf-4301-9ba8-555ca42b9737"

customer_id

Filter by customer ID. The customer ID.

external_customer_id

Filter by customer external ID. The customer external ID.

is_granted

boolean | null

Filter by granted status. If true, only granted benefits will be returned. If false, only revoked benefits will be returned.

page

integer

default:1

Page number, defaults to 1.

limit

integer

default:10

Size of a page, defaults to 10. Maximum is 100.

sorting

enum<string>[] | null

Sorting criterion. Several criteria can be used simultaneously and will be applied in order. Add a minus sign - before the criteria name to sort by descending order.

Available options:

created_at,

-created_at,

granted_at,

-granted_at,

revoked_at,

-revoked_at

Response

Successful Response

items

BenefitGrant · object[]

required

Show child attributes

pagination

Pagination · object

required

Show child attributes

Create Benefit### Intent Creates a benefit from the values supplied in the request. ### When to call it Call this when your application has collected the required values and is ready to create a benefit. ### Access boundary Authorize the request with a token that carries `benefits:write`. ### Successful result A successful request returns `201`. The response schema below defines the body your integration receives. ### Operational notes Create a benefit. **Scopes**: `benefits:write`

List Benefit Grants

curl --request GET \
  --url https://api.getruba.com/v1/benefit-grants/ \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.getruba.com/v1/benefit-grants/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.getruba.com/v1/benefit-grants/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.getruba.com/v1/benefit-grants/"

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

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.getruba.com/v1/benefit-grants/")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "items": [
    {
      "created_at": "2023-11-07T05:31:56Z",
      "modified_at": "2023-11-07T05:31:56Z",
      "id": "<string>",
      "is_granted": true,
      "is_revoked": true,
      "subscription_id": "<string>",
      "order_id": "<string>",
      "customer_id": "<string>",
      "benefit_id": "<string>",
      "customer": {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "metadata": {},
        "email": "<string>",
        "email_verified": true,
        "type": "<string>",
        "name": "John Doe",
        "billing_name": "John Doe",
        "billing_address": {
          "line1": "<string>",
          "line2": "<string>",
          "postal_code": "<string>",
          "city": "<string>",
          "state": "<string>"
        },
        "tax_id": {
          "[0]": "<string>"
        },
        "organization_id": "<string>",
        "deleted_at": "2023-11-07T05:31:56Z",
        "avatar_url": "https://www.gravatar.com/avatar/xxx?d=404",
        "external_id": "usr_1337",
        "locale": "<string>",
        "default_payment_method_id": "<string>"
      },
      "benefit": {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "type": "<string>",
        "description": "<string>",
        "selectable": true,
        "deletable": true,
        "is_deleted": true,
        "organization_id": "<string>",
        "metadata": {},
        "properties": {
          "note": "<string>"
        },
        "visibility_configurable": true
      },
      "properties": {
        "account_id": "<string>",
        "guild_id": "<string>",
        "role_id": "<string>",
        "granted_account_id": "<string>"
      },
      "granted_at": "2023-11-07T05:31:56Z",
      "revoked_at": "2023-11-07T05:31:56Z",
      "member_id": "<string>",
      "error": {
        "message": "<string>",
        "type": "<string>",
        "timestamp": "<string>"
      },
      "member": {
        "id": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "modified_at": "2023-11-07T05:31:56Z",
        "customer_id": "<string>",
        "email": "<string>",
        "name": "Jane Doe",
        "external_id": "usr_1337"
      }
    }
  ],
  "pagination": {
    "total_count": 123,
    "max_page": 123
  }
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Read This First

Create a Sale

Collect and Reconcile

Manage Recurring Revenue

Model Customer Access

Power the Customer Portal

Configure the Platform

React to State Changes

List Benefit Grants

Intent

When to call it

Access boundary

Successful result

Operational notes

Authorizations

Query Parameters

Response