---
title: "Share a compliance export by email or text"
method: POST
path: "/compliance-exports/{compliance_export_id}/shares"
tags: ["Compliance exports"]
---

# Share a compliance export by email or text

`POST /compliance-exports/{compliance_export_id}/shares`

## Request

- Base URL: `https://api.purplegrain.com/api/v1`
- URL: `https://api.purplegrain.com/api/v1/compliance-exports/{compliance_export_id}/shares`
- Auth: HTTP bearer

Hands a ready export to someone with a link (`/s/<token>` on the web app) that offers the zip
without an account for seven days, and never past the export's own expiry.

* `email`: sends the link, the file name, the properties and dates, and an optional note.
* `sms`: sends exactly "{first name} from PurpleGrain shared a compliance export for
  {properties}: {link} (expires D/M/YY)". (Outside production the text is logged, not sent.)

Needs edit rights on every exported property (owner, admin or manager; a viewer is refused)
and only the person who made the export may share it. First-party web and mobile only,
because this sends records off the platform. The recipient is returned masked.

If the email or text fails, the share is stored as `failed` (its link then answers 404) and
the response is a **502** with `errors[0].code` `email_bounced` or `text_not_delivered`.

## Path parameters

- `compliance_export_id` string, required

## Request body

- ComplianceExportShareRequest: Who to send the link to. Flat JSON body (`application/json`). The full address or number is sent here and nowhere else.
  - `via` 'email' | 'sms', required
  - `recipient` string, required: An email address, or an Australian mobile (`0412 345 678`, `+61412345678`).
  - `message` string: An optional note, shown in the email. Ignored for a text.

## Response `201`

Shared.

- ComplianceExportShareResponse
  - `share` ComplianceExportShare, required: The recipient is always masked (`04•• ••• 318`, `j•••@farm.com.au`); the full value is never returned.
    - `id` string, required
    - `via` 'email' | 'sms', required
    - `recipient` string, required
    - `expires_at` string, date-time, required
    - `url` string, required: The link on the web app (`/s/<token>`). A credential.

## Other responses

- `400`: A bad `via` or `recipient`.
- `401`: Unauthenticated
- `403`: Not the requester, no edit rights on an exported property (a viewer), or an assistant / API key.
- `404`: No such export.
- `409`: The export is not ready, or its file has expired (`code` `export_not_ready`).
- `502`: The share was stored but the email or text did not go.

## Changes

- **2026-10-24** `e285768a8f1d`: 36 warning
  - added the new `map_boundaries` enum value to the `_meta/onboarding/completed_steps/items/` response property for the response status `400` (media type: application/json)
  - added the new `map_boundaries` enum value to the `_meta/onboarding/completed_steps/items/` response property for the response status `400` (media type: application/vnd.api+json)
  - added the new `map_boundaries` enum value to the `_meta/onboarding/completed_steps/items/` response property for the response status `403` (media type: application/json)
  - added the new `map_boundaries` enum value to the `_meta/onboarding/completed_steps/items/` response property for the response status `403` (media type: application/vnd.api+json)
  - …32 more
- **2026-10-24** `92f716edc989`: 24 info
  - added the optional property `_meta` to the response with the `400` status (media type: application/json)
  - added the optional property `_meta` to the response with the `400` status (media type: application/vnd.api+json)
  - added the optional property `_meta` to the response with the `403` status (media type: application/json)
  - added the optional property `_meta` to the response with the `403` status (media type: application/vnd.api+json)
  - …20 more
- **2026-10-20** `29c5c990d66e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/purplegrain/apis/purple-grain-api/changes/compliance-exports/:compliance_export_id/shares/post.md)

---

[API](https://skmtc.dev/purplegrain/apis/purple-grain-api.md) - [All operations](https://skmtc.dev/purplegrain/apis/purple-grain-api/llms.txt) - [OpenAPI document](https://skmtc.dev/purplegrain/apis/purple-grain-api/revisions/7c60f959fec9?raw)