# Integrations · REST API

> Integrations are pre-configured sources for third-party services — currently Shopify and QuickBooks.

HTML version: https://developers.sheetgo.com/api/integrations/

[Developers](/index.md) › [REST API](/api.md) › [Forms & Integrations](/api.md#api-endpoints)

REST API · 2 endpoints

## Integrations

**Complete for this group.** Each operation below lists its parameters, request body, responses and errors. Every model they use is documented under [Models used on this page](#models), so you do not need another page to build a request. Base URL `https://api.sheetgo.com`; paths are complete, version included (`/rest/beta/…`): append them to the base URL exactly as shown; send `Authorization: Bearer sg_…`. Also in the API's own docs: <https://api.sheetgo.com/rest/reference/integrations> ([Markdown](https://api.sheetgo.com/rest/reference/integrations.md)).

**Conventions for every endpoint.** Lists take `page` (from 1) and `per_page` (1-100, default 50), and `total` counts **pages**, not items. Collection URLs end with `/`. `POST …/run` returns `200` when the run is *queued*; poll `GET …/run`. Google Sheets use `provider: "drive"`; column fields take letters (`"E"`). Error bodies and status codes: [REST API › Errors](/api.md#api-errors).

**Python recipes.** [API client helper](/examples.md#recipe-sheetgo-api).

**Integrations** are pre-configured sources for third-party services — currently Shopify and QuickBooks. Instead of describing an HTTP request yourself, you pick a *data source* from a menu and Sheetgo supplies the URL, credentials, pagination and response parsing for the account you authorized.

Use `GET /rest/beta/integrations` to see which providers you have connected and under which accounts, and `GET /rest/beta/integrations/{provider}/options` to list the data sources you can pull and the parameters each accepts. Then create an automation with an `integration` source.

Authorizing a provider is a browser sign-in in the Sheetgo web app and cannot be done through the API — these endpoints report the result.

## Operations

#### GET `/rest/beta/integrations` — List integrations and connected accounts

Every integration, whether or not you have authorized it.

`accounts[].account` is what an automation's `sources[].account` expects.
With exactly one account for a provider you can omit that field and Sheetgo
resolves it; with several, naming one is required.

Authorization itself happens in the Sheetgo web app — it is a browser OAuth
flow and cannot be driven from an API key.

##### Responses

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | Providers and your authorized accounts | [`IntegrationListResponse`](#model-IntegrationListResponse) |
| 401 | Authentication failed or token is invalid | — |

##### Example request

```
curl -s -X GET "https://api.sheetgo.com/rest/beta/integrations" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"
```

In the API's own docs: <https://api.sheetgo.com/rest/reference/integrations#get-rest-beta-integrations>

#### GET `/rest/beta/integrations/{provider}/options` — List a provider's data sources

What you can ask this provider for.

Static per provider and identical for every account, so this answers even
before you have authorized one — useful for exploring first. `id` is what
`sources[].data_source` expects; `parameters` is what `sources[].parameters`
accepts, and only QuickBooks reports declare any.

Retired data sources are omitted: they would raise mid-run rather than
return data.

##### Parameters

| Name | In | Type |  | Description |
| --- | --- | --- | --- | --- |
| `provider` | path | [`IntegrationProvider`](#model-IntegrationProvider) | required | Integration provider: shopify or quickbooks |

##### Responses

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | Selectable data sources | [`IntegrationOptionsResponse`](#model-IntegrationOptionsResponse) |
| 401 | Authentication failed or token is invalid | — |
| 422 | Validation Error | [`HTTPValidationError`](#model-HTTPValidationError) |

##### Example request

```
curl -s -X GET "https://api.sheetgo.com/rest/beta/integrations/PROVIDER/options" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"
```

In the API's own docs: <https://api.sheetgo.com/rest/reference/integrations#get-rest-beta-integrations-provider-options>

## Models used on this page

Every request and response model referenced above, including nested ones (9). The full catalogue is on the [Models](/api/models.md) page.

#### `DataSourceOut`

One thing you can ask a provider for.

| Field | Type |  | Description |
| --- | --- | --- | --- |
| `description` | string | optional | What it returns Default: `""` |
| `id` | string | required | Pass this back as `sources[].data_source` |
| `kind` | string | required | `query` for records, `report` for a report |
| `name` | string | required | Display name |
| `parameters` | object (map of string → [`DataSourceParameter`](#model-DataSourceParameter)) | optional | Parameters this data source accepts, keyed by name. Empty for everything except QuickBooks reports. |

#### `DataSourceParameter`

One parameter a data source accepts.

When `options` is present it is the authority: `date_macro` declares
`type: date` but its options are macro strings like "Last Month", so a
value is checked against `options` first and against `type` only when no
options are declared.

| Field | Type |  | Description |
| --- | --- | --- | --- |
| `description` | string | nullable | What it controls |
| `format` | string | nullable | Expected format when the type is `date` |
| `name` | string | nullable | Display name |
| `optional_for` | array of string | nullable | Advisory: supplying this parameter makes those alternatives unnecessary. Nothing is enforced as required. |
| `options` | array of string | nullable | Accepted values. When present, the only accepted values. |
| `type` | string | nullable | `date` or `string` |

#### `HTTPValidationError`

| Field | Type |  | Description |
| --- | --- | --- | --- |
| `detail` | array of [`ValidationError`](#model-ValidationError) | optional |  |

Used by: [GET /rest/beta/workflows/](/api/workflows.md#get-rest-beta-workflows), [POST /rest/beta/workflows/](/api/workflows.md#post-rest-beta-workflows), [POST /rest/beta/workflows/run/{id}](/api/workflows.md#post-rest-beta-workflows-run-id), [GET /rest/beta/workflows/{id}](/api/workflows.md#get-rest-beta-workflows-id), [PATCH /rest/beta/workflows/{id}](/api/workflows.md#patch-rest-beta-workflows-id), [DELETE /rest/beta/workflows/{id}](/api/workflows.md#delete-rest-beta-workflows-id), [GET /rest/beta/workflows/{id}/collaborators](/api/workflows.md#get-rest-beta-workflows-id-collaborators), [POST /rest/beta/workflows/{id}/collaborators](/api/workflows.md#post-rest-beta-workflows-id-collaborators), [DELETE /rest/beta/workflows/{id}/collaborators](/api/workflows.md#delete-rest-beta-workflows-id-collaborators), [PATCH /rest/beta/workflows/{id}/collaborators/{email}](/api/workflows.md#patch-rest-beta-workflows-id-collaborators-email), [DELETE /rest/beta/workflows/{id}/collaborators/{email}](/api/workflows.md#delete-rest-beta-workflows-id-collaborators-email), [GET /rest/beta/workflows/{id}/destinations](/api/workflows.md#get-rest-beta-workflows-id-destinations), [GET /rest/beta/workflows/{id}/files](/api/workflows.md#get-rest-beta-workflows-id-files), [GET /rest/beta/workflows/{id}/general-access](/api/workflows.md#get-rest-beta-workflows-id-general-access), [PUT /rest/beta/workflows/{id}/general-access](/api/workflows.md#put-rest-beta-workflows-id-general-access), [DELETE /rest/beta/workflows/{id}/general-access](/api/workflows.md#delete-rest-beta-workflows-id-general-access), [POST /rest/beta/workflows/{id}/leave](/api/workflows.md#post-rest-beta-workflows-id-leave), [POST /rest/beta/workflows/{id}/request-access](/api/workflows.md#post-rest-beta-workflows-id-request-access), [GET /rest/beta/workflows/{id}/run](/api/workflows.md#get-rest-beta-workflows-id-run), [POST /rest/beta/workflows/{id}/run](/api/workflows.md#post-rest-beta-workflows-id-run), [GET /rest/beta/workflows/{id}/sources](/api/workflows.md#get-rest-beta-workflows-id-sources), [GET /rest/beta/automations/](/api/automations.md#get-rest-beta-automations), [POST /rest/beta/automations/run/{id}](/api/automations.md#post-rest-beta-automations-run-id), [GET /rest/beta/automations/{id}](/api/automations.md#get-rest-beta-automations-id), [DELETE /rest/beta/automations/{id}](/api/automations.md#delete-rest-beta-automations-id), [GET /rest/beta/automations/{id}/destinations](/api/automations.md#get-rest-beta-automations-id-destinations), [GET /rest/beta/automations/{id}/files](/api/automations.md#get-rest-beta-automations-id-files), [GET /rest/beta/automations/{id}/run](/api/automations.md#get-rest-beta-automations-id-run), [POST /rest/beta/automations/{id}/run](/api/automations.md#post-rest-beta-automations-id-run), [GET /rest/beta/automations/{id}/sources](/api/automations.md#get-rest-beta-automations-id-sources), [GET /rest/beta/workflows/{id}/trigger](/api/triggers.md#get-rest-beta-workflows-id-trigger), [DELETE /rest/beta/workflows/{id}/trigger](/api/triggers.md#delete-rest-beta-workflows-id-trigger), [GET /rest/beta/workflows/{id}/dashboard](/api/dashboards.md#get-rest-beta-workflows-id-dashboard), [DELETE /rest/beta/workflows/{id}/dashboard/elements/{element\_id}](/api/dashboards.md#delete-rest-beta-workflows-id-dashboard-elements-element-id), [GET /rest/beta/workflows/{id}/dashboard/elements/{element\_id}/data](/api/dashboards.md#get-rest-beta-workflows-id-dashboard-elements-element-id-data), [PUT /rest/beta/workflows/{id}/dashboard/publish](/api/dashboards.md#put-rest-beta-workflows-id-dashboard-publish), [GET /rest/beta/workflows/{workflow\_id}/forms/](/api/forms.md#get-rest-beta-workflows-workflow-id-forms), [POST /rest/beta/workflows/{workflow\_id}/forms/](/api/forms.md#post-rest-beta-workflows-workflow-id-forms), [GET /rest/beta/workflows/{workflow\_id}/forms/{form\_id}](/api/forms.md#get-rest-beta-workflows-workflow-id-forms-form-id), [PATCH /rest/beta/workflows/{workflow\_id}/forms/{form\_id}](/api/forms.md#patch-rest-beta-workflows-workflow-id-forms-form-id), [DELETE /rest/beta/workflows/{workflow\_id}/forms/{form\_id}](/api/forms.md#delete-rest-beta-workflows-workflow-id-forms-form-id), [GET /rest/beta/workflows/{workflow\_id}/forms/{form\_id}/responses](/api/forms.md#get-rest-beta-workflows-workflow-id-forms-form-id-responses), [HEAD /rest/beta/workflows/{workflow\_id}/forms/{form\_id}/responses](/api/forms.md#head-rest-beta-workflows-workflow-id-forms-form-id-responses), [GET /rest/beta/automations/{automation\_id}/webhook](/api/webhook.md#get-rest-beta-automations-automation-id-webhook), [GET /rest/beta/workflows/{workflow\_id}/webhooks](/api/webhook.md#get-rest-beta-workflows-workflow-id-webhooks), [GET /rest/beta/api-destination/{public\_id}](/api/api-destination.md#get-rest-beta-api-destination-public-id), [HEAD /rest/beta/api-destination/{public\_id}](/api/api-destination.md#head-rest-beta-api-destination-public-id), [GET /rest/beta/integrations/{provider}/options](/api/integrations.md#get-rest-beta-integrations-provider-options), [GET /rest/beta/outlook/messages](/api/outlook.md#get-rest-beta-outlook-messages), [POST /rest/beta/outlook/messages/batch](/api/outlook.md#post-rest-beta-outlook-messages-batch), [GET /rest/beta/outlook/messages/{message\_id}](/api/outlook.md#get-rest-beta-outlook-messages-message-id), [GET /rest/beta/outlook/messages/{message\_id}/attachments/{attachment\_id}](/api/outlook.md#get-rest-beta-outlook-messages-message-id-attachments-attachment-id), [POST /rest/beta/outlook/send](/api/outlook.md#post-rest-beta-outlook-send), [GET /rest/beta/gmail/messages](/api/gmail.md#get-rest-beta-gmail-messages), [POST /rest/beta/gmail/messages/batch](/api/gmail.md#post-rest-beta-gmail-messages-batch), [GET /rest/beta/gmail/messages/{message\_id}](/api/gmail.md#get-rest-beta-gmail-messages-message-id), [GET /rest/beta/gmail/messages/{message\_id}/attachments/{attachment\_id}](/api/gmail.md#get-rest-beta-gmail-messages-message-id-attachments-attachment-id), [POST /rest/beta/gmail/send](/api/gmail.md#post-rest-beta-gmail-send), [GET /rest/beta/files/{provider}](/api/files.md#get-rest-beta-files-provider), [GET /rest/beta/files/{provider}/roots](/api/files.md#get-rest-beta-files-provider-roots), [GET /rest/beta/files/{provider}/search](/api/files.md#get-rest-beta-files-provider-search), [GET /rest/beta/files/{provider}/{file\_id}](/api/files.md#get-rest-beta-files-provider-file-id), [GET /rest/beta/bigquery/projects](/api/bigquery.md#get-rest-beta-bigquery-projects), [GET /rest/beta/bigquery/projects/{project}/datasets](/api/bigquery.md#get-rest-beta-bigquery-projects-project-datasets), [GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables](/api/bigquery.md#get-rest-beta-bigquery-projects-project-datasets-dataset-tables), [GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables/{table}](/api/bigquery.md#get-rest-beta-bigquery-projects-project-datasets-dataset-tables-table), [POST /rest/beta/bigquery/projects/{project}/validate-query](/api/bigquery.md#post-rest-beta-bigquery-projects-project-validate-query), [POST /rest/auth/refresh](/api/auth.md#post-rest-auth-refresh), [POST /rest/auth/token](/api/auth.md#post-rest-auth-token)

#### `IntegrationAccount`

One authorized account for a provider.

| Field | Type |  | Description |
| --- | --- | --- | --- |
| `account` | string | required | Pass this back as `sources[].account`. The shop domain for Shopify, the realm (company) id for QuickBooks. |
| `connected_at` | string (date-time) | nullable | When the account was authorized |
| `may_be_revoked` | boolean | optional | True when the stored credentials are gone — the account must be re-authorized in the web app before it will run. Default: `false` |

#### `IntegrationListResponse`

Standard envelope. The provider list is fixed and short, so there are no
paging query params -- same as `GET /rest/beta/files/{provider}/roots`.

| Field | Type |  | Description |
| --- | --- | --- | --- |
| `page` | integer | nullable | Page number Default: `1` |
| `per_page` | integer | nullable | Number of items per page Default: `50` |
| `results` | array of [`IntegrationOut`](#model-IntegrationOut) | optional | List of results |
| `total` | integer | nullable | Total number of pages Default: `0` |

Used by: [GET /rest/beta/integrations](/api/integrations.md#get-rest-beta-integrations)

#### `IntegrationOptionsResponse`

Everything selectable for one provider.

| Field | Type |  | Description |
| --- | --- | --- | --- |
| `data_sources` | array of [`DataSourceOut`](#model-DataSourceOut) | optional | Every data source this provider exposes. Use a `key` from here as an integration source's `data_source`. |
| `provider` | string | required | The provider these options belong to, e.g. `shopify` or `quickbooks`. |

Used by: [GET /rest/beta/integrations/{provider}/options](/api/integrations.md#get-rest-beta-integrations-provider-options)

#### `IntegrationOut`

One provider, with whatever the caller has authorized for it.

| Field | Type |  | Description |
| --- | --- | --- | --- |
| `accounts` | array of [`IntegrationAccount`](#model-IntegrationAccount) | optional | Authorized accounts. Empty when not connected — authorization happens in the Sheetgo web app, not here. |
| `connected` | boolean | required | True when at least one account is authorized |
| `name` | string | required | Display name |
| `provider` | string | required | Pass this back as `sources[].provider` |

#### `IntegrationProvider`

Third-party services with a pre-configured, server-managed API source.

Distinct from `Provider`, which lists storage backends. The value is also
the prefix of the compound `service_origin` a compiled source carries
(`shopify:<shop>`), which is what makes core-lib's load\_provider\_manager
pick the provider-specific request manager.

**Type:** one of `"shopify"`, `"quickbooks"`

Used by: [GET /rest/beta/integrations/{provider}/options](/api/integrations.md#get-rest-beta-integrations-provider-options)

#### `ValidationError`

| Field | Type |  | Description |
| --- | --- | --- | --- |
| `loc` | array of string or integer | required |  |
| `msg` | string | required |  |
| `type` | string | required |  |