> ## Documentation Index
> Fetch the complete documentation index at: https://docs.grdd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Read and manage partnerships

> List partners and requests, check a relationship, and manage partnerships for your company on the Connect API.

Use `https://data.grdd.net` with `Authorization: Bearer <ACCESS_TOKEN>`. Get a [Core-issued access token](https://docs.grdd.dev/connect-api/get-token.md) for your company. These operations act for the company in that token and require access to the partnership action you request. You cannot choose another company to act for.

In a path, `{partnershipId}` means the **other company's GNET ID**, not the request ID. For a confirmed partner, get it from `counterpartyCompanyId`. For a pending request, get it from `counterparty.companyId`. Encode the ID as one URL path segment.

## Read partnerships

Send no body on these reads. The list and detail routes accept only `fresh=true` or `fresh=false`. The default is `false`. Use `fresh=true` when you need a refreshed result. The relationship and status routes take no query parameters.

| Task | Method and path | `200` response |
| - | - | - |
| List your partners and requests | `GET /api/partnerships` | `confirmed`, `incoming`, `outgoing`, optional `access`, `counts` and `fetchedAt`. |
| Read one counterparty's details | `GET /api/partnerships/{partnershipId}` | A company summary object. This is not that company's partner list. |
| Check whether either company lists the other as a partner | `GET /api/partnerships/{partnershipId}/relationship` | `{ "partnered": true }` or `{ "partnered": false }`. Your own GNET ID returns `false`. |
| Check partnership status, pending requests and mutual partners | `GET /api/partnerships/{partnershipId}/status` | `hasPending` and `partners` booleans, and `mutual`, an array of `{ "griddid": "example-company" }` objects. Your own GNET ID returns `404`. |

```bash theme={null}
curl --fail-with-body 'https://data.grdd.net/api/partnerships' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

The Connect list returns its fields directly. It does not accept Core's `include`, `format`, `fields` or `force` query parameters.

* `confirmed` entries have `id`, `subjectCompanyId`, `counterpartyCompanyId`, `status: "confirmed"` and `counterparty`. `partneredAt` can be absent or null.
* `incoming` and `outgoing` entries have `id`, `senderCompanyId`, `recipientCompanyId`, `status: "pending"` and `counterparty`. `requestId` is optional. `requestedAt` can be absent or null.
* Each `counterparty` or `access` summary includes `companyId` and `name`. Other fields can be absent or null.
* `counts` has `confirmed`, `incoming` and `outgoing`. `fetchedAt` is a UTC timestamp.

Keep the [Core read reference](https://docs.grdd.dev/connect-api/get-partners.md) if you need a separately selected company's partner list or the old Core request or response format.

## Change a partnership

All six writes require an `Idempotency-Key` of 8 to 128 printable ASCII characters without spaces. They do not require `If-Match`. Send `Content-Type: application/json` for send and update. For the other four actions, send no body, not even `{}`.

| Task | Method and path | Request body | Completed |
| - | - | - | - |
| Send a request | `POST /api/partnerships` | `partnerid` and optional details. | `201` |
| Accept an incoming request | `POST /api/partnerships/{partnershipId}/accept` | None. | `200` |
| Reject an incoming request | `POST /api/partnerships/{partnershipId}/reject` | None. | `200` |
| Withdraw an outgoing request | `POST /api/partnerships/{partnershipId}/cancel` | None. | `200` |
| Update details for a partner | `PATCH /api/partnerships/{partnershipId}` | At least one detail. The path selects the partner. | `200` |
| End an existing partnership | `DELETE /api/partnerships/{partnershipId}` | None. | `204`, no body |

`partnerid` is the other company's GNET ID. Do not send `griddid` on either JSON write or `partnerid` in the update body. The optional details accept `null` or the values below. The body rejects unknown fields.

| Field | Accepted type and limit |
| - | - |
| `notes` | String, up to 4000 characters. |
| `fleetSize` | String, up to 20 characters. |
| `accountno` | String, up to 80 characters. |
| `contactName` | String, up to 200 characters. |
| `contactPhone` | String, up to 50 characters. |
| `contactEmail` | String, up to 250 characters. |
| `userField1`, `userField2` | String, up to 500 characters each. |
| `farmGroupId` | Integer. |
| `shareMyfleet`, `contractedFlg`, `primaryAffiliate`, `allowQuotes`, `allowFarmhouseAccess` | Boolean. |

The following example changes a partner record. Replace `PARTNER_GNET_ID` with the URL-encoded ID of a partner you intend to update. Set `WRITE_KEY` to a new key for this change.

```bash theme={null}
curl --include --fail-with-body -X PATCH \
  "https://data.grdd.net/api/partnerships/$PARTNER_GNET_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $WRITE_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"notes":"Dispatch contact confirmed"}'
```

## Write results and recovery

All six writes can return `202`. The partnership change succeeded, but follow-up work is pending. Completed `200` and `201` responses, and pending `202` responses, include `operationId`, `counterpartyCompanyId`, `status` and `effects`. `status` is `completed` or `pending`. Each effect has `name`, `status`, `retryable` and, when available, `problemCode`. A completed `204` delete has no JSON body. A pending `202` delete does have JSON.

There is no partnership operation URL to poll or resume. After a `202`, keep the operation ID for support. Read partnership state if you need to check the change. Do not retry with a new key. An exact retry with the same key can replay the recorded response, including a recorded `202`. If the first request is still running or used the same key with different data, the API can return `409 idempotency_conflict`.

| Error | What to check |
| - | - |
| `400 invalid_request` | Check path, query, JSON fields and key format. |
| `401 unauthenticated` or `403 forbidden` | Check your access token and permission for the action. |
| `404 not_found` | Check the counterparty ID and whether the requested record or relationship is available to you. |
| `409 conflict` with `reason: "self_partnership"` | Use another company's GNET ID. |
| `428 idempotency_key_required` | Send an `Idempotency-Key` with the write. |

On a timeout or an error that leaves the result unknown, check partnership state before starting a new write. See [Connect API errors](https://docs.grdd.dev/connect-api/content/api-conventions.md#errors) for the problem fields. Use the [Core write reference](https://docs.grdd.dev/connect-api/manage-partners.md) only if your integration still needs its existing wire contract.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.