# Connect an integration

```http
POST https://secure.yoprint.com/v1/api/store/{team_slug}/setting/external_integration/{external_integration_reference}
```

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

Connects an integration. The last path segment is the integration's subtype, for example `POST /v1/api/store/{team_slug}/setting/external_integration/sanmar_v1`.

**Suppliers and Twilio take credentials.** YoPrint checks them with the provider before saving, so the call waits for the provider's answer. If the provider rejects them you get 422 `invalid_key` and nothing is saved. The answer never contains them: supplier passwords, AS Colour's API key and Twilio's Account SID and auth token are not returned.

| Subtype | Integration | Body |
| --- | --- | --- |
| `sanmar_v1` | SanMar | `account_number`, `user`, `pass` |
| `sanmar_ca_v1` | SanMar Canada | `user`, `pass` |
| `ssa_v1`, `ssa_ca_v1` | S&S Activewear, S&S Activewear Canada | `user`, `pass` |
| `momentec_v2`, `momentec_ca_v2` | Momentec (Augusta Sportswear), Momentec Canada | `user`, `pass` |
| `ascolour_v1` | AS Colour | `email`, `password` |
| `twillio_v1` | Twilio | `account_sid`, `auth_token` |

**GoShippo (`goshippo_v1`), QuickBooks Online (`quickbook_v1`) and Square (`square_v2`) connect through the provider's sign-in, in YoPrint's web app.** The call returns `{"type": "oauth", "url": "..."}`, but the `url` is a YoPrint connect link that only the web app can use: opened in a browser tab or from a script it shows a refusal page and connects nothing. To connect one of these, a person who can manage settings clicks Connect in Settings > Apps.

**Shopify** is installed from the Shopify admin, never here (422 `shopify_install_from_shopify_required`). FedEx (`fedex_v1`), UPS (`ups_v1`), AlphaBroder (`alphabroder_v1`, `alphabroder_ca_v1`) and Delta Apparel (`deltapp_v1`) are retired (422 `integration_deprecated`).

## Permission

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

## Business rules

- One integration of each subtype per team: 422 `unique_constraint` (Square: `unique_integration_error`). Change the credentials of an existing one with "Update an integration". QuickBooks Online is not checked at this step.
- The integration must be in your plan (422 `plan_limitation`).
- Suppliers and Twilio are saved only after the provider accepts the credentials.

## Side effects

- Calls the supplier or Twilio to check the credentials. No order is placed and no message is sent.
- For a provider sign-in, nothing is saved until the person finishes signing in from Settings > Apps.

## Path parameters

- `team_slug` (string, required): Your team slug, shown as Team ID next to your API key in Profile. Example `your-team`.
- `external_integration_reference` (string, required): The subtype of the integration to connect. Retired ones (`fedex_v1`, `ups_v1`, `alphabroder_v1`, `alphabroder_ca_v1`, `deltapp_v1`) answer 422, and `shopify_v1` is installed from Shopify. One of: `"sanmar_v1"`, `"sanmar_ca_v1"`, `"ssa_v1"`, `"ssa_ca_v1"`, `"momentec_v2"`, `"momentec_ca_v2"`, `"ascolour_v1"`, `"twillio_v1"`, `"goshippo_v1"`, `"quickbook_v1"`, `"square_v2"`, `"shopify_v1"`, `"fedex_v1"`, `"ups_v1"`, `"alphabroder_v1"`, `"alphabroder_ca_v1"`, `"deltapp_v1"`. Example `sanmar_v1`.

## Request body

Content type `application/json`, required.

Which integration are you connecting? Send one of these 5 bodies: **SanMar**, **S&S Activewear, SanMar Canada or Momentec**, **AS Colour**, **Twilio**, **Provider sign-in (GoShippo, QuickBooks Online, Square)**.

### SanMar

Variant 1 of 5. On the web page: https://developer.yoprint.com/reference/integrations/v1-external-integration-store/#variant-sanmar

Path `sanmar_v1`. Your SanMar web services account.

Fields:

- `account_number` (string, required): Your SanMar customer number.
- `pass` (string, required): Your password with the supplier. It is never returned.
- `user` (string, required): Your username with the supplier.

Example request (SanMar):

```bash
curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/sanmar_v1' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_number": "123456",
    "pass": "YOUR_PASSWORD",
    "user": "YOUR_SUPPLIER_USERNAME"
  }'
```

### S&S Activewear, SanMar Canada or Momentec

Variant 2 of 5. Sent with `external_integration_reference` `ssa_v1` in the path. On the web page: https://developer.yoprint.com/reference/integrations/v1-external-integration-store/#variant-s-s-activewear-sanmar-canada-or-momentec

Paths `ssa_v1`, `ssa_ca_v1`, `sanmar_ca_v1`, `momentec_v2` (Augusta Sportswear) and `momentec_ca_v2`.

Fields:

- `pass` (string, required): Your password with the supplier. It is never returned.
- `user` (string, required): Your username with the supplier.

Example request (S&S Activewear, SanMar Canada or Momentec):

```bash
curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/ssa_v1' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "pass": "YOUR_PASSWORD",
    "user": "YOUR_SUPPLIER_USERNAME"
  }'
```

### AS Colour

Variant 3 of 5. On the web page: https://developer.yoprint.com/reference/integrations/v1-external-integration-store/#variant-as-colour

Path `ascolour_v1`. Your AS Colour account sign-in.

Fields:

- `email` (string (email), required)
- `password` (string, required): Never returned.

Example request (AS Colour):

```bash
curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/sanmar_v1' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "alex@example.com",
    "password": "YOUR_PASSWORD"
  }'
```

### Twilio

Variant 4 of 5. On the web page: https://developer.yoprint.com/reference/integrations/v1-external-integration-store/#variant-twilio

Path `twillio_v1` (spelled with two l's). Your Twilio account, for text messages.

Fields:

- `account_sid` (string, required): Your Twilio Account SID.
- `auth_token` (string, required): Your Twilio auth token.

Example request (Twilio):

```bash
curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/setting/external_integration/sanmar_v1' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_sid": "YOUR_TWILIO_ACCOUNT_SID",
    "auth_token": "YOUR_TWILIO_AUTH_TOKEN"
  }'
```

### Provider sign-in (GoShippo, QuickBooks Online, Square)

Variant 5 of 5. Sent with `external_integration_reference` `goshippo_v1` in the path. On the web page: https://developer.yoprint.com/reference/integrations/v1-external-integration-store/#variant-provider-sign-in-goshippo-quickbooks-online-square

Paths `goshippo_v1`, `quickbook_v1` and `square_v2`. Send no fields; the answer is a link to sign in at the provider.

Fields:

- None: this variant sends no fields.

Example request (Provider sign-in (GoShippo, QuickBooks Online, Square)):

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

## Response

`200` Successful response.

Fields:

- `data` (object, required)
  - One of:
    - **The integration**: As "Get an integration" returns it. No stored credential is in it: supplier passwords, Twilio's Account SID and auth token, the GoShippo sign-in and AS Colour's API key are never returned.
      - `deprecated` (boolean, required): A retired integration: it can only be deleted.
      - `has_logs` (boolean, required): Whether it keeps a log of sync errors: true for QuickBooks Online only.
      - `id` (string, required)
      - `label` (string, required)
      - `status` (string, required): For example `ENABLED`, `ACTION_REQUIRED`, `REAUTH` (sign in to the provider again), `UNINITIALIZED` (set up but not configured yet) or `DISABLED`.
      - `subtype` (string, required): Which integration, for example `sanmar_v1`. The same value goes in the create path.
      - `trashed` (boolean, required)
      - `type` (string, required): The kind: `supplier`, `sms` (Twilio), `shipment_v1` (GoShippo), `data_sync` (QuickBooks Online, Shopify), `payment_gateway` (Square), `shipment` (retired FedEx and UPS). One of: `"supplier"`, `"sms"`, `"shipment_v1"`, `"data_sync"`, `"payment_gateway"`, `"shipment"`.
      - `data` (object | array | null, optional)
      - `integration_check_key` (string, optional): A fixed key for the kind of integration, such as `sanmar` or `shopify`.
      - `last_sync` (string (date-time) | null, optional)
      - `last_token_refresh` (string (date-time) | null, optional)
      - `option` (object | array | null, optional): The integration's settings, which differ by type.
      - `shopify_admin_app_url` (string | null, optional): Shopify only.
      - `shopify_admin_settings_apps_url` (string | null, optional): Shopify only: the store's apps settings page, where the app is uninstalled.
      - `shopify_admin_url` (string | null, optional): Shopify only: the YoPrint app in the store's Shopify admin. Same as `shopify_admin_app_url`.
      - `shopify_compliance_deletion` (object | null, optional): Shopify only: where a store data deletion requested by Shopify stands, or null.
    - **Connect link**: A YoPrint connect link that only YoPrint's web app can use. Settings > Apps posts it with the signed-in person's session; YoPrint then ties the connection to that person and browser and sends them on to the provider's sign-in, and the provider sends them back to YoPrint, which saves the connection. Opened any other way (in a browser tab, from a script, or by someone else) it shows a refusal page and connects nothing.
      - `type` (string, required): Always `"oauth"`.
      - `url` (string (uri), required): The connect link, on YoPrint's own address (`/callback/integration_connect/...`). It works once, within 2 minutes, and only from YoPrint's web app for the person whose API key asked for it.
- `status` (integer, required)
- `success` (boolean, required)

Example response:

```json
{
  "data": {
    "account_number": "123456",
    "data": [],
    "deprecated": false,
    "has_logs": false,
    "id": "d9ZxWgBz09mDFq",
    "integration_check_key": "sanmar",
    "label": "SanMar Integration",
    "last_sync": null,
    "last_token_refresh": null,
    "option": [],
    "status": "ENABLED",
    "subtype": "sanmar_v1",
    "trashed": false,
    "type": "supplier",
    "user": "YOUR_SUPPLIER_USERNAME"
  },
  "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: The subtype in the path is unknown: `error.code` `page_not_found`, `error.message` null. Fix: Use a subtype from the table.
- `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: The provider rejected the credentials: `error.code` `invalid_key` (Twilio's reason is in `error.message`). Fix: Check the credentials with the provider and try again.
  - When: The supplier could not be reached to check them: `error.code` `credential_check_unavailable`, with `error.retryable: true`. Fix: Try again later.
  - When: The team already has this integration: `unique_constraint` (Square: `unique_integration_error`). QuickBooks Online is not checked here. Fix: Update the existing one.
  - When: A credential field is missing (`validation_failed`). Fix: Send every field the table lists.
  - When: Shopify: it is installed from the Shopify admin (`shopify_install_from_shopify_required`). Fix: Open the YoPrint app in Shopify.
  - 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.

## Notes

- AI apps can connect suppliers. Twilio and the provider sign-ins are done in YoPrint.

## Related

- [List integrations](https://developer.yoprint.com/reference/integrations/v1-external-integration-index.md): `GET /v1/api/store/{team_slug}/setting/external_integration`
- [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}`
- [Disconnect an integration](https://developer.yoprint.com/reference/integrations/v1-external-integration-destroy.md): `DELETE /v1/api/store/{team_slug}/setting/external_integration/{external_integration_reference}`