# Using the API

Bunny's GraphQL API lets you create trial subscriptions, track feature usage, update accounts, contacts, quotes and almost all other objects that you can see in the web user interface.

To interact with with Bunny API you will need to follow these steps:

1. [Get an access token](#get-an-access-token)
2. [Send a GraphQL request to query or modify data](#making-a-graphql-request)

### Get an access token

All requests to Bunny require an Access Token to be sent in an Authorization header. To get started quickly you can generate an access token directly in the Bunny admin portal or alternatively you can obtain the client credentials for an API client and generate an access token using an SDK.

* In Bunny, go to **Settings > API Clients**
* Select the Default API client
* Click the Generate Access Token button and copy the token

### Send a GraphQL request

The Bunny SDKs offers convenience methods for some of the common GraphQL requests as well as a raw query method so that you can build your own queries. [Learn how to use the Bunny API reference to build your own custom queries](https://docs.bunny.com/developer/using-the-graphql-api/sending-a-graphql-request).

*For example,* if a new trial has signed up in your SaaS application then you will track this in Bunny using the convenient subscription creation methods.

{% tabs %}
{% tab title="Javascript" %}

```javascript
const res = bunny.createSubscription('Acme Yachts', 'Jill', 'McGill', 'jill@example.com', 'free', {
  trial: true,
  tenantCode: '123456'
})
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
response = BunnyApp::Subscription.create(
  product_plan_code: 'starter',
  options: {
    account_name: "Superdesk",
    first_name: "Meg",
    last_name: "La Don",
    email: "meg@example.com",
    trial: true,
    tenant_code: "123456",
    tenant_name: "Superdesk"
  }
)
```

{% endtab %}

{% tab title="Curl" %}
{% code overflow="wrap" %}

```sh
curl --location 'https://SUBDOMAIN.bunny.com/graphql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--data-raw '{"query":"mutation subscriptionCreate ($attributes: SubscriptionAttributes!) { subscriptionCreate (attributes: $attributes) { subscription { id  account {  id  name  contacts { id firstName lastName }  }  trialStartDate  trialEndDate  startDate endDate  state plan { code name } priceList {  code name } tenant { id code name } } errors }}","variables":{"attributes":{"account":{"billingContact":{"firstName":"Bruce","lastName":"Wayne","email":"bruce@example.com"},"name":"Superdesk"},"trial":true,"priceListCode":"free","tenant":{"code":"tenant-123"}}}}'
```

{% endcode %}
{% endtab %}
{% endtabs %}

Alternately you may want to get back a list of [Accounts](https://docs.bunny.com/developer/api-reference/types/account) including Contacts. In this case you can build and send your own query using the `query` method.

{% tabs %}
{% tab title="Javascript" %}

```javascript
const query = `query accounts ($filter: String, $limit: Int) {
  accounts (filter: $filter, limit: $limit) {
      id 
      name
      contacts {
          firstName
          lastName
          email
      }
      customMyField
  }
}`;

const variables = {
  filter: "",
  limit: 10,
};

const response = await bunny.query(query, variables);
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
query = <<~'GRAPHQL'
  query accounts ($filter: String, $limit: Int) {
    accounts (filter: $filter, limit: $limit) {
        id 
        name
        contacts {
            firstName
            lastName
            email
        }
    }
  }
GRAPHQL

variables = {
  filter: '',
  limit: 10
}

response = BunnyApp.query(query, variables)
```

{% endtab %}

{% tab title="Curl" %}
{% code overflow="wrap" %}

```sh
curl --location 'https://SUBDOMAIN.bunny.com/graphql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN
--data '{"query":"query accounts ($filter: String, $first: Int) { accounts (filter: $filter, first: $first) { totalCount pageInfo { startCursor endCursor hasNextPage hasPreviousPage } nodes { id  code name } }}","variables":{"filter":"","first":10}}'
```

{% endcode %}
{% endtab %}
{% endtabs %}

GraphQL is pretty simple in the sense that you're always just sending a HTTP POST request with a specially formatted body. Within that request body you will be asking graphal to perform either a query or a mutation.

* [**query**](#performing-a-query) - Use this to retrieve data.
* [**mutation**](https://docs.bunny.com/developer/api-reference/mutations) - Use this to create or modify data.

### Custom fields

Any custom fields you have created will be prefixed with `custom`, for example `customProcurementPortal`.&#x20;