# Read data from an integration's provider

```http
PUT https://secure.yoprint.com/v1/api/store/{team_slug}/setting/external_integration/{id}/data
```

- API version: v1
- Operation ID: `v1_public_external_integration_data`
- Section: Team settings › [Integrations](https://developer.yoprint.com/reference/integrations.md)
- Web page: https://developer.yoprint.com/reference/integrations/v1-external-integration-data/
- Authentication: `Authorization: Bearer YOUR_API_KEY`

Reads live data from the provider through the integration. Send `type`.

**Check `success`, not only the HTTP status:** when Square doesn't create a pairing code (`create_device_code`), this call answers **HTTP 200** with `{"status": 500, "success": false, "error": {"code": 422, "message": null}}`. Here `error.code` is the number 422, not a string.

- **Twilio**: `balance`, or `phone_numbers` (200 a page; `page_number` and `page_token` page through). Twilio's records keep Twilio's own field names: use a record's `phoneNumber` as `selected_phone_number`.
- **Square**: `location` (a list) and `merchant` (one record), as Square returns them; `device`, which refreshes the devices saved in YoPrint from Square and returns them all as connected devices; or `create_device_code` with `device_name`, `device_location_id` and `idempotency_key` to start pairing a terminal. It returns the new connected device, whose `device_config.code` is the pairing code to enter on the terminal.
- **QuickBooks Online**: it runs the action of the same `type`, so it takes the same values, such as `account`, `tax` and `customer_payment_sync`.

Apart from the connected devices, the answer is the provider's data, shaped by the provider, so it has no fixed fields. Suppliers, GoShippo and Shopify have no data here. It is a PUT, so it needs Manage Settings. The `{id}` is the integration's id from the list.

## Permission

Needs the Manage Settings permission. The team owner always has it.

## Side effects

- Calls the provider.
- Square `create_device_code` creates a pairing code at Square and a connected device in YoPrint; `device` updates the saved devices from Square.
- QuickBooks Online `upsert_yoprint_item` writes to QuickBooks, as the action does.

## Path parameters

- `team_slug` (string, required): Your team slug, shown as Team ID next to your API key in Profile. Example `your-team`.
- `id` (string, required): The integration, from the integration list. Its hash id from an earlier answer; there is no unique key for it. Example `d9ZxWgBz09mDFq`.

## Request body

Content type `application/json`, required.

Which integration? Send one of these 3 bodies: **Twilio**, **Square**, **QuickBooks Online**.

### Twilio

Variant 1 of 3. On the web page: https://developer.yoprint.com/reference/integrations/v1-external-integration-data/#variant-twilio

Your Twilio balance, or the phone numbers on your Twilio account (200 a page).

Fields:

- `type` (string, required): One of: `"balance"`, `"phone_numbers"`.
- `page_number` (integer, optional): For `phone_numbers`: the page to read.
- `page_token` (string, optional): For `phone_numbers`: Twilio's page token, from a previous page.

Example request (Twilio):

```bash
curl -X PUT 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/d9ZxWgBz09mDFq/data' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "phone_numbers"
  }'
```

### Square

Variant 2 of 3. On the web page: https://developer.yoprint.com/reference/integrations/v1-external-integration-data/#variant-square

Your Square locations, merchant details or devices, or a code to pair a new terminal.

Fields:

- `type` (string, required): One of: `"location"`, `"merchant"`, `"device"`, `"create_device_code"`.
- `device_location_id` (string, optional): For `create_device_code`: a Square location id, from `type: location`.
- `device_name` (string, optional): For `create_device_code`: the terminal's name in YoPrint and Square.
- `idempotency_key` (string, optional): For `create_device_code`: a unique string per request, which Square requires. Reuse it only to retry the same request.

Example request (Square):

```bash
curl -X PUT 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/d9ZxWgBz09mDFq/data' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "device_location_id": "YOUR_SQUARE_LOCATION_ID",
    "device_name": "Front counter",
    "idempotency_key": "pair-front-counter-0001",
    "type": "create_device_code"
  }'
```

### QuickBooks Online

Variant 3 of 3. On the web page: https://developer.yoprint.com/reference/integrations/v1-external-integration-data/#variant-quickbooks-online

Your QuickBooks accounts (`account`) or tax data (`tax`), a setup check, or the customer portal payment list (`customer_payment_sync`). It runs the action of the same `type`, so it takes the same values, including `upsert_yoprint_item`, which writes to QuickBooks.

Fields:

- `type` (string, required): One of: `"account"`, `"tax"`, `"check"`, `"refresh_account"`, `"refresh_qbo_accounts"`, `"refresh_qbo_tax"`, `"upsert_yoprint_item"`, `"reauth"`, `"customer_payment_sync"`.
- `order_id` (string, optional): For `customer_payment_sync`: only the payments on this sales order or quote (its id).
- `page` (integer, optional): For `customer_payment_sync`: the page, from 1. Minimum 1.
- `per_page` (integer, optional): For `customer_payment_sync`: rows per page, 20 when left out. Minimum 1. Maximum 100.

Example request (QuickBooks Online):

```bash
curl -X PUT 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/d9ZxWgBz09mDFq/data' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "account"
  }'
```

## Response

`200` The provider's data, or (Square `create_device_code` only) a refusal sent with HTTP 200: check `success`.

> **Warning: a 200 answer can still be a refusal.** Check `success` (and the fields named below) as well as the HTTP status.
> - Square did not create the pairing code. The HTTP status is 200, but the body is `{"status": 500, "success": false, "error": {"code": 422, "message": null}}` (`code` is the number 422). This always happens outside Square's production environment. Check `success`. Fix: Check `device_location_id` and send a new `idempotency_key`. Nothing was saved.
> - QuickBooks Online with a `type` it doesn't know: HTTP 200 with an empty body (not JSON). Fix: Use a `type` from the list.

Refusal example (Refused with HTTP 200: `success` is false and `error.code` is the number 422):

```json
{
  "error": {
    "code": 422,
    "message": null
  },
  "status": 500,
  "success": false
}
```

Example response:

```json
{
  "data": {
    "device_config": {
      "code": "ABCDEF",
      "created_at": "2026-11-03T09:00:00.000Z",
      "id": "device_code_example_1",
      "location_id": "YOUR_SQUARE_LOCATION_ID",
      "name": "Front counter",
      "pair_by": "2026-11-03T09:05:00.000Z",
      "product_type": "TERMINAL_API",
      "status": "UNPAIRED",
      "version": "1"
    },
    "device_id": "device_code_example_1",
    "device_name": "Front counter",
    "device_status": "unpaired",
    "device_type": "square_terminal",
    "id": "fPbIOxwKlAzDsA",
    "is_enabled": true
  },
  "status": 200,
  "success": true
}
```

## Errors

- `401` The API key is missing or wrong (`unauthenticated`).
- `403` You are not allowed to do this. `api_access_not_in_plan`: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only `{"message": "Insufficient Permission"}`. Other refusals use the error envelope, with `unauthorized` or `user_is_not_authorized`.
  - When: Your role lacks Manage Settings. The body is `{"message": "Insufficient Permission"}`, without the error envelope. Fix: Use the key of a member whose role has Manage Settings, or the owner's.
- `404` Not found. `page_not_found`: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. `code: null`, with a message that starts "No query results for": there is no record with that id.
  - When: No integration of your team has this id. `error.code` is null; `error.message` names the record type. Fix: Use an id from the list.
- `422` The request was refused and changed nothing. `validation_failed` lists what to fix in `error.fields`; other codes name a business rule, explained in `error.message`. A few checks answer with only `{"message": "..."}`. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer `connect_timeout` ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.
  - When: `type` is missing or not allowed (`validation_failed`), or the provider read failed (`failed_to_retrieve_data` for Twilio and for Square `location` and `merchant`). Fix: Check the integration's status and the `type`.
  - When: Square: this Square account is connected to another YoPrint team (`integration_transfer_pending`). Fix: Confirm the move with the `transfer_confirm` action first.
  - When: The integration is not in your plan (`plan_limitation`). Fix: Upgrade the plan, or use another integration.
  - When: The integration is retired (`integration_deprecated`). Fix: Delete it and connect an alternative.
- `500` A business rule refused the request (see the operation's errors), or something failed inside YoPrint. Refusals use the error envelope with a code such as `action_not_allowed`; an unexpected failure answers `{"message": "Server Error"}`. Repeating a refusal gets the same answer; after an unexpected failure, read the record back before you retry a change.
  - When: The integration has no data: `error.code` `data_type_empty`, for example a supplier. Fix: Use Twilio, Square or QuickBooks Online.

## Related

- [Update an integration (same as PUT)](https://developer.yoprint.com/reference/integrations/v1-external-integration-update-patch.md): `PATCH /v1/api/store/{team_slug}/setting/external_integration/{external_integration_reference}`
- [Run an integration action](https://developer.yoprint.com/reference/integrations/v1-external-integration-action.md): `PUT /v1/api/store/{team_slug}/setting/external_integration/{id}/action`
- [List connected devices](https://developer.yoprint.com/reference/connected-devices/v1-connected-device-index.md): `GET /v1/api/store/{team_slug}/setting/connected_device`