> ## 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 update profiles

> Read your company profile or a visible company profile by GNET ID. Update your company's contact or profile display fields.

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. Your token selects the company for owner reads and writes. You cannot select another company for a write.

| Task | Method and path |
| - | - |
| Read your company profile and contact versions | `GET /api/profile` |
| Read a visible profile by GNET ID | `GET /api/profiles/{griddid}` |
| Update your company's account contact and address details | `PUT /api/profile/contact` |
| Update your company's profile display fields | `PATCH /api/profile` |
| Resume a pending profile or contact write | `POST /api/profile/operations/{operationId}` |

## Read a profile

Both reads accept only the `locale` query parameter: `en`, `es`, `de` or `fr`. The default is `en`. Send no body.

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

A successful read returns `200` and a profile object directly, without a `data` wrapper. On the owner read, the `ETag` header gives the profile version as `"vN"`. If the body includes a contact record, `contact.version` is a separate version number. In that record, `contact.mainEmail` and `contact.mainPhone` are the public email and phone, not the account contact fields accepted by the contact PUT.

Use `GET /api/profiles/{griddid}` when a visible profile is enough. Replace `{griddid}` with the company GNET ID and encode it as a URL path segment. This read still requires a Bearer token. The response includes `griddid`, `name`, `locale` and `resolvedLocale`. Other fields depend on what the caller may see. If the API supplies an English fallback, `resolvedLocale` can differ from `locale`. A missing or inaccessible profile can return `404 not_found`.

Use the [Core member lookup](https://docs.grdd.dev/connect-api/search.md) if you need the existing Core member fields or response. Use the [Core company content read](https://docs.grdd.dev/connect-api/content/get-company.md) if you need the combined profile, fleet, services and locations in one response. The Connect profile is neither of those records.

## Update account contact details

Send `PUT /api/profile/contact` with a flat JSON object. All fields below are optional strings and accept `null`. Send no company selector or locale.

| Request purpose | Request fields |
| - | - |
| Account contact | `mainContact`, `mainEmail`, `mainPhone` |
| Public contact | `email`, `phone`, `website` |
| Address | `address`, `city`, `state`, `zipCode`, `country` |
| Social links | `facebook`, `instagram`, `linkedin`, `twitter`, `yelp` |

Use `mainEmail` and `mainPhone` for the account contact, not `email` and `phone`. The response uses different names: `contact.mainEmail` and `contact.mainPhone` in the GET profile response, and `data.mainEmail` and `data.mainPhone` in the contact PUT response, contain the public values written with `email` and `phone`. Do not copy the GET contact fields into the PUT request's `mainEmail` or `mainPhone`. That would overwrite the account contact with the public contact and trigger the effects below. A successful account contact update does not make the PUT response's `data.mainEmail` or `data.mainPhone` show the new account values.

To update the website field from Core company edit, send `website`, not `webURL`, in this request.

Set `If-Match` from **`contact.version`** in your latest own profile response. For example, send `"v3"` for `contact.version: 3`. If there is no contact record, send `"v1"`. Do not use the profile's ETag for this write.

> [!WARNING]
>
> Every contact write also replaces your company's Farmhouse alert email and SMS recipients with the stored account `mainEmail` and `mainPhone`. A null stored value clears the corresponding alert recipient. This includes the website-only example below. When the account email changes, the write can also change your billing customer email to `mainEmail` if a billing customer exists.
>
> Keep [Core company edit](https://docs.grdd.dev/connect-api/edit-company.md) if your integration must preserve separate alert recipients or a separate billing email. Core company edit does not make these alert or billing email changes.

```bash theme={null}
curl --include --fail-with-body -X PUT 'https://data.grdd.net/api/profile/contact' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H "If-Match: $CONTACT_ETAG" \
  -H "Idempotency-Key: $CONTACT_WRITE_KEY" \
  --data '{"website":"https://example.com"}'
```

This write updates the contact record and applies the account contact and address fields to the company account. If the response is `202`, follow the [recovery steps](#write-results-and-recovery) before you rely on the account update. This write does not return the [Core company edit](https://docs.grdd.dev/connect-api/edit-company.md) response. Keep Core for integrations that need that contract or the existing cross-company edit mode.

## Update profile display fields

Send `PATCH /api/profile` with a flat JSON object. Set `If-Match` to the **profile ETag** from your latest own profile read for the intended locale. If you also updated the contact record, read your profile again after that write completes. Set `locale` in the request body to the language from your read. It defaults to `en`.

| Field | Accepted value |
| - | - |
| `name` | String, 2 to 250 characters after trimming. |
| `publicAddressMode` | `exact` or `approximate`. |
| `visibility` | `private`, `partners`, `gnet`, `unlisted`, `public` or `null`. |
| `logo` | Positive integer, nonempty string or `null`. Do not set a non-null `logo` and a non-null `logo_url` together. |
| `title`, `tagline`, `description`, `logo_url`, `foundingDate`, `mainPhone`, `mainEmail`, `mainContact`, `address`, `city`, `state`, `zipCode`, `country`, `webURL`, `lat`, `lon` | String or `null`. |

```bash theme={null}
curl --include --fail-with-body -X PATCH 'https://data.grdd.net/api/profile' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H "If-Match: $PROFILE_ETAG" \
  -H "Idempotency-Key: $PROFILE_WRITE_KEY" \
  --data '{"webURL":"https://example.com","locale":"en"}'
```

This PATCH changes the profile display fields only. It does not update the company account contact. If the website must change in both records, use `website` in the contact PUT and `webURL` in the profile PATCH. The two calls have separate versions and keys. One can succeed without the other.

## Write results and recovery

For both writes, send `Content-Type: application/json`, `If-Match` in the form `"vN"` with a positive integer, and an `Idempotency-Key` of 8 to 128 printable ASCII characters without spaces. Use a new key for each new change. Reuse a key only for an exact retry of that request.

| Result | Meaning |
| - | - |
| `200` | The response has `status: "completed"`, `operationId`, `effects` and `data`. The `data` field and ETag refer to the record you changed. For contact PUT, `data.mainEmail` and `data.mainPhone` are the public values written with `email` and `phone`, not the request's account `mainEmail` and `mainPhone`. |
| `202` | The response has `status: "pending"`, `operationId` and `effects`. If it has `data`, it also has the record's ETag. |
| `400 invalid_request` | A field or header is invalid. The JSON body does not accept unknown fields. |
| `401 unauthenticated` or `403 forbidden` | The token is missing or invalid, or the caller is not allowed to perform the write. |
| `409 idempotency_conflict` | The key was used for a different request. |
| `412 version_conflict` | Read the record again. Reapply your change with its current version and a new key. |
| `428 version_required` or `428 idempotency_key_required` | A required write header is missing. |

For a `202`, use the operation ID instead of starting the write again. Send a Bearer token for the same company and no body:

```bash theme={null}
curl --include --fail-with-body -X POST \
  "https://data.grdd.net/api/profile/operations/$OPERATION_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

The response has `operationId`, `status` and `effects`. Each effect has `name`, `status`, `retryable` and, when available, `problemCode`. The request returns `200` when complete, `202` when still pending, or `404` if the operation is missing or does not belong to your company. See [Connect API errors](https://docs.grdd.dev/connect-api/content/api-conventions.md#errors) for the problem response fields.


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