Developers API reference Version 1 · generated from the code openapi.json
Routes

sharing

Share a flow

POST /api/v1/flows/{entity_id}/sharing/recipients

Give a role to addresses, sharing lists or email domains.

Each recipient gets its own result: shared, invited (the address has no account yet: the invitation is recorded, and leaves with the invitations route) or refused. A domain is only accepted when it is a verified domain of the organisation the entity belongs to. notify emails the accounts shared with.

Required scope: share

Path parameters

  • entity_id integer · required

    Id of the binder or flow.

Request body application/json

  • recipients array of RecipientIn · required

    Who to share with.

    2 fields
    • type string · required

      What recipient is: an address, a sharing list or a verified email domain of the organisation the entity belongs to.

    • recipient string · required

      An address, the name of a sharing list, or a domain

  • role string · required

    The role they all get.

  • notify boolean · optional

    Email the accounts shared with.

  • message string · optional

    A few words added to that email.

Response

200 RecipientsAdded

  • results array of RecipientResult

    One result per recipient, in the order sent.

    5 fields
    • type string

      As sent.

    • recipient string

      As sent.

    • status string

      shared: done. invited: the address has no account yet, the invitation is recorded. refused: not shared, detail says why.

    • detail string

      A sentence for a person.

    • notified boolean or null

      With notify: whether the email left.

  • sharing Sharing

    The sharing afterwards.

    4 fields
    • inherit boolean

      Whether it follows the sharing of the binder that holds it instead of rules of its own.

    • reading_access string

      Its own rule: public opens it to anyone who has its link, limited keeps it to its recipients.

    • effective_reading_access string

      The rule that really applies, inheritance included.

    • recipients array of Recipient

      Who it is shared with, pending invitations included.

      6 fields
      • id integer

        Id of the share, unique per type: what the recipient routes take as permission_id (or invitation_id).

      • type string

        user: an account. userslist: a sharing list. domain: every address of an email domain. invitation: an address that has no account yet.

      • name string

        The address, the name of the list, or the domain.

      • permission string

        What the recipient may do.

      • pending boolean

        true for an invitation not accepted yet.

      • sent boolean or null

        Invitations only: whether the invitation email left.

Errors

  • 401

    No valid credential.

  • 403

    The credential lacks the required scope, or the account may not do this.

  • 404

    Nothing with that id, or nothing the account may open.

  • 409

    The current state of the content forbids the request.

  • 422

    A value is missing or malformed.

  • 429

    Too many requests; Retry-After gives the seconds to wait.

planner_banner_ad_pt